@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/build-loop/fallbacks.md

@@ -14,7 +14,7 @@ Each section is self-contained. Keep prose tight: the goal is "capture the conce
 
 **Build-loop-owned static fallback.** When no browser/simulator/native-AX path is available, build-loop cannot compute every rendered style value, but it CAN grep the code for specific UI contract and design-rule violations. The checks below are the minimum-viable static-analysis subset.
 
-> **Precedence note**: IBR is explicit-only. Do not route web UI builds, Review-B validation, coverage-gap generation, or Iterate re-validation through `build-loop:ibr-bridge` unless the user specifically asks for IBR / Interface Built Right / `.ibr-test.json`. The default path is `design-contract-specialist` for direction, `ui-validator` for rendered checks, and this static matrix when rendered evidence is unavailable.
+> **Precedence note**: follow `../../references/ibr-ui-verification-policy.md`. Headless IBR is the primary verifier when Build Loop updates, compares, or audits a renderable UI design and IBR is installed. This file defines the fallback when IBR is absent or cannot reach the surface. Interactive viewers and persistent sessions remain explicit-only.
 
 ### Design principles (Calm Precision, condensed from global `CLAUDE.md`)
 
@@ -266,7 +266,7 @@ The `build-loop:debug-loop` skill is bundled with build-loop. Use this fallback
 2. **Isolate** — binary-search the diff / commits / inputs until you find the smallest change that flips pass ↔ fail.
 3. **Hypothesize** — one specific claim about cause. Write it as a statement, not a question.
 4. **Test** — make the smallest possible change that would confirm or refute the hypothesis. Run it. Observe.
-5. **Record** — append one line to `.build-loop/issues/YYYY-MM-DD-<slug>.md` with: symptom, root cause, fix, prevention.
+5. **Record** — after verification, use the native `build-loop-debugger store` command so the incident lands in `.claude/memory/`.
 
 Stop after 3 failed hypotheses and escalate to the user with what was tried.
 
@@ -274,7 +274,7 @@ Stop after 3 failed hypotheses and escalate to the user with what was tried.
 
 ## bug-memory — Prior-bug lookup
 
-The `build-loop:debugging-memory` skill is bundled with build-loop. Use this fallback only if the skill cannot provide structured recall. No cross-project training — just a file-grep of this project's prior builds.
+The `build-loop:debugging-memory` skill and debugger core are bundled with Build Loop. Use this fallback only if the native CLI or compiled core cannot load.
 
 ### Query procedure
 
@@ -287,7 +287,7 @@ TOKENS=$(echo "$SYMPTOM" | tr ' ' '\n' | grep -E '^[A-Z][a-zA-Z]+$|^[a-z_]+[A-Z]
 
 # Search local project history
 for T in $TOKENS; do
-  grep -R -l "$T" .build-loop/issues/ 2>/dev/null
+  grep -R -l "$T" .claude/memory/incidents/ 2>/dev/null
   grep -R -l "$T" .build-loop/feedback.md 2>/dev/null
   grep -R -l "$T" .bookmark/ 2>/dev/null
 done | sort -u
@@ -300,25 +300,15 @@ done | sort -u
 | `LOCAL_HIT_EXACT` | At least one file contains the full symptom string (case-insensitive substring match) | Read that file; adapt its recorded fix as the Iterate plan. Not direct-apply. |
 | `LOCAL_HIT_PARTIAL` | ≥2 tokens co-occur in the same file | Reference the file in the Iterate plan; investigate normally |
 | `LOCAL_WEAK` | 1 token match only | Note reference, investigate normally |
-| `LOCAL_NO_MATCH` | No files contain any tokens | Standard Iterate; write a new `.build-loop/issues/<slug>.md` after resolution |
+| `LOCAL_NO_MATCH` | No files contain any tokens | Standard Iterate; use the native debugger store after resolution |
 
 No confidence score (no classifier). No cross-project lookup. No automatic training signal back to the source — this is strictly read-only memory for one project.
 
 ### Storage (write side)
 
-After resolving a failure, append to `.build-loop/issues/YYYY-MM-DD-<slug>.md`:
+After resolving a failure, create the JSON payload documented in `skills/debugging-memory/references/store.md` and invoke the native store command. It writes to `.claude/memory/incidents/` and updates the indexes used by search.
 
-```
-# <one-line title>
-
-**Symptom**: <error string as it appeared>
-**Root cause**: <what was actually wrong>
-**Fix**: <diff summary or description>
-**Files**: <paths touched>
-**Tags**: <layer>, <component>, <pattern>
-```
-
-Future builds will grep this file. The bundled `build-loop:debugging-memory` skill promotes this to native build-loop recall; standalone Coding Debugger can mirror it into cross-project ranked memory when installed separately.
+Do not write resolved incident history to `.build-loop/issues/`; that directory remains an executable/open-work lane.
 
 ---
 
@@ -415,11 +405,16 @@ Use the **6-Part Stack** for any system prompt or agent prompt:
 5. **Output format** — exact structure: JSON schema, markdown template, or free text with labeled sections. Specify escape behavior for ambiguous inputs.
 6. **Acceptance criteria** — how success is judged. If deterministic, what makes it wrong. If LLM-judged, what the judge looks for.
 
-Calibrate to model tier:
+Calibrate to the target model's capability rung. **These lines are kept byte-equal to the `summary` strings in `references/model-taxonomy.json` (`prompting_profiles.by_tier`) by test `T-09` in `scripts/test_model_taxonomy.py`. Edit the taxonomy first, then mirror the change here — editing only one side fails the test.** Rungs are the taxonomy's ladder: T0 restricted-frontier · T1 ultra-frontier · T2 frontier · T3 balanced workhorse · T4 efficient near-frontier · T5 utility. Inside build-loop, resolve a target's rung with `python3 scripts/resolve_agent_model.py <agent>`; the lines below stand on their own when you are not.
+
+- **T0** — State the goal, the context, and the falsifier. Omit worked examples. Give every constraint its rationale. Trust the model with the edge cases.
+- **T1** — State the goal, the context, and the falsifier. Omit worked examples. Give every constraint its rationale. Trust the model with the edge cases.
+- **T2** — Lead with context rather than directives. Include at most one compact example, and only when the contract is novel. Delegate the edge cases, but name the falsifiers you already know.
+- **T3** — Write the full brief: worked contract examples, explicit caps with the arithmetic shown, and known edge cases enumerated (including schema-field warnings).
+- **T4** — Write the full explicit brief: worked examples and direct instructions.
+- **T5** — Write the full explicit brief: worked examples and direct instructions. Use this rung for bounded mechanical tasks only.
 
-- **Frontier (T1 — Opus 4.6, GPT-5)**: can handle longer instructions, implicit reasoning, self-correction. Prefer clarity over verbosity.
-- **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).
+T4 and T5 are weakly-evidenced placeholders encoding current behavior rather than a posture chosen on evidence; see each rung's `evidence_note` in the taxonomy.
 
 Review checklist — when auditing an existing prompt:
 

