@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/skills/build-loop/references/correction-aware-capture.md

@@ -1,177 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Correction-aware lesson capture — three-tier design
-
-## Why
-
-Two gaps in the prior capture stack:
-
-1. **`scan_transcript_for_decisions.py` no-ops entirely without Ollama.**
-   The script gates on `shutil.which("ollama")`; absent the binary, an
-   entire session's worth of decisions is silently dropped.
-2. **No lessons / feedback lane from live conversation.** The decisions
-   scanner captures decisions only. A user correcting the assistant's
-   just-taken action — the highest-signal lesson event in a session —
-   had no trigger and no destination.
-
-The three-tier design closes both gaps without disrupting the existing
-decisions pipeline.
-
-## Three tiers
-
-### Tier 1 — Deterministic Stop-hook (always runs, no LLM)
-
-**Script:** `scripts/scan_corrections/`
-**Hook:** `hooks/hooks.json` Stop entry, fires alongside (not instead of)
-the decisions scanner.
-
-Detects three classes of high-signal patterns in USER turns:
-
-| Class | Patterns | Confidence |
-|---|---|---|
-| Correction | `revert that`, `don't X`, `undo`, `stop X`, `back that out`, `wrong approach` | `confirmed` (extra: `prior_assistant_acted: true` when assistant just used tools) |
-| Preference | `always X`, `never X`, `must X`, `default to X`, `we use X for Y`, `prefer X` | `confirmed` |
-| Tradeoff | `X instead of Y`, `actually X not Y`, `X over Y because Z` | `confirmed` |
-
-Scope routing: keywords like `across projects`, `globally`, `for all projects`,
-`as a rule`, `standing rule` flag the candidate as `scope: global` (otherwise
-`project`). Anti-false-positive: wh-question turns ending in `?` are skipped
-by hard-skip patterns; greetings/thanks/ok are skipped.
-
-Writes one `.build-loop/pending-lessons/<ts>-<kind>-<id>.md` per candidate
-with YAML frontmatter:
-
-```yaml
----
-id: <16-char sha1>
-kind: correction|preference|tradeoff
-signal_type: <named pattern>
-confidence: confirmed
-scope: project|global
-turn_index: <int>
-captured_chars: <int>
-tier: 1-deterministic
-source: stop-hook
-captured_at: <iso8601>
-extras:
-  prior_assistant_acted: true|false
----
-
-## Quote
-> <verbatim user span>
-
-## Context (±200 chars)
-```
-
-Idempotent: `id_hash` is a SHA-1 of (kind, signal_type, normalized quote),
-so re-running the scanner on the same transcript does not duplicate files.
-Promoted/discarded subdirs are also checked for dedup.
-
-Fail-open contract: any exception logs to stderr and exits 0. The
-`.build-loop/.no-capture` opt-out short-circuits before any work.
-`SCAN_CORRECTIONS_BUDGET_S` (default 10s) caps wall-clock.
-
-### Tier 2 — Optional Ollama accelerator (existing path, unchanged)
-
-**Script:** `scripts/scan_transcript_for_decisions.py` (the existing
-decisions scanner, untouched). When Ollama is installed AND the
-transcript is large enough to benefit from clustering, this path
-distills/dedups decisions and writes to
-`build-loop-memory/projects/<slug>/decisions/` (or `_review/` for
-quarantine).
-
-Tier 2 is **strictly optional**. The user installed Ollama on this
-machine, so it runs; on a fresh machine without Ollama, tier 1 alone
-guarantees capture and the session continues uninterrupted.
-
-### Tier 3 — Host-agent refinement (the primary intelligence)
-
-**Script:** `scripts/surface_pending_lessons.py`
-**Consumed by:** the host coding agent (Claude Code in this build,
-Codex on a Codex host, etc.) at SessionStart.
-
-Per the user's standing "host-agent-is-the-LLM" rule, the host coding
-agent is the primary refinement layer. Each session, the host reads
-`.build-loop/pending-lessons/` (and optionally
-`build-loop-memory/projects/<slug>/decisions/_review/`), classifies each
-candidate, and promotes via:
-
-- `scripts/memory_writer.py` — for `kind=lesson|feedback|preference`
-  (routes to `build-loop-memory/lessons/` for `scope=global` or
-  `build-loop-memory/projects/<slug>/lessons/` for `scope=project`)
-- `scripts/write_decision/__main__.py` — for `kind=decision`
-
-Discarded candidates move into
-`.build-loop/pending-lessons/discarded/` (any file there is silently
-skipped on re-runs, so the discard is durable).
-
-The same surface also exposes the existing Ollama `_review/` quarantine
-when `--include-decisions-review` is set, so the host agent has one
-queue to drain.
-
-## Store bridge (harness ↔ build-loop-memory)
-
-**Script:** `scripts/bridge_lesson_to_harness.py`
-
-Once a lesson lands in build-loop-memory (via tier-3 promotion or any
-other path), it can be mirrored into the harness auto-memory store the
-host coding agent auto-loads at session start
-(`~/.claude/projects/-Users-<u>/memory/`). The bridge:
-
-- Resolves a deterministic target basename `<kind>_<slug>.md` matching
-  the harness convention
-- Augments the bridged copy's frontmatter with `bridged_from`,
-  `bridged_at`, `source_store: build-loop-memory`
-- Appends a one-line entry to harness `MEMORY.md` under
-  `## Bridged from build-loop-memory` (creates the section if absent;
-  preserves other sections; dedup'd on target basename)
-
-Idempotent and reversible. Only `lesson | feedback | preference | convention | gotcha`
-types bridge; decisions stay in their own canonical store.
-
-## Triggers — what fires when
-
-| Event | Tier | Effect |
-|---|---|---|
-| Session ends (Stop hook) | 1 | tier-1 scanner writes raw candidates to `.build-loop/pending-lessons/` |
-| Session ends (Stop hook) | 2 | tier-2 scanner (Ollama, if present) writes distilled decisions |
-| Session starts (host agent reads context-bootstrap) | 3 | pending-lessons queue count surfaces in queue summary; host agent runs `surface_pending_lessons.py` to refine |
-| Lesson promoted to build-loop-memory | — | `bridge_lesson_to_harness.py` mirrors to harness auto-memory |
-
-## File layout summary
-
-```
-scripts/
-  scan_corrections/
-    __init__.py
-    detect.py             — patterns + Candidate dataclass + JSONL parser
-    __main__.py           — Stop-hook CLI (tier 1)
-    test_detect.py        — 26 unit tests
-    test_cli.py           — 8 CLI integration tests
-  surface_pending_lessons.py     — tier 3 host-agent surface
-  test_surface_pending_lessons.py — 10 tests
-  bridge_lesson_to_harness.py    — store bridge
-  test_bridge_lesson_to_harness.py — 11 tests
-  scan_transcript_for_decisions.py — UNCHANGED (tier 2)
-
-hooks/hooks.json — Stop hook now runs both scanners in parallel
-
-scripts/context_bootstrap.py — QUEUE_NAMES extended with "pending-lessons"
-
-.build-loop/pending-lessons/   — tier-1 candidate queue (this run)
-                  /promoted/    — host-agent promoted (silenced)
-                  /discarded/   — host-agent discarded (silenced)
-```
-
-## Non-goals + tradeoffs
-
-- **Not a replacement for `auto-decision-capture`.** That skill is for
-  the host agent's in-session reasoning — explicit captures during the
-  conversation. Tier-1 + tier-3 fire at session boundaries; the skill
-  fires inline. They compose.
-- **Tier 1 is intentionally narrow.** Adding fuzzy patterns would
-  produce false positives. The host agent (tier 3) is where ambiguous
-  cases get judged — that's the design intent of "host-agent-is-the-LLM."
-- **Bridge runs on demand, not automatically.** A future enhancement
-  could fire it via a post-promotion hook; the durable lesson lives in
-  build-loop-memory either way, and the bridge is reversible.

package/plugin-artifacts/codex/skills/build-loop/references/experiment-results-template.md

@@ -1,101 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-<!-- CONFIG: v1.0 | T2 | plugin(report-writeup) | Analytical | SCORE: 22/25 [A:5|C:4|Cs:5|D:4|Cp:4] -->
-
-# Experiment / data-analysis results — reusable template + guide
-
-One write-up shape for any analysis: A/B, DOE / full-factorial / fractional-factorial,
-regression, backtest, ablation, regression-test. Fill the blanks; delete the Method
-sub-lines that don't apply; never delete the honesty rails (n, direction legend,
-certainty, "not computed — why").
-
----
-
-## The template (copy below this line)
-
-```markdown
-# <test name> — results
-<!-- headline: DECISION: <build X / don't / inconclusive> · certainty: <high|medium|low> · n=<N> -->
-
-## Objective
-- **Testing:** <the one thing under test>
-- **Why:** <the recurring problem or the decision this informs>
-- **Payoff if it succeeds (user-visible):** <what changes for the end user / consumer>
-- **Decision this unblocks:** <what we do differently on a pass vs a fail>
-
-## What we did
-- **Analysis type:** <A/B | DOE full-factorial | fractional-factorial | regression | backtest | ablation | regression-test | other>
-- **Method (1 paragraph):** <how it ran, start to finish>
-- **Sample size n = <N>** (<unit: bugs / runs / requests / rows / sessions>)  ← never omit
-- **Arms / factors** (keep the line that fits your type):
-  - A/B: control = <...> · treatment(s) = <...>
-  - DOE/factorial: factors × levels = <...> · runs = <...> · design = <full | fractional res IV | ...>
-  - Regression: predictors = <...> · response = <...> · model = <OLS | logistic | ...>
-  - Backtest: data + window = <...> · in/out-of-sample split = <...>
-  - Ablation: component removed = <...> · baseline = <...>
-- **Held constant (confounds managed):** <model, environment, inputs, seed, …>
-- **Measurement:** <who/what scored, against what ground truth, and exactly how>
-  - Blinding: <none | labels withheld | fully blinded> — <if you claim blinded, say what made it so; if a tell leaked, say so>
-
-## Hypothesis
-- **Predicted:** <outcome> **because** <mechanism / prior reason>
-- **Pass means:** <what it implies> → **action:** <...>
-- **Fail means:** <what it implies> → **action:** <...>
-- **Pre-registered?** <yes + link | no> · decision rule fixed before running? <yes | no>
-
-## Results
-
-**Metric legend — state direction for EVERY metric (this is mandatory):**
-| Metric | Measures | Direction | Scale |
-|--------|----------|-----------|-------|
-| <m1> | <...> | higher better / lower better | <0–2 · % · ms · count · $> |
-| <cost> | effort/latency/$ | lower better (only counts when quality ties or wins) | <calls · s · $> |
-
-**Data:**
-| <arm / run / config> | <m1> | <m2> | <cost> |
-|---|---|---|---|
-| <...> | | | |
-
-**Statistics — fill what you actually computed; for the rest write "not computed — <why>":**
-- **Effect size:** <metric: value (e.g. Δ, Cohen's d, lift %)> | not computed — <why>
-- **Statistical significance:** <test, p-value, CI> | **NOT COMPUTABLE — n=<N> too small (directional only)**
-- **Correlation:** <vars: r> | not computed — <why>
-- **Goodness of fit** (regression only): <R², adj-R², residual check> | n/a
-- **Winner / direction:** <which, on which metrics>
-
-## Interpretation
-- **Certainty:** ✅ high | ⚠️ medium | ❓ low — <why, tied to n + method strength>
-- **What it shows / does NOT show:** <scope of the claim>
-- **Threats to validity / confounds:** <weak blinding (how), small n, self-selected subject, model substitution, single grader, …>
-- **Unknowns:** <what could not be verified>
-- **Honesty check:** every adjective here is earned by the method — no "fair / blind / significant / proven" unless the method above supports it.
-
-## Next steps
-- [ ] **Implement winner:** <...>  (or: do not implement — <why>)
-- [ ] **Stronger re-test:** <what raises certainty — larger n, cleaner blinding, a real significance test, second grader>
-- [ ] **New tests suggested:** <...>
-- [ ] **Risks to monitor after rollout:** <...>
-```
-
----
-
-## Usage guide
-
-1. **Pick one Method sub-line** for your analysis type; delete the others. The honesty
-   rails — `n`, the direction legend, the statistics block, certainty — stay regardless
-   of type.
-2. **Direction legend is not optional.** A table of numbers is unreadable without "higher
-   or lower better" per metric. Cost metrics (calls, time, $) are lower-better but only
-   count as a win when quality ties or improves (Accuracy > Speed > Cost).
-3. **When stats don't apply, say so explicitly** — never leave significance/correlation/
-   fit blank or imply them. Rules of thumb: significance/correlation need roughly n ≥ 8–10+
-   to mean anything; below that write "directional only (n too small)". Regression fit
-   (R²) is n/a unless you actually fit a model. DOE reports main effects + interactions,
-   not p-values, unless replicated.
-4. **Earn every adjective.** Do not write "fair", "blind", "robust", "significant", or
-   "proven" unless the Method section shows what made it so. If blinding leaked (e.g. the
-   treatment's output format was a tell), record it as a threat to validity — don't claim
-   blindness.
-5. **Headline = decision + certainty + n.** A decision-maker should get "build it / don't /
-   inconclusive", how sure, and on how much data, from the first line.
-6. **Pre-register when the result will drive a real decision** — commit Objective +
-   Hypothesis + decision rule before running, so the verdict can't be retrofit.

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

@@ -1,72 +0,0 @@
-<!-- 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

@@ -1,257 +0,0 @@
-<!-- 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.