@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/build-loop/references/phase-1-assess.md

@@ -54,6 +54,7 @@
 3. **Set sub-routers**: `uiTarget` (web / mobile / **macos** / null), `platform` (web / apple / react-native / null), `migrationSource` (replit / lovable / bolt / v0 / null). See the Capability Routing §Sub-routers rules. **macOS desktop is a first-class `uiTarget`** — distinct from `mobile` — because macOS has no simulator and routes visual-verify to `native-ax-driver` (or IBR `scan_macos` when present), never to `xcrun simctl`. Folding macOS into `mobile` was the routing bug from session-findings 2026-06-04.
 4. **Detect available tools**: test runners (`package.json` scripts, `pytest.ini`, etc.), linters, deploy targets.
    - **Deployment policy**: read `.build-loop/config.json.deploymentPolicy` if present. Defaults are `preview: auto`, `testflight: auto`, `production: confirm`, `unknown: confirm`. Use `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/deployment_policy.py --workdir "$PWD" --command "<candidate push/deploy command>"` before any push/deploy. Treat helper errors as `confirm`.
+4a. **Automatic execution profile**: load `references/resource-aware-execution.md`, run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/review_trigger.py --context .build-loop/state.json --json`, and persist the envelope at `state.json.execution.resourceProfile`. `skip` exits the full loop after deterministic validation; `standard` uses one independent audit plus signal-triggered heavy checks; `high` keeps the full review path. Recompute after Plan has concrete changed-file and line estimates. Profiles are internal routing data, never user-facing options.
 5. **Map architecture** using best available approach:
    - If `.navgator/architecture/index.json` exists → invoke `Skill("build-loop:architecture-scan")` to refresh data, then `Skill("build-loop:architecture-impact")` on up to 5 highest-risk components for blast-radius. Output goes to `.build-loop/state.json.architecture.{scan,impact}`. Phase 2 Plan consults this for scoping. Flags high-fan-in hotspots, 2-hop dependents, layer-crossing risks, and prompts-in-scope when `triggers.promptAuthoring` is true.
    - Else if `gator:*` is available → use those commands.
@@ -67,7 +68,7 @@
 
 6a. **Runtime-server detection** (informational, no changes): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/detect_runtime_server.py --workdir "$PWD" --json` and write the result to `.build-loop/state.json.triggers.runtimeServer` (boolean) plus `.build-loop/state.json.runtimeServerInfo` (full envelope: `server_module`, `sse_route`, `default_port`, `embedded_ui_module`, `event_handler_locations[]`, `evidence[]`). Phase 4 sub-step B Validate consults these for the live HTTP/SSE smoke gate. Helper failure → treat as `runtimeServer: false` and log a one-line warning; never blocks. Silent default for CLIs, libraries, plugins, and static-render web apps. Implements decision `_unscoped/0003` (live smoke required when build-loop touches a runtime server) — closes the pytest-with-mocks blind spot that let example-app ship 27 commits with two real bugs.
 7. **Debugger context priming** (always; native to build-loop): invoke `Skill("build-loop:debugging-memory")` with `{ intent: "list-recent", project: "<current>" }` to summarize recent incidents in this project. One-line output; no action. If cross-project Coding Debugger is installed, the skill may use it; otherwise it falls through to `fallbacks.md#bug-memory`.
-8. **Capture UI state** (if web/mobile): host browser/screenshot tooling or simulator/native-AX evidence when available → showcase capture → manual screenshot. Do not route to IBR unless the user explicitly requested it.
+8. **Capture UI state** (if web/mobile): when a renderable UI design is being updated, compared, or audited, invoke headless IBR first when installed per `../../../references/ibr-ui-verification-policy.md`; otherwise use host browser/screenshot tooling or simulator/native-AX evidence → showcase capture → manual screenshot.
 8a. **UI input/output inventory** (if `uiTarget != null`): load `skills/build-loop/references/ui-io-contract.md` and identify every affected user input and system output before component choices are made. Classify each by structural type, content format, persistence intent, operation/domain verb, component mapping, state matrix, modality fallback, validation/security layer, and traceability. Mirror a compact summary to `.build-loop/state.json.uiIOContract` when practical; the full contract is finalized in Phase 2.
 
 8b. **Load short-term working context (Pillar 0 — structurally loaded first, inside memory bootstrap)**: `context_bootstrap.build_packet()` calls `load_current(workdir)` at its very entry, before any heavier memory work, and attaches the result as `packet['working_context']` (a serialized `WorkingContextEnvelope`). The working context is therefore available as part of the Phase-1 packet without a separate CLI step.
@@ -122,6 +123,14 @@
 
    **Supersedes** the legacy `ps aux | grep -c "[c]laude$"` advisory below — Rally Point presence is the canonical signal. Keep the legacy line as a fallback only when Rally Point is unavailable (older plugin cache without `scripts/rally_point/`).
 
+9b. **Data-plane worktree router**: Inspect the goal and repo signals using
+`references/capability-routing.md` § `data-plane-worktrees`. When any signal
+fires, set `state.json.triggers.dataPlaneWorktree: true` and load
+`Skill("build-loop:data-plane-worktrees")` before Phase 2. Inventory every
+mutable non-Git surface in the baseline manifest created by step 9a, then require
+manifest validation before the first write. No signal means the baseline empty
+manifest is an explicit source-only run record.
+
 10. **Load PRD if present** (strategic frame check): load `build-loop:prd-bridge`, run its Phase 1 Assess step. If `docs/prd-*.md` exists, the bridge reads frontmatter (`core_principles`, `load_when`, `evolves_when`), Navigation Map, and Section Index, mirrors them to `.build-loop/state.json.prd`, and surfaces staleness signals. If no PRD exists, the bridge writes a one-line recommendation in `state.json.prd.recommendation` pointing to `prd-builder` skill / `/build-loop:start-prd` command — surfaces in Sub-step G Report's `## Held` section, doesn't block. Step 11 below uses PRD as primary source of truth when present; falls back to fresh capture when absent.
 11. **Capture north star + update intent**: When `state.json.prd.core_principles` is non-empty (a PRD was loaded by step 10), use it as the strategic frame; `intent.md` cites the PRD path + revision rather than re-deriving. Otherwise use `references/intent-capability-pack.md` to identify app/repo purpose, primary users, core jobs, update intent, user value, and non-goals fresh. Write `.build-loop/intent.md` and mirror compact fields to `.build-loop/state.json.intent`.
 
@@ -179,12 +188,103 @@
    This is the canonical active view over existing state, queue, and
    project-scoped memory backlog surfaces. Do not create a second task ledger by
    default. See `references/task-capture-policy.md`.
+14b. **Groundwork request intake** (blocking when present): when
+   `GROUNDWORK_BUILD_REQUEST` is set or `.designdoc/build-request.json` exists,
+   validate the request and its adjacent canonical Spec before planning:
+
+   ```bash
+   request="${GROUNDWORK_BUILD_REQUEST:-$PWD/.designdoc/build-request.json}"
+   spec="${GROUNDWORK_SPEC:-$(dirname "$request")/spec.json}"
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/groundwork_exchange.py" validate-request \
+     --request "$request" --spec "$spec" \
+     --output "$PWD/.build-loop/groundwork-request.json"
+   ```
+
+   Exit 0 binds `specDigest`, the ordered `taskDigest`, and the self-digested
+   request; carry its task IDs, acceptance criteria, dependencies, and manual
+   boundaries into the plan without rewriting Groundwork's desired state. Exit
+   2 is a Phase 1 failure: stop this request path and report the exact contract
+   error. Never downgrade an invalid or stale request to an ordinary prompt.
+   Keep the request and Spec paths for Review-G, where Build Loop returns
+   implementation evidence and Groundwork calculates convergence.
+14c. **Outcome-autonomy preflight** (required before autonomous, background,
+   headless, `--long`, or resumed queue-drain work): assemble the facts already
+   known from intent, goal, plan, credentials, deployment policy, and tool
+   detection. Initialize the runtime envelope once, then assess missing facts:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/autonomy_supervisor.py" \
+     --workdir "$PWD" initialize --run-id "<run_id>" --goal "<outcome>" \
+     [--long | --budget 30m] [--autonomous false]
+   python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/autonomy_supervisor.py" \
+     --workdir "$PWD" preflight --request \
+     '{"goal":"<outcome>","success_criteria":["<pass condition>"],"scope_roots":["<repo>"],"validation_commands":["<command>"],"external_dependencies":[]}'
+   ```
+
+   Persist the envelope at `state.json.execution.autonomyPreflight`. Process it
+   before Plan:
+
+   - `questions[]` contains only facts that change production, reversibility,
+     authorized scope, or a major user-facing outcome. Ask them together once;
+     include `why` and `impact` from the envelope.
+   - `assumptions[]` contains reversible gaps. Record every assumption in the
+     plan and execute its named `validation` before the first dependent chunk.
+   - `task_profile` summarizes prior runs of the same task shape. Use
+     `supervision_recommended` to enable checkpointed queue supervision; never
+     treat elapsed time as the outcome or a reason to stop useful work.
+
+   The initializer enforces `--budget` over `--long`, persists one host-neutral
+   budget envelope, and marks the deadline as a soft finalization target. The
+   run still optimizes for the accepted outcome and related validated work.
+
+   After closeout, append actual duration, related discoveries/completions, and
+   interventions with `autonomy_supervisor.py record-run`. This makes future
+   preflight task-specific. No history means `insufficient_history`, never a
+   guessed claim.
 15. **Recovery check**: This used to be a phase-level marker. As of v0.11 the canonical recovery surface is the `--resume` argument and the heartbeat-staleness path documented under §Resume Protocol. The pre-Assess resolver already ran by the time Phase 1 starts; if it returned `decision: "prompt_user"` and the user chose "fresh", proceed normally; if they chose `--resume`, you're not in this code path (the agent is in §0 Resume mode instead).
 16. **Workspace concurrency check** (advisory, no blocking — surface as one-line notes):
     - **Concurrent sessions**: `ps aux | grep -c "[c]laude$"`. If `>1`, warn that other sessions on this repo can silently revert each other's work; the checkpoint reactions (severity + reason) tell you whether overlap is `merged_residue` / `squash_landed` / `active_conflict`. See `agents/build-orchestrator.md` §Multi-session concurrency.
     - **Branch divergence**: `git rev-list --count HEAD..origin/main` and `origin/main..HEAD`. If local main is ahead of origin AND a feature branch will be cut, recommend branching from `origin/main` directly (`git checkout -b <name> origin/main`) so unpushed local commits don't ride into the eventual squash and bundle under a misleading title.
     - **Recovery if symptoms appear during build** (file writes vanish, system reminders flag "intentional" reverts, `git status` clean): pause edits, run `ps aux | grep claude` + `git log --oneline -- <affected paths>` to identify the colliding session/squash, then re-apply dropped work on a fresh branch from `origin/main`.
 
+### Pre-authorization interview (unattended runs only)
+
+Fires when the run is meant to proceed without a human present: autonomous / `--long` mode, a background or headless dispatch, a `ScheduleWakeup` resume, or an explicit "run this unattended / overnight / while I'm out". Skip it entirely for attended interactive runs — the normal gates already work when someone is watching.
+
+Collect the standing policy **once, up front**, instead of discovering each stop mid-run. Four questions, asked together in a single `AskUserQuestion`:
+
+1. **Repo scope** — which repos/paths may this run write to?
+2. **Irreversible-action policy** — `skip_and_record` (skip and log the exact command) · `surface_and_wait` · `never_attempt`.
+3. **Conditional gates** — any action pre-authorized *only when a measurement clears a threshold*. This is the one that carries weight: *"deploy only if contrast measures ≥ 4.5:1"* authorizes an outcome, not an action.
+4. **Stop rule** — consecutive failures on the same problem, and wall-clock ceiling.
+
+Record it:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/preauthorization.py" record \
+    --run-id "<run_id>" --unattended --repo-scope "$PWD" \
+    --irreversible-policy skip_and_record --stop-rule-failures 5 --stop-rule-hours 8 \
+    --gate '{"id":"deploy-contrast","action":"deploy","metric":"contrast_ratio","op":">=","threshold":4.5,"measurement_source":"computed from rendered fg/bg","on_fail":"skip_and_record"}' \
+    --workdir "$PWD" --json
+```
+
+At the moment a gated action comes up, evaluate it against a **measured** value:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/preauthorization.py" evaluate \
+    --gate deploy-contrast --measured 4.2045 --workdir "$PWD" --json    # exit 1 — refused
+```
+
+Rules the script enforces, so they cannot erode:
+
+- A gate recorded without a `measurement_source` is rejected at record time. An authorization whose evidence source is unnamed cannot be checked later.
+- A gated action with **no measurement supplied** returns `confirm`, never `auto`. The gate existing is not the authorization.
+- Pre-authorization can only relax a `confirm` into an `auto` for an action it explicitly covers with a satisfied condition. It never relaxes a `block`, never covers an action outside `repo_scope`, and an absent `preauthorization.json` authorizes nothing.
+
+This is the proactive counterpart to `scripts/question_timeout.py`, which resolves questions reactively once the run is already moving. Both may be active; the interview answers what it can before the run starts, the timeout handles what it could not anticipate.
+
+**Why.** 2026-08-07: four questions asked up front converted a run that would have stopped six times into one that ran unattended across three repos. The conditional gate proved its own worth by refusing — the authorized deploy did not fire, because the value it was authorized against measured 4.2045 against a 4.5 threshold. Blanket approval would have shipped it.
+
 ### UI scope and mockup pre-flight (when uiTarget != null)
 
 **UI pre-flight**: If project has `mockups/` or `.mockup-gallery/` and goal references selected mockups, run the design-rule scanner against the mockup HTML/CSS first to surface conflicts before coding:
@@ -244,6 +344,6 @@
 
    Write to `state.json.synthesisDensity` as `{count, escalated, reason}`. Routing target is `tier: thinking`, **never a hardcoded model name** (`scripts/model_overrides.py`: repo config → state snapshot → orchestrator frontmatter fallback → fail-loud). When `escalated == true`, do NOT fan out; execute inline at thinking-tier.
 
-    **Why this shape:** n=6 A/B experiment (2026-05-07, `~/dev/research/topics/synthesis-decision-delegation/experiment-2026-05-07/`) showed β catches ~40% of α's novels — real quality gap — but also showed β saves ~33% wall-clock and ~28% tokens, and the C3-C5 backstops catch some leaks. Defaulting Opus universally would erase β's velocity; the `> 5` threshold matches the empirical inflection point where β's recall collapses (C5 at 5 dims surfaced 0 novels vs α's 5). Below that, fan-out is the right speed choice; above it, depth dominates. Plan/chunk-level overrides let the operator pick quality > speed when needed without changing the default. See `agents/build-orchestrator.md` Phase 1 for full procedure.
+    **Why this shape:** n=6 A/B experiment (2026-05-07, "synthesis-decision-delegation" — private research note, substance summarized here) showed β catches ~40% of α's novels — real quality gap — but also showed β saves ~33% wall-clock and ~28% tokens, and the C3-C5 backstops catch some leaks. Defaulting Opus universally would erase β's velocity; the `> 5` threshold matches the empirical inflection point where β's recall collapses (C5 at 5 dims surfaced 0 novels vs α's 5). Below that, fan-out is the right speed choice; above it, depth dominates. Plan/chunk-level overrides let the operator pick quality > speed when needed without changing the default. See `agents/build-orchestrator.md` Phase 1 for full procedure.
 
 **Output**: Structured state summary + `.build-loop/intent.md` + `.build-loop/goal.md` with criteria. Brief.

package/skills/build-loop/references/phase-2-plan.md

@@ -16,12 +16,13 @@
    - `action: "call"`, `skill: "prd-builder"` → greenfield PRD authoring (only when `run_active == false`); outside an active run this row rarely reaches Phase 2.
    - **Fallback** (record absent — older state, or a Codex lead that skipped step 11): apply the router's own logic inline. Compute `plan_status` exactly as the signal is defined — `no-plan` when `.build-loop/plan.md` is absent/empty OR the last `plan-verify` result failed; `plan-valid` otherwise. If `plan_status == no-plan`, invoke `Skill("build-loop:spec-writing")`; otherwise skip to step 1.
 
-   When spec-writing is invoked it walks the completeness checklist (auth guard, external API contracts, rate-limit criterion, discoverability surfaces, server/client boundary, concurrency mechanism, observability events, input validation, UI input/output contract when UI is in scope, and routing-risk fields), runs `check_checklist.py` + `plan-critic`, writes the plan to `docs/plans/<feature-slug>.md`, and commits it before any implementation branches are cut. Only continue to step 1 once a plan path exists.
+   When spec-writing is invoked it walks the completeness checklist (auth guard, external API contracts, rate-limit criterion, discoverability surfaces, server/client boundary, concurrency mechanism, observability events, input validation, UI input/output contract when UI is in scope, routing-risk fields, dispatch/env-var fields, capability gap map, single-shot build guardrails, and read-before-edit map), runs `check_checklist.py` + `plan-critic`, writes the plan to `.build-loop/plans/<feature-slug>.md`. Only continue to step 1 once a plan path exists.
 
 1. **Invoke `writing-plans` skill** for detailed task breakdown
 2. **Identify parallel-safe tasks** vs sequential dependencies — build a dependency graph
    - If the graph has 2+ independent / parallel-safe chunks, write `parallel_batch:` naming the chunks that will dispatch together.
    - If the graph appears parallelizable but execution must serialize, write `parallel_skipped_reason:` with the specific dependency, tool limit, or coordination constraint.
+2a. **Recompute resource profile**: rerun `scripts/review_trigger.py` with every planned `--changed-file` and `--lines-changed <expected-delta>`. Persist the result at `state.json.execution.resourceProfile`; promote to `high` when either Assess or Plan returned `high`. Carry its `review_steps` into Review instead of dispatching every optional reviewer by default.
 3. **Map each task to intent**: state which user workflow, user-value rule, and north-star outcome it supports. Remove tasks that add complexity without clear user value.
 3a. **Approach Lenses section**: For non-trivial architecture, workflow, dependency, UI/product, or long-lived interface decisions, add `## Approach Lenses` before the task list. Use the Phase 1 `.build-loop/state.json.approachLenses` summary and include:
    - **Clean-sheet best approach**: the use-case-first answer if no prior implementation debt or historical decisions constrained the design.