package/skills/build-loop/phases/ui-validation.md

@@ -21,7 +21,7 @@ When `uiTarget != null`, the UI gates wire in automatically:
 1. **Phase 1 (Assess)** — mockup pre-flight scan + required UI scoring criteria
 2. **Phase 2 (Plan)** — UI input/output contract section from `references/ui-io-contract.md`, then mockup-gallery hook for major UI work (new page or ≥40% redesign): draft B&W mockups via `mockup-gallery:mockup-session-new` before any UI is written. The exception to build-loop's "actions/functions only, no plugin UI" policy — mockup drafting is itself the action.
 3. **Phase 3 (Execute)** — verbatim subagent-prompt template injection on every UI dispatch, including the plan's UI input/output contract
-4. **Phase 4 sub-step B (Validate)** — build-loop-owned `ui-validator` first, then design-rule scanner on changed files, contract coverage, code graders, and visual evidence capture
+4. **Phase 4 sub-step B (Validate)** — IBR primary when installed for renderable UI design updates/comparisons/audits, with `ui-validator` in parallel; then design-rule scanner, contract coverage, and code graders
 5. **Phase 4 sub-step D (Fact-Check)** — Gate 5 design-rule scanner across full project; Gate 5a UI input/output contract scan; Gate 7 UX triage scanner (interactability, performance, data-accuracy, usability) writing queue entries to `.build-loop/ux-queue/`
 6. **Phase 5 (Iterate)** — drains the UX queue alongside Validate failures; parallel fan-out (≤4) for independent fixes; runs the build-loop UI re-validate hook before returning to Review-B
 
@@ -44,7 +44,7 @@ When `uiTarget != null`, build-loop owns the design route:
 
 1. Phase 2 loads `build-loop:ui-design`, then dispatches `design-contract-specialist` with `trigger_point: phase2-design-direction` for non-trivial UI work. It reads the UI input/output contract, `references/recent-design-structures.md`, `skills/ui-design/references/ui-guidance-sources.md`, product/workflow needs, project tokens, mockups, screenshots, and local design artifacts, then chooses a fit-for-purpose direction and writes `.build-loop/app-contract/ui.md`. Recent and existing design patterns are inputs, not mandates.
 2. Phase 3 implementers receive the UI contract plus `templates/ui-subagent-prompt.md`.
-3. Visual verification routes per `state.json.availablePlugins.ibr`:
+3. Visual verification follows `../../../references/ibr-ui-verification-policy.md` and routes per `state.json.availablePlugins.ibr`:
    - **IBR installed → IBR primary**: dispatch IBR `scan` (web) / `scan_macos` (macOS) via `build-loop:ibr-bridge`; `ui-validator` runs in parallel as the build-loop-owned check.
    - **IBR absent → native fallback**: Phase 4-B dispatches `ui-validator` first (web), or routes to `native-ax-driver` (macOS), or the iOS-simulator screenshot path (`uiTarget: "mobile"`). Either path satisfies the BL-1 visual-evidence gate.
 4. Phase 4-B always runs scanners and code graders after the visual verifier. The BL-1 gate (`scanners/require-visual-evidence.mjs`) is a separate exit-code check; it does not care which route ran, only that the evidence is visual/AX rather than symbol/string.

package/skills/build-loop/references/advisor-dispatch-ladder.md

@@ -45,7 +45,7 @@ The orchestrator (single writer) appends one row to `.build-loop/agent-ledger.js
 action: author | re-plan
 agent: advisor · tier: frontier · model: <resolved id (fable / gpt-5.x / …)>
 rung: 0|1|2|3 · status: pass|fail|partial · trigger: <synthesisDensity>5 | riskSurfaceChange | stakes>=medium | dispatch_tier:frontier>
-refs: {output: docs/plans/<slug>.md, input: <prior plan / failure evidence>}
+refs: {output: .build-loop/plans/<slug>.md, input: <prior plan / failure evidence>}
 note: <on re-plan: failure evidence + why a retry is justified>
 ```
 

package/skills/build-loop/references/apple-native-planning.md

@@ -302,7 +302,7 @@ For native iOS/macOS modernization passes scoped from a prior audit, run a three
 
 ### Native visual evidence
 
-Use built-in simulator screenshots and native AX evidence for visual regression after a redesign that changes layout. Those tools do not extract computed SwiftUI font/color/spacing values, so source-code extraction remains load-bearing for metric audits. Use grep + Read for typography, color, spacing, and token claims. IBR native scans are explicit-only auxiliary evidence when the user asks for IBR.
+When IBR can reach the running native surface, use its headless native scan or comparison automatically as the primary visual verifier for UI design updates, comparisons, and audits. Keep built-in simulator screenshots and native AX evidence as the fallback and corroborating evidence. Those tools do not extract computed SwiftUI font/color/spacing values, so source-code extraction remains load-bearing for metric audits. Use grep + Read for typography, color, spacing, and token claims. Interactive IBR viewers and persistent sessions remain explicit-only.
 
 ### Three-tier ROI ordering
 

