@tyroneross/build-loop 0.30.3 → 0.35.0

package/plugin-artifacts/codex/references/self-review.md

@@ -0,0 +1,234 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Self-Review — Periodic Autonomous Self-Improvement
+
+Single source of truth for the build-loop self-review subsystem: purpose, light/deep model, config schema, launchd schedule, graceful degradation, and the headless apply prompt.
+
+---
+
+## Purpose
+
+Self-review mines recent build-loop runs for recurring issues and efficiency signals, produces a human-readable digest, and (in deep mode) automatically applies safe improvements via the normal build-loop pipeline. It closes the loop between observations captured during builds and durable fixes that land in the repo — without requiring the user to manually schedule or trigger a review.
+
+Two cadences balance cost against coverage:
+
+| Mode | Default cadence | Scope | Auto-apply |
+|---|---|---|---|
+| **light** | Daily (09:00) | Issues in the last 7 days; proposal cap 10 | No — digest + queue only |
+| **deep** | Weekly (Sunday 03:00) | Issues in the last 30 days; uncapped | Yes — SAFE proposals auto-routed through build-loop |
+
+---
+
+## Config schema
+
+Add a `selfReview` block to `.build-loop/config.json` (all fields optional; defaults shown):
+
+```json
+{
+  "selfReview": {
+    "enabled": true,
+    "autonomy": "apply_push",
+    "light": "daily",
+    "deep": "weekly"
+  }
+}
+```
+
+| Field | Values | Meaning |
+|---|---|---|
+| `enabled` | `true` / `false` | `false` disables the launchd jobs and is a no-op for the installer |
+| `autonomy` | `apply_push` \| `apply_local` \| `propose` | `apply_push` — apply SAFE items and push main; `apply_local` — apply but do not push; `propose` — queue only, no auto-apply |
+| `light` | `daily` \| `weekly` \| `disabled` | Cadence for the light job |
+| `deep` | `daily` \| `weekly` \| `disabled` | Cadence for the deep job |
+
+Cadence values map to launchd `StartCalendarInterval`. `daily` → every day at the job's configured hour. `weekly` → once per week on the configured weekday. `disabled` skips installing that job.
+
+---
+
+## How it works
+
+### Data-gathering layer (scripts/self_review/ package — frozen CLI)
+
+`python3 scripts/self_review/__main__.py --mode {light|deep} [--workdir <repo>] [--days N] [--dry-run] --json`
+
+Always exits 0. Writes:
+- `.build-loop/self-review/<UTCdate>-<mode>.md` — human digest
+- `.build-loop/proposals/self-review-*.md` — one file per candidate improvement, each with `classify_hint: SAFE|RISKY|DECISION` frontmatter
+
+Returns JSON to stdout:
+```json
+{
+  "mode": "light|deep",
+  "window_days": 7,
+  "mined": {"corrections": [], "rituals": [], "sequences": []},
+  "efficiency_findings": [],
+  "self_simplification": [],
+  "digest_path": ".build-loop/self-review/2026-05-29-deep.md",
+  "queued": [".build-loop/proposals/self-review-foo.md"],
+  "errors": [],
+  "dry_run": false
+}
+```
+
+**`self_simplification[]`** (deep mode, self-recursive only): a list of proactive simplification findings for build-loop's own code. Each entry has the shape:
+
+```json
+{
+  "target": "self",
+  "file": "<relative path>",
+  "finding": "<one-line description>",
+  "classify_hint": "SAFE|RISKY|DECISION",
+  "proposed_action": "<what to do>"
+}
+```
+
+`target: self` marks a proposal as targeting build-loop's own code (plugin repo or `build-loop-memory`). These proposals are subject to the SELF-MODIFICATION SAFETY GATE (see §"Self-modification of the restricted repo" below) — they are never processed by the standard reactive-fix path.
+
+Deep mode digests include an `## Apply plan` section that separates SAFE-to-auto-apply items from RISKY-to-surface items. When `self_simplification[]` is non-empty, the digest also includes a `## Self-simplification proposals` section listing each `target: self` finding.
+
+### Scheduling layer (launchd)
+
+`python3 scripts/install_self_review.py install` writes two plists to `~/Library/LaunchAgents/`:
+
+- `com.build-loop.selfreview-light.plist` — daily at 09:00, invokes `scripts/self_review_run.sh light`
+- `com.build-loop.selfreview-deep.plist` — weekly Sunday at 03:00, invokes `scripts/self_review_run.sh deep`
+
+`install` and `uninstall` also unload + remove any jobs still installed under the pre-rename legacy labels (developer-prefixed `*.buildloop.selfreview-*`), so an existing machine transitions to the neutral labels on the next run.
+
+Both jobs write output to `.build-loop/self-review/launchd-{light,deep}.log`.
+
+### Wrapper layer (scripts/self_review_run.sh)
+
+Invoked by launchd (or manually). Runs the gatherer, saves the JSON snapshot to `.build-loop/self-review/last-<mode>.json`, appends a timestamped line to `.build-loop/self-review/run.log`, and (for deep mode with `autonomy` in `{apply_push, apply_local}`) invokes the headless apply prompt via `claude -p`.
+
+---
+
+## Install / uninstall / status
+
+```bash
+# Install both launchd jobs
+python3 scripts/install_self_review.py install
+
+# Remove launchd jobs and plists
+python3 scripts/install_self_review.py uninstall
+
+# Check loaded/not-loaded
+python3 scripts/install_self_review.py status
+
+# JSON output for any subcommand
+python3 scripts/install_self_review.py status --json
+```
+
+Or via the slash command: `/build-loop:self-review --install` / `--uninstall` / `--status`.
+
+---
+
+## Graceful degradation
+
+If the `claude` CLI is not installed or not on PATH when the deep wrapper fires, the wrapper logs the skip reason and exits 0. The digest and queued proposals are still produced — the user can process them manually via `/build-loop:run` or `/build-loop:self-review deep`.
+
+The queue accumulates across skipped deep runs. On the next successful headless invocation, all queued SAFE proposals are processed.
+
+---
+
+---
+
+## Self-modification of the restricted repo
+
+The self-review/self-heal loop is authorized to write to the restricted repo — build-loop's own plugin repo and the `build-loop-memory` durable repo (lessons and skills). This is normally a guarded action because it edits the running runtime.
+
+**The SELF-MODIFICATION SAFETY GATE is MANDATORY and non-negotiable for ANY change to build-loop's own code.** It is the load-bearing safety for this authorization.
+
+### Gate protocol (every self-modification commit must pass all steps)
+
+**Step 1 — Bundle first (reversibility):**
+```bash
+git bundle create .build-loop/bundles/pre-selfmod-$(date +%Y%m%dT%H%M%S).bundle --all
+```
+Always bundle before any self-modification. This is the rollback point.
+
+**Step 2 — Self-recursive / per-commit mode:**
+Self-modifications use the existing per-commit mode machinery (one commit at a time, reviewed before the next). `selfRecursive.enabled` is `true` when the working directory IS build-loop's own repo. Do not batch multiple self-modification commits without a gate pass between each.
+
+**Step 3 — Verify gate (MANDATORY before commit):**
+```bash
+python3 scripts/self_mod_verify.py \
+  --workdir "$PWD" \
+  --scope auto \
+  --changed-files <space-separated file list> \
+  --auto-revert \
+  --json
+```
+`--scope auto` runs mapped tests for small changes and broader tests for multi-file/core changes (practical default). Use `--scope full` for the slow exhaustive option (900s, parallel when pytest-xdist is present).
+
+`verdict: pass` → the self-modification may commit.
+`verdict: fail` → the gate AUTO-REVERTS the change and writes the finding to `.build-loop/proposals/failed-gate/`. The change is NEVER committed. Do not retry a failed gate verdict without diagnosing the root cause.
+
+**Self-modifications execute — they do not stop the loop.** A self-modification that is part of the accepted plan (including edits to the gate, tests, or the self-improvement loop) executes behind the test-suite gate: `self_mod_verify.py --scope auto --auto-revert` must return `verdict: pass` (tests are the oracle; a failed gate auto-reverts the change). Build-loop never halts a planned self-modification for human approval. Oversight is post-hoc, not a gate: (a) self-modifying runs trigger an ADDITIONAL adversarial review (independent-auditor at build scope; the periodic deep self-review re-audits recent self-modifications) — non-blocking; (b) the end-of-run readback reports every self-modification and the additional-review findings so the human sees results at the end. The loop stays on task and reports once, at the end.
+
+**Step 4 — SAFE-only auto-apply:**
+Only changes that `classify_action.py` classifies as SAFE auto-apply through this path. Structural or architectural self-modifications — new phase, changed dispatch contract, agent-role change — surface as DECISION and are never auto-applied. They are queued to `.build-loop/proposals/needs-decision/` for explicit user action.
+
+### Authorized targets
+
+- Build-loop's own plugin repo (files under the build-loop working directory when `selfRecursive.enabled`)
+- `build-loop-memory` durable repo: lessons, skills, and project-scoped memory entries written via `scripts/memory_writer.py`
+
+### What is NOT authorized without user confirmation
+
+- Promotion of project-local skills to `~/.claude/skills/` (global scope — confirm first)
+- Changes to `agents/build-orchestrator.md` phase contracts or MECE ownership rules (structural — DECISION; surface as DECISION, never auto-apply)
+
+---
+
+## APPLY PROMPT
+
+This is the exact prompt text fed to `claude -p` by `scripts/self_review_run.sh` for deep auto-apply. Do not paraphrase — the wrapper reads this file and extracts the block between the `BEGIN_APPLY_PROMPT` and `END_APPLY_PROMPT` markers.
+
+<!-- BEGIN_APPLY_PROMPT -->
+You are running headlessly as part of a scheduled build-loop self-review. Your job is to apply safe improvements identified by the periodic self-review.
+
+Step 1 — Read the context:
+- Read `.build-loop/self-review/last-deep.json` (the data-gatherer output).
+- For each path listed in `queued[]`, read the proposal file. Take only proposals where `classify_hint: SAFE`.
+- Skip any proposal where `classify_hint` is `RISKY` or `DECISION` — leave those files untouched.
+- Separately, collect every entry in `self_simplification[]` where `classify_hint: SAFE` AND `target: self`. These are proactive self-simplifications of build-loop's own code and require the SELF-MODIFICATION SAFETY GATE in Step 2b.
+
+Step 2a — Apply each SAFE non-self proposal:
+For each SAFE proposal without `target: self`, route it through `/build-loop:run` with a goal derived from the proposal's title and body. Build-loop handles apply + commit + collapse. Its own autonomy gate and deployment policy govern what lands — do not bypass them.
+
+Step 2b — Apply SAFE `target: self` proposals (self-modification path):
+Self-modifications execute — they do not stop the loop. For each SAFE `target: self` proposal, apply the change, then — BEFORE committing — run the MANDATORY SAFETY GATE:
+```bash
+python3 scripts/self_mod_verify.py \
+  --workdir "$PWD" \
+  --scope auto \
+  --changed-files <the files you changed> \
+  --auto-revert \
+  --json
+```
+- `verdict: pass` → commit the change via the normal per-commit mode (one commit per self-modification; do not batch). The self-modification is recorded for the end-of-run readback.
+- `verdict: fail` → the gate has already auto-reverted the change. Move the proposal to `.build-loop/proposals/failed-gate/` and continue with the next proposal. NEVER commit a failed-gate self-modification.
+- Skip any `target: self` proposal that `classify_action.py` does not classify as SAFE (RISKY → isolate to worktree-branch + log; DECISION → queue to `.build-loop/proposals/needs-decision/`, do not apply).
+
+Do NOT stop the loop for any self-modification, including those that touch the gate scripts, tests, or the self-improvement loop. The test-suite gate is the oracle; if it passes, the change commits and is reported at the end.
+
+Step 3 — Determine push behavior:
+Read `.build-loop/config.json` key `selfReview.autonomy` (default `apply_push`).
+- If `apply_push`: after all SAFE proposals have been routed and landed, run `git push origin main` for the accumulated commits. Build-loop's deployment_policy still gates this; if the push is blocked by policy, log the block and exit 0 — do not force.
+- If `apply_local`: do not push. Commits land locally; the user pushes manually.
+
+Step 4 — Report:
+Print a short summary: how many SAFE proposals were processed (split: standard vs `target: self`), how many RISKY/DECISION items were left queued, how many `target: self` proposals were gated/reverted by a failed test gate, and the push status (pushed / local-only / skipped by policy / n/a).
+
+Include a `## Self-modifications (readback)` section listing every self-modification that landed this run: file, one-line what/why, test-gate verdict, and the additional-review finding (pass/flag). If no self-modifications occurred, omit the section.
+
+Constraints:
+- Never apply a RISKY or DECISION proposal autonomously.
+- Never apply a `target: self` proposal without running `self_mod_verify.py` first.
+- Never commit a change that `self_mod_verify.py` returned `verdict: fail` for.
+- Never stop the loop for a self-modification — including those that touch the gate, tests, or self-improvement loop scripts. The test gate is the oracle; pass → commit and continue; fail → auto-revert and continue. Report at the end.
+- Never bypass build-loop's commit auditor or autonomy gate.
+- If build-loop is not available as a slash command, log the unavailability and exit 0 — the queue stays intact.
+- This is a local developer tool; there are no users to protect other than the repo owner.
+<!-- END_APPLY_PROMPT -->

