@tyroneross/build-loop 0.30.3 → 0.34.0

package/skills/model-tiering/SKILL.md

@@ -17,18 +17,21 @@ skill answers "which tier should run the role?", not "who owns the work?".
 
 | Tier | Anthropic default | Role | Equivalents (advisory — verify benchmarks before swapping) |
 |---|---|---|---|
-| **Thinking** | Opus 4.7 | Synthesis, planning, ambiguity resolution, severity ranking, audit/learnings, cross-file judgment | GPT-5 Thinking, Gemini 2.5 Pro, future Claude tier; any model >= Opus 4.6 on SWE-bench Verified + Frontier-class on ARC-AGI / MMLU-Pro |
-| **Code** | Sonnet 4.6 | Application — apply rule to bounded input, scoped implementation, adversarial critic, mechanical refactor | Sonnet 4.7+, GPT-5 Codex, qwen2.5-coder-32B (local); any model with SWE-bench Verified within ~5pt of Sonnet 4.6 (currently ~79.6%) |
+| **Frontier** | Fable 5 | **Phase 2 Plan synthesis (frame goal, draft spec/ADRs, F-criteria, MECE partition) via the Advisor dispatch ladder when stakes-gated** — `advisor` agent / peer host / already-Fable session; honestly-labeled inline-Opus fallback otherwise (`references/advisor-dispatch-ladder.md`). (Advisor v1 = Phase 2 only; Phase 1 Assess synthesis runs inline as today until v2.) AND verification judgment (plan-critic, scope-auditor, independent-auditor, fix-critique, fact-checker, security-reviewer, overfitting-reviewer, promotion-reviewer) | GPT-5.5 Thinking (or whichever tier scores above the prior Thinking-tier ceiling), future Claude tier above Opus; any model that benchmarks above the Thinking-tier contract on SWE-bench Verified AND ARC-AGI / GPQA Diamond |
+| **Thinking** | Opus 4.8 | Coordination — build-orchestrator, assessment-orchestrator — and the escalation target for execution (ambiguous spec, 2 consecutive failures, cross-file surprise) and audit/learnings synthesis when Frontier is unavailable | GPT-5 Thinking, Gemini 2.5 Pro; any model >= Opus 4.6 on SWE-bench Verified + Frontier-class on ARC-AGI / MMLU-Pro |
+| **Code** | Sonnet 4.6 | Application — apply rule to bounded input, scoped implementation, mechanical refactor, bounded domain assessment | Sonnet 4.7+, GPT-5 Codex, qwen2.5-coder-32B (local); any model with SWE-bench Verified within ~5pt of Sonnet 4.6 (currently ~79.6%) |
 | **Pattern** | Haiku 4.5 | Recognition — regex/syntactic match, classification into known buckets, log scan, deterministic checklist | Haiku 4.6, GPT-5 Mini, llama3.2-3b (local); any small/fast model that handles structured pattern matching |
 
-**Rule of substitution:** tier A's swap target must score within tolerance of the default on the benchmark relevant to its role. For Code tier that's SWE-bench Verified ≥75% AND tool-use accuracy ≥85%; for Thinking tier that's SWE-bench ≥78% AND ARC-AGI / GPQA Diamond competitive; for Pattern tier no benchmark — just "fast and cheap, doesn't hallucinate on bounded structured tasks."
+**Rule of substitution:** tier A's swap target must score within tolerance of the default on the benchmark relevant to its role. For Code tier that's SWE-bench Verified ≥75% AND tool-use accuracy ≥85%; for Thinking tier that's SWE-bench ≥78% AND ARC-AGI / GPQA Diamond competitive; for Frontier tier that's clearing the Thinking-tier contract AND scoring above the prior-generation Thinking-tier ceiling on at least one of SWE-bench Verified / ARC-AGI / GPQA Diamond; for Pattern tier no benchmark — just "fast and cheap, doesn't hallucinate on bounded structured tasks."
+
+**Why Frontier sits above Thinking for plan + verification (and not for execution):** wrong plans and wrong verdicts compound — a bad plan dispatches N implementers into the wrong work, and a bad verdict ships a regression. The user's standing priority is Accuracy > Speed > Cost (`feedback_accuracy_speed_cost_priority.md`), so the planning and verification surfaces — where one miscall poisons everything downstream — pay the Frontier premium. Execution and coordination stay on Sonnet/Opus because they're either bounded application (Sonnet implementer applies a settled plan) or routing (Opus orchestrator chooses which subagent runs next, with deterministic gates as the safety net).
 
 ## Provider-swap recipe
 
-Build-loop's agent frontmatter uses Anthropic model aliases (`opus`, `sonnet`, `haiku`) because Claude Code is the primary host. To run on a different provider:
+Build-loop's agent frontmatter uses Anthropic model aliases (`fable`, `opus`, `sonnet`, `haiku`) because Claude Code is the primary host. To run on a different provider:
 
-1. **One-time edit per agent:** open each `agents/*.md` and change the `model:` field to your provider's equivalent. The tier (Thinking/Code/Pattern) determines the substitution target.
-2. **Runtime override:** `.build-loop/config.json.modelOverrides` accepts `{ thinking: "<id>", code: "<id>", pattern: "<id>" }`. The orchestrator resolves this through `scripts/model_overrides.py` before dispatching subagents (see `references/model-tier-mapping.md` for full schema).
+1. **One-time edit per agent:** open each `agents/*.md` and change the `model:` field to your provider's equivalent. The tier (Frontier/Thinking/Code/Pattern) determines the substitution target.
+2. **Runtime override:** `.build-loop/config.json.modelOverrides` accepts `{ frontier: "<id>", thinking: "<id>", code: "<id>", pattern: "<id>" }`. The orchestrator resolves this through `scripts/model_overrides.py` before dispatching subagents (see `references/model-tier-mapping.md` for full schema). Configs without `frontier` resolve frontier → `fable` by default.
 3. **Per-dispatch override:** any orchestrator dispatch may pass `model: <id>` in the subagent prompt to force that call.
 
 The role-and-task table below uses tier names. The Anthropic-default mapping in the right column is illustrative; substitute your equivalents at swap time.
@@ -41,7 +44,7 @@ The role-and-task table below uses tier names. The Anthropic-default mapping in
 - Deciding whether to escalate mid-flow after failures
 - Evaluating whether to swap providers (use the Tier abstraction table above as the contract)
 
