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 .

References

• Mode Matrix

• Audit Templates

• Quality Gates

• Discovery Questions

• Phase Protocol