@@ -32,6 +33,9 @@
    Skip only for narrow single-file fixes, pure config changes, or decisions where the two answers are identical; in that case write `Approach Lenses: n/a - <reason>`.
 3b. **Depends-on (reads-from) section**: For any plan that ships code, add a `## Depends-on (reads-from)` section listing every data path, contract, or invariant the new/changed code reads. Each entry takes the form `- \`<path-or-contract>\` — verified` or `- \`<path-or-contract>\` — unverified`. Mark `verified` when you can confirm something in the repo writes that path or holds that invariant (grep, schema inspection, or test fixture confirms it); mark `unverified` when no writer exists or you cannot confirm. Any `unverified` entry is a BLOCKING unknown that must be resolved — either add the missing writer to the plan, remove the read, or add `override: reads-from-dependency` with rationale. This section is exempt for doc-only and config-only plans that name no source-code paths. Enforced by `plan-verify` rule `reads-from-dependency`.
 3c. **Activation Map section**: For any plan that proposes a new *event-driven or call-site-dependent* component — a stop/SessionStart/PreToolUse/PostToolUse hook, a cron/launchd job, a watcher, a git hook (pre-commit/post-commit), a webhook, or a gate that fires on a host event — add an `## Activation Map` section. This converts build-loop's recurring failure class (machinery built, activation path never verified — a dormant WARN gated on a dict that int()'d to 0, state_finalize reading the wrong phase key, repo-level codex hooks that never fired, run-identity reuse silently skipping records) into a structural plan requirement. Each entry takes the form `- <component> — trigger: <event-or-call-site> — verified-live: yes|pending`. The `trigger:` must name the *concrete* host event or call site (e.g. `PostToolUse:Bash matcher in hooks/hooks.json`, `SessionStart hook`, `pre-commit hook in .pre-commit-config.yaml`), not an aspiration ("runs at review time"). Mark `verified-live: yes` only when you have confirmed the trigger actually fires (a live run exercised it, or a test asserts the host event reaches the handler); mark `verified-live: pending` otherwise. Any `pending` entry must map to a verification task before Report — the plan does not close while a component's activation is unconfirmed. This section is exempt for plans that propose no new event-driven machinery (doc-only, refactor-only, pure inline-logic changes); a `## Activation Map` is not required there. Add `override: activation-map-exempt` with rationale only when the section genuinely does not apply. Enforced by `plan-verify` rule `activation-map-required` (BLOCKER: missing section on a dormant-risk plan, or any entry that names a `trigger:` without a `verified-live:` key).
+3d. **Capability Gap Map section**: For any non-trivial implementation plan, add `## Capability Gap Map` before the F/Q criteria. Map each changed capability or workflow to: current source of truth, target behavior, gap, build action, owned files/contracts, and validation. This is the default home for "current vs target" gap closure; avoid a separate gap-closure plan unless the user asks for one or the map is too large for the main plan.
+3e. **Single-Shot Build Guardrails section**: For any non-trivial implementation plan, add `## Single-Shot Build Guardrails`. Each row names a guardrail, the failure mode it prevents, and the evidence/test that proves compliance. Guardrails must be enforceable: cite a target test, ADR, source file, acceptance criterion, or command. Generic cautions without evidence do not count.
+3f. **Read-Before-Edit Map section**: For any non-trivial implementation plan, add `## Read-Before-Edit Map`. Each work item must name the files, tests, contracts, docs, or search commands the implementer reads first; why those reads matter; and which files are edited after. This keeps execution grounded in current repo state and reduces build-from-memory drift.
 
 4. **Partition tasks and files MECE**: Use one grouping dimension per level (domain, layer, workflow, bounded context, adapter, or test surface). Every changed file gets exactly one owner; every required behavior, state, migration, test, and user-facing surface gets an owner.
 5. **Define subagent integration points**: Where do agents need to coordinate? Where must outputs be tested together? Record interface contracts and checkpoints for every boundary.
@@ -50,6 +54,7 @@
 
 **Optimization checklist** (review the plan for these before proceeding):
 - Can more tasks run in parallel? Unnecessary sequential bottlenecks?
+- Does planned fan-out fit `references/resource-aware-execution.md` — token-led for cloud, CPU-led for local, measured usage before T-shirt fallback?
 - Can subagent context be smaller? Shared reads that should be done once?
 - Missing dependencies, interface mismatches, env assumptions?
 - Changes that could conflict with each other (oscillation risk)?
@@ -58,6 +63,9 @@
 - Define coordination checkpoints where subagents must sync
 - UI/API/data choices that add options, mocks, or complexity without user value?
 - UI plans missing input/output coverage, state coverage, modality fallbacks, validation/security layers, or schema/API traceability?
+- Missing capability gap rows: any target behavior without a current source of truth, named gap, owner, and validation?
+- Missing single-shot guardrails: known failure modes without enforceable evidence/tests?
+- Missing read-before-edit entries: any implementation chunk whose required current-state reads are implicit?
 - MECE gaps or overlaps: unowned responsibilities, shared file ownership, or mixed grouping dimensions?
 - Boundaries that are too tight, too broad, or missing a stable interface?
 - If the plan chooses a simpler/integrated path over modularity, is there a documented `MODULARITY EXCEPTION`?

package/skills/build-loop/references/phase-3-execute.md

@@ -8,15 +8,18 @@
 
 **Goal**: Implement the plan using parallel subagents where possible.
 
+0. **External-source gate** — when a chunk's plan entry names an external repository, vendored tree, or unfamiliar library as the source of its APPROACH (`adapts` / `ports` / `vendors` / `mirrors`), load `Skill("build-loop:repository-intelligence")` and scan the pinned source BEFORE dispatch. Pin repo, branch or tag, and `git rev-parse HEAD` into the implementer brief alongside the portable concepts and each concept's evidence state (`source-confirmed` / `issue-reported` / `inferred`). An `inferred` concept may not carry a load-bearing design decision. Set `triggers.externalSourceAdaptation` so Review-D grades the diff against the same SHA. Ordinary dependency use does NOT fire this: calling a package's documented API is `api-registry` / Context7 territory, and the distinction is whether you read someone else's source to decide your own structure. The skill is read-only and never executes the source, so the gate costs a scan rather than a build.
 1. **Use `subagent-driven-development`** — dispatch subagents per task
