create-ccc-tutor 0.1.0

package/template/.harness/docs/tool-map.md

@@ -0,0 +1,120 @@
+# Tool map — detail
+
+> **Reference for `CLAUDE.md § Tool map`.** Loaded on demand when AI needs per-skill purpose, full subagent role inventory, hook trigger conditions, or memory mechanism details. The compact list in CLAUDE.md is the load-bearing index; this file is the elaboration.
+
+## Bootstrap (not a skill; see top of CLAUDE.md)
+
+Before any skill runs, the Bootstrap Status Check at the top of CLAUDE.md decides whether harness is configured. If not:
+- **CCC mode**: CCC's bundled Step 1 driver runs (detects existing harness + 3-option menu + git clone)
+- **Standalone mode**: `.harness/scripts/standalone-bootstrap.md` runs (same logic minus git clone, since user already cloned manually)
+
+Both bootstrap paths converge on invoking `/init` to fill project-specific values.
+
+## Slash commands & skills (`.harness/skills/`)
+
+Each skill lives at `.harness/skills/<name>/SKILL.md`. Skills with a `description` are auto-discoverable and create the `/<name>` invocation.
+
+Skills are invokable two ways:
+
+- **Slash syntax**: `/<skill-name> <args>` (e.g., `/remember 这事很重要`). Forwarded via `.claude/commands/` shims to the actual skill at `.harness/skills/<name>/SKILL.md`.
+- **Natural language**: phrases listed in each skill's `description` field will trigger the same skill (e.g., "记一下: 这事很重要" triggers /remember). See individual SKILL.md `description` for accepted phrases.
+
+### Per-skill detail
+
+- `/init` — **Step 2** of harness setup: fills L0/L1 slots interactively, writes `.harness/state/install.json` as the canonical "configured" marker. Re-runnable for re-configuration with `--force`. Does NOT run detection — bootstrap handles that before /init is invoked.
+- `/next` — workflow state inspector: detects current feature progress and suggests next command. Doesn't auto-invoke; pure wayfinder. Use when unsure which skill to run.
+- `/pickup` — session resume: reads `.harness/state/workflow-checkpoints/<feature>.json` and restores stage / artifact / progress state. Auto-surfaced at SessionStart if a checkpoint matches the current git branch. Use after multi-day breaks, cross-device work, or context-compaction loss.
+- `/abandon` — mark a feature dead: moves checkpoint to `_archived/`, logs reason to decision-log. Does NOT touch git or source code (CEO's job). Use when CEO rejects a feature post-spec or when cleaning dormant features from `/pickup --list`.
+- `/uninstall` — cleanly remove CCC-MAGI from the project. Detects whether a prior harness archive exists (`old_version_harness/` from bootstrap option 1); if so, offers to restore it. Preserves source code, `docs/features/*.md` specs, git history. Constitutional basis: § 3 (CEO Final Authority).
+- `/feature-draft <name>` — stage 1, **new-feature mode**
+- `/audit-spec <name>` — stage 1, **audit mode**
+- `/spec-finalize <name>` — stage 2
+- `/db-schema <name>` — stage 3 (skip if no backend)
+- `/execution-plan <name>` — stage 4
+- `/implement <name>` — stage 5
+- `/test-fix` — stage 6 (skip if `test_required = false`)
+- `/commit` — stage 8
+- `/constitution-edit` — edit Section 2 / Section 3 / slot registry of constitution.md. Cannot modify Section 1 (Universal Core — harness-guaranteed invariants). Generates a versioned Sync Impact Report at the top of constitution.md (Spec-Kit-pattern audit trail).
+- `/add-constitution-clause` — append to Section 3 of constitution (new project-specific red line)
+- `/add-anti-flag` — grow the L2 anti-flag rules over time (in AGENTS.md)
+- `/remember` — user-curated entry into Tier 2 memory (and Tier 1 shared `decisions.jsonl` for high-signal calls)
+- `/recall <id|feature|tag>` / `/recall --deep <query>` — JIT body fetch from memory tiers
+- `/handoff` — user-invoked at 95% context. Generates a rich 5-slot snapshot entry into Tier 2.
+- `/offload <task>` — spawn fresh-context subagent for a sub-task at ~75% budget.
+
+## Constitution versioning
+
+`constitution.md` follows semver. Edits via `/constitution-edit` prepend a Sync Impact Report HTML comment at the top of the file documenting:
+- Version bump (MAJOR / MINOR / PATCH)
+- What changed in which section
+- Downstream templates that may need review
+
+Ad-hoc edits (raw `vim constitution.md`) skip the report. Use `/constitution-edit` for material changes — the audit trail is worth it.
+
+Semver rules:
+- **MAJOR** — removes / substantively changes an existing principle or slot
+- **MINOR** — adds a new principle or slot
+- **PATCH** — typo / clarification / non-semantic rewording
+
+Section 1 (Universal Core) is harness-guaranteed and cannot be modified by `/constitution-edit`.
+
+## Subagents (`.harness/agents/`)
+
+Subagents enforce **mechanical rules only** — they do not exercise judgment, propose new patterns, or evaluate business logic. Judgment is MAGI Verdict's job; pattern proposals belong to MAGI Core; intent decisions are CEO's. A subagent finding always cites the rule source (a `CLAUDE.md` or rule file); if it can't, that's not a finding to report.
+
+**Core MAGI positions (built-in):**
+- **MAGI Planner** — Stage 1 + 4. Played by MAGI Core: turns CEO intent into a plain-language spec, then a per-file execution plan.
+- **MAGI Programmer** — Stage 5. Played by MAGI Core: implements per the plan.
+- **MAGI Tester** — Stage 6. Played by `test-fixer` subagent (fresh context, so it doesn't inherit Programmer's rationalizations).
+- **MAGI Verdict** — Stages 2-6 + commit gate. Cross-model judgment auditor (default `{{auditor_model}}`). Single-engine fallback (fresh-context same-model) when no second model available.
+- **MAGI Archivist** — Hook-triggered (SessionStart / PreCompaction). Memory layer service.
+
+**MAGI Reviewer plugins** (`{{junior_reviewers}}` — user picks at /init):
+<!-- ⟦L1⟧ Filled per project. Examples shipped: frontend-reviewer,
+     backend-reviewer, security-reviewer, infra-reviewer. User selects
+     which plugins to enable based on tech stack. -->
+
+**Test programmer:**
+- `test-fixer` — junior **programmer** (not reviewer): writes/edits test code from a fresh context. Spawned by `/test-fix`; does not exercise judgment about whether the test is right — that's the auditor's job in the post-fix audit.
+
+## Hooks (`.harness/settings.json`)
+
+Hooks are deterministic checks that run automatically.
+
+- **Pre-commit typecheck** — blocks commit if static type/syntax check fails. Script: `scripts/precommit-typecheck.sh`.
+- **Pre-commit lint bans** — blocks commit if anti-flag patterns are found. Script: `scripts/lint-bans.sh`.
+- **Pre-commit cycles** — blocks commit if a dependency cycle is detected (enabled only if `dependency_flow` is non-empty). Script: `scripts/precommit-cycles.sh`.
+- **Post-edit format** — runs the project's formatter on edited files. Script: `scripts/format-edit.sh`.
+- **Budget pressure monitor** — `.harness/scripts/budget-monitor.sh` (UserPromptSubmit). Monitors transcript token usage (parses Anthropic `usage` field). **Auto-detects context budget from model** (v0.10.3+): `[1m]` suffix → 1M, standard `claude-*` → 200K, `gpt-4*` → 128K, others → 200K safe default. Override with `CCC_CONTEXT_BUDGET` env var. Emits `additionalContext` at 50% / 75% / 90% / 95% with detected model shown in each message; 95% surfaces a `/compact` / `/handoff` / continue menu. Advisory-only; can't force model switch (Claude Code doesn't expose runtime model switching to hooks). Silent under 50%.
+
+> **Install-time registry**: `.harness/state/shipped-hashes.json` records SHA-256 of every file the installer shipped, so re-installs can content-hash-detect "user-modified" vs "unmodified" files and safely deliver harness updates without clobbering local changes.
+
+## Memory layer (`.harness/memory/` + `.harness/state/scratchpad.md`) — v2 3-tier
+
+> Full architectural rationale: `docs-harness/context-architecture-v2.md`.
+
+Cross-session persistence in 3 tiers (Letta pattern):
+
+| Tier | Location | Purpose | In-context at SessionStart? |
+|---|---|---|---|
+| **1 — Working** | `.harness/state/scratchpad.md` | Current objective + last/next step + blockers; rewritten every turn (Stop hook) | ✅ Always (~500 tokens) |
+| **2 — Recall** | `.harness/memory/sessions/recall/*.jsonl` (`observations` + `snapshots`) | Last 30 days of decisions/failures/snapshots | ✅ Manifest only (~500-1000 tokens), bodies on demand |
+| **3 — Archive** | `.harness/memory/sessions/archive/<YYYY-MM>.jsonl` | Older entries, cold storage | ❌ Never — only via `/recall --deep <query>` |
+
+Shared (team, committed): `conventions.md` (long-form rules) + `decisions.jsonl` (`/remember` writes here).
+
+Mechanisms:
+
+- **`memory-archive.sh`** (SessionStart) — migrates Tier 2 entries >30 days into Tier 3. Back-fills `id` on legacy entries. Idempotent.
+- **`memory-recall.sh`** (SessionStart) — emits a **manifest** of one-line index entries from Tier 2 (`[<id>] feature=<f> kind=<k> date=<YYYY-MM-DD> focus="<≤80 chars>"`). **Does NOT load entry bodies** — that requires `/recall <id>`.
+- **`scratchpad-recall.sh`** (SessionStart) — reads `scratchpad.md`, injects as additionalContext.
+- **`scratchpad-update.sh`** (Stop hook) — instructs AI to rewrite scratchpad at end of each turn.
+- **`memory-snapshot.sh`** (PreCompaction) — deterministically harvests scratchpad + checkpoint + git status into a snapshot entry. **No LLM call** (was v1; now deprecated).
+- **`/remember`** — user-curated entry into Tier 2 (and Tier 1 shared `decisions.jsonl` for high-signal calls).
+- **`/handoff`** — user-invoked at 95% context. Generates a rich 5-slot snapshot entry into Tier 2.
+- **`/recall <id|feature|tag>`** / **`/recall --deep <query>`** — JIT body fetch.
+
+Token economics (v2):
+- SessionStart cost: ~1-1.5K tokens regardless of project age (Tier 1 + Tier 2 manifest, bounded). v1's eager-injection often hit 2-5K.
+- Per fetch: ~1-2K tokens (body load). Hard cap: ≤3 recall + ≤1 archive search per session.
+- Net: same-or-cheaper than v1 in common cases; only more expensive in extreme-history-mining sessions, where the cost is justified.

