@tyroneross/build-loop 0.34.0 → 0.36.0

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:

package/skills/build-loop/references/output-style.md

@@ -10,16 +10,18 @@ It extends — does not duplicate — the existing guidance:
 
 Scope: **user-facing output only.** Internal agent-to-agent envelopes (subagent return JSON, judge-decisions, run records, MECE briefs) are structured data and stay as-is — they exist for machines, not the human.
 
-## The five rules
+## The rules
 
 1. **Headline = one plain full sentence** stating what changed. First non-blank line. Not a noun phrase, not a telegraph fragment, not a heading.
-2. **Bulleted concrete artifacts.** Below the headline: commit hashes, file paths, issue paths. Concrete things the user can grep, open, or `git show`.
-3. **Substance bullets.** What the change captures or does, in plain language. Optional when the artifacts alone are self-explanatory.
-4. **Validation line, explicit.** Name the exact command, method, or observer that verified the work, with a status marker:
+2. **Outcome framing — lead with what changes for the user.** The headline and substance lead with what the user can now do, what stops failing, or what no longer needs a manual step — the *result*, not the implementation. Use before→after when it clarifies. Mechanism, file paths, and design detail still belong in the report — below the lead, in the progressive-disclosure detail (see rules 3–4), never in the headline. See "Outcome framing" below for the worked good/bad pair.
+3. **Bulleted concrete artifacts.** Below the headline: commit hashes, file paths, issue paths. Concrete things the user can grep, open, or `git show`.
+4. **Substance bullets.** What the change does for the user, in plain language (outcome-first per rule 2). Optional when the artifacts alone are self-explanatory.
+5. **Validation line, explicit.** Name the exact command, method, or observer that verified the work, with a status marker:
    - `✅ Verified by <method>` — ran the script, passing test, curl response, IBR scan, demo
    - `⚠️ Untested — <what couldn't be verified and why>`
    - `❓ Uncertain — <what's assumed and what would close it>`
-5. **Plain language.** No jargon (see blocklist below). No contrastive pivot (`not X — it's Y`, `isn't X, it's Y`, `not just X but Y`) — state the point directly.
+6. **Plain language, stated directly.** No jargon (see blocklist below). No contrastive pivot (`not X — it's Y`, `isn't X, it's Y`, `not just X but Y`) and no soft hedging — state the point directly, and state cause and effect directly (see "Precision and Brevity" below: shorter words, data over adjectives, direct cause→effect). The contrastive-pivot ban and the direct-cause-and-effect rule are the same instinct: say what happened and why, without negation or padding.
+7. **Numbers only when supplied or verified.** Never invent a metric, date, percentage, or count to make a sentence concrete. This is the user-facing-style restatement of build-loop's existing "no false data, no unverified claims" guarantee — the fact-checker (Review-D) traces every rendered metric to its source; this rule keeps the report from adding one the fact-checker never saw. If you have no number, write the plain claim without one.
 
 ## Jargon blocklist (user-facing only)
 
@@ -39,6 +41,97 @@ These tokens are fine in internal envelopes; they must be translated to plain la
 | `state.json.runs[]` | "run record" |
 | Internal phase codenames (C-HEAL, C-RCA, C-FLOW…) | Describe the behavior, not the code |
 