package/skills/build-loop/references/autonomous-and-per-commit-modes.md

@@ -9,9 +9,9 @@ each; the full detail lives here and loads on demand.
 
 ## Autonomous Mode (Queue-Drain Loop)
 
-Autonomous mode generalizes Phase 5 Iterate into a self-replenishing worker that drains its own `ux-queue/` + `issues/` + `proposals/`, alignment-checks each item against the original intent, executes the aligned subset, and commits in batches until the queue is empty or the wall-clock budget elapses. Default since this mode shipped (`--autonomous=false` opts back to classic one-pass).
+Autonomous mode generalizes Phase 5 Iterate into a self-replenishing worker that drains executable `queue/` + `ux-queue/` + `issues/` + `followup/` lanes, alignment-checks each item against the original intent, executes the aligned subset, and commits in batches until the queue is empty or the wall-clock budget elapses. Proposals and backlog items remain non-executable.
 
-**End-of-run backlog/issues drain — SHIPPED DEFAULT 2026-06-04**: every run now auto-drains `.build-loop/issues/` then `.build-loop/backlog/` at end-of-thread without asking. Reversible per-repo via `.build-loop/config.json`:
+**End-of-run queue continuation:** every run may continue its executable lanes at end-of-thread. Backlog work joins only through `backlog.py promote` at a planning boundary. Planned work is pickup-eligible; initiatives require user approval and an isolated non-main worktree; decisions only surface for matching workstreams.
 
 ```json
 { "sessionPrefs": { "continueFromQueues": "never" } }
@@ -77,8 +77,8 @@ The orchestrator writes `state.execution.budget` at autonomous-mode start:
 | Mode | Per-build cap | Per-item cap |
 |---|---|---|
 | Classic (autonomous=false) | 5 | n/a |
-| Autonomous default | 25 | 3 same-verdict |
-| Autonomous long | 25 | 3 same-verdict |
+| Autonomous default | 25 | audit at 3 identical unresolved verdicts; quarantine at 5 |
+| Autonomous long | 25 | audit at 3 identical unresolved verdicts; quarantine at 5 |
 
 `maxIterateAttemptsAutonomous` is configurable in `.build-loop/config.json.autonomy.maxIterateAttemptsAutonomous`.
 
@@ -137,7 +137,13 @@ Passing both `--per-commit` and `--no-per-commit` is a user error — fail loud
 
 2. **Per-commit orchestrator dispatch.** For each commit in the plan (respecting `depends_on`), the skill body dispatches a fresh `Agent(subagent_type="build-loop:build-orchestrator", ...)` carrying ONLY that commit's packet plus a `PER_COMMIT_DISPATCH: { commit_id, run_id, prior_commit_hashes }` prompt prefix. Each dispatched orchestrator runs Phase 3 Execute + Phase 4 Review for ITS commit only, then commits and returns. The dispatched orchestrator's behavior on the prefix is documented in `agents/build-orchestrator.md` §0a.
 
-3. **Aggregate.** The skill body collects each orchestrator's return envelope and writes a final report combining all commits' results. On partial failure (commit N fails), do NOT dispatch downstream commits; retain `.build-loop/per-commit-plan.json` so a subsequent `/build-loop:run --resume` invocation can pick up where it stopped. **Parent-dispatch contract (GAP-1):** the dispatcher (this skill body) HAS the Agent tool, so it is the parent that owes the audit. For every returned envelope whose `auditor_status` is `not-run:parent-must-dispatch` or `cross-vendor-deferred`, the dispatcher MUST — before declaring that commit/run review-complete — dispatch `Agent(subagent_type="build-loop:independent-auditor")` on that commit's diff range, append the verdict to `.build-loop/judge-decisions.json`, and re-run `write_run_entry --scope build` so the review-completeness gate passes. A nested per-commit orchestrator cannot audit itself; the audit is the dispatcher's responsibility, not an optional step.
+3. **Aggregate.** The skill body collects each orchestrator's return envelope and writes a final report combining all commits' results. On partial failure (commit N fails), do NOT dispatch downstream commits; retain `.build-loop/per-commit-plan.json` so a subsequent `/build-loop:run --resume` invocation can pick up where it stopped. **Parent-dispatch contract (GAP-1 — now machine-checkable, not prose):** the dispatcher (this skill body) HAS the Agent tool, so it is the parent that owes the audit. A nested per-commit orchestrator that could not run the auditor writes an **owed-verification manifest** (`.build-loop/owed-verification.json`, via `scripts/owed_verification.py write`) at its Review Sub-step A and flips `state.json.review_incomplete = true`. The dispatcher MUST — before declaring the run review-complete — resolve every owed manifest:
+
+1. `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/owed_verification.py check --workdir "$PWD" --json`. Exit 1 (`status: incomplete`) means verifiers are still owed; exit 0 (`complete`/`absent`) means nothing outstanding.
+2. For each verifier in the manifest's `owed[]`, dispatch it using the manifest's `dispatch_commands[verifier]` (e.g. `Agent(subagent_type="build-loop:independent-auditor")` on that commit's diff range), append the verdict to `.build-loop/judge-decisions.json`, then `owed_verification.py clear --verifier <name> --workdir "$PWD"`.
+3. When the last owed verifier is cleared the manifest is removed and `review_incomplete` flips back to `false`. Re-run `write_run_entry --scope build` so the review-completeness gate passes.
+
+Also handle any returned envelope whose `auditor_status` is `not-run:parent-must-dispatch` or `cross-vendor-deferred` even if (for a partial/legacy path) no manifest was written — the audit is the dispatcher's responsibility, not an optional step. The manifest is what makes "the parent can't silently skip it" a mechanism rather than a memory. Helper + tests: `scripts/owed_verification.py` / `scripts/test_owed_verification.py`.
 
    **Parent owes Phase 6 Learn + retrospective (E3).** A stop-early dispatch that never reaches Phase 4 Review-G can't run Phase 6 Learn or the post-push retro — so the dispatching parent owes them at close, under the same parent-dispatch contract as GAP-1 (not optional, name the owner at dispatch). Full contract: `agents/build-orchestrator.md` §Phase 4 A (E3 block).
 

package/skills/build-loop/references/autonomy-dashboard.md

@@ -0,0 +1,115 @@
+# Build Loop Dashboard
+
+## Big idea
+
+The local dashboard shows the current Build Loop phase, major tasks, and agents
+that have actually been invoked. The same page retains the autonomy decision
+controls for production, reversibility, scope, and major user outcomes.
+
+## Start
+
+```bash
+python3 scripts/autonomy_dashboard.py --workdir "$PWD" --port 8765
+```
+
+The command starts a detached local server that survives the launching terminal
+or agent session. Open `http://127.0.0.1:8765`. Check or stop it with:
+
+```bash
+python3 scripts/autonomy_dashboard.py --workdir "$PWD" --status
+python3 scripts/autonomy_dashboard.py --workdir "$PWD" --stop
+```
+
+The dashboard is opt-in and token-free. Build Loop does not start it
+automatically, `--stop` removes the running surface whenever the user prefers,
+and the projection performs no LLM or provider calls.
+
+Use `--foreground` only when an external process manager owns the server
+lifecycle. The server refuses non-loopback binding and non-loopback Host/Origin
+headers.
+
+## Live run projection
+
+`GET /api/state` includes a `run` object produced by
+`scripts/dashboard_projection.py`. The browser refreshes that projection every
+two seconds while the page is visible; no server restart is required when the
+run advances.
+
+Each of the six standard phases includes its expected output. Free-form progress
+comments use the existing bounded working-state channel:
+
+```bash
+python3 scripts/working_state_writer.py --workdir "$PWD" \
+  --agent "<agent-id>" --run-id "<run-id>" --phase execute \
+  --status editing --note "Connecting the live task projection."
+```
+
+The note is capped at 800 characters, stored in
+`.build-loop/working-state/{current.json,log.jsonl}`, and filtered to the current
+run before display.
+
+The projection is read-only and rebuildable. It uses these canonical records:
+
+- `.build-loop/state.json` for the current run, phase, and structured task
+  collections;
+- `.build-loop/plan.md` to enrich matching bare task IDs and as a major-task
+  fallback when structured execution tasks are absent;
+- `.build-loop/agent-ledger.jsonl` for recorded agent invocations in the current
+  run; and
+- `.build-loop/working-state/{current.json,log.jsonl}` for bounded free-form run
+  notes and comments; and
+- `runs[-1].judge_decisions` in `.build-loop/state.json` for the latest
+  completed run when no agent-ledger rows are available.
+
+Missing or malformed optional records produce an honest empty state or warning.
+The dashboard does not infer invocation from an available-agent roster and does
+not write phase, task, agent, or judge state.
+
+## Persistence contract
+
+- Every selection or note edit appends a `response_saved` event to
+  `.build-loop/autonomy-dashboard/responses.jsonl`.
+- Reload and process restart reconstruct the latest response per gap from that
+  append-only log.
+- Each collapsed card names the selected policy and shows saved, queued, or
+  applied state;
+  JavaScript applies selected styling directly so feedback does not depend on
+  CSS `:has()` support.
+- **Queue this decision** appends `response_queued` and creates
+  `.build-loop/followup/dashboard-<gap>-<timestamp>.md`.
+- Queuing a revision moves older executable files for the same gap to
+  `.build-loop/autonomy-dashboard/superseded/`; one gap has one live instruction.
+- A validated completion appends `response_applied`, moves its instruction out
+  of `.build-loop/followup/` into `.build-loop/autonomy-dashboard/applied/`, and
+  shows the completion summary and evidence in the dashboard.
+- Agents may read saved responses for context. They act only on queued follow-up
+  items or a direct user instruction.
+
+## Agent consumption
+
+1. Run `python3 scripts/autonomy_dashboard.py --workdir "$PWD" --print-state`.
+2. Treat `responses[*].choice_id` and `note` as owner-authored direction.
+3. Treat `queued_path` as the execution instruction and re-check its premise
+   against the live repo before changing code.
+4. Route the follow-up through normal autonomy, validation, and production gates.
+5. After validation succeeds, close the queue item and publish evidence:
+
+   ```bash
+   python3 scripts/autonomy_dashboard.py --workdir "$PWD" \
+     --complete "<dashboard_gap_id>" \
+     --summary "<what changed>" \
+     --evidence "commit:<sha>; tests:<result>; audit:<verdict>"
+   ```
+
+`Queued` means a current or future Build Loop run can execute the instruction;
+the dashboard does not run a hidden worker. `Applied` means Build Loop validated
+the result and removed the item from the executable queue.
+
+## Policy ownership
+
+The dashboard explains and records choices. `scripts/autonomy_supervisor.py`
+owns execution policy: missing-information routing, task-shape learning, bounded
+queue manifests, discovered-issue classification, convergence enforcement, and
+live provider/host/cost backpressure. Queue sizing and fan-out are adaptive;
+150 is an absolute ceiling, not a target. The third repeated unresolved verdict
+requires independent audit and the fifth quarantines the item.

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

