howells/arc/audit

<tool_restrictions> EnterPlanMode and ExitPlanMode are banned. This skill is Arc's own structured process. </tool_restrictions>

<arc_runtime> Requires the full Arc bundle. Arc-owned paths (agents/, references/, disciplines/, templates/, scripts/, rules/, skills/) resolve from the plugin root — the directory containing agents/ and skills/. Everything else is the user's repository. </arc_runtime>

<platform_context> Adapt to the current harness rather than assuming Claude tool names — task tracking, structured questions, and subagent delegation each degrade gracefully when absent. Load references/platform-tools.md when a mapping isn't obvious.

Where native task tracking exists, check for an existing task for this audit and mark it in_progress before starting. </platform_context>

<required_reading> Load each at the phase that needs it, not up front:

Load when relevant:

• references/react-audit-signals.md — React, Next.js, TanStack Query, or React Native projects. Pass the relevant sections into reviewer prompts as audit signals.
• references/index.md — the full reference catalogue, when a finding needs background you can't name a file for.

</required_reading>

<rules_context> Project coding rules come from .ruler/ when it exists, otherwise Arc's own rules/.

references/audit-reviewer-rules.md lists which rules each reviewer receives and the frontend implementation checks for daniel-product-engineer and accessibility-engineer. Load it before composing reviewer prompts.

These inform implementation and accessibility checks only. Do not score visual taste, invent a visual direction, or create redesign findings; defer visual direction to the project's design source of truth. </rules_context>

<process>

Phase 1: Detect Scope & Project Type

Parse arguments:

• $ARGUMENTS may contain:
• A path (e.g., apps/web, packages/ui, src/)
• A plain-language focus (e.g., "security", "performance", "architecture", "accessibility")

Do not advertise audit flags or variants. If the user provides a path or focus, treat it as scope guidance for the same default audit workflow.

Gardening modes (lightweight, run periodically):

The harness that earns trust decays: docs drift from code, rules go stale. When the focus is "doc gardening" or "rule gardening", skip reviewer dispatch and run the matching cheap pass instead. These are cheap enough to run on a cadence, not only when something is wrong.

• Doc gardening — walk the project's documentation (README, docs/, AGENTS.md, CONTEXT.md, package docs) and, for each claim, check it against the code. Fix what is clearly stale (wrong paths, renamed commands, dead links); flag what needs a human decision.
• Rule gardening — check that the project's written rules (.ruler/ or rules/) are still followed. For each violation, ask whether it is intentional before flagging. Flag dead rules for deletion: never triggered, no longer relevant, or already enforced mechanically elsewhere (linter, boundaries, CI).

If no scope provided:

Use Glob tool to detect structure:

