@tyroneross/build-loop 0.30.3 → 0.35.0

package/skills/loop-builder/scripts/loop_builder.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Generate focused-loop packs from preset specs.
+
+Preset files use YAML-compatible JSON so this tool stays stdlib-only while the
+generated loop spec remains readable YAML.
+"""
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+SKILL_ROOT = HERE.parent
+PRESETS_DIR = SKILL_ROOT / "presets"
+
+IDENTIFIER_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+class LoopBuilderError(RuntimeError):
+    pass
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    slug = re.sub(r"-+", "-", slug)
+    if not slug:
+        raise LoopBuilderError("loop id cannot be empty")
+    return slug
+
+
+def require_identifier(value: str, *, field: str) -> str:
+    slug = slugify(value)
+    if not IDENTIFIER_RE.match(slug):
+        raise LoopBuilderError(f"{field} must be kebab-case: {value!r}")
+    return slug
+
+
+def preset_paths() -> list[Path]:
+    return sorted(PRESETS_DIR.glob("*.yaml"))
+
+
+def available_presets() -> list[str]:
+    return [path.stem for path in preset_paths()]
+
+
+def load_preset(name: str) -> dict[str, Any]:
+    preset_id = require_identifier(name, field="preset")
+    path = PRESETS_DIR / f"{preset_id}.yaml"
+    if not path.is_file():
+        choices = ", ".join(available_presets()) or "(none)"
+        raise LoopBuilderError(f"unknown preset {preset_id!r}; available: {choices}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LoopBuilderError(f"invalid preset JSON in {path}: {exc}") from exc
+    validate_preset(data, source=path)
+    return data
+
+
+def validate_preset(data: dict[str, Any], *, source: Path | None = None) -> None:
+    required = ("id", "title", "summary", "inputs", "outputs", "phases", "validators", "gates", "skill_chain", "learn")
+    missing = [key for key in required if key not in data]
+    if missing:
+        label = str(source) if source else data.get("id", "<preset>")
+        raise LoopBuilderError(f"{label} missing required fields: {', '.join(missing)}")
+    require_identifier(str(data["id"]), field="preset id")
+    if not isinstance(data["phases"], dict) or not data["phases"]:
+        raise LoopBuilderError(f"{data['id']} phases must be a non-empty object")
+    if not isinstance(data["validators"], list) or not data["validators"]:
+        raise LoopBuilderError(f"{data['id']} validators must be a non-empty list")
+    if not isinstance(data["skill_chain"], dict):
+        raise LoopBuilderError(f"{data['id']} skill_chain must be an object")
+
+
+def scalar_to_yaml(value: Any) -> str:
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if value is None:
+        return "null"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def to_yaml(value: Any, indent: int = 0) -> str:
+    pad = " " * indent
+    if isinstance(value, dict):
+        if not value:
+            return pad + "{}"
+        lines: list[str] = []
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                if not item:
+                    lines.append(f"{pad}{key}: {to_yaml(item, 0).strip()}")
+                else:
+                    lines.append(f"{pad}{key}:")
+                    lines.append(to_yaml(item, indent + 2))
+            else:
+                lines.append(f"{pad}{key}: {scalar_to_yaml(item)}")
+        return "\n".join(lines)
+    if isinstance(value, list):
+        if not value:
+            return pad + "[]"
+        lines = []
+        for item in value:
+            if isinstance(item, (dict, list)):
+                lines.append(f"{pad}-")
+                lines.append(to_yaml(item, indent + 2))
+            else:
+                lines.append(f"{pad}- {scalar_to_yaml(item)}")
+        return "\n".join(lines)
+    return pad + scalar_to_yaml(value)
+
+
+def build_loop_spec(preset: dict[str, Any], *, loop_id: str, title: str | None, preset_name: str) -> dict[str, Any]:
+    spec = copy.deepcopy(preset)
+    spec["schema_version"] = 1
+    spec["id"] = loop_id
+    spec["source_preset"] = preset_name
+    if title:
+        spec["title"] = title
+    return spec
+
+
+def render_loop_yaml(spec: dict[str, Any]) -> str:
+    header = [
+        "# Generated focused-loop spec.",
+        "# Edit the artifact contract, validators, and skill_chain before using on high-stakes work.",
+        "",
+    ]
+    return "\n".join(header) + to_yaml(spec) + "\n"
+
+
+def render_rubric(spec: dict[str, Any]) -> str:
+    lines = [
+        f"# {spec['title']} Rubric",
+        "",
+        spec["summary"],
+        "",
+        "## Binary Validators",
+        "",
+        "| Validator | Pass Condition | Method |",
+        "|---|---|---|",
+    ]
+    for validator in spec["validators"]:
+        lines.append(
+            f"| `{validator['id']}` | {validator['pass_condition']} | {validator.get('method', 'review')} |"
+        )
+    lines.extend(
+        [
+            "",
+            "## Confirmation Gates",
+            "",
+        ]
+    )
+    for gate_name, gate_items in spec.get("gates", {}).items():
+        lines.append(f"### {gate_name}")
+        lines.append("")
+        for item in gate_items:
+            lines.append(f"- `{item}`")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_report_template(spec: dict[str, Any]) -> str:
+    validator_rows = "\n".join(f"| `{item['id']}` | pass/fail | evidence |" for item in spec["validators"])
+    outputs = "\n".join(f"- {item}" for item in spec["outputs"])
+    return f"""# {spec['title']} Report
+
+## Bottom Line
+
+[One sentence: what changed, what decision/artifact is ready, and what remains open.]
+
+## Outputs
+
+{outputs}
+
+## Evidence
+
+- [source path / transcript timestamp / row or slide reference]
+
+## Validator Results
+
+| Validator | Verdict | Evidence |
+|---|---|---|
+{validator_rows}
+
+## Gates
+
+- External send/publish: [clear/confirm]
+- Sensitive data exposure: [clear/confirm]
+- Irreversible source-of-truth change: [clear/confirm]
+
+## Learn
+
+- Reusable artifact:
+- Source quirks:
+- Rubric failures:
+"""
+
+
+def render_validator(spec: dict[str, Any]) -> str:
+    required_tokens = ["schema_version", "id", "phases", "validators", "gates", "skill_chain", "learn"]
+    token_literal = repr(required_tokens)
+    return f'''#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Basic generated validator for the {spec["id"]} loop pack."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+REQUIRED_FILES = [
+    ROOT / "loop.yaml",
+    ROOT / "rubric.md",
+    ROOT / "templates" / "report.md",
+]
+REQUIRED_TOKENS = {token_literal}
+
+
+def main() -> int:
+    missing = [str(path.relative_to(ROOT)) for path in REQUIRED_FILES if not path.is_file()]
+    if missing:
+        print("missing required files: " + ", ".join(missing), file=sys.stderr)
+        return 1
+    text = (ROOT / "loop.yaml").read_text(encoding="utf-8")
+    absent = [token for token in REQUIRED_TOKENS if token + ":" not in text]
+    if absent:
+        print("loop.yaml missing required fields: " + ", ".join(absent), file=sys.stderr)
+        return 1
+    print("loop pack ok: " + str(ROOT))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+'''
+
+
+def write_file(path: Path, content: str, *, executable: bool = False) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    if executable:
+        path.chmod(0o755)
+
+
+def create_loop(
+    *,
+    loop_id_raw: str,
+    preset_name: str,
+    output: Path | None,
+    title: str | None,
+    force: bool,
+) -> Path:
+    loop_id = require_identifier(loop_id_raw, field="loop id")
+    preset_id = require_identifier(preset_name, field="preset")
+    preset = load_preset(preset_id)
+    spec = build_loop_spec(preset, loop_id=loop_id, title=title, preset_name=preset_id)
+    target = output.expanduser().resolve() if output else (Path.cwd() / ".build-loop" / "loops" / loop_id).resolve()
+    if target.exists():
+        if not force:
+            raise LoopBuilderError(f"target already exists: {target}; pass --force to replace")
+        shutil.rmtree(target)
+    write_file(target / "loop.yaml", render_loop_yaml(spec))
+    write_file(target / "rubric.md", render_rubric(spec))
+    write_file(target / "templates" / "report.md", render_report_template(spec))
+    write_file(target / "validators" / "validate_loop.py", render_validator(spec), executable=True)
+    write_file(
+        target / "README.md",
+        f"# {spec['title']}\n\nGenerated from `{preset_id}`. Start with `loop.yaml`, then run `python3 validators/validate_loop.py`.\n",
+    )
+    return target
+
+
+def cmd_list(_args: argparse.Namespace) -> int:
+    for name in available_presets():
+        preset = load_preset(name)
+        print(f"{name}\t{preset['title']}")
+    return 0
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    preset = load_preset(args.preset)
+    print(render_loop_yaml(build_loop_spec(preset, loop_id=preset["id"], title=None, preset_name=preset["id"])))
+    return 0
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    target = create_loop(
+        loop_id_raw=args.loop_id,
+        preset_name=args.preset,
+        output=Path(args.output) if args.output else None,
+        title=args.title,
+        force=args.force,
+    )
+    print(f"created loop pack: {target}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    list_parser = sub.add_parser("list", help="List available loop presets.")
+    list_parser.set_defaults(func=cmd_list)
+
+    inspect_parser = sub.add_parser("inspect", help="Print a preset as generated loop YAML.")
+    inspect_parser.add_argument("preset")
+    inspect_parser.set_defaults(func=cmd_inspect)
+
+    create_parser = sub.add_parser("create", help="Create a focused-loop pack.")
+    create_parser.add_argument("loop_id")
+    create_parser.add_argument("--preset", required=True, help="Preset name from `list`.")
+    create_parser.add_argument("--output", help="Target directory. Defaults to .build-loop/loops/<loop-id>.")
+    create_parser.add_argument("--title", help="Override generated title.")
+    create_parser.add_argument("--force", action="store_true", help="Replace an existing target directory.")
+    create_parser.set_defaults(func=cmd_create)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except LoopBuilderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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.