@tyroneross/build-loop 0.35.0 → 0.36.1

package/scripts/build_codex_plugin_artifact.py

@@ -24,6 +24,7 @@ DEFAULT_TARGET = Path("plugin-artifacts/codex")
 IGNORED_NAMES = {".DS_Store", "__pycache__", ".pytest_cache"}
 IGNORED_SUFFIXES = {".pyc"}
 TOP_LEVEL_FILES = ("AGENTS.md", "README.md", "LICENSE")
+ASSET_FILES = (Path("assets") / "build-loop-plugin-icon.png",)
 
 # Bundle markdown points readers at ``references/<file>.md`` (root-relative).
 # The Claude source resolves that logical namespace across the repo's top-level
@@ -226,6 +227,10 @@ def validate_artifact(target: Path) -> None:
     if rel_files != ["skills/build-loop/SKILL.md"]:
         raise ArtifactError(f"artifact must expose exactly one SKILL.md, got {rel_files}")
 
+    for rel_path in ASSET_FILES:
+        if not (target / rel_path).is_file():
+            raise ArtifactError(f"artifact missing asset: {rel_path}")
+
     check_reference_pointers(target)
 
 
@@ -242,6 +247,8 @@ def build_artifact(source: Path, target: Path) -> None:
         write_codex_manifest(source, tmp / ".codex-plugin" / "plugin.json")
         for name in TOP_LEVEL_FILES:
             copy_file(source / name, tmp / name)
+        for rel_path in ASSET_FILES:
+            copy_file(source / rel_path, tmp / rel_path)
         copy_tree(source / "skills" / "build-loop", tmp / "skills" / "build-loop")
         copy_file(source / "docs" / "agent-surface-policy.md", tmp / "docs" / "agent-surface-policy.md")
         write_notice(tmp / "BUILD-ARTIFACT.md")

package/scripts/embed_backend.py

@@ -17,12 +17,13 @@ vectors are NOT comparable, so callers writing rows must record
 written by a different model. See research entry
 `build-loop-search-architecture` for rationale.
 
-The active backend is chosen on first call from $EMBED_BACKEND
-({"mlx","ollama"}, default "mlx"). If MLX init fails (import error,
-model load error, first-call failure), the module logs a warning to
-stderr and falls through to Ollama for the rest of the process. Once
-fallen through, MLX is not retried — keeps stop-hook latency
-predictable.
+The active backend is chosen on first call. When $EMBED_BACKEND is unset,
+a warm local daemon is preferred; an explicit $EMBED_BACKEND
+({"mlx","ollama"}) bypasses the daemon and selects the requested in-process
+backend. If MLX init fails (import error, model load error, first-call
+failure), the module logs a warning to stderr and falls through to Ollama
+for the rest of the process. Once fallen through, MLX is not retried —
+keeps stop-hook latency predictable.
 
 Public API:
   embed(text)                -> list[float]              (single text)
@@ -372,16 +373,19 @@ def _select_backend():
     if _BACKEND is not None:
         return _BACKEND
 
-    # Phase H: try the daemon FIRST. When it's up, this is the entire
-    # selection — we don't load MLX/Ollama in-process at all.
-    daemon = _probe_daemon()
-    if daemon is not None:
-        _BACKEND = daemon
-        return _BACKEND
-
+    explicit_backend = "EMBED_BACKEND" in os.environ
     requested = os.environ.get("EMBED_BACKEND", "mlx").lower().strip()
     custom_model = os.environ.get("EMBED_MODEL")
 
+    # Phase H: default selection may use the warm daemon. An explicit
+    # EMBED_BACKEND is a caller override and must select the requested
+    # in-process backend even when a daemon is already warm.
+    if not explicit_backend:
+        daemon = _probe_daemon()
+        if daemon is not None:
+            _BACKEND = daemon
+            return _BACKEND
+
     if requested == "ollama":
         _BACKEND = OllamaBackend(model=custom_model or OLLAMA_DEFAULT_MODEL)
         return _BACKEND

package/scripts/lessons_index/query.py