• apps/*, packages/* → monorepo (audit both)
• src/* → standard (audit src/)
• Neither → audit current directory

Detect project type with Glob + Grep:

Check for database/migrations:

Use Glob tool: prisma/*, drizzle/*, migrations/* → has-db

Collect the Phase 1 signal manifests using references/audit-signals.md — React/Next signals, dependency vulnerabilities, dead code (knip), structural hotspots, page shape, code policy, fail-fast determinism, complexity hotspots, and the read-only codebase map from scripts/codebase-map.py. Run only the scans that apply to the detected project type, and carry each stored manifest forward into reviewer context.

Treat every manifest as orientation, not evidence. Reviewers still inspect files before reporting.

Detect project scale, lifecycle stage, and the security gate:

Load references/audit-detection.md and apply it — file-count thresholds that set reviewer depth, the lifecycle-stage signal table, and the security readiness gate that decides whether security-engineer runs at all. Confirm the detected stage with the user before proceeding; if they correct it, use their override. With no user response available, proceed with the detected stage and mark it unconfirmed in the report header — stage drives every severity rating.

Summarize detection:

Scope: [path or "full codebase"]
Project type: [Next.js / React / Python / etc.]
Project scale: [small / medium / large]
Project stage: [prototype / development / pre-launch / production]
Security gate: [full reviewer / lightweight only] ([reason])
Has database: [yes/no]
Has tests: [yes/no]
Dead code: [X unused files, Y unused exports, Z unused deps] or "N/A (not JS/TS)"
Structural hotspots: [X long files 600+ LOC, Y severe 1000+ LOC, Z at 2000+ LOC, V suspicious boundary files, W suspicious+long overlap]
Page shape: [X thin page/layout pass-throughs, Y to god clients 600+ LOC, Z to god clients 1000+ LOC] or "N/A (not React/Next)"
Code policy: [X useless barrels, env-typing: yes/no, Y dynamic imports, Z generic-suffix components] or "N/A (not JS/TS)"
Determinism: [X env-default fallbacks, Y swallowed catches, Z legacy/compat aliases] or "N/A (not JS/TS)"
Pipeline coverage: [X/Y workspaces with lint+typecheck configured]
Complexity signals: [X repeated scans, Y sorting/grouping, Z data-access/render-path candidates] or "N/A"
React audit signals: [X state/effect, Y boundary, Z data-client, W security/frontend/perf hotspots] or "N/A (not React)"
Codebase map: [available / unavailable]
Coding rules: [yes/no]
Focus: [all / security / performance / architecture / accessibility / user-provided focus]

Phase 1.5: Mechanical Checks

Run these before any reviewer agents so obvious breakage gets caught cheaply.

Tooling Detection

• Detect package manager from lockfiles
• Detect build command from package.json
• Detect typechecker from tsconfig.json
• Detect linter from Biome / ESLint config
• Detect tests from Vitest / Jest config

Pipeline Coverage (every app & package)

Linting and typechecking must be configured in every app and package — not just at the repo root. A monorepo where the root has lint/typecheck scripts but individual apps/* / packages/* do not is a real gap: those workspaces ship unchecked.

For the root and every workspace with a package.json:

# Enumerate workspaces and check for lint + typecheck wiring
for pkg in $(find . apps packages -maxdepth 3 -name package.json 2>/dev/null | grep -vE 'node_modules'); do
  dir=$(dirname "$pkg")
  grep -qE '"lint"\s*:' "$pkg" && lint=yes || lint=no
  grep -qE '"(typecheck|type-check|tsc)"\s*:' "$pkg" && tc=yes || tc=no
  test -f "$dir/tsconfig.json" && tsc=yes || tsc=no
  echo "$dir  lint=$lint  typecheck=$tc  tsconfig=$tsc"
done

Flag any app/package missing a lint script, a typecheck script, or (for TS workspaces) a tsconfig.json. Then confirm these actually run in CI (.github/workflows/*, or the Turborepo turbo.json pipeline) — a script that exists but is never executed in CI is a soft gap. Record per-workspace coverage in the mechanical summary and map gaps to Operations (see the Operations cap rule in the scorecard).

Check Order

1. Build — stop immediately if it fails
2. Typecheck — report errors and continue
3. Lint — auto-fix first, then report remaining issues
4. Tests — run when test tooling is detected
5. Debug log audit
6. Git status
7. Secrets scan — run when a suitable scanner or safe grep fallback is available
8. React scanner — optional, React projects only; see below

Include the mechanical summary in reviewer context, then continue to reviewer selection.

Optional React Scanner (react-doctor)

For React/Next.js/React Native projects, react-doctor provides a deterministic scan across state/effects, performance, architecture, security, and accessibility — the mechanized counterpart of references/react-audit-signals.md. It is an optional enhancement, never a dependency: the audit must produce the same scorecard without it.

• Availability: use it when it is already wired into the project (a dependency, doctor.config.ts, or a react-doctor CI workflow). Otherwise offer it with one question — running npx react-doctor@latest downloads and executes third-party code and reports telemetry, so never start that silently. Skip without comment if declined or offline.
• Run: npx react-doctor@latest --no-telemetry at the project root (omit --no-telemetry if the project's own config opts in).
• Findings are leads, not proof: attach the scanner output to the mechanical summary and reviewer context. Reviewers confirm each lead against the code path before it becomes a finding, and skip re-deriving mechanical patterns the scanner already covers — their attention belongs on what static analysis cannot see (cross-file semantics, architecture, product intent).
• Scoring: scanner output alone never moves a scorecard axis; only reviewer-confirmed findings do.

External-Surface Checks

When the project exposes an agent-facing surface or ships published bundles, add these one-line checks to the mechanical summary:

• Is the agent-facing surface (API / MCP / llms.txt) current with shipped behavior?
• Have published component bundles been verified post-build (the built artifact, not just source)?

Phase 2: Select Reviewers

Apply security readiness gate first:

• If the gate says full reviewer, include security-engineer.
• If the gate says lightweight only, do not include security-engineer; carry forward the mechanical secrets/dependency scan summary and any concrete dangerous findings.
• If a concrete dangerous finding appears after reviewer selection, add security-engineer back before Phase 3.

Base reviewer selection by project scale: