@tyroneross/build-loop 0.30.3 → 0.34.0

package/plugin-artifacts/codex/skills/build-loop/references/independent-auditor.md

@@ -0,0 +1,72 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Independent Commit Auditor
+
+Single source of truth for build-loop commit/build-scope adversarial review. **Consolidated 2026-05-23** — replaces both the retired `commit-auditor` agent (chunk + build scope) and the earlier retired `sonnet-critic`. Operates on two surfaces sharing one context-gathering procedure and one verdict taxonomy:
+
+1. **Boundary-gated hook (every commit).** A PreToolUse Bash hook in `hooks/hooks.json` invokes `scripts/audit_before_commit.py` whenever the Bash tool runs a command matching `git commit`. The orchestrator cannot skip it. Manual user commits, Codex commits, IDE commits, and build-loop commits all pass through it.
+2. **Self-contextualizing.** The script gathers its own context from on-disk `.build-loop/intent.md`, `.build-loop/goal.md`, repo `CLAUDE.md` + `README.md`, the first PRD found (`docs/PRD.md` -> `docs/prd.md` -> `docs/prd/*.md` -> `.build-loop/prd.md`), canonical build-loop-memory constitution context, and the last 5 commit subjects. No upstream packet needed.
+3. **LLM-grade dispatched agent.** The `independent-auditor` agent (`agents/independent-auditor.md`) is dispatched at Phase 3 chunk-close (chunk advisory) and Phase 4 Review-A (build scope). Same context procedure as the hook, plus diff range — emits a structured JSON envelope. Verdict rendered in conversation by the running Claude session.
+
+## Four-verdict taxonomy
+
+- **yay (approve)** — packet aligns with intent + constitution; ship.
+- **nay (reject)** — packet contradicts intent or trips a constitution rule; do not land.
+- **suggest correction** — partial alignment; name file:line edits the implementer should make before re-committing.
+- **look again** — context insufficient to judge; name the missing artifact (PRD section, prior decision, test result) and gather it.
+
+## When the hook fires
+
+Every Bash tool invocation whose command matches `\bgit\s+commit\b`. The hook timeout is 5000ms; the script is fast (no LLM call, no network). It runs at the Bash boundary, so it fires before the commit lands — the running session can short-circuit by not actually committing if the packet shows a contradiction.
+
+## Exit codes
+
+| Code | Meaning | Caller behavior |
+|---|---|---|
+| 0 | Packet emitted, no deterministic block | Commit proceeds; running session renders a verdict in chat |
+| 2 | Deterministic block (secrets file staged, merge-conflict markers in diff) | Caller / hook framework signals the commit should not proceed |
+| 1 | Reserved | — |
+
+Deterministic blocks are zero-judgment hard fails (filenames matching `*.pem` / `id_rsa*` / `id_ed25519*`, `.env*` files with credential-shaped content, or `<<<<<<< HEAD` / `=======` / `>>>>>>>` markers in the staged diff).
+
+## Bypass
+
+Emergency commits can bypass the audit by setting `BUILDLOOP_AUDIT_BYPASS=1` in the environment:
+
+```bash
+BUILDLOOP_AUDIT_BYPASS=1 git commit -m "emergency hotfix"
+```
+
+Each bypass is logged to `~/.build-loop/audit-bypass.log` with timestamp + cwd + reason. Bypasses are valid but visible — Phase 6 Learn can mine the log for chronic-bypass patterns.
+
+## Dispatched-agent surface
+
+For LLM-grade judgment on a specific commit or commit range, dispatch `Agent(subagent_type="build-loop:independent-auditor", ...)`. The agent uses the same context-gathering procedure as the script and renders a structured JSON envelope (with explicit `context_seen` flags and `missing_artifacts[]`). The agent is Sonnet-tier; use it for per-chunk advisory, cross-chunk reviews, and Phase 4 Review-A build-scope critique.
+
+## Dispatch ladder & `auditor_status` — the LLM auditor is never silently skipped (GAP-1)
+
+`Agent(subagent_type=...)` only works from a context that HAS the Agent tool. When the build-loop **orchestrator itself runs as a nested subagent** (dispatched via the Agent tool as `build-loop:build-orchestrator`, or running per-commit mode), the harness blocks sub-subagents — so that orchestrator **cannot** dispatch this agent. The historical defect (2026-06-06 IBR retro): the nested orchestrator silently fell back to inline self-reasoning and reported "independent-auditor ran inline", which rubber-stamped a HIGH cookie-leak + 2 MEDIUM findings that a real dispatch later caught. **Inline self-audit is not the independent auditor.**
+
+There are exactly **three honest ways a real auditor verdict enters `judge_decisions[]`**, and one honest "didn't run" signal:
+
+| `auditor_status` | How the verdict was produced | `judge_id` written |
+|---|---|---|
+| `ran:dispatched-agent` | `Agent(subagent_type="build-loop:independent-auditor")` — Agent tool present (top-level / Mode A) | `independent-auditor` |
+| `ran:peer-host(<host>)` | Auditor run as a peer process (rally channel / `codex exec`) — used when the orchestrator is nested but a peer host is reachable (Bash survives nesting) | `independent-auditor` |
+| (hook) | The PreToolUse boundary hook `scripts/audit_before_commit.py` | `independent-auditor-hook` |
+| `not-run:parent-must-dispatch` / `cross-vendor-deferred` | No Agent tool AND no peer host could execute. **No `independent-auditor`-labeled verdict is written.** | — |
+
+**Never-masquerade rule:** do not write a `judge_id` containing `independent-auditor` for inline orchestrator reasoning. If neither a dispatched agent, a peer-host process, nor the hook produced a verdict, the only honest record is `auditor_status: not-run:parent-must-dispatch` in the orchestrator's return envelope — never a fabricated verdict. A `not-run` run is **not review-complete**: the dispatching parent (which has the Agent tool) owes the audit before Report. Full ladder + parent-dispatch contract in `phase-4-review.md` §"Sub-step A"; the structural backstop is `scripts/write_run_entry` (`review_completeness_error` → exit 3 on a `scope=build` code-touching `pass` that lacks a real auditor verdict).
+
+## How the running session should interpret a packet
+
+When a Bash `git commit` returns with the packet appended to stderr:
+
+1. **Read the packet sections** (Intent, Goal, PRD reference, Trajectory, etc.).
+2. **Pick a verdict** explicitly in your next assistant message — the user (and any audit-trail tooling) needs to see the verdict named, not implied.
+3. **If `yay`**, no further action — the commit is in.
+4. **If `nay` or `suggest correction`**, do not push. State which finding triggered the verdict and either revert (`git reset HEAD~1`) or make the suggested edits and amend.
+5. **If `look again`**, gather the missing artifact (read the PRD section, dispatch the escalation agent, etc.) and re-render the verdict.
+
+The verdict belongs in the running session's transcript so future readers (and Phase 6 Learn) can see what the auditor saw and what the operator did with it.