-2. **Model assignment**: Default implementer `model: sonnet`, `effort: high` (`xhigh` on hard/code-heavy chunks — Sonnet 5's coding gains land at high/xhigh, claude-api T1). Consult `Skill("build-loop:model-tiering")` for task-specific defaults and escalation triggers
-3. **Parallel agents** where dependency graph allows. build-loop dispatches up to `effective_max` parallel subagents, where `effective_max = scripts/parallelism.py effective_max_implementers(workdir)` — machine-aware (default 8; `min(config.parallelism.maxImplementers, cpu_count−2, hard ceiling 12)`). Decompose the plan into as many independent MECE chunks as the dependency graph allows so the wider fan-out is filled; dispatch in batches via `plan_batches()` when chunk count exceeds `effective_max`.
+2. **Model assignment**: Resolve each agent through `scripts/resolve_agent_model.py <agent> --workdir "$PWD" --json`. Use its supported `preferred_effort` unless an explicit dispatch effort overrides it. Start Sonnet/Terra execution at `high`; use `xhigh` only after a verifier establishes a quality miss, and `max` only after a controlled comparison shows material gain. Haiku has no effort control: keep it bounded and escalate the model when necessary. Consult `Skill("build-loop:model-tiering")` for task-specific defaults and escalation triggers.
+3. **Resource-aware parallel agents** where the dependency graph allows. Load `references/resource-aware-execution.md`, resolve the concrete model, then call `autonomy_supervisor.py fanout` with independent-item count, shared-session capacity, provider/location, output-size, effort, and live signals. Persist the capacity and admission envelopes at `state.json.execution.fanout`; dispatch no more than `admission.next_concurrency`. Cloud inference is token-led; local inference is CPU-led. Both retain MECE, shared-capacity, live backpressure, and the absolute ceiling of 150. Batch with `plan_batches()` when chunk count exceeds the result.
 
    **Maximize parallel-safe chunks**: the partition should expose the maximum number of independent chunks (one file-owner each) so fan-out scales to the available `effective_max`. Serializing parallelizable work requires a `parallel_skipped_reason:` entry in the plan record.
 
    **MECE pre-dispatch gate (NEW)**: before fanning out, validate the partition is *mutually exclusive* — `python3 scripts/parallelism.py --check-partition <{agent:[owned_paths]} JSON>` (exit 1 + overlap report if any file is claimed by >1 agent). A non-empty overlap means two writers would race the shared worktree — fix the partition (or give the overlapping agent `isolation:"worktree"`) before dispatch. Complements `brief_mece_validator.py` (which checks a single brief *has* the seven ownership fields) by checking they are disjoint *across* the fan-out — closing the file-race / fan-out scope-blindness class.
 4. **Each agent gets**: minimal context + clear integration contract + relevant doc context for external APIs + the intent packet from `.build-loop/intent.md` + the MECE ownership packet from the plan (`owns`, `does not own`, `interface contract`, `integration checkpoint`, `allowed tools`, `denied tools`, `acceptance criteria`)
 
+   **Bounded context**: capture the assembled brief once, then pass file pointers instead of copying shared document bodies. Use the resolved model's `prompting_profile`. Fan-out is inappropriate for sequential or cross-cutting work when repeated brief cost exceeds the concurrency benefit.
+
    **`acceptance criteria` (7th field)**: the testable conditions the returning envelope must satisfy — a per-chunk oracle the verifier reads instead of re-deriving one from the diff. Linted by `scripts/brief_mece_validator.py`; a write-handoff brief missing it now lints invalid. *Recovery-path was deliberately rejected as an 8th field — recovery stays centralized in the orchestrator's status-routing + stuck-cascade, not duplicated per handoff.*
 4a. **Implementers do NOT commit** (NEW 2026-05-07 — single-writer git contract). Implementers modify the working tree and return `files_changed` + `commit_subject` + `commit_body` in their envelope. The orchestrator commits sequentially after each parallel batch returns: `git add -- <files>` + `git commit -m <subject> -m <body>`, one implementer at a time through the pre-commit hook. This prevents the parallel-commit race that lost 3 of 4 commits in example-app round 3 (2026-05-07). See `agents/build-orchestrator.md` §"Phase 3 commit step" for the full procedure.
 4b. **Halt-and-ask backstop for architectural-class decisions** (NEW — C5). When an implementer encounters a synthesis-class decision NOT in the plan's `synthesis_dimensions` AND it's architectural-class (where a phase lives, defensive contract shape, error-propagation policy, persistence boundary, hard-fail counters), the implementer returns `status: "blocked"` with the decision in `novel_decisions[]` and does NOT commit. The orchestrator dispatches each blocked decision to the configured Thinking-tier resolver (per `references/model-tier-mapping.md` — never a hardcoded model name), persists resolutions to `state.json.novelDecisionResolutions[]`, and re-dispatches the implementer with resolutions appended to its brief. Hard-fail counter N=3 per chunk; exhausted chunks surface as ❓ Unfixed in Review-F. C3's attestation lint and C4's synthesis-critic still cover what they can grade — C5 catches what falls outside both. Full procedure: `agents/build-orchestrator.md` §"Phase 3 halt-and-ask branch".

package/skills/build-loop/references/phase-4-review.md

@@ -15,15 +15,32 @@ Review runs every time we need an evaluation (initial post-Execute, and again af
 Catch scope drift, patch-over-root-cause, missed edge cases, and rubric violations before spending tokens on full validation. Uses a separate read-only agent with no incentive to sandbag.
 
 0. **Quality-gate trigger profile (QM v0.13.0, single source of truth — F4)**: run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/review_trigger.py --context .build-loop/state.json $(git diff --name-only origin/main..HEAD | sed 's/^/--changed-file /') --json`. The returned `{independent_review_required, cross_vendor_required, reasons}` is the **single source** for when adversarial/cross-vendor review fires — don't invent separate heuristics. Triggers cover `riskSurfaceChange`, architecture-boundary crossing, new dependency/runtime, auth/file/network/persistence/security/model-tool changes, and low-confidence critic output.
-1. **Dispatch `independent-auditor`** at `scope: "build"` against the full build diff (`<pre_build_sha>..HEAD`). Consolidated 2026-05-23 — single source of truth replacing both retired `commit-auditor` (chunk + build scope) and earlier retired `sonnet-critic`. The auditor has tools=[Read, Grep, Glob, Bash] (Bash for `git diff`), no Edit/Write. For Phase 3 step 7 (per-chunk advisory), dispatch the same `independent-auditor` with `diff_sha_range: <chunk_parent_sha>..<chunk_sha>` and `reason: "chunk-advisory"`. **Cross-vendor (QM v0.13.0)**: when the profile sets `cross_vendor_required` and a peer host is reachable (rally channel / `codex exec`), fan out a second-vendor reviewer in parallel and reconcile by severity+evidence; if no peer host can execute, record `cross_vendor: untested` — never claim it ran (per host-agent-is-the-LLM, this is the host's peer, not a vendored API call).
+1. **Dispatch `independent-auditor`** at `scope: "build"` against the full build diff (`<pre_build_sha>..HEAD`). Consolidated 2026-05-23 — single source of truth replacing both retired `commit-auditor` (chunk + build scope) and earlier retired `sonnet-critic`. The auditor has tools=[Read, Grep, Glob, Bash] (Bash for `git diff`), no Edit/Write.
+
+   **Dispatch the auditor CONTAINED (Lever 5, 2026-08-07).** Pass `isolation: "worktree"` to the Agent tool, and brief the auditor that every git call routes through `python3 scripts/audit_git.py <args>` — a refuse-by-default read-only front door — with bare `git` prohibited. `tools: [...]` without `Edit`/`Write` declares read-only; it does not enforce it, because `Bash` carries the whole write surface. Observed in TruePace: this agent ran `git checkout -- website/public/styles.css` mid-audit and destroyed an implementer's uncommitted work, then reported the destruction as its own finding. Nothing was lost only because the work was re-applied by hand — the second collision in one session that isolation would have prevented. Worktree isolation contains the blast radius; the front door blocks the command class. Ship both; neither substitutes for the other. For Phase 3 step 7 (per-chunk advisory), dispatch the same `independent-auditor` with `diff_sha_range: <chunk_parent_sha>..<chunk_sha>` and `reason: "chunk-advisory"`. **Cross-vendor (QM v0.13.0)**: when the profile sets `cross_vendor_required` and a peer host is reachable (rally channel / `codex exec`), fan out a second-vendor reviewer in parallel and reconcile by severity+evidence; if no peer host can execute, record `cross_vendor: untested` — never claim it ran (per host-agent-is-the-LLM, this is the host's peer, not a vendored API call).
 
    **Auditor dispatch ladder & parent-dispatch contract (GAP-1 — the LLM auditor is never silently skipped).** Dispatching `independent-auditor` via `Agent(subagent_type=...)` requires the Agent tool. A *nested* orchestrator — one dispatched as a subagent (`Agent(subagent_type="build-loop:build-orchestrator")`, Mode B) or running per-commit mode — does **not** have the Agent tool, because the harness blocks sub-subagents. The historical failure (2026-06-06 IBR retro, 4+ runs): the nested orchestrator silently substituted inline self-reasoning and reported it as "independent-auditor ran inline", rubber-stamping a HIGH cookie-leak + 2 MEDIUM findings a real dispatch later caught. To make that impossible, walk this ladder and record `auditor_status` honestly:
 
    1. **Agent tool present** (top-level / Mode A) → dispatch `independent-auditor` at build scope as above → `auditor_status: ran:dispatched-agent`.
    2. **No Agent tool, peer host reachable** → run the auditor as a **peer process** over the same channel the cross-vendor reviewer uses (rally channel handoff / `codex exec <prompt>` — reachable because the orchestrator retains Bash even when nested). Reconcile the peer's JSON envelope into `.build-loop/judge-decisions.json` with `judge_id: "independent-auditor"` (a real, cross-host verdict that satisfies the `write_run_entry --scope build` gate honestly) → `auditor_status: ran:peer-host(<host>)`. Prefer this over the not-run signal whenever a peer host can execute.
-   3. **Neither reachable** → `auditor_status: not-run:parent-must-dispatch` (or `cross-vendor-deferred` when a peer host exists but cannot execute this pass). Then, **all of**: (a) do NOT write any `judge_id` containing `independent-auditor` for inline self-reasoning — *inline self-audit is not the independent auditor*, and a mislabeled record would defeat the gate; (b) do NOT report a `scope=build` code-touching run as a review-complete `pass` — use `outcome: partial`; (c) surface `auditor_status: not-run:parent-must-dispatch` in the orchestrator's return envelope.
+   3. **Neither reachable** → `auditor_status: not-run:parent-must-dispatch` (or `cross-vendor-deferred` when a peer host exists but cannot execute this pass). Then, **all of**: (a) do NOT write any `judge_id` containing `independent-auditor` for inline self-reasoning — *inline self-audit is not the independent auditor*, and a mislabeled record would defeat the gate; (b) do NOT report a `scope=build` code-touching run as a review-complete `pass` — use `outcome: partial`; (c) surface `auditor_status: not-run:parent-must-dispatch` in the orchestrator's return envelope; **(d) WRITE THE OWED-VERIFICATION MANIFEST** — `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/owed_verification.py write --workdir "$PWD" --run-id "<run_id>" --diff-range "<pre_build_sha>..HEAD" --owe independent-auditor [--owe plan-critic] [--owe security-reviewer] --json`. This writes `.build-loop/owed-verification.json` (owed list + the exact `Agent(...)` dispatch command per verifier) and flips `state.json.review_incomplete = true`. Step (d) is what makes the parent-dispatch contract a MECHANISM instead of a note the parent might forget: the manifest survives in `.build-loop/` and `owed_verification.py check` is a gate the parent's Report step reads.
+
+   **Parent-dispatch contract (machine-checkable).** A run or commit whose envelope carries `auditor_status: not-run:parent-must-dispatch` (or `cross-vendor-deferred`) — equivalently, one for which `owed_verification.py check` reports `status: incomplete` — is **NOT review-complete**. The dispatching parent — the top-level session that *does* have the Agent tool (the `/build-loop:run` skill body, or the human-driving session) — MUST, on receiving such an envelope: (1) `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/owed_verification.py check --workdir "$PWD" --json` to read the owed list + per-verifier dispatch commands; (2) for each owed verifier, dispatch it (`Agent(subagent_type="build-loop:independent-auditor")` on the run's diff range `<pre_build_sha>..HEAD`, plus `plan-critic` / `security-reviewer` when owed) and append its verdict to `.build-loop/judge-decisions.json`; (3) `owed_verification.py clear --verifier <name>` (or `--all`) for each — the last clear removes the manifest and flips `review_incomplete` back to `false`; (4) re-run `write_run_entry --scope build` so the review-completeness gate passes, and only then finalize Report. Two structural backstops now bind: the manifest (`owed_verification.py check` exit 1 on any owed verifier) AND the existing `write_run_entry --scope build` `review_completeness_error` → exit 3 on a `pass`+`scope=build`+files-touched run lacking a real auditor verdict. Neither can be satisfied by an honest nested orchestrator, which is what forces the parent to finish the audit instead of shipping un-audited code. Helper + tests: `scripts/owed_verification.py` / `scripts/test_owed_verification.py`.
+   **Hostile-input closure gate — when a commit closes a security/safety finding (Lever 3, 2026-08-07).** A guard's test must contain the finding's literal hostile input, and a planted mutant disabling the guard must turn it red. Both are executable, both must pass before the finding is `closed`:
+
+   ```bash
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/hostile_input_gate.py check \
+       --hostile-input "<the finding's literal hostile_input>" --test-file <test path> --json
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/hostile_input_gate.py mutate \
+       --guard-file <path> --guard-symbol <fn> --test-cmd "<test command>" --json
+   ```
+
+   Exit 1 on `check` = `hostile_input_absent` (the test does not contain the attack) or `hostile_input_weak_match_only` (it contains only a path-segment match). Exit 1 on `mutate` = `mutant_survived`: the tests stay green with the guard disabled, so they never exercised it. Exit 2 on `mutate` = `baseline_red`, `mutant_run_timeout`, or `isolation_setup_failed` — a run that could not be observed is not a pass. Any of these means the finding is not closed regardless of how green the suite is; record the real state rather than the verdict.
+
+   `matched_via` names the tier that matched (`literal` / `normalized` / `distinctive_token`) and only the first two close a finding — the weak tier is gated because the original incident's own three-branch test would have scored as covered on a `Application Support` segment match. `--accept-weak-match` is the explicit, off-by-default override. `mutate` plants the mutant in a `git checkout-index` materialization of the index, never in the live checkout (`isolated: true`), so a killed run cannot strand a disabled guard on disk where a concurrent `git add` would stage it.
+
+   `security-reviewer` findings now carry a mandatory `hostile_input` field — the literal argv/path/payload, not a description of the class — which is exactly the string this gate consumes. Observed: a guard written to refuse writing to a user's live store shipped with a test asserting three adjacent things (in-repo target refused, default-with-flag-absent refused, outside path returns absolute), all of which already passed. It never called the function with the live store as an explicit argument — the attack the finding named. The guard required its flag only on the branch where the path was omitted, so naming the path walked past it, and the shipped code wrote 49 entries into the real store. A test written by reading the implementation enumerates the branches that exist; a test written from the threat asks what the attacker types.
 
-   **Parent-dispatch contract.** A run or commit whose envelope carries `auditor_status: not-run:parent-must-dispatch` (or `cross-vendor-deferred`) is **NOT review-complete**. The dispatching parent — the top-level session that *does* have the Agent tool (the `/build-loop:run` skill body, or the human-driving session) — MUST, on receiving such an envelope: (1) dispatch `Agent(subagent_type="build-loop:independent-auditor")` on the run's diff range (`<pre_build_sha>..HEAD`); (2) append its verdict to `.build-loop/judge-decisions.json`; (3) re-run `write_run_entry --scope build` so the review-completeness gate passes, and only then finalize Report. The existing gate (`scripts/write_run_entry`, `review_completeness_error` → exit 3 on a `pass` + `scope=build` + files-touched run lacking a real auditor verdict) is the structural backstop: it cannot be satisfied by an honest nested orchestrator, which is what forces the parent to finish the audit instead of shipping un-audited code.
 2. **Input**: the rubric from `.build-loop/goal.md` + the implementer's diff (`git diff HEAD~1` or the changed-file set).
 3. **Output**: JSON envelope with `verdict` ∈ {yay, nay, suggest_correction, look_again} + normalized `findings[]` (`severity: critical|high|medium|low`). See `agents/independent-auditor.md` for the full schema.
 4. **Routing** (QM v0.13.0 normalized severities; legacy `major→high`, `minor→medium`, `info→low`):
@@ -58,6 +75,8 @@ Catch scope drift, patch-over-root-cause, missed edge cases, and rubric violatio
 
 Test every criterion from Assess with evidence.
 
+**Keep validation bounded.** Default graders, smokes, and functional checks to quick runs (seconds–minutes) — most are fast. Escalate to a long-running test only when a radical or unexpected result genuinely needs more time to characterize, and note that in the Review-G report rather than silently running long. A bounded live check that catches what a mocked/green suite hides (e.g. a real-osascript smoke over a mocked unit test) outranks a long run that adds no signal.
+
 **UI validation — build-loop-owned route** (`uiTarget != null`): dispatch `ui-validator` first, then run the static design-rule scanner and UI input/output contract check. Build-loop does not auto-route to IBR for validation. If the user explicitly requested IBR, treat that as a manual auxiliary validator and keep its findings out of the default gate order.
 
 **UI validation fallback**: paste `fallbacks.md#web-ui` into the validation subagent prompt when `ui-validator` cannot render the route. The fallback contains 10 specific grep checks (Gestalt violations, touch targets, missing handlers, missing aria-labels, status-pill anti-patterns, off-token colors, non-8pt spacing, console leftovers, mock data) plus a file-check matrix for landmarks, focus styles, and viewport tags. Findings get `⚠️ static-analysis only — browser/simulator evidence unavailable` in the Review-G report. This is the standalone UI validation path — degraded vs rendered validation, but not silent.
@@ -78,6 +97,19 @@ design-rule scan     → must-fix=0 pass/fail (uiTarget != null only)
 ui io contract       → pass/fail (uiTarget != null only)
 ```
 
+**Perturbation spot-check (advisory, WARN-only — outcome-based graders on a risk-surface change)**: an outcome-only grader (a test/assertion whose whole signal is pass/fail) can be Goodharted — a gamed or overfit implementation passes the check without satisfying the rule, and a plain pass/fail oracle cannot see it (arXiv:2606.09863 false-success; RLVR obfuscated-enumeration arXiv:2604.15149). When a grader above is **outcome-based** (test/assertion pass/fail, not a structural/lint check) AND `triggers.riskSurfaceChange` is set, re-run that grader once under an isomorphic perturbation and record whether the pass/fail flips:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/perturbation_spotcheck.py" \
+    --check-cmd "<the grader command, with {input} where the changed source path goes>" \
+    --input "<changed source file under this outcome gate>" \
+    --mode rename            # rename identifiers; use --mode reorder for order-independent inputs
+```
+
+The check exits 0 by contract (WARN-only — **it never blocks the build or routes to Iterate**; omit `--strict`). A legitimate outcome check is invariant under an isomorphic perturbation, so a **flip** (`WARN: pass flipped under …`) is an advisory signal the oracle may be gamed/overfit — record it in the Review-G `## Notes from judges` as `perturbation_spotcheck: WARN (<perturbation> flipped) — inspect the oracle` and let the operator judge; a clean run records `perturbation_spotcheck: clean`. Skip entirely when no outcome-based grader ran, or when `triggers.riskSurfaceChange` is unset.
+
+**Safety-boundary guard test — mutation-verify (any change touching a never-X / safety-boundary guard)**: when the diff adds or changes a guard that enforces a safety invariant — a "never modify X" / "never delete Y" / "reject a path outside Z" boundary (e.g. an `isSidecarPath` write-fence, a path allowlist, a destructive-op gate) — the guard's test MUST import and exercise the SHIPPED guard, never a copy of its logic pasted into the test. A test that asserts against its own duplicate of the guard passes even when the shipped guard is broken to `return true` (observed: an Obsidian plugin's sole never-modify-`writing/` guard had a test that re-implemented the guard, so it stayed 20/0 green when the real guard was mutated to always-allow — a test that cannot fail blocks nothing). Then mutation-verify it: flip the shipped guard to the unsafe verdict, re-run only that test, confirm it now FAILS, restore. A guard test that stays green against a broken guard is a fake test — treat it as a Validate failure (route to Iterate: import the real guard, then re-mutation-verify). **How** (one line): flip the guard's return in place → re-run its test → expect red → `git checkout -- <guard-file>`. Memory: `feedback_verify_test_validity_by_mutation`. No new script/agent — the rule + memory are the mechanism; a deterministic mutation-runner is a possible follow-up, not built here.
+
 **Design-rule scan** (when `uiTarget != null`):
 ```
 node "${CLAUDE_PLUGIN_ROOT}/skills/build-loop/scanners/audit-design-rules.mjs" --root=<project> --platform=<swiftui|react|web> --json
@@ -148,7 +180,7 @@ Per-criterion `gate_verdict`:
 - `WEAK_SIGNAL` → note reference in the Iterate plan, investigate normally
 - `NO_MATCH` → standard Iterate fallthrough; store at sub-step G Report for future learning
 
-The memory gate is always on. Build-loop bundles native debugging-memory skills and file-backed search/store, with standalone Coding Debugger available only as an optional cross-project memory plugin when explicitly installed. If structured memory is unavailable, the orchestrator falls through to the local-grep fallback. The strict direct-apply triple-gate spec lives in `skills/debugging-memory/SKILL.md` §"Direct-apply gate (strict)".
+The memory gate is always on. Build Loop bundles the debugger core and reads and writes the same project-local `.claude/memory/` store through `bin/build-loop-debugger.js`; no standalone package or MCP server is required. The strict direct-apply triple-gate spec lives in `skills/debugging-memory/references/search.md`.
 
 **Output**: per-criterion pass/fail with evidence. Any `fail` → Iterate. All `pass` → sub-step C.
 
@@ -171,12 +203,14 @@ Metric-driven autonomous optimization using Karpathy's autoresearch pattern. Opt
 Nothing false, fabricated, or placeholder reaches the user. Three gates, run in parallel. Load `phases/fact-check.md` for detailed guidance.
 
 - **Gate 1 — Fact Checker**: Trace every rendered %, $, score, count, or assessment to its data source. Flag "always", "never", "100%", "guaranteed" — replace with accurate language unless genuinely absolute. Every rendered metric needs a traceable path: source → transformation → display.
+- **Gate 1b — External-source adaptation** (fires on `triggers.externalSourceAdaptation`): load `Skill("build-loop:repository-intelligence")` and grade the diff against the SHA Phase 3 pinned. Two questions the other gates do not ask. **Concept or implementation?** The skill's contract is reuse of concepts and interfaces, not copied implementation; a diff reproducing an external file's structure line-for-line is a finding even when it compiles and passes tests. **License fit?** Check the source's license against this repo's — a permissive license removes an objection, it is not evidence the implementation fits. Also confirm no `inferred` concept from the Phase 3 scan became load-bearing without promotion to `source-confirmed`. WARN by default; BLOCK on an incompatible license, or on copied implementation whose license requires attribution this repo does not carry.
 - **Gate 2 — Mock/Privacy Data Scanner**: Run via `mock-scanner`. Lightweight scan of production code paths and public release/package surfaces for residual mock/placeholder data and private data leaks — hardcoded fake data, placeholder text, faker/random in display paths, stubs replacing real implementations, live-looking API keys/secrets, absolute local paths, private vault/wiki/session paths, persona/profile exports, customer/user lists, resumes, calendars, private notes, transcripts, hostnames, Rally runtime logs, worktree bundles, and other personal or machine-specific data. Exclude test files, dev-only code, and clearly synthetic documentation examples.
-- **Gate 3 — Architectural Violation Check**: invoke `Skill("build-loop:architecture-rules")` (no plugin gate — the native skill no-ops cleanly when `.navgator/architecture/index.json` is absent). Executes `navgator rules --json` and classifies blocking (`circular-dependency`, `layer-violation`, `database-isolation`, `frontend-direct-db` at error) vs warning (`hotspot`, `high-fan-out`, `orphan`). Flags recurrences against `.navgator/lessons/lessons.json`. For cross-layer changes, escalate to `Skill("build-loop:architecture-review")` for the full integrity review.
+- **Gate 2b — Memory/Resource Leak Scanner** (only when the diff touches long-lived runtime code — a daemon, service, server, registry, app-lifetime controller, or stream/parser path): run via `leak-scanner`. Lifecycle accounting: every acquire site (insert/register/spawn/open/subscribe/buffer) must have a release path that fires on the real input, including the uncooperative case. Core checks: unbounded collections fed by external input (memory AND the disk/inode/fd sprawl the same client-controlled key drives), terminal-only eviction predicates (the *terminal* set ≠ the *evictable* set — sweeps must age stale non-active entries), idempotency maps with no forget-point, registration without deregistration, retain/Arc cycles, spawn-without-reap (per-session helpers need session-end cleanup, a single-instance guard, or orphan self-exit), unclosed handles/sessions, and uncapped stream buffer accumulation (enumerate ALL entry forms and accumulating states — a cap on one introducer/sub-code is a false cap). **Scan the whole long-lived surface, not only changed lines** — the highest-value leaks are often pre-existing siblings of the changed code (a second unbounded map in the same registry), so the scanner sets `preexisting` per finding. Routing mirrors Gate 5: **new-content** blocking findings (introduced by this diff) require an `adversary_move` and route to **Iterate**; **pre-existing** blocking findings log to `.build-loop/issues/` with a break-what-if note (user decides scope — do not block the current build on a leak the diff did not introduce). For any eviction fix, honor the finding's `recovery_safe` flag: an eviction that is not recovery-safe (drops correctness state — sequence counters, cursors, dedup keys — with no rehydration path) must pair eviction with rehydration or bound a different way. Warnings go to Report.
+- **Gate 3 — Architectural Violation Check**: invoke `Skill("build-loop:architecture-rules")` (no plugin gate — the native skill no-ops cleanly when `.navgator/architecture/index.json` is absent). Executes `navgator rules --json` and classifies blocking (`circular-dependency`, `layer-violation`, `database-isolation`, `frontend-direct-db` at error) vs warning (`hotspot`, `high-fan-out`, `orphan`, `shallow_module`). Flags recurrences against `.navgator/lessons/lessons.json`. For cross-layer changes, escalate to `Skill("build-loop:architecture-review")` for the full integrity review. **`shallow_module` findings** (from the `architecture-scout` `review-rules` envelope or the native `rules` engine — a thin pass-through with high fan-out and low fan-in) are surfaced in the Report `## Notes from judges` as advisory design guidance ("consider deepening `<component>` behind a narrower interface"); they are WARN-only and never route to Iterate.
 - **Gate 4 — Plugin Cache Sync Check** (only when `pluginWork: true`): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check_cache_sync.py --host claude --source <plugin-source-repo>` for Claude runtime surfaces. If the build changes Codex-visible surfaces (`.codex-plugin/`, `AGENTS.md`, `README.md`, `skills/`, or `commands/`), also run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check_cache_sync.py --host codex --source <plugin-source-repo>`. `[DIVERGED]`, `[MISSING IN CACHE]`, or stale installed Codex versions are **blocking** when they affect the host being used — runtime invocations will hit stale or missing files. Fix with `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/sync_plugin_cache.py --source <plugin-source-repo> --host <claude|codex|all>`, which syncs committed `HEAD` by default; use `--dirty --file <path>` only for explicit temporary runtime testing. Defer version bumps until the feature batch is declared complete (see Gate 6). Missing cache with no installed version skips silently (user has not installed the plugin, nothing to break).
 - **Gate 5 — Design-Rule Scanner** (only when `uiTarget != null`): run `audit-design-rules.mjs` across full project (broader than Sub-step B's changed-files scope). Surfaces any pre-existing must-fix violations newly observable due to scanner rule additions. Pre-existing findings on first run are logged to `.build-loop/issues/` with break-what-if analysis (user decides scope). New-content findings are blocking. See `phases/ui-validation.md` for tuning.
 - **Gate 5a — UI Input/Output Contract Scan** (only when `uiTarget != null`): walk the full rendered surface touched by the build and trace every input/output against `## UI Input/Output Contract`. Flag user-visible data without a component mapping, validation layer, state branch, or source trace. New-content gaps are blocking; pre-existing gaps are logged to `.build-loop/issues/` with user impact and recommended follow-up.
-- **Gate 6 — Version-Bump Advisor** (only when `pluginWork: true`): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/version_advisor.py --workdir "$PWD"`. Default state is `hold` — emits a one-line note in Review-F: `"N commits accumulated since vX.Y.Z. Holding version. Create .build-loop/release-pending.md when the batch is ready."` Switches to `suggest` only when `.build-loop/release-pending.md` exists; in `suggest` mode, Review-F proposes `vA.B.C` (semver inferred from Conventional Commits) and asks for explicit user confirmation before any plugin.json edit. Never auto-bumps. Never blocks. The marker file is the user's release signal; build-loop only ever advises.
+- **Gate 6 — Version-Bump Advisor** (only when `pluginWork: true`): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/version_advisor.py --workdir "$PWD"`. Default state is `hold` — emits a one-line note in Review-F: `"N commits accumulated since vX.Y.Z. Holding version. Create .build-loop/release-pending.md when the batch is ready."` Switches to `suggest` only when `.build-loop/release-pending.md` exists. The marker may declare `bump: minor` or `bump: major`; absent or invalid declarations default to patch because one push is one release. Review-F surfaces `breaking_commits` for the release author's decision and asks for explicit user confirmation before any plugin.json edit. Never auto-bumps. Never blocks.
 - **Gate 7 — UX Triage** (only when `uiTarget != null`): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ux_triage.py --workdir "$PWD" --clear`. Static-scans for four dimensions — interactability, performance, data-accuracy beyond current scope, usability — across the full project (not just changed files). Each `blocker` or `major` finding becomes a queue entry in `.build-loop/ux-queue/<id>.md` with a complete fix plan, evidence, files-touched, and an `architecture_impact` flag. Minor findings stay in the Review-F report only. The agent layer augments static findings with `performance-assessor` and `fact-checker` agent dispatches against the same surface for dimensions the static scanner can't fully cover. Queue entries feed into Phase 5 Iterate (see "Iterate input contract" below). Never block the current build — UX rot fixes ride along, they don't gate.
 - **Gate 8 — UI Coverage-Gap** (only when `uiTarget != null`): compare changed surfaces against existing project test files and the UI input/output contract. If a changed critical surface has no interaction/render coverage, add a queue entry to `.build-loop/ux-queue/` with `dimension: test-coverage` and a proposed repo-native test plan. Build-loop does not auto-draft `.ibr-test.json` files.
 - **Gate 9 — README Currency** (every build; generic, not plugin-only): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/readme_currency_check.py --workdir "$PWD" --diff-range <pre_build_sha>..HEAD --json`. If the run changed a user-facing surface (a command, skill, agent, or CLI/`bin` entry per `readmeCurrency.surfaceGlobs`) but touched no README/`AGENTS.md` (`readmeCurrency.readmePaths`), it emits `verdict: warn` naming the undocumented surface. **WARN-only, never blocks** (advisory per the hook charter; exit 0 always) — surfaced in the Review-F report so the doc is updated before the batch ships. Skips cleanly when no surface changed, when disabled (`readmeCurrency.enabled: false`), or when no diff range resolves. Distinct from Gate 4 (which checks README↔plugin-cache *sync*, plugin repos only); this checks README *content currency* in any repo. Config + defaults: `.build-loop/config.json > readmeCurrency`; gate + tests: `scripts/readme_currency_check.py` / `scripts/test_readme_currency_check.py`.
@@ -267,6 +301,7 @@ Final report sections, in this order:
 - `## Done` — every verified pass + every Auto-Resolve `auto` item, with one-line evidence each. **Lead outcome-first** (`output-style.md` §"Outcome framing"): the report's headline and substance lead with what the user can now do / what stops failing / what no longer needs a manual step, not the feature or mechanism that delivers it; mechanism, file paths, and design detail stay in the progressive-disclosure detail below the lead.
 - `## Held` — items Auto-Resolve verdicted as `confirm`, with the `reason` field from `autonomy_gate.py` quoted verbatim. The user may run any held command manually if they want to. Build-loop does NOT prompt or auto-execute these.
 - `## Blocked` — items Auto-Resolve verdicted as `block`, same shape as Held.
+- `## Findings disposition` — MANDATORY every run (constitution `C-FINDINGS`). Table `| Finding | Source | State | Record |`, one row per finding surfaced from any source (Review A/B/D graders, lint, type-check, scanners, failing or skipped tests, deprecations, contract drift). `State` is exactly one of `fixed` / `waived` / `escalated`; `Record` is the commit sha, a `.build-loop/waivers/<ID>.md` (or decision) path, or a backlog / Operations Center id. Zero findings → header plus `_(no findings surfaced this run)_`; never omit the section, because omission and "nothing found" must not look alike. "Pre-existing" is provenance, not a state — an unchanged-by-this-commit warning still needs one of the three. Waivers are checked and written with `python3 scripts/waivers.py check|new`, always carry an expiry, and default to re-surfacing when their covered file next changes. Scope bounds what a run FIXES, never what it RECORDS: an out-of-scope finding takes the `escalated` row, never omission.
 - `## Status markers` — ✅ Known / ⚠️ Untested / ❓ Unfixed (existing convention; keep this section).
 
 Research citation gate: before emitting, read
@@ -320,7 +355,38 @@ If a category is empty (no Held items, no Blocked items), omit the section entir
 
 Write scorecard to `.build-loop/evals/YYYY-MM-DD-<topic>-scorecard.md`.
 
-**Debugger store + outcome**: for each resolved Review-B/Iterate failure, write a native `.build-loop/issues/<incident>.md` incident note with `{symptom, root_cause, fix, tags, files}`. If `availablePlugins.codingDebugger` is true and the run explicitly requested cross-project memory, mirror the same outcome to standalone Coding Debugger. Both sides of the memory feedback loop — local store and outcome status — are required for learning.
+**Groundwork implementation-map return (blocking when Phase 1 accepted a
+request).** Write `.build-loop/groundwork-evidence.json` with exactly
+`mappings`, `evidence`, and `deviations`. Map only request target IDs. Every
+`implemented`/`verified` mapping names both existing repository-relative files
+and real commits; every `verified` mapping references passing test/runtime evidence;
+every passed evidence row names an existing repository-relative `artifactPath`
+under `.build-loop/evidence/` whose bytes the adapter hashes. A passed row is
+not trusted merely because the draft says `outcome: passed`: include one
+`--verified-evidence-id` per evidence ID whose command Review-B actually ran
+successfully. Then run:
+
+```bash
+request="${GROUNDWORK_BUILD_REQUEST:-$PWD/.designdoc/build-request.json}"
+spec="${GROUNDWORK_SPEC:-$(dirname "$request")/spec.json}"
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/groundwork_exchange.py" emit-map \
+  --request "$request" --spec "$spec" \
+  --evidence "$PWD/.build-loop/groundwork-evidence.json" \
+  --workdir "$PWD" --output "$(dirname "$request")/implementation-map.json" \
+  --producer-version auto --created-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --verified-evidence-id "<id-from-Review-B>"
+```
+
+Any non-zero adapter exit routes to Iterate; contract and operational failures
+return structured JSON with exit 2. Review-G cannot pass with stale bindings, unsafe
+paths, missing commits/artifacts, unsupported targets, or a `verified` status
+without passing evidence. Repeat `--verified-evidence-id` for each passed
+receipt; never grant it to an unexecuted, stale, or user-supplied assertion.
+Report the output digest and path. Build Loop never
+writes Groundwork convergence or mutates `spec.json`; Groundwork independently
+validates the map and calculates `groundwork.convergence/v1`.
+
+**Debugger store + retrieval check**: for each resolved Review-B/Iterate failure, invoke `build-loop:debugging-memory` `{op:"store"}` with `{symptom, root_cause, fix, verification, tags, files_changed}`. Then search the symptom again and confirm the stored incident is discoverable from the same `.claude/memory/` root.
 
 **Orphan scan**: invoke `Skill("build-loop:architecture-dead")` — runs `navgator dead`, diffs against the Phase 1 Assess baseline, surfaces ONLY new orphans introduced this build. No-ops cleanly when `.navgator/architecture/index.json` is absent.
 
@@ -334,8 +400,19 @@ python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deployment_policy.py" \
 
 Follow the returned `action`: `auto` may proceed after Review passes; `confirm` requires an explicit user confirmation in chat before running the command; `block` must not run and should be reported as a configured repo policy. Defaults favor speed for preview/TestFlight and safety for production/unknown.
 
-**Auto-version-bump (LAST step before push/merge for plugin-bearing repos)**: when `plugin.json` (or `.claude-plugin/plugin.json`) exists at repo root AND `git diff --name-only origin/main..HEAD` includes any path outside `docs/`, `tests/`, `*.md`: bump the patch segment of `plugin.json:version`; mirror the new version into every locally-known `.claude-plugin/marketplace.json` (search `~/dev/git-folder/`, `~/.claude/plugins/marketplaces/`) entry referencing this plugin; commit `chore(version): bump <plugin-name> to <new-version>`. No minor/major bumps; no bumps for docs-only diffs.
+**Auto-version-bump (LAST step before push/merge for plugin-bearing repos)**: when `plugin.json` (or `.claude-plugin/plugin.json`) exists at repo root AND `git diff --name-only origin/main..HEAD` includes any path outside `docs/`, `tests/`, `*.md`: bump the patch segment of `plugin.json:version`; mirror the new version into every locally-known `.claude-plugin/marketplace.json` (search sibling checkouts under your dev root, if any, and `~/.claude/plugins/marketplaces/`) entry referencing this plugin — no sibling dev root or no matching entries is `(none found)`, not an error; commit `chore(version): bump <plugin-name> to <new-version>`. No minor/major bumps; no bumps for docs-only diffs.
 
 **Post-deploy verification gate (after a deploy actually ran)**: once a deploy executed — i.e. the deployment policy gate returned `auto` and the deploy/push command ran, or the pushed branch auto-deploys via Vercel — invoke `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/verify_deploy.py --workdir "$PWD" --changed-route <route> [--changed-route <route> ...] --json`. The script detects a Vercel link (`.vercel/project.json` or `vercel.json`), resolves the latest production deployment, polls `vercel inspect` to a terminal state, then probes the prod root + each changed route. `pass` proceeds; `fail` routes to Iterate using the envelope's `findings` as the rubric; `skipped` (no Vercel link, CLI missing, not authed, or other transient infra) records `deploy_verify: skipped (<reason>)` in Review-F and proceeds. An auth-gated `401`/`403` on a protected route is **healthy** (function deployed and running) — only a `5xx`/build-error is a real failure. Never block the build on infra. See `agents/build-orchestrator.md` §"Review: Post-deploy verification gate" for the routing rules and `fallbacks.md#web-deploy-verify` for the inline degraded procedure.
 
 **Append a run entry to `.build-loop/state.json.runs[]`** for Learn (Phase 6) to scan. The orchestrator agent owns the invocation — see `agents/build-orchestrator.md` §G for the canonical call (including `--judge-decisions-json` and `--budget-summary-json`). Schema and flags are owned by `scripts/write_run_entry/__main__.py --help`; do not hand-write JSON.
+
+**Run-close assertion (MANDATORY every Phase 4G — run record and Learn receipt are verified, not assumed).** After `write_run_entry` and Phase 6 complete, assert both mutations landed:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/run_close_lint.py" \
+  --workdir "$PWD" --run-id "<run_id>" --require-orchestrator --require-learn --json
+```
+
+Exit 0 (`status: recorded`) → proceed. Exit 1 means the report waits: `missing`/`floor_only`/`no_state` describe run-record failures; `learn_missing` means the runner, receipt, state summary, or agent attestations are incomplete. Run the returned remediation, then re-run the lint.
+
+Why this exists as a separate read rather than another clause inside the writer: the `runs[]` write already carried a "MUST fire on every Phase 4G regardless of dispatch path" rule and a `--scope build` review-completeness gate, and both are inside the write path, so both stay silent on **non-invocation** — the one failure mode observed on 2026-07-16, when six sequential dispatched orchestrators each returned a quality report and wrote no run record, retrospective, milestone, or feedback entry, starving Phase 6 Learn of a six-run day. A gate inside the script cannot fire when nobody runs the script, so the assertion reads durable state instead. The matching half is the dispatching parent's check at the completion boundary (`references/verify-dispatch.md` §6) — Review-G catches a write that failed, the parent catches an orchestrator that never reached Review-G. Contract locked by `scripts/test_run_close_lint.py`; lesson: `build-loop-memory/lessons/2026-07-17-lesson-dispatched-orchestrator-writes-no-run-records.md`.