@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/build-loop/references/phase-5-iterate.md

@@ -10,6 +10,16 @@
 
 Entered when Review sub-step A, B, or D finds blocking issues OR `.build-loop/ux-queue/` is non-empty. Critic-only failures (strong-checkpoint from A without touching B) route to Execute instead — no iteration counter burn.
 
+**Bounded admission at first entry.** Snapshot pre-existing, intent-aligned queue
+work once with `python3 scripts/autonomy_supervisor.py --workdir "$PWD" snapshot
+--goal "<intent>" --limit <configured-or-12>`. Schedule only paths in
+`.build-loop/autonomy/queue-manifest.json`; later queue arrivals wait for the
+next manifest. An issue discovered while executing the current work is handled
+separately: run `classify-related` and execute it in this run when the verdict is
+`execute` (intent-aligned, inside the repo, reversible, and deterministically
+testable). `followup` writes a durable item. `decision` names why the owner is
+needed, available choices, and owner/app/user/other impact.
+
 **Iterate input contract (prioritized work list)**:
 
 | Priority | Source | Notes |
@@ -23,25 +33,61 @@ Entered when Review sub-step A, B, or D finds blocking issues OR `.build-loop/ux
 
 The "code is cheap, AI agents build fast" framing: the orchestrator does NOT defer based on patch size. It defers only when `architecture_impact: true` (new component, new data flow, navigation graph change, schema migration, auth provider swap). Everything else is fair game for the current loop.
 
+## Premise re-validation gate (MANDATORY before scheduling any queue item)
+
+A queue item is written at one moment and executed at another. By the time it surfaces, the bug may be fixed, the file moved, or the precondition false. Before scheduling any item drained from `.build-loop/queue/`, `.build-loop/issues/`, `.build-loop/ux-queue/`, or `.build-loop/followup/`:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/premise_revalidation.py" gate --item <path> --repo "$PWD" --json
+```
+
+Exit 0 = `fresh`, schedule it. Exit 1 = do not schedule; route by `reason_code`:
+
+| Verdict | Meaning | Route |
+|---|---|---|
+| `fresh` | Within the window, or re-validated with evidence | Schedule |
+| `stale_needs_revalidation` | Past the window (default 7d), never re-checked | Re-check the premise against the live repo, then `validate --note "<what you checked>"`; if it has resolved, close the item with that receipt |
+| `premise_broken` | A cited path or commit the item depends on is genuinely gone | Close the item with the receipt; do not implement |
+| `needs_human_recheck` | A cited path **relocated** (same basename elsewhere), or extraction was ambiguous | Re-read the item against the new path before acting |
+
+Freshness falls back to `created` when `validated` is absent, so an item filed minutes ago is fresh by construction — the gate cannot deadlock a queue fed by the current run. Stamp freshness only through:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/premise_revalidation.py" validate --item <path> --note "<evidence>"
+```
+
+`--note` is required. A bare timestamp asserts freshness without evidence, which is the failure being fixed.
+
+**Why `needs_human_recheck` is a separate verdict from `premise_broken`.** 2026-08-07: a sweep of 67 queue cards found 16 (24%) whose premise had already resolved — one claimed 65 commits were stranded by a push blocker that had cleared two days earlier. Several card specs even carried hand-written *"VALIDATE FIRST (mandatory) … if stale, write a receipt and STOP"* prose, which proves the need was known and unautomated. The sharper finding: **the careful human sweep was itself stale** — it reported a file as deleted when the file had been relocated, and a repo as 0 ahead when it was 6. A missing path is therefore never enough to declare a premise dead; the gate checks for a same-basename relocation first and asks for a human re-read instead of concluding. Staleness is also repo-dependent (one repo measured 4/4 stale, another 12 live to 1 stale), so the gate is per-item, never a blanket policy.
+
+Mirrors the Operations Center design (`validated_at` + refusal at the same gate that already refuses an unrunnable card, commit `3fd0a23`) rather than reinventing it.
+
 **Fan-out** (mode-dependent): After dequeue, partition entries by `files_touched` into independent groups (no overlapping files).
 
+Before each fan-out and after a provider/worker error, run
+`autonomy_supervisor.py backpressure --signals '<json>'`. Feed available 429
+count, memory percentage, free disk, thermal state, error streak, cost use and
+ceiling, current concurrency, and stable-window count. Obey `pause_new_work`,
+`reduce_concurrency`, `steady`, or `recover_one`; finish in-flight chunks before
+reducing admission. Missing signals retain current concurrency.
+
 - **Top-level mode** (orchestrator invoked directly via the user's session): dispatch up to 4 `implementer` subagents in parallel via `Agent(subagent_type="build-loop:implementer", ...)` per the bundled `agents/implementer.md` (Sonnet 5, scoped tools=[Read, Write, Edit, Bash, Glob, Grep]). Hard cap from `~/.claude/CLAUDE.md` §Sub-Agents. Sequential groups process after the parallel batch.
 - **Subagent mode** (orchestrator was itself spawned via `Agent(...)` so the no-sub-sub-agents rule applies): degrade to **inline-implementer mode** — iterate the queue serially, apply each fix following the implementer's protocol (scope to `files_touched`, refuse `architecture_impact: true`, verify locally before declaring fixed). No parallelism, same quality bar. The orchestrator surfaces the degradation in Review-F.
 
 In both modes, each pass returns the same structured outcome (status + files_changed + verifications). Status routing covers all 9 implementer return values:
 - `fixed` → mark done (delete the .md)
 - `partial` → keep entry, re-pass next iteration
-- `scope_breach` → ask user before extending scope
+- `scope_breach` → re-plan automatically when the added files remain inside the authorized repo and resolve to the current intent; otherwise route through `classify-related`
 - `deferred_architecture` → Review-F surfaces for explicit user confirmation
 - `evidence_stale` → regenerate via `ux_triage.py --clear`, then re-pass
 - `plan_malformed` → same as `evidence_stale` (regenerate); log id to `.build-loop/state.json.malformedPlans[]`
-- `needs_dependency` → ask user; never auto-add deps
-- `failed` → re-pass with implementer's `notes` as `additional_context`; after 2 attempts escalate to Opus per `model-tiering`; after 3 surface as ❓ Unfixed
+- `needs_dependency` → classify the concrete dependency change with `classify_action.py`; SAFE/RISKY follows its normal branch route, while DECISION/PRODUCTION surfaces with impact
+- `failed` → re-pass with implementer's `notes` as `additional_context`; after 2 attempts escalate per `model-tiering`; after 3 identical verdicts quarantine and continue
 - `concurrent_modification_detected` → abort current parallel batch (orchestrator partition bug; never transient)
 
 Results re-enter Sub-step B for re-validation. For Validate failures (no queue entry), construct an inline plan in the same shape and treat identically.
 
-**UI re-validate hook (when uiTarget != null)**: After each implementer subagent reports back AND before re-entering Sub-step B Validate, the orchestrator runs the build-loop-owned UI re-validate path for affected surfaces: `ui-validator` for web routes when resolvable, native AX driver for macOS, or simulator screenshot/interaction commands for iOS. Catches "fix introduced a new visual or interaction regression" cheaply, without burning a full Validate cycle. If no renderable surface can be resolved, record the gap and fall back to `audit-design-rules.mjs`. IBR is not invoked unless the user explicitly requested it for this build.
+**UI re-validate hook (when uiTarget != null)**: After each implementer subagent reports back AND before re-entering Sub-step B Validate, invoke headless IBR for affected renderable surfaces when installed, following `../../../references/ibr-ui-verification-policy.md`. Run `ui-validator` in parallel for web, with native AX or simulator/browser evidence as the fallback. If no renderable surface can be resolved, record the gap and fall back to `audit-design-rules.mjs`.
 
 **Infra self-heal before counting an attempt (C-HEAL / self_heal_safe_issues).** When an Iterate attempt's own tooling, hook, or Bash command FAILS (infra error — non-zero exit that is not a graded-criterion failure, e.g. a pre-commit hook crash, a lint runner that throws on a binary file, a script that errors on a missing env var): ROOT-CAUSE and FIX that infra error first. Classify via `scripts/classify_action.py`. SAFE → apply, verify (re-run the failed action), commit, then resume the Iterate attempt. RISKY/DECISION/PRODUCTION → isolate/surface per the normal routing table. An infra self-heal does NOT burn the iterate budget; only a graded-criterion failure (test/lint/validate failure against the rubric) burns a count. This prevents `--no-verify` bypasses and other workarounds from masking fixable infra errors.
 
@@ -53,17 +99,39 @@ Per attempt:
    - **2 consecutive same-root-cause failures** → parallel multi-domain assessment via `build-loop:debugging-memory` `{op:"assess"}`. Pass `model: sonnet` to domain assessors explicitly (override `inherit` default to prevent 4× Opus fan-out from the Opus 4.7 orchestrator). The full procedure is documented in `skills/debug-loop/SKILL.md` §"If stuck — parallel multi-domain assessment".
    - **3 consecutive same-criterion failures** → causal-tree investigation via `Skill("build-loop:debug-loop")`. Runs its own 7-phase cycle internally; returns with fix applied or hard-stop.
 3. **Build the prioritized work list** from the table above (Validate failures + UX queue).
-4. **Partition for parallel fan-out**: group by disjoint `files_touched`; dispatch ≤4 subagents in parallel.
+4. **Partition for parallel fan-out**: group by disjoint `files_touched`; use `autonomy_supervisor.py fanout` for the binding dynamic admission count. The absolute ceiling is 150, while independent work, shared capacity, provider errors, cost, memory, disk, load, latency, and measured thermal stability normally set a lower limit.
 5. **Execute fixes**; for UI files, run the UI re-validate hook before continuing.
 6. **Loop back to Review sub-step B** (Validate). Sub-step A (Critic) usually skipped on re-runs unless the fix touched new files. Sub-steps C-F run only on final pass.
+   - When the completed queue file has `source: autonomy-dashboard`, read its
+     `dashboard_gap_id` and record the validated completion before advancing:
+     `python3 scripts/autonomy_dashboard.py --workdir "$PWD" --complete
+     "<dashboard_gap_id>" --summary "<what changed>" --evidence
+     "commit:<sha>; tests:<result>; audit:<verdict>"`. This moves the file out
+     of the executable follow-up queue and makes the dashboard show `Applied`.
 7. **Followup overflow**: when the iteration cap (5) is reached and queue entries remain, write them to `.build-loop/followup/<topic>.md` for a subsequent `/build-loop:run` invocation. Plan content is already complete — the followup build skips its own Plan phase for these entries.
    - **`judgment-owed-<run-id>.md`** entries (written by `stop_closeout` when a stakes-gated inline run closed at the inline floor) mean: **dispatch the owed verification layer(s) named in the file for that run** (the Frontier auditor/advisor it skipped), then the file is cleared automatically on the next passing Stop. Do not treat it as a code work-item — it is a dispatch-the-judgment debt.
 8. **Track**: attempt count, what failed, what was attempted, what changed, queue depth before/after each pass.
 
+After every item outcome, enforce the per-item limit:
+
+```bash
+python3 scripts/autonomy_supervisor.py --workdir "$PWD" verdict \
+  --item "<stable-item-id>" --verdict "<verdict>" --limit 5 --audit-at 3 \
+  --actor-id "<worker-id>" --actor-session "<worker-session-id>"
+```
+
+`action: independent_audit` dispatches a different worker/session. The orchestrator first
+records the returned `verify` action in the current run's agent ledger with
+`refs.item_id` and `refs.session_id`, then records its evidence with
+`autonomy_supervisor.py audit --item <stable-item-id> --evidence <evidence>
+--auditor-id <auditor-id> --auditor-session <auditor-session-id>`. Only then may the
+fourth attempt start. `action: quarantine` moves the item to follow-up with all five
+verdict receipts and continues the manifest. A resolved verdict resets the counter.
+
 **Convergence detection**:
-- Same criterion fails 2x with same root cause → escalate to user
-- Fix A breaks criterion B (oscillation) → flag and ask user
-- 3+ criteria fail simultaneously after a fix → systemic issue, stop and reassess
+- Same criterion fails 2x with the same root cause → invoke the causal-tree re-plan; the third identical unresolved verdict requires an independent audit, and the fifth quarantines the item
+- Fix A breaks criterion B (oscillation) → revert the weaker reversible fix, re-plan once, then quarantine on recurrence
+- 3+ criteria fail simultaneously after a fix → treat as one systemic issue, re-plan from the shared cause, and continue unaffected manifest items
 
 **Stop condition (QM v0.13.0 — severity-aware, replaces the blunt 5-cap for critical/high)**. The 5-iteration cap still bounds the loop, but it **cannot finalize with an open `critical` or `high` finding** (the no-critical/high exit gate in Review-G, `review_finding_gate.py`, blocks the final pass). On reaching the cap:
 - **Open `critical`/`high` remain** → do NOT silently ship as ❓ Unfixed. Escalate to the user with the blocking findings and their `closure_proof` gaps; the build does not pass until they close or the user explicitly waives. (If the same approach keeps failing, re-plan instead of burning more iterations.)

package/skills/build-loop/references/phase-6-learn.md

@@ -6,30 +6,21 @@
 
 ## Phase 6: Learn — Cross-Build Pattern Detection (mandatory; always runs and always reports)
 
+**One executable path:** `python3 scripts/learn/__main__.py run --workdir "$PWD" --run-id <recorded-run-id> --source review-g --json`. It writes `.build-loop/learn/<run-id>.json`, updates `runs[].learn`, and returns durable `work_orders[]` for agent-only drafting/review. Dispatch those roles and attach results with the CLI's `attest` command. `status: complete` is the only completed Phase 6 state.
+
 **Goal**: detect recurring patterns across recent runs, auto-draft experimental skills/agents to address them, surface them for keep/remove decisions. Closes the loop between "build N times" and "build N+1 is faster because we learned."
 
 **Load the `build-loop:self-improve` skill for the full protocol.** (Skill keeps its existing name for backward compatibility; this phase was named "Self-Improvement Review" in v0.2.0 — renamed here to avoid collision with Phase 4 Review.)
 
-**Mandatory contract (v0.30.0+).** Every Phase 6 always does three things: (a) dispatches the Haiku detector (cheap), (b) runs `consolidate_memory.py` + `procedural_governance.py --mode detect-patterns` (already unconditional), and (c) emits a `## Learn` outcome line in the Review-G report — even when nothing crosses threshold. Net marginal cost over the prior gated path is one cheap Haiku state-scan per run. The expensive arm (Sonnet draft + Opus signoff) stays conditional on `runs[] >= 3` AND a pattern crossing threshold AND not-deferred. Also user-invokable via `/build-loop:self-improve` to run a scan without a build.
+**Mandatory contract (v0.39.0+).** Every Phase 6 runs the deterministic detector and consolidation stages, persists their receipt, and emits its `learn_line` in Review-G. This path uses no LLM when nothing crosses threshold. Sonnet drafting and promotion review stay conditional and appear as explicit work orders. Also user-invokable via `/build-loop:self-improve` after recording a manual run id.
 
 Quick flow:
 
