/audit internals

Rules and commands bound to /audit's own tooling. Loaded when a file under audit/ is read. Cross-cutting rules that also apply here (orchestrator writes/subagents return, fresh-shell-per-Bash-block, marker hashing, model:inherit, hook scope) live in the root CLAUDE.md.

Architecture

/audit is a PR review before push (rebuilt 2026-10-03, replaces the per-dimension Workflow pipeline). Flow: deterministic pre-checks, then the built-in /code-review high in a review worktree (plus one code-reviewer checklist agent when orch_sensitive_paths returns paths), triage by the orchestrator, one spec-executor fix round, one test run, log, push marker. audit/SKILL.md stays under ~150 lines.

Why (evidence, 2026-10-02/03):

• The old pipeline used about 45% of the weekly usage limit in 7 days (single runs 8-78 M weighted tokens).
• A benchmark on 5 historical diffs with 6 known Criticals: built-in /code-review high found all 3 security Criticals and 1 of 2 architecture ones, plus 2 serious issues the pipeline missed, at ~0.1-1.7 M per run.
• It missed one privacy Critical (third-party map tiles without consent) and one policy bypass; references/sensitive-checklist.md covers those two.

Other decisions:

• No verifier agents, no backlog file, no start question, no dimension selection. Triage is the orchestrator's job.
• Marker only when pre-checks are clean, every dispatched review completed, no Critical/Important is open and tests are green. orch_marker_write keeps its argument semantics: selected = reviews run, incomplete = failed reviews plus open findings.
• A DIFF_CLASS=prose diff runs the deterministic checks only (references/prose-gate.md).
• Platform: detect-framework.sh emits PLATFORM=web|native|cross; /screens uses it. check-i18n-keys.sh handles .lproj and values-*/strings.xml.

Commands

. audit/bin/lib-orchestrator.sh functions: orch_resolve_audit_root, orch_helper, the two cwd-hash families orch_hash_passed/orch_hash_progress, orch_progress_claim/touch/release, orch_state_save/orch_state_load/orch_state_clear, orch_tree_hash, orch_marker_write/orch_marker_matches/orch_marker_delta, orch_url_host/orch_host_public, orch_run_log, orch_ship_value, orch_test_command_declared, orch_test_command, orch_unaudited_record/orch_unaudited_base/orch_unaudited_clear, orch_sensitive_paths, orch_review_worktree_create/orch_review_worktree_remove, orch_usage_start/orch_usage_report. orch_progress_claim clears state so a run starts empty.

Every test is a single script; there is no wrapper that runs all of them.

Audit Context (auditing this repo itself)

• Markdown + Bash skills repo, no runtime, no dependencies. Findings about missing package manifests, test frameworks, or CI configs for the skills themselves are noise.
• Public repo on GitHub. Secrets/keys/tokens anywhere in the diff are always Critical. There are no per-run audit logs; suppressions.json under .claude/audits/ may be committed, so its entries never contain secrets or file content.
• audit/bin/*.sh and every hook must stay bash 3.2 compatible (macOS default): no declare -A, no readarray, no ${var,,}.
• German-named contract identifiers (ALLE_DATEIEN, ...) are deliberate cross-file contracts, NOT English-migration violations.
• Deliberate decision: orchestrator writes, subagents return (subagents cannot write under .claude/); exit 2 blocking in the audit Stop hook is intentional, additionalContext would not block.

Gotchas

• Every Bash block in a SKILL.md is a fresh shell; nothing sourced or assigned survives into the next block. Every block that calls an orch_ function starts with the one-line source loop from the lib header, and every value a later block needs is saved with orch_state_save and re-read with orch_state_load. Enforced by check-fresh-shell.sh.
• Marker hash families. /tmp/claude-audit-passed-* hashes the cwd WITHOUT trailing newline, /tmp/claude-audit-in-progress-* WITH newline (pre-compact.sh recomputes the latter). Never mix them (root CLAUDE.md).
• Push guard: every push needs a fresh marker. hooks/block-unsafe-push.sh asks for any git push without a marker younger than 30 minutes, whatever the branch name; pinned by hooks/block-unsafe-push.test.sh.
• Pre-push marker and git push must be separate Bash calls. The PreToolUse hook scans the command string for git push and blocks before a marker write in the same call would execute.
• Review worktree helpers by name only. hooks/block-worktree-wide-git.sh denies the forced worktree-remove git command whenever it appears in a Bash call (it also blocks a heredoc that merely contains it); use orch_review_worktree_create/orch_review_worktree_remove.
• The prose gate is the audit's stopping rule. Fixing what an audit finds in prose creates the next diff that deserves an audit, a loop with no exit (2026-08-05). classify-diff.sh emits DIFF_CLASS; a prose diff runs the deterministic checks only. references/prose-gate.md.
• The finding-line format of the chat report is a contract. - [Severity][source] file:line: description on ONE physical line (SKILL.md Phase 5, "Report format"); humans grep it.
• "Which files are frontend?" has one definition, FRONTEND_EXT_RE in lib-git-base.sh. collect-scope.sh reads it with an inline literal fallback so a missing lib does not collapse to "nothing is frontend".
• SOURCE_DIRS from detect-framework.sh is quoted per element, not as a whole string. Each directory is individually %q-quoted, joined by plain spaces. Capture stdout as text, extract the value after SOURCE_DIRS=, rebuild the array with eval "SOURCE_DIRS_ARR=($SOURCE_DIRS)"; never one blanket eval "$(...)" over the three lines. The safety against attacker-controlled directory names comes entirely from the per-element printf %q. A directory name with a literal newline cannot round-trip.
• TEST_COMMAND is a repo-supplied command string (.claude/ship.md test-command:, else the manifest's own). Every test run, also a hand-assembled xcodebuild test, goes through test-lock.sh; two concurrent runs on one simulator kill each other ("Early unexpected exit, operation never finished bootstrapping"). Full-suite runs use --cached (cache, admission, stall watchdog; lib-testrun.sh header documents state, env and layers). test-status shows what runs; the xcodebuild shim (skills-personal/bin/shims/xcodebuild) admits xcode runs (2 at once, -jobs 6/3).
• mutate.sh reports SKIP no-mutations in a worktree whose vendor/ is a symlink to the main project. Pest then resolves the class to the main project's file and prints No mutations created; nothing was tested. Run the mutation step from the main checkout, or give the worktree its own vendor/. A runner that dies without a summary (e.g. a Browser test needing Playwright) is ERROR, never OK; Browser/ test directories are excluded from discovery. Both routes (--class for classes, --path for an enum) need the worktree's own vendor/.
• laravel/pao rewrites Pest's output as ONE json line inside an agent session (AI_AGENT, CLAUDECODE), so the score parser read the second word of Mutating application files... (MUTATE_SCORE=<file>:application, 2026-10-09). mutate.sh sets PAO_DISABLE=1 on the Pest call and parse_pest also unwraps the json raw array; pinned by pest-mutate-service-pao.log.