package/plugin-artifacts/codex/references/single-writer-commit-protocol.md

@@ -0,0 +1,90 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Single-Writer Git Commit Protocol
+
+_Linked from `agents/build-orchestrator.md` §Phase 3 Execute._
+
+Build-loop's commit-step protocol introduced 2026-05-07 to eliminate the parallel-commit race condition that lost 3 of 4 commits in round-3 fan-out testing. Implementers no longer call `git add` or `git commit` (per `agents/implementer.md` Hard rule 4); the orchestrator owns `.git/` as a single-writer resource. After **each parallel batch returns**, run this step before dispatching the next wave or proceeding to Phase 4.
+
+For each implementer return envelope with `status: fixed | partial | completed`:
+
+(For `status: "blocked"`, see `references/halt-and-ask-protocol.md` — that branch fires BEFORE the commit step and may iterate up to 3 times before producing a commit-eligible envelope.)
+
+00. **Pre-commit context snapshot** (NEW 2026-05-28 - non-blocking resume evidence): before staging, write the boundary state:
+   ```bash
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_snapshot.py \
+     --workdir "$PWD" \
+     --trigger pre_commit \
+     --phase execute \
+     --agent orchestrator \
+     --run-id "$RUN_ID" \
+     --chunk-id "<chunk_id>" \
+     --status committing \
+     --message "<commit_subject>" \
+     --file "<file-from-files_changed>" \
+     --json
+   ```
+   The helper writes `.build-loop/context/current.md`, a JSON snapshot, and a row in `.build-loop/context/commit-boundaries.jsonl`. Failure is a WARN only; do not bypass or alter the commit protocol because a snapshot failed.
+
+0. **Verify no staged residue** (NEW 2026-05-12 — closes the index-leak class seen in a prior 2026-05-11 private-app run): `git status --porcelain` and inspect the staged column (character 1 of each XY line). Implementers are contracted to leave working-tree changes only — they NEVER call `git add` (per `agents/implementer.md` Hard rule 4). Any non-space character in the staged column means an implementer violated that rule and the index is dirty before the orchestrator's own `git add`. ABORT this dispatch with: `Implementer left staged residue in the index; refusing to proceed. Files staged: <list>`. Route the offending implementer's plan back to Iterate with `additional_context: "Hard rule 4 violation — staged the index"`. Do NOT auto-clean and continue; the residue indicates the implementer's commit envelope can no longer be trusted.
+
+1. **Verify scope**: `git status --porcelain` — every modified/untracked file must appear in some implementer's `files_changed`. Files not claimed by any implementer = orchestrator-side scope-leak; investigate before committing.
+2. **Stage exactly that implementer's files**: `git add -- <files_changed_list>`. Use absolute paths to avoid relative-path ambiguity when multiple worktrees coexist.
+3. **Commit with the implementer's message metadata, not agent authorship**: `git commit -m "<commit_subject>" -m "<commit_body>"`. Do not pass `--author`, change `GIT_AUTHOR_*` / `GIT_COMMITTER_*`, or otherwise set the official git/GitHub author, committer, push actor, release actor, or equivalent platform actor to `Claude Code`, `Codex`, or any agent identity. Use the repo's configured human or service identity for official authorship. Agent involvement belongs in the commit body, run notes, `.build-loop` context, judge decisions, or other auxiliary metadata only. The pre-commit hook runs HERE (full-project tsc, lint-staged, betterer-strict — whatever the project has). If the hook fails, do NOT pass `--no-verify`; instead, capture the failure and route the implementer's plan back to Iterate with `additional_context: "<hook output>"`.
+4. **Verify commit landed**: `git log -1 --oneline` confirms the SHA. If `git status` after the commit still shows the implementer's files as modified, the commit didn't land — investigate.
+4a. **Post-commit context snapshot** (NEW 2026-05-28): after the SHA is known, write the landed boundary:
+   ```bash
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_snapshot.py \
+     --workdir "$PWD" \
+     --trigger post_commit \
+     --phase execute \
+     --agent orchestrator \
+     --run-id "$RUN_ID" \
+     --chunk-id "<chunk_id>" \
+     --status completed \
+     --message "<commit_subject>" \
+     --commit-sha "<sha>" \
+     --file "<file-from-files_changed>" \
+     --json
+   ```
+   This is the canonical handoff record for "what changed right before/after commit." It is generated runtime state under `.build-loop/context/` and is never durable memory by itself.
+5. **Attestation lint** (NEW 2026-05-07 — synthesis-decision drift catcher): immediately after the commit lands, persist the implementer's envelope to a temp path and run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/attestation_lint.py --diff "<sha>~1..<sha>" --envelope <envelope.json>` where `<sha>` is the commit just verified. The lint cross-checks every `synthesis_attestation` entry against the actual diff for the deterministic dimensions (`placement`, `cta_tier`, `visual_weight`); subjective dims (`copy_tone`, `empty_state`) return `unverifiable` and don't grade.
+   - **Exit 0** — every applied claim verified or only-unverifiable-with-some-pass: proceed silently to step 6.
+   - **Exit 1** — at least one entry FAILED: a synthesis claim is contradicted by the diff. Default action: revert the commit and route to Iterate with the lint output as `additional_context` (option a). Do not stop and ask the user — this is the kind of issue the loop is built to handle. Two failure modes warrant escalation: (i) Iterate has already retried this same lint failure 3 times without clearing it, in which case surface the failing entries via `AskUserQuestion` and offer all three options (revert, accept with override, amend envelope); (ii) the synthesis claim is on a dimension the user explicitly named in the original plan as load-bearing for user-visible behavior, in which case ask before reverting because reverting destroys evidence the user wants to inspect. Otherwise: revert, iterate, keep going.
+   - **Exit 2** — only unverifiable results (every dim was subjective or bare-string form): log a one-line warning to terminal output (e.g. `[Attestation] ⚠️  envelope had no graded claims — synthesis drift undetected this commit`), then proceed. This is informational, not blocking; it tells the operator the lint added zero coverage and the envelope should be richer next time.
+6. **Synthesis critic** (NEW 2026-05-07 — model-based grader for the subjective dims `attestation_lint.py` cannot verify): immediately after step 5 settles, decide whether to dispatch `synthesis-critic`.
+   - **UI-file gate (skip-if-no-UI-files)**: inspect the implementer's `files_changed`. If **none** of the paths match `*.tsx`, `*.jsx`, `*.vue`, or `*.svelte`, skip this step entirely and proceed to step 7 — the subjective dims (`copy_tone`, `empty_state`) only meaningfully apply to commits that change user-visible UI. Backend-only, infra-only, methodology-only, and doc-only commits never invoke the critic. Log one line: `[SynthesisCritic] skipped — no UI files in commit`.
+   - **Dispatch when UI files are present**: `Agent(subagent_type="build-loop:synthesis-critic", prompt=...)` with three context blocks in the prompt: (a) the unified diff (`git diff <sha>~1..<sha>`); (b) the plan's `synthesis_dimensions` block verbatim (so the critic has the claimed phrasing); (c) the implementer's `synthesis_attestation` and `notes` from the envelope. The critic returns one JSON object: `{verdict: "pass" | "flag", flagged: [{dimension, claimed, observed, reasoning}], notes: "..."}`.
+   - **`verdict: "pass"`**: log one line: `[SynthesisCritic] ✅ pass — N subjective dim(s) graded`. Proceed to step 7.
+   - **`verdict: "flag"`**: log a WARN line per flagged dimension (e.g. `[SynthesisCritic] ⚠️  copy_tone — claimed "calm-precision, no exclamation points"; observed "Done!" in NewsBanner.tsx`). Append the full JSON to `.build-loop/state.json.synthesisCriticFlags[]` for Phase 6 Learn pattern detection. **Do NOT block.** Do NOT route to Iterate. Do NOT alter the implementer's `f_criteria`. The critic is WARN-only by contract — flagged dims surface for the operator to triage but never gate the build.
+   - **Critic outage** (subagent dispatch fails or returns non-JSON): log `[SynthesisCritic] ⚠️  critic unavailable — subjective dims ungraded this commit` and proceed. Same WARN-only posture.
+7. **Commit-auditor advisory verdict** (NEW 2026-05-12, plan §12.7 P5): after step 5 settles, decide whether to dispatch `commit-auditor` (Opus, advisory).
+
+   **Trivial bypass** (skip dispatch when ALL of these hold):
+   - `(lines_added + lines_removed) < 20` for this commit (`git diff --shortstat <sha>~1..<sha>`)
+   - No spec-touch trigger present in the chunk's metadata (`contract_change`, `layer_crossing`, `destructive_op` all false)
+   - `state.json.planVerify.exit == 0` (last known)
+   - `state.json.scopeAudit.last_verdict == "green"` (last known)
+
+   When bypassed: append `{judge_id: "commit-auditor", checkpoint_id: "<run_id>:<chunk_id>:pre-commit", verdict: "approve", confidence: 1.0, spec_alignment: "aligned", variances: [], bypass_reason: "trivial", policy_refs: []}` directly to a temp `judge_decisions.json` (collected for Phase 4 Review-F `--judge-decisions-json` flush). Log one line: `[CommitAuditor] bypass — trivial (lines=N, no spec-touch)`.
+
+   **Otherwise dispatch**: `Agent(subagent_type="build-loop:commit-auditor", prompt=...)` with the brief shape documented in `agents/commit-auditor.md` (chunk_id, diff_sha, diff_stat, files_owned, plan_path, rubric_criteria_ids, constitution_loaded_rule_ids, triggers, recent_judge_decisions). Run in parallel with step 6 synthesis-critic when both are firing — they read the diff independently and write to non-overlapping state fields.
+
+   **Verdict routing** (advisory only — NEVER blocks):
+   - `approve` — log one line, append to `judge_decisions[]`, proceed.
+   - `rethink` — log WARN per variance; surface to the implementer's next-iteration brief if Phase 5 fires; do not auto-revert. Implementer's eventual response goes in `implementer_response` field of the same judge_decisions entry (orchestrator updates after Phase 5 attempt or commit).
+   - `new_approach` — log WARN, surface to Phase 4 Report's `## Notes from judges`, route to next phase normally. If the implementer disputes and proceeds, that's a logged disagreement, not a halt. Two consecutive `new_approach` on the same chunk → orchestrator surfaces via PushNotification + TaskCreate "[BUILD-LOOP] Judge requesting re-plan on chunk <id> — your review needed" but the build continues independent chunks; chunk-id's dependents pause until user input or the next phase transition allows them to resume.
+
+   **Auditor outage** (dispatch fails or returns non-JSON): log `[CommitAuditor] ⚠️  unavailable — chunk un-audited this commit` and proceed. Same advisory posture.
+
+8. **Repeat sequentially** for each remaining implementer in this batch. Sequential by design — the pre-commit hook is the only serializer; implementers' parallel work landed on a clean working tree, but the commits themselves serialize through the hook.
+
+## Concurrency contract
+
+- Implementer side: writes to working tree, never to `.git/`. Returns `commit_subject` + `commit_body` + `files_changed` in envelope.
+- Orchestrator side: reads `.git/` (status, log, diff) freely; writes to `.git/` (add, commit) only here, sequentially.
+- Single writer = no race. Round-3's lost-commits issue is structurally prevented.
+
+## Recovery from legacy implementer behavior
+
+If you discover an implementer that ignored Hard rule 4 and called `git commit`: the working tree may show some files committed, others uncommitted. Run `git log -<N> --oneline | head` to enumerate the unexpected commits, then commit the remaining files with their owning implementer's metadata. Surface the rule-4 violation in Review-G so we can refine the implementer prompt for next run.

package/plugin-artifacts/codex/references/task-capture-policy.md

@@ -0,0 +1,68 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Task Capture Policy
+
+Build-loop does not add a new durable task ledger by default. The active task
+view is derived from existing surfaces through:
+
+```bash
+python3 scripts/task_surface.py --workdir "$PWD" --json
+```
+
+This answers "what is still open for this repo/branch?" without creating
+another freeform cross-repo tracker.
+
+## Current Surfaces
+
+| Surface | Lifecycle | Owner |
+|---|---|---|
+| Plan `T-N` IDs | Planned work inside a specific build | Phase 2 plan + `plan_verify.py` |
+| `.build-loop/state.json.execution` | Active run queue/in-flight/completed chunks | Orchestrator |
+| Implementer working state | Current task/file/status while a worker is active | Implementer |
+| Cost ledger `task_id` | Dispatch/return correlation and cost analysis | Orchestrator |
+| Rally task heartbeat | Long-running task liveness and still-on-task health | Active terminal |
+| `.build-loop/ux-queue/` | Review-discovered UX/test-coverage work for Phase 5 | Review-D/Iterate |
+| `.build-loop/issues/` | Repo-local open issues detected during runs | Review/Learn |
+| `.build-loop/followup/` | Deferred current-run items that should drain later | Report/queue drain |
+| `.build-loop/backlog/` | Repo-local backlog items | Queue continuation |
+| `.build-loop/proposals/` | Candidate self-review/improvement ideas, opt-in only | Learn/self-review |
+| `build-loop-memory/projects/<slug>/backlog.md` | Durable project backlog | Memory writer / human backlog |
+| TaskCreate/TaskUpdate list | Host-visible user-facing mirror | Orchestrator/session |
+
+## Decision
+
+Use `scripts/task_surface.py` as the canonical active view. It reads the
+current repo's execution state, local queues, and project-scoped memory backlog,
+then emits a priority-sorted JSON list with
+`decision: "derived-active-view-no-new-ledger"`. It is read-only and writes no
+ledger. Proposals are excluded by default because they are candidates, not open
+tasks; pass `--include-proposals` for self-review sweeps.
+
+Do not add `.build-loop/tasks.jsonl` until there is evidence that the derived
+view cannot answer a real Phase 1 or coordination question. The failure mode to
+avoid is a second source of truth where tasks close in one place and remain open
+elsewhere.
+
+## Promotion Rules
+
+- Transient checklist items stay in the host task list and current run state.
+- Deferred work becomes `.build-loop/followup/` or `.build-loop/backlog/` using
+  the existing queue rules.
+- Durable project work goes to `build-loop-memory/projects/<slug>/backlog.md`
+  or milestones. Do not persist every subtask into memory.
+- Completed/superseded tasks archive with rationale through the owning surface
+  (followup/backlog archive, milestone, or decision), not silent deletion.
+
+## Phase 1 Contract
+
+Phase 1 may answer open-work questions by running:
+
+```bash
+python3 scripts/task_surface.py --workdir "$PWD" --json
+```
+
+If `open_count > 0`, surface the top active items by priority:
+in-flight/queued chunks, UX queue, issues, followups, repo backlog, memory
+backlog. Do not scan sibling project backlogs. Include proposals only when the
+current task is specifically self-review, improvement triage, or proposal
+cleanup.