package/template/.harness/docs/workflow.md

@@ -0,0 +1,59 @@
+# Workflow detail
+
+> **Reference for `CLAUDE.md § Workflow`.** Loaded on demand when AI needs full stage internals, mode-vs-lane distinction, or cross-model audit operationalization. The compact summary in CLAUDE.md is the load-bearing version; this file is the elaboration.
+
+## Two sides, three lanes (full picture)
+
+The **CEO (you, human)** sets intent. The **MAGI System** (the AI team) implements + reviews — see `AGENTS.md § MAGI System` for the 7 positions. Concretely:
+
+- **MAGI Core** (your primary CLI, e.g. Claude Code) — orchestrator + workflow manager. Talks to you. Spawns subagents.
+- **MAGI Verdict** (default `{{auditor_model}}`, e.g. Codex) — cross-model auditor. **Judgment authority. Not under MAGI Core's chain of command** — independent reviewer per Universal Core.
+- **MAGI Planner / Programmer / Tester** — played by MAGI Core during the matching stage (mode switch, not separate processes).
+- **MAGI Reviewer** — `{{junior_reviewers}}` rule-enforcement plugins (backend / frontend / security). Mechanical. Cite rule source; never invent.
+- **MAGI Archivist** — `memory-recall.sh` / `memory-snapshot.sh` hook services.
+
+Judgment is MAGI Verdict's; rule enforcement is MAGI Reviewer's; orchestration is MAGI Core's; intent is yours.
+
+## Two modes (Stage 1 branches)
+
+The workflow runs in two **modes** that share Stages 2–9. Stage 1 differs by mode:
+
+- **New-feature mode** — for shipping new features. Stage 1 paraphrases CEO intent, runs an 8-category edge-case round, then writes a plain-language spec.
+- **Audit mode** — for verifying existing features. Stage 1 runs the same intent rounds, then a fresh general-purpose subagent scans the codebase for an as-built read; the auditor independently reviews; CEO decides each delta; output is the same two-file model.
+
+Stage-specific tools are in `.harness/` — see `CLAUDE.md § Tool map`.
+
+## Full 9-stage description
+
+1. **Draft / as-built spec** — `/feature-draft <name>` (new-feature mode) **or** `/audit-spec <name>` (audit mode, fresh-context subagent + auditor review)
+2. **Finalize spec** — `/spec-finalize <name>` (auditor final cross-check)
+3. **Design schema** (when data model changes; **skip if project has no backend**) — `/db-schema <name>`
+4. **Write execution plan** — `/execution-plan <name>` (per-file checklist + auditor judgment audit)
+5. **Implement per plan** — `/implement <name>` (mechanical reviewer chain + auditor judgment)
+6. **Auto tests** — `/test-fix` (test-fixer subagent + auditor audit). **Skipped if `test_required = false`.**
+7. **User smoke test** — CEO runs the application manually against the spec's smoke-test procedures (`{{spec_dir}}<name>.md` only — implementation file not consulted). *Mandated by Constitution § 4.*
+8. **Commit & push** — `/commit` using Conventional Commits, with affected scenario IDs in the message body. Plan file is deleted in this commit. Pushed to GitHub only after **both** the CEO smoke test (Stage 7) **and** the auditor audit have passed.
+9. **Watch after release** — for any change shipped, check `{{error_tracker}}` within 24h for new error groups or a drop in error-free rate. If anything spiked, hotfix or roll back before moving on.
+
+Do not reorder stages. Do not advance to the next stage until the current stage's artifact exists or the user has approved skipping. Stages may only be skipped via one of the two explicit lanes below.
+
+## Cross-model audit (operationalizing Constitution § 1)
+
+The constitutional invariant is in `./constitution.md § 1`. Below is how it is operationalized stage-by-stage:
+
+- Audit strength scales with change size: full review on the standard lanes, BLOCKING-only on the trivial lane.
+- The auditor is invoked at stages 2, 3, 4, 5, 6 (post-fix), and on every commit gate.
+- The auditor emits JSON per `AGENTS.md § Verdict output`.
+- `FAIL` halts the flow; `CONCERNS` advances with a logged warning (see `.harness/audits/concerns-*.json`); `PASS with advisory_items` advances silently; `WAIVED` is a CEO override and is rejected by the gate if any blocking item is `category: "universal-core"`.
+
+## Lanes (full description)
+
+A change picks one of three lanes; lane decisions are Tech-Lead inferred and CEO-confirmed (never silently auto-changed mid-flow).
+
+**Full workflow.** New feature, intent change (audit delta), schema change, or new external dependency. All 9 stages.
+
+**Stability-fix lane.** Bug fix or hotfix where intent is unchanged, no new feature surface, no schema change, no new dependency. Skip stages 1–3. **Failing test is mandatory** (if `test_required = true`) — write it before the fix, confirm it fails on the broken code, then fix and watch it go green. Path-based reviewer auto-fire on the diff (Stage 5) plus auditor audit on the fix correctness + test legitimacy (Stage 6).
+
+**Trivial-change lane.** < 20 LOC, no new feature surface, no schema change, no new dependency, no intent change (typo, copy tweak, single-line bug fix, dependency bump). Skip stages 1–3. Stage 4 reduces to applying the change with path-based reviewer auto-fire; Stage 5 confirms existing tests still pass. Auditor runs in **Quick mode (BLOCKING-only)** — security, data loss, and outright defects only. Stage 7 (smoke) skipped only for pure copy/text/translation; spot-check for any logic change. If the auditor's Quick audit surfaces non-trivial concerns, the lane is wrong — surface to CEO and re-classify.
+
+Knowing the lane in advance lets you triage a bug correctly: "panic-fix in 30min" vs. "plan for 48h with a workaround in the meantime."

package/template/.harness/scripts/README.md

@@ -0,0 +1,70 @@
+# `.harness/scripts/` — Starter Templates + Bootstrap Driver
+
+This directory holds:
+
+1. **Shell-script templates** that get copied into the user's project at `/init` time (target: `.harness/scripts/`). Each script is a **starter** — the user customizes the parts marked `# CUSTOMIZE:` based on their stack.
+
+2. **Standalone bootstrap driver** (`standalone-bootstrap.md`) — an AI-instruction file that runs when the user has cloned CCC-MAGI from GitHub directly (no CCC), the first time they open a CLI in the project.
+
+## File inventory
+
+| File | Type | Used by | What it does | Required? |
+|------|------|---------|--------------|-----------|
+| `bootstrap-check.sh` | Shell hook | Claude/Codex `UserPromptSubmit` event | Fires on every user prompt. If `.harness/state/install.json` is missing AND `.harness/` is present, injects a directive telling Claude to read `standalone-bootstrap.md` and run the bootstrap flow BEFORE responding. Exits silently if install.json exists. | **Yes — load-bearing** |
+| `standalone-bootstrap.md` | AI driver | CLAUDE.md Bootstrap Status Check + `bootstrap-check.sh` hook | Detects existing harness configs (using AI semantic judgment), presents 3-option menu, archives/deletes other configs, then invokes /init | **Yes — standalone path** |
+| `auditor-gate.sh` | Shell | every audit-gated skill | Invokes the auditor CLI ({{auditor_model}}), parses JSON verdict, returns exit code 0 (PASS / CONCERNS / WAIVED — all advance) / 2 (FAIL — halt) / 1 (script error, Universal Core WAIVED rejected, missing waiver_reason, or legacy verdict). CONCERNS verdicts are logged to `.harness/audits/concerns-*.json`; WAIVED verdicts to `.harness/audits/waivers-*.json`. | **Yes — core** |
+| `precommit-typecheck.sh` | Shell | Claude/Codex hooks (PreToolUse `git commit`) | Runs the project's typecheck before commit | Yes, customize per stack |
+| `lint-bans.sh` | Shell | Claude/Codex hooks (PreToolUse `git commit`) | Greps staged diff for anti-flag patterns | Yes if `{{anti_flag_rules}}` non-empty |
+| `precommit-cycles.sh` | Shell | Claude/Codex hooks (PreToolUse `git commit`) | Runs dependency-cycle check | Optional — only if `{{dependency_flow}}` is non-empty |
+| `format-edit.sh` | Shell | Claude/Codex hooks (PostToolUse Edit\|Write) | Runs the project's formatter on the edited file | Yes, customize per stack |
+| `post-migration.sh` | Shell | `/db-schema` skill (manual invocation) | Backend cache refresh + typed-bindings regeneration | Only if `{{backend_db_type}}` configured |
+| `memory-recall.sh` | Shell hook | Claude/Codex `SessionStart` event | Reads `.harness/memory/observations.jsonl`, scores entries by relevance to the current git branch's feature, injects top-N entries into Claude's `additionalContext`. Silent no-op when memory file is missing or empty. | Yes if memory layer in use |
+| `memory-snapshot.sh` | Shell hook | Claude/Codex `PreCompaction` event | Injects an instruction telling Claude to summarize the session's key decisions into `.harness/memory/observations.jsonl` BEFORE context compaction proceeds. Creates the memory directory/file on first run. | Yes if memory layer in use |
+| `budget-monitor.sh` | Shell hook | Claude/Codex `UserPromptSubmit` event | Reads `transcript_path` from hook input, parses Anthropic-reported `usage` from the most recent assistant turn (falls back to byte/4 estimate). **Auto-detects context budget from transcript's `model` field** (v0.10.3+): `[1m]` suffix → 1M, standard `claude-*` → 200K, `gpt-4*` → 128K, others → 200K safe default. Override via `CCC_CONTEXT_BUDGET` env var. Emits advisory `additionalContext` at 50% / 75% / 90% / 95% with the detected model shown in each message. 95% triggers a deferred end-of-turn 3-option `/compact` / `/handoff` / continue menu. Silent under 50%. Advisory-only — Claude Code doesn't expose runtime model switching to hooks. | Yes (P1.6) |
+
+## Why no harness-detect.sh anymore
+
+Earlier versions had a `harness-detect.sh` shell script for detecting existing harness installations. It's been **removed** in favor of AI-driven detection inside `standalone-bootstrap.md` (and a parallel CCC-bundled driver on the CCC side).
+
+Reasons:
+- Shell-based detection can only match canonical markers (e.g., `.bmad-core/`, `.cursorrules`). Real-world projects often have ad-hoc AI config files (`agent.md`, `agent/harness.md`, etc.) that no static rule catches.
+- AI can read file contents and make semantic judgments about what's harness-related.
+- One uniform mechanism (AI judgment + user confirmation) is simpler than maintaining two layers (shell strict-match + AI fallback).
+- See `CCC_harness_flow.md` § decision 1 for the architectural rationale.
+
+## Bash / POSIX only (for shell scripts)
+
+All shell scripts target **bash on macOS and Linux**. The harness-detect.sh removal also removed the last `declare -A` (bash 4+) dependency, so the remaining scripts are bash 3.2 compatible (macOS default).
+
+## Customization pattern
+
+Each shell script has a `# CUSTOMIZE:` block near the top. Edit that block, leave the rest alone:
+
+```bash
+# CUSTOMIZE: pick your stack's typecheck command
+# Examples:
+#   TypeScript:    COMMAND=(npx tsc --noEmit)
+#   Python+mypy:   COMMAND=(mypy .)
+#   Go:            COMMAND=(go vet ./...)
+COMMAND=(npx tsc --noEmit)
+```
+
+`/init` may pre-fill some `CUSTOMIZE` blocks based on detected `tech_stack` — but you're always free to override.
+
+## Permissions
+
+After copying to your project, make sure shell scripts are executable:
+
+```bash
+chmod +x .harness/scripts/*.sh
+```
+
+`/init` does this automatically.
+
+## Failure mode
+
+If a shell script fails (non-zero exit), the calling hook / skill halts. This is by design — broken hooks are infinitely better than silent skipping.
+
+If you want to temporarily disable a hook, edit `.claude/settings.json` (or `.codex/hooks.json`) to remove the entry, OR make the script `exit 0` early. **Do not delete the script** — other skills may reference it.
+
+For `standalone-bootstrap.md`: this file is read by AI, not executed. If you want to disable standalone-bootstrap behavior, edit the Bootstrap Status Check block at the top of `CLAUDE.md` to remove the "read standalone-bootstrap.md" instruction. (Not recommended — without it, new users get no guidance on existing-harness handling.)