@@ -24,6 +24,7 @@ Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` a
 | Intent capability pack | Phases 1-4 | Read `references/intent-capability-pack.md`; write `.build-loop/intent.md`; pass the intent packet to every subagent |
 | 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 |
+| `build-loop:data-plane-worktrees` | Phase 1 Assess through terminal closeout when a worktree touches mutable non-Git state | Inventory surfaces inline, keep writable paths under `.build-loop/data/<run-id>/`, namespace external resources by run id, and serialize any unavoidable shared writer |
 
 ### Spec/Plan author router (intent-driven, ordered)
 
@@ -100,13 +101,13 @@ The order is the contract: row 1 short-circuits before any author runs; row 2 is
 | Recent design structures | `design-contract-specialist` reads `references/recent-design-structures.md` and selects by product/workflow/data fit | explicit design-tool artifacts passed as evidence | `fallbacks.md#web-ui` |
 | Screenshot / visual evidence | `showcase:capture`, `showcase:record` | `screenshot` MCP tool | `fallbacks.md#screenshot` |
 | Web content fetching (low LLM) | `scraper-app:web-scraper` SDK | — | `fallbacks.md#web-fetch` (flags LLM cost in report) |
-| Deep debugging | `build-loop:debug-loop` + `build-loop:debugging-memory` native search/store | standalone Coding Debugger only when explicitly installed for cross-project memory | `fallbacks.md#debug` |
+| Deep debugging | `build-loop:debug-loop` + bundled `build-loop:debugging-memory` native search/store | — | `fallbacks.md#debug` |
 | Bug-pattern memory | `build-loop:debugging-memory` | — | `fallbacks.md#bug-memory` (greps `.build-loop/issues/` + `.bookmark/`) |
 | Agent authoring | `agent-builder:agent-builder-anthropic` | `plugin-dev:agent-development` (if plugin work) | `fallbacks.md#agent-authoring` |
 | DeepAgents / local-LLM agent work | `build-loop:building-with-deepagents` (SubAgent API, middleware stack, per-agent tool scoping, anti-patterns) | — | Read installed `deepagents` source: `python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))'` then `graph.py` + `middleware/subagents.py` |
 | Structured reports / handoffs | `pyramid-principle:pyramid-short-form` (Review-F reports), `pyramid-long-form` (design docs) | — | `fallbacks.md#structured-writing` (SCQA + MECE skeleton) |
 | Hosted-IDE migration (Replit / Lovable / Bolt / v0) | `replit-migrate:migration-scan`, `migrate-web`, `migrate-ios`; MCP tools `migrate_scan`, `migrate_plan_web`, `migrate_plan_native`, `migrate_map_apis`, `migrate_map_models`, `migrate_check_progress` | — | `fallbacks.md#migration` (manual inventory + stack-translation) |