package/plugin-artifacts/codex/references/ui-io-contract.md

@@ -0,0 +1,116 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Input/Output Contract
+
+Use this contract for any build-loop task that adds, modifies, or validates a user-facing UI surface. It turns "build the component" into an explicit inventory of what the user can provide, what the system returns, and which UI pattern must handle each data shape.
+
+## When It Applies
+
+Apply this when `uiTarget != null` and the task changes any screen, component, form, table, chart, voice/audio affordance, file workflow, generated output, or streamed response. Skip only for copy-only changes that do not alter the available inputs, outputs, states, or operations.
+
+## Required Plan Section
+
+Every UI plan must include a `## UI Input/Output Contract` section before implementation. Use one row per affected screen or component, and keep each field concrete.
+
+| Field | Required Answer |
+|---|---|
+| Surface | Screen/component name plus file path |
+| User inputs | Every value the user can provide |
+| System outputs | Every value the user receives or decides from |
+| Data taxonomy | Structural type, content format, persistence intent |
+| Operation model | CRUD operation plus any domain verb |
+| Component mapping | Exact input control and output renderer |
+| State matrix | Empty, populated, focused, disabled, loading, success, error, and streaming/abort when relevant |
+| Modality | Text, voice, file, vision, chart, map, AI/generated, or streaming; include fallback |
+| Validation/security | Presentation, application, and domain validation; sanitization; auth/authz display behavior |
+| Traceability | Data schema, API endpoint/method, design-system component, and rationale |
+
+## Data Taxonomy
+
+Classify each input and output before choosing UI controls:
+
+- **Structural type**: scalar, structured object/array, binary, stream.
+- **Content format**: plain text, Markdown, rich text, HTML, JSON tree, chart data, audio, image, map/geospatial.
+- **Persistence intent**: persisted CRUD data, transient session state, real-time stream, computed/derived output.
+
+## Operation Model
+
+Name the operation the UI performs:
+
+- **Create**: POST, form, wizard, inline add.
+- **Read**: GET, table, card, detail view, chart.
+- **Update**: PUT/PATCH, edit form, inline edit, toggle.
+- **Delete**: DELETE, destructive button, confirmation.
+- **Domain verbs**: submit, approve, publish, escalate, cancel, refund, reorder, filter, sort, export, download.
+
+Do not hide domain verbs inside generic "update" language when rules, side effects, or affordances differ.
+
+## Component Mapping
+
+Choose components from the data shape, not habit.
+
+| Data Shape | Input Control | Output Renderer |
+|---|---|---|
+| Short string | Single-line input | Text with overflow/copy behavior |
+| Long plain text | Textarea with sizing policy | Paragraph or preformatted text |
+| Markdown | Split write/preview editor | Sanitized Markdown renderer |
+| Rich text | Schema-backed editor | Paired rich-text viewer |
+| JSON/object | Schema-aware JSON editor/tree | Collapsible tree or raw/parsed toggle |
+| Number | Number input, slider, or stepper | Locale-aware number display |
+| Boolean | Toggle, checkbox, or yes/no radio | Explicit state label |
+| Date/time | Date/time/range picker | Locale/timezone-aware display |
+| Enum | Select, radio group, or searchable select when options exceed seven | Label/chip/list value |
+| File/binary | Upload/dropzone with progress | Preview/download with file metadata |
+| Voice/audio | Mic button with waveform and text fallback | Audio player/TTS plus transcript |
+| Tabular data | Filters/search feeding table | Sort/filter/paginated table |
+| Chart data | Form/filter inputs feeding visualization | Named chart type plus table fallback |
+| Streaming/AI output | Prompt or structured input | Token/partial renderer with abort and retry |
+| Geospatial | Address/map controls | Map with markers/clusters and fallback text |
+
+## State Matrix
+
+Document the states each component must render:
+
+- Default/empty.
+- Populated/filled.
+- Focused.
+- Hover on pointer devices.
+- Active/pressed.
+- Disabled/permission-blocked.
+- Loading.
+- Success.
+- Error/invalid.
+- Empty result.
+- Streaming/partial with abort and retry behavior when relevant.
+
+## Modalities
+
+When a modality exists, it needs its own UI and failure path:
+
+- **Text**: text input, textarea, rich text, text/Markdown renderer.
+- **Voice**: push-to-talk or wake-word trigger, ASR provider/threshold if known, transcript fallback, TTS controls.
+- **File**: upload control, MIME/size rules, preview/download, copy-text fallback.
+- **Vision/image**: image upload/camera, viewer/annotation, alt-text fallback.
+- **Chart/graph**: chart type, data schema, axis labels, colorblind-safe palette, table fallback.
+- **AI/generated output**: output type contract, response schema/template, streaming vs complete mode, abort/retry behavior.
+
+## Validation And Security
+
+Validation must be named by layer:
+
+- **Presentation**: required fields, max length, pattern, type, inline field errors.
+- **Application**: cross-field and business-rule errors, form-level/toast surface.
+- **Domain**: invariant failures, system-error surface, and whether repeated domain failures indicate a spec gap.
+- **Sanitization**: allowed subset for Markdown, rich text, HTML, JSON, and generated content.
+- **Auth/authz**: permission required for create/update/delete/domain verbs, and UI behavior when denied: hidden, disabled, or 403/empty view.
+
+## Traceability
+
+Each UI element that accepts or returns data must trace to:
+
+- Data model or schema version.
+- API endpoint/method or local data source.
+- Design-system component or explicit net-new rationale.
+- Test or validation evidence.
+
+If the trace cannot be named, the plan is incomplete.

