audit_project

Returns the multi-phase PROJECT AUDIT PLAYBOOK (instructions for the agent).

Strict mode is the default. Strict means EXHAUSTIVE — the agent does not stop until every finding is resolved, framework_bug (in framework_audit_results.md), or an active 🟢 ASK USER block awaiting user input. No finding stays open.

Two CLI flags (default ON in strict mode, both opt-out via --no-...):

• --deep-fix: agent does NOT stop at first blocker (missing project key, auth-protected route, missing CLI subcommand). Surfaces ASK-USER blocks or runs documented fallbacks (e.g. publish blocked → local frank+brender preview).

• --deep-framework-audit: every framework_bug entry includes a Read+Grep trace into smbls/ source identifying the suspected function, plus a suggested patch.

Two report files the CLI emits + the agent appends to:

• audit/symbols_audit_results.md — PROJECT findings + resolutions

• audit/framework_audit_results.md — FRAMEWORK bugs + repro + smbls/ trace + suggested patch (each entry must be debuggable by someone who's never seen the code; vague "doesn't work" entries are not acceptable in strict mode)

Findings have an origin field (project | framework | shared) classified by bin/symbols-audit heuristically, then refined by the agent during Phase 2.

This tool is a playbook getter, not an executor. The agent runs the playbook itself using:

• get_project_context — call FIRST to resolve owner/key/env. Missing values surface as 🟢 ASK USER blocks (NEVER hardcoded).

• bin/symbols-audit <symbols-dir> — deterministic regex sweep + dual-report template emission. Strict + deep modes default ON.

• audit_component(code) — inline single-component validator (no filesystem).

• chrome-mcp tools — for the Phase 3c local-vs-remote UI testing protocol.

Phase summary:

• Phase 0: setup + baseline metrics + project-context resolution. Missing owner/key resolved here via ASK-USER (not deferred).

• Phase 1: static audit via bin/symbols-audit (creates findings.json + symbols_audit_results.md + framework_audit_results.md templates).

• Phase 2: fix loop with self-test. 3 failed fix attempts → finding becomes framework_bug with deep-audit trace. Continue, never stop on first bug.

• Phase 3a: build gates with fallbacks for missing CLI subcommands.

• Phase 3b: publish to staging WITH FALLBACK LADDER. If publish is blocked (missing key, AUTH_REQUIRED, env doesn't exist), agent surfaces ASK-USER AND/OR falls back to local frank to-json + brender + http.server preview so Phase 3c still has a viewable artifact. NEVER silently skip publish.

• Phase 3c: STRICT UI testing — local-vs-(remote OR localfallback) side-by-side, click every clickable, icon rendering verification per Rule 62, theme/lang/ active-nav/forms/responsive.

• Phase 4: iterate until two consecutive runs converge — zero open findings, zero pending ASK-USER, viewable artifact exists. Deep-fix loop re-visits framework_bug entries to strengthen them and retries blockers.

• Phase 5: report = record of resolutions, NOT a TODO list. Strict mode forbids "Recommended follow-up tasks" as a terminal state.

Transport awareness: this playbook assumes stdio MCP transport (filesystem access). For SSE/HTTPS/CDN, the agent surfaces filesystem-dependent steps as shell commands the user runs locally, then resumes Phase 2/3 with pasted output. audit_component and audit_project are stateless and work over any transport; get_project_context and bin/symbols-audit are stdio-only.

Output artifacts created in /audit/: findings.json, symbols_audit_results.md (framework bugs), runs/, report.md.

Use this when the user asks to audit, validate, refactor for compliance, or 'make my project publish-ready in one shot'. Returns the entire playbook so the agent has the full context. Pair with the bundled bin/symbols-audit CLI for the deterministic regex pass.

Args: phase: 'all' (full playbook — default) | '0' | '1' | '2' | '3' | '4' | '5' (just one phase's section)