-## Evidence base (2026 Q1)
+## Evidence base (2026 Q1–Q2)
 
 | Claim | Source | Certainty |
 |-------|--------|-----------|
@@ -49,43 +52,57 @@ The role-and-task table below uses tier names. The Anthropic-default mapping in
 | Opus 4.6: 80.8% SWE-bench Verified (1.2pt gap — smallest in Claude history) | Same | ⚠️ T2, single-source |
 | Sonnet 4.6 uses 70% fewer tokens than 4.5 on complex file ops with +38% accuracy | Anthropic Sonnet 4.6 announcement | ⚠️ T2, single-source |
 | Pricing: Sonnet $3/$15 per MTok input/output | Anthropic pricing page | ⚠️ verify before billing |
-| Pricing: Opus $15/$75 per MTok input/output (5x gap) | Anthropic pricing page | ⚠️ verify before billing |
+| Pricing: Opus 4.8 $5/$25 per MTok input/output | Anthropic pricing page | ⚠️ verify before billing |
+| Pricing: Fable 5 $10/$50 per MTok input/output (1M context, capability tier above Opus 4.8) | claude-api skill cache 2026-05-26 (T1 — Anthropic) | ✅ T1 source, advisory until re-confirmed at next billing audit |
 
 ## MECE primitive: cognitive type of the task
 
-Before consulting the role table, classify the task by reasoning shape. The MECE cut is the kind of thinking the task requires; lifecycle stage (plan/execute/review) is a second-order cut that often mixes types.
+Before consulting the role table, classify the task by reasoning shape. The MECE cut is the kind of thinking the task requires; lifecycle stage (plan/execute/review) is a second-order cut that often mixes types. Within Synthesis, a second-order cut decides whether the task is a planning/verification decision (Frontier) or coordination/escalation/learnings (Thinking).
 
 | Reasoning shape | Model | What it means | Example tasks |
 |---|---|---|---|
-| **Synthesis** — combine N inputs into a novel decision; cross-file/cross-system reasoning; ambiguity resolution; severity ranking | **Opus** | The "what" and "why" calls. No single rule produces the answer. | Frame goal, draft spec/ADRs, trace call-paths across files, rank finding severity, escalate stuck iteration with causal-tree, write audit/learnings |
-| **Application** — apply a known rule, spec, or pattern to bounded input; produce an artifact that matches a contract | **Sonnet** | The "how" call when "what" is decided. Single-correct-answer derivable from a rule. | Implement a commit's owned files per spec, write tests for given F-criteria, adversarial critic vs rubric, mechanical simplify, fact-check with named source |
-| **Recognition** — pure regex/syntactic match; classify into known buckets; no judgment | **Haiku** | No gradient — matches or doesn't. | Mock-data scan, log pattern detection, file inventory, cross-run pattern detection, deterministic checklist verification |
+| **Planning + Verification synthesis** — frame the goal, draft the spec/ADRs, define F-criteria, MECE-partition the work, then later judge whether a plan, a commit, a fix, a claim, or a security/scope boundary actually holds | **Fable (Frontier)** | The "what to do" and "did it actually work" calls. Wrong calls poison every downstream dispatch. | Phase 2 Plan drafting (reaches Fable via the stakes-gated Advisor ladder; Phase 1 Assess synthesis stays inline until v2), plan-critic, scope-auditor, independent-auditor, fix-critique, fact-checker, security-reviewer, overfitting-reviewer, promotion-reviewer |
+| **Coordination + escalation synthesis** — route work between subagents, ladder severity, run causal-tree on stuck iterations, write audit/learnings | **Opus (Thinking)** | The "who runs next" + "why did the rule run out" calls. Deterministic gates backstop the routing. | build-orchestrator, assessment-orchestrator, severity ranking after critic findings, causal-tree after 2 consecutive failures, Phase 6 Learn audit synthesis (when no Frontier escalation needed) |
+| **Application** — apply a known rule, spec, or pattern to bounded input; produce an artifact that matches a contract | **Sonnet (Code)** | The "how" call when "what" is decided. Single-correct-answer derivable from a rule. | Implement a commit's owned files per spec, write tests for given F-criteria, mechanical simplify, bounded domain assessment (api/db/frontend/perf), design-contract reconciliation, ui-validator, retrospective-synthesizer, self-improvement-architect drafting |
+| **Recognition** — pure regex/syntactic match; classify into known buckets; no judgment | **Haiku (Pattern)** | No gradient — matches or doesn't. | Mock-data scan, log pattern detection, file inventory, cross-run pattern detection, deterministic checklist verification |
 
-**Decision tree:** "Does this task have a single-correct answer derivable from a rule applied to bounded input?" → Yes = Application/Sonnet. Else "Is the answer pure pattern-match?" → Yes = Recognition/Haiku. Else = Synthesis/Opus.
+**Decision tree:** "Does this task have a single-correct answer derivable from a rule applied to bounded input?" → Yes = Application/Sonnet. Else "Is the answer pure pattern-match?" → Yes = Recognition/Haiku. Else, Synthesis. Then ask: "Is this a planning decision (what to build) or a verification verdict (did it hold)?" → Yes = Frontier/Fable. Else (routing, escalation, audit-synthesis when no verdict is being rendered) = Thinking/Opus.
 
 ## Default assignments
 
 | Task | Reasoning shape | Model | effort | Why |
 |------|------|-------|--------|-----|
-| Frame & plan: goal, ADRs, scope, F-criteria, MECE partition | Synthesis | Opus | medium | Ambiguity resolution; wrong plan compounds |
+| Frame & plan: goal, ADRs, scope, F-criteria, MECE partition | Planning synthesis | Fable | medium | A wrong plan dispatches N implementers into the wrong work; user's standing priority Accuracy > Speed > Cost |
 | Plan-verify deterministic checklist | Recognition | (script) | — | No model; runs `plan_verify.py` |
