@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/codex-subagents.md

@@ -0,0 +1,98 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Codex Subagent Adapter
+
+Use this adapter when Build Loop runs inside Codex. It translates Build Loop's host-neutral "parallel subagents" concept into Codex-native delegation without changing Claude Code's `agents/*.md` runtime.
+
+## Core Rule
+
+Codex may use subagents only when the user explicitly authorizes delegation or parallel agent work. Examples: "use subagents", "parallelize this", "delegate", "spin up workers", or `/build-loop --parallel ...`.
+
+If authorization is absent, keep the work local in the lead Codex session. Still write the same MECE plan and ownership packets, but do not spawn workers.
+
+## Role Mapping
+
+| Build Loop need | Codex role | Use when |
+|---|---|---|
+| Codebase question | `explorer` | The answer can be read-only, bounded, and returned as facts with file paths. |
+| Implementation slice | `worker` | The write set is disjoint from other workers and the interface contract is clear. |
+| Phase 4 review passes | lead session inline, or `explorer` if authorized | See the enumerated passes below — the lead owns these whether or not delegation is allowed. |
+| Final integration | lead session | The lead must own merge, validation, and final judgment. |
+
+**Phase 4 review is not one pass — it is a set.** Whether run inline (default) or via an authorized `explorer`, the lead must cover all of these every non-trivial build; do not skip a pass just because Codex lacks a dedicated agent file for it:
+
+- **Adversarial audit (independent-auditor)** — read the diff against intent/goal/PRD/constitution; verdict `yay`/`nay`/`suggest_correction`/`look_again`. Advisory at chunk close, gating at build scope.
+- **Fact-check** — trace every rendered metric (%, $, score, count) to its source; flag absolute claims. *Blocking* when a rendered number is unverifiable.
+- **Mock-data scan** — production paths only; lorem/faker/hardcoded/`Math.random()`-in-display. *Blocking* when it renders to the user.
+- **Security review** — only when Assess flagged a risk-surface change (auth, network, persistence, secrets, external input); OWASP LLM/Agentic/Web top-10. *Blocking* on critical/high (feeds the exit gate).
+
+The first row's "read-only, does not block" applies to the adversarial-audit *critic* pass; the fact-check, mock-scan, and security passes CAN block and route to Iterate.
+
+## Permission Gate
+
+Before spawning any Codex subagent:
+
+1. Confirm user authorization is explicit in the current request or command flags.
+2. Confirm the task is not on the immediate critical path.
+3. Confirm the subtask has a bounded write set or read-only question.
+4. Confirm the prompt includes a MECE ownership packet.
+
+If any condition fails, do the work locally.
+
+## When Not To Delegate
+
+- Ambiguous product decisions.
+- Final integration or final report.
+- Destructive git operations.
+- Push/deploy confirmation.
+- A task whose result is required before the lead can make the next local move.
+- Files already owned by another active worker.
+- Cross-file architecture decisions that were not settled in the plan.
+
+## Prompt Packet Required
+
+Every Codex worker prompt must include:
+
+- `task`: one concrete outcome.
+- `owns`: exact files or directories the worker may edit.
+- `does_not_own`: files, directories, or responsibilities the worker must avoid.
+- `context`: condensed facts from Phase 1 and Phase 2.
+- `interface_contract`: functions, routes, schemas, props, CLI flags, or docs the worker must preserve or expose.
+- `integration_checkpoint`: what the lead will verify before merging the worker result.
+- `validation`: commands the worker should run if feasible.
+- `return_format`: changed files, summary, validation, unresolved risks, integration notes.
+
+Tell every worker: "You are not alone in the codebase. Do not revert edits made by others; adapt around them and report conflicts."
+
+## Context Policy
+
+Prefer explicit prompt packets over full context forks. Use full context only when the worker genuinely needs the thread history to avoid a wrong implementation.
+
+Shared reads should happen once in the lead session, then be condensed into worker prompts. This keeps workers focused and reduces contradictory interpretations.
+
+## Parallel Pattern
+
+1. Lead creates the plan and identifies parallel-safe groups.
+2. Lead spawns only independent sidecar work.
+3. Lead continues non-overlapping local work while workers run.
+4. Lead waits only when blocked on a worker result.
+5. Lead reviews changed files and integrates deliberately.
+6. Lead runs final validation locally.
+
+## Return Format
+
+Workers should finish with:
+
+```text
+Changed files:
+- <path>: <what changed>
+
+Validation:
+- <command or "not run">: <result or reason>
+
+Integration notes:
+- <contract, migration, or ordering notes>
+
+Unresolved risks:
+- <risk or "none known">
+```