package/plugin-artifacts/codex/references/ui-spotcheck-protocol.md

@@ -0,0 +1,65 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Spot-Check Protocol (Phase 3 chunk-close)
+
+_Linked from `agents/build-orchestrator.md` §Phase 3 Execute and §"Phase 3 UI spot-check (between chunks)"._
+
+After the commit step closes for a chunk **and before the next chunk dispatches**, fire `ui-validator` whenever the just-closed chunk's `uiTouched` signal is true. Catches UI regressions inside the chunk that introduced them instead of letting them ride to end-of-Phase-4.
+
+This is the procedural complement to `agents/ui-validator.md` (the agent contract).
+
+## `uiTouched` signal
+
+Compute at chunk-close from the envelope's `files_changed`:
+
+| Trigger | `uiTouched` |
+|---|---|
+| Any file under `(app\|components)/**/*.tsx` | `true` |
+| `tailwind.config.{js,ts}` or theme/global-style files | `true` |
+| Style helpers under `lib/(theme\|styles)/**` | `true` |
+| Test files only (`tests/**`, `*.test.*`) | `false` |
+| Schema / API route only (no UI files in the chunk) | `false` |
+
+Cache the verdict on `state.json.execution.completed_chunks[<chunk_id>].uiTouched` so resume picks it up.
+
+## Dispatch
+
+Sonnet tier; see `agents/ui-validator.md` for the agent contract:
+
+```python
+Agent(
+  subagent_type="build-loop:ui-validator",
+  prompt=brief({
+    triggerPoint: "phase3-chunk-close",
+    changedFiles: envelope.files_changed,
+    baseUrl: state.devServer.baseUrl,           # captured by detect_runtime_server
+    priorBaselineDir: ".build-loop/ui-baselines/" + run_id + "/",
+    signInForm: state.devServer.signInForm,     # null if no auth fixture
+  })
+)
+```
+
+Cost ledger (M3) applies — emit `--agent ui-validator` rows at dispatch and return.
+
+## Routing on return
+
+| envelope.status | Action |
+|---|---|
+| `pass` | Continue to next chunk dispatch. Persist envelope to `.build-loop/subagent-results/<run_id>/ui-spotcheck-<chunk_id>.json`. |
+| `fail` | Treat `envelope.failing_assertion` as a rubric and route the chunk back to Iterate (same routing as Review-B failure path). Do NOT dispatch downstream chunks in the same batch — drain the queue first by serializing the next batch after the iterate fix. |
+| `skipped` | Continue. `skip_reason` distinguishes: `auth-gap` (mark `⚠️ ui-spotcheck skipped — auth fixture missing` in Review-G), `no-dev-server` (mark `⚠️ untested ui — no dev server`), `no-routes-implicated` (silent skip — implementer touched no public render path). |
+
+## Iteration budget
+
+UI-spot-check failures consume the global 5x classic (or 25 autonomous) Iterate cap. They do not get a separate budget.
+
+## Skip conditions
+
+Skip the dispatch entirely when:
+
+- `uiTouched: false` (no UI files in chunk)
+- `state.devServer.runtimeServer: false` (library-only project, no dev server to scan against)
+
+## Render-path fallback
+
+If no browser/simulator/native-AX render path is available, `ui-validator` returns `skipped` with the reason and the orchestrator records the evidence gap. Review-D then falls back to `audit-design-rules.mjs` plus the static checks in `skills/build-loop/fallbacks.md#web-ui`. IBR is not an automatic fallback; run `build-loop:ibr-bridge` only when the user explicitly asks for IBR / Interface Built Right / `.ibr-test.json`.