-1. **Detect** — dispatch `recurring-pattern-detector` (Haiku). Reads **two signal sources**:
-   - **Signal 1**: `.build-loop/state.json.runs[]` — emits `phase_failure`, `manual_intervention`, and `security_finding` patterns (real pain signals; `diagnostic_repeat` and `file_churn` were removed to prevent skill sprawl). **`runs[]` is written by the orchestrator's Review-G, so an INLINE run (skill-as-methodology, no orchestrator dispatch) records nothing and is invisible to Learn.** Any run-close path that did not go through Review-G — inline runs, the memory closeout — MUST record the run with `python3 scripts/append_run.py --workdir "$PWD" --run-id <id> --goal "..." --outcome <done|partial|blocked> [--manual-intervention "<phase>:<note>"] [--phase "<id>:<status>"]` (append-only, idempotent on `run_id`). Without it, inline work never accrues toward the `runs[] >= 3` threshold and recurring inline pain (e.g. the user re-prompting for a skipped step) never becomes a `manual_intervention` pattern.
-   - **Signal 2**: `.build-loop/proposals/enforce-from-retro/*.md` (the post-push retrospective's enforce-candidates) — emits `enforce_recurrence` patterns when the same normalized candidate signature appears across ≥ 2 distinct run-ids. The orchestrator may cite `python3 scripts/enforce_retro_signals.py --workdir "$PWD" --json` as pre-computed input to the agent. This delivers "anything prompted/needed repeatedly → enforce" **across** sessions, not just within one.
-2. **Filter** — keep only `confidence: high` or `count >= 4`; manual interventions at lower threshold. Dedupe against existing active/experimental skill names. Cap 2 artifacts per scan.
-3. **Draft** — for each kept pattern, dispatch `self-improvement-architect` (Sonnet). Writes to `.build-loop/skills/experimental/<name>/SKILL.md` with an A/B Experiment section including `run_id` and `co_applied_experimental_artifacts[]` schema.
-4. **Signoff** — orchestrator (Opus 4.7) reviews each draft: APPROVE / REVISE (1 retry) / DISCARD.
-5. **Sample review sweep** — for artifacts in `.build-loop/skills/experimental/` from prior runs: if `.build-loop/config.json.autoPromote` is true AND effective (non-confounded) sample ≥ 8 AND target met → eligible for promotion. **Promotion is no longer silent.** Each eligible candidate goes through (a) advisory review by `promotion-reviewer` (Opus, agent), (b) async user confirmation via PushNotification + TaskCreate fallback. The reviewer's variance verdict (approve / rethink / new_approach) becomes the body of the notification. Move from `experimental/` to `active/` happens only after the user confirms via `/build-loop:promote-experiment <name>`. Regressions and inconclusive-at-2N write proposals to `.build-loop/proposals/` for user confirmation — never auto-delete.
-
-   **Promotion-reviewer dispatch protocol** (per advisory-judge design, plan §12 / `agents/promotion-reviewer.md`):
-   - For each eligible candidate, dispatch `Agent(subagent_type="build-loop:promotion-reviewer", ...)` with brief fields: `artifact_path`, `experiment_log`, `sample_size`, `target_metric`, `triggering_run_id`, `recent_judge_decisions`.
-   - Append the returned verdict object to the run's `judge_decisions[]` via `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry/__main__.py --judge-decisions-json <verdict.json>` (combined with other Phase 4 verdicts if any).
-   - Compose the user-facing notification body from the verdict's `variances[]` and `meta_guidance`. Fire `PushNotification` if available; fall back to `TaskCreate` with subject `"[BUILD-LOOP] Promotion candidate <name>: <verdict> — review needed"`.
-   - Write a marker file at `.build-loop/proposals/<name>.pending.md` with the verdict + how-to-confirm so the user can resume context later (TTL 14 days; lapsed candidates auto-archive to `.build-loop/proposals/<name>.lapsed.md`).
-   - **Do not move the artifact.** The user-invoked `/build-loop:promote-experiment <name>` command performs the move after reading the pending verdict.
-
-6. **Notify** — concise synthesis appended to Review sub-step G report, including: (a) removal command for each artifact moved or proposed, (b) for each pending promotion: the reviewer verdict + confirmation command.
+1. **Run** — the executable runner reads four bounded sources: `runs[]`, retro enforce-candidates, learning objects, and tool traces. It consolidates memory, detects and deduplicates patterns, caps new work at two, and performs the sample sweep.
+2. **Read** — no patterns means no agent dispatch. Agent-only work appears in `work_orders[]` with the exact role and payload.
+3. **Dispatch** — call only returned roles. Architects draft experimental skills or agents. Implementers realize enforcement specifications. Promotion reviewers judge drafted or sample-eligible artifacts.
+4. **Attest** — attach repository-relative artifacts and reviewer verdicts with the CLI. Pending or failed work keeps Phase 6 open.
+5. **Close** — emit `learn_line`, enforce `run_close_lint.py --require-learn`, and leave promotion to explicit `/build-loop:promote-experiment` confirmation.
 
 **Always-run + report gating (v0.30.0)**
 
@@ -52,6 +43,8 @@ Phase 6 has NO "skip entirely" condition. Three outcome states cover every run:
 
 - Consumer default — learned drafts route to `~/.build-loop-extensions/pending/` via `scripts/extensions_route.py --name <ext-slug> --file <draft>`; they do not load until `scripts/extensions_approve.py` moves them into `plugin/`. (Maintainer routing: P2.)
 
+**Retrospective finding capture — ownership (2026-08-29).** build-loop is the DEFAULT owner of the retrospective-finding-filing flow (`scripts/retrospective/file_findings.py`; see `AGENTS.md` §"Retrospective finding capture" for the exact `plan`/`apply`/`lint` commands and filing ladder). The `ai-assistant` and `ambient agent` projects may also invoke or guide this same flow, but only through those same `file_findings.py` commands — never a parallel reimplementation. This pointer lives in build-loop's own docs only: `ai-assistant` and `ambient agent` are NOT edited by this change.
+
 **What this phase will NOT do**:
 - Modify the build-loop plugin repo
 - Promote artifacts cross-project without explicit `/build-loop:promote-experiment <name>`

package/skills/build-loop/references/privileged-request-broker.md

@@ -0,0 +1,254 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Privileged-request broker — naming, coalescing, and recording admin prompts
+
+Load this when a build touches a command that asks macOS for an administrator
+password, when a user reports unexplained password dialogs, or when changing
+`scripts/privileged_commands.json`.
+
+Scope: RUNTIME privileged requests across concurrent agent tasks. The separate
+background-item identity work — giving persistent login items recognizable names
+— is a different problem and is untouched here.
+
+---
+
+## The incident this exists for
+
+**2026-08-20, 01:29:11 and 01:29:25 PDT.** A Codex task ran `sfltool dumpbtm`
+twice. macOS showed two administrator-password dialogs naming only `sfltool` —
+no app, no repository, no reason. Parent chain: ChatGPT/Codex → zsh → sfltool.
+
+Evidence, from `~/.codex/sessions/2026/08/20/`:
+
+| Session | UTC | Command |
+|---|---|---|
+| `01a01e31` | 08:04:07 | `sfltool dumpbtm` (bare, inside a 4-way `Promise.all`) |
+| `01a01e46` | 08:29:11 | `sfltool dumpbtm 2>/dev/null \| rg -n -C 2 '…' \| sed -n '1,260p'` |
+| `01a01e46` | 08:29:25 | `set -o pipefail`⏎`sfltool dumpbtm \| sed -n '1,120p'`⏎`rc=$?` |
+| `01a01e4b` | 08:30:59 | probing where `sfltool` lives (no `dumpbtm`) |
+
+The 08:29 pair share a session AND a `turn_id`. Both returned **empty output**
+after 10.6 s and 30.6 s of wall clock — the time the dialog sat on screen.
+
+### Three separable faults
+
+**1 — Anonymity.** `sfltool dumpbtm` requires root and is **undocumented**:
+`sfltool(1)` describes only `sfltool archive`. macOS names the leaf binary in the
+dialog and nothing else, so the user could not tell which of several concurrent
+agent tasks was asking, or why.
+
+**2 — A failure shaped like a result.** A refused privileged read returns empty
+stdout, which is indistinguishable from "the grep matched nothing". The agent
+could not tell denial from no-results, so it retried 14 seconds later with a
+different wrapper (`set -o pipefail`, `rc=$?`) purely to get diagnostics. **The
+retry was rational.** The second dialog was caused by the first one's outcome
+being unreadable, not by carelessness.
+
+**3 — No shared broker.** Three sessions reached for the same host fact inside
+27 minutes. Nothing coalesced them, named them, or recorded that a prompt
+occurred.
+
+### Baseline, measured
+
+`python3 scripts/privileged_audit.py report` over 4,169 transcript files:
+
+| metric | before | projected |
+|---|---:|---:|
+| privileged invocations | 13 | 13 |
+| OS prompts | 10 | 7 |
+| coalesced | 0 | 3 |
+| retries | 1 | 0 |
+| unattributed | 13 | 0 |
+| distinct requests | 6 | 6 |
+
+`projected` replays the same observed trace through the coalescing rules. It is a
+counterfactual on real input, not a measurement; the measured column fills in from
+the broker's own ledger as traffic routes through it.
+
+---
+
+## What was built
+
+| Piece | File | Job |
+|---|---|---|
+| Registry | `scripts/privileged_commands.json` | Which commands are privileged, their scope, mutability, TTL. Data, not code. |
+| Coordinator | `scripts/privileged_broker.py` | Attribution, single-flight, TTL cache, state machine, hash-chained ledger. |
+| Forensics | `scripts/privileged_audit.py` | Read-only. Reconstructs the baseline from transcripts; before/after counts. |
+| Enforcement | `scripts/hooks/pre_bash_privileged.py` | PreToolUse:Bash gate. Redirects a raw privileged command to the broker. |
+
+---
+
+## Using it
+
+```bash
+# What in this command needs root?
+python3 scripts/privileged_broker.py classify --command "sfltool dumpbtm | head" --json
+
+# Run it through the coordinator. --purpose is MANDATORY.
+python3 scripts/privileged_broker.py request \
+  --purpose "enumerate background-task items to name unlabeled login items" \
+  --task-id "$RUN_ID" --repo "$PWD" --initiating-app "Claude Code" \
+  --argv sfltool dumpbtm
+
+# What is in flight, what is cached, is the ledger intact?
+python3 scripts/privileged_broker.py status --json
+python3 scripts/privileged_broker.py verify-ledger --json
+
+# Cancelled a dialog and now want to allow it? Drop the cached answer.
+# This can only ever CAUSE a prompt, never skip one. An in-flight key is left alone.
+python3 scripts/privileged_broker.py forget --key <key-or-prefix> --json
+
+# Before/after counts.
+python3 scripts/privileged_audit.py report --window 300
+```
+
+Exit codes for `request`: `0` completed · `1` denied/cancelled/timeout/failed ·
+`2` refused by the broker (bad request, password-capture shape, attempt cap).
+
+### What the user sees before the dialog
+
+```
+┌ ADMIN PASSWORD REQUEST ─────────────────────────────────────
+│ macOS is about to ask for your admin password for: sfltool
+│ Who    Codex · task d71397a3 · thread 01a01e46
+│ Where  build-loop (worktree run-864834) · branch main
+│ What   /usr/bin/sfltool dumpbtm
+│ Why    enumerate background-task items to name unlabeled login items
+│ Scope  btm:read · read-only · trust=local-admin
+│ Shared yes — identical read-only requests reuse this for 900s, 2 task(s) waiting
+│ When   2026-08-20T08:29:11Z · request 4f2a…
+└─────────────────────────────────────────────────────────────
+```
+
+---
+
+## The rules
+
+### Coalescing is narrow
+
+Two requests share one authorization only when **all** of these are identical:
+resolved `argv`, `scope`, `trust_domain`, `mutating`, uid, and registry entry.
+Anything different is a different key and inherits nothing.
+
+The identity is the **argv**, not the shell string. That is what makes it work on
+the real incident: `sfltool dumpbtm 2>/dev/null | rg …` and `set -o pipefail`⏎
+`sfltool dumpbtm | sed …` are different strings and the same request.
+
+### Mutating never coalesces
+
+A mutating request gets a private key directory, never reads the cache, never
+writes one. One request, one prompt, no inheritance — in either direction.
+
+### A negative is remembered; a negative is never upgraded
+
+Denial, cancellation, and timeout are cached for `negative_ttl_seconds`
+(default 300 s, 600 s for `sfltool dumpbtm`). During that window an identical
+request is refused **from cache, without a dialog**. This is the control that
+kills the observed retry. A cached terminal state replays verbatim; no branch
+turns a `denied` into a `completed`.
+
+The negative cache must not become a trap, so `forget --key` drops a cached
+answer on demand. It removes an answer; the next request has to earn a new one.
+
+### A cap is a rate limit, never a lockout
+
+When a result ages out and nobody owns the key, the TTL window rolls: the cached
+result and the prompt-attempt counter are cleared **together**. They have to move
+as a unit — a counter that outlived its window would leave a key that once hit
+the cap permanently `denied_exhausted`.
+
+### The password is never touched
+
+macOS performs the authentication. The broker decides who triggers it and shares
+the resulting *output*. It refuses `sudo -S`, `--stdin`, `-A`, `--askpass`, a set
+`SUDO_ASKPASS`, and any `--password=` argument, and never gives the child a piped
+stdin. Nothing password-shaped is ever written to the store.
+
+### A crashed owner cannot strand or storm
+
+The owner heartbeats while the command runs. A waiter whose owner has a stale
+heartbeat **and** a dead pid takes the lease over — once. `max_prompt_attempts`
+(default 2) bounds how many dialogs one key may open in a TTL window; past it the
+key goes terminal as `denied_exhausted` and every waiter gets that answer.
+
+### Ambient observes; Ambient never decides
+
+Durable visibility is `ledger.jsonl` — append-only and hash-chained, so a deleted
+or edited record is detectable (`verify-ledger`). Live visibility is an optional
+`ambient.notify_command` that receives each event on stdin. **The return value is
+discarded and never inspected**, so no Ambient state can approve, deny, terminate,
+or widen a request. A hostile sink is a covered test case.
+
+To surface the event in RossLabs Ambient Agent, run its local daemon and configure
+the broker with its `ambientctl` binary and state directory. The receiver accepts
+only the redacted event on standard input; it records the purpose, requesting app,
+risk class, and broker event id in Ambient activity. It never receives command
+arguments, command output, or a password.
+
+```json
+{
+  "ambient": {
+    "mode": "live",
+    "notify_command": ["/absolute/path/to/ambientctl", "--state-dir", "/absolute/path/to/ambient-state", "systemAccessRequest"],
+    "notify_timeout_seconds": 3
+  }
+}
+```
+
+### Unavailability is never approval
+
+| Risk class | Coordinator unavailable | Ambient unavailable |
+|---|---|---|
+| read-only | proceed **uncoalesced**, attribution still printed, gap receipt written | proceed; gap receipt |
+| mutating | **refuse** — never run a privileged mutation with no record | proceed; gap receipt |
+| unknown | proceed uncoalesced, never coalesce; gap receipt | proceed; gap receipt |
+
+Every receipt carries `unattributed_possible: true`. An empty ledger means *no
+brokered traffic*, never *no privileged request*. `privileged_audit.py` counts
+gaps as `unattributed` for exactly this reason.
+
+---
+
+## Adding a command
+
+Edit `scripts/privileged_commands.json`. Never special-case a command in the
+broker.
+
+```json
+{
+  "id": "sfltool-dumpbtm",
+  "executable": "sfltool",
+  "argv_prefix": ["dumpbtm"],
+  "scope": "btm:read",
+  "mutating": false,
+  "cacheable": true,
+  "ttl_seconds": 900,
+  "negative_ttl_seconds": 600,
+  "confidence": "observed",
+  "notes": "…"
+}
+```
+
+Longest matching `argv_prefix` wins, so `csrutil status` (`"privileged": false`)
+beats the `csrutil` catch-all. Set `"prompts": false` for a privileged command
+that cannot open a dialog (`sudo -n`) — it is still attributed and recorded, just
+never counted as a prompt. `confidence` is one of `observed` (seen prompting here,
+evidence on file), `documented` (vendor/man page says root), `inferred`
+(behaviour follows from the command class; unverified here).
+
+When in doubt, leave `mutating: true`. A read wrongly marked mutating costs one
+extra dialog; a mutation wrongly marked read-only inherits an approval it should
+never have had.
+
+## Known limits
+
+- `prompt_opened` is a **proxy**: the broker counts the times it invoked a
+  privileged command, because it cannot observe SecurityAgent directly.
+- `sudo` keeps its own sudoers timestamp cache, independent of this broker.
+  Consecutive `sudo` calls inside that window may show fewer real dialogs than
+  the baseline counts. The SecurityAgent commands have no such cache.
+- The PreToolUse gate covers **Claude Code Bash calls**. Codex sessions are
+  covered by the `AGENTS.md` protocol, which is instruction-level, not enforced.
+- `ambient.mode` defaults to `ledger-only`; live push stays unconfigured until a
+  `notify_command` is set, and that state is reported once as a coverage gap
+  rather than silently.

package/skills/build-loop/references/resource-aware-execution.md

@@ -0,0 +1,183 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Resource-Aware Execution
+
+This is the canonical token, CPU, execution-profile, and context-conservation
+contract. It is internal. The user still has one Build Loop entry point and no
+resource-mode choices to manage.
+
+## Automatic execution profile
+
+Run `scripts/review_trigger.py` in Assess and again after Plan has concrete file
+and line estimates. Persist the last envelope at
+`state.json.execution.resourceProfile`.
+
+| Profile | Trigger | Required path |
+|---|---|---|
+| `skip` | Small single-file/config change with no risk signal | Execute directly; deterministic validation only; do not start the full loop |
+| `standard` | Multi-file, non-trivial, or 20+ line work with no high-risk signal | One independent auditor, deterministic validation, report, cheap Learn outcome; fact-check/security/simplify only when their signal exists |
+| `high` | Auth, security, network, persistence, architecture, runtime, model/tool, dependency, large-diff, or ambiguous-risk signal | Full Review and cross-vendor review when reachable |
+
+Profiles never bypass production, destructive-delete, secret, security, owed-
+verification, or user-impact gates. A later high-risk signal promotes the run to
+`high`; profiles never demote during a run.
+
+## Resource-aware fan-out
+
+Resolve the concrete model first. Then run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/parallelism.py" \
+  --workdir "$PWD" --model "$MODEL" --provider "$PROVIDER" \
+  --segment "$SEGMENT" --tier "$TIER" \
+  --execution-location "$LOCATION" --output-size "$OUTPUT_SIZE" \
+  --agent implementer \
+  --independent-items "$READY_CHUNKS" --shared-capacity "$SHARED_CAPACITY" \
+  --active-elsewhere "$ACTIVE_ELSEWHERE" --describe --json
+```
+
+Persist the envelope at `state.json.execution.fanout`. `effective_max` is
+capacity, not a dispatch target. Pass it to `autonomy_supervisor.py fanout`;
+the supervisor applies provider/host/cost/failure backpressure and chooses the
+next wave. Dispatch only across a MECE partition. The absolute safety ceiling
+is 150, while every lower live cap remains binding.
+
+The role supplies an advisory effort when `--effort` is omitted. Today
+`agentic_execution/T3` prefers `high`, so Codex execution resolves to Terra-high
+and Claude execution resolves to Sonnet-high. Passing `--effort` remains an
+explicit override.
+
+## Accuracy-first token efficiency
+
+Minimize tokens only among approaches expected to meet the same acceptance
+criteria. Use this order:
+
+1. Run deterministic scripts for repeatable checks, transforms, inventories,
+   and schema validation.
+2. Use keyword or semantic retrieval to narrow source context before any model
+   reads it.
+3. Route bounded scanning and classification to Pattern-tier or local models
+   when a deterministic verifier can judge the output.
+4. Read the relevant implementation and tests before proposing complex code.
+   Early source grounding is cheaper than rework and repeated troubleshooting.
+5. Use measured ledger rows to tune prompts, effort, and fan-out after quality
+   passes. Never count an unmatched or lower-quality run as a token win.
+
+### Adaptive backpressure
+
+- Start with a bounded ramp of at most four workers.
+- Reduce admissions after repeated 429s, worker errors, memory pressure,
+  serious thermal state, low disk, or 80% cost use.
+- Pause new work at critical thermal/memory/disk pressure or the cost ceiling.
+- Recover one worker only after two stable telemetry windows.
+- External cooling changes measured thermal stability; it does not bypass CPU,
+  token, cost, ownership, or provider limits.
+
+Every tool call and result reconciles into
+`.build-loop/telemetry/tool-traces.jsonl` as an OTel-shaped, bounded, redacted
+span. The supervisor consumes error, retry, 429, and latency summaries; Phase 6
+consumes the same signals for recursive learning.
+
+### Synthetic load safety
+
+Never launch an unbounded background CPU loop. Run load-sensitive checks through
+`build-loop-load-probe`, which caps admission, names every worker, gives each
+worker an internal hard deadline, and verifies cleanup:
+
+```bash
+build-loop-load-probe --workers 4 --duration-seconds 30 -- npm test -- --runInBand
+```
+
+The lifecycle receipt contains only a fixed product/purpose, opaque run id, PID
+birth identity, process group, timestamps, and cleanup result. It must never
+contain prompts, URLs, secrets, repository paths, or the wrapped command line.
+Host-wide cleanup may signal a probe only when its owned receipt, PID birth
+identity, process-group identity, marker, and expired deadline all match.
+Unknown or ambiguous processes remain advisory.
+
+### Cloud inference: token-led
+
+1. Use the median measured raw tokens for the same model and agent from the
+   cost ledger when available.
+2. Otherwise use the model/output/effort T-shirt estimate.
+3. Divide the wave token budget by per-worker demand.
+4. Apply configuration, CPU headroom, and hard-ceiling caps as secondary limits.
+
+Default heuristic demand before output/effort multipliers:
+
+| Model size | Typical role | Tokens/worker |
+|---|---|---:|
+| small | Pattern/utility | 8,000 |
+| medium | Code/workhorse | 16,000 |
+| large | Thinking | 24,000 |
+| xlarge | Frontier | 32,000 |
+
+Output multipliers are small `0.5`, medium `1.0`, large `1.75`. Effort
+multipliers are low `0.75`, medium `1.0`, high `1.25`, xhigh `1.75`, max
+`2.25`, ultra `3.0`. These values are routing heuristics, not pricing claims.
+Measured data replaces them automatically.
+
+### Local inference: CPU-led
+
+Local workers reserve CPU according to model size: small `1`, medium `2`, large
+`4`, xlarge `8` cores per worker. The resolver keeps two cores for the lead and
+OS. Token limits apply to local inference only when the caller supplies one;
+local token throughput does not silently override CPU safety.
+
+### Unknown location
+
+Pass the provider/location when known. `auto` recognizes Ollama, MLX, LM Studio,
+llama.cpp, and explicit local adapters. Other models default to cloud so an
+unknown provider receives the conservative token-led path.
+
+## Token telemetry
+
+`cost_ledger_hook.py` always records dispatch identity, run, phase, execution
+location, model/output T-shirt sizes, and a heuristic token estimate. Provider
+adapters enrich the same task id through `write_cost_ledger_row.py` with:
+
+- `input_tokens`
+- `output_tokens`
+- `cache_read_input_tokens`
+- `cache_creation_input_tokens`
+- `phase`, `fanout_limit`, and `fanout_primary_constraint`
+
+Keep measured buckets separate from `tokens_estimate`. Benchmark conclusions
+use measured rows only.
+
+## Bounded context
+
+- Capture each assembled brief once under `.build-loop/briefs/<run>/<chunk>.md`.
+- Pass goal, ownership, interface, acceptance criteria, falsifier, and file
+  pointers. Do not paste full shared documents into every worker.
+- Preserve stable prefixes for provider caching.
+- Use the resolved model's `prompting_profile`; compressed/standard profiles
+  remove repeated examples and rationale while keeping safety and acceptance
+  contracts.
+- Prefer one context for sequential/cross-cutting work. Fan-out must earn its
+  repeated brief cost through genuinely independent chunks.
+
+## Proposal maintenance
+
+Before Phase 6 pattern detection, run the reversible consumer once:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/drain_self_review_proposals.py" \
+  --workdir "$PWD" --archive --stamp "$RUN_ID" --json
+```
+
+This archives superseded, stale, and non-actionable proposals before any model
+reads the queue. It never applies findings and never deletes evidence.
+
+## Benchmark
+
+Use `evals/token-efficiency/tasks.jsonl` as the starter task set. Record results
+for identical task id, repository snapshot, and model, then compare with:
+
+```bash
+python3 scripts/token_efficiency_benchmark.py --results results.jsonl \
+  --baseline current --candidate resource-aware --json
+```
+
+The harness excludes estimates and unmatched tasks from the A/B token claim.
+Quality must remain non-inferior before a token reduction counts as a win.

package/skills/build-loop/references/self-recursive-dev.md

@@ -8,7 +8,7 @@ A run is **self-recursive** when the build-loop working tree IS the loaded runti
 Recommended: pass the working tree directly to Claude Code at session start.
 
 ```sh
-claude --plugin-dir ~/dev/git-folder/build-loop
+claude --plugin-dir <path-to-your-local-checkout>
 ```
 
 `--plugin-dir` takes session precedence over any cached marketplace copy, and Claude Code sets `CLAUDE_PLUGIN_ROOT` to that directory. The detector reads it. No symlink, no `~/.claude/` mutation.
@@ -16,7 +16,7 @@ claude --plugin-dir ~/dev/git-folder/build-loop
 Convenience alias (optional, in `~/.zshrc` or `~/.bashrc`):
 
 ```sh
-alias claude-bl='claude --plugin-dir ~/dev/git-folder/build-loop'
+alias claude-bl='claude --plugin-dir <path-to-your-local-checkout>'
 ```
 
 Use the alias when you intend to dogfood build-loop changes; use plain `claude` for normal work that should run against the released cache version.