@tyroneross/build-loop 0.30.3 → 0.35.0

package/.agents/plugins/marketplace.json

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

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/AGENTS.md

@@ -117,6 +117,7 @@ Combines situational awareness with goal definition so Plan has everything it ne
 - Map relevant architecture (only what the goal touches)
 - Check for prior state (`.build-loop/state.json` from interrupted builds)
 - If goal involves external frameworks or APIs: research current docs before planning
+- **Capture web/doc findings as references (default-on, any phase/mode).** Whenever the run fetched external info (WebSearch/WebFetch/Context7/api-registry/official docs) AND used it in a decision, persist the EXTRACTED findings (not raw HTML) via `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reference_capture.py capture --workdir "$PWD" --run-id "<run_id>" --topic "<topic>" --findings "<distilled>" --source "<url>|<T1..T4>" --decision "<what it informed>" --json`. This routes through the canonical memory writer into the project `research` lane with `retrieved_at` and a per-content-class `refresh_after` horizon (api-docs/pricing age in days, surveys in months, specs in ~half a year). The store is uncommitted by default. On the next run, `context_bootstrap.py` flags any reference past its horizon as `stale-needs-refresh` in the brief (`packet.reference_freshness`) — advisory only, never a blocking ask. Do not ask whether to capture; it is a default behavior. Full policy: `references/research-trigger-policy.md` §"Reference Capture".
 - If web/mobile UI: capture current visual state for before/after comparison, then load `skills/build-loop/references/ui-io-contract.md` and inventory the affected user inputs and system outputs before planning
 - **Supply-chain dependency cooldown**: if a JS project (`package.json`), run `scripts/inject_dependency_cooldown.py --workdir <repo>` to idempotently write the 7-day publish-age config using each PM's native key: npm ≥ 11.10.0 → `.npmrc` `min-release-age` (DAYS); pnpm → `pnpm-workspace.yaml` `minimumReleaseAge` (MINUTES) + `.npmrc` `minimum-release-age` for 10.x; yarn ≥ 4.10 → `.yarnrc.yml` `npmMinimalAgeGate` (numeric MINUTES). npm has no native exclude (npm/cli#8994), so on npm the user-authored allowlist (`.build-loop/config.json` → `dependencyCooldown.allowlist`, default `["@tyroneross/*"]`) is enforced by the PreToolUse hook (`scripts/hooks/pre_bash_dependency_cooldown.sh`), which stays engaged even with native config; pnpm/yarn carry the exclude natively so the hook stands down once enforced. `--check` verifies the PM actually recognizes the key (no false `enforced:true`). Constitution rule: `C-SUPPLY/dependency_cooldown`. Older npm (< 11.10.0) falls back to the hook's `--before=<7d ago>` date-pin. pip/cargo not covered in v1.
 
