@tyroneross/build-loop 0.36.0 → 0.43.0

package/.agents/plugins/marketplace.json

@@ -1,10 +1,10 @@
 {
   "name": "build-loop",
-  "version": "0.36.0",
+  "version": "0.43.0",
   "plugins": [
     {
       "name": "build-loop",
-      "source": "./plugin-artifacts/codex"
+      "source": "."
     }
   ]
 }

package/.claude-plugin/marketplace.json

@@ -6,14 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for build-loop — orchestrated 5-phase development loop with optional Learn phase",
-    "version": "0.36.0"
+    "version": "0.43.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. 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"
       },
@@ -32,7 +31,8 @@
         "code-quality",
         "self-improvement",
         "prompt-engineering"
-      ]
+      ],
+      "version": "0.43.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "build-loop",
-  "version": "0.36.0",
+  "version": "0.43.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",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "build-loop",
-  "version": "0.36.0",
+  "version": "0.43.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/.cursor/rules/build-loop-surface.mdc

@@ -1,5 +1,5 @@
 ---
-description: Keep Build Loop routing focused on public entrypoints and treat helper skills as internal implementation details.
+description: Build Loop exposes one human-facing entry; every skill under skills/ is internal implementation.
 globs:
   - "**/*"
 alwaysApply: true
@@ -7,16 +7,17 @@ alwaysApply: true
 
 # Build Loop Surface
 
-Use these public Build Loop entrypoints first:
+Build Loop has exactly one human-facing entry: `/build-loop:run`. Describe the
+work in plain language — build, fix, debug, optimize, research, test, plan — and
+the orchestrator routes it internally. There are no mode flags and no second
+command to choose between.
 
-- `build-loop` for multi-step code work
-- `debug-loop` for root-cause debugging
-- `optimize` for measurable optimization
-- `research` for pre-build investigation
-- `knowledge` for durable decisions and lessons
+Every skill under `skills/` sets `user-invocable: false`. A skill becomes public
+only by declaring `public-justification:` in its own frontmatter; today none do.
 
-Treat `skills/` as Build Loop's internal implementation tree. Do not load
-helper skills directly unless a public entrypoint, command file, or orchestrator
-instruction explicitly references that helper.
+Treat `skills/` as Build Loop's internal implementation tree. Do not load a
+helper skill directly unless `/build-loop:run`, a command file, or an
+orchestrator instruction explicitly references that helper.
 
-For the full policy, read `docs/agent-surface-policy.md`.
+For the full policy, read `docs/agent-surface-policy.md`. It and this file are
+enforced against the code by `scripts/test_agent_surface_policy.py`.

package/.cursor/rules/skill-index.mdc

@@ -0,0 +1,33 @@
+---
+description: Route requests to the right Build Loop skill using the generated skill index at docs/SKILL-INDEX.md.
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# Skill Index
+
+`docs/SKILL-INDEX.md` is the routing table for every skill in this repo. Each row
+names a skill, says when to use it, how it is reached, and whether it is
+user-facing. Read that file to pick the skill that owns a request; read the
+linked `SKILL.md` for the procedure.
+
+That file is the only skill list. This rule deliberately does not repeat it —
+three copies of the same list in `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/`
+would be three places to drift.
+
+The index is generated from `skills/**/SKILL.md` frontmatter, so a newly
+authored skill is indexed by regenerating, not by editing the table:
+
+```bash
+python3 scripts/skill_index.py --workdir . --apply   # regenerate
+python3 scripts/skill_index.py --workdir . --check   # exit 1 when stale
+```
+
+Never hand-edit `docs/SKILL-INDEX.md`. To change a row, edit that skill's
+`SKILL.md` `description:` and regenerate. `--check` is the drift guard; a
+non-zero exit means run `--apply`.
+
+Companion rule: `.cursor/rules/build-loop-surface.mdc` covers which skills are
+reachable by a human (today: only `/build-loop:run`). This rule covers where to
+look them up.

package/AGENTS.md

@@ -16,43 +16,102 @@ Action classification: SAFE → execute on main; RISKY → isolate to branch + l
 
 There is NO gate for code size or complexity. Genuine inability to proceed (missing credential, external blocker) is logged, worked around with available tasks, and reported in the readback — not a stop-and-ask. Oversight is the end-of-run readback, not a mid-run halt.
 
+## Privileged commands — always go through the broker
+
+**Never run a command that asks macOS for an administrator password directly.** Route it through the broker so the request is named before the dialog appears, shares one authorization with any identical read-only request already in flight, and lands in a durable record:
+
+```bash
+python3 <build-loop>/scripts/privileged_broker.py classify --command "<your command>" --json   # is anything privileged?
+python3 <build-loop>/scripts/privileged_broker.py request \
+  --purpose "<one plain sentence: why this is needed>" \
+  --task-id "$RUN_ID" --repo "$PWD" --initiating-app codex \
+  --argv <executable> <args...>
+```
+
+`--purpose` is mandatory; a request without one is refused. That sentence is what the user reads next to the password dialog, which today names only the binary.
+
+Exit codes: `0` completed · `1` denied/cancelled/timeout/failed · `2` refused by the broker.
+
+**On a `1`, do not retry.** A denial, cancellation, or timeout is cached and replayed, so an immediate retry cannot produce a different answer — it can only produce another dialog. This is the exact 2026-08-20 failure: one Codex turn ran `sfltool dumpbtm` twice, 14 seconds apart, because a refused read returned empty output that was indistinguishable from "no matches". Report the denial and continue with the rest of the work.
+
+Claude Code enforces this through a PreToolUse hook. Codex and other hosts follow it as protocol. Full contract, registry format, and risk-class behaviour when the coordinator is unavailable: `skills/build-loop/references/privileged-request-broker.md`.
+
 ## 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. 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 enter --tool codex --json
-rally next --tool codex --json
-rally room --tool codex --json
+# Rally takes an exclusive lock on .rally/direct.owner.lock for EVERY command,
+# including the read-only ones. Under a read-only sandbox (`codex exec --sandbox
+# read-only`, a hardened CI runner) that open fails EPERM and all three commands
+# below emit a JSON error. Coordination is optional, so check first and skip
+# cleanly rather than opening a session with three failures in the log.
+_rally_writable() {
+  local root="$PWD" d="$PWD/.rally"
+  if [ -d "$d" ]; then [ -w "$d" ] || return 1
+  else [ -w "$root" ] || return 1; mkdir -p "$d" 2>/dev/null || return 1
+  fi
+  ( : > "$d/.writetest.$$" ) 2>/dev/null || return 1   # mode bits lie under seatbelt; prove it
+  rm -f "$d/.writetest.$$" 2>/dev/null
+}
+
+if _rally_writable; then
+  BASE_TOOL="${BUILD_LOOP_RALLY_TOOL:-codex}"  # set to this host family
+  RALLY_SESSION_ID="$(python3 scripts/rally_point/actor_identity.py --tool "$BASE_TOOL" --field session-id)"
+  export RALLY_SESSION_ID
+  RALLY_TOOL="$(python3 scripts/rally_point/actor_identity.py --tool "$BASE_TOOL" --session-id "$RALLY_SESSION_ID")"
+  rally enter --tool "$RALLY_TOOL" --session-id "$RALLY_SESSION_ID" --json
+  rally next --tool "$RALLY_TOOL" --json
+  rally room --tool "$RALLY_TOOL" --json
+else
+  echo "[build-loop] rally preflight skipped: .rally is not writable (read-only sandbox)." >&2
+  echo "[build-loop] You have NO peer/claim visibility this session. Treat every file as possibly claimed by a peer, and do not assume you are alone." >&2
+fi
 ```
 
-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.
+The command surface is **host-neutral**. Set `BASE_TOOL` to the host family (`codex`, `cursor`, `gemini`, `claude_code`, or `other`); `RALLY_TOOL` is the session-qualified native actor. Never use the bare family as a native Rally actor because two same-host sessions would collapse into one squad, claim owner, and reader cursor. Build Loop's local fallback deliberately keeps the base tool plus its separate session id. 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 enter --tool codex --path "<file-or-dir>" --json
-rally say claim --tool codex --subject "<what you are doing>" --path "<file-or-dir>" --json
+rally enter --tool "$RALLY_TOOL" --session-id "$RALLY_SESSION_ID" --path "<file-or-dir>" --json
+rally say claim --tool "$RALLY_TOOL" --subject "<what you are doing>" --path "<file-or-dir>" --json
 ```
 
 When you finish or hand off, close the loop:
 
 ```bash
-rally stop codex --json
+python3 scripts/agent_rally.py stop --workdir "$PWD" \
+  --tool "$BASE_TOOL" --session-id "$RALLY_SESSION_ID" --json
 ```
 
-`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.
+`agent_rally.py stop` removes live presence for the exact session actor and releases only that session's active claims. 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`.
 
+## Skill index — how to find the right skill
+
+`docs/SKILL-INDEX.md` is the routing table for every skill in this repo: one row per skill giving its id, when to use it, how an agent reaches it, and whether it is user-facing. Read that file when you need to decide which skill owns a request. It is plain markdown with no host-specific syntax, so Codex, Claude Code, Cursor, and any other agent get the same answer from the same file.
+
+The index is **generated** from `skills/**/SKILL.md` frontmatter, never hand-maintained — a hand-kept list would be a second source of truth and would drift from the skills it describes. Authoring a skill is therefore enough to get it indexed; regenerate and the row appears.
+
+```bash
+python3 scripts/skill_index.py --workdir . --apply   # regenerate after adding or editing a skill
+python3 scripts/skill_index.py --workdir . --check   # exit 1 when the index is stale
+```
+
+`--check` is the drift guard: run it before declaring any skill work done, and treat a non-zero exit as "run `--apply`", not as a reason to edit the index. To change a row, edit that skill's `SKILL.md` description. The script scans any plugin root via `--workdir`, so sibling plugins reuse it with no new code.
+
 ## Output style
 
 Concise output — say only what the user needs to decide or act; cut narration, restated context, filler; no jargon.
 
 Lead each point with the finding. Progressive disclosure: headline first, files/detail below. Number points as standalone **bold-number** paragraphs with a blank line between (plain `1.` list syntax renders compressed). Never use the contrastive-pivot construction ("not X — it's Y", "isn't X, it's Y", "not just X but Y"); state the point directly. Style only, never a gate.
 