+## Outcome framing — lead with the result, not the mechanism
+
+The report describes what the change DOES FOR THE USER, not the feature or mechanism that delivers it. Lead with what the user can now do, what stops failing, or what no longer needs a manual step. Before→after where it clarifies. Plain language, minimal jargon. The mechanism — script names, normalization, TTLs, file paths — still appears, but in the progressive-disclosure detail below the lead, never in the headline or the first substance line.
+
+This is judgment, not a deterministic check: `report_lint.py` does NOT grade outcome framing (a fuzzy "is this outcome-framed?" rule would false-green on disguised mechanism prose and false-block on terse-but-correct outcome reports). The rule is enforced by the Review-G one-pass self-heal — the orchestrator rewrites a mechanism-only lead into an outcome-first one before emitting.
+
+### Good — outcome-framed (the user-approved target style)
+
+```
+When you run build-loop and a model it depends on goes down, the work now keeps
+running on a backup instead of stopping and waiting for you to step in — and when
+that model comes back, it returns to it on its own. You stop having to be the
+manual fallback.
+
+- No more stalled runs during an outage — if the preferred model is unavailable,
+  agents automatically continue on the next-best one, instead of erroring out and
+  needing a restart.
+- Self-recovery — once the model is back, the system returns to it within about
+  half an hour by itself, rather than staying on the backup until someone resets it.
+- Quality holds during fallback — it won't quietly drop verification to a weaker
+  model, and won't pick a model the setup can't run.
+- Works as you add or change models — the same behavior applies no matter which
+  vendor a model comes from.
+```
+
+Why this is good: the headline says what changes for the user ("the work now keeps running … you stop having to be the manual fallback"), each bullet leads with the user-visible outcome (no stalled runs, self-recovery, quality holds, works as you change models), and the before→after contrast ("instead of stopping and waiting", "rather than staying on the backup") makes the gain concrete. The mechanism that delivers it (the fallback script, the recovery window, the tier floor, vendor-agnostic resolution) is implied through outcomes, not enumerated.
+
+### Bad — mechanism-only (same change, tells the user nothing)
+
+```
+Added dispatch_fallback.py with canonical-id normalization and a host-provider
+filter; outages persist to model-availability.json with a TTL.
+```
+
+Why this is bad: it is the exact same change, but described as the feature/implementation. The reader learns what files exist, not that their runs stop stalling during an outage or that quality holds on the backup. It leads with the mechanism (`dispatch_fallback.py`, `canonical-id normalization`, `host-provider filter`, `model-availability.json`, `TTL`) and never states the user outcome. The fix is the rewrite above: keep this detail, but move it below an outcome-first lead.
+
+## Precision and Brevity — sentence architecture
+
+Clear, concise statements depend less on better words and more on sentence architecture. Strongest pattern: concrete noun + strong verb + specific object/outcome + cause/evidence when needed.
+
+### 1. Core elements of a clear sentence
+| Element | Job | Strong | Weak |
+|---|---|---|---|
+| Actor/subject | Who or what it is about | The team | There was |
+| Verb | What happened/changed | launched, cut, missed, caused | had, was, experienced |
+| Object/outcome | What the action affected | the onboarding flow | the process |
+| Cause | Why it happened | because ownership was split | due to various issues |
+| Metric/evidence | What proves it | 70% dropped at step 5 | many users struggled |
+| Time/place | When/where | in Q2, at step 5 of 7 | recently, during the process |
+| Implication | Why it matters | so the team should shorten setup | which is important |
+
+Core sentence spine: [Actor] [verb] [object/outcome] [because cause].
+Example: The team launched behind schedule because ownership was split across three groups.
+
+### 2. Parts of speech: what to favor
+- Nouns — concrete: name real things/people/roles/systems/outcomes. ("Users abandoned onboarding at step 5." not "There was friction in the user journey.")
+- Verbs — carry the sentence: had an impact on→changed; was responsible for→caused; made improvements to→improved; experienced delays→slipped; provided support for→supported; made a decision→decided.
+- Adjectives — only when they add precision: "missed the regulatory deadline" (why it matters) not "an important deadline" (asks for trust).
+- Adverbs — usually replace with data: significantly increased→increased 42%; quickly resolved→resolved in two days; frequently failed→failed in 3 of 5 tests; strongly suggests→suggests; materially improved→improved conversion by 8 points.
+
+### 3. Most useful sentence patterns
+1. Outcome → Cause — [Actor] [outcome] because [cause]. ("The model gave inconsistent answers because the prompt lacked success criteria.")
+2. Metric → Behavior → Location → Meaning — [Metric] of [group] [behavior] at [point], suggesting [meaning]. ("70% of users abandoned onboarding at step 5 of 7, suggesting the flow was too long.") Use "suggesting" when data implies but does not prove a cause.
+3. Cause → Outcome — [Cause] caused [outcome]. ("No single owner caused the project to stall.")
+4. Actor → Action → Object → Reason — [Actor] should [action] [object] because [reason]. ("The team should cut onboarding from seven steps to three because most users drop off before setup is complete.")
+5. Decision → Rationale → Tradeoff — [Decision] works because [rationale], but [tradeoff]. ("A shorter onboarding flow should improve completion, but it may collect less user data upfront.")
+6. If → Then → Because — If [condition], then [action/outcome] because [reason]. ("If users abandon step 5, then the team should test a shorter flow because the current sequence likely asks for too much upfront.")
+
+### 4. Order of information
+Default: (1) main point, (2) evidence or cause, (3) implication or next step.
+Example: "Users are dropping out late in onboarding. 70% abandon at step 5 of 7, suggesting the setup asks for too much before users see value. The team should test a three-step version."
+
+### 5. Practical rule set
+1. Start with the real actor, not "there is" / "it is."
+2. Use one strong verb instead of a weak verb plus extra words.
+3. Prefer numbers over vague claims.
+4. Put the main point before the explanation.
+5. Use "because" for known causes.
+6. Use "suggesting" for likely causes.
+7. Cut adjectives unless they add specific meaning.
+8. Replace adverbs with data when possible.
+9. Keep one main idea per sentence.
+10. Keep caveats close to the claim they qualify.
+Do not invent data: numbers, dates, and evidence appear only when supplied or verified (this is the user-facing-style face of build-loop's no-false-data principle + the fact-checker, not a second check).
+
+### Best default formula
+[Specific actor] + [strong verb] + [specific outcome] + because + [specific cause].
+Example: "Users abandoned onboarding because the seven-step flow asked for too much before showing value."
+
+This section is JUDGMENT-enforced in the Review-G one-pass self-heal alongside outcome framing — `report_lint.py` does NOT grade "shorter words", sentence patterns, or "is this a causal sentence": a fuzzy check there would false-flag correct terse prose and over-block, against the deterministic-only-for-known-risks rule. The direct cause→effect guidance is the same instinct as rule 6's no-contrastive-pivot ban (state what happened and why, without negation or padding); the no-invented-data line is the user-facing-style face of rule 7 and of build-loop's standing "no false data, no unverified claims" principle, traced by the fact-checker in Review-D — not a second enforcement path. Apply these when rewriting the draft; do not add a lint for them.
+
 ## Good — the exemplar (Codex output, captured 2026-06-04)
 
 ```