package/skills/build-loop/references/coordination.md

@@ -0,0 +1,161 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Coordination — How build-loop consumes agent-rally
+
+Build-loop is a **consumer** of the agent-rally architecture, but it currently
+vendors native embedded copies of the substrate and watcher while the standalone
+repos mature. Treat `agent-rally-point` and `agent-rally-watcher` as
+mini-plugins inside build-loop: grouped scripts, skills, docs, tests, and thin
+build-loop adapters first; full spin-out later. Cross-reference the upstream
+architecture docs before changing how build-loop reads or writes events, but do
+not make build-loop depend on those external repos at runtime yet.
+
+> **Binding constitution** (verdict-gating, MECE briefs, Phase D closeout, peer-no-mutate, release-surface verification) lives in [`references/coordination-rules.md`](../../../references/coordination-rules.md). This file documents the **integration shape**, not the rules of engagement.
+
+## Build-loop's position in the three-layer model
+
+```
+Layer 3 — CONSUMERS (build-loop, codex, claude_code, ...)
+              ▲
+              │  build-loop is one of many
+              ▼
+Layer 2 — agent-rally-watcher (embedded watcher namespace; optional listener)
+              ▲
+              │  build-loop CAN subscribe, OR poll Layer 1 directly
+              ▼
+Layer 1 — agent-rally-point (embedded substrate; channel, schema, post API)
+```
+
+Build-loop **always** uses Layer 1 (it posts events and calls `checkpoint_read`). It uses Layer 2 **opportunistically** — when a peer session is detected via Rally Point presence, the coordination polling gate spins up a `coordination_watch.py` loop or installs a watcher subscription so chunk-close, commit, and feedback events surface within seconds rather than at the next phase boundary.
+
+Native skill entrypoints:
+
+- `skills/agent-rally-point/SKILL.md` — substrate workflow, CLI, boundary,
+  run identity, and spin-out rules.
+- `skills/agent-rally-watcher/SKILL.md` — watcher workflow, JSONL sensor
+  behavior, closeout, and spin-out rules.
+
+The machine-readable boundary is `scripts/rally_point/plugin_boundary.json`.
+
+## What build-loop posts
+
+Every cross-session signal goes through `scripts/rally_point/post.py::post()` (the canonical writer that bumps revision *before* appending — see [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md) for the field-by-field record format). Raw `append_change(...)` without a subsequent `bump_revision(...)` is a silent-no-op for peers (`feedback_codex_pass_is_gate_not_comment`).
+
+| When                                  | `kind`       | `payload` shape                                                  | Triggered by                       |
+|---------------------------------------|--------------|------------------------------------------------------------------|------------------------------------|
+| Chunk closes and lands on the branch  | `phase`      | `{phase: "chunk-close", chunk_id, commit_sha, files_changed}`    | Phase 3 commit step                |
+| Phase boundary (Phase 1, 4, 5)        | `phase`      | `{phase: "<phase-name>", summary, ...}`                          | Orchestrator phase entry           |
+| Build run closes (Phase D)            | `phase`      | `{phase: "run-closeout", session_id, coord_file, outcomes}`      | Phase D closeout sequence          |
+| Peer hands off work to a verifier     | `handoff`    | `{from_tool, to_tool, work_item, deadline_ts}`                   | Sub-step F when a peer is present  |
+| Verifier returns a verdict            | `feedback`   | `{step, verdict: PASS|VARIANCE|BLOCKED, rationale, evidence}`    | After verifier runs on a step      |
+| Architecture scan completes           | `arch-scan-complete` | `{digest_path, files_scanned}`                            | Phase 1 architecture baseline      |
+| Dependency manifest changed           | `dep-change` | `{manifest, added, removed, session_id}`                         | Phase 3 commit step on manifest    |
+| Coordination announcement / take-over | `phase`      | `{phase: "leadership", role, scope}`                             | Multi-orchestrator handoff         |
+
+All writes are fire-and-forget — a coordination failure must never crash the build.
+
+## What build-loop reads
+
+### Phase 1 Assess — inbox pickup + presence check
+
+At Phase 1 entry, the orchestrator (see `agents/build-orchestrator.md` §"Phase 1: Assess") runs:
+
+```bash
+python3 scripts/coordination_status.py --workdir "$PWD" --session-id "$SESSION_ID" --json
+```
+
+The status reports: active peers (live sessions in the channel's `sessions/`), session-ack-aware unread inbox messages (`inbox/<my-tool>.jsonl`, `inbox/all.jsonl`), task-heartbeat health when `--task-ref` is set, and any active coordination file. If `active_peers > 0` OR `inbox_unread_count > 0`, the orchestrator MUST drain the inbox before dispatching any chunk; otherwise the peer's last verdict/handoff is invisible to the new run. After acting on the inbox payload, run `python3 scripts/agent_rally.py ack-inbox --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" --json` so stale notes stop ringing the doorbell.
+
+### Coordination polling gate — watcher install when a peer is present
+
+When the Phase 1 status returns peers, build-loop installs a cheap continuous watcher:
+
+```bash
+python3 scripts/coordination_watch.py --workdir "$PWD" --session-id "$SESSION_ID" --tool claude_code --task-ref "$TASK_REF" --interval 5 --jsonl --baseline-current
+```
+
+The watcher reports revision changes, inbox deltas, and task-heartbeat health as line-delimited JSON. The orchestrator polls it before commits, before final responses, and after any 30-second work interval. When a peer posts (e.g. a verifier returns a `feedback` verdict), the orchestrator routes the response into the active coordination file's "Codex feedback log" section rather than asking the user to paste it.
+
+For long-running work, write `agent_rally.py heartbeat --task-ref "$TASK_REF"`
+at task start and at least every 10 minutes. Presence says the session is live;
+task heartbeat says it is still on the claimed task.
+
+The watcher process is OPTIONAL — if the daemon process can't start (no FS-watch support, sandboxed environment), the orchestrator falls back to per-checkpoint `coordination_status.py` polls. The same flow works; latency is higher.
+
+### Chunk-close — checkpoint read for downstream chunks
+
+After each chunk's commit step closes, the orchestrator runs `checkpoint_read` against this session's cursor to surface any peer events that landed during the chunk. Reactions (`reinstall`, `re-baseline`, `soft-claim`) are documented in [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md). Reactions are **awareness only** — `soft-claim` warns when a peer touched files this session also plans to touch; the orchestrator decides whether to wait, rebase, or proceed.
+
+## Peer-no-mutate rule
+
+When a peer presence record indicates active work AND that work isn't already merged (`branch_merge_status: unmerged` AND files differ from `origin/main`), build-loop's orchestrator MUST NOT modify the same files. The rule and the merge-status pre-check are in [`references/coordination-rules.md`](../../../references/coordination-rules.md) §"Peer-no-mutate" and `feedback_verify_peer_merged_before_blocking`.
+
+Read-only operations (Phase 1 architecture baseline, plan drafting, fact-check) are always safe and do not invoke the rule.
+
+## Embedded mini-plugin boundary
+
+For now, the Rally Point substrate and watcher still ship inside the
+build-loop plugin, but they are treated as embedded mini-plugins with
+explicit extraction edges:
+
+| Future plugin | Embedded namespace | Build-loop compatibility entrypoints |
+|---|---|---|
+| `agent-rally-point` | `scripts/rally_point/**` | `scripts/agent_rally.py`, `commands/agent-rally-point.md`, `hooks/*rally-point.sh`, `scripts/coordination_status.py`, `scripts/coordination_rally.py`, `scripts/coordination_bootstrap.py` |
+| `agent-rally-watcher` | `scripts/agent_rally_watcher/**` | `scripts/coordination_watch.py` |
+
+The machine-readable contract lives at
+`scripts/rally_point/plugin_boundary.json` and is validated by:
+
+```bash
+python3 scripts/rally_point/boundary.py --repo "$PWD" --check --json
+python3 scripts/agent_rally.py boundary --workdir "$PWD" --check --json
+```
+
+Boundary rule: put substrate behavior in `scripts/rally_point/**`, watcher
+behavior in `scripts/agent_rally_watcher/**`, and leave build-loop files as
+thin adapters. Do not import build-loop memory-store or orchestration internals
+from those namespaces unless the dependency is explicitly isolated as an
+adapter in the boundary manifest.
+
+## Discovery integration (current)
+
+Build-loop uses `scripts/rally_point/discovery_bridge.py` as the shared
+channel resolver. It prefers the standalone `agent-rally-point` discovery
+surface when installed and falls back to build-loop's embedded resolver only
+when needed. Both native discovery and the embedded fallback default to
+`~/.agent-rally-point/apps/...`; the fallback uses the local worktree-aware
+`<slug>` when no native `<repo-id>` is available.
+
+The discovery layer (see
+[`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md))
+provides:
+
+```python
+from agent_rally_point.discover import discover
+info = discover()  # returns dict with channel_dir, channel_layout, active_revision, active_peers, ...
+channel_dir = info["channel_dir"]   # canonical OR legacy-fallback path
+```
+
+Current build-loop callers route through the bridge:
+
+1. `scripts/agent_rally.py` resolves `where`, `presence`, `handoff`, `lead`,
+   and `boundary` through the shared namespace.
+2. `scripts/coordination_status.py` reads status from the resolved channel
+   instead of deriving a parallel channel path.
+3. `scripts/rally_point/session_probe.py` and `scripts/rally_point/hooks.py`
+   use the resolved channel for session-start and pre-edit hook behavior.
+4. `scripts/coordination_watch.py` remains a compatibility wrapper; watcher
+   behavior lives under `scripts/agent_rally_watcher/`.
+
+## Cross-references
+
+- **Substrate (channel format, post API, presence, lifecycle)** — [`agent-rally-point/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-point/blob/main/ARCHITECTURE.md)
+- **Record schema (all 6 kinds + payloads)** — [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md)
+- **Discovery protocol (manifest, CLI, `discover()`)** — [`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md)
+- **Push-based daemon (consumers.toml, sinks)** — [`agent-rally-watcher/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-watcher/blob/main/ARCHITECTURE.md)
+- **Binding constitution (verdicts gating, MECE briefs, Phase D closeout)** — [`references/coordination-rules.md`](../../../references/coordination-rules.md)
+- **Per-run coordination file template** — [`references/coordination-file-template.md`](../../../references/coordination-file-template.md)
+
+## Why a separate doc
+
+`coordination-rules.md` is the binding *constitution* — operating rule, verdict gating, MECE field list, closeout sequence. This file is the *integration map* — where build-loop sits in the three-layer architecture, what it posts, what it reads, where the path-hardcoding lives, and what the discovery migration looks like. Conceptually distinct audiences: the rules file is for any participant; this file is for build-loop's orchestrator and anyone modifying how build-loop talks to rally-point.

package/skills/build-loop/references/correction-aware-capture.md

@@ -0,0 +1,177 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Correction-aware lesson capture — three-tier design
+
+## Why
+
+Two gaps in the prior capture stack:
+
+1. **`scan_transcript_for_decisions.py` no-ops entirely without Ollama.**
+   The script gates on `shutil.which("ollama")`; absent the binary, an
+   entire session's worth of decisions is silently dropped.
+2. **No lessons / feedback lane from live conversation.** The decisions
+   scanner captures decisions only. A user correcting the assistant's
+   just-taken action — the highest-signal lesson event in a session —
+   had no trigger and no destination.
+
+The three-tier design closes both gaps without disrupting the existing
+decisions pipeline.
+
+## Three tiers
+
+### Tier 1 — Deterministic Stop-hook (always runs, no LLM)
+
+**Script:** `scripts/scan_corrections/`
+**Hook:** `hooks/hooks.json` Stop entry, fires alongside (not instead of)
+the decisions scanner.
+
+Detects three classes of high-signal patterns in USER turns:
+
+| Class | Patterns | Confidence |
+|---|---|---|
+| Correction | `revert that`, `don't X`, `undo`, `stop X`, `back that out`, `wrong approach` | `confirmed` (extra: `prior_assistant_acted: true` when assistant just used tools) |
+| Preference | `always X`, `never X`, `must X`, `default to X`, `we use X for Y`, `prefer X` | `confirmed` |
+| Tradeoff | `X instead of Y`, `actually X not Y`, `X over Y because Z` | `confirmed` |
+
+Scope routing: keywords like `across projects`, `globally`, `for all projects`,
+`as a rule`, `standing rule` flag the candidate as `scope: global` (otherwise
+`project`). Anti-false-positive: wh-question turns ending in `?` are skipped
+by hard-skip patterns; greetings/thanks/ok are skipped.
+
+Writes one `.build-loop/pending-lessons/<ts>-<kind>-<id>.md` per candidate
+with YAML frontmatter:
+
+```yaml
+---
+id: <16-char sha1>
+kind: correction|preference|tradeoff
+signal_type: <named pattern>
+confidence: confirmed
+scope: project|global
+turn_index: <int>
+captured_chars: <int>
+tier: 1-deterministic
+source: stop-hook
+captured_at: <iso8601>
+extras:
+  prior_assistant_acted: true|false
+---
+
+## Quote
+> <verbatim user span>
+
+## Context (±200 chars)
+```
+
+Idempotent: `id_hash` is a SHA-1 of (kind, signal_type, normalized quote),
+so re-running the scanner on the same transcript does not duplicate files.
+Promoted/discarded subdirs are also checked for dedup.
+
+Fail-open contract: any exception logs to stderr and exits 0. The
+`.build-loop/.no-capture` opt-out short-circuits before any work.
+`SCAN_CORRECTIONS_BUDGET_S` (default 10s) caps wall-clock.
+
+### Tier 2 — Optional Ollama accelerator (existing path, unchanged)
+
+**Script:** `scripts/scan_transcript_for_decisions.py` (the existing
+decisions scanner, untouched). When Ollama is installed AND the
+transcript is large enough to benefit from clustering, this path
+distills/dedups decisions and writes to
+`build-loop-memory/projects/<slug>/decisions/` (or `_review/` for
+quarantine).
+
+Tier 2 is **strictly optional**. The user installed Ollama on this
+machine, so it runs; on a fresh machine without Ollama, tier 1 alone
+guarantees capture and the session continues uninterrupted.
+
+### Tier 3 — Host-agent refinement (the primary intelligence)
+
+**Script:** `scripts/surface_pending_lessons.py`
+**Consumed by:** the host coding agent (Claude Code in this build,
+Codex on a Codex host, etc.) at SessionStart.
+
+Per the user's standing "host-agent-is-the-LLM" rule, the host coding
+agent is the primary refinement layer. Each session, the host reads
+`.build-loop/pending-lessons/` (and optionally
+`build-loop-memory/projects/<slug>/decisions/_review/`), classifies each
+candidate, and promotes via:
+
+- `scripts/memory_writer.py` — for `kind=lesson|feedback|preference`
+  (routes to `build-loop-memory/lessons/` for `scope=global` or
+  `build-loop-memory/projects/<slug>/lessons/` for `scope=project`)
+- `scripts/write_decision/__main__.py` — for `kind=decision`
+
+Discarded candidates move into
+`.build-loop/pending-lessons/discarded/` (any file there is silently
+skipped on re-runs, so the discard is durable).
+
+The same surface also exposes the existing Ollama `_review/` quarantine
+when `--include-decisions-review` is set, so the host agent has one
+queue to drain.
+
+## Store bridge (harness ↔ build-loop-memory)
+
+**Script:** `scripts/bridge_lesson_to_harness.py`
+
+Once a lesson lands in build-loop-memory (via tier-3 promotion or any
+other path), it can be mirrored into the harness auto-memory store the
+host coding agent auto-loads at session start
+(`~/.claude/projects/-Users-<u>/memory/`). The bridge:
+
+- Resolves a deterministic target basename `<kind>_<slug>.md` matching
+  the harness convention
+- Augments the bridged copy's frontmatter with `bridged_from`,
+  `bridged_at`, `source_store: build-loop-memory`
+- Appends a one-line entry to harness `MEMORY.md` under
+  `## Bridged from build-loop-memory` (creates the section if absent;
+  preserves other sections; dedup'd on target basename)
+
+Idempotent and reversible. Only `lesson | feedback | preference | convention | gotcha`
+types bridge; decisions stay in their own canonical store.
+
+## Triggers — what fires when
+
+| Event | Tier | Effect |
+|---|---|---|
+| Session ends (Stop hook) | 1 | tier-1 scanner writes raw candidates to `.build-loop/pending-lessons/` |
+| Session ends (Stop hook) | 2 | tier-2 scanner (Ollama, if present) writes distilled decisions |
+| Session starts (host agent reads context-bootstrap) | 3 | pending-lessons queue count surfaces in queue summary; host agent runs `surface_pending_lessons.py` to refine |
+| Lesson promoted to build-loop-memory | — | `bridge_lesson_to_harness.py` mirrors to harness auto-memory |
+
+## File layout summary
+
+```
+scripts/
+  scan_corrections/
+    __init__.py
+    detect.py             — patterns + Candidate dataclass + JSONL parser
+    __main__.py           — Stop-hook CLI (tier 1)
+    test_detect.py        — 26 unit tests
+    test_cli.py           — 8 CLI integration tests
+  surface_pending_lessons.py     — tier 3 host-agent surface
+  test_surface_pending_lessons.py — 10 tests
+  bridge_lesson_to_harness.py    — store bridge
+  test_bridge_lesson_to_harness.py — 11 tests
+  scan_transcript_for_decisions.py — UNCHANGED (tier 2)
+
+hooks/hooks.json — Stop hook now runs both scanners in parallel
+
+scripts/context_bootstrap.py — QUEUE_NAMES extended with "pending-lessons"
+
+.build-loop/pending-lessons/   — tier-1 candidate queue (this run)
+                  /promoted/    — host-agent promoted (silenced)
+                  /discarded/   — host-agent discarded (silenced)
+```
+
+## Non-goals + tradeoffs
+
+- **Not a replacement for `auto-decision-capture`.** That skill is for
+  the host agent's in-session reasoning — explicit captures during the
+  conversation. Tier-1 + tier-3 fire at session boundaries; the skill
+  fires inline. They compose.
+- **Tier 1 is intentionally narrow.** Adding fuzzy patterns would
+  produce false positives. The host agent (tier 3) is where ambiguous
+  cases get judged — that's the design intent of "host-agent-is-the-LLM."
+- **Bridge runs on demand, not automatically.** A future enhancement
+  could fire it via a post-promotion hook; the durable lesson lives in
+  build-loop-memory either way, and the bridge is reversible.

package/skills/build-loop/references/independent-auditor.md

@@ -0,0 +1,72 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Independent Commit Auditor
+
+Single source of truth for build-loop commit/build-scope adversarial review. **Consolidated 2026-05-23** — replaces both the retired `commit-auditor` agent (chunk + build scope) and the earlier retired `sonnet-critic`. Operates on two surfaces sharing one context-gathering procedure and one verdict taxonomy:
+
+1. **Boundary-gated hook (every commit).** A PreToolUse Bash hook in `hooks/hooks.json` invokes `scripts/audit_before_commit.py` whenever the Bash tool runs a command matching `git commit`. The orchestrator cannot skip it. Manual user commits, Codex commits, IDE commits, and build-loop commits all pass through it.
+2. **Self-contextualizing.** The script gathers its own context from on-disk `.build-loop/intent.md`, `.build-loop/goal.md`, repo `CLAUDE.md` + `README.md`, the first PRD found (`docs/PRD.md` -> `docs/prd.md` -> `docs/prd/*.md` -> `.build-loop/prd.md`), canonical build-loop-memory constitution context, and the last 5 commit subjects. No upstream packet needed.
+3. **LLM-grade dispatched agent.** The `independent-auditor` agent (`agents/independent-auditor.md`) is dispatched at Phase 3 chunk-close (chunk advisory) and Phase 4 Review-A (build scope). Same context procedure as the hook, plus diff range — emits a structured JSON envelope. Verdict rendered in conversation by the running Claude session.
+
+## Four-verdict taxonomy
+
+- **yay (approve)** — packet aligns with intent + constitution; ship.
+- **nay (reject)** — packet contradicts intent or trips a constitution rule; do not land.
+- **suggest correction** — partial alignment; name file:line edits the implementer should make before re-committing.
+- **look again** — context insufficient to judge; name the missing artifact (PRD section, prior decision, test result) and gather it.
+
+## When the hook fires
+
+Every Bash tool invocation whose command matches `\bgit\s+commit\b`. The hook timeout is 5000ms; the script is fast (no LLM call, no network). It runs at the Bash boundary, so it fires before the commit lands — the running session can short-circuit by not actually committing if the packet shows a contradiction.
+
+## Exit codes
+
+| Code | Meaning | Caller behavior |
+|---|---|---|
+| 0 | Packet emitted, no deterministic block | Commit proceeds; running session renders a verdict in chat |
+| 2 | Deterministic block (secrets file staged, merge-conflict markers in diff) | Caller / hook framework signals the commit should not proceed |
+| 1 | Reserved | — |
+
+Deterministic blocks are zero-judgment hard fails (filenames matching `*.pem` / `id_rsa*` / `id_ed25519*`, `.env*` files with credential-shaped content, or `<<<<<<< HEAD` / `=======` / `>>>>>>>` markers in the staged diff).
+
+## Bypass
+
+Emergency commits can bypass the audit by setting `BUILDLOOP_AUDIT_BYPASS=1` in the environment:
+
+```bash
+BUILDLOOP_AUDIT_BYPASS=1 git commit -m "emergency hotfix"
+```
+
+Each bypass is logged to `~/.build-loop/audit-bypass.log` with timestamp + cwd + reason. Bypasses are valid but visible — Phase 6 Learn can mine the log for chronic-bypass patterns.
+
+## Dispatched-agent surface
+
+For LLM-grade judgment on a specific commit or commit range, dispatch `Agent(subagent_type="build-loop:independent-auditor", ...)`. The agent uses the same context-gathering procedure as the script and renders a structured JSON envelope (with explicit `context_seen` flags and `missing_artifacts[]`). The agent is Sonnet-tier; use it for per-chunk advisory, cross-chunk reviews, and Phase 4 Review-A build-scope critique.
+
+## Dispatch ladder & `auditor_status` — the LLM auditor is never silently skipped (GAP-1)
+
+`Agent(subagent_type=...)` only works from a context that HAS the Agent tool. When the build-loop **orchestrator itself runs as a nested subagent** (dispatched via the Agent tool as `build-loop:build-orchestrator`, or running per-commit mode), the harness blocks sub-subagents — so that orchestrator **cannot** dispatch this agent. The historical defect (2026-06-06 IBR retro): the nested orchestrator silently fell back to inline self-reasoning and reported "independent-auditor ran inline", which rubber-stamped a HIGH cookie-leak + 2 MEDIUM findings that a real dispatch later caught. **Inline self-audit is not the independent auditor.**
+
+There are exactly **three honest ways a real auditor verdict enters `judge_decisions[]`**, and one honest "didn't run" signal:
+
+| `auditor_status` | How the verdict was produced | `judge_id` written |
+|---|---|---|
+| `ran:dispatched-agent` | `Agent(subagent_type="build-loop:independent-auditor")` — Agent tool present (top-level / Mode A) | `independent-auditor` |
+| `ran:peer-host(<host>)` | Auditor run as a peer process (rally channel / `codex exec`) — used when the orchestrator is nested but a peer host is reachable (Bash survives nesting) | `independent-auditor` |
+| (hook) | The PreToolUse boundary hook `scripts/audit_before_commit.py` | `independent-auditor-hook` |
+| `not-run:parent-must-dispatch` / `cross-vendor-deferred` | No Agent tool AND no peer host could execute. **No `independent-auditor`-labeled verdict is written.** | — |
+
+**Never-masquerade rule:** do not write a `judge_id` containing `independent-auditor` for inline orchestrator reasoning. If neither a dispatched agent, a peer-host process, nor the hook produced a verdict, the only honest record is `auditor_status: not-run:parent-must-dispatch` in the orchestrator's return envelope — never a fabricated verdict. A `not-run` run is **not review-complete**: the dispatching parent (which has the Agent tool) owes the audit before Report. Full ladder + parent-dispatch contract in `phase-4-review.md` §"Sub-step A"; the structural backstop is `scripts/write_run_entry` (`review_completeness_error` → exit 3 on a `scope=build` code-touching `pass` that lacks a real auditor verdict).
+
+## How the running session should interpret a packet
+
+When a Bash `git commit` returns with the packet appended to stderr:
+
+1. **Read the packet sections** (Intent, Goal, PRD reference, Trajectory, etc.).
+2. **Pick a verdict** explicitly in your next assistant message — the user (and any audit-trail tooling) needs to see the verdict named, not implied.
+3. **If `yay`**, no further action — the commit is in.
+4. **If `nay` or `suggest correction`**, do not push. State which finding triggered the verdict and either revert (`git reset HEAD~1`) or make the suggested edits and amend.
+5. **If `look again`**, gather the missing artifact (read the PRD section, dispatch the escalation agent, etc.) and re-render the verdict.
+
+The verdict belongs in the running session's transcript so future readers (and Phase 6 Learn) can see what the auditor saw and what the operator did with it.