+Direct language — clear verb, clear outcome (the leverage stack): fix clarity top-down — message logic (lead with the answer to the question actually asked; `suggesting` when evidence implies a cause, `because` only when proven), then sentence emphasis (match the opening to the job: actor / outcome / cause / metric / contrast-first; default spine `[Actor] [strong verb] [specific outcome] because [specific cause]`), then word spine (strong verb over weak-verb-plus-filler `was responsible for`→`caused`; data over adverbs `significantly increased`→`increased 42%`; concrete nouns over vague). Enforced by `report_lint.py` (weak-verb / filler-opener / hedge); full tables in `skills/build-loop/references/output-style.md`. Block-level shape for findings and status — the cold-read test (actor / specific object / modality) — is `skills/build-loop/references/status-output-format.md`.
+
 ## Phases
 
 | # | Phase | Purpose | Output |
@@ -76,7 +135,7 @@ These run parameters apply on any host — pass them on the invocation (`--flag`
 | `--autonomous=false` | Classic single pass — run Phases 1–6 once; queue items become `followup/` instead of being drained. |
 | `--resume <run-id \| latest>` | Re-enter a crashed/killed build mid-flight. Reuses the original `deadline_at` (a 2h budget that died at 1h59m does NOT get a fresh 2h — `resume_resolver.py` owns this). Reads existing `intent.md`/`plan.md`; jumps to remaining chunks. On a normal dispatch with an incomplete prior run detected, offer resume vs fresh before Phase 1. |
 
-**Iteration caps:** classic = 5 per build; autonomous = 25 per build (3 same-verdict per item). Stop conditions: cap reached, budget exhausted, a drained item classifying `confirm`/`block`, 5 consecutive same-criterion failures, or an item whose intent anchor no longer resolves.
+**Iteration caps:** classic = 5 per build; autonomous = 25 per build. For one unresolved item, the third identical verdict requires an independent audit before another attempt; the fifth quarantines the item with evidence. A resolved issue resets the counter. Stop conditions: cap reached, budget exhausted, a drained item classifying `confirm`/`block`, 5 consecutive same-criterion failures, or an item whose intent anchor no longer resolves.
 
 **Per-commit mode** (self-recursive builds — when the working dir IS the runtime, e.g. editing build-loop itself): plan once, then run one orchestrator pass per commit so each commit reviews and lands cleanly before the next starts. Auto-on for self-recursive; force with `--per-commit` / `--no-per-commit`.
 
@@ -88,11 +147,16 @@ The phase logic in this file is host-neutral, but several primitives it names ar
 
 | 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). |
