@tyroneross/build-loop 0.30.3 → 0.34.0

package/plugin-artifacts/codex/docs/agent-surface-policy.md

@@ -0,0 +1,63 @@
+# Agent Surface Policy
+
+Build Loop keeps one user-facing Codex entrypoint while preserving the richer
+Claude Code skill tree for hosts that can route helpers internally.
+
+## Public Entry Points
+
+Codex must expose exactly one user-facing Build Loop choice:
+
+- `build-loop` — main workflow and router for build, fix, debug, optimize,
+  research, knowledge capture, handoff, and plugin-test work
+
+Claude Code may expose advanced direct overrides in its command/skill surface
+where useful:
+
+- `build-loop`
+- `debug-loop`
+- `optimize`
+- `research`
+- `knowledge`
+- `handoff`
+
+## Host Rules
+
+Codex and ChatGPT install from `plugin-artifacts/codex`, not from the source
+repo root. Codex auto-discovers root `skills/*/SKILL.md` files and manifest
+skill paths supplement that default, so installing the source root leaks every
+internal helper into the picker. The artifact is generated by:
+
+```bash
+python3 scripts/build_codex_plugin_artifact.py --source . --target plugin-artifacts/codex
+```
+
+The artifact contains one `skills/build-loop/SKILL.md` copied from the
+canonical workflow and `.codex-plugin/plugin.json` rewritten to
+`"skills": "./skills"`. It must not contain any other `SKILL.md` files.
+
+The local Codex marketplace (`.agents/plugins/marketplace.json`) points at this
+artifact. Release and marketplace updates must do the same.
+
+Claude Code keeps `.claude-plugin/plugin.json` pointed at `./skills` because
+commands and orchestrator agents load internal skills by qualified name. Helper
+skills must set `user-invocable: false`; the public entrypoints set
+`user-invocable: true`.
+
+Cursor and other AGENTS.md-style tools should treat `AGENTS.md` plus this file
+as the routing contract. Start from `build-loop`. Read helper files under
+`skills/` only when the active entrypoint, a command, or an orchestrator
+instruction explicitly references them.
+
+## Cache Hygiene
+
+Plugin cache pruning is explicit and auditable:
+
+```bash
+npm run codex:sync-cache
+python3 scripts/prune_plugin_cache.py --source . --apply
+```
+
+`npm run codex:sync-cache` rebuilds the slim artifact first, then syncs that
+artifact into the Codex cache. The prune command keeps the current host manifest
+version and deletes older verified cache directories for the same plugin. Use
+`--host codex` or `--host claude` for a single host.

package/plugin-artifacts/codex/references/advisor-dispatch-ladder.md

