@tyroneross/build-loop 0.34.0 → 0.36.0

package/.agents/plugins/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "build-loop",
-  "version": "0.33.0",
+  "version": "0.36.0",
   "plugins": [
     {
       "name": "build-loop",

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for build-loop — orchestrated 5-phase development loop with optional Learn phase",
-    "version": "0.34.0"
+    "version": "0.36.0"
   },
   "plugins": [
     {
       "name": "build-loop",
       "source": "./",
-      "description": "Orchestrated 5-phase development loop (Assess → Plan → Execute → Review → Iterate) plus optional Learn phase. Review combines critic, validate, optimize, fact-check, simplify, and report as ordered sub-steps. Bundles native debug-loop, debugging-memory, and logging-tracer skills without a build-loop MCP server. Bridges (debugger-bridge, logging-tracer-bridge) are escalation hops that target skills can use to delegate to the standalone Coding Debugger supporting plugin for extended capability (cross-project memory, additional assessors). NavGator integration via cherry-pick bridge. Opus 4.7 orchestrator, Sonnet execution, Haiku pattern-matching.",
-      "version": "0.34.0",
+      "description": "Orchestrated 5-phase development loop (Assess → Plan → Execute → Review → Iterate) plus optional Learn phase. Review combines critic, validate, optimize, fact-check, simplify, and report as ordered sub-steps. Bundles native debug-loop, debugging-memory, and logging-tracer skills without a build-loop MCP server. The logging-tracer skill includes an optional Coding Debugger escalation hop to delegate to the standalone supporting plugin for extended capability (cross-project memory, additional assessors). NavGator integration via cherry-pick bridge. Opus 4.7 orchestrator, Sonnet execution, Haiku pattern-matching.",
+      "version": "0.36.0",
       "author": {
         "name": "Tyrone Ross"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "build-loop",
-  "version": "0.34.0",
-  "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; logging-tracer-bridge is an optional escalation hop to the standalone Coding Debugger supporting plugin for extended capability.",
+  "version": "0.36.0",
+  "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; the logging-tracer skill includes an optional Coding Debugger escalation hop to the standalone supporting plugin for extended capability.",
   "author": {
     "name": "Tyrone Ross",
     "url": "https://github.com/tyroneross"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "build-loop",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
   "author": {
     "name": "Tyrone Ross",

package/AGENTS.md

@@ -18,31 +18,35 @@ There is NO gate for code size or complexity. Genuine inability to proceed (miss
 
 ## Session-start preflight
 
-Run this once at the start of every session, **before any other action**, to learn the coordination state of this repo (active peers, pending ACKs addressed to you, north-star paths, memory locations, guardrails) and to write a presence record so other tools can see you. Output tells you whether to `proceed_solo` or `join_active` (handle pending ACKs first).
+Run this once at the start of every session, **before any other action**, to learn the coordination state of this repo (active peers, pending ACKs addressed to you, north-star paths, memory locations, guardrails) and to write a presence record so other tools can see you. Rally is coordination metadata, not verification evidence: use it to discover peers, claims, handoffs, and soft file conflicts; confirm code/package/release truth from the repo, tests, manifests, registries, or GitHub directly.
 
 ```bash
-rally codex --human
+rally enter --tool codex --json
+rally next --tool codex --json
+rally room --tool codex --json
 ```
 
-The command is **host-neutral** — the same binary works for every coding tool. Substitute the `--tool` value for your host: `codex`, `cursor`, `gemini`, `claude_code`, or `other`. The JSON form (omit `--human`) is the machine-readable envelope.
+The command surface is **host-neutral** — substitute the `--tool` value for your host: `codex`, `cursor`, `gemini`, `claude_code`, or `other`. If `rally --help` on the local machine disagrees with an older instruction, follow the live CLI help and record the docs drift.
 
 When you know your intent or files at session start, include them so peers can see the work immediately:
 
 ```bash
-rally start codex --intent "<what you are doing>" --path "<file-or-dir>" --json
+rally enter --tool codex --path "<file-or-dir>" --json
+rally say claim --tool codex --subject "<what you are doing>" --path "<file-or-dir>" --json
 ```
 
 When you finish or hand off, close the loop:
 
 ```bash
-rally stop codex --session-id "<session-id>" --reason "done" --json
+rally stop codex --json
 ```
 
-`rally stop` removes live presence, marks the agent stopped, and releases active file claims unless `--keep-claims` is passed.
-Peers read active work from `active_peers[]` and last-known active/stopped session state from `peer_states[]`.
+`rally stop` removes live presence for the selected session/name/tool and releases active claims for cooperative peers. Peers read active work from Rally room state; those records are peer-authored coordination records, never proof that code, tests, releases, or remote refs are correct.
 
 **Fallback:** if `rally` is not on PATH, proceed without preflight — do **not** crash, do **not** block on it. The Phase 1 Rally Point presence write below covers the minimum coordination contract.
 
+**Codex heartbeat parity:** codex sessions emit presence via `session_probe.py --tool codex` (wired in `.codex/hooks.json` `SessionStart`), so their presence/claims/lead decay identically to claude sessions — parity proven by `scripts/rally_point/heartbeat_parity_vectors.json`.
+
 ## Output style
 
 Concise output — say only what the user needs to decide or act; cut narration, restated context, filler; no jargon.
@@ -78,6 +82,21 @@ These run parameters apply on any host — pass them on the invocation (`--flag`
 
 **Budget-aware behavior is host-neutral** — without programmatic budget tracking, treat the budget as a soft wall-clock target: check in at ~50%, finalize before the deadline rather than starting new chunks.
 
+## Codex Execution Adapter
+
+The phase logic in this file is host-neutral, but several primitives it names are Claude-Code-specific. When running under Codex (or any non-Claude host), map each primitive to its Codex equivalent. This closes the functional-parity gap — the workflow runs the same; only the dispatch mechanics differ.
+
+| Claude primitive | Codex equivalent | How |
+|---|---|---|
+| `Agent(subagent_type="<name>", …)` | Codex worker, peer process, inline read, or unavailable-fallback | **Preferred:** spawn a Codex worker per `references/codex-subagents.md` (role mapping + permission gate) using `templates/codex-worker-prompt.md` as the prompt skeleton — only under explicit `--parallel` / delegation authorization. **No authorization:** keep the work in the lead session (inline), still writing the same MECE plan + ownership packet. **Cross-vendor verifier:** a reachable peer host via `codex exec <prompt>` or a rally-channel handoff. **None reachable:** record the role as not-run and have the dispatching parent owe it (see the verifier matrix below). |
+| `Skill("<name>")` | Inline-read the skill | Read that skill's `SKILL.md` and follow it inline. Codex auto-discovers root `skills/*/SKILL.md`; for nested build-loop skills, read the file at its path. There is no Codex "invoke skill" call — the SKILL.md body is the instruction set. |
+| `AskUserQuestion` | Surface to user | Codex has no structured-choice tool. Print the question + 2–4 labeled options inline and wait for the reply; persist the answer as a DECISION record (see Post-Build steering-decision capture). For non-blocking/reversible choices, pick the default, label it `[ASSUMED: <reason>]`, and continue. |
+| `TaskCreate` / `TaskUpdate` / `TaskList` | Backlog files or inline list | Use the host-neutral backlog system (`scripts/backlog.py`, `.build-loop/backlog/`) for durable work items, or a plain inline checklist in the lead session for within-run tracking. Do not block on a task tool that does not exist. |
+| `PushNotification` | Surface to user | Print the notification inline in the session; there is no background push channel under `codex exec`. |
+| `${CLAUDE_PLUGIN_ROOT}` | Repo-relative path or `BUILD_LOOP_ROOT` | Under Codex this variable is unset. Resolve scripts/references relative to the repo root (`root="$(git rev-parse --show-toplevel)"`), or export `BUILD_LOOP_ROOT=<path-to-build-loop>` and substitute it. Every `${CLAUDE_PLUGIN_ROOT}/…` invocation in this file has a working `"$root"/…` or `"$BUILD_LOOP_ROOT"/…` equivalent. |
+
+When a primitive is unavailable and no equivalent applies, do not silently skip the step — record it as not-run and surface it in the end-of-run readback so the dispatching parent (or the user) can complete it.
+
 ## Core Principles
 
 - **KISS + DRY — code and output (governing).** Before adding a rule, gate, schema, script, agent, or report section, first try to (a) delete something, (b) extend something that exists, or (c) do nothing. A new mechanism must earn its place against a *named, observed* failure in this repo — not a cited statistic. Prefer one rule covering many cases over many narrow rules; one source of truth over duplicated logic. For output: say it once in the fewest words that keep the evidence; omit empty sections; headline first. Fewer rules and fewer lines is the default; growth is the justified exception. When this tensions with the principles below, simplify. **Every issue is a systems issue:** when something doesn't work, debugging finishes only when the *system* is updated so the class can't recur (durable guidance/check/simplification/restructure addressing root cause + meta-point, never a surface patch). Default corrective move is to reduce complexity (fewer lines/deps/steps) or, when size is irreducible, better structure (split large files, progressive disclosure) to minimize cognitive load. Scalable means simple over compact — every node (rule, script, agent, step, dep) is a failure site.
@@ -91,7 +110,7 @@ These run parameters apply on any host — pass them on the invocation (`--flag`
 - **No false data.** No mock data in production. No hardcoded metrics pretending to be real. No unverified claims.
 - **Name every UI input and output.** For UI work, every affected surface must have an input/output contract before component choices are locked: data taxonomy, CRUD/domain operation, component mapping, states, modality fallback, validation/security, and traceability.
 - **Diagnose before fixing.** Root-cause analysis before code changes. Many errors sharing a pattern = one system problem.
-- **C-RCA / root_cause_before_done — investigate every open issue to root cause before "done," verified by a second subagent.** Before any completion claim, investigate EVERY open issue — failed tests, loose ends, errors, warnings, minor issues — none left unaddressed. For each, reach the ROOT CAUSE, not a surface patch. Use debugging skills (debug-loop / root-cause-investigator / systematic-debugging) and/or a 5-whys / causal-tree analysis to find the true cause AND its full span (does the same root cause affect other sites? fix all of them). The fix MUST address the root cause — a surface/symptom patch is a violation. The root-cause identification, fix, and non-regression MUST be verified by an independent subagent before "done." Pairs with C-HEAL (reactive self-heal) and the verify-every-subagent rule.
+- **C-RCA / root_cause_before_done — investigate every open issue to root cause before "done," verified by a second subagent.** Before any completion claim, investigate EVERY open issue — failed tests, loose ends, errors, warnings, minor issues — none left unaddressed. For each, reach the ROOT CAUSE, not a surface patch. Use debugging skills (debug-loop / root-cause-investigator / systematic-debugging) and/or a 5-whys / causal-tree analysis to find the true cause AND its full span (does the same root cause affect other sites? fix all of them). The fix MUST address the root cause — a surface/symptom patch is a violation. The root-cause identification, fix, and non-regression MUST be verified by an independent subagent before "done." **Closure test (counterfactual):** not closed at "an actionable control" — closed only when the named lever would have prevented/detected/contained THIS exact failure on the real input (not a hand-constructed one); a control that exists but is dormant on the real signal does not count. **Fix strength:** prefer the strongest feasible control — eliminate → impossible-state → automated-block → detect → contain → decision-support → docs — over the reflex "add a detect-gate"; a dependency you don't own is never "ignore it" (isolate / validate / monitor / degrade / escalate / accept-residual-risk explicitly). Pairs with C-HEAL (reactive self-heal) and the verify-every-subagent rule.
 - **Research persistent problems, don't just retry.** When a fix doesn't hold, the same Iterate criterion fails 2+ times, or behavior contradicts your model, stop guessing and do internet research from trusted sources (T1 official docs and issue trackers first) before another attempt. `root-cause-investigator` carries WebSearch for exactly this. A documented upstream bug or library/terminal behavior often explains an "impossible" intermittent failure faster than another local loop — and prevents shipping a layered workaround over a known root cause. Mark confidence on what you find (✅ T1 cited / ⚠️ inferred).
 - **Hook policy.** Hooks are advisory and non-blocking by default. Stop hooks must emit valid JSON on stdout when they emit anything, must exit 0, and must not stop work for reminders such as dirty worktrees, coordination notes, missing optional telemetry, or cache maintenance. Blocking is reserved for explicit safety/security/integrity gates: destructive actions, secret exposure, protected push/deploy/publish/release gates, or the self-modification safety gate. If a Stop hook needs blocking behavior, it must be behind an explicit opt-in and explain the exact safety boundary.
 - **Converge or escalate.** If iteration isn't improving scores, stop and surface the blocker. Don't burn cycles.
@@ -132,7 +151,9 @@ Run once at the Phase 1 preamble, immediately after `run_id` is known and before
      --workdir "$PWD" --query "<goal-keywords>" \
      --output "$PWD/.build-loop/context-bootstrap.json" --json
    ```
-   The packet covers: canonical `build-loop-memory` root/project `MEMORY.md` + `constitution.md`, indexed recall via `memory_facade.py`, repo-local `.build-loop/{feedback,state,goal,intent,plan}` files, Codex memory registry `~/.codex/memories/MEMORY.md` plus linked rollout summaries, best-effort Rally/coordination state, **queue counts + top items** (`queues.{issues,backlog,ux-queue,followup,proposals}.{count,top[]}`), **progressive lessons** (`lessons_progressive[]` — SQLite FTS5, scoped to current work, zero external deps; degrades gracefully when DB absent), and `session_prefs`.
+   The packet covers: canonical `build-loop-memory` root/project `MEMORY.md` + `constitution.md`, indexed recall via `memory_facade.py`, repo-local `.build-loop/{feedback,state,goal,intent,plan}` files, Codex memory registry `~/.codex/memories/MEMORY.md` plus linked rollout summaries, best-effort Rally/coordination state, **queue counts + top items** (`queues.{issues,backlog,ux-queue,followup,proposals}.{count,top[]}`), a **backlog summary** (`backlog.{open_p01,stale,gated}` from `.build-loop/backlog/INDEX.md` when present), **progressive lessons** (`lessons_progressive[]` — SQLite FTS5, scoped to current work, zero external deps; degrades gracefully when DB absent), and `session_prefs`.
+
+   **Backlog system (host-neutral, any agent).** Deferred-but-wanted work lives in `<repo>/.build-loop/backlog/` as plain Markdown+YAML items (`items/<ID>.md`, canonical truth) with a regenerated `INDEX.md` (derived view). Read it with `cat <repo>/BACKLOG.md` → `INDEX.md` → `grep` over `items/*.md`; write it with `python3 ${RUNTIME_PLUGIN_ROOT}/scripts/backlog.py {new,sync,list} --repo <path>` (pure stdlib — runs under bare `python3`, no host SDK). `sync` regenerates INDEX deterministically, archives done/dropped (never deletes), flags past-`review_by` items, and mirrors active items one-way into the user's personal memory (`build-loop-memory/projects/<slug>/backlog/`) for a cross-repo view. Full convention, schema, and lifecycle: `references/backlog-system.md`.
 3. **Surface + ask once** (immediately after reading the packet):
    - Read `packet.agent_brief` for the one-liner summary, then check each queue: if any `queues.*.count > 0`, emit `#issues=N #backlog=M …` plus the top item titles from `queues.*.top[0].title`.
    - Surface `lessons_progressive[].name` (up to 3) as ambient context so planning reflects recent learnings.
@@ -161,11 +182,13 @@ Multiple build-loop sessions can run concurrently against the same project acros
 
 1. **Write presence and intent at the Phase 1 preamble** (immediately after `run_id` is known), and refresh it at each phase-start. Preferred Rust path:
    ```bash
-   rally start codex --session-id "<sid>" --intent "phase=assess" --json
+   rally enter --tool codex --json
+   rally say presence --tool codex --subject "phase=assess" --json
    ```
    When files are owned, include one `--path` per file or directory so Rally creates explicit file claims:
    ```bash
-   rally start codex --session-id "<sid>" --intent "phase=execute" --path "src/app.ts" --json
+   rally enter --tool codex --path "src/app.ts" --json
+   rally say claim --tool codex --subject "phase=execute" --path "src/app.ts" --json
    ```
    Embedded fallback path when the Rust `rally` binary is unavailable:
    ```python
@@ -179,7 +202,7 @@ Multiple build-loop sessions can run concurrently against the same project acros
        model="<model>", run_id="$RUN_ID", app_slug=slug,
        phase="assess", files_in_flight=[])
    ```
-   `tool` values: `claude_code | codex | gemini | other`. Resolve the channel through `discovery_bridge.resolve(...)` before every direct write. Rust-backed channels use `rally start` / `rally stop`; embedded fallback writes one file per live session at `<resolved-channel>/sessions/<session-id>.json` (session_id, tool, model, run_id, app_slug, phase, files_in_flight, heartbeat_ts, read cursor). Fire-and-forget — never raises, never blocks.
+   `tool` values: `claude_code | codex | gemini | other`. Resolve the channel through `discovery_bridge.resolve(...)` before every direct write. Rust-backed channels use `rally enter` / `rally stop`; embedded fallback writes one file per live session at `<resolved-channel>/sessions/<session-id>.json` (session_id, tool, model, run_id, app_slug, phase, files_in_flight, heartbeat_ts, read cursor). Fire-and-forget — never raises, never blocks.
 2. **Read active peers** at the preamble and each phase-start:
    ```python
    peers = presence.read_active_presence(channel, exclude_session="<sid>")
@@ -189,7 +212,7 @@ Multiple build-loop sessions can run concurrently against the same project acros
    - No peers / no `files_in_flight` overlap → log one line per peer (tool, run_id, phase); proceed.
    - Overlap with a peer's `files_in_flight` → surface a `soft-claim` **WARNING** (peer, overlapping files, peer phase); proceed with awareness. Interactive hosts MAY additionally ask the user to coordinate; headless hosts (Codex / cron) log + proceed. There is no SAFE-STOP sentinel and no non-zero exit.
 4. **Refresh presence** at every phase-start and whenever the phase's owned files change — re-call `write_presence` with the new `phase` + `files_in_flight` (the per-session read cursor is preserved across refreshes).
-5. **Stop explicitly.** On Rust-backed channels, run `rally stop <tool> --session-id <sid> --reason "<done|handoff|blocked>" --json` when the session ends or file ownership changes materially. This clears presence, marks the session stopped in `peer_states[]`, and releases active claims. Embedded fallback still self-heals with `reap_stale` when a host exits without unregistering.
+5. **Stop explicitly.** On Rust-backed channels, run `rally stop <session|name|tool> --json` when the session ends or file ownership changes materially. This clears presence for the selected session/name/tool and releases active claims. Embedded fallback still self-heals with `reap_stale` when a host exits without unregistering.
 6. **Memory writes (M5 — separate concern)** — use `scripts/memory_writer.py write` instead of writing memory files directly. The writer adds provenance frontmatter (source_repo, source_workdir, source_run_id, source_host, cross_repo_validated, applied_in_repos, created_at, last_updated_at), then atomically appends a row to `INDEX.jsonl` for sibling discovery:
    ```
    python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py write \
@@ -197,6 +220,13 @@ Multiple build-loop sessions can run concurrently against the same project acros
      --type feedback --run-id "$RUN_ID" --workdir "$PWD" --host codex \
      --body-file /tmp/memory-body.md
    ```
+   Codex-specific guard: `apply_patch` has no shell `workdir`; relative patch
+   paths target the active workspace. For direct cross-repo memory repairs, use
+   absolute `apply_patch` paths, or write through `memory_writer.py`. If a file
+   was already exposed as a Codex file card and then moved to canonical memory,
+   leave an openable pointer, mirror, or stub at the old path and update any
+   dependent indexes/links so Finder and Codex file cards do not point at a
+   missing path.
 7. **Memory reads (cross-session discovery)** — between phases, tail the index for new peer learnings:
    ```
    python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_index.py tail \
@@ -261,7 +291,7 @@ Full provider substitution table (Thinking / Code / Pattern → each host's mode
 - Break work into tasks with exact file paths
 - Identify dependency order — what must complete before what?
 - Flag parallel-safe groups: files that don't import each other can be written simultaneously
-- Partition files and agents MECE: every changed file has exactly one owner, every required responsibility has an owner, and each group declares `owns`, `does not own`, `interface contract`, and `integration checkpoint`
+- Partition files and agents MECE: every changed file has exactly one owner, every required responsibility has an owner, and each group declares all seven ownership fields — `owns`, `does not own`, `interface contract`, `integration checkpoint`, `allowed tools`, `denied tools`, and `acceptance criteria` (the testable conditions the returning envelope must satisfy — the verifier's per-chunk oracle)
 - Define checkpoints where work should be verified before continuing
 - Optimize: remove unnecessary steps, combine related changes, eliminate redundant work
 - **Two-lens approach gate**: for non-trivial architecture, workflow, dependency, UI/product, or long-lived interface decisions, add a `## Approach Lenses` section before implementation tasks. It must include:
@@ -308,7 +338,7 @@ Wire all three surfaces (`skills/build-loop/SKILL.md`, `agents/build-orchestrato
 ### Phase 3: Execute
 
 - Dispatch parallel work for independent file groups
-- Each worker gets minimal context + integration contract (what interfaces to implement) + an intent packet explaining how the subtask fits the north star + a MECE ownership packet defining owned files, non-owned files, interface contracts, and integration checkpoints
+- Each worker gets minimal context + integration contract (what interfaces to implement) + an intent packet explaining how the subtask fits the north star + a MECE ownership packet defining all seven fields: owned files, non-owned files, interface contracts, integration checkpoints, allowed tools, denied tools, and acceptance criteria (the testable conditions the returning envelope must satisfy — the verifier's per-chunk oracle)
 - If the host supports typed subagents, map read-only codebase questions to explorer-style agents and disjoint implementation slices to worker-style agents. If the host requires explicit user authorization for subagents, identify parallel-safe groups but execute locally unless the user asked for delegation, parallelization, workers, or a `--parallel` mode.
 - **Single-entry routing (host-neutral):** every coding task enters through one build-loop invocation; the runtime auto-classifies intent (build / optimize / research / debug / test) and routes accordingly. The host does not pick a mode — classification is internal. This applies equally across coding hosts (Claude Code, Codex, Cursor, Gemini CLI, others).
 - **Subagent scaling (host-neutral):** when the host supports parallel delegation (e.g. Codex with `--parallel` authorization), dispatch up to `scripts/parallelism.py effective_max_implementers()` workers — machine-aware cap, default 8, ceiling 12 — decomposing work into the maximum number of independent MECE chunks. The permission gate still applies: workers only on explicit `--parallel` / delegation authorization. When parallel delegation is unavailable, execute sequentially without asking.
@@ -342,6 +372,18 @@ The `synthesis_attestation` map MUST have one entry per dimension named in the p
 
 Seven ordered sub-steps; intermediate failures route to Iterate, final pass writes Report artifacts.
 
+**Verifier contract matrix (Codex parity).** Each review verifier has a required output shape, a routing effect, and a rule for whether inline Codex execution is valid. Mirror `skills/build-loop/references/codex-subagents.md` (role mapping) and `skills/build-loop/references/phase-4-review.md`.
+
+| Verifier | When | Required output | Routing effect | Inline Codex valid? |
+|---|---|---|---|---|
+| **Critic (independent-auditor)** | every non-trivial build (Sub-step A) | JSON envelope: `verdict ∈ {yay, nay, suggest_correction, look_again}` + `findings[]` (`severity: critical\|high\|medium\|low`) | `nay`/critical+high route to Iterate; advisory at chunk close, gating at build scope | **Inline self-review is NEVER recorded as `independent-auditor`** (per `skills/build-loop/references/phase-4-review.md` §20). A lead session inline-reasoning IS valid review work, but it must NOT be written to `judge-decisions.json` with `judge_id: independent-auditor`, and a `scope=build` code-touching run must report `outcome: partial` (not `pass`) when no real dispatched/peer auditor ran. Record `auditor_status` honestly: `ran:dispatched-agent` / `ran:peer-host(<host>)` / `not-run:parent-must-dispatch`. |
+| **Validate (graders)** | every build (Sub-step B) | scorecard rows: criterion · method · PASS/FAIL · evidence | any FAIL routes to Iterate | Yes — code-based graders (test/lint/type/build) run inline in the lead session. UI validation must use a real visual/AX surface, never symbol-only checks. |
+| **Fact-Check** | every build (Sub-step D) | per-claim trace: metric → source, or `unverifiable` | unverifiable rendered number is **blocking** → Iterate | Yes — runs inline; it is a read-and-trace pass, no dedicated agent required. |
+| **Mock-Scanner** | every build (Sub-step D) | findings: path · pattern · `blocking\|warning` | blocking (renders to user) → Iterate | Yes — inline grep/scan of production paths. |
+| **Security-Reviewer** | only when Assess flagged a risk-surface change (Sub-step A) | findings vs OWASP LLM/Agentic/Web top-10, severity-tagged | critical/high feed the no-critical/high exit gate (blocking) | Yes inline, OR a cross-vendor peer when `cross_vendor_required` and a peer host is reachable; if neither, record `cross_vendor: untested` — never claim it ran. |
+
+**The inline-self-review rule is the load-bearing one:** a solicited inline pass agreeing with the lead is not independent validation. Dispatch a real auditor (Agent tool), run it as a peer process (`codex exec` / rally handoff), or mark the run `not-run:parent-must-dispatch` so the parent that *does* have the dispatch capability completes the audit before Report finalizes.
+
 **Sub-step A — Critic (adversarial read-only)**: perform a read-only adversarial review of the diff — inline in the lead session, or via an authorized explorer when delegation is permitted. This is the independent-auditor pass: render one of four verdicts (`yay` approve / `nay` reject / `suggest_correction` / `look_again`) gathering context from intent, goal, PRD, constitution. Catch scope drift, missed edge cases, rubric violations before spending tokens on full validation. **When Assess flagged a risk-surface change** (new auth, network, persistence, secrets, or external-input surface), also run a security review in this sub-step against OWASP LLM/Agentic/Web top-10 — its critical/high findings feed the no-critical/high exit gate and are blocking. Strong-checkpoint findings route back to Execute (no iteration burn); guidance findings are logged.
 
 **Sub-step A.5 — Synthesis-decision backstops (post-implementer-commit, runs before B):**
@@ -454,7 +496,9 @@ Build loop stores state in `.build-loop/` within the project directory:
 ├── followup/            # Overflow when iteration cap hit; input to subsequent build
 │   └── <topic>.md
 ├── backlog/             # Deferred-but-wanted work (drained by end-of-run continuation)
-│   └── <id>.md          # frontmatter: title, created, classify, effort, status
+│   ├── INDEX.md         # DERIVED view — regenerated by `scripts/backlog.py sync`; do not hand-edit
+│   ├── items/<ID>.md    # CANONICAL items — host-neutral MD+YAML (id/status/priority/type/area/gated/provenance/evidence/review_by)
+│   └── archive/<ID>.md  # done/dropped items (never deleted)
 ├── evals/               # Scorecard archives
 │   └── YYYY-MM-DD-*.md
 └── issues/              # Discovered issues (drained by end-of-run continuation)
@@ -490,11 +534,20 @@ When a run created zero refs: `Branch hygiene: clean — no run-created branches
 
 **Structural run-close (Stop hook).** Phase D above is the orchestrator path. An INLINE run (skill-as-methodology, no orchestrator dispatch) never reaches it, so a host `Stop` hook fires the minimum structural closeout with no human prompt — `hooks/closeout.sh stop` → `scripts/stop_closeout.py`:
 
-1. **Record + surface.** Records the run via `append_run.py` (so Phase 6 Learn's `runs[]` sees it) and runs `judgment_gate.py --agent-tool-available false`, surfacing a WARN `systemMessage` when a stakes-gated run skipped the Frontier judgment layer. A Stop hook cannot dispatch agents, so it auto-records + auto-surfaces the gap — it does not run the retrospective-synthesizer or memory closeout; it leaves `.build-loop/closeout-pending/<run-id>.md` for the next SessionStart (`hooks/closeout.sh session-start`) to surface once.
+1. **Record + surface.** Records the run via `append_run.py` (so Phase 6 Learn's `runs[]` sees it) and runs `judgment_gate.py --agent-tool-available false`, surfacing a WARN `systemMessage` when a stakes-gated run skipped the Frontier judgment layer. A Stop hook cannot dispatch agents, so it auto-records + auto-surfaces the gap — it does not run the retrospective-synthesizer or memory closeout; it leaves `.build-loop/closeout-pending/<run-id>.md` for the next SessionStart (`hooks/closeout.sh session-start`) to surface once. A terminal (`pass`) record also releases the run identity — the `execution` block is archived to `historicalExecutions` and cleared — so the next inline effort mints a fresh `build_loop_id` instead of silently resuming a finished run (partial/blocked outcomes keep identity for crash-resume).
 
 2. **Contract.** Advisory + fail-open (always exit 0, never `decision: block`), self-gated on `.build-loop/` presence + this-session match (`current_session_id`, heartbeat-freshness fallback when the host passes no session id), minimal-PATH safe, idempotent with Phase D — the marker is the inline-path sentinel and `runs[]` membership is the Phase-D sentinel, so neither double-records the other. Tests: `scripts/test_stop_closeout.py` + `hooks/test_closeout.sh`.
 
-3. **Codex wiring.** Both hosts ship in-repo: Claude via `hooks/hooks.json`, Codex via the tracked `.codex/hooks.json` — `Stop` and `SessionStart` entries call the same shim (`root="$(git rev-parse --show-toplevel)"; bash "$root/hooks/closeout.sh" stop`).
+3. **Codex wiring.** Both hosts ship in-repo: Claude via `hooks/hooks.json`, Codex via the tracked `.codex/hooks.json` — `Stop` and `SessionStart` entries call the same shim (`root="$(git rev-parse --show-toplevel)"; bash "$root/hooks/closeout.sh" stop`). ⚠ VERIFIED DORMANT under `codex exec` 0.139.0 (live probe 2026-06-12, `--dangerously-bypass-hook-trust`): codex fired global/built-in hooks but never the repo-level file. Until codex honors repo-level hooks, the working Codex path is the global `~/.codex/hooks.json` (the shim self-gates on `.build-loop/`, so a global install is safe — but global installs are user-opt-in, not shipped).
+
+**Codex closeout + run-recording fallbacks (do these MANUALLY when hooks do not fire).** Because repo-level Codex hooks are dormant under `codex exec` (verified above), the `Stop`/`SessionStart` shim that auto-records a run does NOT run on its own in a Codex session. Unless the global `~/.codex/hooks.json` is installed AND confirmed firing, a Codex run must perform these steps by hand before declaring the run done (resolve `${RUNTIME_PLUGIN_ROOT}` to the build-loop repo root — see the Codex Execution Adapter):
+
+1. **Append the run record** — `python3 "$root"/scripts/append_run.py …` so Phase 6 Learn's `runs[]` sees this run. Without it, the run is invisible to the recurring-pattern detector and the milestone log.
+2. **Run the judgment gate** — `python3 "$root"/scripts/judgment_gate.py --workdir "$PWD" --run-id <run-id> --agent-tool-available false --json`. On a stakes-gated run that stayed at the inline floor, it surfaces the skipped-Frontier-judgment WARN that the Stop hook would otherwise have surfaced.
+3. **Write the closeout status** — record `state.json.runs[N].closeout_status` (and the inline-path marker `.build-loop/closeout-pending/<run-id>.md` if a follow-up surface is needed), matching what `stop_closeout.py` would have written.
+4. **Phase 6 Learn recording** — run the cheap detector + consolidation and emit the `## Learn` outcome line (accruing / deferred / full) explicitly; it does not auto-fire without the hook.
+
+These are idempotent with the hook path (the marker is the inline sentinel; `runs[]` membership is the Phase-D sentinel), so a later host that DOES fire the hook will not double-record. The rule: **never let "the hook will catch it" stand in for run recording under Codex** — confirm the hook fired, or do the four steps by hand.
 
 ## Post-Build