-| Plan-critic adversarial review against rubric+checklist | Application | Sonnet | high | Bounded — rubric is the rule. Separation drives quality |
-| **Scope auditor (NEW — Plan→Execute boundary)**: trace callers of every modified-API symbol; annotate `caller_audit:` per commit | Synthesis | Opus | medium | Cross-file call-path tracing that fanned-out implementers can't do (round-2 lesson) |
-| Code execution — bounded chunk, spec clear | Application | Sonnet | medium | Default. High accuracy, 5× cheaper |
-| Code execution — ambiguous spec | Synthesis | Opus | medium | Interpretation cost cheaper than rework |
-| Adversarial critic pass (read-only diff vs rubric) | Application | Sonnet | high | Bounded — rubric vs diff is rule-application; separation effect |
-| Code review — severity ranking + recommendation order (given findings) | Synthesis | Opus | medium | Cross-finding judgment about what matters most |
+| Plan-critic adversarial review against rubric+checklist | Verification synthesis | Fable | high | Verification verdict — separation drives quality; verdict gates Phase 3 dispatch |
+| Scope auditor (Plan→Execute boundary): trace callers of every modified-API symbol; annotate `caller_audit:` per commit | Verification synthesis | Fable | medium | Cross-file call-path tracing AND a gating verdict on whether a commit is `internal_only`; verification compound risk |
+| Code execution — bounded chunk, spec clear | Application | Sonnet | medium | Default workhorse. Spec is settled; apply the rule |
+| Code execution — ambiguous spec or cross-file surprise mid-execution | Coordination synthesis | Opus | medium | Escalation target; interpretation cost cheaper than rework |
+| Independent-auditor adversarial pass (read-only diff vs rubric at chunk + build scope) | Verification synthesis | Fable | high | Verdict gates the build's outcome line; a missed regression in production-impacting work is the most expensive miss in the loop |
+| Severity ranking + recommendation order (given findings) | Coordination synthesis | Opus | medium | Cross-finding routing; no per-finding verdict being rendered, the verdicts are upstream |
 | Mock data scanning | Recognition | Haiku | low | Regex only |
-| Fact-checking — trace metric → source, judge accuracy | Synthesis | Opus | medium | Cross-system; "is this number real?" requires cross-context judgment |
-| Fact-checking — trace metric → named-source pattern (rule-bound) | Application | Sonnet | medium | When the source-pattern rule is explicit |
+| Fact-checking — trace metric → source, judge accuracy | Verification synthesis | Fable | medium | Final read on "is this number real" before report ships; user-trust verdict |
+| Fix-critique — pressure-test a proposed fix before "resolved" | Verification synthesis | Fable | medium | Verdict on whether the fix addresses root cause vs symptom; wrong verdict reopens the bug downstream |
+| Security-reviewer — adversarial OWASP/ATLAS pass | Verification synthesis | Fable | high | Verdict gates riskSurfaceChange dispatch; missed exposure is the most expensive verification miss |
+| Overfitting-reviewer — Goodhart / test-gaming verdict on optimize runs | Verification synthesis | Fable | medium | Verdict on whether optimization is genuine; cheap to wrong-call into a regression |
+| Promotion-reviewer — Phase 6 Learn experimental promotion verdict | Verification synthesis | Fable | medium | Gates the move from `experimental/` to `active/`; durable surface |
 | Simplify — apply known simplifications | Application | Sonnet | medium | Inline single-use helper, delete dead branch — bounded |
 | Debugging — symptom-to-known-pattern match | Application | Sonnet | high | Memory-first gate's "Application until the rule runs out" |
-| Debugging — causal-tree after 2 consecutive failures | Synthesis | Opus | high | Synthesis takes over when rule-match exhausts |
-| Novel architecture decision | Synthesis | Opus | medium | Cross-file impact; wrong call is expensive |
-| Writing user-facing prose (copy, microcopy, errors) | Synthesis | Opus | medium | Tone, restraint, and nuance matter |
-| Audit / learnings / Phase 6 promotion-decision | Synthesis | Opus | medium | Cross-run synthesis |
+| Debugging — causal-tree after 2 consecutive failures | Coordination synthesis | Opus | high | Synthesis takes over routing when rule-match exhausts |
+| Novel architecture decision | Planning synthesis | Fable | medium | Cross-file impact; wrong call compounds |
+| Writing user-facing prose (copy, microcopy, errors) | Coordination synthesis | Opus | medium | Tone, restraint, and nuance matter; no verification verdict being rendered |
+| Audit / learnings / Phase 6 audit synthesis | Coordination synthesis | Opus | medium | Cross-run routing; promotion-reviewer carries the gating verdict separately |
 | Recurring-pattern detection across runs[] | Recognition | Haiku | low | Pattern-match across structured logs |
 
+### Deliberate exceptions (Sonnet retained for cost where the surface is high-frequency advisory)
+
+Two verification-shaped agents stay on Sonnet rather than escalating to Fable. The tension with round-2 evidence ("rubric-application = Sonnet is robust") is real; the user chose Fable for the rest of the verification surface anyway because the compound risk of a wrong verification verdict outweighs the per-call premium. Pins are defaults, not locks — these can be overridden per dispatch or re-tiered after telemetry.
+
+| Agent | Pin | Why retained on Sonnet |
+|---|---|---|
+| `alignment-checker` | Sonnet | Called once per queue item during autonomous iterate (up to 25× per run). Advisory only — flags drift, doesn't gate. Cost dominates value at this fan-out frequency. |
+| `synthesis-critic` | Sonnet | Per-UI-commit WARN-only check. Advisory only — never gates. Frequency × non-gating shape means a cheaper tier is the right tradeoff. |
+
 ## Round 2 evidence (2026-05-07, example-app news-podcast iteration 2)
 
 n=2 dispatch-pattern A/B comparison on a 6-commit feature reversed the round-1 belief that Skill-path (Sonnet fan-out) is materially cheaper across the board:
@@ -105,16 +122,20 @@ Findings that updated the model tiering:
 3. **Inline-Opus is faster wall-clock** when there's no real parallelism to exploit. Fan-out parallelism is only a win when ≥3 chunks are truly independent.
 4. **Plan-critic on Sonnet caught 17 substantive findings** on a written spec — confirms "rubric-application = Sonnet" is robust.
 
-These findings inform the role assignments, especially the rubric-application=Sonnet vs severity-assessment=Opus split for code review.
+These findings informed the earlier rubric-application=Sonnet split for code review. The current org overrides that for the verification surface specifically — the user chose Fable for verification because a missed verdict at this stage compounds, even though round-2 showed Sonnet rubric-application was substantively robust on a 17-finding plan-critic pass. The exceptions table above (alignment-checker, synthesis-critic) preserves the Sonnet split where the surface is high-frequency advisory and non-gating.
 