package/template/.harness/scripts/auditor-gate.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+# auditor-gate.sh — invoke the auditor CLI on a target artifact, parse the structured
+# verdict, persist the result, and exit with the gate's exit code.
+#
+# Constitution § 1 (cross-model audit is mandatory) — every audit-gated skill
+# invokes this script. It is the load-bearing primitive for the harness.
+#
+# USAGE
+#   auditor-gate.sh review     <feature> <stage> <focus-text> [target-file]
+#   auditor-gate.sh diagnostic <feature>         <focus-text> [attempts-file]
+#
+# ENVIRONMENT
+#   AUDITOR_CLI         — "codex" (default) | "claude" | "gemini" | "none"
+#                         "none" = single-engine fallback (fresh-context same-model)
+#   AUDITOR_MODEL_ID    — model version string (default: gpt-5.5 for codex)
+#   AUDITOR_GATE_PRESET — optional preset name (loaded from
+#                         .harness/scripts/auditor-prompts/<preset>.md if exists)
+#   AUDITOR_GATE_TARGET_LABEL — optional human-readable label for the target
+#   AUDITOR_GATE_TARGET_MODE  — "full" (default) | "diff" | "diff-against:<rev>"
+#                         full              = embed entire target file (legacy behavior)
+#                         diff              = embed `git diff HEAD -- <target>` (working-tree change)
+#                         diff-against:<rev>= embed `git diff <rev> -- <target>`
+#                         When diff is empty (untracked / no change), falls back to full.
+#                         Use diff for code-change audits (Stage 5 implement) to cut input
+#                         tokens 60-80%. Use full for artifact audits (specs / plans / schemas).
+#
+# PROMPT-CACHE NOTE
+#   The prompt is assembled as [PRESET_PREFIX → FOCUS → TARGET]. OpenAI / Anthropic both
+#   apply automatic prefix caching when consecutive calls share the same opening tokens.
+#   DO NOT reorder these three parts — putting the variable TARGET last keeps the
+#   stable prefix cacheable across calls within the 5-min TTL window.
+#
+# EXIT CODES
+#   0 — PASS, CONCERNS, or WAIVED (all advance; caller reads JSON for nuance)
+#   1 — script error (CLI not found, malformed output, IO failure, JSON validation,
+#       Universal Core WAIVED attempt, missing waiver_reason, legacy verdict, etc.)
+#   2 — FAIL (halt)
+#
+# OUTPUT FILE
+#   review:     .harness/state/auditor-approvals/<feature>-stage<N>.json
+#   diagnostic: .harness/state/auditor-approvals/<feature>-stage<N>-diagnostic.json
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# ─────────────────────────────────────────────────────────────────────
+# Args
+# ─────────────────────────────────────────────────────────────────────
+MODE="${1:-}"
+case "$MODE" in
+  review)
+    FEATURE="${2:?feature name required}"
+    STAGE="${3:?stage required}"
+    FOCUS="${4:?focus text required}"
+    TARGET="${5:-}"
+    OUTPUT_SUFFIX="stage${STAGE}"
+    ;;
+  diagnostic)
+    FEATURE="${2:?feature name required}"
+    FOCUS="${3:?focus text required}"
+    TARGET="${4:-}"
+    STAGE="6"  # diagnostic mode is always Stage 6 escalation
+    OUTPUT_SUFFIX="stage6-diagnostic"
+    ;;
+  *)
+    echo "usage: $0 review <feature> <stage> <focus> [target]" >&2
+    echo "       $0 diagnostic <feature> <focus> [attempts-file]" >&2
+    exit 1
+    ;;
+esac
+
+# ─────────────────────────────────────────────────────────────────────
+# Resolve auditor + paths
+# ─────────────────────────────────────────────────────────────────────
+AUDITOR_CLI="${AUDITOR_CLI:-codex}"
+AUDITOR_MODEL_ID="${AUDITOR_MODEL_ID:-gpt-5.5}"
+STATE_DIR=".harness/state/auditor-approvals"
+mkdir -p "$STATE_DIR"
+OUTPUT_FILE="$STATE_DIR/${FEATURE}-${OUTPUT_SUFFIX}.json"
+LABEL="${AUDITOR_GATE_TARGET_LABEL:-${FEATURE} stage${STAGE}}"
+
+# Load preset focus prefix if specified
+PRESET_PREFIX=""
+if [ -n "${AUDITOR_GATE_PRESET:-}" ]; then
+  PRESET_FILE=".harness/scripts/auditor-prompts/${AUDITOR_GATE_PRESET}.md"
+  if [ -f "$PRESET_FILE" ]; then
+    PRESET_PREFIX="$(cat "$PRESET_FILE")"$'\n\n'
+  else
+    echo "warning: preset file not found: $PRESET_FILE" >&2
+  fi
+fi
+
+FULL_PROMPT="${PRESET_PREFIX}${FOCUS}"
+
+# ─────────────────────────────────────────────────────────────────────
+# Resolve TARGET content (full file / diff / diff-against:<rev>)
+# Computed once here so both invoke_codex and invoke_claude_fresh share
+# identical TARGET_BLOCK — keeps logic in one place + prompt cache stable.
+# ─────────────────────────────────────────────────────────────────────
+TARGET_MODE="${AUDITOR_GATE_TARGET_MODE:-full}"
+TARGET_BLOCK=""
+
+resolve_target_block() {
+  [ -z "$TARGET" ] && return 0
+
+  case "$TARGET_MODE" in
+    full)
+      if [ -f "$TARGET" ]; then
+        TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+      fi
+      ;;
+    diff)
+      # Working-tree diff for this file/path. Empty result = no staged or unstaged
+      # change → fall back to full so the auditor still has something to look at.
+      if command -v git >/dev/null 2>&1; then
+        local diff_text
+        diff_text="$(git diff HEAD -- "$TARGET" 2>/dev/null || true)"
+        if [ -n "$diff_text" ]; then
+          TARGET_BLOCK=$'\n\n=== TARGET (diff) ===\n'"$diff_text"
+        elif [ -f "$TARGET" ]; then
+          echo "info: AUDITOR_GATE_TARGET_MODE=diff returned empty for $TARGET — falling back to full file" >&2
+          TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+        fi
+      else
+        echo "warning: TARGET_MODE=diff requested but git not on PATH — falling back to full" >&2
+        [ -f "$TARGET" ] && TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+      fi
+      ;;
+    diff-against:*)
+      local rev="${TARGET_MODE#diff-against:}"
+      if command -v git >/dev/null 2>&1; then
+        local diff_text
+        diff_text="$(git diff "$rev" -- "$TARGET" 2>/dev/null || true)"
+        if [ -n "$diff_text" ]; then
+          TARGET_BLOCK=$'\n\n=== TARGET (diff vs '"$rev"') ===\n'"$diff_text"
+        elif [ -f "$TARGET" ]; then
+          echo "info: AUDITOR_GATE_TARGET_MODE=diff-against:$rev returned empty — falling back to full file" >&2
+          TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+        fi
+      else
+        echo "warning: TARGET_MODE=diff-against requested but git not on PATH — falling back to full" >&2
+        [ -f "$TARGET" ] && TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+      fi
+      ;;
+    *)
+      echo "warning: unknown AUDITOR_GATE_TARGET_MODE=$TARGET_MODE — falling back to full" >&2
+      [ -f "$TARGET" ] && TARGET_BLOCK=$'\n\n=== TARGET ===\n'"$(cat "$TARGET")"
+      ;;
+  esac
+}
+
+resolve_target_block
+
+# ─────────────────────────────────────────────────────────────────────
+# JSON output schema
+# ─────────────────────────────────────────────────────────────────────
+read -r -d '' REVIEW_SCHEMA <<'JSON' || true
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["verdict", "risk_score", "waiver_reason", "blocking_items", "advisory_items"],
+  "properties": {
+    "verdict": {"type": "string", "enum": ["PASS", "CONCERNS", "FAIL", "WAIVED"]},
+    "risk_score": {"type": "integer", "minimum": 0, "maximum": 10},
+    "waiver_reason": {"type": "string"},
+    "blocking_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["category", "rule_source", "finding"],
+        "properties": {
+          "category": {"type": "string", "enum": ["universal-core", "strong", "advisory"]},
+          "rule_source": {"type": "string"},
+          "finding": {"type": "string"}
+        }
+      }
+    },
+    "advisory_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["rule_source", "finding"],
+        "properties": {
+          "rule_source": {"type": "string"},
+          "finding": {"type": "string"}
+        }
+      }
+    }
+  }
+}
+JSON
+
+read -r -d '' DIAGNOSTIC_SCHEMA <<'JSON' || true
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["hypotheses"],
+  "properties": {
+    "hypotheses": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary", "evidence", "next_step"],
+        "properties": {
+          "summary": {"type": "string"},
+          "evidence": {"type": "string"},
+          "next_step": {"type": "string"}
+        }
+      }
+    }
+  }
+}
+JSON
+
+# ─────────────────────────────────────────────────────────────────────
+# Invoke the auditor CLI
+# ─────────────────────────────────────────────────────────────────────
+# Note: mktemp template without .json suffix — macOS BSD mktemp doesn't
+# substitute X chars when a dot extension follows. The output file is JSON
+# regardless; the extension doesn't matter for jq parsing.
+TEMP_OUTPUT="$(mktemp /tmp/auditor-gate.XXXXXX)"
+
+invoke_codex() {
+  # Codex CLI 0.130.0+ removed `--file <path>` support. Embed TARGET content
+  # in the prompt body instead (same pattern as invoke_claude_fresh).
+  # TARGET_BLOCK was resolved upstream by resolve_target_block (honors
+  # AUDITOR_GATE_TARGET_MODE = full / diff / diff-against:<rev>).
+  local schema_file="$(mktemp /tmp/schema.XXXXXX)"
+  if [ "$MODE" = "review" ]; then
+    echo "$REVIEW_SCHEMA" > "$schema_file"
+  else
+    echo "$DIAGNOSTIC_SCHEMA" > "$schema_file"
+  fi
+
+  local prompt_with_target="${FULL_PROMPT}${TARGET_BLOCK}"
+
+  codex exec \
+    --model "$AUDITOR_MODEL_ID" \
+    --output-schema "$schema_file" \
+    -- "$prompt_with_target" > "$TEMP_OUTPUT"
+
+  rm -f "$schema_file"
+}
+
+invoke_claude_fresh() {
+  # Single-engine fallback: invoke Claude with --output-format json in a fresh
+  # context (no prior session). Lower bias-cancellation but preserves discipline.
+  # TARGET_BLOCK was resolved upstream by resolve_target_block.
+  local schema_hint=""
+  if [ "$MODE" = "review" ]; then
+    schema_hint=$'\n\nRespond with JSON only matching schema: {"verdict": "PASS" | "CONCERNS" | "FAIL" | "WAIVED", "risk_score": 0-10, "waiver_reason": "string (required if WAIVED)", "blocking_items": [{"category": "universal-core" | "strong" | "advisory", "rule_source": "...", "finding": "..."}], "advisory_items": [{"rule_source": "...", "finding": "..."}]}'
+  else
+    schema_hint=$'\n\nRespond with JSON only matching schema: {"hypotheses": [{"summary": "...", "evidence": "...", "next_step": "..."}, ...]}'
+  fi
+
+  claude --output-format json --no-session -- "${FULL_PROMPT}${schema_hint}${TARGET_BLOCK}" > "$TEMP_OUTPUT"
+}
+
+invoke_none() {
+  # No auditor configured. Emit a structured "skipped" verdict and let the caller decide.
+  echo "warning: AUDITOR_CLI=none — emitting auto-PASS without verification" >&2
+  cat > "$TEMP_OUTPUT" <<JSON
+{
+  "verdict": "PASS",
+  "risk_score": 0,
+  "blocking_items": [],
+  "advisory_items": [
+    {
+      "rule_source": "constitution.md § 1",
+      "finding": "auditor skipped (AUDITOR_CLI=none); single-engine fallback not engaged either — config error?"
+    }
+  ]
+}
+JSON
+}
+
+case "$AUDITOR_CLI" in
+  codex)  invoke_codex ;;
+  claude) invoke_claude_fresh ;;
+  none)   invoke_none ;;
+  *)
+    echo "unknown AUDITOR_CLI: $AUDITOR_CLI" >&2
+    exit 1
+    ;;
+esac
+
+# ─────────────────────────────────────────────────────────────────────
+# Parse + persist
+# ─────────────────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  echo "auditor-gate.sh requires jq. Install with: brew install jq" >&2
+  cp "$TEMP_OUTPUT" "$OUTPUT_FILE"
+  exit 1
+fi
+
+# Validate JSON
+if ! jq empty "$TEMP_OUTPUT" 2>/dev/null; then
+  echo "auditor returned non-JSON output:" >&2
+  cat "$TEMP_OUTPUT" >&2
+  cp "$TEMP_OUTPUT" "$OUTPUT_FILE"
+  exit 1
+fi
+
+# Persist
+mv "$TEMP_OUTPUT" "$OUTPUT_FILE"
+
+# ─────────────────────────────────────────────────────────────────────
+# Exit on verdict
+# ─────────────────────────────────────────────────────────────────────
+if [ "$MODE" = "diagnostic" ]; then
+  # Diagnostic mode doesn't have a verdict — just exit 0 if hypotheses present.
+  HYPOTHESIS_COUNT=$(jq '.hypotheses | length' "$OUTPUT_FILE")
+  if [ "$HYPOTHESIS_COUNT" -gt 0 ]; then
+    echo "✓ Diagnostic complete: $HYPOTHESIS_COUNT hypothesis/hypotheses written to $OUTPUT_FILE"
+    exit 0
+  else
+    echo "✗ Diagnostic returned no hypotheses" >&2
+    exit 1
+  fi
+fi
+
+VERDICT=$(jq -r '.verdict' "$OUTPUT_FILE")
+RISK_SCORE=$(jq -r '.risk_score // 0' "$OUTPUT_FILE")
+BLOCKING_COUNT=$(jq '.blocking_items // [] | length' "$OUTPUT_FILE")
+ADVISORY_COUNT=$(jq '.advisory_items // [] | length' "$OUTPUT_FILE")
+
+case "$VERDICT" in
+  PASS)
+    echo "✓ ${LABEL}: PASS (risk_score=${RISK_SCORE})"
+    if [ "$ADVISORY_COUNT" -gt 0 ]; then
+      echo "  (note: $ADVISORY_COUNT advisory item(s) in $OUTPUT_FILE)"
+    fi
+    exit 0
+    ;;
+  CONCERNS)
+    # Log to .harness/audits/ for CEO review
+    AUDIT_DIR=".harness/audits"
+    mkdir -p "$AUDIT_DIR"
+    TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+    CONCERNS_FILE="$AUDIT_DIR/concerns-${FEATURE}-stage${STAGE}-${TIMESTAMP}.json"
+    cp "$OUTPUT_FILE" "$CONCERNS_FILE"
+    echo "⚠ ${LABEL}: CONCERNS (risk_score=${RISK_SCORE}, $BLOCKING_COUNT item(s); advancing)"
+    echo "  Logged to: $CONCERNS_FILE"
+    echo "  CEO should review before commit."
+    exit 0
+    ;;
+  FAIL)
+    echo "✗ ${LABEL}: FAIL (risk_score=${RISK_SCORE}, $BLOCKING_COUNT blocking item(s))"
+    echo "  See: $OUTPUT_FILE"
+    exit 2
+    ;;
+  WAIVED)
+    # Verify no Universal Core items are being waived
+    UNIVERSAL_CORE_COUNT=$(jq '[.blocking_items[]? | select(.category == "universal-core")] | length' "$OUTPUT_FILE")
+    if [ "$UNIVERSAL_CORE_COUNT" -gt 0 ]; then
+      echo "✗ ${LABEL}: WAIVED rejected — $UNIVERSAL_CORE_COUNT Universal Core item(s) cannot be waived (constitution.md § 3 — CEO has final authority EXCEPT on Universal Core)" >&2
+      echo "  See: $OUTPUT_FILE" >&2
+      exit 1
+    fi
+    WAIVER_REASON=$(jq -r '.waiver_reason // "(no reason given)"' "$OUTPUT_FILE")
+    if [ "$WAIVER_REASON" = "(no reason given)" ] || [ "$WAIVER_REASON" = "null" ]; then
+      echo "✗ ${LABEL}: WAIVED rejected — waiver_reason is required" >&2
+      exit 1
+    fi
+    AUDIT_DIR=".harness/audits"
+    mkdir -p "$AUDIT_DIR"
+    TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+    WAIVER_FILE="$AUDIT_DIR/waivers-${FEATURE}-stage${STAGE}-${TIMESTAMP}.json"
+    cp "$OUTPUT_FILE" "$WAIVER_FILE"
+    echo "⚠ ${LABEL}: WAIVED (advancing; reason: $WAIVER_REASON)"
+    echo "  Logged to: $WAIVER_FILE"
+    exit 0
+    ;;
+  APPROVE|"REQUEST CHANGES")
+    echo "auditor returned legacy verdict '$VERDICT' — schema migration incomplete. Update the auditor's prompt to use PASS/CONCERNS/FAIL/WAIVED." >&2
+    exit 1
+    ;;
+  *)
+    echo "auditor returned unexpected verdict: $VERDICT" >&2
+    exit 1
+    ;;
+esac