Deep Audit

Run deterministic repository audits with clear artifacts, refactor plans, and delivery gates.

Core Modes

project: Audit the full repository and cross-cutting architecture.
section: Audit one bounded area (module, layer, package, service, or folder).
feature-trace: Audit one feature across all touched files and layers.

Use depth presets from references/mode-matrix.md.

Execution Continuity Modes

section-lock: Current section boshlanganidan keyin shu section audit + refactor + verification tugamaguncha to'xtamaslik.
full-lock: Refaktor boshlanganidan keyin butun audit scope tugamaguncha to'xtamaslik.

Default:

section mode uchun section-lock.
project va feature-trace mode uchun full-lock.

Clarification Protocol

Before auditing, build full understanding of the project intent and constraints.

Capture purpose, business flow, and critical user journeys in system-understanding.md.
If ambiguity exists, ask concise questions with options and one recommended option.
Log user answers in clarifications.md before continuing.

Use:

references/discovery-questions.md

Language Policy

If the user starts in Uzbek or asks for Uzbek, keep conversation in Uzbek.
Keep clarification questions, options, recommendations, updates, and final reports in Uzbek.
If language preference is unclear, ask one short language confirmation question before deep audit.

Required Artifacts

Create these artifacts for every audit run:

work-items/audits/<audit-id>/audit-map.md
work-items/audits/<audit-id>/system-understanding.md
work-items/audits/<audit-id>/clarifications.md
work-items/audits/<audit-id>/implementation-plan.md
work-items/audits/<audit-id>/tasks.md
work-items/audits/<audit-id>/roadmap.md
work-items/audits/<audit-id>/sections/<nn>-<section-slug>/{section-audit.md,implementation-plan.md,tasks.md,roadmap.md}

Create them quickly with:

node agent/deep-audit/scripts/init_dynamic_audit.js --mode <project|section|feature-trace> --depth <deep|medium|low> --scope "<target>"

Create each section package with:

node agent/deep-audit/scripts/init_section_audit.js --audit-root "work-items/audits/<audit-id>" --section "<section-name>" --order <nn>

Template and checklist details:

references/templates.md
references/quality-gates.md
references/phase-protocol.md

Execution Workflow

1. Discover System Essence First

Parse mode, depth, continuity, and scope.
Model project essence: domain goals, core flows, non-functional constraints, and risk appetite.
If scope is unclear, ask user clarifying questions with options and explicit recommendation.
Normalize an audit-id: <mode>-<depth>-<scope-slug>-<stamp>.
Record assumptions, continuity mode, and excluded areas in audit-map.md.

2. Run Phase 0 Gate

Run quality checks before deep audit:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-0-baseline"

If checks fail, stop and log blocker in clarifications.md.

3. Build Audit Map First

Inventory repository sections before deep inspection.
Group files into sections by architecture boundary, not by random folders.
For each section, add:

purpose
key files
dependencies in and out
risk label (critical, high, medium, low)

Run phase gate:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-1-map"

4. Run Section-by-Section Audit in Phases

Create one section package per section inside sections/.
Process each section in phases (intent -> dependency graph -> findings -> fixes -> confidence).
Keep evidence file-level (path:line) and severity-tagged.
Run phase gate after each section:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-2-section-<name>"

If section-lock is active, do not pause until section is verification-complete.

5. Maintain Audit-Level Work Item Pack

Keep audit-level files in work-items/audits/<audit-id>/.
Fill:

implementation-plan.md with phased refactor strategy.
tasks.md with trackable checklist and owners.
roadmap.md with sequencing and dependencies.

Link audit-level tasks to section-level findings and section-level plans.
Run phase gate:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-3-planning"

If full-lock is active, continue directly into implementation until full scope closes.

6. Implement Refactor

Execute tasks in dependency order.
Keep commits scoped and reversible.
Update tasks.md status after each completed change.
Run phase gate after each implementation batch:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-4-implementation"

7. Verify and Close

Run test and quality commands relevant to changed areas.
Perform regression checks for impacted flows.
Mark unresolved items as explicit follow-up work, never silent omission.
Run final gate:

node agent/deep-audit/scripts/run_phase_checks.js --phase "phase-5-final"

8. Commit and Push Gate

Ensure all required checks in references/quality-gates.md pass.
Commit with a conventional message aligned to audit scope.
Push only after gates pass, branch policy allows it, and explicit user confirmation exists.

Mode Routing Rules

Route to project when request says full system, full repo, or complete architecture audit.
Route to section when request targets one module, package, folder, or bounded context.
Route to feature-trace when request targets one feature behavior across multiple layers.
If user gives no depth, default to medium.

Non-Negotiable Rules

Never start refactor before audit-map.md exists.
Never report findings without file-level evidence.
Never mark audit complete without section phase reports and section-level task/plan/roadmap files.
Never skip phase gate checks (typecheck, build, lint) without recording blocker and user decision.
Never stop in section-lock before current section is verification-complete.
Never stop in full-lock before full scope is verification-complete.
Never push changes if verification fails.
Log known risks in roadmap follow-ups.

Output Contract

Return results in order: Mode/Scope -> Clarification -> Map -> Section Findings -> Work Items -> Refactor -> Verification -> Continuity Status -> Git Status.

deep-audit