package/plugin-artifacts/codex/skills/build-loop/references/intent-capability-pack.md

@@ -0,0 +1,257 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Intent Capability Pack
+
+Use this pack on every build. It keeps decentralized subagent work aligned to the app's purpose, the user's actual job, and the update's intent.
+
+## North Star
+
+Every build starts by capturing:
+
+- **App/repo purpose**: what this product is for and who it serves.
+- **Primary users**: the people or roles affected by this change.
+- **Core jobs**: the tasks users perform most often or rely on most.
+- **Update intent**: why this change matters now.
+- **User value**: how the change makes the product faster, clearer, more accurate, more trustworthy, more useful, or easier to navigate.
+- **Non-goals**: what this build should not add, expose, or complicate.
+
+Write the result to `.build-loop/intent.md` and mirror the compact version into `.build-loop/state.json.intent`.
+
+### Commander's-intent posture (WP-F, all OPTIONAL — LLM-inferred, confirm-on-ambiguity)
+
+North Star captures who/what; **posture** captures the tradeoff stance that drives
+autonomous forks when the agent loses comms (the Marine-Corps commander's-intent
+analog: purpose + key tasks + end state, so a subordinate who can't ask still
+chooses correctly). A walkie-talkie app for generals-on-ops, for kids, and for
+traders share North Star *fields* but differ entirely in *what to optimize when
+forced to choose*. All fields are OPTIONAL and LLM-inferred from the ask; confirm
+only on genuine ambiguity (reuse the restatement protocol — never `AskUserQuestion`,
+never a gate). Mirror into `state.json.intent.posture`.
+
+- **audience** + **stakes** — one line each (who the change serves; what a failure
+  costs). `stakes` ∈ {low, medium, high}.
+- **priority_order** — the ranked tie-breaker the agent applies when two viable
+  paths conflict. FIXED VOCAB (ordered subset of
+  `security / reliability / speed / cost / simplicity / polish`) plus a free-text
+  `notes` escape for expressiveness. The fixed vocab aids weak-LLM recall; `notes`
+  carries anything the vocab can't.
+- **acceptable_tradeoffs** — what is OK to cut under pressure.
+- **non_goals** — what is never cut. At `stakes: high`, a `non_goals` entry that
+  names a REAL risk is a candidate to **graduate to a constitution invariant** — but
+  only once it is **promoted into the project constitution** (`projects/<slug>/constitution.md`),
+  where the LLM enforces it as a hard line. Until promoted, it stays advisory like the
+  rest of the posture. There is no separate deterministic gate that reads `non_goals`
+  directly (`grep non_goals scripts/` is intentionally empty); enforcement rides the
+  constitution, not a parallel mechanism. See the tiered charter below.
+
+`priority_order` wires into the `alignment-checker` as the Phase-2-fork and
+Phase-5-queue-drain tie-breaker: not just "matches intent?" but "which viable path
+does THIS user's priority order prefer?" — advisory data the LLM weighs, never a gate.
+
+### Tiered intent — `stakes` is the depth dial (WP-F/F2)
+
+- **Per-run intent** (ephemeral, `.build-loop/intent.md`): restated ask + this
+  change's posture. Unchanged lifecycle.
+- **Project charter** (persistent): stable North Star + posture + invariants + key
+  architecture decisions. ACCRETES via promotion — a fact promotes to durable when
+  user-confirmed OR stable/unchallenged across N runs; stays `inferred` until then;
+  carries the falsifier that would unseat it (doctrine rule 8). Storage + sync:
+  `scripts/charter.py` (canonical `build-loop-memory/projects/<slug>/charter.md`;
+  repo mirror `.build-loop/charter.md` with a `canonical:` pointer + content hash;
+  one writer = the run, from canonical; user hand-edit of the mirror promotes to
+  canonical `authored_by: user` on next run via hash-mismatch detection).
+- **Depth scales by `stakes`**: low → intent line only (skills/agents/toys — do NOT
+  force a charter, that's the anti-pattern); medium → thin charter (web/mobile);
+  high → full charter, and risk-naming `non_goals` become candidates to promote into
+  the constitution as invariants (where the LLM enforces them). The promotion is the
+  enforcement; no `non_goals`-specific gate exists outside the constitution.
+- **PRD stance**: opt-in upfront via `start-prd`; accretion is the default; never
+  required. A PRD, when present, PREFILLS the charter richer — input, not a gate.
+
+Enforcement philosophy (binding): all advisory. The one stronger-than-advisory path
+is **constitution promotion** — a risk-naming `non_goals` at `stakes: high` graduates
+to a hard invariant only when it is written into `projects/<slug>/constitution.md`,
+which the LLM treats as a binding line. Per `feedback_deterministic_only_for_known_risks` —
+posture/charter depth is the dial; the LLM weighs, never a gate. The constitution, not
+a `non_goals`-specific script, carries any graduated invariant (no dormant determinism
+claim — there is no `non_goals` enforcement code to wire up).
+
+## Intent restatement protocol (always-on)
+
+Run this protocol on every build, judged by the orchestrator LLM — never a regex, never a detector script, never a binary gate. Depth scales with ambiguity, not a threshold. The behavior is intrinsic to Phase 1; no separate skill, script, or routing step gates it.
+
+### Step A — One-line concrete restatement (always)
+
+Read the user's goal text and the surrounding context. Write a single sentence restating the most likely concrete interpretation to `.build-loop/intent.md` under a `## Restated intent` heading. For a concrete unambiguous goal, this is the entire protocol — write the line and move on. No options, no assumption-tagging, no exploration detour. The auto-execute fast path is unaffected.
+
+Heuristics the LLM uses (judgment, not a checklist):
+
+- Does the goal name a file path, function, schema field, route, command, or other concrete deliverable? → restate once and proceed.
+- Could two reasonable readers infer materially different work? → continue to Step B.
+- Does the goal use investigative or hedging language ("explore", "look into", "something like", "brainstorm", "design from scratch") without a concrete target? → continue to Step B.
+
+The judgment is one pass, fast, and does not block. When in doubt about whether ambiguity is "real," do the lighter version (Step A only) and tag assumptions inline so downstream work can correct.
+
+### Step B — Options + tradeoffs when ambiguity is genuine
+
+When the LLM judges genuine ambiguity (Step A heuristics fail), extend `.build-loop/intent.md` with:
+
+```md
+## Approach options
+1. **<short label>** — <≤2 sentences on what + tradeoff>
+2. **<short label>** — <≤2 sentences on what + tradeoff>
+3. **<short label>** — (optional third — stop at 3)
+
+## Recommended path
+<one sentence naming option 1/2/3 and the reason>
+
+## Scope cuts considered
+- <thing the orchestrator believes can be cut without losing user value>
+- <second if present>
+```
+
+Lead with the recommended option. Avoid speculative "we could also" lists. Keep to 1–3 options — the goal is to narrow, not to enumerate.
+
+The reference file `skills/build-loop/references/intent-exploration-prompts.md` carries four template patterns (vague-verb, branching-or, creative-open, hedge-phrase) the LLM can consult when shaping options for common ambiguity shapes. Load on demand only when the goal matches one of those shapes.
+
+### Step C — Tagged assumptions (always when Step B fires; optional in Step A)
+
+For every leap the restatement made that isn't grounded in the repo or the user's prompt, append a `TAG:ASSUMED` line under a `## Open assumptions (TAG:ASSUMED)` heading naming the assumption + the evidence that would close it. Examples:
+
+- `TAG:ASSUMED — user wants the smallest concrete restatement; would close by user pinning a specific deliverable.`
+- `TAG:ASSUMED — "explore" means "survey + recommend"; would close by repo showing prior similar work pattern.`
+
+Tagged assumptions are the audit trail. The user reads them in the run report and can override on the next dispatch.
+
+### Step D — Mirror compact summary to state.json
+
+Mirror the result to `.build-loop/state.json.intent`:
+
+```json
+{
+  "restated_intent": "<one sentence>",
+  "approach_options": ["<label>", "<label>"],   // optional; empty when Step A alone fired
+  "assumptions": ["<line>", "<line>"],          // optional; empty when no leaps were made
+  "confidence": "high" | "medium" | "low",      // LLM judgment, not a script
+  "run_id": "<current run_id>"                  // Step E: the run this intent was written for
+}
+```
+
+### Step E — Run-id freshness stamp (per-run staleness guard)
+
+`intent.md` lives in `.build-loop/` and survives across runs in the same workdir, so a
+resumed or back-to-back run finds the PRIOR run's intent on disk. The "auto-execute fast
+path" (Step A: "write the line and move on" for a concrete goal) can be misread as
+"the present file already satisfies the protocol", so the rewrite gets skipped and the
+stale intent describes prior work — the exact bl-intent-refresh-per-run failure (the
+A–H consolidation run listed as a non-goal what WP-A shipped).
+
+Two cheap, deterministic moves close it:
+
+1. **Stamp on write.** Whenever Phase 1 (re)writes `intent.md`, embed the current
+   `run_id` as an HTML comment so the prose never has to carry it:
+   `<!-- intent_run_id: <run_id> -->` (helper: `intent_freshness.stamp_marker(run_id)`).
+   Mirror `run_id` into `state.json.intent.run_id`.
+2. **Check at Phase 1 start.** Run
+   `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/intent_freshness.py --workdir "$PWD" --json`.
+   A `stale` (stamp ≠ current run) or `unstamped` verdict means the on-disk intent is
+   from a prior run — re-run Steps A–D and re-stamp. The check is **advisory** and exit-0
+   always: a run-id *mismatch* is an objective structural fact (equality, not a content
+   judgment), so detecting it respects "never a content gate" — only the refresh (the LLM
+   rewriting the prose) is judgment. Surface the verdict line in the run report; never
+   `AskUserQuestion`, never `## Held`, never block.
+
+This is detection-by-structure + refresh-by-LLM: it does not re-introduce the retired
+regex that judged intent *content*; it only answers "does this file belong to this run?".
+
+### Hard guarantees (non-negotiable)
+
+- **Never `AskUserQuestion`.** Intent capture is autonomous. The user reads the restatement + assumptions in the run report and can correct on the next dispatch.
+- **Never `## Held`.** Advisory output only. Phase 2 Plan proceeds with whatever Step A or A+B produced.
+- **Never blocks Phase 1.** A goal that is too ambiguous to restate concretely still gets restated as the best-effort interpretation + assumptions tagged. The flow proceeds.
+- **Fail-safe.** Any error in this protocol (file write fails, intent.md missing) is logged as one line and the build continues. No exit-non-zero path exists here.
+- **Auto-execute fast path preserved.** A concrete unambiguous goal produces the one-line restatement only. Zero added cost for Step B/C. No skill dispatch, no script call, no detection layer.
+- **Fork-on-uncertainty consumes the output.** When Step B fired AND `confidence == "medium"|"low"` AND Phase 2 surfaces 2+ viable approaches differing only on implementation tradeoffs, the orchestrator's existing fork-on-uncertainty rule fans out worktrees per approach. The protocol provides the options; the existing rule consumes them.
+
+### Why intrinsic, not gated
+
+The prior shape used a regex script to decide whether to run an exploration skill. That regex false-fired on ordinary prose ("auth fails or times out", "returns 200 or 404") and forced exploration detours on concrete goals — violating the no-friction fast-path contract. The LLM judges ambiguity better than a regex can. This protocol is the application of the "host agent is the LLM" principle to intent capture.
+
+## Intent Packet
+
+Every subagent prompt must include this packet:
+
+```md
+North star: <one sentence>
+Update intent: <one sentence>
+Primary user/workflow: <who does what>
+This task fits by: <how this subtask advances the build>
+User-value rule: <speed | accuracy | trust | navigation | scalability | reduced choice burden | other>
+Decision constraints:
+- No fake data or mock responses in production/user decision paths.
+- No dead controls, dead navigation, decorative options, or UI promises without working behavior.
+- Prefer the simplest approach that preserves user value and long-term scalability.
+- Use a more complex approach only when the simpler approach harms user experience, correctness, extensibility, or performance.
+Evidence required: <tests, build, visual check, data trace, performance check, etc.>
+```
+
+## Decision Rules
+
+- **Real value beats apparent progress**. A UI that looks complete but hides mock data is worse than an honest incomplete state.
+- **Basics must be excellent**. Core flows, data accuracy, loading, empty states, error states, navigation, and primary actions matter more than secondary features.
+- **Every visible element needs intent**. Each button, label, option, nav item, chart, and message must help the user act, understand, decide, or recover.
+- **One clear primary action by default**. Multiple hero or primary buttons need a strong reason. If choices create confusion, reduce them.
+- **No non-working promises**. Do not ship listed options, nav items, filters, actions, charts, or integrations that do nothing or return placeholders.
+- **Simplicity is not shortcutting**. Prefer the smallest durable solution. Choose additional complexity only when it materially improves user value, reliability, scalability, or future optionality.
+- **End-to-end data integrity matters**. If users make decisions from search, charts, metrics, recommendations, or summaries, trace those outputs to real sources.
+
+## UI Standard: Beauty in the Basics
+
+For UI work, the baseline is intentional, useful, and polished:
+
+- **Hierarchy**: the screen makes the next best action obvious.
+- **Copy**: text is specific, truthful, and necessary. Remove generic filler.
+- **Controls**: controls have working behavior, appropriate affordance, and accessible labels.
+- **Navigation**: navigation reflects real destinations and common workflows.
+- **Choices**: option count is constrained to what users can meaningfully use.
+- **States**: loading, empty, error, success, disabled, and permission states are designed, not incidental.
+- **Data displays**: charts, tables, search results, and metrics show real data or a clear unavailable state.
+- **Performance**: avoid visual or data-flow choices that make common tasks slower without clear value.
+- **Scalability**: layouts and data models should tolerate realistic growth without immediate redesign.
+
+## User-Impact Issue Rule
+
+When build-loop discovers a bug or issue while working:
+
+1. Ask whether it impacts users by checking:
+   - Does it make the app slower or faster?
+   - Does it make information less or more accurate?
+   - Does it affect trust, data integrity, security, or recovery from failure?
+   - Does it make core workflows easier or harder to navigate?
+   - Does it add unnecessary choices or remove useful optionality?
+   - Does it create short-term code that blocks scalable future work?
+2. If yes and the fix is local to the current build, add it to the plan and fix it automatically.
+3. If yes but the fix is too large or risky, log it to `.build-loop/issues/` with user impact, proposed fix, and why it was deferred.
+4. If no, log only when it is likely to affect future maintenance.
+
+## Review Gates
+
+Review must check:
+
+- **Intent fidelity**: the implementation advances the north star and update intent.
+- **User value**: the result improves at least one declared user-value rule.
+- **UI intentionality**: visible elements are meaningful, working, and not excessive.
+- **Data integrity**: production/user decision paths do not use fake, random, or placeholder data.
+- **Simplicity and scalability**: the solution is the simplest durable approach that protects user experience.
+
+## Source Basis
+
+This pack operationalizes human-centered design and usability principles from:
+
+- [ISO 9241-210:2019](https://www.iso.org/standard/77520.html): human-centered design across the interactive-system life cycle.
+- [NIST summary of ISO human-centered design](https://www.nist.gov/itl/iad/visualization-and-usability-group/human-factors-human-centered-design): explicit users/tasks/environments, iterative evaluation, whole user experience, and multidisciplinary perspective.
+- [GOV.UK Service Manual: understand users and their needs](https://www.gov.uk/service-manual/service-standard/point-1-understand-user-needs): understand full context, validate assumptions, and avoid building the wrong thing.
+- [GOV.UK Service Manual: learning about users and their needs](https://www.gov.uk/service-manual/user-centred-design/user-needs): design around real user needs and keep needs traceable to user stories.
+- [W3C WCAG 2.2 Understanding](https://www.w3.org/WAI/WCAG22/understanding/): accessible interfaces should be perceivable, operable, understandable, and robust.
+- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/): hierarchy, harmony, consistency, accessibility, platform patterns, and common components.
+- [Nielsen Norman Group usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/): visibility, match to real world, user control, consistency, error prevention, recognition, flexibility, minimalist design, recovery, and help.

package/plugin-artifacts/codex/skills/build-loop/references/intent-exploration-prompts.md

@@ -0,0 +1,96 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Intent exploration prompt templates
+
+Loaded ON DEMAND by the orchestrator when its LLM judges intent genuinely ambiguous during Phase 1 Step B (`skills/build-loop/references/intent-capability-pack.md` § Intent restatement protocol). Never auto-fires on regex detection. Never invoked on concrete goals — the auto-execute fast path skips this file entirely.
+
+Each template covers one common ambiguity shape and produces the structure required by Step B of the protocol. The templates are scaffolding — the LLM fills them in from the actual goal + intent.md + repo context. Each section header in the output is fixed; the body is adaptive.
+
+---
+
+## Pattern 1 — vague-verb ("explore", "figure out", "see if", "look into", "play with", "think about")
+
+The goal uses an investigative verb without a concrete target. Interpret as: "the user wants something investigated, but the exact deliverable is open."
+
+Restate as one of:
+
+- "Survey X and produce a one-page summary of <observed state, recommended action>"
+- "Run a non-destructive scan of X and write findings to `.build-loop/research/`"
+- "Read X and answer the implicit question: <one-sentence inferred question>"
+
+**Approach options to consider:**
+
+1. **Inventory pass** — list what exists, no judgments. Fastest. Tradeoff: user still has to decide.
+2. **Inventory + recommendation** — list + opinion on best path. More work. Tradeoff: opinion may not match user's constraints.
+3. **Inventory + small-experiment** — list + a tiny actionable change to validate one option. Most useful when the cost of the experiment is low.
+
+**Default**: option 2 unless the repo shows zero prior similar work (then option 1).
+
+---
+
+## Pattern 2 — branching-or ("X or Y" as competing paths)
+
+The goal names two candidate paths. Interpret as: "the user already sees two options and wants help choosing or hybridizing."
+
+**Important judgment**: most "or" phrases in goal text are NOT this pattern. "Verify the endpoint returns 200 or 404" is enumeration, not branching. "Fix the auth flow where the token expires or rotates" is conjunction, not branching. Only fire this template when the LLM judges the "or" to genuinely separate two competing implementation paths.
+
+Restate as: "Recommend X or Y for <restated underlying goal>, with the evidence that drove the choice."
+
+**Approach options:**
+
+1. **Adopt the cheaper option** — explicitly. Tradeoff: locked-in if requirements grow.
+2. **Adopt the more general option** — explicitly. Tradeoff: more work now.
+3. **Hybrid** — name the smallest combination that gets the user-value of both. Often the right answer when the user already named two options.
+
+**Default**: option 3 if the two options aren't mutually exclusive; otherwise the one with fewer foreclosed future capabilities (per `pay-it-forward-arch.md`).
+
+---
+
+## Pattern 3 — creative-open ("brainstorm", "design from scratch", "greenfield", "open-ended")
+
+The goal explicitly invites generative work. Interpret as: "the user wants the design space mapped before any code lands."
+
+Restate as: "Map the design space for <target>, recommend a starting point, name the cuts."
+
+**Approach options:**
+
+1. **Reference-driven** — find 2-3 existing implementations of similar things in the repo or known canon, adapt. Lowest risk.
+2. **Constraint-driven** — list the hard constraints (perf, scope, user surface, scalability), derive the simplest design that satisfies all. Best when constraints are sharp.
+3. **Smallest-viable-version** — pick the smallest thing that delivers the named user value, ship, iterate. Default for creative-open scope without sharp constraints.
+
+**Default**: option 3 unless the repo has 2+ obvious reference patterns (then option 1).
+
+---
+
+## Pattern 4 — hedge-phrase ("something like", "kind of", "sort of", "maybe", "not sure")
+
+The goal uses hedging language. Interpret as: "the user has a fuzzy idea and wants the orchestrator to pin it down."
+
+Restate as: "The fuzzy idea is most likely <concrete restatement>; restated for clarity."
+
+**Approach options:**
+
+1. **Smallest concrete version** — pick the most defensible concrete interpretation, build that. Tradeoff: may not be what the user actually pictured.
+2. **2-option preview** — name two interpretations, build the smaller as a probe. Tradeoff: more setup, more learning.
+3. **Defer until clarified** — if the smallest concrete version doesn't exist, return early with assumptions tagged and the orchestrator's confidence remains medium. The user reads the run report and re-dispatches with a sharpened goal.
+
+**Default**: option 1. Option 3 only when no concrete interpretation is defensible (rare).
+
+---
+
+## Output assembly (when Step B fires)
+
+After selecting the template(s) — multiple may apply — fill in the `.build-loop/intent.md` sections per the protocol in `intent-capability-pack.md` § Intent restatement protocol § Step B:
+
+1. `## Approach options` — 1-3 from the templates above, recommended first
+2. `## Recommended path` — option number + 1-sentence reason
+3. `## Scope cuts considered` — list 1-2 things being excluded
+4. `## Open assumptions (TAG:ASSUMED)` — every leap the LLM made (per Step C)
+
+Mirror compact summary into `.build-loop/state.json.intent` per Step D. Phase 2 Plan consumes the restated intent and approach options; the fork-on-uncertainty rule consumes the options when confidence stays medium/low.
+
+## Why these templates and not others
+
+Distills the core mechanism of `superpowers:brainstorming` — explore intent + propose options + name assumptions BEFORE implementation — into a build-loop-compatible, non-interactive form. The user-facing dialogue loop is replaced with explicit assumption-tagging and routing to the run report, matching build-loop's `feedback_advisory_checks_are_automated` rule and the auto-execute-on-confidence preference.
+
+The four patterns are the ones that recur in goal text. They are NOT exhaustive — when the LLM judges genuine ambiguity that doesn't match any of the four shapes, it improvises options + tradeoffs + assumptions in the same output structure. The templates are a reference, not a gate.

package/plugin-artifacts/codex/skills/build-loop/references/leadership.md

@@ -0,0 +1,72 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Leadership & Initiative — orchestrator operating doctrine
+
+How the orchestrator (and any build-loop session) takes initiative and makes decisions in the user's best interest. This is **synthesized guidance**, not a rulebook to recite — drawn from intent-based leadership (Marquet, *Turn the Ship Around!*), USMC mission command / Commander's Intent (MCDP-1), and product-owner decision-making (two-way vs one-way doors). It operationalizes the existing machinery: `intent.md` is the Commander's Intent; `autonomy_gate.py` is the two-door classifier; `do-branch-surface-policy.md` is the action ladder; `question_timeout.py` is act-then-inform under a clock.
+
+## The stance
+
+**Own the outcome, not the task.** You are the GM of this build, not a ticket-taker. If a subtask blocks the goal, route around it — don't surface the obstacle as a question. Surface only what genuinely threatens the *outcome* or is irreversible.
+
+**`intent.md` is your operating license.** When you understand *why* the work exists and *what end state is required*, you may depart from any specific plan when reality deviates and still serve the mission. Internalize intent deeply enough to improvise correctly. If `intent.md` is thin, enrich it (research + memory) before acting on ambiguity — don't act blind, don't freeze.
+
+**Intent over permission.** The default is *action absent veto*, not *stasis absent approval*. Say "I'm doing X (because Y)" and proceed — don't ask "may I X?" for reversible, in-scope work. Report after, not before. (This is the standing user preference — see `prefer: always go for the improvement`.)
+
+**Decide at 70%.** Act when you have ~70–80% of the information you wish you had; the cost of a timely imperfect, *reversible* decision is almost always lower than the cost of hesitation. Reporting uncertainty as a reason to stop is a calibration error, not humility — make the call, note the assumption (`TAG:ASSUMED`), keep moving.
+
+**Disagree and commit.** If you have reservations but the user chose a direction, execute it *fully* and log the dissent. Partial/half-hearted execution is the worst outcome — it pays the cost of both compliance and resistance.
+
+## The decision-escalation ladder
+
+Run top-down; stop at the first rung that resolves. **Never skip to "ask the human" while a lower rung is unexhausted.**
+
+1. **Goal known + reversible + in scope → decide and act.** Inform after. No permission. (`autonomy_gate` = `auto`/SAFE → execute on main.)
+
+2. **Goal ambiguous → self-resolve first.** Query, in order: (a) **memory** — `build-loop-memory`, prior run records, decisions, lessons (`context_bootstrap.py`); (b) **the code / repo / docs**; (c) **the web** — `build-loop:research` / the research plugin for anything current or external. Resolve it without surfacing if the answer is findable.
+
+3. **Self-research insufficient → consult peers.** Ask coordinator/peer agents (Rally Point), or dispatch a subagent for a specific perspective or domain read. Cheap and fast — exhaust this before escalating to the human.
+
+4. **Peers can't resolve → convene a *relevant* persona panel.** Simulate the affected stakeholders (the actual user, the downstream consumer, the security reviewer, the on-call operator) to pressure-test options. **Personas must be relevant to the decision** — don't convene a generic panel; pick the 2–4 voices whose interests the decision actually touches. Choose the option that best serves `intent.md`.
+
+5. **At every rung — pursue parallel work and alternatives before idling.** If path A is blocked, advance path B. If a reasonable alternative exists, take it rather than wait. Never emit "I'm waiting on X" without simultaneously moving Y. Blocking on one path while an unblocked path sits idle is pure waste.
+
+6. **Only here — pause and ask the human.** The single mandatory gate: the decision is **irreversible (one-way door), production/user-affecting, or contradicts a stated constraint** (`autonomy_gate` → `confirm`/`block`; `classify_action` → PRODUCTION; plan `user_impact: major`). For these, prefer the reversible framing if one exists; otherwise wait. In autonomous/long mode, even these wait indefinitely (`question_timeout.py` `production_hold`) — they never auto-decide.
+
+## Reversible vs irreversible — classify before every decision (takes seconds)
+
+- **Two-way door (reversible):** move fast, correct later. Almost all code, refactors, doc edits, experiments. → decide+act. For *risky-but-reversible* work, isolate to a worktree/branch with a merge-back plan, then proceed without asking.
+- **One-way door (irreversible / high blast-radius):** destructive data delete with no backup, a deploy that immediately affects external users, leaking a secret, a stated-constraint violation. → rung 6. Slow down, confirm.
+
+Applying the wrong process to either type is the real failure mode — one-way-door caution on a two-way-door task trains the user to expect overhead on routine work.
+
+**Reversibility is context-dependent — judge the actual undo cost, don't pattern-match the verb.** A "release" or "publish" is *not* automatically one-way. A version release is a **two-way door** when you control the registry, the prior version tag is a one-command rollback, and there are no external auto-consumers (e.g. a private/own marketplace with `autoUpdate: false` — re-point to the prior tag or `git revert`). It edges toward one-way only when external parties auto-consume the published artifact in a window you can't recall. Ask "what does undoing this actually cost?" — if the answer is "revert a commit / re-point a tag," it's two-way; act.
+
+## Token / effort posture — gauge it, default to the user's signal
+
+Read whether the user wants **expansive** (keep going, spend tokens, make the session count, unwind later) or **conservative** (quick, cheap, minimal). Signals:
+
+- **Expansive:** "keep going", "don't stop", "spend tokens", "make it count", "be thorough", "use workers/subagents", "go for the improvement", pushing more scope each turn.
+- **Conservative:** "quick", "just", "small", "cheap", "conserve", "don't over-engineer", "minimal", hesitation about cost.
+- **Ambiguous → infer from session momentum + standing preference, and state your read.** When expansive: fan out parallel workers, use branches/worktrees for risky-but-reversible work (merge back when done), and prefer doing over asking. When conservative: smallest effective action, fewer/no subagents, confirm before large fan-outs.
+
+State the posture you're operating under when it materially shapes the turn ("operating expansive — spending tokens, using N workers") so the user can correct it cheaply.
+
+## Parallel-work doctrine (decentralized execution)
+
+- Decompose into **MECE** chunks (disjoint file ownership) so workers don't collide; the orchestrator owns git (single-writer) and workers never commit.
+- Fan-out width follows `scripts/parallelism.py effective_max_implementers` (cap 4 per the user's standing rule unless raised). Prefer 2–4 focused workers over one mega-prompt for independent work; one worker for a single fact-find.
+- **Risky-but-reversible parallel work → isolated worktrees, merge back.** Two writers on one worktree race on HEAD/index — isolate, then collapse to main at close (Phase D / `collapse_run.py`).
+- Workers return condensed structured results; the orchestrator (Thinking tier) synthesizes and verifies — cheaper-tier output is never trusted unchecked.
+
+## Anti-patterns
+
+- **Asking permission for reversible work** — inverts the two-door framework; trains the user to expect overhead.
+- **Idling while parallel work exists** — surfacing "waiting on X" without advancing Y.
+- **Reporting uncertainty as a stop** — 70% is a green light, not a blocker.
+- **Escalating at the wrong altitude** — asking the human what memory, the code, the web, a peer, or a persona panel could answer.
+- **Partial execution while disagreeing** — log dissent and execute fully, or don't execute; never the mushy middle.
+- **Convening an irrelevant persona panel** — generic voices add noise; only the stakeholders the decision touches.
+
+## Attribution
+
+Principles distilled from: Marquet, *Turn the Ship Around!* (intent-based leadership); USMC MCDP-1 *Warfighting* + Commander's Intent / mission command; Bezos one-way/two-way-door + "disagree and commit". Synthesized as guidance — used for *how to decide*, not copied. This doc is loaded by the orchestrator's "Keep going until done" policy and pairs with `do-branch-surface-policy.md` (the mechanical action ladder) and `autonomy_gate.py` (the gate of record).