@@ -257,7 +257,7 @@ def _cosine_rerank(conn, candidates: list[dict], goal_vec: list[float]) -> list[
     ids = [r["id"] for r in candidates]
     placeholders = ",".join("?" * len(ids))
     emb_rows = conn.execute(
-        f"SELECT fact_id, vec FROM embeddings WHERE fact_id IN ({placeholders})",
+        f"SELECT fact_id, vec FROM embeddings WHERE fact_id IN ({placeholders})",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
         ids,
     ).fetchall()
     emb_map = {row["fact_id"]: _unpack_floats(row["vec"]) for row in emb_rows}

package/scripts/memory_graph/__init__.py

@@ -242,14 +242,14 @@ class SQLiteEdgesStore:
         if direction in {"out", "both"}:
             rows.extend(
                 self._conn.execute(
-                    f"SELECT * FROM edges WHERE source = ?{rel_sql}",
+                    f"SELECT * FROM edges WHERE source = ?{rel_sql}",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
                     (node_id, *rel_args),
                 ).fetchall()
             )
         if direction in {"in", "both"}:
             rows.extend(
                 self._conn.execute(
-                    f"SELECT * FROM edges WHERE target = ?{rel_sql}",
+                    f"SELECT * FROM edges WHERE target = ?{rel_sql}",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
                     (node_id, *rel_args),
                 ).fetchall()
             )

package/scripts/sync_navgator_lessons.py

@@ -333,19 +333,19 @@ def _upsert_lesson(
     with conn.cursor() as cur:
         if project is None:
             cur.execute(
-                f"DELETE FROM {schema}.semantic_facts "
+                f"DELETE FROM {schema}.semantic_facts "  # nosec: schema is a validated identifier (^[a-z][a-z0-9_]*$); values bound as params
                 "WHERE subject = %s AND project IS NULL;",
                 (subject,),
             )
         else:
             cur.execute(
-                f"DELETE FROM {schema}.semantic_facts "
+                f"DELETE FROM {schema}.semantic_facts "  # nosec: schema is a validated identifier (^[a-z][a-z0-9_]*$); values bound as params
                 "WHERE subject = %s AND project = %s;",
                 (subject, project),
             )
         if vec_lit is None:
             sql = (
-                f"INSERT INTO {schema}.semantic_facts "
+                f"INSERT INTO {schema}.semantic_facts "  # nosec: schema is a validated identifier (^[a-z][a-z0-9_]*$); values bound as params
                 "(subject, predicate, object, confidence, status, embedding, metadata, "
                 " project, tool, task_category, files_touched, "
                 " confidence_source, domain) "
@@ -368,7 +368,7 @@ def _upsert_lesson(
             )
         else:
             sql = (
-                f"INSERT INTO {schema}.semantic_facts "
+                f"INSERT INTO {schema}.semantic_facts "  # nosec: schema is a validated identifier (^[a-z][a-z0-9_]*$); values bound as params
                 "(subject, predicate, object, confidence, status, embedding, metadata, "
                 " project, tool, task_category, files_touched, "
                 " confidence_source, domain) "

package/skills/api-registry-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-registry-bridge
-description: Use when Phase 1 Assess or Phase 5 Iterate detects a new API dependency, API config fails, or the user asks to "register this API" or "check the API registry". Consults api-registry plugin; degrades gracefully if plugin is absent.
+description: Use when Phase 1 Assess or Phase 5 Iterate detects a new API dependency, API config fails, or the user asks to "register this API" or "check the API registry". Consults api-registry plugin; degrades gracefully if plugin is absent. NOT for PRD strategic grounding (use `prd-bridge`) or UI verification (use `ibr-bridge`).
 user-invocable: false
 ---
 

package/skills/auto-decision-capture/SKILL.md

@@ -141,7 +141,7 @@ captures should set these explicitly when the signal is clear:
 | Field | Skill default | Example | When to override |
 |---|---|---|---|
 | `--tool` | `claude-code` (Stop hook fires inside Claude Code) | `claude-code` | If the conversation references another tool authoring the decision (rare) |
-| `--model` | `claude-opus-4-7` (or `$CLAUDE_MODEL`) | `claude-sonnet-4-6` | When you know the active sub-agent's model |
+| `--model` | `claude-opus-4-8` (or `$CLAUDE_MODEL`) | `claude-sonnet-5` | When you know the active sub-agent's model |
 | `--author` | `auto` (skill-driven captures) | `auto` | Always `auto` for in-session skill writes |
 | `--project` | derived from entity prefix or `$CLAUDE_PROJECT_DIR` | `build-loop` | Almost never; the default is right |
 | `--task-category` | `unknown` if no signal | `bugfix`, `feature`, `refactor`, `research`, `docs`, `migration`, `experiment`, `config` | **Set explicitly** whenever the conversational signal is clear (user said "fix this bug" → `bugfix`; "add this feature" → `feature`; "investigate why X" → `research`) |
@@ -367,8 +367,9 @@ self-heals as more signal arrives.
 
 ## When the user runs `/knowledge:review`, surface…
 
-The review surface (loaded by `build-loop:knowledge-review`, backed by
-`scripts/knowledge_review.py`) shows four sections of decisions and
+The review surface (loaded by `build-loop:knowledge` review mode —
+`references/review-mode.md`, backed by `scripts/knowledge_review.py`)
+shows four sections of decisions and
 procedures awaiting human attention:
 
 1. **Review queue** — tier-3 / inferred captures sitting in

package/skills/auto-finding-capture/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: auto-finding-capture
+description: Project-scoped skill documenting build-loop's DEFAULT-ON auto-capture of clearly-identified findings/issues into the backlog, regardless of which terminal or agent surfaced them. Provides the detection contract, routing rules, dedup strategy, and the standing rule that agents/critics must NOT gate identified issues behind a user selection. Use when an agent, audit, or critic surfaces a concrete severity-labeled issue, or when reasoning about where findings persist.
+user-invocable: false
+when_to_use: |
+  - Any agent/audit/critic states a concrete, severity-labeled issue in the session
+  - A dispatched ad-hoc audit (Codex, NavGator, a security pass) returns findings in conversation
+  - You are about to ask the user "which of these should I add to the backlog?" — DON'T; capture is automatic
+  - You need to know where session findings persist and how they dedup
+namespace: .build-loop/backlog/  (review-queue overflow: .build-loop/proposals/)
+companion_scripts:
+  - scripts/scan_findings/__main__.py — Stop-hook deterministic findings sweep
+  - scripts/scan_findings/detect.py — detector (severity-label + structured-JSON extraction)
+  - scripts/backlog.py — the single writer (new/sync/list); mirrors to build-loop-memory on sync
+  - scripts/review_finding_gate.py — canonical severity taxonomy (SEVERITY_MAP), reused for normalization
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# auto-finding-capture — clearly-identified findings land in the backlog by DEFAULT
+
+A clearly-identified finding is durable work. The user should never have to
+remember to add it, and should never be asked to select which findings to keep.
+Whenever ANY agent, audit, or critic surfaces a concrete issue in a session —
+build-loop's own in-run reviewers OR an ad-hoc audit dispatched from a plain
+terminal (Codex, NavGator, a one-off security pass) — that finding is captured
+to the backlog automatically at session end.
+
+## Standing rule (binding)
+
+**Do not gate an identified issue behind a user selection.** If an agent or
+critic has stated a concrete, severity-labeled finding, it is captured — full
+stop. Asking "which of these should I add to the backlog?" is the workflow
+violation this skill exists to remove. Surface findings in conversation AND let
+them persist; the two are not in tension. The user can always drop a backlog
+item later (`status: dropped` + `backlog.py sync`); they cannot recover a
+finding that was never written down.
+
+This mirrors the analogous DEFAULT-ON behavior for DECISIONS
+(`auto-decision-capture` + `scan_transcript_for_decisions.py`) and for
+CORRECTIONS/LESSONS (`scan_corrections`). Findings are the third lane.
+
+## How it works — deterministic Stop-hook sweep
+
+The Stop hook in `hooks/hooks.json` runs `python3 -m scan_findings` against
+`$CLAUDE_TRANSCRIPT_PATH` at session end. It is **deterministic (zero-LLM)** —
+pure regex + JSON parsing, no Ollama dependency — so it fails open with no model
+installed. It scans the agent-authored surface of the transcript: host-assistant
+text blocks AND `tool_result` blocks (where a dispatched sub-agent's condensed
+return lands). It does NOT reach a sub-agent's isolated internal transcript —
+only what surfaces in the session, which is exactly the gap this closes (ad-hoc
+audits report their findings into the conversation).
+
+### What counts as a clearly-identified finding (high precision over recall)
+
+| Signal | Example | Route |
+|---|---|---|
+| **Structured findings JSON** (recognized severity) | `{"findings":[{"severity":"high","title":"Token logged in plaintext"}]}` | **backlog** |
+| **Prose severity label** (UPPERCASE) + concrete clause | `HIGH: verify-install.yml interpolates dispatch input into shell — command injection` | **backlog** |
+| **Explicit `severity:` field** + clause | `severity: medium — cache key collides across tenants` | **backlog** |
+| Structured finding with **absent/unknown severity** | `{"severity":"banana","title":"..."}` | **review queue** |
+| Prose **finding keyword / Bug:/Issue: prefix**, NO severity | `I suspect a race condition in the worker pool` | **review queue** |
+| Anything else (questions, "low latency" prose, hedges) | `Is this high risk?` | ignored |
+
+Routing is MECE: a **recognized severity** → backlog; a **finding signal without
+a recognized severity** → `.build-loop/proposals/` for human triage; **neither**
+→ ignored. A false backlog item is worse than a missed one, so anything short of
+an asserted severity goes to the review queue, never straight to the backlog.
+
+### Backlog mapping
+
+Findings are written through `backlog.py new` (the single, host-agnostic writer
+— never by hand), with:
+
+- `--type fix`, `--area audit`
+- `--priority` from severity: critical→P0, high→P1, medium→P2, low→P3
+- `--provenance-source auto-finding-sweep[:<agent>]` — marks the auto-sweep and
+  the originating agent where detectable (e.g. `auto-finding-sweep:security-reviewer`)
+- `--provenance-ref finding-hash:<hash>` — the cross-session dedup key
+
+### Dedup (idempotent)
+
+Each finding carries a stable `finding-hash` = sha1 of its severity-stripped
+normalized clause. Before writing, the sweep loads every existing backlog item
+(active + archived) and review proposal and collects their hashes + normalized
+titles. A candidate is skipped when its hash already exists OR its normalized
+title equals an existing open item's title. Re-running the sweep on the same
+transcript creates nothing new. The same finding re-stated at a different
+severity (or re-swept on a later Stop) hashes identically and is deduped.
+
+## Hook safety contract
+
+Non-blocking, fail-open, identical guardrails to the decision sweep:
+
+- any error logs and exits 0 (the hook backgrounds with `nohup … &; printf '{}'`)
+- `.build-loop/.no-capture` (per-session opt-out) → clean exit 0
+- single-flight `fcntl.flock` on `/tmp/build-loop-findings-scan.lock`
+- wall-clock budget `SCAN_FINDINGS_BUDGET_S` (default 15s); partial completion is
+  safe (each backlog write is its own atomic `backlog.py new` process)
+- durable log at `${XDG_STATE_HOME:-~/.local/state}/build-loop/findings-scan.log`
+
+## Manual run
+
+```bash
+# What the Stop hook runs (PYTHONPATH lets `-m scan_findings` resolve):
+PYTHONPATH=scripts python3 -m scan_findings \
+  --workdir "$PWD" --transcript "$CLAUDE_TRANSCRIPT_PATH" --print-json
+```
+
+`--print-json` reports `{candidates, backlog, review, skipped_dup}`. After a
+sweep, `python3 scripts/backlog.py sync --repo .` refreshes the INDEX and mirrors
+the new items into `build-loop-memory/projects/<slug>/backlog/`.
+
+## Deferred (NOT built)
+
+An LLM-judged extraction path (for findings stated without a severity label or a
+finding keyword) is a possible future extension. v1 is deterministic-only by
+design: it satisfies the acceptance contract, adds no dependency, and keeps
+precision high. Add the LLM path only against a named, observed miss in this repo.

package/skills/build-loop/SKILL.md

@@ -14,17 +14,22 @@ A 5-phase development loop with a mandatory Phase 6: assess state and criteria,
 
 ## Routing
 
-`/build-loop:run <any task>` is the single entry for all coding work — build, fix, optimize, research, debug, or test. The orchestrator classifies intent automatically and routes to the right mode; no flag or command choice required.
+**`/build-loop:run` is the ONLY human-facing command.** Type it with any request in plain language — or just describe what you need — and the orchestrator classifies intent and routes to the right internal mode. No flags, no picking a mode, no other commands to learn. Everything below is reached by intent, not by a separate command; agents/build-loop invoke these internally.
 
-Internal modes:
+Intent → internal mode:
 
-- **Build** (default): Full 5-phase loop plus mandatory Phase 6 Learn — triggered by implementation, fix, refactor, migrate, or update language
-- **Optimize**: Metric-driven optimization loop — triggered by "speed up", "reduce", "improve" + a mechanical metric (`/build-loop:optimize-run` as a direct override)
-- **Research**: Pre-decision analysis, outputs a research packet, no commits — triggered by "research", "evaluate", "compare", "should I" (`/build-loop:research-run` as a direct override)
-- **Debug**: Deep iterative root-cause investigation — triggered by symptom language; also auto-invoked inside the loop on Review-B failures (`/build-loop:debug` as a direct override)
-- **Test**: Static plugin-test suite — triggered by "test plugin", "validate plugin" (`/build-loop:test` as a direct override)
+- **Build** (default): full 5-phase loop + mandatory Phase 6 Learn — implementation / fix / refactor / migrate / update / "add" / "wire up" language.
+- **Debug**: deep iterative root-cause investigation — symptom language ("broken", "doesn't work", "failing"); also auto-invoked on Review-B failures.
+- **Optimize**: metric-driven optimization loop — "speed up", "reduce", "improve" + a mechanical metric.
+- **Research**: pre-decision analysis, research packet, no commits — "research", "evaluate", "compare", "should I".
+- **Test**: static plugin-test suite — "test plugin", "validate plugin".
+- **Root-cause analysis**: blameless RCA producing durable system levers — "root cause", "why did this fail", "post-mortem" (delegates to the `root-cause-analysis` skill).
+- **Retrospective**: recursive learning retrospective on a build/project — "retrospective", "retro", "what did we learn", "review this project's trajectory" (delegates to `recursive-retrospective`). *Example: "I need a root cause and a retrospective" → run does both.*
+- **Plan / spec**: "write a plan", "spec this" → spec-writing + plan-verify.
+- **PRD**: "start a PRD", "spec out a new app" → prd-bridge / start-prd flow.
+- **Self-improve / promote / knowledge / handoff / memory setup**: "scan recent runs", "promote this experiment", "record a decision", "hand this off", "set up memory" → the matching internal skill (self-improve, promotion-reviewer, knowledge, handoff, setup-memory).
 
-The standalone commands are advanced overrides for forcing a specific mode. Normal usage only needs `/build-loop:run`.
+**Design intent:** one command for humans, plain-language routing, everything else agent-invoked within build-loop. If a request doesn't match a mode, run treats it as a Build task or asks one clarifying question — it never makes the user pick a command.
 
 ### Parallelism config
 
@@ -95,6 +100,8 @@ Self-heal is **both reactive and proactive**. It is not only triggered by errors
 
 **Investigate every open issue to root cause before declaring done — verified by a second subagent.** Before any "done"/completion claim, investigate EVERY open issue — failed tests, loose ends, errors, warnings, minor issues — none are left unaddressed. For each, reach the ROOT CAUSE, not a surface patch. Use the debugging skills (`build-loop:debug-loop` / `root-cause-investigator` / `systematic-debugging`) and/or a **5-whys / causal-tree** analysis to determine the true cause and its blast radius (same root cause at other sites → fix all of them). The fix MUST address the root cause — a surface patch is a violation — AND MUST be verified by another, independent subagent before "done." The second-subagent check reuses `independent-auditor`, `fix-critique`, or a dispatched verifier — no new agent required.
 
+**Closure test (counterfactual):** a root cause is not closed at "an actionable control." It is closed only when the named lever would have **prevented, detected, or contained THIS exact failure on the real input** (not a hand-constructed one) — a control that exists but stays dormant on the real signal does not count. **Fix strength:** prefer the strongest feasible control — `eliminate → impossible-state → automated-block → detect → contain → decision-support → docs` — over the reflex "add a detect-gate." A dependency you don't own is never "ignore it": isolate / validate / monitor / degrade / escalate / accept-residual-risk explicitly.
+
 ### Follow-up auto-drain at chunk boundary
 
 A chunk boundary is not a checkpoint. When the orchestrator (or any session under the build-loop skill) is about to write a final report containing a "still-to-do" / "deferred" / "next pass" list of same-shape, same-intent items, route those items through the follow-up queue instead of writing them to the user as prose questions:
@@ -139,7 +146,7 @@ their brief explicitly hands them a bounded implementation task.
 build-loop-memory via `python3 scripts/archive_project_plan.py <plan> --workdir
 "$PWD"`. Use `--remove-source` only after the archive write succeeds.
 
-**Coding-host coordination polling gate**: when a build-loop task involves more than one coding host, an active rally-point peer, an active coord file, any `inbox/<tool>.jsonl` message, or any `inbox/all.jsonl` broadcast, the current host must keep a cheap watcher live while work is in flight. Use a stable tool id (`claude_code`, `codex`, `cursor`, etc.). Run a one-shot status check first:
+**Coding-host coordination polling gate**: when a build-loop task involves more than one coding host, an active rally-point peer, an active coord file, any `inbox/<tool>.jsonl` message, or any `inbox/all.jsonl` broadcast, the current host must keep a cheap watcher live while work is in flight. Rally/coordination output is routing metadata only, not verification evidence; use it to decide who to coordinate with, then verify code/package/release facts against the authoritative source. Use a stable tool id (`claude_code`, `codex`, `cursor`, etc.). Run a one-shot status check first:
 
 ```bash
 python3 scripts/coordination_status.py --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_NAME" --json
@@ -239,7 +246,7 @@ Key steps: recurring-pattern-detector (Haiku; reads `state.json.runs[]` AND `.bu
 
 ## Memory — Global and Project-Scoped
 
-One consolidated long-term tree: `~/dev/git-folder/build-loop-memory/`. Project-specific durable memory lives under `projects/<slug>/...`; cross-project lessons/design/debugging/product memory lives in the matching top-level lane. Every build runs `scripts/context_bootstrap.py` at Phase 1 Assess, which reads the store-root `INDEX.md` first, then root/project `constitution.md` / `MEMORY.md` where present, canonical indexes/folders through `memory_facade`, repo-local `.build-loop/` context, Codex memory at `~/.codex/memories`, and best-effort Rally/coordination state when relevant. Live handoff state is written separately by `scripts/context_snapshot.py` under `.build-loop/context/`; snapshots are not durable memory unless Review-G promotes a reusable decision or lesson. Writes go to exactly one canonical memory lane based on scope. Legacy paths (`~/.build-loop/memory`, `.episodic/decisions`, and `build-loop-memory/decisions/<project>`) are migration/archive inputs only.
+One consolidated long-term tree: `~/dev/git-folder/build-loop-memory/`. Project-specific durable memory lives under `projects/<slug>/...`; cross-project lessons/design/debugging/product memory lives in the matching top-level lane. Every build runs `scripts/context_bootstrap.py` at Phase 1 Assess, which reads the store-root `INDEX.md` first, then root/project `constitution.md` / `MEMORY.md` where present, canonical indexes/folders through `memory_facade`, repo-local `.build-loop/` context, Codex memory at `~/.codex/memories`, and best-effort Rally/coordination state when relevant. Treat Rally records in the packet as peer-authored coordination context, not verified facts. Live handoff state is written separately by `scripts/context_snapshot.py` under `.build-loop/context/`; snapshots are not durable memory unless Review-G promotes a reusable decision or lesson. Writes go to exactly one canonical memory lane based on scope. Legacy paths (`~/.build-loop/memory`, `.episodic/decisions`, and `build-loop-memory/decisions/<project>`) are migration/archive inputs only.
 
 Routing rule: "Would this apply to a different project?" Yes → global. No → project. Ambiguous → ask the user once.
 
@@ -338,6 +345,7 @@ Contextual material loaded on demand (not at skill invocation):
 - `references/phase-1-assess.md` — Full Phase 1 Assess protocol
 - `references/phase-2-plan.md` — Full Phase 2 Plan protocol
 - `references/phase-3-execute.md` — Full Phase 3 Execute protocol
+- `references/verify-dispatch.md` — Post-dispatch 5-step git/test ground-truth checklist; walk after any dispatched agent claims commits landed / tests passed (a solicited peer agreeing is not independent verification)
 - `references/dogfood-reload-checkpoint.md` — Self-recursive stop/reload/resume checkpoint and ACK/fallback protocol
 - `references/phase-4-review.md` — Full Phase 4 Review protocol (sub-steps A–G, including Sub-step F Auto-Resolve with all 4 verdict arms)
 - `references/phase-5-iterate.md` — Full Phase 5 Iterate protocol
@@ -346,6 +354,7 @@ Contextual material loaded on demand (not at skill invocation):
 - `references/leadership.md` — Initiative + decision-escalation doctrine (decide-at-70%, self-research → memory → peers → persona panel → human-only-for-irreversible, parallel-work-before-idling, token-posture gauge). Synthesized from intent-based leadership / mission command / two-door decisions.
 - `references/research-trigger-policy.md` — Research plugin trigger/depth gate, t-shirt depth lower bounds, and final-claim citation/unavailable rule
 - `references/task-capture-policy.md` — Read-only active task surface over existing plan/state/queue/backlog surfaces; no new task ledger by default
+- `references/backlog-system.md` — Host-agnostic, multi-repo backlog system: MD+YAML items (canonical truth) + regenerable INDEX, pure-stdlib `scripts/backlog.py` (new/sync/list), one-way mirror to personal memory. Read via `BACKLOG.md`→`INDEX.md`→grep; write via the CLI
 - `references/agent-role-taxonomy.md` — Lead/peer/coder-assessor/reviewer/skill responsibility map; use before adding or renaming agents.
 - `references/capability-routing.md` — Full capability routing table, trigger conditions, sub-routers
 - `references/recent-design-structures.md` — Recent UI structure library loaded by `design-contract-specialist` in Phase 2. Structures are options, not mandates.

package/skills/build-loop/fallbacks.md

@@ -418,7 +418,7 @@ Use the **6-Part Stack** for any system prompt or agent prompt:
 Calibrate to model tier:
 
 - **Frontier (T1 — Opus 4.6, GPT-5)**: can handle longer instructions, implicit reasoning, self-correction. Prefer clarity over verbosity.
-- **Mid (T2 — Sonnet 4.6, GPT-4)**: explicit instructions; show, don't tell; 1-2 few-shot examples help.
+- **Mid (T2 — Sonnet 5, GPT-5 class)**: explicit instructions; show, don't tell; 1-2 few-shot examples help.
 - **Small/fast (T3 — Haiku 4.5, gpt-4-mini)**: keep prompts short; single task only; deterministic output format; more examples (3-5).
 
 Review checklist — when auditing an existing prompt:

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

@@ -25,6 +25,55 @@ Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` a
 | Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
 | Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
 
+### Spec/Plan author router (intent-driven, ordered)
+
+This router selects the single skill that AUTHORS the plan/spec/task graph for this run. It is a recommendation that DRIVES Phase 2 — recorded into `state.json.intent.spec_router`, consumed by Phase 2 Plan, never a hard block.
+
+**Scope — author selection only.** `prd-bridge` is NOT in this router. It is mandatory in Phase 1 step 10 and only *consumes* an existing PRD (`docs/prd-*.md` → `state.json.prd`); it never authors. PRD-context is orthogonal to author selection — keep them separate.
+
+**Governing rule**: select on intent + goal + context, not on a trigger-word match. A skill's word-overlap activation is not enough to call it (this is why `prd-builder` over-fired during build-loop runs). The router is the intent-side selection; it pairs with the activation-side guard (prd-builder's negative-trigger scope, which excludes in-flight changes and active build-loop runs).
+
+Signals (all set during Phase 1 Assess):
+
+- `run_active` — is a build-loop run active? (`true` for any `/build-loop:run` or build-orchestrator dispatch.)
+- `plan_status` — `no-plan` | `plan-valid`, from the Phase 2 plan-exists gate (`.build-loop/plan.md` absent/empty + last `plan-verify` result).
+- `intent_kind` — `PRD-author` | `build-plan` | `task-graph` | `none`, the LLM's read of what this run needs authored.
+- `code_exists` — does the repo have substantive existing code? (Assess maps architecture: new/empty repo → false, existing repo → true.)
+- `goal_scope` — `new-app` | `existing-app-change` | `in-build-task-breakdown`.
+
+The rows are ORDERED — first match wins, so exactly one author is selected and no case matches two. The final default row makes the table exhaustive: every `(run_active, plan_status, intent_kind)` combination matches exactly one row, so nothing falls through.
+
+| # | Match condition (first true wins) | route_type / action | Author selected | Why |
+|---|---|---|---|---|
+| 1 | `intent_kind == none` — nothing to author (Q&A, status, trivial, read-only, or advisory-context-only) | `noop` (call nothing) | — (`skill: null`) | no plan/spec/task graph needed |
+| 2 | `run_active == false` AND greenfield PRD authoring is explicitly intended (new app with no code, OR `/start-prd` requested for a project) | `call` (or `recommend` outside an interactive session) | `prd-builder` | greenfield authoring + interactive intake; honors prd-builder's negative trigger — never fires inside an active run |
+| 3 | `run_active == true` AND `plan_status == no-plan` | `call` | `build-loop:spec-writing` | author the in-build, non-interactive, gated plan for the orchestrator |
+| 4 | `run_active == true` AND `plan_status == plan-valid` | `call` | `build-loop:writing-plans` (external) | turn the accepted plan into the task / dependency graph |
+| 5 (default) | else (no earlier row matched) — the canonical case is `run_active == false` AND `intent_kind` is `build-plan` or `task-graph`: a direct, out-of-run invocation of plan authoring on an existing repo | `recommend` | `build-loop:spec-writing` | recommend, not auto-call: there is no active run to drive, so surface the author for the lead to run if it chooses |
+
+The order is the contract: row 1 short-circuits before any author runs; row 2 is the only PRD author and is fenced off from active runs; rows 3 and 4 are mutually exclusive on `plan_status`; row 5 is the exhaustive `else` default that catches every remaining combination — its canonical case is an out-of-run `build-plan`/`task-graph` intent, but as the final row it also absorbs any residual (e.g. an out-of-run non-greenfield `PRD-author`) so no signal combination ever falls through. The table extends to any future author skill — add a row at the right precedence above the default, key it on the same signals, and the system still selects exactly one and records why.
+
+`build-loop:writing-plans` (row 4) is the **external** `writing-plans` skill from the superpowers plugin — it is not vendored in this repo (`skills/writing-plans/SKILL.md` does not exist here). When it is absent, fall back to the inline "write a structured plan directly" path in the §"Core loop skills/assets" table above.
+
+> Future refinement (do not over-build now): for monorepos, a `target_code_exists` signal (does the *target sub-path* already have code, vs the repo as a whole) would refine row 2's greenfield test. Out of scope until a monorepo case demands it.
+
+**Phase 1 record (the consumable contract)**. Phase 1 writes the matched decision into `state.json.intent.spec_router` so a Codex lead (no `Skill()` auto-activation) can consume it deterministically:
+
+```json
+{
+  "route_type": "author",
+  "action": "call" | "recommend" | "noop",
+  "skill": "build-loop:spec-writing" | "build-loop:writing-plans" | "prd-builder" | null,
+  "fallback": "<fallbacks.md section or inline guidance> | null",
+  "matched_row": 1 | 2 | 3 | 4 | 5,
+  "signals": { "run_active": true, "plan_status": "no-plan", "intent_kind": "build-plan", "code_exists": true, "goal_scope": "existing-app-change" }
+}
+```
+
+`action: "noop"` → `skill: null`, Phase 2 authors nothing from the router (terminal). `action: "recommend"` → `skill` carries the recommended author name (so the lead knows what to run if it chooses); Phase 2 surfaces the recommendation in the report and does NOT auto-call. `action: "call"` → `skill` is non-null and Phase 2 calls it. The three actions are distinct: `call` auto-invokes, `recommend` surfaces-only, `noop` skips.
+
+**Phase 2 read (the load-bearing wire)**. Phase 2 Plan READS `state.json.intent.spec_router` and acts on `action`/`skill` — it does NOT independently re-decide which author to call. See `references/phase-2-plan.md` step 0.
+
 ### Phase quick reference
 
 | # | Phase | Purpose | Sub-steps / key actions |

package/skills/build-loop/references/experiment-results-template.md

@@ -0,0 +1,101 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+<!-- CONFIG: v1.0 | T2 | plugin(report-writeup) | Analytical | SCORE: 22/25 [A:5|C:4|Cs:5|D:4|Cp:4] -->
+
+# Experiment / data-analysis results — reusable template + guide
+
+One write-up shape for any analysis: A/B, DOE / full-factorial / fractional-factorial,
+regression, backtest, ablation, regression-test. Fill the blanks; delete the Method
+sub-lines that don't apply; never delete the honesty rails (n, direction legend,
+certainty, "not computed — why").
+
+---
+
+## The template (copy below this line)
+
+```markdown
+# <test name> — results
+<!-- headline: DECISION: <build X / don't / inconclusive> · certainty: <high|medium|low> · n=<N> -->
+
+## Objective
+- **Testing:** <the one thing under test>
+- **Why:** <the recurring problem or the decision this informs>
+- **Payoff if it succeeds (user-visible):** <what changes for the end user / consumer>
+- **Decision this unblocks:** <what we do differently on a pass vs a fail>
+
+## What we did
+- **Analysis type:** <A/B | DOE full-factorial | fractional-factorial | regression | backtest | ablation | regression-test | other>
+- **Method (1 paragraph):** <how it ran, start to finish>
+- **Sample size n = <N>** (<unit: bugs / runs / requests / rows / sessions>)  ← never omit
+- **Arms / factors** (keep the line that fits your type):
+  - A/B: control = <...> · treatment(s) = <...>
+  - DOE/factorial: factors × levels = <...> · runs = <...> · design = <full | fractional res IV | ...>
+  - Regression: predictors = <...> · response = <...> · model = <OLS | logistic | ...>
+  - Backtest: data + window = <...> · in/out-of-sample split = <...>
+  - Ablation: component removed = <...> · baseline = <...>
+- **Held constant (confounds managed):** <model, environment, inputs, seed, …>
+- **Measurement:** <who/what scored, against what ground truth, and exactly how>
+  - Blinding: <none | labels withheld | fully blinded> — <if you claim blinded, say what made it so; if a tell leaked, say so>
+
+## Hypothesis
+- **Predicted:** <outcome> **because** <mechanism / prior reason>
+- **Pass means:** <what it implies> → **action:** <...>
+- **Fail means:** <what it implies> → **action:** <...>
+- **Pre-registered?** <yes + link | no> · decision rule fixed before running? <yes | no>
+
+## Results
+
+**Metric legend — state direction for EVERY metric (this is mandatory):**
+| Metric | Measures | Direction | Scale |
+|--------|----------|-----------|-------|
+| <m1> | <...> | higher better / lower better | <0–2 · % · ms · count · $> |
+| <cost> | effort/latency/$ | lower better (only counts when quality ties or wins) | <calls · s · $> |
+
+**Data:**
+| <arm / run / config> | <m1> | <m2> | <cost> |
+|---|---|---|---|
+| <...> | | | |
+
+**Statistics — fill what you actually computed; for the rest write "not computed — <why>":**
+- **Effect size:** <metric: value (e.g. Δ, Cohen's d, lift %)> | not computed — <why>
+- **Statistical significance:** <test, p-value, CI> | **NOT COMPUTABLE — n=<N> too small (directional only)**
+- **Correlation:** <vars: r> | not computed — <why>
+- **Goodness of fit** (regression only): <R², adj-R², residual check> | n/a
+- **Winner / direction:** <which, on which metrics>
+
+## Interpretation
+- **Certainty:** ✅ high | ⚠️ medium | ❓ low — <why, tied to n + method strength>
+- **What it shows / does NOT show:** <scope of the claim>
+- **Threats to validity / confounds:** <weak blinding (how), small n, self-selected subject, model substitution, single grader, …>
+- **Unknowns:** <what could not be verified>
+- **Honesty check:** every adjective here is earned by the method — no "fair / blind / significant / proven" unless the method above supports it.
+
+## Next steps
+- [ ] **Implement winner:** <...>  (or: do not implement — <why>)
+- [ ] **Stronger re-test:** <what raises certainty — larger n, cleaner blinding, a real significance test, second grader>
+- [ ] **New tests suggested:** <...>
+- [ ] **Risks to monitor after rollout:** <...>
+```
+
+---
+
+## Usage guide
+
+1. **Pick one Method sub-line** for your analysis type; delete the others. The honesty
+   rails — `n`, the direction legend, the statistics block, certainty — stay regardless
+   of type.
+2. **Direction legend is not optional.** A table of numbers is unreadable without "higher
+   or lower better" per metric. Cost metrics (calls, time, $) are lower-better but only
+   count as a win when quality ties or improves (Accuracy > Speed > Cost).
+3. **When stats don't apply, say so explicitly** — never leave significance/correlation/
+   fit blank or imply them. Rules of thumb: significance/correlation need roughly n ≥ 8–10+
+   to mean anything; below that write "directional only (n too small)". Regression fit
+   (R²) is n/a unless you actually fit a model. DOE reports main effects + interactions,
+   not p-values, unless replicated.
+4. **Earn every adjective.** Do not write "fair", "blind", "robust", "significant", or
+   "proven" unless the Method section shows what made it so. If blinding leaked (e.g. the
+   treatment's output format was a tell), record it as a threat to validity — don't claim
+   blindness.
+5. **Headline = decision + certainty + n.** A decision-maker should get "build it / don't /
+   inconclusive", how sure, and on how much data, from the first line.
+6. **Pre-register when the result will drive a real decision** — commit Objective +
+   Hypothesis + decision rule before running, so the verdict can't be retrofit.

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

@@ -136,6 +136,20 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
 
 The writer auto-detects `source_repo` from the workdir's git remote, appends a row to the lane-local `INDEX.jsonl`, appends a row to the global update ledger at `indexes/updates.jsonl`, and (on update) preserves `created_at` + `applied_in_repos` so cross-repo validation history survives edits. Direct writes are repair/fallback work only: use them only when no canonical writer exists or the current task is explicitly a memory-system repair, then run the host index/check step and verify reachability.
 
+### Codex cross-repo write guard
+
+When using Codex `apply_patch`, path resolution is relative to the active
+workspace, not to a shell command `workdir`. If a memory artifact belongs in a
+different repo such as `build-loop-memory`, use one of these safe paths:
+
+- Prefer `scripts/memory_writer.py` for normal memory writes.
+- If direct repair is unavoidable, pass absolute target paths to `apply_patch`.
+- Before moving a generated file that already appeared in a Codex file card,
+  leave an openable pointer, mirror, or stub at the old path and update any
+  dependent indexes/links. Do not strand UI/Finder file cards at missing paths.
+- After a move, verify both the canonical destination and every old path that a
+  user-facing file card, index, or markdown link still references.
+
 ### Reader side — surface peer writes via INDEX.jsonl
 
 Between phases (or at every M2 heartbeat), tail since your last check: