@tyroneross/build-loop 0.30.3 → 0.34.0

package/skills/build-loop/SKILL.md

@@ -19,8 +19,8 @@ A 5-phase development loop with a mandatory Phase 6: assess state and criteria,
 Internal modes:
 
 - **Build** (default): Full 5-phase loop plus mandatory Phase 6 Learn — triggered by implementation, fix, refactor, migrate, or update language
-- **Optimize**: Metric-driven optimization loop — triggered by "speed up", "reduce", "improve" + a mechanical metric (`/build-loop:optimize` as a direct override)
-- **Research**: Pre-decision analysis, outputs a research packet, no commits — triggered by "research", "evaluate", "compare", "should I" (`/build-loop:research` as a direct override)
+- **Optimize**: Metric-driven optimization loop — triggered by "speed up", "reduce", "improve" + a mechanical metric (`/build-loop:optimize-run` as a direct override)
+- **Research**: Pre-decision analysis, outputs a research packet, no commits — triggered by "research", "evaluate", "compare", "should I" (`/build-loop:research-run` as a direct override)
 - **Debug**: Deep iterative root-cause investigation — triggered by symptom language; also auto-invoked inside the loop on Review-B failures (`/build-loop:debug` as a direct override)
 - **Test**: Static plugin-test suite — triggered by "test plugin", "validate plugin" (`/build-loop:test` as a direct override)
 
@@ -38,158 +38,14 @@ To raise the cap toward the hard ceiling, set in `.build-loop/config.json`:
 
 Values above 12 are clamped. Values above `cpu_count−2` are clamped to `cpu_count−2` to leave headroom for the orchestrator and host OS.
 
-## Autonomous Mode (Queue-Drain Loop)
+## Autonomous Mode + Per-Commit Mode
 
-Autonomous mode generalizes Phase 5 Iterate into a self-replenishing worker that drains its own `ux-queue/` + `issues/` + `proposals/`, alignment-checks each item against the original intent, executes the aligned subset, and commits in batches until the queue is empty or the wall-clock budget elapses. Default since this mode shipped (`--autonomous=false` opts back to classic one-pass).
+Both are conditional modes — their flag tables, budget/iteration caps, question-timeout rules, self-recursive detection, and the per-commit dispatch contract (incl. the GAP-1 parent-dispatch audit + E3 Learn/retro contract) load on demand from `references/autonomous-and-per-commit-modes.md`. Read it when:
 
-**End-of-run backlog/issues drain — SHIPPED DEFAULT 2026-06-04**: every run now auto-drains `.build-loop/issues/` then `.build-loop/backlog/` at end-of-thread without asking. Reversible per-repo via `.build-loop/config.json`:
+- the invocation carries `--long` / `--budget` / `--autonomous=false`, or the goal text matches a long-running keyword (`overnight`, `large-scale`, `multi-day`, …) → **Autonomous Mode** detail;
+- `state.json.selfRecursive.enabled` is true, or the invocation carries `--per-commit` / `--no-per-commit` → **Per-Commit Mode** detail.
 
-```json
-{ "sessionPrefs": { "continueFromQueues": "never" } }
-```
-
-`PRODUCTION`/`DECISION`-classified items still surface (not auto-executed). The continuation runs the same alignment-checker + scope-auditor + independent-auditor wiring as the in-run iterate loop. Stop conditions: iterate-cap (25 autonomous / 5 classic), budget exhausted, PRODUCTION encountered, 5 consecutive iterate failures, explicit user pause. Surfaced in the run report's `## Queue continuation` section.
-
-### Flag surface
-
-| Invocation | Effect |
-|---|---|
-| `/build-loop:run "goal text"` | default mode, 2h budget, autonomous=true |
-| `/build-loop:run --long "goal text"` | long mode, 8h budget |
-| `/build-loop:run --budget 4h "goal text"` | custom budget (overrides `--long`) |
-| `/build-loop:run --budget 30m "goal text"` | accepts `30s`, `30m`, `4h`, or bare integer seconds |
-| `/build-loop:run --autonomous=false "goal text"` | classic single-pass; queue items become `followup/` |
-| `/build-loop:run "overnight refactor of auth ..."` | keyword `overnight` → long mode, 8h |
-
-**Flag precedence (strict, top wins):**
-
-1. `--budget <duration>` — explicit duration always wins; mode tagged `custom`.
-2. `--long` — sets mode `long`, budget 8h.
-3. Keyword detection in goal text — only when `--long` not explicitly set.
-4. Default — mode `default`, budget 2h, autonomous=true.
-
-`--autonomous=false` is orthogonal: it can combine with any budget flag but disables the queue-drain loop entirely. With autonomous off, `--budget` still tracks wall-clock but the orchestrator runs classic Phase 1–6 once and reports.
-
-### Keyword fallback
-
-Case-insensitive whole-word match against the goal text (or `intent.update_intent`). Detection runs ONLY when `--long` is not explicit on the command line. The flag always wins over keyword inference.
-
-| Keyword | Example phrasings |
-|---|---|
-| `long` | "long refactor of …" |
-| `long-running` | "long-running migration" |
-| `overnight` | "overnight build" |
-| `large-scale` | "large-scale rewrite" |
-| `multi-day` | "multi-day backfill" |
-
-Keyword list is configurable via `.build-loop/config.json.autonomy.keywordsLong[]`. The default list above is hard-coded in the orchestrator.
-
-### Budget tracking
-
-The orchestrator writes `state.execution.budget` at autonomous-mode start:
-
-```json
-{
-  "mode": "default | long | custom",
-  "started_at": "<iso8601 UTC>",
-  "deadline_at": "<iso8601 UTC>",
-  "last_checkin_at": "<iso8601 UTC> | null",
-  "commits_since_push": 0,
-  "checkin_interval_pct": 50
-}
-```
-
-`scripts/budget_check.py` reads this block at every iterate-loop entry, every commit, and every phase boundary, returning a routing envelope (`continue | checkin | finalize_and_stop`). The script is informational — exit 0 always; sub-5ms compute.
-
-**Resume contract**: when a budget block exists and the run resumes via `--resume <run_id>`, the orchestrator MUST reuse the original `deadline_at`. A 2h budget that crashed at 1h59m does NOT get a fresh 2h. `scripts/resume_resolver.py._resolve_budget_on_resume()` is the single source of truth for this rule and surfaces the preserved budget under `budget_resume.preserve_deadline: true`.
-
-### Iteration caps
-
-| Mode | Per-build cap | Per-item cap |
-|---|---|---|
-| Classic (autonomous=false) | 5 | n/a |
-| Autonomous default | 25 | 3 same-verdict |
-| Autonomous long | 25 | 3 same-verdict |
-
-`maxIterateAttemptsAutonomous` is configurable in `.build-loop/config.json.autonomy.maxIterateAttemptsAutonomous`.
-
-### Question timeout (autonomous auto-decide)
-
-In autonomous / `--long` mode a question that would otherwise block on the human auto-resolves if unanswered within a window, so an unattended run never stalls. When the orchestrator surfaces such a question it states a **recommended default** + a deadline; `scripts/question_timeout.py` is consulted (e.g. on a `ScheduleWakeup` resume) and returns `answered | take_default | wait`. On `take_default` the orchestrator takes the recommended option, records it to `state.execution.autonomousDefaults[]` + `auto-decision-capture`, continues, and lists every auto-decided question in the end-of-run readback for override (prefer the reversible option when deciding).
-
-**Never auto-resolves — waits indefinitely:** production push, destructive/irreversible delete, and anything the autonomy gate verdicts `confirm`/`block` (gates #1–#2 in `agents/build-orchestrator.md`). Only reversible / `user_impact: major` decisions (gate #3) and steering clarifications time out — the single production gate is preserved.
-
-Config (`.build-loop/config.json.autonomy`): `questionTimeoutMinutes` (default 10), `onTimeout` (`decide_default` default | `wait`).
-
-### Per-Phase A constraint
-
-Phase A (current ship) wires queue drain + alignment-check + time budget. **Pushes stay manual** — `scripts/autonomous_push.py` and the K-commit batch-push policy ship in Phase B. The `should_push_now` field returned by `budget_check.py` is informational in Phase A; the orchestrator surfaces it in check-ins but does not push autonomously yet.
-
-## Per-Commit Mode (Self-Recursive Builds)
-
-Per-commit mode splits a multi-commit build into one independent orchestrator dispatch per commit, so each commit reviews and lands cleanly before the next one starts. It activates automatically when the working directory IS the runtime — that is, when the user is editing the build-loop plugin itself (or any plugin whose runtime symlink points back to the working tree). It can also be explicitly opted into or out of via skill arguments.
-
-### Detection
-
-Phase 1 Assess writes `selfRecursive.enabled: true|false` to `.build-loop/state.json` (commit 1 wired this via `scripts/detect_self_recursive.py`). The skill body MUST read this field BEFORE deciding which dispatch shape to use. If the field is absent, treat it as `false`.
-
-### Mode Resolution
-
-| Skill arg | `selfRecursive` | Resulting mode |
-|---|---|---|
-| `--per-commit` (explicit) | either | per-commit |
-| `--no-per-commit` (explicit) | either | single-orchestrator |
-| (none) | true | per-commit (default for self-recursive) |
-| (none) | false | single-orchestrator (today's behavior) |
-
-Passing both `--per-commit` and `--no-per-commit` is a user error — fail loud with a one-line message naming the conflict and stop before any dispatch.
-
-### Dispatch Contract (Per-Commit Mode)
-
-1. **Plan first, dispatch many.** The skill body invokes a single planning orchestrator (Phase 1 Assess + Phase 2 Plan only). Its return must include a per-commit work list at `.build-loop/per-commit-plan.json` with this exact JSON shape:
-
-   ```json
-   {
-     "run_id": "run_<UTC>_<hash>",
-     "commits": [
-       {
-         "id": "c1",
-         "subject": "feat(scripts): add foo helper",
-         "scope": "...",
-         "files_planned": ["scripts/foo.py", "tests/test_foo.py"],
-         "spec": "verbatim packet for the implementer orchestrator",
-         "depends_on": []
-       }
-     ],
-     "branch": "feat/...",
-     "from_branch": "main"
-   }
-   ```
-
-2. **Per-commit orchestrator dispatch.** For each commit in the plan (respecting `depends_on`), the skill body dispatches a fresh `Agent(subagent_type="build-loop:build-orchestrator", ...)` carrying ONLY that commit's packet plus a `PER_COMMIT_DISPATCH: { commit_id, run_id, prior_commit_hashes }` prompt prefix. Each dispatched orchestrator runs Phase 3 Execute + Phase 4 Review for ITS commit only, then commits and returns. The dispatched orchestrator's behavior on the prefix is documented in `agents/build-orchestrator.md` §0a.
-
-3. **Aggregate.** The skill body collects each orchestrator's return envelope and writes a final report combining all commits' results. On partial failure (commit N fails), do NOT dispatch downstream commits; retain `.build-loop/per-commit-plan.json` so a subsequent `/build-loop:run --resume` invocation can pick up where it stopped. **Parent-dispatch contract (GAP-1):** the dispatcher (this skill body) HAS the Agent tool, so it is the parent that owes the audit. For every returned envelope whose `auditor_status` is `not-run:parent-must-dispatch` or `cross-vendor-deferred`, the dispatcher MUST — before declaring that commit/run review-complete — dispatch `Agent(subagent_type="build-loop:independent-auditor")` on that commit's diff range, append the verdict to `.build-loop/judge-decisions.json`, and re-run `write_run_entry --scope build` so the review-completeness gate passes. A nested per-commit orchestrator cannot audit itself; the audit is the dispatcher's responsibility, not an optional step.
-
-   **Parent owes Phase 6 Learn + retrospective (E3).** A stop-early dispatch that never reaches Phase 4 Review-G can't run Phase 6 Learn or the post-push retro — so the dispatching parent owes them at close, under the same parent-dispatch contract as GAP-1 (not optional, name the owner at dispatch). Full contract: `agents/build-orchestrator.md` §Phase 4 A (E3 block).
-
-### State.json schema
-
-The per-commit dispatcher tracks its own progress under a `perCommit` block alongside the existing `execution` block:
-
-```json
-{
-  "perCommit": {
-    "enabled": true,
-    "mode_source": "self_recursive_default|explicit_flag|opt_out",
-    "plan_path": ".build-loop/per-commit-plan.json",
-    "completed": [{"commit_id": "c1", "hash": "abc123", "completed_at": "..."}],
-    "in_flight": "c2",
-    "queued": ["c3"]
-  }
-}
-```
-
-M2's `execution.iterate_attempt` continues to track per-commit-orchestrator attempt counters (each dispatched orchestrator manages its own iterate counter) — do not duplicate iteration tracking inside `perCommit`.
+Default behavior with none of those signals: classic single-pass Phase 1–6, 2h budget, autonomous queue-drain on. The end-of-run `issues/` then `backlog/` drain is a SHIPPED DEFAULT (2026-06-04), reversible per-repo via `.build-loop/config.json` `sessionPrefs.continueFromQueues: "never"`.
 
 ## Scope Check
 
@@ -357,13 +213,13 @@ Key steps: subagent-driven-development → model assignment (Sonnet default) →
 
 ## Phase 4: Review — Critic, Validate, Fact-Check, Simplify, Auto-Resolve, Report
 
-Seven sub-steps run in order: A Critic → B Validate → C Optimize (opt-in) → D Fact-Check → E Simplify → F Auto-Resolve → G Report. F drains non-destructive items via `scripts/autonomy_gate.py` (auto/warn/confirm/block routing). G is final-pass-only.
+Seven sub-steps run in order (A–G): Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Auto-Resolve → Report. F (Auto-Resolve) drains non-destructive items via `scripts/autonomy_gate.py` (auto/warn/confirm/block routing). G (Report) is final-pass-only.
 
 Key steps: independent-auditor (build scope) adversarial read → build-loop-owned UI validation when UI changed → code-based graders → live smoke gate → LLM judges → fact-checker + mock-scanner + architecture-rules in parallel → simplify → autonomy gate queue → final scorecard + run entry → **non-gating post-push retrospective dispatch** (`build-loop:retrospective-synthesizer` writes the 9-section `.build-loop/retrospectives/<date>/<run-id>.md` + ≤5-line summary surfaced inline; enforce-candidates land at `.build-loop/proposals/enforce-from-retro/` for human review — never auto-promoted; fire-and-continue, run-close is NOT delayed). On self-recursive runs, G appends `## Self-modifications (readback)` listing every self-modification attempted this run — file, what/why, gate verdict, additional-review finding — so the human sees results at the end without the loop stopping. Full spec in `agents/build-orchestrator.md` §G.
 
 **Load `skills/build-loop/references/phase-4-review.md`** for sub-step details, gate matrices, routing rules, and the full Sub-step F Auto-Resolve protocol (all 4 verdict arms including `warn` exit-0 behavior).
 
-**Independent commit auditor — boundary gate + dispatched judge.** Single consolidated auditor (2026-05-23 — replaces retired `commit-auditor` and earlier retired `sonnet-critic`). Two surfaces share the same context-gathering procedure and verdict taxonomy: (1) a PreToolUse Bash hook fires `scripts/audit_before_commit.py` on every `git commit` regardless of who initiates it (manual, Codex, build-loop, IDE) — deterministic packet-builder, hard-blocks (exit 2) on staged secrets and merge-conflict markers, bypass via `BUILDLOOP_AUDIT_BYPASS=1`; (2) the `independent-auditor` agent dispatches at Phase 3 chunk-close (chunk advisory) and Phase 4 Review-A (build scope) for LLM-grade judgment. Four verdicts: `yay (approve)` / `nay (reject)` / `suggest_correction` / `look_again`. **Auditor dispatch ladder (GAP-1):** a *nested* orchestrator (dispatched as a subagent, or per-commit mode) has no Agent tool and cannot dispatch the auditor — it walks `dispatched-agent → peer-host (rally / codex exec) → not-run:parent-must-dispatch`, records the chosen rung in `auditor_status`, and **never** lets inline self-reasoning masquerade as the independent auditor. A `not-run:parent-must-dispatch` run is not review-complete: the dispatching parent owes the audit before Report. Full reference: `skills/build-loop/references/independent-auditor.md` + `references/phase-4-review.md` §"Sub-step A" + `agents/independent-auditor.md`.
+**Independent commit auditor — boundary gate + dispatched judge.** Single consolidated auditor (2026-05-23 — replaces retired `commit-auditor` and earlier retired `sonnet-critic`). Two surfaces share the same context-gathering procedure and verdict taxonomy: (1) a PreToolUse Bash hook fires `scripts/audit_before_commit.py` on every `git commit` regardless of who initiates it (manual, Codex, build-loop, IDE) — deterministic packet-builder, hard-blocks (exit 2) on staged secrets and merge-conflict markers, bypass via `BUILDLOOP_AUDIT_BYPASS=1`; (2) the `independent-auditor` agent dispatches at Phase 3 chunk-close (chunk advisory) and Phase 4 Review-A (build scope) for LLM-grade judgment. Four verdicts: `yay (approve)` / `nay (reject)` / `suggest_correction` / `look_again`. **Auditor dispatch ladder (GAP-1):** a *nested* orchestrator (dispatched as a subagent, or per-commit mode) has no Agent tool and cannot dispatch the auditor — it walks `dispatched-agent → peer-host (rally / codex exec) → not-run:parent-must-dispatch`, records the chosen rung in `auditor_status`, and **never** lets inline self-reasoning masquerade as the independent auditor. A `not-run:parent-must-dispatch` run is not review-complete: under the parent-dispatch contract the dispatching parent owes the audit before Report. Full reference: `skills/build-loop/references/independent-auditor.md` + `references/phase-4-review.md` §"Sub-step A" + `agents/independent-auditor.md`.
 
 ## Phase 5: Iterate — Fix Review Failures + UX Queue (up to 5x)
 
@@ -383,11 +239,11 @@ Key steps: recurring-pattern-detector (Haiku; reads `state.json.runs[]` AND `.bu
 
 ## Memory — Global and Project-Scoped
 
-One consolidated long-term tree: `~/dev/git-folder/build-loop-memory/`. Project-specific durable memory lives under `projects/<slug>/...`; cross-project lessons/design/debugging/product memory lives in the matching top-level lane. Every build runs `scripts/context_bootstrap.py` at Phase 1 Assess, which reads canonical root/project `MEMORY.md` and `constitution.md` files, canonical indexes/folders through `memory_facade.py`, repo-local `.build-loop/` context, Codex memory at `~/.codex/memories`, and best-effort Rally/coordination state when relevant. Live handoff state is written separately by `scripts/context_snapshot.py` under `.build-loop/context/`; snapshots are not durable memory unless Review-G promotes a reusable decision or lesson. Writes go to exactly one canonical memory lane based on scope. Legacy paths (`~/.build-loop/memory`, `.episodic/decisions`, and `build-loop-memory/decisions/<project>`) are migration/archive inputs only.
+One consolidated long-term tree: `~/dev/git-folder/build-loop-memory/`. Project-specific durable memory lives under `projects/<slug>/...`; cross-project lessons/design/debugging/product memory lives in the matching top-level lane. Every build runs `scripts/context_bootstrap.py` at Phase 1 Assess, which reads the store-root `INDEX.md` first, then root/project `constitution.md` / `MEMORY.md` where present, canonical indexes/folders through `memory_facade`, repo-local `.build-loop/` context, Codex memory at `~/.codex/memories`, and best-effort Rally/coordination state when relevant. Live handoff state is written separately by `scripts/context_snapshot.py` under `.build-loop/context/`; snapshots are not durable memory unless Review-G promotes a reusable decision or lesson. Writes go to exactly one canonical memory lane based on scope. Legacy paths (`~/.build-loop/memory`, `.episodic/decisions`, and `build-loop-memory/decisions/<project>`) are migration/archive inputs only.
 
 Routing rule: "Would this apply to a different project?" Yes → global. No → project. Ambiguous → ask the user once.
 
-Append-only memory contract: (1) steering answers from `AskUserQuestion` append to `build-loop-memory/projects/<slug>/decisions/` immediately via `auto-decision-capture` — do not let them die in context; (2) every run appends a milestone at Review-G via `scripts/append_milestone.py` — the permanent progress record, never rewritten; (3) Phase 1 flags staleness when the latest milestone predates HEAD (`scripts/memory_staleness_check.py`). Full write protocol in `references/memory.md`.
+Append-only memory contract: (1) steering answers from `AskUserQuestion` append to `build-loop-memory/projects/<slug>/decisions/` immediately via the decision writer — do not let them die in context; (2) durable lessons/decisions are written when discovered, then deduped at Review-G; (3) every run appends a milestone at Review-G via `scripts/append_milestone.py` when warranted — the permanent progress record, never rewritten; (4) Phase 1 flags staleness when the latest memory update/milestone predates HEAD (`scripts/memory_staleness_check.py`). Full recall-optimized write protocol in `references/memory.md` and `build-loop-memory/references/2026-06-11-memory-discipline-prompt.md` (`version: 2026-06-11.1`).
 
 **Load `skills/build-loop/references/memory.md`** for the full routing rule, write timing, read timing, and memory type taxonomy.
 

package/skills/build-loop/references/advisor-dispatch-ladder.md

@@ -0,0 +1,62 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Advisor dispatch ladder (Phase 2 plan synthesis at Frontier)
+
+The Advisor (Fable) is the Frontier standing role that **authors and re-plans** the Phase 2 plan synthesis. Generating a plan is harder than evaluating one, so the deepest reasoning pays here — but the Advisor is **pull-based**: summoned only when stakes-gating trips, not every run. This ladder enforces that the plan is authored at Frontier *when it matters*, without breaking the runs where it doesn't.
+
+It deliberately **mirrors the GAP-1 independent-auditor ladder** (`phase-4-review.md` §"Sub-step A"). Same shape, same honesty discipline, an analogous `advisor_status` field. If you know that ladder, you know this one.
+
+## When the ladder is evaluated (stakes-gating)
+
+The orchestrator walks this ladder at the Phase 2 plan-synthesis step **only when** any of these objective triggers fire:
+
+- `state.json.synthesisDensity > 5` (synthesis-dense plan), or
+- `triggers.riskSurfaceChange` (security/persistence/runtime/deploy/trust boundary), or
+- `stakes >= medium` (from the commander's-intent posture / charter), or
+- an explicit `dispatch_tier: frontier` on any work item in the draft plan.
+
+If none trips, the ladder is skipped entirely — the orchestrator synthesizes the plan inline as today (most runs stay single-context; this respects the multi-agent-handoff risk by not decomposing more than needed). **Triggers are objective signals, never self-reported confidence** (models are systematically overconfident).
+
+## The four rungs (record `advisor_status` honestly)
+
+Dispatching the Advisor via `Agent(subagent_type="build-loop:advisor")` requires the Agent tool. A *nested* orchestrator (dispatched as a subagent — Mode B — or running per-commit mode) does **not** have the Agent tool, because the harness blocks sub-subagents. Walk the ladder and record `advisor_status`:
+
+1. **Rung 0 — own context already Frontier** (the orchestrator is itself running on Fable, e.g. `/build-loop:run` while the session model is Fable): **synthesize the plan inline** — it is *already* Frontier, no handoff needed. → `advisor_status: inline-frontier`. Zero added cost.
+
+2. **Rung 1 — Agent tool present** (top-level / Mode A, own context not already Frontier): **dispatch the Fable Advisor** (`Agent(subagent_type="build-loop:advisor")`) to author/re-plan, then verify via plan-critic + scope-auditor. → `advisor_status: ran:dispatched-agent`.
+
+3. **Rung 2 — no Agent tool, peer host reachable** (nested Mode B, but a peer host — rally channel / `codex exec` — can execute; reachable because the orchestrator retains Bash even when nested): **run the Advisor as a peer process** over the same channel the cross-vendor reviewer uses. Reconcile the peer's plan + envelope into the plan artifact. → `advisor_status: ran:peer-host(<host>)`. Prefer this over the fallback whenever a peer host can execute (fresh-context synthesis is plausibly *higher quality*, not merely cheaper — see "Quality, not only cost" below).
+
+4. **Rung 3 — none reachable** (no Agent tool, no peer host): **synthesize inline on the orchestrator's own model (Opus)**, labeled honestly. → `advisor_status: fallback:inline-opus`.
+
+## Non-breaking guarantee
+
+**Rung 3 IS today's behavior** — the orchestrator synthesizing the plan inline on Opus. The floor of this ladder equals the current state; it is strictly better whenever a dispatch path (Rung 1/2) or an already-Frontier context (Rung 0) is reachable. The handoff cost fires *only* in Rung 1/2 — i.e., only when the active context isn't already Frontier — so you pay it exactly where it buys an upgrade and never where planning is already Frontier. Worst case equals current; there is no regression path.
+
+## Quality, not only cost
+
+Dispatch is a **quality lever**, not just a cost knob. Context-separation evidence (⚠️ 2026 cross-context-review lead, directionally consistent with the corroborated self-correction literature: correction needs *external* feedback; intrinsic self-correction degrades accuracy) indicates synthesis in a *fresh* context beats same-session work. So Rungs 1/2 (fresh-context dispatch) are plausibly *higher quality* than Rung 0/3 inline — inline is a genuine quality compromise, taken only when dispatch is unreachable. The Advisor is a **separate agent**, never the executor self-reflecting.
+
+## Ledger row per Advisor action (the instrument)
+
+The orchestrator (single writer) appends one row to `.build-loop/agent-ledger.jsonl` per Advisor action via `scripts/agent_ledger.py`:
+
+```
+action: author | re-plan
+agent: advisor · tier: frontier · model: <resolved id (fable / gpt-5.x / …)>
+rung: 0|1|2|3 · status: pass|fail|partial · trigger: <synthesisDensity>5 | riskSurfaceChange | stakes>=medium | dispatch_tier:frontier>
+refs: {output: docs/plans/<slug>.md, input: <prior plan / failure evidence>}
+note: <on re-plan: failure evidence + why a retry is justified>
+```
+
+This closes the unmeasured quality-delta: the A/B test reads the ledger to compare plan outcomes by `rung`/`model` and find whether Frontier planning actually pays.
+
+## Re-plan mode (the remediation contract, v1)
+
+When the orchestrator diagnoses a **planning miss** during Iterate (the plan itself no longer fits, on an objective signal — test/build failure, auditor verdict, retry-count, scope breach), it re-enters this ladder with `action: re-plan`. The Advisor reads the **failure evidence + the diff vs the current plan**, diagnoses planning-miss vs execution-miss (*its* Frontier call, never the failing executor's self-report), and on a planning miss issues **corrected instructions** — a diff against the prior plan + the evidence — so execution resumes at the cheap tier on a sound plan.
+
+**v1 scope:** author + re-plan only. The **take-over-execution rung** (the Advisor executing a chunk directly) and **proactive mid-run checkpoint check-ins** are **v2** — land after the A/B confirms the core pays.
+
+## Always verified — never self-certifying
+
+The Advisor's authored/re-planned plan is checked by the existing Frontier critics before any implementer runs: `plan_verify.py` (deterministic) → `plan-critic` (reasoning; **blocking on the same stakes triggers**, advisory otherwise) → `scope-auditor` at the Plan→Execute boundary. Frontier-authored output does not get a pass on review. Keep the verification panel multi-specialist — do not collapse it to a single judge.

package/skills/build-loop/references/autonomous-and-per-commit-modes.md

@@ -0,0 +1,161 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Autonomous Mode + Per-Commit Mode (conditional detail)
+
+Extracted from `SKILL.md` (WP-A, 2026-06-09): both modes are conditional — their
+tables and contracts are load-bearing only when the mode is active, yet they
+loaded in every session. The SKILL.md body now carries a one-line pointer to
+each; the full detail lives here and loads on demand.
+
+## Autonomous Mode (Queue-Drain Loop)
+
+Autonomous mode generalizes Phase 5 Iterate into a self-replenishing worker that drains its own `ux-queue/` + `issues/` + `proposals/`, alignment-checks each item against the original intent, executes the aligned subset, and commits in batches until the queue is empty or the wall-clock budget elapses. Default since this mode shipped (`--autonomous=false` opts back to classic one-pass).
+
+**End-of-run backlog/issues drain — SHIPPED DEFAULT 2026-06-04**: every run now auto-drains `.build-loop/issues/` then `.build-loop/backlog/` at end-of-thread without asking. Reversible per-repo via `.build-loop/config.json`:
+
+```json
+{ "sessionPrefs": { "continueFromQueues": "never" } }
+```
+
+`PRODUCTION`/`DECISION`-classified items still surface (not auto-executed). The continuation runs the same alignment-checker + scope-auditor + independent-auditor wiring as the in-run iterate loop. Stop conditions: iterate-cap (25 autonomous / 5 classic), budget exhausted, PRODUCTION encountered, 5 consecutive iterate failures, explicit user pause. Surfaced in the run report's `## Queue continuation` section.
+
+### Flag surface
+
+| Invocation | Effect |
+|---|---|
+| `/build-loop:run "goal text"` | default mode, 2h budget, autonomous=true |
+| `/build-loop:run --long "goal text"` | long mode, 8h budget |
+| `/build-loop:run --budget 4h "goal text"` | custom budget (overrides `--long`) |
+| `/build-loop:run --budget 30m "goal text"` | accepts `30s`, `30m`, `4h`, or bare integer seconds |
+| `/build-loop:run --autonomous=false "goal text"` | classic single-pass; queue items become `followup/` |
+| `/build-loop:run "overnight refactor of auth ..."` | keyword `overnight` → long mode, 8h |
+
+**Flag precedence (strict, top wins):**
+
+1. `--budget <duration>` — explicit duration always wins; mode tagged `custom`.
+2. `--long` — sets mode `long`, budget 8h.
+3. Keyword detection in goal text — only when `--long` not explicitly set.
+4. Default — mode `default`, budget 2h, autonomous=true.
+
+`--autonomous=false` is orthogonal: it can combine with any budget flag but disables the queue-drain loop entirely. With autonomous off, `--budget` still tracks wall-clock but the orchestrator runs classic Phase 1–6 once and reports.
+
+### Keyword fallback
+
+Case-insensitive whole-word match against the goal text (or `intent.update_intent`). Detection runs ONLY when `--long` is not explicit on the command line. The flag always wins over keyword inference.
+
+| Keyword | Example phrasings |
+|---|---|
+| `long` | "long refactor of …" |
+| `long-running` | "long-running migration" |
+| `overnight` | "overnight build" |
+| `large-scale` | "large-scale rewrite" |
+| `multi-day` | "multi-day backfill" |
+
+Keyword list is configurable via `.build-loop/config.json.autonomy.keywordsLong[]`. The default list above is hard-coded in the orchestrator.
+
+### Budget tracking
+
+The orchestrator writes `state.execution.budget` at autonomous-mode start:
+
+```json
+{
+  "mode": "default | long | custom",
+  "started_at": "<iso8601 UTC>",
+  "deadline_at": "<iso8601 UTC>",
+  "last_checkin_at": "<iso8601 UTC> | null",
+  "commits_since_push": 0,
+  "checkin_interval_pct": 50
+}
+```
+
+`scripts/budget_check.py` reads this block at every iterate-loop entry, every commit, and every phase boundary, returning a routing envelope (`continue | checkin | finalize_and_stop`). The script is informational — exit 0 always; sub-5ms compute.
+
+**Resume contract**: when a budget block exists and the run resumes via `--resume <run_id>`, the orchestrator MUST reuse the original `deadline_at`. A 2h budget that crashed at 1h59m does NOT get a fresh 2h. `scripts/resume_resolver.py._resolve_budget_on_resume()` is the single source of truth for this rule and surfaces the preserved budget under `budget_resume.preserve_deadline: true`.
+
+### Iteration caps
+
+| Mode | Per-build cap | Per-item cap |
+|---|---|---|
+| Classic (autonomous=false) | 5 | n/a |
+| Autonomous default | 25 | 3 same-verdict |
+| Autonomous long | 25 | 3 same-verdict |
+
+`maxIterateAttemptsAutonomous` is configurable in `.build-loop/config.json.autonomy.maxIterateAttemptsAutonomous`.
+
+### Question timeout (autonomous auto-decide)
+
+In autonomous / `--long` mode a question that would otherwise block on the human auto-resolves if unanswered within a window, so an unattended run never stalls. When the orchestrator surfaces such a question it states a **recommended default** + a deadline; `scripts/question_timeout.py` is consulted (e.g. on a `ScheduleWakeup` resume) and returns `answered | take_default | wait`. On `take_default` the orchestrator takes the recommended option, records it to `state.execution.autonomousDefaults[]` + `auto-decision-capture`, continues, and lists every auto-decided question in the end-of-run readback for override (prefer the reversible option when deciding).
+
+**Never auto-resolves — waits indefinitely:** production push, destructive/irreversible delete, and anything the autonomy gate verdicts `confirm`/`block` (gates #1–#2 in `agents/build-orchestrator.md`). Only reversible / `user_impact: major` decisions (gate #3) and steering clarifications time out — the single production gate is preserved.
+
+Config (`.build-loop/config.json.autonomy`): `questionTimeoutMinutes` (default 10), `onTimeout` (`decide_default` default | `wait`).
+
+### Per-Phase A constraint
+
+Phase A (current ship) wires queue drain + alignment-check + time budget. **Pushes stay manual** — `scripts/autonomous_push.py` and the K-commit batch-push policy ship in Phase B. The `should_push_now` field returned by `budget_check.py` is informational in Phase A; the orchestrator surfaces it in check-ins but does not push autonomously yet.
+
+## Per-Commit Mode (Self-Recursive Builds)
+
+Per-commit mode splits a multi-commit build into one independent orchestrator dispatch per commit, so each commit reviews and lands cleanly before the next one starts. It activates automatically when the working directory IS the runtime — that is, when the user is editing the build-loop plugin itself (or any plugin whose runtime symlink points back to the working tree). It can also be explicitly opted into or out of via skill arguments.
+
+### Detection
+
+Phase 1 Assess writes `selfRecursive.enabled: true|false` to `.build-loop/state.json` (commit 1 wired this via `scripts/detect_self_recursive.py`). The skill body MUST read this field BEFORE deciding which dispatch shape to use. If the field is absent, treat it as `false`.
+
+### Mode Resolution
+
+| Skill arg | `selfRecursive` | Resulting mode |
+|---|---|---|
+| `--per-commit` (explicit) | either | per-commit |
+| `--no-per-commit` (explicit) | either | single-orchestrator |
+| (none) | true | per-commit (default for self-recursive) |
+| (none) | false | single-orchestrator (today's behavior) |
+
+Passing both `--per-commit` and `--no-per-commit` is a user error — fail loud with a one-line message naming the conflict and stop before any dispatch.
+
+### Dispatch Contract (Per-Commit Mode)
+
+1. **Plan first, dispatch many.** The skill body invokes a single planning orchestrator (Phase 1 Assess + Phase 2 Plan only). Its return must include a per-commit work list at `.build-loop/per-commit-plan.json` with this exact JSON shape:
+
+   ```json
+   {
+     "run_id": "run_<UTC>_<hash>",
+     "commits": [
+       {
+         "id": "c1",
+         "subject": "feat(scripts): add foo helper",
+         "scope": "...",
+         "files_planned": ["scripts/foo.py", "tests/test_foo.py"],
+         "spec": "verbatim packet for the implementer orchestrator",
+         "depends_on": []
+       }
+     ],
+     "branch": "feat/...",
+     "from_branch": "main"
+   }
+   ```
+
+2. **Per-commit orchestrator dispatch.** For each commit in the plan (respecting `depends_on`), the skill body dispatches a fresh `Agent(subagent_type="build-loop:build-orchestrator", ...)` carrying ONLY that commit's packet plus a `PER_COMMIT_DISPATCH: { commit_id, run_id, prior_commit_hashes }` prompt prefix. Each dispatched orchestrator runs Phase 3 Execute + Phase 4 Review for ITS commit only, then commits and returns. The dispatched orchestrator's behavior on the prefix is documented in `agents/build-orchestrator.md` §0a.
+
+3. **Aggregate.** The skill body collects each orchestrator's return envelope and writes a final report combining all commits' results. On partial failure (commit N fails), do NOT dispatch downstream commits; retain `.build-loop/per-commit-plan.json` so a subsequent `/build-loop:run --resume` invocation can pick up where it stopped. **Parent-dispatch contract (GAP-1):** the dispatcher (this skill body) HAS the Agent tool, so it is the parent that owes the audit. For every returned envelope whose `auditor_status` is `not-run:parent-must-dispatch` or `cross-vendor-deferred`, the dispatcher MUST — before declaring that commit/run review-complete — dispatch `Agent(subagent_type="build-loop:independent-auditor")` on that commit's diff range, append the verdict to `.build-loop/judge-decisions.json`, and re-run `write_run_entry --scope build` so the review-completeness gate passes. A nested per-commit orchestrator cannot audit itself; the audit is the dispatcher's responsibility, not an optional step.
+
+   **Parent owes Phase 6 Learn + retrospective (E3).** A stop-early dispatch that never reaches Phase 4 Review-G can't run Phase 6 Learn or the post-push retro — so the dispatching parent owes them at close, under the same parent-dispatch contract as GAP-1 (not optional, name the owner at dispatch). Full contract: `agents/build-orchestrator.md` §Phase 4 A (E3 block).
+
+### State.json schema
+
+The per-commit dispatcher tracks its own progress under a `perCommit` block alongside the existing `execution` block:
+
+```json
+{
+  "perCommit": {
+    "enabled": true,
+    "mode_source": "self_recursive_default|explicit_flag|opt_out",
+    "plan_path": ".build-loop/per-commit-plan.json",
+    "completed": [{"commit_id": "c1", "hash": "abc123", "completed_at": "..."}],
+    "in_flight": "c2",
+    "queued": ["c3"]
+  }
+}
+```
+
+M2's `execution.iterate_attempt` continues to track per-commit-orchestrator attempt counters (each dispatched orchestrator manages its own iterate counter) — do not duplicate iteration tracking inside `perCommit`.

package/skills/build-loop/references/capability-routing.md

@@ -16,7 +16,8 @@ Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` a
 |-------|---------|----------|
 | `writing-plans` | Phase 2 (Plan) | Write a structured plan directly: goal, tasks with exact file paths, dependency order, test commands |
 | `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually using the host's available delegation tool for independent file groups |
-| `verification-before-completion` | Phase 4 sub-step G (Report) | Run all test/build/lint commands and confirm output before claiming completion |
+| `verification-before-completion` | Phase 4 sub-step G (Report) | Run all test/build/lint commands and confirm output before claiming completion. For app/UI changes this is NOT sufficient alone — also run the runtime UI⇄source-of-truth parity check (`runtime-parity-verification`); compile-green and a screenshot do not prove the running flow works |
+| `runtime-parity-verification` | Phase 4 Review-B + Phase 5 Iterate (any `uiTarget != null` or user-visible flow) | Cross-check the rendered/queryable UI against the authoritative backend (DB/API/daemon/tool-state), screen-independently, and keep a validated per-repo smoke. Catches the "action does nothing / not showing / shows empty despite real data / stale projection" class. Drivers: web `ui-validator`; macOS `native-ax-driver` / IBR `scan_macos`; iOS `idb`; agent = tool-result vs rendered output. Reference smoke: easy-terminal `tools/smoke_launch.py` |
 | `simplify` (slash: `/simplify`) | Phase 4 sub-step E (Simplify) | Self-review the diff: remove scaffolding, inline single-use helpers, delete dead branches |
 | `complexity_detector.py` (accelerator, not a gate) | Phase 4 sub-step E (Simplify) | Diff-scoped stdlib-AST hotspot detector for changed Python; surfaces high-severity hotspots for a simpler rewrite, apply-vs-advise via existing Review-B + independent-auditor. Optional Python aid — the default Simplify pass reasons over the diff language-agnostically (see `phase-4-review.md` §"Sub-step E: Simplify") |
 | `build-loop:self-improve` | Phase 6 (Learn) | Scan recent runs for recurring patterns, auto-draft experimental skills/agents with A/B tracking, notify user for keep/remove decisions |
@@ -80,7 +81,7 @@ Tie-breaker: if signals are mixed (an Apple project with both `ios/` and a macOS
 
 **Migration source**: if `.replit` / `replit.nix` present → `migrationSource: "replit"`. Lovable / Bolt / v0 export markers (e.g. `lovable.config`, `bolt.config`, `v0.dev` in comments) → corresponding source. `replit-migrate` skills generalize — load `migration-scan` for any of the above, override hints as needed.
 
-**Apple deploy**: when `platform: "apple"` AND goal includes "deploy", "TestFlight", or "App Store" → Phase 7/8 invoke `apple-dev` deploy flow using ASC creds per `~/.claude/projects/-Users-tyroneross/memory/reference_asc_credentials.md`. Apply deployment policy first: TestFlight/App Store Connect upload/export defaults to `auto`; App Store production release/submission defaults to `confirm`.
+**Apple deploy**: when `platform: "apple"` AND goal includes "deploy", "TestFlight", or "App Store" → Phase 7/8 invoke `apple-dev` deploy flow using ASC creds from your harness memory store (e.g. `~/.claude/projects/<project-slug>/memory/reference_asc_credentials.md`). Apply deployment policy first: TestFlight/App Store Connect upload/export defaults to `auto`; App Store production release/submission defaults to `confirm`.
 
 **Web deploy verify**: fires when `.vercel/project.json` or `vercel.json` is present AND the build performed a push/deploy → Phase 4 Review-B invokes `scripts/verify_deploy.py` (preferred-tier upgrade: Vercel MCP only if the user has added it to `.mcp.json`). Infra failures return `skipped`, never block the build.
 
@@ -175,7 +176,7 @@ If Phase 1 detects that the task touches plugin components, Phase 3 must map eac
 
 | Source | When | How |
 |---|---|---|
-| `/cookbook` | Claude API patterns: tool calling, PTC, code execution, Agent SDK, RAG, thinking, structured output, batch, caching | Invoke `/cookbook` or read `~/.claude/projects/-Users-tyroneross/memory/reference_claude_cookbook.md` |
+| `/cookbook` | Claude API patterns: tool calling, PTC, code execution, Agent SDK, RAG, thinking, structured output, batch, caching | Invoke `/cookbook` or read `reference_claude_cookbook.md` from your harness memory store (`~/.claude/projects/<project-slug>/memory/`) |
 | `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` | Any plugin work | Read during Phase 1 ASSESS |
 | `context7` MCP | Any library/framework use | `query-docs` / `resolve-library-id` — do NOT code from training data |
 | `research` skill | Factual claims, pricing, versions | Run `scripts/research_trigger.py` first; T1 official docs → T4 forums; 2-source minimum |

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

@@ -70,6 +70,14 @@ Prefer explicit prompt packets over full context forks. Use full context only wh
 
 Shared reads should happen once in the lead session, then be condensed into worker prompts. This keeps workers focused and reduces contradictory interpretations.
 
+### Prompt Cache Discipline
+
+OpenAI prompt caching is automatic, so Build Loop cannot call the cache directly from Codex. The lever the Codex adapter controls is prompt shape: keep the reusable prefix stable, and move volatile task state later.
+
+For Codex CLI and Codex app runs, put reusable role rules, output contracts, validation expectations, and ownership schema before task-specific facts. Put Rally state, timestamps, command output, diffs, browser comments, thread IDs, worktree metadata, current claims, and task IDs after the stable contract.
+
+Do not reorder stable sections between worker prompts. Monitoring cached-token counters only detects prefix churn; the improvement comes from preserving the prefix and reducing noisy context before dispatch.
+
 ## Parallel Pattern
 
 1. Lead creates the plan and identifies parallel-safe groups.

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

@@ -100,7 +100,7 @@ explicit extraction edges:
 
 | Future plugin | Embedded namespace | Build-loop compatibility entrypoints |
 |---|---|---|
-| `agent-rally-point` | `scripts/rally_point/**` | `scripts/agent_rally.py`, `commands/agent-rally-point.md`, `hooks/*rally-point.sh`, `scripts/coordination_status.py`, `scripts/coordination_rally.py`, `scripts/coordination_bootstrap.py` |
+| `agent-rally-point` | `scripts/rally_point/**` | `scripts/agent_rally.py`, `commands/rally-point.md`, `hooks/*rally-point.sh`, `scripts/coordination_status.py`, `scripts/coordination_rally.py`, `scripts/coordination_bootstrap.py` |
 | `agent-rally-watcher` | `scripts/agent_rally_watcher/**` | `scripts/coordination_watch.py` |
 
 The machine-readable contract lives at

package/skills/build-loop/references/intent-capability-pack.md

@@ -17,6 +17,65 @@ Every build starts by capturing:
 
 Write the result to `.build-loop/intent.md` and mirror the compact version into `.build-loop/state.json.intent`.
 
+### Commander's-intent posture (WP-F, all OPTIONAL — LLM-inferred, confirm-on-ambiguity)
+
+North Star captures who/what; **posture** captures the tradeoff stance that drives
+autonomous forks when the agent loses comms (the Marine-Corps commander's-intent
+analog: purpose + key tasks + end state, so a subordinate who can't ask still
+chooses correctly). A walkie-talkie app for generals-on-ops, for kids, and for
+traders share North Star *fields* but differ entirely in *what to optimize when
+forced to choose*. All fields are OPTIONAL and LLM-inferred from the ask; confirm
+only on genuine ambiguity (reuse the restatement protocol — never `AskUserQuestion`,
+never a gate). Mirror into `state.json.intent.posture`.
+
+- **audience** + **stakes** — one line each (who the change serves; what a failure
+  costs). `stakes` ∈ {low, medium, high}.
+- **priority_order** — the ranked tie-breaker the agent applies when two viable
+  paths conflict. FIXED VOCAB (ordered subset of
+  `security / reliability / speed / cost / simplicity / polish`) plus a free-text
+  `notes` escape for expressiveness. The fixed vocab aids weak-LLM recall; `notes`
+  carries anything the vocab can't.
+- **acceptable_tradeoffs** — what is OK to cut under pressure.
+- **non_goals** — what is never cut. At `stakes: high`, a `non_goals` entry that
+  names a REAL risk is a candidate to **graduate to a constitution invariant** — but
+  only once it is **promoted into the project constitution** (`projects/<slug>/constitution.md`),
+  where the LLM enforces it as a hard line. Until promoted, it stays advisory like the
+  rest of the posture. There is no separate deterministic gate that reads `non_goals`
+  directly (`grep non_goals scripts/` is intentionally empty); enforcement rides the
+  constitution, not a parallel mechanism. See the tiered charter below.
+
+`priority_order` wires into the `alignment-checker` as the Phase-2-fork and
+Phase-5-queue-drain tie-breaker: not just "matches intent?" but "which viable path
+does THIS user's priority order prefer?" — advisory data the LLM weighs, never a gate.
+
+### Tiered intent — `stakes` is the depth dial (WP-F/F2)
+
+- **Per-run intent** (ephemeral, `.build-loop/intent.md`): restated ask + this
+  change's posture. Unchanged lifecycle.
+- **Project charter** (persistent): stable North Star + posture + invariants + key
+  architecture decisions. ACCRETES via promotion — a fact promotes to durable when
+  user-confirmed OR stable/unchallenged across N runs; stays `inferred` until then;
+  carries the falsifier that would unseat it (doctrine rule 8). Storage + sync:
+  `scripts/charter.py` (canonical `build-loop-memory/projects/<slug>/charter.md`;
+  repo mirror `.build-loop/charter.md` with a `canonical:` pointer + content hash;
+  one writer = the run, from canonical; user hand-edit of the mirror promotes to
+  canonical `authored_by: user` on next run via hash-mismatch detection).
+- **Depth scales by `stakes`**: low → intent line only (skills/agents/toys — do NOT
+  force a charter, that's the anti-pattern); medium → thin charter (web/mobile);
+  high → full charter, and risk-naming `non_goals` become candidates to promote into
+  the constitution as invariants (where the LLM enforces them). The promotion is the
+  enforcement; no `non_goals`-specific gate exists outside the constitution.
+- **PRD stance**: opt-in upfront via `start-prd`; accretion is the default; never
+  required. A PRD, when present, PREFILLS the charter richer — input, not a gate.
+
+Enforcement philosophy (binding): all advisory. The one stronger-than-advisory path
+is **constitution promotion** — a risk-naming `non_goals` at `stakes: high` graduates
+to a hard invariant only when it is written into `projects/<slug>/constitution.md`,
+which the LLM treats as a binding line. Per `feedback_deterministic_only_for_known_risks` —
+posture/charter depth is the dial; the LLM weighs, never a gate. The constitution, not
+a `non_goals`-specific script, carries any graduated invariant (no dormant determinism
+claim — there is no `non_goals` enforcement code to wire up).
+
 ## Intent restatement protocol (always-on)
 
 Run this protocol on every build, judged by the orchestrator LLM — never a regex, never a detector script, never a binary gate. Depth scales with ambiguity, not a threshold. The behavior is intrinsic to Phase 1; no separate skill, script, or routing step gates it.
@@ -73,10 +132,38 @@ Mirror the result to `.build-loop/state.json.intent`:
   "restated_intent": "<one sentence>",
   "approach_options": ["<label>", "<label>"],   // optional; empty when Step A alone fired
   "assumptions": ["<line>", "<line>"],          // optional; empty when no leaps were made
-  "confidence": "high" | "medium" | "low"       // LLM judgment, not a script
+  "confidence": "high" | "medium" | "low",      // LLM judgment, not a script
+  "run_id": "<current run_id>"                  // Step E: the run this intent was written for
 }
 ```
 
+### Step E — Run-id freshness stamp (per-run staleness guard)
+
+`intent.md` lives in `.build-loop/` and survives across runs in the same workdir, so a
+resumed or back-to-back run finds the PRIOR run's intent on disk. The "auto-execute fast
+path" (Step A: "write the line and move on" for a concrete goal) can be misread as
+"the present file already satisfies the protocol", so the rewrite gets skipped and the
+stale intent describes prior work — the exact bl-intent-refresh-per-run failure (the
+A–H consolidation run listed as a non-goal what WP-A shipped).
+
+Two cheap, deterministic moves close it:
+
+1. **Stamp on write.** Whenever Phase 1 (re)writes `intent.md`, embed the current
+   `run_id` as an HTML comment so the prose never has to carry it:
+   `<!-- intent_run_id: <run_id> -->` (helper: `intent_freshness.stamp_marker(run_id)`).
+   Mirror `run_id` into `state.json.intent.run_id`.
+2. **Check at Phase 1 start.** Run
+   `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/intent_freshness.py --workdir "$PWD" --json`.
+   A `stale` (stamp ≠ current run) or `unstamped` verdict means the on-disk intent is
+   from a prior run — re-run Steps A–D and re-stamp. The check is **advisory** and exit-0
+   always: a run-id *mismatch* is an objective structural fact (equality, not a content
+   judgment), so detecting it respects "never a content gate" — only the refresh (the LLM
+   rewriting the prose) is judgment. Surface the verdict line in the run report; never
+   `AskUserQuestion`, never `## Held`, never block.
+
+This is detection-by-structure + refresh-by-LLM: it does not re-introduce the retired
+regex that judged intent *content*; it only answers "does this file belong to this run?".
+
 ### Hard guarantees (non-negotiable)
 
 - **Never `AskUserQuestion`.** Intent capture is autonomous. The user reads the restatement + assumptions in the run report and can correct on the next dispatch.