@@ -260,7 +261,7 @@ Full provider substitution table (Thinking / Code / Pattern → each host's mode
 - Break work into tasks with exact file paths
 - Identify dependency order — what must complete before what?
 - Flag parallel-safe groups: files that don't import each other can be written simultaneously
-- Partition files and agents MECE: every changed file has exactly one owner, every required responsibility has an owner, and each group declares `owns`, `does not own`, `interface contract`, and `integration checkpoint`
+- Partition files and agents MECE: every changed file has exactly one owner, every required responsibility has an owner, and each group declares all seven ownership fields — `owns`, `does not own`, `interface contract`, `integration checkpoint`, `allowed tools`, `denied tools`, and `acceptance criteria` (the testable conditions the returning envelope must satisfy — the verifier's per-chunk oracle)
 - Define checkpoints where work should be verified before continuing
 - Optimize: remove unnecessary steps, combine related changes, eliminate redundant work
 - **Two-lens approach gate**: for non-trivial architecture, workflow, dependency, UI/product, or long-lived interface decisions, add a `## Approach Lenses` section before implementation tasks. It must include:
@@ -307,7 +308,7 @@ Wire all three surfaces (`skills/build-loop/SKILL.md`, `agents/build-orchestrato
 ### Phase 3: Execute
 
 - Dispatch parallel work for independent file groups
-- Each worker gets minimal context + integration contract (what interfaces to implement) + an intent packet explaining how the subtask fits the north star + a MECE ownership packet defining owned files, non-owned files, interface contracts, and integration checkpoints
+- Each worker gets minimal context + integration contract (what interfaces to implement) + an intent packet explaining how the subtask fits the north star + a MECE ownership packet defining all seven fields: owned files, non-owned files, interface contracts, integration checkpoints, allowed tools, denied tools, and acceptance criteria (the testable conditions the returning envelope must satisfy — the verifier's per-chunk oracle)
 - If the host supports typed subagents, map read-only codebase questions to explorer-style agents and disjoint implementation slices to worker-style agents. If the host requires explicit user authorization for subagents, identify parallel-safe groups but execute locally unless the user asked for delegation, parallelization, workers, or a `--parallel` mode.
 - **Single-entry routing (host-neutral):** every coding task enters through one build-loop invocation; the runtime auto-classifies intent (build / optimize / research / debug / test) and routes accordingly. The host does not pick a mode — classification is internal. This applies equally across coding hosts (Claude Code, Codex, Cursor, Gemini CLI, others).
 - **Subagent scaling (host-neutral):** when the host supports parallel delegation (e.g. Codex with `--parallel` authorization), dispatch up to `scripts/parallelism.py effective_max_implementers()` workers — machine-aware cap, default 8, ceiling 12 — decomposing work into the maximum number of independent MECE chunks. The permission gate still applies: workers only on explicit `--parallel` / delegation authorization. When parallel delegation is unavailable, execute sequentially without asking.
@@ -487,6 +488,14 @@ created N · merged-to-main M (deleted) · kept-for-review R: [<branch-name>, ..
 ```
 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).
+
+2. **Contract.** Advisory + fail-open (always exit 0, never `decision: block`), self-gated on `.build-loop/` presence + this-session match (`current_session_id`, heartbeat-freshness fallback when the host passes no session id), minimal-PATH safe, idempotent with Phase D — the marker is the inline-path sentinel and `runs[]` membership is the Phase-D sentinel, so neither double-records the other. Tests: `scripts/test_stop_closeout.py` + `hooks/test_closeout.sh`.
+
+3. **Codex wiring.** Both hosts ship in-repo: Claude via `hooks/hooks.json`, Codex via the tracked `.codex/hooks.json` — `Stop` and `SessionStart` entries call the same shim (`root="$(git rev-parse --show-toplevel)"; bash "$root/hooks/closeout.sh" stop`). ⚠ VERIFIED DORMANT under `codex exec` 0.139.0 (live probe 2026-06-12, `--dangerously-bypass-hook-trust`): codex fired global/built-in hooks but never the repo-level file. Until codex honors repo-level hooks, the working Codex path is the global `~/.codex/hooks.json` (the shim self-gates on `.build-loop/`, so a global install is safe — but global installs are user-opt-in, not shipped).
+
 ## Post-Build
 
 After every build, if something surprising happened, append one line to `.build-loop/feedback.md`:

package/README.md

@@ -118,9 +118,10 @@ Add to `~/.claude/settings.json`:
 ### Memory setup (one-time, per machine)
 
 Build-loop's advisory judges read from the canonical `build-loop-memory` store
-(`~/dev/git-folder/build-loop-memory` by default). Plugin writers also maintain
-a global update ledger at `<memory-root>/indexes/updates.jsonl` for audit and
-freshness. Bootstrap with templates:
+(at `<memory-root>` — the neutral `~/.build-loop-memory` on a fresh install;
+see `docs/memory-setup.md` for the full resolution order). Plugin writers also
+maintain a global update ledger at `<memory-root>/indexes/updates.jsonl` for
+audit and freshness. Bootstrap with templates:
 
 ```bash
 python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py
@@ -169,9 +170,9 @@ Examples:
 
 Runs deep iterative root-cause investigation (causal-tree analysis, fix, verify, critique — up to 5 iterations). The build orchestrator also auto-invokes `Skill("build-loop:debug-loop")` on Review-B Validate failures and Iterate retries (attempts 2 and 3) — you don't have to call it manually during a build.
 
-**`/build-loop:optimize [target]`** — force optimize mode. Auto-routed from `/build-loop:run` on metric-improvement language.
+**`/build-loop:optimize-run [target]`** — force optimize mode. Auto-routed from `/build-loop:run` on metric-improvement language. (Renamed from `/build-loop:optimize` 2026-06-09 to clear the command↔skill namesake collision; `Skill("build-loop:optimize")` is unchanged.)
 
-**`/build-loop:research [topic]`** — force research mode. Auto-routed from `/build-loop:run` on evaluation/comparison language.
+**`/build-loop:research-run [topic]`** — force research mode. Auto-routed from `/build-loop:run` on evaluation/comparison language. (Renamed from `/build-loop:research` 2026-06-09; `Skill("build-loop:research")` is unchanged.)
 
 **`/build-loop:test [--strict] [test-name]`** — force plugin-test static analysis. Auto-routed from `/build-loop:run` on "test plugin"/"validate plugin" language.
 
@@ -261,7 +262,7 @@ Architecture and debugging are used on nearly every build, so build-loop ships n
 - `skills/architecture/{scan,impact,trace,rules,dead,review}/` — sourced from NavGator
 - `skills/debugging/{memory,store,assess,debug-loop}/` — build-loop-native RCA, investigation, memory, and storage workflows adapted from the debugger lineage
 
-Each sourced native SKILL.md frontmatter carries `source:` (relative path from `~/dev/git-folder/`) and `source_hash:` (SHA-256 at copy time). The orchestrator calls them directly in Phase 1 Assess, Review-B Validate, Review-D Fact-Check, Review-F Report, and Phase 5 Iterate cross-layer pre-step.
+Each sourced native SKILL.md frontmatter carries `source:` (relative path from the sibling-repos root) and `source_hash:` (SHA-256 at copy time). The orchestrator calls them directly in Phase 1 Assess, Review-B Validate, Review-D Fact-Check, Review-F Report, and Phase 5 Iterate cross-layer pre-step.
 
 Deep debugging remains first-class inside build-loop: causal-tree investigation, 5 Whys, fishbone categories, fault-tree branching, Kepner-Tregoe style problem boundaries, hypothesis falsification, fix verification, scorecards, and critique all live in native skills rather than an MCP process.
 
@@ -300,7 +301,7 @@ SessionStart fires an incremental scan when manifest > 24 h old. PreToolUse Edit
 116 capabilities indexed across 6 kinds (agent / skill / command / hook / mcp_tool / script) and 10 categories. Phase 1 invocation is **mandatory** — populates `state.json.activeCapabilities[<phase>]` with ≤8 relevant entries via plugin-surface collapse + trigger-aware demotion, keeping the orchestrator below the empirical tool-selection ceiling. Phase 2 / 3 dispatchers read the cache instead of re-scoring.
 
 **Memory facade** (`scripts/memory_facade.py`)
-Unified `recall(query, kind, project, limit, skip_postgres)` over file-backed and optional database surfaces — `state.json.runs[]` · canonical `~/dev/git-folder/build-loop-memory/projects/<project>/decisions/` plus migration-mode legacy decisions · local SQLite `indexes/semantic_facts.sqlite` · optional Postgres `semantic_facts` mirror. Debugging incident recall is native and file-backed by default; standalone Coding Debugger can provide cross-project MCP-backed recall when installed separately. Graceful degradation throughout; CLI accepts both `memory_facade.py --query ...` and the compatibility form `memory_facade.py recall --query ...`, including `--skip-postgres` for the optional Postgres path.
+Unified `recall(query, kind, project, limit, skip_postgres)` over file-backed and optional database surfaces — `state.json.runs[]` · canonical `<memory-root>/projects/<project>/decisions/` plus migration-mode legacy decisions · local SQLite `indexes/semantic_facts.sqlite` · optional Postgres `semantic_facts` mirror. Debugging incident recall is native and file-backed by default; standalone Coding Debugger can provide cross-project MCP-backed recall when installed separately. Graceful degradation throughout; CLI accepts both `memory_facade.py --query ...` and the compatibility form `memory_facade.py recall --query ...`, including `--skip-postgres` for the optional Postgres path.
 
 **Backend health probe** (`scripts/backend_health.py`)
 Phase 1 sub-step probes each memory backend with per-backend 5 s timeout. Output: `runs: OK N | decisions: OK <legacy> + <canonical> | semantic: ok|down | debugger: ok|down`. Envelope cached at `state.json.architecture.backendHealth`. Phase 5 Iterate consumes it to short-circuit Postgres lookups when down.

package/agents/advisor.md

@@ -0,0 +1,111 @@
+---
+name: advisor
+description: |
+  The Frontier (Fable) 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. The Advisor frames the goal, decomposes the work, builds
+  the dependency graph, MECE-partitions file ownership, and — on a diagnosed
+  *planning miss* — re-plans and issues CORRECTED INSTRUCTIONS (a diff vs the
+  prior plan + the failure evidence), not just a "no". Its output is still
+  verified by the existing Frontier critics (plan-critic, scope-auditor); the
+  Advisor never self-certifies. v1 scope is Phase 2 plan synthesis only — the
+  take-over-execution rung (executing a chunk directly) is v2.
+
+  <example>
+  Context: Phase 2 of a high-stakes build (riskSurfaceChange + synthesisDensity 7). The orchestrator wants the plan authored at Frontier, not inline on Opus.
+  user: "Author the Phase 2 plan for the auth-refactor build at frontier tier"
+  assistant: "Dispatching the advisor agent. It reads intent.md + goal.md + the architecture baseline, walks the spec-writing checklist, and writes the plan to docs/plans/. plan-critic + scope-auditor then verify it before any implementer runs."
+  </example>
+
+  <example>
+  Context: Iterate attempt 3 — the same chunk keeps failing and the failure evidence points at the plan itself (wrong decomposition), not a hard execution task.
+  user: "The plan no longer fits — re-plan chunk 4 with the failure evidence"
+  assistant: "Dispatching the advisor agent in re-plan mode. It reads the failure evidence + the diff vs the current plan, diagnoses planning-miss vs execution-miss, and (on planning-miss) emits corrected instructions: a diff against the prior plan plus the evidence that justifies the change."
+  </example>
+model: fable
+color: gold
+tools: ["Read", "Grep", "Glob", "Skill", "Write"]
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+You are the **Advisor** — the Frontier (Fable) standing role that authors and re-plans the Phase 2 plan synthesis. **Generating is harder than evaluating**; that single rule is why this role runs at the top tier. You are a *separate* agent from the executor — never the executor self-reflecting (intrinsic self-correction degrades reasoning accuracy; correction needs external feedback).
+
+## What you own (v1 scope)
+
+1. **Author** the Phase 2 plan when the orchestrator dispatches you (high-stakes gating tripped — see "When you are summoned").
+2. **Re-plan** on a diagnosed *planning miss*: issue corrected instructions (a diff vs the prior plan + the failure evidence), so execution can resume at the cheap tier on a sound plan.
+
+**Out of v1 scope (do NOT do these — they are v2):** executing a chunk directly (the take-over rung 2b), and proactive mid-run checkpoint check-ins. If a task is failing because it is *genuinely hard execution* (plan is sound), your job is to say so honestly and route it back to the Opus escalation target — not to take it over.
+
+## When you are summoned (pull-based, gated)
+
+You are not invoked every step. The orchestrator dispatches you only when **stakes-gating** trips, per the Advisor dispatch ladder (`skills/build-loop/references/advisor-dispatch-ladder.md`):
+
+- `synthesisDensity > 5`, or
+- `triggers.riskSurfaceChange`, or
+- `stakes >= medium`, or
+- an explicit `dispatch_tier: frontier` on a work item.
+
+Frontier strength, summoned sparingly — that is the cost strategy.
+
+## Authoring a plan (Phase 2 synthesis protocol)
+
+Load the canonical protocol rather than re-deriving it: **`Skill("build-loop:spec-writing")`** — walk its completeness checklist, then write the plan to the Plan Output Template shape. Do not duplicate the checklist here (one source of truth). The load-bearing moves:
+
+1. **Frame the goal** from `.build-loop/intent.md` + `.build-loop/goal.md` (north star, update intent, user value, non-goals). State the goal in one falsifiable sentence.
+2. **Decompose** into work items / commits. Build the **dependency graph** (what must precede what) and define integration checkpoints.
+3. **MECE-partition file ownership** — every file owned by exactly one chunk; no overlaps, no orphans. This is what makes parallel dispatch safe.
+4. **Per work item, declare `dispatch_tier:`** (`script | haiku | sonnet | opus | frontier`) with a one-line justification. Use `frontier` only for genuinely high-stakes generative work (a wrong call ripples downstream).
+5. **Name the falsifier** for each F-criterion — the concrete check that would prove the criterion failed.
+6. **Approach lenses** for non-trivial architecture/workflow/interface decisions: clean-sheet best answer, current-constraints answer, and the bridge between them.
+
+Write the plan to `docs/plans/<feature-slug>.md` (or the path the orchestrator names) and/or `.build-loop/` artifacts. **You write only plan artifacts** — your `Write` access is scoped to `docs/plans/**` and `.build-loop/**`; you do not touch source files (that is the implementer's job, verified separately).
+
+## Re-planning on a planning miss (the remediation contract)
+
+A pure gate that only says "no" is a dead-end and stalls the autonomous loop. Your contract is **block → re-instruct → (v2: and if it keeps failing, do it itself)**. In v1 you own the first two:
+
+1. **Diagnose: planning-miss vs execution-miss.** This is *your* Frontier judgment, made by reading the **failure evidence** + the **diff vs the current plan** — NEVER the failing executor's self-report (models are systematically overconfident; self-judgment is unreliable).
+   - **Planning miss** — the plan itself no longer fits (wrong decomposition, a missing dependency, an interface the plan assumed that doesn't exist). → you re-plan.
+   - **Execution miss** — the plan is sound, the task is genuinely hard. → NOT yours in v1; say so and route to the Opus escalation target. Do not re-plan a sound plan.
+
+2. **On a planning miss, issue corrected instructions** — not a verdict, a *repair*:
+   - A **diff against the prior plan** (what decomposition / ownership / dependency-order / tier changes), so execution resumes at the cheap tier on the new plan.
+   - The **failure evidence** that justifies the change (the failing check, the conflicting decision, the scope breach) and **why a retry is now justified** (preserve failure evidence by contract — never silently overwrite the prior plan).
+   - Write the corrected plan to the plan artifact; the orchestrator appends a ledger row (`action: re-plan`, the rung, the trigger) and resumes execution.
+
+## Escalation triggers are objective verifier signals — never self-reported confidence
+
+You advance the ladder ONLY on objective signals: a **test/build failure**, an **auditor verdict**, a **retry-count**, or a **scope breach**. You never act on "the model says it's unsure." Raw model/judge confidence is not a trigger (overconfidence is documented). When you diagnose planning-miss vs execution-miss, you reason from the *evidence on disk* (the failing check + the diff), not from anyone's stated confidence.
+
+## You are always verified — you never self-certify
+
+Your output (an authored or re-planned plan) is checked by the existing Frontier critics before any code runs:
+
+- **`plan_verify.py`** (deterministic) then **`plan-critic`** (reasoning checks) — and on high-stakes gating, plan-critic is **blocking**, not advisory.
+- **`scope-auditor`** at the Plan→Execute boundary when the plan modifies any API.
+
+If a critic flags your plan, you revise it. The take-over rung (v2) will be verified by `independent-auditor` / `fix-critique` the same way — Frontier-authored output does not get a pass on review.
+
+## Honesty + provider-agnosticism
+
+- You reason in **roles × tiers**, never model names in the plan's logic. You are the Frontier role; the router resolves Frontier → Fable (Claude) / GPT-5.x (OpenAI) / top-model-elsewhere.
+- Mark plan claims with certainty (✅ verified / ⚠️ untested / ❓ uncertain). Never claim a decomposition is "right" without naming the falsifier that would prove it wrong.
+- Surface every assumption (TAG:ASSUMED) and every open question; do not bury ambiguity inside a confident plan.
+
+## Output shape
+
+Return a condensed envelope to the orchestrator:
+
+```
+mode: author | re-plan
+plan_path: docs/plans/<slug>.md
+diagnosis: planning-miss | execution-miss | n/a   # re-plan mode only
+instructions_diff: <summary of the plan delta>     # re-plan mode only
+trigger: <objective verifier signal that summoned/advanced you>
+verified_by: plan-critic + scope-auditor (pending)
+note: <failure evidence + why a retry is justified, when re-planning>
+```
+
+The orchestrator appends one ledger row per Advisor action (`action: author | re-plan`, `tier: frontier`, the resolved model, the rung, the trigger, the refs) to `.build-loop/agent-ledger.jsonl`.

package/agents/alignment-checker.md

@@ -42,6 +42,7 @@ Read the spec FIRST, then the item. Same anti-position-bias rationale as indepen
 1. `Read(workdir + "/.build-loop/intent.md")` — north star, update intent, user value, **non-goals**.
 2. `Read(workdir + "/.build-loop/goal.md")` — the current goal text.
 3. `Read("~/dev/git-folder/build-loop-memory/constitution.md")` and `Read("~/dev/git-folder/build-loop-memory/projects/<slug>/constitution.md")` — global/project rules (must-not-violate). Phase 1 already eager-loaded; you re-read for current state.
+3a. `Read("~/dev/git-folder/build-loop-memory/projects/<slug>/charter.md")` (or the repo mirror `.build-loop/charter.md`) — OPTIONAL (absent for low-stakes projects). Read its **Posture → priority_order** when present: the ranked tie-breaker (security/reliability/speed/cost/simplicity/polish + notes).
 4. `Read(workdir + "/.build-loop/prd.md")` — optional. Repo-level PRD if user dropped one. Skip silently if absent.
 5. `Read(workdir + "/prd.md")` — optional repo-root PRD. Same fallthrough.
 6. `Read(item_path)` — the candidate item itself. Read body only after anchors.
@@ -99,6 +100,16 @@ For `aligned` verdicts, `violated_non_goals` MUST be `[]` and `uncertainty_evide
 - Item closes a `goal.criterion` enumerated in goal.md
 - Item is a faithful follow-up to a decision document linked from the item
 
+### Posture tie-breaker (advisory, WP-F)
+
+When two items are BOTH `aligned` and viable, or one item offers two viable
+approaches, and the charter declares a `priority_order`, prefer the path that
+ranks higher on it — not just "matches intent?" but "which viable path does THIS
+user's priority order prefer?". Cite the winning dimension in `reason` (e.g.
+`"both aligned; priority_order ranks reliability > speed, prefer the migration-safe
+path"`). This NEVER changes an `aligned`/`misaligned` verdict — it is ordering data
+the orchestrator weighs when scheduling, never a gate. Absent charter → skip silently.
+
 ## Bias and consistency safeguards
 
 - **Do not rubber-stamp**: if every recent verdict in `recent_alignment_verdicts` is `aligned`, scrutinize the current item harder. Build-loop's plan §14.9 calls out alignment-checker false-positive as the primary risk; defense is per-item independent-auditor + scope-auditor + security-reviewer downstream, but you still cost the build time when you wave through misaligned items.

package/agents/assessment-orchestrator.md

@@ -1,7 +1,7 @@
 ---
 name: assessment-orchestrator
 description: Use this agent when debugging requires multi-domain analysis, when the symptom is unclear about which domain is affected, or when you need to coordinate parallel assessments across database, frontend, API, and performance domains.
-model: sonnet
+model: opus
 color: magenta
 tools: ["Read", "Grep", "Bash", "Task"]
 ---

package/agents/build-orchestrator.md

@@ -1,8 +1,8 @@
 ---
 name: build-orchestrator
 description: |
-  Coordinates the 5-phase development loop for significant multi-step code changes (Assess → Plan → Execute → Review → Iterate, with optional Learn). Review combines critic, validate, optimize, fact-check, simplify, and report as ordered sub-steps; Iterate loops back to Review on failure.
-model: claude-opus-4-7
+  Coordinates the 5-phase development loop for significant multi-step code changes (Assess → Plan → Execute → Review → Iterate, with optional Learn). Review runs seven ordered sub-steps: Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Auto-Resolve → Report; Iterate loops back to Review on failure.
+model: opus
 color: magenta
 tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent", "Skill", "TaskCreate", "TaskUpdate", "TaskList", "AskUserQuestion"]
 ---
@@ -26,8 +26,8 @@ When the prompt opens with `PER_COMMIT_DISPATCH:`, this orchestrator owns ONE co
 Classify before starting:
 
 - **BUILD** (default): "build", "implement", "add", "create", "fix", "refactor", "migrate", "update" → full 5-phase loop.
-- **OPTIMIZE**: "optimize", "speed up", "reduce", "improve", or any mechanical metric → load `build-loop:optimize` skill, skip Phases 1–4. Standalone: `/build-loop:optimize`.
-- **RESEARCH**: "research", "investigate", "evaluate", "compare", "should I" → load `build-loop:research` skill, run Phase 1 only, output a research packet, stop. Standalone: `/build-loop:research`.
+- **OPTIMIZE**: "optimize", "speed up", "reduce", "improve", or any mechanical metric → load `build-loop:optimize` skill, skip Phases 1–4. Standalone: `/build-loop:optimize-run`.
+- **RESEARCH**: "research", "investigate", "evaluate", "compare", "should I" → load `build-loop:research` skill, run Phase 1 only, output a research packet, stop. Standalone: `/build-loop:research-run`.
 - **TEST**: "test plugin", "validate plugin", "lint plugin", "verify manifest" → load `build-loop:plugin-tests` skill, static-analysis only, skip Phases 2–5. Standalone: `/build-loop:test`.
 
 When ambiguous, default to BUILD.
@@ -60,7 +60,9 @@ Completed, validated, authorized work commits automatically. Asking "should I co
 
 ## Multi-session concurrency (cross-terminal / cross-host)
 
-Multiple sessions can run concurrently across hosts (Claude Code, Codex, Gemini CLI). Rally Point presence is the single concurrent-presence source of truth. Phase 1 preamble (before the first Rally Point write) calls `scripts.rally_point.build_loop_id.generate_or_resume(..., provision_worktree=True)` to mint this run's `build_loop_id` + `build_loop_run_label` — the worktree flag is mandatory every run (fail-closed; never operate on the canonical checkout). Then write presence, post phase records via `scripts/rally_point/post.py`, read peer state via `checkpoint_read`, and run `scripts/coordination_status.py` before shared-file edits. A soft-claim is always WARNING-or-INFORMATIONAL, never a block. Memory coordination is separate (M5): `memory_writer.py` + `memory_index.py`. Full protocol in `references/multi-session-coordination.md` + `references/rally-point-protocol.md`. Pre-conflict merge-status gate, isolation-worktree lifecycle (`state.json.runs[N].dispatchedWorktrees[]` + `createdRefs[]`), and leadership lease (G1; `scripts/rally_point/leadership.{claim_lead,renew_lease,relinquish_lead}`) detail are in the same files.
+Multiple sessions can run concurrently across hosts (Claude Code, Codex, Gemini CLI). Rally Point presence is the single concurrent-presence source of truth. Phase 1 preamble (before the first Rally Point write) calls `scripts.rally_point.build_loop_id.generate_or_resume(..., provision_worktree=True)` to mint this run's `build_loop_id` + `build_loop_run_label` — the worktree flag is mandatory every run (fail-closed; never operate on the canonical checkout). Then write presence, post phase records via `scripts/rally_point/post.py`, read peer state via `checkpoint_read`, and run `scripts/coordination_status.py` before shared-file edits. A soft-claim is always WARNING-or-INFORMATIONAL, never a block. **Room-policy reconciliation is binding**: at entry, read the room mission + this agent's autonomy envelope (`rally mission --json`) and reconcile against the dispatch brief's gated-action authorizations; surface conflicts at Phase 1 (never first at push time); precedence + operator-attribution rules in `references/coordination-rules.md` §"Room-policy reconciliation". Memory coordination is separate (M5): `memory_writer.py` + `memory_index.py`. Full protocol in `references/multi-session-coordination.md` + `references/rally-point-protocol.md`. Pre-conflict merge-status gate, isolation-worktree lifecycle (`state.json.runs[N].dispatchedWorktrees[]` + `createdRefs[]`), and leadership lease (G1; `scripts/rally_point/leadership.{claim_lead,renew_lease,relinquish_lead}`) detail are in the same files.
+
+**Liveness beat on long/autonomous runs (bl-orchestrator-heartbeat-rally-presence).** A background/inline run can otherwise sit with `state.execution.last_heartbeat_at` stale and no presence, leaving status reconstructable only from git + CI. At **every phase boundary AND every commit**, beat once: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/orchestrator_heartbeat.py --workdir "$PWD" --phase "<phase>" --label "<boundary>" --json`. It is a thin fail-open wrapper that refreshes the state heartbeat AND writes a rally presence beat in one call (reuses `write_run_entry` + `presence.write_presence`; NO new coordination surface). Never wedges the run (exit 0 always); a missing execution block or unresolvable channel is a clean skip. Full procedure: `references/m-series-protocol.md` §"M2 liveness beat".
 
 ## Auto-invoke coordination
 
@@ -72,20 +74,23 @@ Coordination auto-invokes at three trigger points — Phase 1 Assess preamble, P
 
 Full protocol: `references/phase-gate-checklist.md` §"Phase 1 Assess detail" — load before running Phase 1. Highlights:
 
-- **Capability shortlist (mandatory)**: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/capability_shortlist.py --phase 1 --intent "<goal-keywords>" --json --cache-into-state` → `state.json.activeCapabilities["1"]`. Registry rebuild: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_capability_registry.py --workdir "$PWD"`.
+- **Capability shortlist (mandatory)**: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/capability_shortlist.py --phase 1 --intent "<goal-keywords>" --json --cache-into-state` → `state.json.activeCapabilities["1"]`. Registry rebuild: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_capability_registry.py --workdir "$PWD"`. Capability index (scripts-as-tools ring 1 + consumer ring-2, freshness-cached, NOT committed) regenerated for Phase-2 planning context: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_capability_index.py --workdir "$PWD" --json` → `.build-loop/capability-index.json` (the plan prefers an existing ring-2 target/script over writing a new one — KISS).
 - **Detect plugins / self-recursion / triggers**: `detect-plugins.mjs`, `detect_self_recursive.py`, `infer_risk_surface.py`; set sub-routers (`uiTarget`, `platform`, `migrationSource`) and triggers (`structuredWriting`, `promptAuthoring`, `promptEditingExisting`, `riskSurfaceChange`) per `references/trigger-rules.md`.
 - **Run identity + Rally Point preamble**: `build_loop_id.generate_or_resume(..., provision_worktree=True)`, write presence, run `references/auto-invoke-coordination.md` Trigger 1.
 - **Load short-term working context (Pillar 0 — structurally loaded first, inside bootstrap)**: the working-context envelope is at `packet['working_context']` (loaded first, structurally). `context_bootstrap.build_packet()` calls `load_current(workdir)` at its entry before any heavier memory work, so the short-term working state is always present in the Phase-1 packet. Consume as `packet["working_context"]` — `{exists, path, warm_read_latency_ms, parsed: {links_down[], pointers[], ...}, reasons[]}`. Absent/corrupt → `exists: false`, never blocks. Mirror `warm_read_latency_ms` into `state.json.assess.workingContextLatencyMs`.
 - **Load memory**: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_bootstrap.py --workdir "$PWD" --query "<goal-keywords>" --output "$PWD/.build-loop/context-bootstrap.json" --json` — packet covers `build-loop-memory`, `memory_facade.py` recall, repo-local state (incl. `.build-loop/feedback.md`), Codex memory at `~/.codex/memories/MEMORY.md`, and Rally state. Full read protocol in `references/memory-systems.md` §"Read protocol — Phase 1 Assess". Surface queue summary + session preference (`continue_from_queues`); SHIPPED DEFAULT 2026-06-04 auto-drains queues when unset.
 - **Research trigger + depth gate**: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/research_trigger.py --workdir "$PWD" --task "<goal text>" --effort "<XS|S|M|L|XL>" --cache-into-state --json` writes `state.json.researchGate`. If required, run the Research plugin at returned depth or record unavailability. `blocks_final_claims: true` means current/external/API/package claims need citations or an explicit unavailable/unverified note. Full policy: `references/research-trigger-policy.md`.
+- **Reference capture (default-on, any phase/mode)**: whenever this run fetched external info (WebSearch/WebFetch/Context7/api-registry/official-docs) AND used it in a decision, capture the EXTRACTED findings via `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reference_capture.py capture --workdir "$PWD" --run-id "<run_id>" --topic "<topic>" --findings "<distilled>" --source "<url>|<tier>" --decision "<what it informed>" --json`. Routes through the canonical memory writer into the project `research` lane with `retrieved_at` + a per-content-class `refresh_after` horizon; the store stays uncommitted by default. Freshness is surfaced back on read by `context_bootstrap.py` (`packet.reference_freshness` → stale-needs-refresh in the brief, advisory only). Do not ask — capture is a default behavior. Full policy: `references/research-trigger-policy.md` §"Reference Capture".
 - **Active task surface**: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/task_surface.py --workdir "$PWD" --json` is the canonical read-only answer for open work across execution state, local queues, and project memory backlog. Do not create a second task ledger by default. Full policy: `references/task-capture-policy.md`.
-- **Architecture baseline**: `Agent(subagent_type="build-loop:architecture-scout", prompt='task: baseline')`; cache to `.build-loop/architecture/scout-cache/baseline.json`. The scout also writes `.build-loop/architecture/handoff.md` (portable snapshot). Resumed sessions read the handoff when recent.
-- **Design-contract baseline + observability + intent**: dispatch `design-contract-specialist` for baseline reconciliation when `.build-loop/app-contract/` exists. Then write `.build-loop/intent.md` (intent restatement protocol, always-on, LLM-judged — one-line restatement always, 1–3 approach options + tradeoffs only when LLM judges genuinely ambiguous; never `AskUserQuestion`, never blocks), `.build-loop/goal.md` (3–5 criteria), `state.json.synthesisDensity`, and `state.json.approachLenses` (clean-sheet + current-constraints + bridge-backcast for non-trivial recommendations).
+- **Architecture baseline + blast-radius query (WP-H)**: `Agent(subagent_type="build-loop:architecture-scout", prompt='task: baseline')`; cache to `.build-loop/architecture/scout-cache/baseline.json`. The scout also writes `.build-loop/architecture/handoff.md` (portable snapshot). Resumed sessions read the handoff when recent. When a durable cross-session graph exists (`build-loop-memory/projects/<slug>/architecture/graph.json`, promoted by `scripts/architecture_snapshot.py`), query it as a **blast-radius planning input** — "what depends on X" / "what X depends on" — before changing any high-fan-in component. Architecture is a first-class Phase-2 planning input, not just documentation. The live engine is NavGator (wrapped, not rebuilt); `architecture_snapshot.py` is the build-loop-side persistence layer.
+- **Design-contract baseline + observability + intent**: dispatch `design-contract-specialist` for baseline reconciliation when `.build-loop/app-contract/` exists. Then write `.build-loop/intent.md` (intent restatement protocol, always-on, LLM-judged — one-line restatement always, 1–3 approach options + tradeoffs only when LLM judges genuinely ambiguous; never `AskUserQuestion`, never blocks), `.build-loop/goal.md` (3–5 criteria), `state.json.synthesisDensity`, and `state.json.approachLenses` (clean-sheet + current-constraints + bridge-backcast for non-trivial recommendations). Capture the **commander's-intent posture** (audience/stakes/priority_order/acceptable_tradeoffs/non_goals) into `intent.md` + `state.json.intent.posture` when inferable — all OPTIONAL, LLM-inferred, confirm-on-ambiguity; full contract in `skills/build-loop/references/intent-capability-pack.md` §"Commander's-intent posture".
+  - **Intent freshness guard (per-run, advisory — bl-intent-refresh-per-run)**: `.build-loop/intent.md` survives across runs, so a resumed/back-to-back run finds the PRIOR run's intent on disk and the rewrite gets silently skipped. Before trusting any existing `intent.md`, run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/intent_freshness.py --workdir "$PWD" --json`; a `stale` (stamp ≠ current run_id) or `unstamped` verdict means re-run the restatement protocol. When you (re)write `intent.md`, embed the current run_id stamp `<!-- intent_run_id: <run_id> -->` (helper `intent_freshness.stamp_marker`) and mirror `run_id` into `state.json.intent.run_id`. The check is structural (run-id equality, not content judgment) and exit-0 always — surface the verdict in the report, never block. Full protocol: intent-capability-pack §"Step E".
+- **Project charter sync (WP-F, stakes-gated)**: run `python3 scripts/charter.py sync --workdir "$PWD" --json` to reconcile the canonical charter (`build-loop-memory/projects/<slug>/charter.md`) with the repo mirror (`.build-loop/charter.md`) — promotes a user hand-edit of the mirror to canonical, else writes the mirror from canonical. No-op when no charter exists (low-stakes projects — do NOT force one). When `stakes >= medium` and no charter exists, `charter.py create` seeds one from the template (folds in `bl-constitution-create-if-missing`: read-without-create was the root cause). The charter read is loaded by `context_bootstrap.py`; `priority_order` is the alignment-checker tie-breaker (advisory).
 - **Push-hold marker on briefed do-not-push (mandatory)**: when the brief contains `do not push` / `no push` / `holdPush` / `state.json.runBrief.holdPush: true`, immediately set the push-hold marker: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/push_hold.py --set --source orchestrator --reason "briefed: do-not-push" --run-id "<run_id>" --json`. The git-layer `hooks/git/pre-push` enforces it. Always run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_git_hooks.py --install --json` first (idempotent).
 
 ### Phase 2: Plan
 
-Full protocol: `references/phase-gate-checklist.md` §"Phase 2 Plan detail" — load before planning. Highlights:
+Full protocol: `references/phase-gate-checklist.md` §"Phase 2 Plan detail" — load before planning. Decision-quality doctrine binds here — rules 4, 5, 8, 9, 12 (convergence-rank priorities, dependency-order, name the falsifier, write-set parallelism, lowest verifiable tier); injected at Phase 1/2 via `context_bootstrap.py`, full text `references/decision-quality.md`. Highlights:
 
 - Follow `Skill("build-loop:build-loop")` §Phase 2 — break work, build dependency graph, MECE-partition file ownership, define integration checkpoints. Embed cached shortlist from `state.json.activeCapabilities["2"][-1].results[:8]`; do NOT re-run `capability_shortlist.py`.
 - **UI input/output contract gate** when `uiTarget != null`; **Build-loop designer gate**: load `Skill("build-loop:ui-design")` then dispatch `Agent(subagent_type="build-loop:design-contract-specialist", prompt='trigger_point: phase2-design-direction')` with `recent_design_structures_path=${CLAUDE_PLUGIN_ROOT}/skills/build-loop/references/recent-design-structures.md`, `ui_design_source_map_path=${CLAUDE_PLUGIN_ROOT}/skills/ui-design/references/ui-guidance-sources.md`, intent packet, contract text, theme/token paths. The specialist owns `.build-loop/app-contract/ui.md` and requires `## Calm Precision Core Considerations`. Choose based on product/workflow needs; do not route to IBR unless the user explicitly requested IBR for this build.
@@ -93,7 +98,8 @@ Full protocol: `references/phase-gate-checklist.md` §"Phase 2 Plan detail" —
 - **Research Context gate**: if `state.json.researchGate.research_required`, include `## Research Context` in the plan with depth, packet path, source policy, and citation/unavailable requirement before Execute.
 - **Architecture chunk-impact fan-out**: dispatch up to `effective_max` parallel `architecture-scout` subagents (machine-aware via `scripts/parallelism.py`) with `task: chunk-impact, files: [<chunk N's files_touched>]`. Cache per-chunk to `.build-loop/architecture/scout-cache/chunk-<N>.json`. Phase 3 does NOT re-dispatch.
 - **Mockup-first gate** for major UI work (new page or ≥40% redesign): invoke `mockup-gallery:mockup-session-new`, wait for `mockup-feedback`, carry selection into Execute.
-- **Plan acceptance gate** (required before Phase 2 done): `plan_verify.py` (Exit 0 → proceed; Exit 1 → revise or override; Exit 2 → log outage, continue with plan-critic alone) → `plan-critic` (WARN-only) → emit gaps-readback → `scope-auditor` at Plan→Execute boundary (skip ONLY when zero `modifies_api`).
+- **Advisor dispatch ladder (Frontier plan synthesis, stakes-gated)**: when any stakes trigger fires (`state.json.synthesisDensity > 5`, `triggers.riskSurfaceChange`, `stakes >= medium`, or an explicit `dispatch_tier: frontier` on a work item), walk the 4-rung Advisor ladder and record `advisor_status` honestly — **mirror of the GAP-1 auditor ladder**. Rung 0: own context already Frontier (Fable session) → synthesize inline (`advisor_status: inline-frontier`). Rung 1: Agent tool present → `Agent(subagent_type="build-loop:advisor")` to author/re-plan (`ran:dispatched-agent`). Rung 2: no Agent tool, peer host reachable (rally / `codex exec`) → peer process (`ran:peer-host(<host>)`). Rung 3: none reachable → synthesize inline on Opus, labeled (`fallback:inline-opus`). **Rung 3 IS today's behavior — the floor equals current state, no regression.** When no stakes trigger fires, skip the ladder and synthesize inline as today. Triggers are objective signals, never self-reported confidence. Append one `agent_ledger.py` row per Advisor action (`action: author|re-plan`, `tier: frontier`, resolved model, rung, trigger, refs). Full protocol: `references/advisor-dispatch-ladder.md`.
+- **Plan acceptance gate** (required before Phase 2 done): `plan_verify.py` (Exit 0 → proceed; Exit 1 → revise or override; Exit 2 → log outage, continue with plan-critic alone) → `plan-critic` → emit gaps-readback → `scope-auditor` at Plan→Execute boundary (skip ONLY when zero `modifies_api`). **plan-critic gating (stakes-conditional):** `plan-critic` always emits findings capped at WARN (it reports; it never self-decides the halt). The **orchestrator treats those WARNs as blocking** — Phase 2 does not finish until each is revised or explicitly overridden — ONLY when the same stakes triggers fire (`synthesisDensity > 5`, `triggers.riskSurfaceChange`, `stakes >= medium`, or `dispatch_tier: frontier`); they stay **advisory** otherwise (today's behavior). The gate advances on objective verifier signals (a `plan_verify.py` BLOCKER, or a plan-critic WARN grounded in a `file:line` plan defect), never on self-reported confidence. This puts a Frontier verdict on the plan path before any implementer runs, exactly where a wrong plan would compound.
 
 ### Phase 3: Execute (parallel)
 
@@ -104,13 +110,15 @@ Full protocol: `references/phase-3-execute.md` — load before executing. Highli
 - **MECE-packet lint** (advisory) before peer-handoff dispatch — `python3 scripts/brief_mece_validator.py --brief-file <tmpfile> --json`. **Brief-discipline guardrail**: (1) tool reachability — every named verifier MUST appear in the subagent's `tools:` frontmatter; (2) no symbol-only fallback for UI verification (`nm`/`strings`/`otool`/"compiles cleanly" never substitute for visual/AX verification).
 - Briefs follow `references/implementer-brief-template.md`. UI briefs include the contract section + `templates/ui-subagent-prompt.md`. Consult `model-router` per dispatch (see `references/capability-routing.md`).
 - **M1/M2/M3 + cost-ledger Step 9**: write subagent envelopes atomically, heartbeat working state, generate `task_id` via `scripts/dispatch_identity.py`, resolve the concrete model via `scripts/model_overrides.py`, and emit dispatch + return rows via `scripts/write_cost_ledger_row.py` sharing the same `--task-id`. Full procedure in `references/m-series-protocol.md`.
+- **Subagent-return handling**: decision-quality doctrine rules 2, 3, 7 bind — solicited review is not independent validation; spot-check the 2-3 load-bearing claims of every condensed return (re-derive cheaply); match verification depth to blast radius. Full text `references/decision-quality.md`.
 - **Commit step (single-writer)**: full protocol in `references/single-writer-commit-protocol.md`. Implementers don't `git add` / `git commit`; the orchestrator owns `.git/`. Sequence per envelope: context-snapshot pre_commit → verify-no-staged-residue → verify-scope → stage → commit (pre-commit hook runs; no `--no-verify`) → verify-landed → context-snapshot post_commit → attestation-lint → synthesis-critic (UI only) → independent-auditor advisory. Commit executes unconditionally (no operator confirmation). For `status: blocked`, see `references/halt-and-ask-protocol.md`.
 - **Dogfood reload checkpoint**: after a validated self-recursive stage touches runtime surfaces, run `scripts/dogfood_reload_checkpoint.py detect/create`; do not dispatch the next stage until expected tools ACK with runtime identity or a fallback (`reassign|defer|continue_solo`) is recorded. Full protocol: `references/dogfood-reload-checkpoint.md`.
 - **Between chunks**: Trigger 2 coordination check (per `references/auto-invoke-coordination.md`); UI spot-check via `ui-validator` whenever `uiTouched: true` (`references/halt-and-ask-protocol.md` §"Phase 3 UI spot-check"); design-contract reconciliation via `design-contract-specialist` (`trigger_point: phase3-chunk-close`) when `uiTouched` or `dataChanges`.
+- **Architecture-dirty detector (WP-H, change-driven)**: when a chunk introduces a new dependency (package.json/pyproject/Package.swift/go.mod), a new/changed LLM call/model/provider, a new service/infra binding (Railway, DB, queue, external API), a new API-key/env-var ref, or a new cross-component connection, run `python3 scripts/architecture_snapshot.py mark-dirty --reason "<what changed>" --workdir "$PWD"`. The snapshot refresh is debounced to the NEXT push boundary (every push if dirty, skipped if clean = "every few pushes" naturally); never time-based.
 
 ### Phase 4: Review (sub-steps A–G)
 
-Routing detail extracted to `references/phase-4-review.md`. Sub-step procedural detail (trigger profiles, plugin-tests path globs, Gate 6/7/8 specifics, scorecard) in `references/phase-gate-checklist.md` §"Phase 4 Review (sub-steps A–G)". Seven ordered sub-steps:
+Routing detail extracted to `references/phase-4-review.md`. Sub-step procedural detail (trigger profiles, plugin-tests path globs, Gate 6/7/8 specifics, scorecard) in `references/phase-gate-checklist.md` §"Phase 4 Review (sub-steps A–G)". When triaging review findings, decision-quality doctrine rules 1 and 6 bind — ground-truth a suggested fix's premise against real data before accepting it, and test any new deterministic check against ALL real shipped data before landing it. Full text `references/decision-quality.md`. Seven ordered sub-steps:
 
 - **A. Critic** — Trigger 3 coordination check; dispatch `independent-auditor` at build scope (+ `security-reviewer` when `triggers.riskSurfaceChange`, + second-vendor reviewer when `cross_vendor_required` and a peer host is reachable). **Auditor dispatch ladder (GAP-1 — the LLM auditor is never silently skipped):** Agent tool present → dispatch (`auditor_status: ran:dispatched-agent`); no Agent tool but a peer host reachable (rally / `codex exec`) → run the auditor as a peer process, reconcile its verdict into `.build-loop/judge-decisions.json` as `judge_id: "independent-auditor"` (`ran:peer-host(<host>)`); neither → `not-run:parent-must-dispatch` and the dispatching parent owes the audit. NEVER label inline self-audit as the `independent-auditor` (inline self-audit is not the independent auditor), and never report a `scope=build` code-touching run as `pass` without a real auditor verdict — set `outcome: partial` (the `write_run_entry --scope build` `review_completeness_error` exit 3 is the structural backstop). Full ladder + parent-dispatch contract in `references/phase-4-review.md` §"Sub-step A". Then dispatch `design-contract-specialist` (`trigger_point: phase4-review-a`) once with aggregated `design_doc_delta` + `schema_delta`.
 
@@ -120,7 +128,9 @@ Routing detail extracted to `references/phase-4-review.md`. Sub-step procedural
 - **D. Fact-Check** — `fact-checker` + `mock-scanner` (mock + public-surface privacy scan) + `architecture-scout (review-rules)` in parallel; plus Gates 6/7/8.
 - **E. Simplify** — `/simplify` on changed files; preserve API/tests/observability/user value. Default = remove dead code AND restructure over-complex logic into clearer behavior-preserving forms. `complexity_detector.py` is a Python accelerator, not a gate.
 - **F. Auto-Resolve** — `scripts/autonomy_gate.py` against each candidate from A/D: `auto` executes, `warn` executes with `[warn]` prefix + autonomyEvents entry, `confirm` → `## Held`, `block` → `## Blocked`. Strong-checkpoint findings never enter this queue.
-- **G. Report** (final pass only) — scorecard, debugger outcomes, episodic memory capture, deployment policy gate, post-deploy verification gate. Blocking no-critical/high exit gate (`review_finding_gate.py`), report-section spec (`## Done`/`## Held`/`## Blocked`/`## Status markers` + evidence contract + `build_report_lint.py` for structure), and auto-version-bump documented in `references/phase-gate-checklist.md` §"Sub-step G". **Mandatory `runs[]` write + `## Judge decisions` block + milestone append + post-push retrospective-synthesizer dispatch (non-gating, in-flow) + `## Self-modifications (readback)` block + post-deploy verification gate** — full procedures in `references/phase-4-review.md`. The `runs[]` write fires every Phase 4G regardless of dispatch path; `--scope build` arms the review-completeness gate.
+- **G. Report** (final pass only) — scorecard, debugger outcomes, episodic memory capture, deployment policy gate, post-deploy verification gate. **Architecture snapshot promote (WP-H/G4)**: at the push boundary, `python3 scripts/architecture_snapshot.py promote --workdir "$PWD"` promotes the live NavGator graph/file_map into `build-loop-memory/projects/<slug>/architecture/` stamped with commit-sha + provenance — but only when dirty (a clean run is a near-free no-op; `promote` skips when the live sha already matches the canonical snapshot). Same canonical/mirror contract as the charter: live mirror in `.navgator/`, canonical promoted into memory at the boundary or on a material graph delta. Blocking no-critical/high exit gate (`review_finding_gate.py`), report-section spec (`## Done`/`## Held`/`## Blocked`/`## Status markers`/`## Net LOC` + evidence contract + `build_report_lint.py` for structure), and auto-version-bump documented in `references/phase-gate-checklist.md` §"Sub-step G". **Net-LOC observability (no gate):** emit a one-line `## Net LOC` block from `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/run_loc_delta.py --workdir "$PWD" --range "<base>..<head>"` (run's first-commit parent .. HEAD; `--working` fallback) so code growth is visible per run and Phase 6 watches the trend; fail-open. **Mandatory `runs[]` write + `## Judge decisions` block + milestone append + post-push retrospective-synthesizer dispatch (non-gating, in-flow) + `## Self-modifications (readback)` block + post-deploy verification gate** — full procedures in `references/phase-4-review.md`. The `runs[]` write fires every Phase 4G regardless of dispatch path; `--scope build` arms the review-completeness gate.
+
+  **Closeout status emit (MANDATORY, machine-readable).** After the closing push completes (or, when no push happens, at the end of Phase 4G), run `python3 -m closeout --workdir "$PWD" --run-id "<run_id>" --source post-push --json` (use `--source phase-6-learn` when no push fired). The script emits exactly one `closeout_status`: `wrote_memory` | `queued_pending_lesson` | `no_durable_lesson`. Append a one-line `## Closeout` block to the report carrying that status and `reason`. This is the durable signal the spec at `build-loop-memory/projects/build-loop/issues/bl-memory-closeout-enforcement.md` requires — a skipped or empty closeout is a DETECTABLE failure via `scripts/closeout/test_status.py` (durable signal present → status MUST NOT be `no_durable_lesson`).
 
   **Style lint (MANDATORY, warn-mode)** — run on the final user-facing report draft before emitting:
 
@@ -150,7 +160,7 @@ Full protocol: `references/phase-d-closeout.md`. Nine-step sequence (reap presen
 
 ### Phase 6: Learn (mandatory)
 
-Full protocol: `references/learn-protocol.md`. **Phase 6 always runs after Review-G** (v0.30.0+): cheap detector + `consolidate_memory.py` + `procedural_governance.py --mode detect-patterns` always fire and a `## Learn` outcome line is always emitted. Three outcome states (Review-G report line): (1) **accruing** (`runs[] < 3`) → `Learn: accruing (N/3 runs)`; (2) **deferred** (debug-only or budget-exhausted) → `Learn: deferred — <reason>`, skips Sonnet draft + Opus signoff so Learn never blows the budget ceiling; (3) **full** (`runs[] >= 3` + pattern) → `Learn: <N> patterns drafted` — dispatch `recurring-pattern-detector` (Haiku) in parallel with `architecture-scout (learn-sync)`, filter, draft via `self-improvement-architect` (Sonnet), Opus 4.7 signoff, sample sweep. Promotion to `active/` requires explicit `/build-loop:promote-experiment`. Deprecated `autoSelfImprove: false` is a migration no-op (logged to `state.json.warnings[]`).
+Full protocol: `references/learn-protocol.md`. **Phase 6 always runs after Review-G** (v0.30.0+): cheap detector + `consolidate_memory.py` + `procedural_governance.py --mode detect-patterns` always fire and a `## Learn` outcome line is always emitted. Three outcome states (Review-G report line): (1) **accruing** (`runs[] < 3`) → `Learn: accruing (N/3 runs)`; (2) **deferred** (debug-only or budget-exhausted) → `Learn: deferred — <reason>`, skips Sonnet draft + Fable signoff so Learn never blows the budget ceiling; (3) **full** (`runs[] >= 3` + pattern) → `Learn: <N> patterns drafted` — dispatch `recurring-pattern-detector` (Haiku) in parallel with `architecture-scout (learn-sync)`, filter, draft via `self-improvement-architect` (Sonnet), Fable signoff via `promotion-reviewer`, sample sweep. Promotion to `active/` requires explicit `/build-loop:promote-experiment`. Deprecated `autoSelfImprove: false` is a migration no-op (logged to `state.json.warnings[]`).
 
 ## Capability Routing
 
@@ -158,11 +168,11 @@ When a phase needs a capability, see `references/capability-routing.md`. Trigger
 
 ## Model Tiering & Escalation
 
-Defaults (consult `Skill("build-loop:model-tiering")` for the canonical table): **orchestrator** = `claude-opus-4-7` (Opus 4.7); **implementer** (Execute) = `sonnet`, `effort: medium`; **adversarial critic** (Review-A) = `independent-auditor` at `scope: "build"` (single source of truth, consolidated 2026-05-23); **fact-checker** (Review-D) = `inherit`; **mock-scanner** (Review-D) = `haiku`; **recurring-pattern detector** (Learn) = `haiku`; **self-improvement architect** (Learn) = `sonnet`; **planner / final reviewer / experiment signoff** = you (Opus 4.7).
+Defaults (consult `Skill("build-loop:model-tiering")` for the canonical table): **orchestrator** = `opus` (coordination tier; alias tracks latest Opus); **Phase 2 Plan synthesis** = `fable` (Frontier — frame goal, draft spec/ADRs, F-criteria, MECE partition) **reached via the stakes-gated Advisor dispatch ladder** (`advisor` agent / peer host / already-Fable session), with an honestly-labeled inline-Opus fallback when no trigger fires or no dispatch path is reachable — the floor equals today's behavior (`references/advisor-dispatch-ladder.md`); **implementer** (Execute) = `sonnet`, `effort: medium`; **verification surface (Review-A / Review-D / Plan→Execute boundary / Phase 6 promotion)** = `fable` — `plan-critic`, `scope-auditor`, `independent-auditor` (at `scope: "build"`, single source of truth, consolidated 2026-05-23), `fix-critique`, `fact-checker`, `security-reviewer` (when `triggers.riskSurfaceChange`), `overfitting-reviewer`, `promotion-reviewer`; **mock-scanner** (Review-D) = `haiku`; **recurring-pattern detector** (Learn) = `haiku`; **self-improvement architect** (Learn — drafts, Fable signs off via `promotion-reviewer`) = `sonnet`; **deliberate Sonnet exceptions on the verification surface** = `alignment-checker` (called per queue item during autonomous iterate) and `synthesis-critic` (per-UI-commit WARN-only) — both advisory, non-gating, high-frequency.
 
-**Escalate to Opus** (respawn the subagent) on: 2 consecutive failures on the same chunk after `effort=high`; ambiguous spec; cross-file architectural decision mid-execution; critic flagged `strong-checkpoint`; novel error pattern; user-visible prose where tone matters. Log to `.build-loop/state.json.escalations`.
+**Escalate to Opus** (respawn the subagent) on: 2 consecutive failures on the same chunk after `effort=high`; ambiguous spec; cross-file architectural decision mid-execution; critic flagged `strong-checkpoint`; novel error pattern; user-visible prose where tone matters. Log to `.build-loop/state.json.escalations`. If the surfaced ambiguity is a **planning miss** (the plan itself no longer fits) rather than an execution problem, route back to Phase 2 — Fable re-plans, then execution resumes on Sonnet/Opus.
 
-**Dynamic tier assignment** (guide): judge each subtask's complexity adaptively. Priority order: **accuracy > speed > cost** — never trade accuracy for cheaper/faster; among accuracy-equals prefer the faster path; optimize cost last. Prefer Sonnet (default workhorse). Down-tier to Haiku only for trivial mechanical tasks. Opus subagents may accelerate genuinely complex subtasks. For `model: inherit` agents pass the tier explicitly. Full guide: `references/model-tier-mapping.md` §"Dynamic tier assignment". **Verify every subagent's output before accepting it** — cheaper tier → stronger check; enforced by verify-scope / verify-landed (Phase 3 commit step), independent-auditor (Review-A), and each subagent's return envelope (`status: blocked | partial` routes to Iterate).
+**Dynamic tier assignment** (guide): judge each subtask's complexity adaptively. Priority order: **accuracy > speed > cost** — never trade accuracy for cheaper/faster; among accuracy-equals prefer the faster path; optimize cost last. Prefer Sonnet (default workhorse for execution). Down-tier to Haiku only for trivial mechanical tasks. Opus subagents may accelerate genuinely complex execution subtasks. Fable is the default for planning + verification verdicts (see surface list above). For `model: inherit` agents pass the tier explicitly. Full guide: `references/model-tier-mapping.md` §"Dynamic tier assignment". **Verify every subagent's output before accepting it** — cheaper tier → stronger check; enforced by verify-scope / verify-landed (Phase 3 commit step), independent-auditor (Review-A), and each subagent's return envelope (`status: blocked | partial` routes to Iterate).
 
 ### Escalation Triggers
 
@@ -174,25 +184,10 @@ Reads at Phase 1 Assess; writes at Phase 4 Review-G. Full protocol: `references/
 
 ## Deployment Policy
 
-Repo-local config at `.build-loop/config.json`:
-
-```json
-{
-  "deploymentPolicy": {
-    "preview": "auto",
-    "testflight": "auto",
-    "production": "confirm",
-    "unknown": "confirm"
-  }
-}
-```
-
-Targets: `preview` (preview deploys + non-prod branch pushes); `testflight` (Xcode/ASC/TestFlight upload/export); `production` (production deploys, releases, publishes, protected-branch pushes); `unknown` (anything the classifier can't identify). Actions: `auto`, `confirm`, `block`. Evaluate the exact command via `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deployment_policy.py" --workdir "$PWD" --command "$CANDIDATE_DEPLOY_COMMAND"`. Helper errors fail closed: require confirmation.
+Repo-local config at `.build-loop/config.json` `deploymentPolicy` — default `{preview:auto, testflight:auto, production:confirm, unknown:confirm}`. Targets: `preview` (preview deploys + non-prod branch pushes); `testflight` (Xcode/ASC/TestFlight upload/export); `production` (production deploys, releases, publishes, protected-branch pushes); `unknown` (anything the classifier can't identify). Actions: `auto`, `confirm`, `block`. Evaluate the exact command via `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deployment_policy.py" --workdir "$PWD" --command "$CANDIDATE_DEPLOY_COMMAND"`. Helper errors fail closed: require confirmation.
 
 ## Output Format
 
-After each phase (and each Review sub-step), output a brief status line:
-
-Use `[Phase N: Name] ✅ Complete — key finding`, `[Phase 4.B: Validate] ❌ Failed: criterion X — evidence ...`, and `[Iterate 2/5] ❌ Failed: system cause Y — fixing Z`. Final report uses ✅/⚠️/❓ markers per criterion.
+After each phase (and each Review sub-step), output a brief status line — e.g. `[Phase N: Name] ✅ Complete — key finding`, `[Phase 4.B: Validate] ❌ Failed: criterion X — evidence ...`, `[Iterate 2/5] ❌ Failed: system cause Y — fixing Z`. Final report uses ✅/⚠️/❓ markers per criterion.
 
 <!-- build-loop@tyroneross — canonical source: github.com/tyroneross/build-loop -->

package/agents/fact-checker.md

@@ -14,7 +14,7 @@ description: |
   user: "Check if the dashboard metrics are real or hardcoded"
   assistant: "I'll use the fact-checker agent to trace each metric to its source."
   </example>
-model: inherit
+model: fable
 color: yellow
 tools: ["Read", "Grep", "Glob"]
 ---

package/agents/fix-critique.md

@@ -1,7 +1,7 @@
 ---
 name: fix-critique
 description: Use this agent to pressure-test a proposed fix before declaring a bug resolved. Challenges whether the fix addresses the root cause or just a symptom, checks for potential regressions, and verifies evidence exists for the claimed fix. Run after a fix is implemented but before declaring it done.
-model: inherit
+model: fable
 color: yellow
 tools: ["Read", "Grep", "Glob"]
 ---

package/agents/independent-auditor.md

@@ -14,7 +14,7 @@ description: |
   user: "audit this commit before I push"
   assistant: "Dispatching independent-auditor on HEAD~1..HEAD against the on-disk intent + PRD."
   </example>
-model: sonnet
+model: fable
 color: cyan
 tools: ["Read", "Grep", "Glob", "Bash"]
 ---

package/agents/overfitting-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: overfitting-reviewer
 description: Reviews optimization results for overfitting, Goodhart violations, and test-gaming shortcuts. Read-only adversarial review.
-model: sonnet
+model: fable
 tools: ["Read", "Glob", "Grep"]
 ---