+| `Agent(subagent_type="<name>", …)` | Native `spawn_agent`, 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). **Isolation caveat (verified 2026-08-22, codex-cli 0.149.0):** native `spawn_agent` SHARES the working directory and has no worktree flag, so it does not satisfy the concurrent-dispatch isolation rule on its own — provision explicitly with `git worktree add <path> -b <branch>` then `codex -C <path>`. |
 | `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. |
+| `AskUserQuestion` | `request_user_input` (Plan mode), else surface to user | Codex DOES have a structured-choice tool, `request_user_input`, available in Plan mode (verified 2026-08-22, codex-cli 0.149.0 — this row previously claimed it did not). Outside Plan mode: 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` | `update_plan` (ephemeral) + backlog files (durable) | 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. Codex's native `update_plan` covers within-run plan state; it is ephemeral, so durable work still belongs in `.build-loop/backlog/`. 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`. |
+| `ScheduleWakeup` / the `/loop` command | `coordination_watch.py --interval N`, or a launchd/systemd timer | Both are Claude-Code-only (`/loop` is bundled in the Claude binary and has no on-disk surface, so there is nothing to invoke elsewhere). **Never hand-pick a wait primitive.** Ask the resolver and execute what it returns: `python3 "$root"/scripts/wake_scheduler.py --tool codex --wait-kind tracked_subwork\|external\|peer_ack --desired-seconds N --json`. It returns a `decision` (`stop_surface_human` / `harness_auto` / `self_wake`) plus the `directive` and `delay_seconds` for THIS host — Claude Code gets `ScheduleWakeup`, every other host gets the poll watcher or an OS timer. Codex has NO native scheduler (verified 2026-08-22): `codex resume <session-id>` and `codex queue --thread <id> --message <text>` are manual re-entry, not a timer. A `stop_surface_human` decision means the pending action is irreversible; surface it rather than resuming. |
+| `WebSearch` | Native `web_search` | Enable with `codex --search` (interactive). **`codex exec --help` does not list `--search`**, so a non-interactive worker may have no search at all — check before relying on it, and when it is absent record the query you WOULD have run rather than answering from memory (`agents/root-cause-investigator.md` already specifies that fallback). |
+| `WebFetch` | Native `web__run({open:…})`, else `curl` | Available in the Codex runtime when web tooling is enabled; `curl` is the universal floor. Same rule as Claude: fetch only user-provided URLs or links returned by a search. |
+| `EnterWorktree` / `ExitWorktree` | Plain git | `git worktree add <path> -b <branch>` then `codex -C <path>`; remove with `git worktree remove`. There is no built-in — see the isolation caveat on the `Agent` row above. |
+| Finding callers of a symbol — `code-intel refs` on BOTH hosts (**not** Claude's built-in `LSP` tool) | `code-intel refs` CLI, else `mcp__code_intel__refs`, else grep | Same tool both sides. **Prefer the `code-intel` CLI on PATH** (`code-intel refs <file>:<line>:<col>`) — it needs no MCP registration and no tool approval, so it survives `--ask-for-approval never`. The `mcp__code_intel__refs` MCP form (check `codex mcp list`) is equivalent but approval-gated and DENIED under that flag; fall back to grep only when neither is reachable. Claude's built-in `LSP` tool is **not** a substitute: it sees only servers a host plugin registered and returns confident, incomplete answers on every other language with no error (observed 2026-08-29: 1 hit vs code-intel's 4 on the same TypeScript symbol). Record which method you used and honor the `ready` semantics in `agents/scope-auditor.md`. |
 | `${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.
@@ -117,6 +181,7 @@ When a primitive is unavailable and no equivalent applies, do not silently skip
 - **Keep going until done.** Once the user accepts the plan, every phase is authorized scope. Do not ask the user to confirm each phase. Issues found mid-build route to Iterate. Status updates are fine; permission requests are not. Completed, validated, authorized work commits automatically — asking "should I commit?" or "want me to commit this?" is a workflow violation. `git commit` is classified `auto` by the autonomy gate (exit 0); it is never a permission-gated action. The only commit-adjacent stops are autonomy-gate `confirm`/`block` verdicts on a *push or deploy* command. The only valid stops are: a destructive action not in the plan, a missing credential, externally-blocked work, an explicit hand-off point in the plan, a genuine scope branch the plan does not resolve, or 8 hours wall-clock without a Review pass / 5 consecutive Iterate failures on the same criterion. **NOT stops:** posting a coordination handoff to a peer is *fire-and-continue* (work your owned lane in parallel; only a verifier verdict gating the *next* step is a wait); output volume / turn length is never a stop; "continue or hold?" on authorized, lane-isolated, determinate remaining work is a manufactured fork — finish it. A multi-step prune/refactor/migration with a defined item list runs to completion across that list.
 - **Commit authorship stays human.** When build-loop manages a commit or push, do not set the official git author, committer, GitHub author, push actor, release actor, or equivalent platform actor to `Claude Code`, `Codex`, or any agent identity. Use the repo's configured human or service identity for official authorship. Agent involvement may be recorded in commit-body notes, run notes, `.build-loop` context, judge decisions, or auxiliary metadata; it must not replace the official author or actor field.
 - **Self-heal SAFE issues — reactive fix AND proactive self-simplification (C-HEAL / self_heal_safe_issues).** Self-heal has two arms, both active. **Reactive:** when build-loop encounters (a) an error or crash from its own tooling, a hook, a script, a Bash command, or a build/test/lint failure; OR (b) a quality or performance issue from any Review sub-step, self-review, fact-check, simplify, or efficiency scan — ROOT-CAUSE and FIX it, then continue. Classify via `scripts/classify_action.py`: SAFE → apply, verify, commit, continue — no surface, no ask; RISKY → isolate to worktree-branch + log + continue main + surface in report; DECISION/PRODUCTION → surface/escalate. **Proactive:** during deep self-review (and any self-recursive build), the self-review/self-heal loop ALSO proactively simplifies build-loop's own code — reducing complexity, splitting oversized files, removing dead/duplicated logic, adding missing tests — driven by `self_review.py`'s `self_simplification[]` findings. The loop MAY also author new skills and new scripts (new scripts require a colocated `test_<name>.py`). Any change to build-loop's own code MUST pass the SELF-MODIFICATION SAFETY GATE (`self_mod_verify.py --scope auto --auto-revert`, `verdict: pass` required) before commit; on fail the gate auto-reverts and the change is not committed. **Self-modifications execute — they do not stop the loop.** A self-modification that is part of the accepted plan (including edits to the gate, tests, or the self-improvement loop) executes behind the test-suite gate. Build-loop never halts a planned self-modification for human approval. Oversight is post-hoc: (a) self-modifying runs trigger an ADDITIONAL adversarial review (independent-auditor at build scope; the periodic deep self-review re-audits recent self-modifications) — non-blocking; (b) the end-of-run readback reports every self-modification and the additional-review findings. The loop stays on task and reports once, at the end. Structural/architectural self-modifications surface as DECISION, never auto-apply. Full gate in `skills/build-loop/references/self-review.md` §"Self-modification of the restricted repo". **Banned anti-pattern:** bypassing a fixable error — `--no-verify`, xfail-ing a test, commenting out failing code, `|| true` on a real failure — when a SAFE fix exists. Workarounds allowed only when the fix classifies RISKY/DECISION/PRODUCTION or is genuinely infeasible; record both.
+- **Flagged-issue default route — disposition by WHERE the issue lives (C-HEAL / flagged_issue_default_route).** No run ends with an issue merely flagged plus a "want me to?" question. When work surfaces an issue at any phase, the DEFAULT action is set by where it lives: build-loop's OWN repo (plugin or `build-loop-memory`) → EXECUTE the fix (C-HEAL/Iterate, behind the self-mod gate); any OTHER repo → FILE a task on the shared Operations Center queue (the queue of record — do not build a build-loop-side cross-repo tracker) mechanically via `python3 scripts/file_to_operations_center.py --repo <repo> --title <one-line> --spec <desc+fix-hint> --urgency <low|normal|high|critical> --json` (urgency→priority critical=P0…low=P3; the helper shells the Operations Center CLI `add` subcommand and returns a task-id receipt — it NEVER writes the sqlite store directly; a missing binary returns `filed:false`+exit 1 to surface as its own blocker); PRODUCTION-class or genuinely ambiguous (irreversible / user-trust / product-direction / unclear routing) → SURFACE to the user. The report dispositions every open finding (own-repo fix commit, cross-repo Operations Center task id, or surfaced) — a cross-repo finding left as prose is a workflow violation. Full policy: `references/keep-going-policy.md` §"Flagged-issue default route".
 
 ## Phase Details
 
@@ -151,11 +216,11 @@ 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[]}`), 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`.
+   The packet covers memory, repo-local state, Codex memory, Rally coordination, **executable queue counts** (`queues.{queue,issues,ux-queue,followup}`), non-executable inboxes, a **classed backlog summary** (`backlog.{planned,initiatives,decisions}`), workstream-relevant decisions in `backlog_work.relevant_decisions`, progressive lessons, 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`.
+   **Backlog system (host-neutral, any agent).** Deferred work lives in `<repo>/.build-loop/backlog/items/` and uses `bucket: planned | initiative | decision`. Planned items are pickup-eligible only at a planning boundary; `promote` creates an executable queue receipt. Initiatives require a user approval receipt plus an isolated non-main worktree and carry `production_policy: prohibited`. Decisions never auto-promote; they surface only when their `workstream`/`related_to` matches active work, and only dependent tasks wait. Use `scripts/backlog.py {new,update,promote,reconcile,sync,list}`; `reconcile` is dry-run-first and lossless.
 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`.
+   - Read `packet.agent_brief`. Queue counts cover executable lanes only. Backlog candidates and relevant decisions come from `packet.backlog_work`; never treat backlog items as queued work until `promote` writes a queue receipt.
    - Surface `lessons_progressive[].name` (up to 3) as ambient context so planning reflects recent learnings.
    - Check `session_prefs.continue_from_queues`:
      - `"always"` → include queue work in the plan without asking.
@@ -171,10 +236,10 @@ After the main build's followup drain completes (or `.build-loop/followup/` was
 ```python
 from scripts.context_bootstrap import should_continue_into_queues, pending_queue_items
 should_continue = should_continue_into_queues(workdir)   # True iff session_prefs == "always"
-pending        = pending_queue_items(workdir)             # {"issues": N, "backlog": M}
+pending        = pending_queue_items(workdir)             # queue/issues/ux-queue/followup
 ```
 
-Proceed only when BOTH `should_continue is True` AND `pending["issues"] + pending["backlog"] > 0`. When both are true, enter one additional Phase 5 iterate cycle targeting `.build-loop/issues/` then `.build-loop/backlog/` (issues first). Use the same iterate machinery: alignment-checker per item, scope-auditor, independent-auditor post-fix; same iterate-cap and stop conditions. Items classified `PRODUCTION` or `DECISION` → surface in report, do not auto-execute. When either condition is false, the run ends — do NOT ask again (the preference was already captured at session start).
+Proceed only when BOTH `should_continue is True` AND `sum(pending.values()) > 0`. Drain `.build-loop/queue/`, then issues, UX queue, and followup. Backlog stays deferred. At a new planning boundary, an agent may select a relevant `planned` candidate and call `backlog.py promote`; it may not auto-pick initiatives or decisions.
 
 **Multi-session presence (Rally Point — cross-host: Claude Code, Codex, Gemini CLI, others):**
 
@@ -182,13 +247,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 enter --tool codex --json
-   rally say presence --tool codex --subject "phase=assess" --json
+   rally enter --tool "$RALLY_TOOL" --session-id "$RALLY_SESSION_ID" --json
+   rally say presence --tool "$RALLY_TOOL" --subject "phase=assess" --json
    ```
    When files are owned, include one `--path` per file or directory so Rally creates explicit file claims:
    ```bash
-   rally enter --tool codex --path "src/app.ts" --json
-   rally say claim --tool codex --subject "phase=execute" --path "src/app.ts" --json
+   rally enter --tool "$RALLY_TOOL" --session-id "$RALLY_SESSION_ID" --path "src/app.ts" --json
+   rally say claim --tool "$RALLY_TOOL" --subject "phase=execute" --path "src/app.ts" --json
    ```
    Embedded fallback path when the Rust `rally` binary is unavailable:
    ```python
@@ -202,7 +267,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 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.
+   Local-fallback `tool` values are host families: `claude_code | codex | gemini | other`. Native Rally uses the session-qualified `RALLY_TOOL`; keep the base family explicit as metadata. Resolve the channel through `discovery_bridge.resolve(...)` before every direct write. Rust-backed channels use `rally enter` / the hardened `scripts/agent_rally.py 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>")
@@ -341,7 +406,7 @@ Wire all three surfaces (`skills/build-loop/SKILL.md`, `agents/build-orchestrato
 - 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.
+- **Subagent scaling (host-neutral):** when the host supports parallel delegation (e.g. Codex with `--parallel` authorization), the autonomy supervisor chooses each wave through `scripts/parallelism.py`: the effective width is the minimum of independent MECE work, project/request capacity, CPU headroom, token budget, shared cross-session capacity, and the absolute ceiling of 150. Default project capacity remains 8; adaptive backpressure reduces on provider, memory, disk, thermal, cost, latency, or failure pressure and recovers only after stable windows. The permission gate still applies: workers only on explicit `--parallel` / delegation authorization. When parallel delegation is unavailable, execute sequentially without asking.
 - Do not delegate ambiguous product decisions, final integration, destructive git operations, push/deploy confirmation, or tasks whose result blocks the immediate next lead-session step.
 - For UI work: follow established design system or sensible defaults (44px touch targets, 4.5:1 contrast). Every visible element must have meaning, working behavior, a clear user purpose, and a matching entry in the UI input/output contract.
 - Surface pre-existing issues separately from new work. If an issue impacts users and is local to the current build, plan and fix it automatically; if too large/risky, log user impact and defer.
@@ -395,7 +460,7 @@ Two checkpoints fire automatically after every implementer commit on plans that
 
 Both backstops are first-class on the code-tier (fan-out) implementer path where they catch some of the recall gap, and defense-in-depth on the thinking-tier path where they rarely fire.
 
-**Sub-step B — Validate**: when the build touches UI, run build-loop's `ui-validator` first, then check the UI input/output contract for changed surfaces, code-based graders (test, lint, type, build), design-rule scanner, visual evidence capture, and LLM-as-judge for nuanced criteria. Every pass/fail has evidence. Use only headless/programmatic surfaces — never auto-open a viewer/dashboard. IBR's interactive viewer / persistent browser sessions stay explicit-only; **UI visual-verification** (BL-3) routes through `build-loop:ibr-bridge` as the primary verifier when the IBR plugin is installed (headless scan is a programmatic action), with `native-ax-driver` / `ui-validator` as fallback. Symbol-only checks (`nm`, `strings`, `otool`) are never a substitute for visual/AX verification on a UI chunk. Scorecard format:
+**Sub-step B — Validate**: when Build Loop updates, compares, or audits a renderable UI design, route headless verification through `build-loop:ibr-bridge` as the primary verifier when IBR is installed, then run `ui-validator`, UI contract checks, code graders, and design-rule scans. When IBR is absent or cannot reach the surface, use `native-ax-driver`, simulator/browser evidence, `ui-validator`, and the static scanner. Never auto-open a viewer/dashboard. The binding trigger and boundary contract is `references/ibr-ui-verification-policy.md`. Symbol-only checks (`nm`, `strings`, `otool`) never substitute for visual/AX verification. Scorecard format:
 
 | # | Criterion | Method | Result | Evidence |
 |---|-----------|--------|--------|----------|
@@ -466,6 +531,8 @@ Log iteration state to `.build-loop/state.json`.
 
 Runs after Review sub-step G (Report) on **every** build. Cheap detector + `consolidate_memory.py` + `procedural_governance.py --mode detect-patterns` always fire. A `## Learn` outcome line is always emitted. Three outcome states:
 
+Run `python3 scripts/learn/__main__.py run --workdir "$PWD" --run-id <recorded-run-id> --source review-g --json`. Dispatch only returned `work_orders[]`, attach results through `attest`, and require `status: complete` with `run_close_lint.py --require-learn`. The receipt is `.build-loop/learn/<run-id>.json`.
+
 - **Accruing** (`runs[] < 3`): cheap detector + consolidation only; report `Learn: accruing (N/3 runs)`.
 - **Deferred** (debug-only `closeout: false` in dispatch envelope OR budget-exhausted `budget_check.py` envelope `action == "finalize_and_stop"` at Phase 6 entry): cheap detector + consolidation; write `.build-loop/proposals/learn-deferred-<run-id>.md` marker with `{reason, runs_count, budget_action}`; skip Sonnet draft + Opus signoff so Learn never blows the budget ceiling. Report `Learn: deferred — <reason>`.
 - **Full** (`runs[] >= 3` AND pattern crossing threshold AND not-deferred): full flow below.
@@ -495,7 +562,7 @@ Build loop stores state in `.build-loop/` within the project directory:
 │   └── <id>.md
 ├── followup/            # Overflow when iteration cap hit; input to subsequent build
 │   └── <topic>.md
-├── backlog/             # Deferred-but-wanted work (drained by end-of-run continuation)
+├── backlog/             # Deferred work; classed and never drained as an execution queue
 │   ├── 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)
@@ -516,25 +583,27 @@ Runs by default at the end of every run (after Phase 6 Learn if it ran, otherwis
 2. Stop coordination watchers: SIGTERM any `coordination_watch.py --interval N` processes started during this run (PIDs tracked in `state.json.runs[N].watcherPids[]`).
 3. **Collapse branches and worktrees (merge winner first, then collapse):** for solo-on-main runs the work is already on `main` — nothing to merge. For multi-worktree runs, merge the winning/validated line(s) to `main` via the normal single-writer commit flow before calling collapse. Then run:
    ```bash
-   python3 ${RUNTIME_PLUGIN_ROOT}/scripts/collapse_run.py --workdir "$PWD" --run-id latest --json
+   python3 ${RUNTIME_PLUGIN_ROOT}/scripts/collapse_run.py --workdir "$PWD" \
+     --run-id <exact-run-id> --branch <exact-branch> \
+     --strict --merged-only --owner-released --release-source phase-d-integrator --json
    ```
-   The script normalizes `dispatchedWorktrees[]` + `riskyBranches[]` + `createdRefs[]` into one ref list, creates a `git bundle ... --all` under `.build-loop/bundles/` (reversibility), then per ref: MERGED → delete branch + remove worktree folder; UNMERGED+`review_hold` → keep branch ref, remove worktree folder (→ `kept_for_review`); UNMERGED+no-hold → keep branch ref, remove worktree folder (→ `surfaced_unmerged`). Output: `{run_id, bundle_path, deleted[], kept_for_review[], surfaced_unmerged[], errors[], dry_run}`. Fail-soft — errors logged, closeout continues.
+   Run this from the integrating/primary worktree only after positive owner release; Stop and missing liveness evidence are not release. The script creates and verifies an exact-branch bundle, writes a prepared receipt, rechecks safety and exact branch-to-worktree registration, removes without force, then rechecks the OID and uses Git's checked-out-aware safe branch deletion. Branch hygiene is complete only when output has `strict_success:true`, `bundle_verified:true`, a terminal `receipt_path`, and `errors:[]`. Unmerged/unsafe/ambiguous refs are retained. Full contract: `references/phase-d-closeout.md`.
 4. Archive the coordination file: move `.build-loop/coordination/<this-coord-file>.md` to `.build-loop/coordination/archived/`.
 5. Optional `changes.jsonl` rotation: `scripts/rally_point/lifecycle.rotate_changes_log(channel_dir, max_mb=1, max_entries=500)`.
-6. Final post: `post(kind="phase", payload={"phase": "run-closeout", ...})` signals to the channel that this run is done.
+6. Final post: `post(kind="phase", run_id=<exact-run-id>, workdir=Path("$PWD"), payload={"phase": "run-closeout", ...})` signals to the channel that this run is done. The post returns `None` and writes nothing unless `branch_closeout_gate.py` verifies terminal branch hygiene (solo-on-main/no-ref runs pass directly).
 7. Write `state.json.runs[N].closeout_status`.
 
 **`## Branch hygiene` report block** — every run's final report includes:
 ```
 ## Branch hygiene
-created N · merged-to-main M (deleted) · kept-for-review R: [<branch-name>, ...]
-· surfaced-unmerged U: [<branch-name>, ...] (ask keep/discard) · bundle: <path>
+created N · closed M · retained R: [<branch-name>, ...]
+· bundle-verified: yes|no · receipt: <path/status> · strict-success: yes|no
 ```
 When a run created zero refs: `Branch hygiene: clean — no run-created branches/worktrees; on main.`
 
 **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. 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).
+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. Before a terminal (`pass`) record archives and clears `execution`, Stop materializes its branch/worktree as `createdRefs.status=open` with `branch_closeout.status=pending_external_merge`. Stop is a turn boundary: it never writes owner release or a prepared cleanup receipt.
 
 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`.
 
@@ -542,12 +611,13 @@ When a run created zero refs: `Branch hygiene: clean — no run-created branches
 
 **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.
+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. Pass `--push-range <base>..<head>` whenever the run pushed: `append_run` corroborates `--commit` against that range and records `pending` rather than a SHA it cannot reach (this manual path is where the 2026-07-09 wrong-SHA record came from).
 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.
+4. **Finalize branch hygiene after merge and positive owner release** — from the integrating/primary worktree run `python3 "$root/scripts/collapse_run.py" --workdir "$PWD" --run-id <exact-run-id> --branch <exact-branch> --strict --merged-only --owner-released --release-source codex-manual --json`. Do not declare branch hygiene clean unless `strict_success:true`, `bundle_verified:true`, a terminal receipt, and `errors:[]` are present.
+5. **Phase 6 Learn recording** — run `python3 "$root/scripts/learn/__main__.py" run --workdir "$PWD" --run-id <run-id> --source manual --json`; complete returned work orders and emit its `learn_line`.
 
-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.
+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 or branch finalization under Codex** — confirm the hook fired, or do the five steps by hand.
 
 ## Post-Build
 
@@ -558,3 +628,112 @@ YYYY-MM-DD | what happened | what to do differently
 ```
 
 These entries are loaded during Phase 1 (Assess) of future builds to prevent repeating mistakes.
+
+## Retrospective finding capture
+
+Every retrospective MUST file the issues and recommendations it names to their relevant location — a finding left only in prose is a workflow violation. This command surface is host-neutral: run it identically from Claude Code, Codex, or any other host.
+
+```bash
+cd <build-loop>/scripts
+python3 -m retrospective.file_findings plan  --retro <path> [--json]   # dry-run: what would be filed, where
+python3 -m retrospective.file_findings apply --retro <path> [--json]   # execute the plan
+python3 -m retrospective.file_findings lint  --retro <path> [--json]   # exit 1 if findings are named but not all filed
+```
+
+`plan`/`apply` also accept `--repo-root <dir>` (repeatable, default `~/dev/git-folder`) and `--default-repo <path>` (repo to use for findings naming no recognizable surface).
+
+**When `plan` reports `needs_input`, fill the plan and feed it back — do NOT hand-run `backlog.py new`.** `backlog.py new` creates a backlog store in whatever repo it is pointed at, so running it for a finding the ladder routed to `LESSONS-LEARNED.md` scaffolds a store into a repo that deliberately has none. `apply` honors each entry's resolved mechanism:
+
+```bash
+python3 -m retrospective.file_findings plan --retro <path> --json > plan.json
+# edit plan.json: fill each entry.finding.{what_happened,impact,recommendation,why}
+# and clear that entry's "needs_input" list. Use
+# "unknown - <what would determine it>" when you genuinely cannot tell.
+python3 -m retrospective.file_findings apply --retro <path> --plan plan.json --json
+```
+
+`--plan -` reads the filled plan from stdin. `apply` writes the `## Filed findings` table into the retrospective itself, and replaces a stale one rather than stacking a second, so a regenerated retro recovers its receipt without re-filing.
+
+**Filing ladder** (per finding, first match wins):
+1. The affected repo's `.build-loop/backlog/`, via:
+   ```bash
+   python3 <build-loop>/scripts/backlog.py new --repo <repo> --area <area> --type <type> \
+     --title <title> --provenance-source retrospective --provenance-ref <retro-path> \
+     --observed <YYYY-MM-DD> --impact <text> --what-happened <text> \
+     --recommendation <text> --why <text> --json
+   ```
+2. That repo's `KNOWN-ISSUES.md`
+3. That repo's `LESSONS-LEARNED.md`
+4. build-loop's own `KNOWN-ISSUES.md` (fallback when the repo has none of the above)
+
+**Five body segments, fixed order, every filed finding:** What happened → When → Impact → Recommendation → Why. `apply` never invents a missing segment — an undeducible one is reported `needs_input` rather than filed hollow.
+
+Every retrospective ends with a `## Filed findings` section naming every id/path this run produced — the checkable artifact `lint` requires. `apply` writes it; you do not hand-author it. Lint fails when the section is missing, when it names no location other than the retro itself, or when it accounts for fewer findings than the retro names.
+
+`python3 -m retrospective` runs this lint automatically after writing a retrospective and reports the verdict as `filing` in its JSON envelope, so an unfiled finding surfaces without anyone choosing to check.
+
+## Silent assumptions — expose the calls you made without asking
+
+Doing ordinary work you make judgement calls the user never sees: what "latest"
+meant, which viewports counted, who the audience was, whether to optimise for
+precision or recall. Each is defensible; none was surfaced. The user finds out
+only when a result is wrong, and then cannot tell which call caused it.
+
+The full procedure — the eleven detectors and the two filters — is
+`skills/silent-assumptions/SKILL.md`, with worked examples in
+`skills/silent-assumptions/references/elicitation-detectors.md`. Both are plain
+markdown with no host-specific syntax, so Codex, Claude Code, and Cursor read the
+same instructions. This section is the Codex-specific operating note.
+
+**This never blocks.** Make the call, apply your default, keep working. The
+register records work already done. It is the structural opposite of
+`skills/decision-queue/`, which exists because work has STOPPED and the user is
+blocked. Never merge the two.
+
+**The file-based path is primary, and it is the whole mechanism under Codex.**
+Codex cannot publish a self-saving artifact, so the interactive page is a
+Claude-only enhancement layered on top and is never required. `register.json`
+plus a generated `dashboard.html` need no artifact host, no browser, and no model
+tokens to refresh.
+
+```bash
+BL=<build-loop>
+DIR="$PWD/.build-loop/decisions/<YYYY-MM-DD>-<slug>"
+mkdir -p "$DIR"
+
+python3 "$BL/scripts/assumption_register.py" new \
+  --slug <slug> --title "<title>" --repo "$PWD" -o "$DIR/register.json"
+# … replace the example row with real rows elicited by the eleven detectors …
+
+python3 "$BL/scripts/assumption_register.py" check "$DIR/register.json"           # exit 1 on any error
+python3 "$BL/scripts/assumption_register.py" build "$DIR/register.json" --check   # render + lint
+python3 "$BL/scripts/assumption_register.py" read  "$DIR/register.json"           # after the user edits
+python3 "$BL/scripts/assumption_register.py" promote "$DIR/register.json" --workdir "$PWD"
+```
+
+`check` enforces what a cold reader needs: a `consequence` naming what breaks,
+for whom and when; evidence pointing at a real path, selector, line or count;
+at least two real options with exactly one marked as the default you already
+applied. A row that cannot pass is deleted, not softened.
+
+**The user rules by editing the register**, setting `rows[].decision.pick` to a
+0-based index into that row's `options` and writing `rows[].decision.note`. Then
+`read` reports it, leading with the overrides. **Treat every note as a standing
+instruction, not a comment on that row** — in the reference register 8 of 14
+rulings carried notes and several were policy for all future work.
+
+**The one proactive behaviour is an offer, never a prompt.** Score unruled rows
+`high`=2, `med`=1, `low`=0 and offer at 6; any row marked `escalate` offers
+immediately regardless of score. `assumption_register.py offer <register>` exits
+0 when it is worth one ignorable sentence and 1 when it is not. Never
+`AskUserQuestion`, never mid-task, never twice for the same register.
+
+**Tracking across repos reuses the existing decision store.** `promote` calls
+`scripts/write_decision/__main__.py` — the same atomic writer
+`auto-decision-capture` uses — landing rows in
+`build-loop-memory/projects/<project>/decisions/` tagged `silent-assumption`. A
+silent assumption is a decision with a subtype, not a new record type. Do not
+build a second store.
+
+Reference register, 20 rows with the user's 14 real rulings:
+the consuming project's `.build-loop/decisions/<date>-<slug>/`.