-| Prompt authoring / review / audit (system prompts, agent prompts, eval judges) | `prompt-builder:prompt-builder` skill; slash commands `/prompt-builder:optimize`, `/score`, `/compare`, `/save`, `/list`. Calibrates to model tier (T1/T2/T3) and deployment (interactive, backend, rag_pipeline, agent, plugin, eval_judge, personal_mobile). Returns 6-Part-Stack prompt + 5-dim score + diagnosis + `[ASSUMED:]` tags + `TEMPERATURE_HINT` | `prompt-builder` (personal skill, same name, loaded via Skill tool) | `fallbacks.md#prompt` |
+| Prompt authoring / review / audit (system prompts, agent prompts, eval judges) | `prompt-builder:prompt-builder` skill; slash commands `/prompt-builder:optimize`, `/score`, `/compare`, `/save`, `/list`. Calibrates to prompt-builder's own 3-level scheme (frontier/mid/small — its labels, not taxonomy rungs) and deployment (interactive, backend, rag_pipeline, agent, plugin, eval_judge, personal_mobile). Returns 6-Part-Stack prompt + 5-dim score + diagnosis + `[ASSUMED:]` tags + `TEMPERATURE_HINT` | `prompt-builder` (personal skill, same name, loaded via Skill tool) | `fallbacks.md#prompt` |
 | iOS / watchOS / macOS dev + deploy | `apple-dev` personal skill (via `Skill("apple-dev")`) | `replit-migrate:migrate-ios` (when migrating *to* native) | `fallbacks.md#apple-dev` |
 | Web deploy verification (Vercel) | Vercel MCP (`mcp.vercel.com` remote OAuth, only if user adds it to `.mcp.json`) | Vercel CLI via `scripts/verify_deploy.py` | `fallbacks.md#web-deploy-verify` |
 | Strategic frame / PRD grounding (Assess + Review) | `build-loop:prd-bridge` — reads `docs/prd-*.md` frontmatter (`core_principles`, `load_when`) + Navigation Map + Section Index in Phase 1; verifies diff doesn't violate principles in Phase 5 Fact-Check; recommends `prd-builder` skill if no PRD exists. Falls back to grep on principle keywords if frontmatter parser unavailable. | `prd-builder` skill direct invocation | Phase 1 captures north-star + intent fresh into `intent.md` (existing fallback) |