-## Escalation triggers (stay on Sonnet UNLESS)
+## Escalation triggers (Sonnet execution → Opus, NOT to Fable)
 
-- 2 consecutive failures on the same chunk after a retry at effort=high
-- Spec is ambiguous and interpretation will materially change implementation
-- A cross-file architectural decision surfaces mid-execution that wasn't in the plan
-- Critic flags a "strong-checkpoint" finding that requires judgment, not just a fix
-- Novel error pattern not found in `.build-loop/issues/` or debugging memory
-- Task produces user-visible prose where tone and restraint are load-bearing
+Execution escalates to **Opus**, not Fable. Fable is reserved for planning and verification; execution under genuine ambiguity is a coordination call (interpret the spec, route to a new chunk, decide whether to re-plan) that the orchestrator owns.
+
+- 2 consecutive failures on the same chunk after a retry at effort=high → respawn implementer at Opus
+- Spec is ambiguous and interpretation will materially change implementation → Opus
+- A cross-file architectural decision surfaces mid-execution that wasn't in the plan → Opus, then route back to Plan if the decision changes the MECE partition
+- Critic flags a "strong-checkpoint" finding that requires judgment, not just a fix → Opus
+- Novel error pattern not found in `.build-loop/issues/` or debugging memory → Opus
+- Task produces user-visible prose where tone and restraint are load-bearing → Opus
+
+If the ambiguity surfaces a **planning** problem (the original plan no longer fits) rather than an execution problem, route back to Phase 2 Plan — Fable re-plans, then execution resumes on Sonnet/Opus.
 
 ## Techniques that work
 
@@ -149,19 +170,21 @@ These findings inform the role assignments, especially the rubric-application=So
 
 ## How the build-loop uses this
 
-Orchestrator (Opus 4.7) spawns implementer subagent (Sonnet, effort=medium) → external verification gate (tests/lint/types) → Sonnet critic agent (read-only, effort=high) → if strong-checkpoint flagged, escalate to Opus for judgment call. See `agents/build-orchestrator.md §Escalation Triggers`. The **tier mapping** is the policy; the cost numbers above are advisory context, not the basis for overrides.
+**Fable plans (when stakes-gated) and verifies. Opus coordinates. Sonnet executes. Haiku recognizes.**
 