@@ -0,0 +1,62 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Advisor dispatch ladder (Phase 2 plan synthesis at Frontier)
+
+The Advisor (Fable) is the Frontier standing role that **authors and re-plans** the Phase 2 plan synthesis. Generating a plan is harder than evaluating one, so the deepest reasoning pays here — but the Advisor is **pull-based**: summoned only when stakes-gating trips, not every run. This ladder enforces that the plan is authored at Frontier *when it matters*, without breaking the runs where it doesn't.
+
+It deliberately **mirrors the GAP-1 independent-auditor ladder** (`phase-4-review.md` §"Sub-step A"). Same shape, same honesty discipline, an analogous `advisor_status` field. If you know that ladder, you know this one.
+
+## When the ladder is evaluated (stakes-gating)
+
+The orchestrator walks this ladder at the Phase 2 plan-synthesis step **only when** any of these objective triggers fire:
+
+- `state.json.synthesisDensity > 5` (synthesis-dense plan), or
+- `triggers.riskSurfaceChange` (security/persistence/runtime/deploy/trust boundary), or
+- `stakes >= medium` (from the commander's-intent posture / charter), or
+- an explicit `dispatch_tier: frontier` on any work item in the draft plan.
+
+If none trips, the ladder is skipped entirely — the orchestrator synthesizes the plan inline as today (most runs stay single-context; this respects the multi-agent-handoff risk by not decomposing more than needed). **Triggers are objective signals, never self-reported confidence** (models are systematically overconfident).
+
+## The four rungs (record `advisor_status` honestly)
+
+Dispatching the Advisor via `Agent(subagent_type="build-loop:advisor")` requires the Agent tool. A *nested* orchestrator (dispatched as a subagent — Mode B — or running per-commit mode) does **not** have the Agent tool, because the harness blocks sub-subagents. Walk the ladder and record `advisor_status`:
+
+1. **Rung 0 — own context already Frontier** (the orchestrator is itself running on Fable, e.g. `/build-loop:run` while the session model is Fable): **synthesize the plan inline** — it is *already* Frontier, no handoff needed. → `advisor_status: inline-frontier`. Zero added cost.
+
+2. **Rung 1 — Agent tool present** (top-level / Mode A, own context not already Frontier): **dispatch the Fable Advisor** (`Agent(subagent_type="build-loop:advisor")`) to author/re-plan, then verify via plan-critic + scope-auditor. → `advisor_status: ran:dispatched-agent`.
+
+3. **Rung 2 — no Agent tool, peer host reachable** (nested Mode B, but a peer host — rally channel / `codex exec` — can execute; reachable because the orchestrator retains Bash even when nested): **run the Advisor as a peer process** over the same channel the cross-vendor reviewer uses. Reconcile the peer's plan + envelope into the plan artifact. → `advisor_status: ran:peer-host(<host>)`. Prefer this over the fallback whenever a peer host can execute (fresh-context synthesis is plausibly *higher quality*, not merely cheaper — see "Quality, not only cost" below).
+
+4. **Rung 3 — none reachable** (no Agent tool, no peer host): **synthesize inline on the orchestrator's own model (Opus)**, labeled honestly. → `advisor_status: fallback:inline-opus`.
+
+## Non-breaking guarantee
+
+**Rung 3 IS today's behavior** — the orchestrator synthesizing the plan inline on Opus. The floor of this ladder equals the current state; it is strictly better whenever a dispatch path (Rung 1/2) or an already-Frontier context (Rung 0) is reachable. The handoff cost fires *only* in Rung 1/2 — i.e., only when the active context isn't already Frontier — so you pay it exactly where it buys an upgrade and never where planning is already Frontier. Worst case equals current; there is no regression path.
+
+## Quality, not only cost
+
+Dispatch is a **quality lever**, not just a cost knob. Context-separation evidence (⚠️ 2026 cross-context-review lead, directionally consistent with the corroborated self-correction literature: correction needs *external* feedback; intrinsic self-correction degrades accuracy) indicates synthesis in a *fresh* context beats same-session work. So Rungs 1/2 (fresh-context dispatch) are plausibly *higher quality* than Rung 0/3 inline — inline is a genuine quality compromise, taken only when dispatch is unreachable. The Advisor is a **separate agent**, never the executor self-reflecting.
+
+## Ledger row per Advisor action (the instrument)
+
+The orchestrator (single writer) appends one row to `.build-loop/agent-ledger.jsonl` per Advisor action via `scripts/agent_ledger.py`:
+
+```
+action: author | re-plan
+agent: advisor · tier: frontier · model: <resolved id (fable / gpt-5.x / …)>
+rung: 0|1|2|3 · status: pass|fail|partial · trigger: <synthesisDensity>5 | riskSurfaceChange | stakes>=medium | dispatch_tier:frontier>
+refs: {output: docs/plans/<slug>.md, input: <prior plan / failure evidence>}
+note: <on re-plan: failure evidence + why a retry is justified>
+```
+
+This closes the unmeasured quality-delta: the A/B test reads the ledger to compare plan outcomes by `rung`/`model` and find whether Frontier planning actually pays.
+
+## Re-plan mode (the remediation contract, v1)
+
+When the orchestrator diagnoses a **planning miss** during Iterate (the plan itself no longer fits, on an objective signal — test/build failure, auditor verdict, retry-count, scope breach), it re-enters this ladder with `action: re-plan`. The Advisor reads the **failure evidence + the diff vs the current plan**, diagnoses planning-miss vs execution-miss (*its* Frontier call, never the failing executor's self-report), and on a planning miss issues **corrected instructions** — a diff against the prior plan + the evidence — so execution resumes at the cheap tier on a sound plan.
+
+**v1 scope:** author + re-plan only. The **take-over-execution rung** (the Advisor executing a chunk directly) and **proactive mid-run checkpoint check-ins** are **v2** — land after the A/B confirms the core pays.
+
+## Always verified — never self-certifying
+
+The Advisor's authored/re-planned plan is checked by the existing Frontier critics before any implementer runs: `plan_verify.py` (deterministic) → `plan-critic` (reasoning; **blocking on the same stakes triggers**, advisory otherwise) → `scope-auditor` at the Plan→Execute boundary. Frontier-authored output does not get a pass on review. Keep the verification panel multi-specialist — do not collapse it to a single judge.

package/plugin-artifacts/codex/references/agent-role-taxonomy.md

@@ -0,0 +1,101 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Agent Role Taxonomy
+
+This reference answers two recurring coordination questions:
+
+1. Who is lead?
+2. Is a "coder", "backend", or "database" entity an agent, a skill, or a task role?
+
+Use this doc with `references/model-tier-mapping.md`: this file defines
+responsibility boundaries, while model-tiering defines the model class used for
+each role.
+
+## Binding Rule
+
+The lead is the session holding the current valid Rally Point leadership lease.
+It is not a hardcoded tool name, default UI label, or mock value. If no valid
+lease exists, the first active orchestrator that claims the lease becomes lead
+until it transfers, relinquishes, or expires.
+
+```bash
+python3 scripts/agent_rally.py lead status --workdir "$PWD" --json
+```
+
+When the displayed lead conflicts with the live lease, trust the live lease and
+file the display as a Rally Point bug.
+
+## Roles
+
+| Role | Current surface | Default tier | Owns | Must not own |
+|---|---|---:|---|---|
+| Human/operator | User prompt and explicit gates | n/a | Goal, production push approval, irreversible delete approval, major user-impact decisions | Routine commit cadence, reversible implementation choices |
+| Lead orchestrator | `agents/build-orchestrator.md`; Rally Point leadership lease | Thinking | Run plan, phase transitions, ownership partition, dispatch, final judgment, commits, release/report | Pretending peer handoffs are approval, ignoring stale/off-task peers |
+| Peer host/session | Rally Point presence/inbox/handoff | Host-selected | Its claimed lane, verdicts, handoffs, review requests | Files claimed by another active peer, silent lead takeover |
+| Coder subagent | `agents/implementer.md` | Code | Bounded implementation against owned files and a written spec | Architecture expansion, git staging/commit/push, cross-lane cleanup |
+| Domain assessor | `agents/database-assessor.md`, `api-assessor.md`, `frontend-assessor.md`, `performance-assessor.md` | Code or Thinking by complexity | Diagnosis and evidence in one domain | Shipping code by default; use implementer for the fix |
+| Architecture/scope specialist | `architecture-scout`, `scope-auditor`, architecture skills | Thinking | Blast-radius tracing, caller impact, scope gaps | Applying the fix after finding the gap |
+| Reviewer/auditor | `independent-auditor`, `security-reviewer`, `plan-critic`, `fix-critique`, `synthesis-critic` | Code or Thinking by rubric/judgment mix | Read-only challenge, risk ranking, verdicts | Mutating code under review |
+| UI/design specialist | `design-contract-specialist`, `ui-validator`, `ui-design` skill | Code or Thinking by task | UI contract, visual validation, design direction | Business logic outside the UI contract |
+| Retrospective/learning agent | `retrospective-synthesizer`, `recurring-pattern-detector`, `self-improvement-architect` | Pattern to Thinking | Pattern extraction, proposals, lessons | Silent promotion of new enforcement |
+| Skill | `skills/*/SKILL.md` | n/a | Procedural guidance, routing rules, references, scripts | Acting as a live worker or owner |
+| Script/tool | `scripts/*` | n/a | Deterministic checks, writes, summaries | Making LLM judgment calls unless explicitly wrapped by an agent |
+
+## Coder vs Backend/Database Agent
+
+Build-loop already has a dedicated coder subagent: `implementer`. Do not add a
+separate generic `coder` agent unless evidence shows agents or users repeatedly
+miss that `implementer` is the coding role.
+
+For backend/database work:
+
+1. Use the domain assessor when the problem is diagnostic or cross-layer:
+   `database-assessor`, `api-assessor`, `performance-assessor`, or
+   `assessment-orchestrator`.
+2. Use `implementer` when the fix is scoped to owned files and the "what" is
+   decided.
+3. Escalate to `scope-auditor` or `architecture-scout` when a persistence,
+   schema, API, or data-contract boundary might widen the blast radius.
+
+This keeps roles MECE: assessors diagnose, implementer edits, reviewers judge,
+and the lead orchestrator commits.
+
+## Lead Responsibilities
+
+The lead orchestrator must:
+
+- Claim or verify the leadership lease at Phase 1 and renew it at phase starts.
+- Keep Rally Point status/watch active when peers, inbox items, or an active
+  coord file exist.
+- Write task heartbeats for long-running work and pass `--task-ref` into
+  status/watch.
+- Assign exactly one owner per file/chunk before dispatch.
+- Dispatch subagents by role, not by vague labels like "backend agent" unless
+  the role maps to one of the surfaces above.
+- Remain the single writer to `.git/`; subagents return envelopes, not commits.
+- Decide routine reversible choices under `references/leadership.md`.
+
+## Peer Responsibilities
+
+Every peer host/session must:
+
+- Use a stable `tool` id (`claude_code`, `codex`, `cursor`, etc.).
+- Publish presence and lane ownership before mutating shared files.
+- Read direct and broadcast inbox messages before acting on a handoff preview.
+- Post verdicts or handoffs through Rally Point, not only terminal prose.
+- Use `heartbeat --task-ref` during long-running tasks so other sessions can
+  distinguish "process alive" from "still on task".
+
+## When To Add A New Agent
+
+Add a new agent only when all are true:
+
+1. The task repeats across builds.
+2. The task has a stable input/output envelope.
+3. The responsibility is not already owned by one row above.
+4. A skill or script cannot express the behavior cleanly.
+5. Verification can check the output before the orchestrator accepts it.
+
+If the need is "teach agents how to do X", add or update a skill/reference. If
+the need is "perform X repeatedly with a bounded contract", add an agent. If
+the need is "compute X deterministically", add a script.

package/plugin-artifacts/codex/references/autonomous-and-per-commit-modes.md

@@ -0,0 +1,161 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Autonomous Mode + Per-Commit Mode (conditional detail)
+
+Extracted from `SKILL.md` (WP-A, 2026-06-09): both modes are conditional — their
+tables and contracts are load-bearing only when the mode is active, yet they
+loaded in every session. The SKILL.md body now carries a one-line pointer to
+each; the full detail lives here and loads on demand.
+
+## Autonomous Mode (Queue-Drain Loop)
+
+Autonomous mode generalizes Phase 5 Iterate into a self-replenishing worker that drains its own `ux-queue/` + `issues/` + `proposals/`, alignment-checks each item against the original intent, executes the aligned subset, and commits in batches until the queue is empty or the wall-clock budget elapses. Default since this mode shipped (`--autonomous=false` opts back to classic one-pass).
+
+**End-of-run backlog/issues drain — SHIPPED DEFAULT 2026-06-04**: every run now auto-drains `.build-loop/issues/` then `.build-loop/backlog/` at end-of-thread without asking. Reversible per-repo via `.build-loop/config.json`:
+
+```json
+{ "sessionPrefs": { "continueFromQueues": "never" } }
+```
+
+`PRODUCTION`/`DECISION`-classified items still surface (not auto-executed). The continuation runs the same alignment-checker + scope-auditor + independent-auditor wiring as the in-run iterate loop. Stop conditions: iterate-cap (25 autonomous / 5 classic), budget exhausted, PRODUCTION encountered, 5 consecutive iterate failures, explicit user pause. Surfaced in the run report's `## Queue continuation` section.
+
+### Flag surface
+
+| Invocation | Effect |
+|---|---|
+| `/build-loop:run "goal text"` | default mode, 2h budget, autonomous=true |
+| `/build-loop:run --long "goal text"` | long mode, 8h budget |
+| `/build-loop:run --budget 4h "goal text"` | custom budget (overrides `--long`) |
+| `/build-loop:run --budget 30m "goal text"` | accepts `30s`, `30m`, `4h`, or bare integer seconds |
+| `/build-loop:run --autonomous=false "goal text"` | classic single-pass; queue items become `followup/` |
+| `/build-loop:run "overnight refactor of auth ..."` | keyword `overnight` → long mode, 8h |
+
+**Flag precedence (strict, top wins):**
+
+1. `--budget <duration>` — explicit duration always wins; mode tagged `custom`.
+2. `--long` — sets mode `long`, budget 8h.
+3. Keyword detection in goal text — only when `--long` not explicitly set.
+4. Default — mode `default`, budget 2h, autonomous=true.
+
+`--autonomous=false` is orthogonal: it can combine with any budget flag but disables the queue-drain loop entirely. With autonomous off, `--budget` still tracks wall-clock but the orchestrator runs classic Phase 1–6 once and reports.
+
+### Keyword fallback
+
+Case-insensitive whole-word match against the goal text (or `intent.update_intent`). Detection runs ONLY when `--long` is not explicit on the command line. The flag always wins over keyword inference.
+
+| Keyword | Example phrasings |
+|---|---|
+| `long` | "long refactor of …" |
+| `long-running` | "long-running migration" |
+| `overnight` | "overnight build" |
+| `large-scale` | "large-scale rewrite" |
+| `multi-day` | "multi-day backfill" |
+
+Keyword list is configurable via `.build-loop/config.json.autonomy.keywordsLong[]`. The default list above is hard-coded in the orchestrator.
+
+### Budget tracking
+
+The orchestrator writes `state.execution.budget` at autonomous-mode start:
+
+```json
+{
+  "mode": "default | long | custom",
+  "started_at": "<iso8601 UTC>",
+  "deadline_at": "<iso8601 UTC>",
+  "last_checkin_at": "<iso8601 UTC> | null",
+  "commits_since_push": 0,
+  "checkin_interval_pct": 50
+}
+```
+
+`scripts/budget_check.py` reads this block at every iterate-loop entry, every commit, and every phase boundary, returning a routing envelope (`continue | checkin | finalize_and_stop`). The script is informational — exit 0 always; sub-5ms compute.
+
+**Resume contract**: when a budget block exists and the run resumes via `--resume <run_id>`, the orchestrator MUST reuse the original `deadline_at`. A 2h budget that crashed at 1h59m does NOT get a fresh 2h. `scripts/resume_resolver.py._resolve_budget_on_resume()` is the single source of truth for this rule and surfaces the preserved budget under `budget_resume.preserve_deadline: true`.
+
+### Iteration caps
+
+| Mode | Per-build cap | Per-item cap |
+|---|---|---|
+| Classic (autonomous=false) | 5 | n/a |
+| Autonomous default | 25 | 3 same-verdict |
+| Autonomous long | 25 | 3 same-verdict |
+
+`maxIterateAttemptsAutonomous` is configurable in `.build-loop/config.json.autonomy.maxIterateAttemptsAutonomous`.
+
+### Question timeout (autonomous auto-decide)
+
+In autonomous / `--long` mode a question that would otherwise block on the human auto-resolves if unanswered within a window, so an unattended run never stalls. When the orchestrator surfaces such a question it states a **recommended default** + a deadline; `scripts/question_timeout.py` is consulted (e.g. on a `ScheduleWakeup` resume) and returns `answered | take_default | wait`. On `take_default` the orchestrator takes the recommended option, records it to `state.execution.autonomousDefaults[]` + `auto-decision-capture`, continues, and lists every auto-decided question in the end-of-run readback for override (prefer the reversible option when deciding).
+
+**Never auto-resolves — waits indefinitely:** production push, destructive/irreversible delete, and anything the autonomy gate verdicts `confirm`/`block` (gates #1–#2 in `agents/build-orchestrator.md`). Only reversible / `user_impact: major` decisions (gate #3) and steering clarifications time out — the single production gate is preserved.
+
+Config (`.build-loop/config.json.autonomy`): `questionTimeoutMinutes` (default 10), `onTimeout` (`decide_default` default | `wait`).
+
+### Per-Phase A constraint
+
+Phase A (current ship) wires queue drain + alignment-check + time budget. **Pushes stay manual** — `scripts/autonomous_push.py` and the K-commit batch-push policy ship in Phase B. The `should_push_now` field returned by `budget_check.py` is informational in Phase A; the orchestrator surfaces it in check-ins but does not push autonomously yet.
+
+## Per-Commit Mode (Self-Recursive Builds)
+
+Per-commit mode splits a multi-commit build into one independent orchestrator dispatch per commit, so each commit reviews and lands cleanly before the next one starts. It activates automatically when the working directory IS the runtime — that is, when the user is editing the build-loop plugin itself (or any plugin whose runtime symlink points back to the working tree). It can also be explicitly opted into or out of via skill arguments.
+
+### Detection
+
+Phase 1 Assess writes `selfRecursive.enabled: true|false` to `.build-loop/state.json` (commit 1 wired this via `scripts/detect_self_recursive.py`). The skill body MUST read this field BEFORE deciding which dispatch shape to use. If the field is absent, treat it as `false`.
+
+### Mode Resolution
+
+| Skill arg | `selfRecursive` | Resulting mode |
+|---|---|---|
+| `--per-commit` (explicit) | either | per-commit |
+| `--no-per-commit` (explicit) | either | single-orchestrator |
+| (none) | true | per-commit (default for self-recursive) |
+| (none) | false | single-orchestrator (today's behavior) |
+
+Passing both `--per-commit` and `--no-per-commit` is a user error — fail loud with a one-line message naming the conflict and stop before any dispatch.
+
+### Dispatch Contract (Per-Commit Mode)
+
+1. **Plan first, dispatch many.** The skill body invokes a single planning orchestrator (Phase 1 Assess + Phase 2 Plan only). Its return must include a per-commit work list at `.build-loop/per-commit-plan.json` with this exact JSON shape:
+
+   ```json
+   {
+     "run_id": "run_<UTC>_<hash>",
+     "commits": [
+       {
+         "id": "c1",
+         "subject": "feat(scripts): add foo helper",
+         "scope": "...",
+         "files_planned": ["scripts/foo.py", "tests/test_foo.py"],
+         "spec": "verbatim packet for the implementer orchestrator",
+         "depends_on": []
+       }
+     ],
+     "branch": "feat/...",
+     "from_branch": "main"
+   }
+   ```
+
+2. **Per-commit orchestrator dispatch.** For each commit in the plan (respecting `depends_on`), the skill body dispatches a fresh `Agent(subagent_type="build-loop:build-orchestrator", ...)` carrying ONLY that commit's packet plus a `PER_COMMIT_DISPATCH: { commit_id, run_id, prior_commit_hashes }` prompt prefix. Each dispatched orchestrator runs Phase 3 Execute + Phase 4 Review for ITS commit only, then commits and returns. The dispatched orchestrator's behavior on the prefix is documented in `agents/build-orchestrator.md` §0a.
+
+3. **Aggregate.** The skill body collects each orchestrator's return envelope and writes a final report combining all commits' results. On partial failure (commit N fails), do NOT dispatch downstream commits; retain `.build-loop/per-commit-plan.json` so a subsequent `/build-loop:run --resume` invocation can pick up where it stopped. **Parent-dispatch contract (GAP-1):** the dispatcher (this skill body) HAS the Agent tool, so it is the parent that owes the audit. For every returned envelope whose `auditor_status` is `not-run:parent-must-dispatch` or `cross-vendor-deferred`, the dispatcher MUST — before declaring that commit/run review-complete — dispatch `Agent(subagent_type="build-loop:independent-auditor")` on that commit's diff range, append the verdict to `.build-loop/judge-decisions.json`, and re-run `write_run_entry --scope build` so the review-completeness gate passes. A nested per-commit orchestrator cannot audit itself; the audit is the dispatcher's responsibility, not an optional step.
+
+   **Parent owes Phase 6 Learn + retrospective (E3).** A stop-early dispatch that never reaches Phase 4 Review-G can't run Phase 6 Learn or the post-push retro — so the dispatching parent owes them at close, under the same parent-dispatch contract as GAP-1 (not optional, name the owner at dispatch). Full contract: `agents/build-orchestrator.md` §Phase 4 A (E3 block).
+
+### State.json schema
+
+The per-commit dispatcher tracks its own progress under a `perCommit` block alongside the existing `execution` block:
+
+```json
+{
+  "perCommit": {
+    "enabled": true,
+    "mode_source": "self_recursive_default|explicit_flag|opt_out",
+    "plan_path": ".build-loop/per-commit-plan.json",
+    "completed": [{"commit_id": "c1", "hash": "abc123", "completed_at": "..."}],
+    "in_flight": "c2",
+    "queued": ["c3"]
+  }
+}
+```
+
+M2's `execution.iterate_attempt` continues to track per-commit-orchestrator attempt counters (each dispatched orchestrator manages its own iterate counter) — do not duplicate iteration tracking inside `perCommit`.

package/plugin-artifacts/codex/references/autonomy-config.md

@@ -0,0 +1,231 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Autonomy Gate — Configuration Reference
+
+## Purpose
+
+`scripts/autonomy_gate.py` is the generalized action classifier that lets Phase 4.5 Auto-Resolve drain non-destructive open items (guidance fixes, cache resyncs, lint cleanups, open-rec executions) without prompting the operator. The existing `scripts/deployment_policy.py` already handles push/deploy/release commands; this gate handles everything else, and delegates to deployment_policy when a command looks deployment-flavored. Together they form the complete autonomy boundary: deployment_policy is authoritative for deploy targets, autonomy_gate is authoritative for everything else.
+
+## Default policy
+
+### confirmFor — 7 built-in patterns
+
+These patterns require operator confirmation (`exit 1`). They are active whenever a repo does NOT supply its own `confirmFor` list:
+
+```
+npm publish*
+git push --force*
+git push * main
+git push * master
+production deploy*
+DROP TABLE*
+rm -rf /*
+```
+
+Matching uses `fnmatch.fnmatch` (Unix-shell-style globs, case-insensitive).
+
+### warnFor — empty by default (NEW)
+
+No commands are flagged by default. Repos may add patterns to `warnFor` to observe match-rate without blocking (`exit 0`). The canonical workflow is to ship a candidate pattern as `warnFor` first, observe 10+ builds via `state.json.runs[].autonomyEvents[]`, then promote to `confirmFor` if the match-rate justifies it.
+
+### blockFor — empty by default
+
+No commands are hard-blocked by default. Repos may add patterns to `blockFor` to create absolute vetoes (`exit 2`).
+
+### Boolean flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `autoFixGuidance` | `true` | Phase 4.5 may auto-apply guidance-class fixes without operator confirmation |
+| `autoExecuteOpenRecs` | `true` | Phase 4.5 may auto-execute open recommendations without operator confirmation |
+
+These flags are read by the skill body and orchestrator (Chunks B/C). `autonomy_gate.py` surfaces them in the envelope's `flags` key but does not act on them directly.
+
+## Repo override schema
+
+Add an `autonomy` block to `.build-loop/config.json`:
+
+```json
+{
+  "autonomy": {
+    "autoFixGuidance": true,
+    "autoExecuteOpenRecs": true,
+    "confirmFor": [
+      "wipe database*",
+      "reset production*"
+    ],
+    "warnFor": [
+      "touch-prod-config*"
+    ],
+    "blockFor": [
+      "rm -rf /"
+    ]
+  }
+}
+```
+
+All five fields are optional. Omitting `confirmFor`, `warnFor`, or `blockFor` leaves the defaults active. Setting them (even to `[]`) replaces the defaults.
+
+**Tie semantics**: when a command matches both `confirmFor` and `warnFor`, `confirmFor` wins. The stricter verdict always takes precedence.
+
+## Replacement semantics
+
+`confirmFor`, `warnFor`, and `blockFor` **REPLACE** the defaults — they do not extend them. This is intentional: repos that need a smaller or entirely different set of guarded commands should not be forced to fight the defaults.
+
+To extend the defaults, copy the 7 default `confirmFor` patterns into your config and add your custom patterns alongside them:
+
+```json
+{
+  "autonomy": {
+    "confirmFor": [
+      "npm publish*",
+      "git push --force*",
+      "git push * main",
+      "git push * master",
+      "production deploy*",
+      "DROP TABLE*",
+      "rm -rf /*",
+      "wipe database*"
+    ]
+  }
+}
+```
+
+## Precedence
+
+The gate applies rules in this order, stopping at the first match:
+
+1. **deployment_policy first** — if the command contains deploy/push/release keywords, shell out to `python3 scripts/deployment_policy.py --workdir <path> --command <command>`. Use its verdict directly. `list_source: "deployment_policy"`.
+2. **Repo blockFor next** — if any `blockFor` glob from `.build-loop/config.json` matches the command, return `block` (`exit 2`). `list_source: "config"`.
+3. **Repo confirmFor next** — if any `confirmFor` glob from config matches, return `confirm` (`exit 1`). `list_source: "config"`. **confirmFor wins over warnFor on a tie** — checked first.
+4. **Repo warnFor next** — if any `warnFor` glob from config matches, return `warn` (`exit 0`). `list_source: "config"`. (NEW)
+5. **Default confirmFor next** — if no repo `confirmFor` was provided, check the 7 default patterns. Match → `confirm` (`exit 1`). `list_source: "default"`.
+6. **Default warnFor next** — if no repo `warnFor` was provided, check the default warn list (empty). Match → `warn` (`exit 0`). `list_source: "default"`. (NEW, no-op by default)
+7. **Default blockFor next** — if no repo `blockFor` was provided, check the default block list (empty). Match → `block` (`exit 2`). `list_source: "default"`.
+8. **Otherwise** — return `auto` (`exit 0`). `list_source: "default"` or `"config"` depending on whether a config file exists.
+
+Note: repo `confirmFor`, `warnFor`, and `blockFor` only apply when explicitly set in config. If `confirmFor` is absent from config, step 3 is skipped and step 5 applies. If `confirmFor` is present (even as `[]`), step 5 is skipped entirely. Same logic applies to `warnFor` (step 4 vs step 6) and `blockFor` (step 2 vs step 7).
+
+## Relationship to deployment_policy.py
+
+`deployment_policy.py` is the canonical gate for push/deploy commands. It understands deployment targets (preview, testflight, production, unknown) and repo-level target policies. `autonomy_gate.py` delegates to it rather than duplicating that logic.
+
+`autonomy_gate.py` generalizes for everything else: lint fixes, cache ops, open-rec execution, guidance application, and any other non-deploy action the orchestrator may want to auto-execute. It also delegates to deployment_policy when it detects deployment-flavored keywords.
+
+Do not modify deployment_policy.py to handle non-deploy actions. The two scripts are intentionally decoupled; autonomy_gate calls deployment_policy as a subprocess.
+
+## Usage from skill body / orchestrator
+
+### Human-readable output (default)
+
+```bash
+python3 scripts/autonomy_gate.py \
+  --workdir /path/to/repo \
+  --action "cache resync" \
+  --command "rsync ... codex cache"
+# output: auto: cache resync — no pattern matched; safe to execute
+# exit: 0
+```
+
+### JSON envelope (for machine consumers)
+
+```bash
+python3 scripts/autonomy_gate.py \
+  --workdir /path/to/repo \
+  --action "npm publish" \
+  --command "npm publish" \
+  --json
+```
+
+Output:
+
+```json
+{
+  "action": "confirm",
+  "matched_rule": "npm publish*",
+  "list_source": "default",
+  "reason": "matched default confirmFor pattern",
+  "label": "npm publish",
+  "command": "npm publish",
+  "flags": {
+    "autoFixGuidance": true,
+    "autoExecuteOpenRecs": true
+  }
+}
+```
+
+### Exit code mapping (mirror of deployment_policy.py)
+
+| Exit code | Meaning |
+|---|---|
+| `0` | `auto` — safe to execute without operator input |
+| `0` | `warn` — safe to execute; flagged for match-rate tracking (NEW) |
+| `1` | `confirm` — operator must approve before proceeding |
+| `2` | `block` — do not execute under any circumstance |
+
+### Consuming in a shell script
+
+```bash
+python3 scripts/autonomy_gate.py \
+  --workdir "$WORKDIR" \
+  --action "$ACTION_LABEL" \
+  --command "$COMMAND" \
+  --json > /tmp/gate_result.json
+exit_code=$?
+action=$(python3 -c "import json,sys; print(json.load(open('/tmp/gate_result.json'))['action'])")
+
+case $exit_code in
+  0)
+    if [ "$action" = "warn" ]; then
+      echo "[warn] Executing (flagged): $ACTION_LABEL"
+    else
+      echo "Auto-executing: $ACTION_LABEL"
+    fi ;;
+  1) echo "Needs confirmation: $ACTION_LABEL" ; exit 1 ;;
+  2) echo "BLOCKED: $ACTION_LABEL" ; exit 2 ;;
+esac
+```
+
+### Reading flags from the envelope
+
+The `flags` key surfaces the two boolean flags regardless of which rule triggered. Consumers check them before deciding whether to auto-apply guidance or open-rec items:
+
+```python
+import json, subprocess, sys
+
+result = subprocess.run(
+    [sys.executable, "scripts/autonomy_gate.py",
+     "--workdir", workdir, "--action", label, "--command", cmd, "--json"],
+    capture_output=True, text=True,
+)
+data = json.loads(result.stdout)
+if result.returncode == 0 and data["flags"]["autoFixGuidance"]:
+    apply_guidance_fix()
+```
+
+## Warn-before-block workflow
+
+The canonical pattern for introducing new guarded patterns:
+
+1. **Ship as `warnFor`**: add the candidate glob to `warnFor` in `.build-loop/config.json`. The gate executes the action, records it in `## Done` with a `[warn] <reason>` prefix, and appends one entry to `state.json.runs[].autonomyEvents[]`.
+
+2. **Observe match-rate**: run ~10 builds. Inspect `autonomyEvents[]` entries for this pattern. High match-rate + never-intended-to-run = promote to `confirmFor`. Low match-rate = the pattern is too broad; refine the glob first.
+
+3. **Promote to `confirmFor`**: move the glob from `warnFor` to `confirmFor`. From this point the gate will pause execution and route the item to `## Held` for manual operator approval.
+
+This three-step lifecycle keeps the autonomy policy calibrated. Jumping straight to `confirmFor` with an untested glob creates friction for every legitimate execution of that command. Jumping straight to `blockFor` without data risks blocking operations that are actually safe in this repo's context.
+
+**`autonomyEvents[]` entry shape** (one entry per `warn` verdict, appended by the orchestrator at the end of Sub-step F):
+```json
+{
+  "action": "warn",
+  "matched_rule": "<glob>",
+  "list_source": "config",
+  "label": "<action label>",
+  "command": "<full command>",
+  "run_id": "<state.json run_id>",
+  "timestamp": "<iso8601>"
+}
+```
+
+The orchestrator emits this entry. The gate script itself does not write to `state.json` — separation of concerns: gate classifies, orchestrator records.