@@ -138,6 +139,27 @@ Tie-breaker: if signals are mixed (an Apple project with both `ios/` and a macOS
 
 Some capabilities should fire proactively based on goal phrasing or files touched. Phase 1 ASSESS sets these flags in `.build-loop/state.json.triggers`, and Phase 4 EXECUTE consults them before dispatching each subagent.
 
+**data-plane-worktrees** (mutable non-Git state isolation)
+
+Fires when a Build Loop worktree can read or write state that Git does not
+isolate.
+
+Trigger if any of:
+
+- Goal mentions SQLite, PostgreSQL/Postgres, database/schema migration,
+  generated/search/vector index, Docker/Compose volume or project, mutable file
+  store, cache with canonical writes, bucket, queue, or external namespace.
+- Changed code opens `*.sqlite`, `*.sqlite3`, or `*.db`; connects to PostgreSQL;
+  runs migrations; builds an index; or provisions a persistent service.
+- Repo signals include migration directories, Compose volume definitions,
+  file-backed stores, or generated indexes shared across worktrees.
+
+Action: set `state.json.triggers.dataPlaneWorktree: true`, load
+`Skill("build-loop:data-plane-worktrees")` before Phase 2, inventory every data
+surface in the run manifest, and require `validate` before the first write plus
+`terminal` before closeout. A baseline empty manifest is not evidence that no
+data surface exists; Assess must make that determination from the goal and repo.
+
 **pyramid-principle** (structured writing)
 
 Fires whenever the build produces user-visible prose or professional writing. Even small text should follow pyramid structure, and the logical ordering principle applies to design flow too.

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

@@ -119,12 +119,28 @@ adapter in the boundary manifest.
 
 ## Discovery integration (current)
 
-Build-loop uses `scripts/rally_point/discovery_bridge.py` as the shared
-channel resolver. It prefers the standalone `agent-rally-point` discovery
-surface when installed and falls back to build-loop's embedded resolver only
-when needed. Both native discovery and the embedded fallback default to
-`~/.agent-rally-point/apps/...`; the fallback uses the local worktree-aware
-`<slug>` when no native `<repo-id>` is available.
+Build Loop uses `scripts/rally_point/discovery_bridge.py` as the single backend
+resolver. The contract has two writable backends:
+
+1. `backend=rally`, `transport=rally-cli`: an explicit binary override or the
+   standalone `rally` on `PATH` wins. Build Loop requires valid `version`,
+   `whoami`, and read-only `status read` envelopes before treating the room as
+   operational. All event writes go through `rally say`; Build Loop must never
+   create a private `changes.jsonl` inside `.rally`.
+2. `backend=build-loop-local`, `transport=fact-v1`: when Rally is absent or its
+   room is unhealthy, Build Loop writes its shared fallback spool. Only Build
+   Loop readers consume this backend; `codex`, `claude_code`, and `cursor` are
+   host identities within Build Loop, not independent fallback participants.
+
+The fetched Build Loop binary is a compatibility fallback after standalone
+Rally, not a version authority that may shadow it. When Rally becomes
+operational, `maybe_auto_migrate()` replays fact-v1 rows idempotently and stores
+a digest watermark only after Rally returns a complete migration receipt.
+
+`.build-loop/agent-ledger.jsonl` remains the local authority for judgment gates.
+Each successful canonical append also projects the exact row through the same
+backend adapter. Projection failure is reported but never changes the local
+append result.
 
 The discovery layer (see
 [`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md))
@@ -146,6 +162,8 @@ Current build-loop callers route through the bridge:
    use the resolved channel for session-start and pre-edit hook behavior.
 4. `scripts/coordination_watch.py` remains a compatibility wrapper; watcher
    behavior lives under `scripts/agent_rally_watcher/`.
+5. `scripts/agent_ledger.py` preserves the local gate input and projects each
+   canonical row through `rally_point.post.post(...)`.
 
 ## Cross-references
 

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

@@ -33,6 +33,11 @@ certainty, "not computed — why").
   - Backtest: data + window = <...> · in/out-of-sample split = <...>
   - Ablation: component removed = <...> · baseline = <...>
 - **Held constant (confounds managed):** <model, environment, inputs, seed, …>
+- **Model/thinking identity** (required for model or agent comparisons):
+  - `<arm>`: model `<provider/model/version>` · normalized level `<none|minimal|low|medium|high|xhigh|max|ultra|unknown>` · provider value `<exact label|null>` · mode `<single_agent|multi_agent|adaptive|unknown>`
+  - Provenance: `<source_document|experiment_config|runtime_log|unknown>` · evidence `<URL + table/footnote OR exact command/config/log>`
+  - Evidence kind: `<published_document|local_test>` · observed at `<ISO-8601>`
+  - Mixed/unknown effort confound: `<none | explain why ranking is directional>`
 - **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>
 
@@ -51,9 +56,9 @@ certainty, "not computed — why").
 | <cost> | effort/latency/$ | lower better (only counts when quality ties or wins) | <calls · s · $> |
 
 **Data:**
-| <arm / run / config> | <m1> | <m2> | <cost> |
-|---|---|---|---|
-| <...> | | | |
+| <arm / run> | Model ID | Thinking level / mode | Thinking provenance | <m1> | <m2> | <cost> |
+|---|---|---|---|---|---|---|
+| <...> | <provider/model/version> | <high / single_agent> | <runtime_log: path#line> | | | |
 
 **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>
@@ -99,3 +104,10 @@ certainty, "not computed — why").
    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.
+7. **Thinking level is part of the treatment.** Never collapse scores by model name when
+   effort or mode differs. Preserve the source's exact label and a normalized level. For
+   published rows, cite the page/table/footnote; for our tests, cite the effective runtime
+   config or log. If the value is not reported, write `unknown` and name the confound.
+   Model bake-offs carry these fields in each arm of the existing `abc-comparison/v2`
+   observation artifact. Preserve that raw artifact: Benchmark Lab retention is a pending
+   Lab-owned extension, and current ingest acceptance does not prove the fields survived.

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

@@ -54,7 +54,7 @@ State the posture you're operating under when it materially shapes the turn ("op
 ## Parallel-work doctrine (decentralized execution)
 
 - Decompose into **MECE** chunks (disjoint file ownership) so workers don't collide; the orchestrator owns git (single-writer) and workers never commit.
-- Fan-out width follows `scripts/parallelism.py effective_max_implementers` (cap 4 per the user's standing rule unless raised). Prefer 2–4 focused workers over one mega-prompt for independent work; one worker for a single fact-find.
+- Fan-out width follows the autonomy supervisor's adaptive admission envelope. Start at no more than four, then recover one worker after stable telemetry windows; reduce or pause on provider, host, cost, thermal, latency, or failure pressure. The absolute ceiling is 150, while independent MECE work and all lower resource caps remain binding. Use one worker for a single fact-find.
 - **Risky-but-reversible parallel work → isolated worktrees, merge back.** Two writers on one worktree race on HEAD/index — isolate, then collapse to main at close (Phase D / `collapse_run.py`).
 - Workers return condensed structured results; the orchestrator (Thinking tier) synthesizes and verifies — cheaper-tier output is never trusted unchecked.
 

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

@@ -6,7 +6,7 @@
 
 ## Memory — Global and Project-Scoped
 
-Build-loop maintains one canonical long-term memory store at `~/dev/git-folder/build-loop-memory/`. Every build reads canonical indexes/folders; writes go to exactly one lane based on scope.
+Build-loop maintains one canonical long-term memory store at the memory store root (resolved by `scripts/_paths.py:memory_store_root()`). Every build reads canonical indexes/folders; writes go to exactly one lane based on scope.
 
 ### Recall-optimized memory discipline
 
@@ -50,7 +50,7 @@ Three work/knowledge artifact types, each with a clear WRITE → READ → TRACK
 | Artifact | Write (where) | Read / Track | Lifetime |
 |---|---|---|---|
 | **issues** | `<repo>/.build-loop/issues/<id>.md` — current-run bugs | Phase 5 Iterate drains them; repo-local so inherently scoped | short-lived (resolve → delete) |
-| **backlog** | durable: `build-loop-memory/projects/<slug>/backlog.md` (slug folder = repo scope); active: `<repo>/.build-loop/backlog/<id>.md` | read before planning self-work; Phase 5 drains active items | long-lived |
+| **backlog** | canonical: `<repo>/.build-loop/backlog/items/<ID>.md`; mirror: `build-loop-memory/projects/<slug>/backlog/<ID>.md` | classed deferred work; planned items require promotion, initiatives require approval/isolation, decisions surface by workstream | long-lived |
 | **backlog-archive** | `build-loop-memory/projects/<slug>/backlog-archive.md` | closed/moved/superseded items land here **with rationale + ref** — never deleted silently | durable |
 | **lessons** | `projects/<slug>/lessons/` (project) OR top-level `lessons/` (cross-project, stored `_unscoped`) — via `memory_writer.py` | `context_bootstrap` recall scopes to `(slug OR _unscoped)` — never other projects | durable |
 
@@ -250,6 +250,17 @@ Run once after this version of build-loop is installed; the migration completes
 - `memory_index.py append` — `fcntl.flock(LOCK_EX)` on `INDEX.jsonl.lock`; multi-writer safe across hosts.
 - `memory_update_ledger.py append` — `fcntl.flock(LOCK_EX)` on `updates.jsonl.lock`; append-only and multi-writer safe.
 
+### Peer-held store — queue, never silent-skip (`promotion_queue.py`)
+
+When the canonical store is busy / peer-held, a durable write MUST enqueue, not skip. Observed 2026-07-11: three retrospectives skipped durable promotion because a peer held the store (agents pointed `--memory-root` at a scratch path) — silent loss. `scripts/promotion_queue.py` is the queue-and-report primitive.
+
+- **Busy signal** (`store_busy`): the env `BUILD_LOOP_MEMORY_BUSY` OR a `<memory_root>/.peer-hold` marker.
+- **Producer** — raise the signal around a long store batch so peers queue instead of racing:
+  - `with promotion_queue.peer_hold(memory_root): ...` (context manager), or the `hold` / `release` CLI (`python3 scripts/promotion_queue.py --memory-root <root> hold`).
+  - `promotion_queue.drain` already wraps its multi-write apply phase in `peer_hold` (fires on every post-push closeout), and `append_milestone.py`'s fcntl lock-timeout is the organic milestone-lane producer.
+- **Queue** lives in the CONSUMER repo (`.build-loop/pending-promotions/queue.jsonl`), never in build-loop-memory, so a held store cannot block enqueue.
+- **Drain** replays queued milestone / lesson / retro-durable records via the existing writers at the next closeout (`python3 -m closeout --source post-push`) or `promotion_queue.py drain`. A record enqueued mid-drain is carried forward (locked re-read), never dropped.
+
 ## Append-only milestones (anti-rewrite-drift)
 
 ### The problem this solves
@@ -284,7 +295,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/append_milestone.py \
   --json
 ```
 
-`--commit` and `--project` override the defaults (git HEAD and slug derived from `--workdir`). `--memory-root` overrides the default `~/dev/git-folder/build-loop-memory`.
+`--commit` and `--project` override the defaults (git HEAD and slug derived from `--workdir`). `--memory-root` overrides the resolved memory store root (see `scripts/_paths.py:memory_store_root()` for the resolution order — env override, else an existing legacy checkout, else the neutral per-user default).
 
 Output: `{"appended": true, "path": "...", "line": "..."}` on success; `{"appended": false, "reason": "..."}` on fail-soft (non-git workdir, unwritable root). Exit 0 in both cases.
 

package/skills/build-loop/references/modular-systems-pack.md

@@ -31,6 +31,14 @@ When taking an exception, record:
 MODULARITY EXCEPTION: <why simpler/integrated is better for this use case>
 ```
 
+## Module Shape Is a Cost Lever, Not an Accuracy Gate
+
+Module-shape guidance — **narrow public interface + small, well-named internal files + a testable boundary per capability** — is a **cost** lever, not a correctness gate. Apply it proportionally; **never make it build-blocking.**
+
+A controlled minimal-pair study (matched repos differing only in cleanliness) measured the payoff of cleaner, better-shaped code as roughly **−34% agent file-revisitation/thrash and −7–8% tokens**, with **~0 change in task pass-rate** (91.3% clean vs 92.1% messy). So better module shape makes an agent navigate a codebase *cheaper*, not *more correct*. The "deep module" tension is also illusory: deep constrains *interface width* (fewer symbols the model must hold in context) while "small files" constrains *token load per read* — orthogonal, and the best-supported synthesis is a deep module implemented across small internal files, which modern sub-agent tooling (external refs + exploration summaries) already delivers without fat single files.
+
+Because the win is cost and the accuracy delta is unproven, treat this as guidance the Critic can *surface*, not a gate that can *block*. Do not mandate refactors for module depth; flag avoidable thrash, but ship on correctness. Source: `build-loop-memory/research/2026-07-06-ai-coding-fundamentals-and-harness-claims.md` (Claims 1 & 2).
+
 ## MECE File And Agent Partition
 
 Phase 2 Plan must partition work so every changed file has exactly one owner and every required responsibility has an owner.

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

@@ -47,6 +47,24 @@ The report describes what the change DOES FOR THE USER, not the feature or mecha
 
 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.
 
+### Release notes lead with one useful claim
+
+Each release-note item starts with a direct statement: `[Actor] [strong verb] [specific outcome].` The next sentence explains why the outcome matters. Lists, implementation details, and examples then support the claim.
+
+- Name the actor. Use `Rally`, `Claude Code`, or `Codex` when that system owns the action.
+- State the result before the mechanism. Tell the reader what now works, what stops failing, or what becomes easier.
+- Treat a list as evidence, not insight. Do not lead with a comma-separated inventory of commands, lifecycle events, files, or checks.
+- Keep examples after the point. Details such as lead changes, claim closure, expired-claim takeover, release, and resolution clarify the rule after the reader knows what the rule achieves.
+- Check each item before publishing: actor + verb + outcome; reason next; supporting detail last.
+
+**Weak — the inventory substitutes for the point:**
+
+> Lead-seat changes, claim closure, takeover, release, and resolution now enforce authority at the write boundary.
+
+**Strong — the statement explains the outcome first:**
+
+> Rally enforces ownership at the write boundary so one agent cannot close or transfer another agent's work. This protection covers lead changes, claim closure, expired-claim takeover, release, and resolution.
+
 ### Good — outcome-framed (the user-approved target style)
 
 ```
@@ -77,6 +95,27 @@ 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.
 
+## Governing rule: direct language. Clear verb, clear outcome.
+
+Every sentence names who did what, and what resulted. If a reader cannot extract the verb and
+the outcome in one pass, rewrite it.
+
+These are now ENFORCED by `scripts/report_lint.py`, not merely taught (the doctrine below existed
+and was routinely ignored, which is why it is linted now):
+
+| Rule | Fires on | Fix |
+|---|---|---|
+| `weak-verb` | nominalizations that hide the action: `was responsible for`, `performed an analysis of`, `made a decision`, `in order to` | use the strong verb: `caused`, `analyzed`, `decided`, `to` |
+| `filler-opener` | `Now,` `Basically,` `It's worth noting` `Let me` `I'll now` | delete it and start with the action |
+| `hedge` | `I think`, `perhaps`, `somewhat`, `arguably` | state it, or mark confidence (✅ / ⚠️ / ❓). A line already carrying a status marker is calibrated and exempt. |
+
+Calibrated uncertainty is required and is never a "hedge" finding: `❓ uncertain` is honest,
+`I think` is padding.
+
+**Em dashes (guidance, not linted):** prefer periods, colons, and commas. An occasional em dash
+is fine; leaning on them reads as rushed. This is a taste call, so it stays guidance — a lint that
+fired on every dash would be noise you learn to ignore.
+
 ## 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.
@@ -220,3 +259,50 @@ The lint targets ONLY the final user-facing report markdown + phase status lines
 - Findings are WARN (advisory): the orchestrator self-heals by revising the draft once, then emits it
 - Never hard-blocks a run — worst case is one revision pass
 - The structural lint (`scripts/build_report_lint.py`) keeps running in parallel; it is orthogonal (parallel_batch / merge_plan / evidence triplet shape)
+
+## Evidence class on every claim (added 2026-07-25)
+
+A claim about **why** or **whether** something works must say how it was checked.
+Tag it, or name the observation on the same line.
+
+| Class | Means | Example |
+|---|---|---|
+| `[measured]` | You measured the thing itself | `select max(created_at) from entities` returned a timestamp |
+| `[correlated]` | You measured something related; state the gap | its metric stopped appearing, so the process *may* be stopped |
+| `[reasoned]` | Inferred from code, absence, or an aggregate | grep found no callers |
+
+**The gate: a delete, deploy, or restart may only be justified by `[measured]`.**
+`[correlated]` and `[reasoned]` are fine in a report; they are not sufficient to
+act irreversibly.
+
+`scripts/report_lint.py` enforces the labelling half at Phase 4G
+(`mechanism-claim-unobserved`, WARN). The action gate is a human/orchestrator
+discipline: check the class before acting, not after.
+
+### Why this exists
+
+On 2026-07-25 six claims were wrong the same way. Each measured something true
+one step from what it asserted, then reported the inference at the confidence of
+the measurement:
+
+| Claimed | Actually measured |
+|---|---|
+| "the worker died" | its metric stopped appearing (it was Online, wedged on 5 stuck jobs) |
+| "source maps never uploaded" | the auth token was empty |
+| "persistence works" | ONE article served from store (5.2% of 11,581 rows do) |
+| "Summary V2 is live" | the code was committed (6 of 11,603 rows carry it) |
+| "13 routes safe to delete" | a grep returned nothing (3 had live callers) |
+| "the KG kept growing" | row counts since April (13 days of zero were inside) |
+
+Two of those reached the user as status. One would have deleted a route that a
+passing 149-line test imports. The restart recommendation was correct by
+accident: it freed the slots, but without a per-job deadline the same wedge
+recurs on the next slow host.
+
+**The tell is grammatical.** "Died", "never uploaded", "works", "safe to delete"
+are mechanisms. "Stopped appearing", "returns zero rows", "is empty" are
+observations. A mechanism verb with no matching observation is the flag.
+
+Agreement between reviewers does not substitute. Where two agents disagreed the
+conflict surfaced and was settled; where several shared the same proxy, nothing
+caught it.