-Haiku is only used for Phase 7B mock scanning. Never for reasoning tasks.
+Phase 2 Plan synthesis reaches **Fable** through the **Advisor dispatch ladder** when stakes-gating trips (`synthesisDensity > 5`, `riskSurfaceChange`, `stakes >= medium`, or `dispatch_tier: frontier`): the orchestrator dispatches the `advisor` agent (Rung 1), routes to a peer host (Rung 2), or — if its own session is already Fable — synthesizes inline at Frontier (Rung 0). When no trigger fires or no dispatch path is reachable, the orchestrator synthesizes the plan **inline on its own model (Opus)** and labels it honestly (Rung 3 = today's behavior; the floor equals current state). So "Fable plans" is the *guarantee on high-stakes plans*, with an honestly-labeled inline fallback otherwise — not unconditional. Full protocol: `references/advisor-dispatch-ladder.md`. The Advisor frames the goal, drafts the spec/ADRs, sets F-criteria, and MECE-partitions the work. The orchestrator (**Opus**, `build-orchestrator`, `assessment-orchestrator`) coordinates: it routes dispatches, runs deterministic gates, manages parallel fan-out, walks the Advisor ladder, and handles the escalation ladder. Phase 3 implementer subagents run on **Sonnet** at effort=medium (default workhorse) → external verification gate (tests/lint/types) → adversarial **Fable** verification surface (`plan-critic`, `scope-auditor`, `independent-auditor`, `fix-critique`, `fact-checker`, `security-reviewer`, `overfitting-reviewer`, `promotion-reviewer`). If a strong-checkpoint finding or 2 consecutive chunk failures surface, execution escalates to **Opus** for judgment; if the failure traces back to a planning miss, route back to Fable to re-plan. See `agents/build-orchestrator.md §Escalation Triggers`. The **tier mapping** is the policy; the cost numbers above are advisory context, not the basis for overrides.
+
+Haiku is only used for Phase 7B mock scanning and recurring-pattern detection across `runs[]`. Never for reasoning tasks.
 
 ## Pin vs inherit in agent frontmatter
 
 Not every agent should hard-pin its model. Use this rule:
 
-- **Pin** (`model: opus | sonnet | haiku`) when the task has a clear right tier and cost/quality drift from user's session choice would be a bug. Examples: `independent-auditor` (Sonnet advisory judge across chunk + build scope, consolidated 2026-05-23 — replaces retired `commit-auditor` and earlier `sonnet-critic`), `mock-scanner` (pattern matching only), `build-orchestrator` (Opus judgment at plan/review boundaries).
-- **Inherit** (`model: inherit`) when user intent should flow through. The user's main-session choice is itself a cost/speed preference; respect it. Pair with a "recommended: X" note in this skill rather than forcing via frontmatter. Example: `fact-checker` — recommended Sonnet, but inherit honors whatever tier the user picked upstream.
-- **Override mechanism**: users can override any pin by passing `model:` when spawning the agent or by editing the frontmatter. Pins are defaults, not locks.
+- **Pin** (`model: fable | opus | sonnet | haiku`) when the task has a clear right tier and cost/quality drift from user's session choice would be a bug. Examples: `plan-critic` / `independent-auditor` / `scope-auditor` / `fact-checker` / `fix-critique` / `security-reviewer` / `overfitting-reviewer` / `promotion-reviewer` (Fable — verification verdicts gate downstream work), `mock-scanner` (Haiku, pattern matching only), `build-orchestrator` and `assessment-orchestrator` (Opus, coordination at plan/review boundaries), `implementer` (Sonnet, default execution workhorse).
+- **Inherit** (`model: inherit`) when user intent should flow through. The user's main-session choice is itself a cost/speed preference; respect it. Pair with a "recommended: X" note in this skill rather than forcing via frontmatter. Example: `root-cause-investigator` — recommended Opus on causal-tree work, but inherit honors whatever tier the user picked upstream.
+- **Override mechanism**: users can override any pin by passing `model:` when spawning the agent or by editing the frontmatter. Pins are defaults, not locks. The deliberate exceptions documented above (`alignment-checker`, `synthesis-critic` on Sonnet despite being verification-shaped) are exactly this kind of cost-vs-judgment pin and can be lifted if telemetry says so.
 
-Forward-compat note: pinned family aliases (`sonnet`, `opus`) auto-track latest versions (e.g., 4.6 → 4.7). `inherit` additionally picks up brand-new tiers (e.g., a future Flash-class model) without frontmatter edits.
+Forward-compat note: pinned family aliases (`fable`, `sonnet`, `opus`) auto-track latest versions in their tier (e.g., Sonnet 4.6 → 4.7, Opus 4.7 → 4.8, Fable 5 → 6). `inherit` additionally picks up brand-new tiers (e.g., a future Flash-class model) without frontmatter edits.
 
 ## Limitations of this guidance
 
@@ -213,4 +236,6 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/model_overrides.py \
   --json
 ```
 
+Accepted tiers: `frontier` (default `fable`), `thinking` (default `opus`), `code` (default `sonnet`), `pattern` (default `haiku`). Configs without `frontier` resolve frontier → `fable` so older repos keep working without edits.
+
 Full contract and routing matrix: `~/dev/research/topics/llm/llm.build-loop-router-integration-2026-04.md`

package/skills/optimize/SKILL.md

@@ -40,7 +40,7 @@ Highest-leverage phase. Wrong metric = Goodhart's Law. Wrong factors = wasted ru
 |---|---|---|
 | **A. Power-user explicit** | User supplied factors via CLI flag, `.build-loop/optimize/factors.json`, or inline ("optimize batch_size, retries, workers for throughput") | Skip suggestion; use the user's factors directly |
 | **B. Vague optimization** *(default)* | "run optimization", "make my app faster", "improve performance", "speed up", "reduce <metric>" without naming factors | Run factor-identification scan; propose candidates; **AskUserQuestion to confirm before running** |
-| **C. Single-variable explicit** | "simplify this file", "reduce build time", scoped `/build-loop:optimize <known-target>` | Skip DOE; run autoresearch (existing behavior, Phase 2 LOOP unchanged) |
+| **C. Single-variable explicit** | "simplify this file", "reduce build time", scoped `/build-loop:optimize-run <known-target>` | Skip DOE; run autoresearch (existing behavior, Phase 2 LOOP unchanged) |
 
 ### Step 1.2 — Branch A or B: factor identification
 
@@ -186,7 +186,7 @@ Dispatch the `optimize-runner` agent. It executes:
 
 Phase 4.7 (AUTO-OPTIMIZE): after Phase 4 Execute completes and commits, check for optimization targets. Run sequentially (not parallel with Phase 4).
 
-Standalone: `/build-loop:optimize [target]`
+Standalone: `/build-loop:optimize-run [target]`
 
 ## State Files
 

package/skills/plan-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-verify
-description: Use when build-loop Phase 2 wraps plan drafting, the user runs `/build-loop:plan-verify`, asks to "verify the plan" or "lint the plan", or any plan markdown change touches evidence, synthesis-density, risk_reason, or modifies_api fields. Runs deterministic plan-verify rules and emits findings JSON.
+description: Use when build-loop Phase 2 wraps plan drafting, the user runs `/build-loop:verify-plan`, asks to "verify the plan" or "lint the plan", or any plan markdown change touches evidence, synthesis-density, risk_reason, or modifies_api fields. Runs deterministic plan-verify rules and emits findings JSON.
 user-invocable: false
 ---
 

package/skills/plugin-builder/references/distribution.md

@@ -213,6 +213,10 @@ mapping is valid. A real publish can still fail after a successful dry-run when
 the npm package settings do not match the GitHub workflow. After publishing,
 verify the registry metadata includes
 `dist.attestations.provenance.predicateType = https://slsa.dev/provenance/v1`.
+If the real publish step prints the final `+ @scope/package@version` line but
+the immediate metadata check returns `E404`, do not rerun the same publish.
+npmjs metadata can lag for a few minutes after acceptance; poll `npm view` or
+use a verify-only workflow path.
 
 ### Access Token Fallback Gate
 
@@ -286,6 +290,10 @@ npm audit signatures
 gh run rerun <run-id> --failed
 ```
 
+- If npmjs succeeds through the final `+ @scope/package@version` line but the
+  post-publish metadata check returns `E404`, treat it as a visibility lag until
+  registry polling proves otherwise. Do not rerun the publish for that version;
+  rerun a verify-only path or poll `npm view`.
 - Use local npm login or token publishing only as an explicit fallback decision,
   because it bypasses the trusted-publisher/provenance path.
 

package/skills/research/SKILL.md

@@ -53,10 +53,37 @@ Produces a repo-grounded research packet without committing to implementation. U
 [What could go wrong, what's uncertain]
 
 ## Confidence
-- Context coverage: high/medium/low
-- Verification coverage: high/medium/low
-- Evidence quality: high/medium/low
-- Overall: high/medium/low
+
+Rate each axis high/medium/low, then set Overall to the floor of the three —
+and never above Evidence quality when the packet rests on external claims:
+
+- Context coverage — how much of the relevant repo was actually read
+- Verification coverage — share of material claims checked against repo or source
+- Evidence quality — strength of the sources behind external claims (rubric below)
+- Overall — the floor of the above
+
+### Source & claim rubric (apply to every external claim)
+
+Tier each source: **T1** official docs / standards / primary data · **T2**
+recognized experts / official eng blogs · **T3** reputable industry press ·
+**T4** forums / SEO / unattributed. Then grade the claim's corroboration and
+mark it inline:
+
+- ✅ verified — ≥2 *independent* T1/T2 sources agree (independent = different
+  orgs, not mirrors or one syndicated wire)
+- ⚠️ partial — exactly one T1/T2, or only T3/T4 sources
+- ❓ inferred — single source, T4 only, or your own inference
+
+A claim's confidence can never exceed its corroboration.
+
+### Verify before stating (high-risk / max_accuracy)
+
+For security, auth, payment, legal, medical, finance, production, or any
+`max_accuracy` packet: decompose each external claim into atomic checkable
+facts (a number, a version, an API signature, a citation) and verify each
+against a source before the packet states it. An unverifiable atom is labeled
+❓ or removed — never stated as fact. This applies the cite-or-block rule in
+`references/research-trigger-policy.md` claim-by-claim.
 
 ## Next action
 [Concrete first step — could be "run /build-loop" or "investigate X further"]
@@ -70,10 +97,10 @@ Produces a repo-grounded research packet without committing to implementation. U
 
 ## Integration
 
-- Standalone: `/build-loop:research [topic]`
+- Standalone: `/build-loop:research-run [topic]`
 - From build-loop: orchestrator routes RESEARCH-intent requests here instead of the full loop
 - During normal build-loop runs: `scripts/research_trigger.py` decides whether this skill should run, which depth to use, where to persist the packet, and whether current/external claims are blocked until cited. See `references/research-trigger-policy.md`.
-- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize` to optimize, or shelve
+- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize-run` to optimize, or shelve
 
 ## State
 

package/skills/runtime-parity-verification/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: runtime-parity-verification
+description: Use in Phase 4/5 (Validate/Iterate) for ANY change to a user-visible flow — web, macOS, iOS, agent, or CLI/TUI — before claiming "done". Verifies the RUNNING app's core flow by cross-checking the rendered/queryable UI against the backing source-of-truth (DB/API/daemon/tool-state), screen-independently. Triggers — "verify it works", "confirm the fix", "does X actually work", "nothing happens when I…", "not showing", "shows empty/wrong data", uiTarget != null, or any "action does nothing / data not displaying / stale projection" symptom. Compile-green and a passing unit test do NOT satisfy this; neither does a screenshot alone.
+user-invocable: false
+---
+
+# Runtime Parity Verification
+
+**The recurring failure this prevents:** an agent ships UI/feature work, reports "compiles green / tests pass / committed," and never confirms the **running** app's core flow actually works — or confirms it only by **screenshot**, which is screen-dependent and gets silently deferred (e.g. the user's display locks). The whole "X doesn't work / isn't showing / shows mock/empty despite real data / stale projection" bug class is a **divergence between what the UI renders and the authoritative backend state.** One cheap, headless check catches the entire family.
+
+## The invariant to assert
+
+> For the user's core flow, the **rendered/queryable UI state must equal the authoritative backend state.**
+> - If the backend holds N items and the UI shows 0 / "empty" → **FAIL** (projection diverged).
+> - If an action is supposed to create/change state, assert **both** the backend delta **and** the UI reflecting it.
+
+This is stronger than "did it render" (which UI validators check). It is also stronger than "build + tests pass" (which never exercises the running flow). It must be **screen-independent** so it cannot be skipped when no display is available.
+
+## Platform recipes — source-of-truth (left) ⇄ UI probe (right)
+
+| Platform | Authoritative source-of-truth | Screen-independent UI probe |
+|---|---|---|
+| **Web** | API response JSON / DB row count | Host browser or `ui-validator` / IBR scan; assert via `data-testid` selectors |
+| **macOS** (AppKit/SwiftUI) | backend store / daemon via CLI or socket query | **`native-ax-driver`** Accessibility tree (cursor-free). Reference impl: easy-terminal `tools/smoke_launch.py` |
+| **iOS / watchOS** | backend / store | simulator AX via `idb ui describe-all` or XCUITest queries |
+| **Agent / LLM app** | tool-result or persisted state | the agent's returned/rendered output — assert the claim matches the actual tool/state, not just that text was produced |
+| **CLI / TUI** | process / file / db state | captured stdout / TUI buffer |
+
+## Procedure
+
+1. **Identify the core flow** changed (the thing a user does: launch a thing, submit a form, see a list, run an action).
+2. **Capture source-of-truth** before and (if the flow mutates) after the action — a query that does NOT go through the UI layer.
+3. **Probe the UI headlessly** with the platform driver and extract the rendered state (counts, presence/absence of an empty state, the new item).
+4. **Assert parity**: rendered == source-of-truth. On a mutating flow, assert the backend delta AND the UI reflecting it.
+5. **Encode it as a per-repo smoke** (a script that returns non-zero on divergence). **Validate the smoke is real**: confirm it returns non-zero on a known-broken state, not just zero on green — a check that cannot fail is worthless.
+6. **Gate on it**: run the smoke before any "done" claim. Never substitute compile-green, a passing unit test, or a screenshot.
+
+## Anti-patterns (each one shipped a real bug)
+
+- "Build is green, committed — done." → compile ≠ runtime; never exercised the flow.
+- "Here's a screenshot, looks right." → screen-dependent; deferred when the screen locks; can't diff against truth.
+- "The UI rendered something." → rendering ≠ correct data; an empty state renders fine while the backend has 100 rows.
+- Verifying only the backend (CLI/API works) without the UI, or only the UI without the backing truth — the bug lives in the **gap between them**.
+
+## Build-loop integration
+
+- **Phase 4 Review sub-step B / Phase 5 Iterate**: when `uiTarget != null` OR the diff touches a user-visible flow, a runtime parity check is **required**. The existing drivers do the probing — web: `ui-validator`; macOS: `native-ax-driver` / IBR `scan_macos`; iOS: `idb`. THIS skill adds the missing step: **cross-check the probe against source-of-truth**, and keep a validated per-repo smoke.
+- **Phase 4 sub-step G (`verification-before-completion`)**: for app/UI changes, "confirm output" includes the runtime parity smoke, not only test/build/lint.
+- The `verify` skill ("run the app and observe behavior") is the manual counterpart; this skill is the automatable, source-of-truth-anchored form.
+
+Origin lesson: build-loop-memory `lessons/2026-06-08-pattern-runtime-ui-source-of-truth-parity-verification.md` (easy-terminal launch/no-pane bug — UI projection diverged from daemon, missed across a whole UI pass because verification was compile-green + screenshot-only).

package/skills/spec-writing/SKILL.md

@@ -314,6 +314,24 @@ If no UI surface is in scope, write "N/A: no UI surface."
 
 ---
 
+### Item 18 — Dispatch tier per work item (WP-B)
+
+**Prompt:** Assign `dispatch_tier:` per work item — one of `script | haiku | sonnet | opus | frontier` — plus a one-line justification. The tier names which executor the orchestrator dispatches; the justification states why that tier fits the work's nature. `frontier` requests the Frontier tier (resolves to Fable via `scripts/model_overrides.py`) for a work item whose generative reasoning compounds — plan synthesis / re-planning / a decomposition call where a wrong answer ripples downstream. It routes to the Advisor dispatch ladder (`references/advisor-dispatch-ladder.md`); use it sparingly, only on genuinely high-stakes generative work.
+
+**Eligibility test for `script` (ALL must hold):** machine-checkable output; fully enumerable inputs; the tool exists OR is ≤~50 LOC plus a colocated test. If any fails, the task needs a model tier (judgment), not a script. Escalate on evidence (2 failures or surfaced ambiguity) with the failure evidence attached; never patch a script mid-run to absorb ambiguity.
+
+**Effect:** `plan_verify.py` runs two ADVISORY checks (never block, user-confirmed 2026-06-09): `tier-sanity-judgment-on-script` (a judgment-flavored task pinned to `script` — rigidity) and `tier-sanity-mechanical-on-opus` (a rote task pinned to `opus` — waste). Both are WARN flags in the report, surfaced for the author to reconsider.
+
+**How to check:**
+
+```bash
+grep -n "dispatch_tier:" docs/plans/<feature-slug>.md
+```
+
+Each value must be exactly one of `script | haiku | sonnet | opus | frontier`. Omit the field for an item whose tier is obvious from context; the checks fire only on a declared tier that fights its task description. (`frontier` never trips a sanity WARN — it is the top judgment tier, never a "waste" smell.)
+
+---
+
 ## Frontmatter fields used by routing
 
 These fields appear in plan or chunk frontmatter and affect orchestrator routing decisions. They are validated by `scripts/plan_verify.py`.
@@ -322,6 +340,7 @@ These fields appear in plan or chunk frontmatter and affect orchestrator routing
 |-------|------|--------|
 | `risk_reason:` | one of 5 canonical strings | Routes chunk to `tier: thinking` regardless of `synthesis_dimensions` count (see Item 16). |
 | `modifies_api: true\|false` | boolean | When `true`, the orchestrator runs a mandatory scope-auditor gate before Phase 3 dispatch. Any public function, component, type, route, or CLI-flag signature change qualifies. When set without a companion `scope_auditor_status:` field in the plan body, `plan_verify.py` emits a WARN (`scope-audit-required`) to surface the missing audit trail. |
+| `dispatch_tier:` | one of `script\|haiku\|sonnet\|opus\|frontier` | Names the executor tier for the work item (Item 18). `frontier` resolves to Fable (`scripts/model_overrides.py`) and routes the item to the Advisor dispatch ladder for high-stakes generative work. `plan_verify.py` emits an advisory WARN when the tier fights the task: judgment on `script` (`tier-sanity-judgment-on-script`) or a mechanical task on `opus` (`tier-sanity-mechanical-on-opus`). `frontier` never trips a WARN. Never blocks. |
 
 ---
 

package/templates/memory/README.md

@@ -0,0 +1,65 @@
+# build-loop-memory — public seed (scaffolding only)
+
+This folder is the **self-contained seed** for a build-loop-memory store. It is the
+single place that holds everything build-loop ships for memory setup: the generic
+templates, the privacy allowlist (`manifest.json`), and this layout spec.
+
+**What ships vs. what does not.** The memory *store* itself is **private and never
+ships** — it holds personal lessons, project decisions, raw artifacts, and operator
+paths. Only this **scaffolding** ships in the public plugin: generic `*.template`
+files + an allowlisted manifest. `scripts/install_memory.py` *materializes* the store
+from this seed at a **separate root** (`$BUILD_LOOP_MEMORY_ROOT` → legacy
+`~/dev/git-folder/build-loop-memory` → fresh `~/.build-loop-memory`), seeding only
+missing files (idempotent, never overwrites).
+
+## Files in this seed (all of them)
+
+| File | Role |
+|------|------|
+| `manifest.json` | Privacy allowlist + the complete structure spec. `install_memory.py --validate-seed` rejects any seed file not allowlisted here, and scans for secret/PII deny-patterns. |
+| `constitution.md.template` | First-run rule scaffold → `constitution.md` in the store. |
+| `MEMORY.md.template` | Global memory-index scaffold → `MEMORY.md` in the store. |
+| `charter.md.template` | Project-charter scaffold (North Star + commander's-intent + invariants) → `charter.md`. Placeholder bodies; filled per project at run time. |
+| `README.md` | This document. |
+
+Empty directories are **not** shipped (git can't track them, and the manifest is
+strict-allowlist); they are **generated** by `install_memory.py` at setup. The full
+target layout is below and is declared machine-readably in `manifest.json` →
+`generated`.
+
+## Store layout that install_memory.py generates
+
+```
+<memory-root>/                     # private, separate root — NEVER the plugin cache
+├── constitution.md                # from constitution.md.template
+├── MEMORY.md                      # from MEMORY.md.template
+├── charter.md                     # from charter.md.template (optional)
+├── indexes/                       # rebuildable local indexes
+└── projects/
+    ├── README.md                  # generated project-lane guide
+    └── <slug>/                    # one per project (--ensure-project <slug>)
+        ├── raw/                   # raw-source lanes:
+        │   ├── documents/  data/  db/  runtime/
+        │   └── agent-artifacts/  artifacts/  files/
+        ├── apps/        assets/      architecture/  context/
+        ├── decisions/   docs/        features/      formats/
+        ├── indexes/     lessons/     plugins/       product/
+        ├── prompts/     research/    semantic/      skills/
+        └── sources/     testing/     tradeoffs/
+```
+
+`raw/` lanes (7): documents, data, db, runtime, agent-artifacts, artifacts, files.
+Per-project topic dirs (20): apps, assets, architecture, context, decisions, docs,
+features, formats, indexes, lessons, plugins, product, prompts, raw, research,
+semantic, skills, sources, testing, tradeoffs.
+
+## Setup
+
+```bash
+python3 scripts/install_memory.py                      # bootstrap store + seed missing files
+python3 scripts/install_memory.py --ensure-project foo # add projects/foo/ scaffold
+python3 scripts/install_memory.py --check              # status, no writes
+python3 scripts/install_memory.py --validate-seed      # validate THIS seed (allowlist + deny-scan)
+```
+
+The store is the durable, private half; this seed is the public, structure-only half.

package/templates/memory/charter.md.template

@@ -0,0 +1,46 @@
+# Project Charter — {{PROJECT}}
+
+The durable North Star + posture + invariants + key architecture decisions that
+outlive any single run. Canonical here in memory; mirrored to `.build-loop/charter.md`
+each run. Facts ACCRETE: each carries provenance (`inferred` until user-confirmed
+or stable across N runs) and, where it locks a decision, the falsifier that would
+unseat it (decision-quality rule 8).
+
+This is a template — replace the bodies with the project's actual content. Depth
+scales by `stakes`: a low-stakes skill/agent/toy needs none of this; a thin charter
+(North Star + posture) suits medium-stakes web/mobile; a high-stakes system fills
+every section and graduates risk-naming non-goals to enforced invariants.
+
+## North Star
+
+- **Purpose**: <what this product is for and who it serves>
+- **Primary users**: <roles affected>
+- **Core jobs**: <the tasks users rely on most>
+
+## Posture (commander's intent)
+
+- **audience**: <who> — provenance: inferred
+- **stakes**: <low|medium|high> — provenance: inferred
+- **priority_order**: <ordered subset of security/reliability/speed/cost/simplicity/polish>
+  - notes: <free-text expressiveness the fixed vocab can't carry>
+- **acceptable_tradeoffs**: <what is OK to cut under pressure>
+- **non_goals**: <what is never cut>
+  - <at stakes:high, a non_goal that names a REAL risk is an ENFORCED invariant>
+
+## Invariants
+
+Stable rules cited by advisory judges via stable IDs (mirror the constitution
+shape). At `stakes: high`, risk-naming entries are deterministically enforced.
+
+- **INV-<DOMAIN>/<name>**: <rule body> — provenance: <inferred|user-confirmed>
+  - falsifier: <the observation that would unseat this>
+
+## Key architecture decisions
+
+- **<decision>**: <what was decided and why> — provenance: <inferred|user-confirmed>
+  - falsifier: <what would prove it wrong; the revisit trigger>
+
+<!-- Provenance legend: `inferred` (LLM-derived, not yet confirmed) graduates to
+     `user-confirmed` on explicit user statement OR to `stable` after N
+     unchallenged runs. The run is the single writer (from canonical); a user
+     hand-edit of the repo mirror promotes to canonical authored_by:user. -->

package/templates/memory/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "1.0.0",
   "kind": "build-loop-memory-public-seed",
-  "seed_version": "2026-06-07",
-  "description": "Privacy-safe scaffolding for a fresh build-loop-memory store. This manifest allowlists only generic templates and generated directories; it must not include personal lessons, project decisions, raw files, indexes, or operator-specific content.",
+  "seed_version": "2026-06-12",
+  "description": "Self-contained, privacy-safe seed for a fresh build-loop-memory store. Ships the generic templates + this manifest + README; install_memory.py materializes the store at a separate private root. This manifest allowlists only generic templates/docs and declares (in 'generated') the complete directory structure install_memory.py creates. It must not include personal lessons, project decisions, raw files, indexes, or operator-specific content.",
   "sources": [
     {
       "source": "constitution.md.template",
@@ -15,6 +15,18 @@
       "target": "MEMORY.md",
       "required": true,
       "purpose": "Generic global-memory index scaffold for first-run installs."
+    },
+    {
+      "source": "charter.md.template",
+      "target": "charter.md",
+      "required": false,
+      "purpose": "Generic project-charter scaffold (North Star + commander's-intent posture + invariants). Placeholder bodies only; filled per project by the run (WP-F)."
+    },
+    {
+      "source": "README.md",
+      "target": "README.md",
+      "required": false,
+      "purpose": "Human-readable seed + complete layout documentation (allowlisted so --validate-seed passes)."
     }
   ],
   "generated": [
@@ -26,14 +38,22 @@
       "target": "projects/README.md",
       "purpose": "Generic project-scoped memory lane guide generated by install_memory.py."
     },
+    {
+      "target": "projects/<slug>/",
+      "purpose": "Per-project memory lane, created by --ensure-project <slug>."
+    },
     {
       "target": "projects/<slug>/raw/{documents,data,db,runtime,agent-artifacts,artifacts,files}/.gitkeep",
-      "purpose": "Empty raw-source lane placeholders created only when --ensure-project is passed."
+      "purpose": "Empty raw-source lane placeholders (7 lanes) created when --ensure-project is passed."
+    },
+    {
+      "target": "projects/<slug>/{apps,assets,architecture,context,decisions,docs,features,formats,indexes,lessons,plugins,product,prompts,raw,research,semantic,skills,sources,testing,tradeoffs}/",
+      "purpose": "Per-project topic lanes (20) — canonical structure spec, mirrors install_memory.py PROJECT_TOPIC_DIRS."
     }
   ],
   "privacy": {
     "classification": "scaffolding-only",
-    "rule": "The public build-loop package ships templates and empty scaffolds only. Personal memory files, private repository contents, project-specific decisions, raw artifacts, generated indexes, and local operator paths are excluded.",
+    "rule": "The public build-loop package ships templates, this manifest, and the README only. Personal memory files, private repository contents, project-specific decisions, raw artifacts, generated indexes, and local operator paths are excluded. Empty directories are generated at install time, never shipped.",
     "deny_patterns": [
       "(?i)BEGIN (OPENSSH|RSA|DSA|EC) PRIVATE KEY",
       "(?i)\\b(api[_-]?key|secret|password|token)\\s*[:=]\\s*['\\\"][^'\\\"]{8,}",

package/codex-skills/debug-loop/SKILL.md

@@ -1,18 +0,0 @@
----
-name: debug-loop
-description: "Main Build Loop debugging entrypoint. Use for root-cause analysis, failing fixes, crashes, exceptions, broken behavior, and validation failures that need an iterative diagnose-fix-verify loop."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Debug Loop
-
-This is the public Codex entrypoint for Build Loop debugging. The canonical
-implementation remains internal:
-
-```text
-../skills/debug-loop/SKILL.md
-```
-
-Start with diagnosis, use evidence to identify root cause, apply the smallest
-targeted fix, and verify with the repo's native tests or runtime checks.