@pilotspace/add 1.1.0 → 1.3.0

package/skill/add/graduate.md

@@ -0,0 +1,74 @@
+# Stage graduation — propose the move to production as a roadmap, never a flip
+
+A project does not become "production" because someone typed a new label. It graduates when
+the MVP is genuinely covered AND a human-confirmed roadmap of production work exists. This guide
+is the **4th scope level** — after setup (`phases/0-setup.md`), intake (`intake.md` / `scope.md`),
+and the milestone loop (`loop.md`). It turns the bare `add.py stage` flip into the **final step** of
+an analytics-driven, interview-led orchestration.
+
+You (the AI) **gather and propose**; the **human confirms and judges**; the engine only counts
+tallies and enforces the floor. The engine never decides that the project is "ready" — that is
+judgment, and it belongs to the interview.
+
+## The cue (what starts this)
+
+When every milestone is `done` AND the human's stage-goal-criteria in `PROJECT.md` are all `[x]`,
+`add.py status` prints:
+
+```
+  → MVP covered → propose graduation
+```
+
+That line is the trigger. Before both tallies complete, status is silent and nothing here applies
+(a project with no stage-goal-criteria block behaves exactly as today — grandfathered, zero change).
+
+## The flow
+
+1. **Gather the analytics** — run `add.py graduation-report` (add `--json` to branch on it). It
+   clusters the whole MVP loop's evidence into five labeled record-sets: open deltas by competency ·
+   open RISK-ACCEPTED waivers by expiry · RETRO records · verify residue · observe-loop coverage gaps.
+   It **gathers, never judges** — there is no readiness verdict to read; the records are what you
+   reason from.
+2. **Co-specify interview** — synthesize *"what production means HERE"* WITH the human, using the
+   gathered records as the agenda (the residue to harden, the coverage gaps to monitor, the open
+   deltas to consolidate). This synthesis is the judgment the engine refuses to make. Interview to real confidence —
+   do not guess what "production-ready" means for this project.
+3. **Draft the roadmap** — for each production outcome the interview surfaces, draft a production
+   milestone with the EXISTING command and goal-gate criteria:
+   `add.py new-milestone <slug> --stage production --goal "…"`, then write its exit criteria. The
+   roadmap is **≥1** milestone — the hardening work itself (SLOs, rollback tests, incident runbooks)
+   is what these milestones *contain*; this guide proposes them, it does not do them.
+4. **Human confirms** — present the roadmap via `report-template.md`, opening with the ARC
+   (goal · done · plan): the stage-graduation goal, the MVP coverage that earns the move, and the
+   plan the production milestones lay out. The human accepts, edits, or declines each drafted
+   milestone. No milestone is created without this; nothing advances on a draft the human has not confirmed.
+5. **Flip — the final step** — only now run `add.py stage production`. Because ≥1 production milestone
+   now exists, the guard passes and the transition is recorded. This is the orchestration's last act.
+
+## The floor (what the engine enforces)
+
+`add.py stage production` is **guarded**: it refuses with `stage_no_roadmap` (non-zero exit, state
+byte-unchanged) when zero milestones have `stage: production`. The check is a **tally** — "does a
+production-roadmap record exist?" — never a readiness judgment (gather-not-judge at stage level;
+it mirrors the milestone goal-gate's `milestone_goal_unmet`). `--force` overrides it, preserving human
+authority for grandfathered/edge cases; use it deliberately, not as the normal path.
+
+Scope: the guard is on the `→production` **transition** only. Flips to prototype/poc/mvp are the
+existing bare flip, unchanged. `add.py init --stage production` is an explicit at-creation declaration
+(the same authority as `--force`), not a transition — it is out of scope of the guard by design.
+
+## Invariants (never break these)
+
+- **The flip is the final step**, never called outside this confirmed-roadmap path. A bare flip with
+  no roadmap is the symptom this scope level removes.
+- **The engine never auto-flips.** Every step here is human-confirmed; the engine gathers, counts, and
+  enforces the floor — it does not advance the stage on its own.
+- **The flow is continuous, not cue-reentrant.** The moment you draft the first production milestone,
+  `status` stops printing the cue (the "every milestone done" tally breaks). That is expected — do NOT
+  re-await the cue after drafting; carry the flow straight through to confirm and flip.
+
+## Depth and reuse
+
+The same orchestration serves prototype→poc and poc→mvp; **mvp→production** is the rigorous proof
+case (every step at full depth + the observe loop). At lower stages, run it light — the shape is the
+same, the depth is less.

package/skill/add/intake.md

@@ -1,10 +1,19 @@
 # Intake — size a request into versioned scope
 
 Before a task exists, ADD turns a raw request into correctly-sized, versioned scope.
-This is the **intake altitude**: the per-task flow is phases 0–7; intake is the step
+This is the **intake level**: the per-task flow is phases 0–7; intake is the step
 *before* a task — request → milestone or task. You (the AI) **propose**; the human
 **confirms**. Never create scope without a confirmed proposal.
 
+## Interview before you size
+
+When the request arrives as a question, or its intent is not yet sharp enough to
+place in one bucket: explore it WITH the user before classifying. Reflect the
+intent you heard, name what seems in and out of scope, and offer 2–3 sized options
+with your own recommendation. Only then emit `{ bucket, rationale, command }`.
+`ask_human` stays the floor: when interviewing cannot sharpen the request,
+reject — never guess a bucket.
+
 ## The four buckets
 
 Classify every request into exactly ONE bucket:
@@ -24,17 +33,23 @@ First ask "does this change already-frozen scope?" → if yes, it is a `change-r
 
 ## What you emit (the proposal)
 
+Present the proposal to the human via `report-template.md` — open with the ARC (goal · done ·
+plan): the goal this request serves, what is already covered, and the plan the chosen bucket sets up.
+
 For every request, emit ONE of:
 
 - **a classification** — `{ bucket, rationale, command }` — where `rationale` names WHY
   (the theme, the slice, the fit, or the frozen scope touched) and `command` is the exact
   `add.py …` from the table. The human confirms or overrides before you run it.
-- **a rejection** — `{ reject, rationale }` — and you create nothing:
-  - `ask_human` — too ambiguous/underspecified to size. Ask the human; never guess a bucket.
-  - `frozen_scope` — it changes frozen scope; route it as a `change-request` back to
-    SPECIFY/CONTRACT of the affected task — never spawn a parallel milestone that forks the truth.
-  - `split_required` — it spans more than one bucket; propose the SMALLEST set of correctly-sized
-    items, each with its own rationale; never force it into one milestone.
+- **a rejection** — `{ reject, rationale }` — and you create nothing, emitting one of the closed set:
+
+<reject_codes>
+- `ask_human` — too ambiguous/underspecified to size. Ask the human; never guess a bucket.
+- `frozen_scope` — it changes frozen scope; route it as a `change-request` back to
+  SPECIFY/CONTRACT of the affected task — never spawn a parallel milestone that forks the truth.
+- `split_required` — it spans more than one bucket; propose the SMALLEST set of correctly-sized
+  items, each with its own rationale; never force it into one milestone.
+</reject_codes>
 
 When confirmed, record the `rationale` in the artifact you create or affect — the new
 MILESTONE.md goal/body, the new TASK.md, or a note in the affected TASK.md — never in state.json.

package/skill/add/loop.md

@@ -0,0 +1,59 @@
+# The dynamic loop — open deltas and extras become the next tasks
+
+A milestone is not done when its tasks are done — it is done when its **GOAL** is met.
+This guide is the loop that drives a milestone toward that goal: turn what each task
+leaves behind (open lessons, and work discovered but out of scope) into the next tasks,
+and keep going until the exit criteria are all met.
+
+You (the AI) **gather and propose**; the **human confirms**; the existing `add.py new-task`
+creates each one. The engine never decides what the next task is — that is judgment.
+
+## The goal-gate (what holds the loop open)
+
+`add.py milestone-done <slug>` REFUSES to close a milestone while its exit criteria are not
+all met — it stops with `milestone_goal_unmet` and the milestone stays active. The exit-criteria
+checkboxes in `MILESTONE.md` ARE the human's goal-met affirmation: the engine reads the
+`- [x]`/`- [ ]` tally, it never judges whether the goal is met (the same trust model as reading a
+recorded `PASS`). Checking the last box is the deliberate act that releases the gate.
+
+The gate fires only when criteria exist. A milestone with no exit-criteria checkboxes closes as
+before — write criteria into `MILESTONE.md` if you want the goal-gate to hold the milestone open.
+
+`milestone-done` is the only way a milestone reaches `done`; `archive-milestone` and `compact`
+both refuse a milestone that is not done. So the one gate is enough — there is no quiet way around it.
+
+## The loop
+
+When every task is done but the goal is not, `add.py status` shows
+`goal not met (m/n exit criteria)` where it would otherwise prompt to archive. That is the cue:
+
+1. **Gather** the carried inventory:
+   - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
+   - the planned-but-unscaffolded tasks — the plan-vs-state line in `add.py status`;
+   - any reopened task — one a deepened verify returned to the flow (see below).
+2. **Propose** the next tasks: for each carried item worth doing now, draft a one-line task
+   (slug + title + why) and show the human. Group the trivial ones; do not propose noise.
+3. **Confirm** — the human accepts, edits, or declines each. No task is created without this.
+4. **Create** each accepted task — `add.py new-task <slug> --title "..."` — and run it through
+   the normal flow (specify → … → verify).
+5. **Repeat** until the work the goal needs is done.
+6. **Close** — when the goal is genuinely met, check the exit-criteria boxes in `MILESTONE.md`,
+   then `add.py milestone-done <slug>` succeeds (then consolidate the open deltas and archive).
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the
+   milestone goal, the exit-criteria met that prove it, and the plan beyond the close.
+
+## Reopen is the verb; this loop is the trigger
+
+When a deepened verify (the no-skim wiring / dead-code / semantic check) finds a criterion unmet
+on a task already marked done, `add.py reopen <task> --to <phase> --reason "..."` returns it to the
+flow with a recorded reason and a reset gate. `reopen` is the recorded action; deciding WHEN to
+fire it — because a goal criterion is unmet — is this loop's job.
+
+## The reactivation residual (deferred)
+
+A reopen fired inside the loop happens while the milestone is still **active** — the goal-gate held
+it open, so it never reached done, and no reactivation is needed. The one residual — reopening a
+task inside a milestone that was already closed — is surfaced by `add.py check` (a done milestone
+with a live task reads as incoherent). Re-activating a closed milestone is **deferred**: resolve it
+by hand for now (the loop's own design keeps in-flight milestones open), until a later task makes
+milestone reactivation first-class.

package/skill/add/phases/0-ground.md

@@ -0,0 +1,66 @@
+# Phase 0 — Ground (the real codebase)
+
+Goal: before you specify anything, gather the REAL current working folder the task will
+touch — the actual files, symbols, signatures, docs, todos, config, data, patterns, and conventions — so the
+contract, tests, and build are grounded in what exists, not in what you assume.
+Fill **§0 GROUND** in TASK.md. Ground is a per-task preamble to the seven steps;
+it is **AI-owned** — no human gate here (the one approval stays at the §3 freeze).
+
+If you cannot name the files and symbols the task touches, you do not yet understand
+the work — gathering them IS the job, not a detour.
+
+## Gather (in TASK.md §0)
+
+- **Touches** — the real files · symbols · signatures the task will read or change,
+  named from the actual code (use your code-navigation tools — grep / symbol search,
+  never memory). Each as `path:symbol — what it is / how it is keyed`.
+- **Context (working folder)** — beyond code, the NON-code artifacts the task touches:
+  docs/textbase (README · `*.md` · design notes) · TODOs (`TODO.md` · `FIXME`/`TODO`/`HACK`
+  comments · task lists) · config/manifests (configs · `.env.example` · `pyproject`/`package`
+  · CI) · data/fixtures (samples · fixtures · schemas). Gather only the TASK-SPECIFIC
+  delta — never index the whole repo.
+- **Honors** — the patterns and conventions the work must respect, cited from
+  `PROJECT.md` / `CONVENTIONS.md`. Gather only the TASK-SPECIFIC delta — never
+  re-derive the architecture or re-run the setup brownfield scan.
+- **Anchors the contract cites** — the specific symbols §3 CONTRACT will name. The
+  contract may cite only anchors that appear here.
+
+**How — gather efficiently:** for the BROAD sweep, prefer a small-model subagent / fast
+index / skim (offload to a cheap context, return a compact map); then DEEPEN on what THIS
+task specifically needs — never lock a shallow first pass. A recommendation: the engine
+never spawns a subagent (tool-agnostic), so the orchestrating agent chooses.
+
+## Greenfield / first task
+
+The first task of a project runs ground too. When there is little or no code yet
+(greenfield), or you are mid-setup, your grounding IS the foundation docs / brownfield
+scan you just produced — point at them; do not re-scan. An honest "new module, no
+existing code; honors CONVENTIONS.md §X" is a complete grounding.
+
+## AI prompt
+
+<prompt>
+Role: an engineer who reads the real code before designing against it.
+Read first: PROJECT.md · CONVENTIONS.md · the actual files the task touches.
+Objective: fill §0 GROUND with the real files/symbols/signatures + the conventions to
+honor + the anchor points the contract will cite — gathered from the codebase, never assumed.
+Steps:
+  0. Sweep broad cheaply first — prefer a small-model subagent / fast index / skim — then deepen task-specifically.
+  1. Locate the files and symbols the task reads or changes (code tools, not memory).
+  2. Record their signatures / how they are keyed; cite the conventions to honor (task delta only).
+  3. Name the anchors §3 will cite.
+Never: invent a file, symbol, or signature you have not opened.
+</prompt>
+
+## Exit gate
+
+<exit_gate>
+- [ ] The real files/symbols the task touches are named (from the code, not assumed).
+- [ ] The conventions to honor are cited (task-delta only; no architecture re-scan).
+- [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
+</exit_gate>
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/1-specify.md`.
+Book: `docs/02-the-flow.md` (the flow; ground is the §0 preamble to the seven steps).

package/skill/add/phases/0-setup.md

@@ -1,14 +1,14 @@
-# Phase 0 — Setup (autonomous draft → one human lock-down)
+# Phase 0 — Setup (autonomous draft → one human baseline approval)
 
 Goal: point ADD at a repo and **you** draft the whole foundation — domain, first-milestone scope,
-and the first task's contract — then hand the human exactly one decision: the **lock-down**. Brownfield
+and the first task's contract — then hand the human exactly one decision: the **baseline approval**. Brownfield
 is silent (the code answers the questions); greenfield keeps a short interview. Either way, the human's
-only gate is `add.py lock`. This is the setup-altitude analog of a task's one-approval contract freeze.
+only gate is `add.py lock`. This is the setup-level analog of a task's one-approval contract freeze.
 
 ## 1 · Zero-touch entry — you run init yourself
 
 When there is no `.add/state.json`, do **not** tell the human to initialise — run it yourself. Infer the
-project name and stage from the repo, and **arm the lock-down gate** with `--await-lock`:
+project name and stage from the repo, and **arm the baseline-approval gate** with `--await-lock`:
 
 ```bash
 python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prototype|poc|mvp|production> --await-lock
@@ -27,16 +27,16 @@ python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prot
 
 ## 2a · Brownfield — map it silently
 
-The code answers the questions a greenfield interview would ask, so **read it, don't ask**. Open
-`adopt.md` and follow it: fill each survivor file from the code, never clobber an existing one, and tag
+The code answers the questions a greenfield interview would ask, so **read it instead of asking**. Open
+`adopt.md` and follow it: fill each living-doc file from the code, never clobber an existing one, and tag
 every decision `evidence-grounded` (cite the file) or `guessed`. Ask the human **nothing** at this step.
 
-## 2b · Greenfield — the 4-lens interview (kept): co-specify at foundation altitude
+## 2b · Greenfield — the 4-lens interview (kept): co-specify at foundation level
 
 An empty repo has no code to read, so run the short interview. This is the **co-specify at foundation
-altitude** move — the same diverge → converge → validate brainstorm a task's §1 uses (`phases/1-specify.md`),
+level** move — the same diverge → converge → validate brainstorm a task's §1 uses (`phases/1-specify.md`),
 lifted to the foundation. Ask the one load-bearing question per lens (diverge), draft the foundation
-(converge), then rank what you're least sure of and show the top flag first (validate):
+(converge), then rank where your confidence is lowest and show the top flag first (validate):
 
 | Lens | The one question that unblocks the section |
 |------|--------------------------------------------|
@@ -45,52 +45,59 @@ lifted to the foundation. Ask the one load-bearing question per lens (diverge),
 | Users (UDD) | The primary user and the one job they hire this for? (or "no UI — surface is X") |
 | Decisions | What's already decided that you'd regret re-litigating? (first Key Decision row) |
 
-Ask only the live ones; skip what the request already answers. Rank your drafts least-sure-first using the
-one notation every altitude shares — `⚠ <assumption> — least sure because <why>; if wrong: <cost>` — and
+Ask only the live ones; skip what the request already answers. Rank your drafts lowest-confidence-first using the
+one notation every scope level shares — `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — and
 tag thin or inferred answers `guessed`.
 
 ## 3 · Draft to the lock (both paths)
 
-1. **Fill the survivors** (they outlive all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
+1. **Fill the living documentation** (it outlives all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
    milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
-   `dependencies.allowlist`. Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
+   `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
+   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI).
+   Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
 2. **Size the first milestone** (read `scope.md`) and draft its `MILESTONE.md` — goal · scope · exit criteria
    · breadth-first tasks.
-3. **Create the first task and draft its candidate front.** `new-task` is allowed pre-lock:
+3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash
    python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
    ```
    Draft §1 (specify) · §2 (scenarios) · §3 (contract). **Leave §3 `Status: DRAFT`** — the lock is its
    approval (see §5). You MAY `advance` through specify → scenarios → contract → tests pre-lock, but the
-   engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: front → lock → build.
+   engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: bundle → lock → build.
 4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every decision you drafted (foundation, scope,
-   first contract), **least-sure-first**, each tagged `guessed` | `evidence-grounded`.
+   first contract), **lowest-confidence-first**, each tagged `guessed` | `evidence-grounded`.
 
-## 4 · The one human gate — the lock-down
+## 4 · The one human gate — the baseline approval
 
-Present `SETUP-REVIEW.md` least-sure-first (the `guessed` rows are what the human must actually check). They
-sign **once**:
+Open the report with the ARC (goal · done · plan) per `report-template.md`, then present
+`SETUP-REVIEW.md` lowest-confidence-first (the `guessed` rows are what the human must actually check). They
+confirm **once** — an explicit yes to the baseline approval itself, in conversation; ambient agreement mid-stream is
+not a confirmation. On that recorded confirmation, you run the lock with their name:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"
 ```
 
-`lock` records the lock layers (foundation · scope · contract) in one atomic write and opens the build. It is
-judgment-free — it does **not** parse `SETUP-REVIEW.md`; the human *reading* it is the review.
+Typing the command themselves stays the **escape hatch** — the decision is always the human's; you just
+execute it. `lock` records the lock layers (foundation · scope · contract) in one atomic write and opens the
+build. It is judgment-free — it does **not** parse `SETUP-REVIEW.md`; the human *reading* it is the review.
 
 ## 5 · After the lock
 
-- The lock **is** the first task's contract approval — the v7 one-approval-front and the lock-down collapse
+- The lock **is** the first task's contract approval — the v7 specification-bundle approval and the baseline approval collapse
   into this single signature. Do **not** ask for a separate contract-freeze sign-off (that double-gates).
 - Stamp the first task's §3 `Status: FROZEN @ v1` (lock-authorized), then read `phases/5-build.md` — build is
   now open. Everything before this signature, you drafted.
 
 ## Exit gate
 
+<exit_gate>
 - [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
-- [ ] Survivors filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
-- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written least-sure-first.
-- [ ] Human signed `add.py lock`; first task §3 `FROZEN @ v1`; build open.
+- [ ] Living docs filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
+- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
+- [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name; first task §3 `FROZEN @ v1`; build open.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/1-specify.md

@@ -11,42 +11,57 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 
 1. **Diverge** — before drafting, surface the decision space: the 2–3 genuine framings of the
    feature + the open questions you would otherwise guess. Invite the user to add, kill,
-   redirect. (Conversational — no new file. At prototype/poc this collapses to one sentence.)
-2. **Converge** — draft §1, then RANK what you are least sure about (below).
+   redirect. (Conversational — no new file. At prototype/poc this shortens to one sentence.)
+2. **Converge** — draft §1, then RANK where your confidence is lowest (below).
 3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
 
+**Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
+color, the core palette, the typeface — are human-owned. Surface them for discussion during
+Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
+is the user's call (`udd-tokens.md`).
+
 ## Produce (in TASK.md §1)
 
+<output_format>
 - **Framings weighed** — a one-line trace of what you considered: `X (chosen) · Y · Z`.
 - **Must** — each required behavior.
 - **Reject** — each refused input/situation, paired with a **named error code**
   (`amount <= 0 -> "amount_invalid"`, never "handle bad input").
 - **After** — the state that is true once it succeeds.
-- **Assumptions — least-sure first** — ranked most-likely-wrong → least. The top 1–2 carry a
-  `⚠` flag: `⚠ <assumption> — least sure because <why>; if wrong: <cost>`. The rest are the
-  low-stakes `[x]` tail. Never a flat wall of equal `[x]` ticks — that is what gets rubber-stamped.
+- **Assumptions — lowest-confidence first** — ranked most-likely-wrong → least. The top 1–2 carry a
+  `⚠` flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. The rest are the
+  low-stakes `[x]` tail. Keep the ranking visible — a flat list of equal `[x]` ticks gets approved without reading.
+</output_format>
 
-## The least-sure flag is bundle-wide
+## The lowest-confidence flag is bundle-wide
 
 The single human approval happens once, at the contract freeze, over the whole bundle. So your
-§1 ranking is the FIRST FEEDER into a bundle-level flag the user reads at the seam (`run.md`):
+§1 ranking is the first input into a bundle-level flag the user reads at the decision point (`run.md`):
 *"of everything I'm asking you to freeze, these 1–2 are most likely wrong."* A flag may point at
 a §1 assumption, an uncovered scenario, or the contract shape.
 
 ## AI prompt
 
-> Role: a domain analyst who brainstorms, then asks rather than assumes. Read CONVENTIONS,
-> GLOSSARY, and the user's raw input. First surface 2–3 framings + open questions and let me
-> react. Then produce §1: Framings weighed, every Must, every Reject with a named error code,
-> the After state, and the Assumptions RANKED least-sure first — flag the 1–2 you are least
-> sure about with why + cost. Never resolve an ambiguity by guessing.
+<prompt>
+Role: a domain analyst who brainstorms, then asks rather than assumes.
+Read first: CONVENTIONS · GLOSSARY · the user's raw input.
+Objective: fill §1 SPECIFY with zero ambiguity left for the AI to resolve by guessing.
+Steps:
+  1. Surface 2–3 framings + the open questions; let the user react before you draft.
+  2. Produce §1 — Framings weighed, every Must, every Reject with a named error code, the
+     After state, and the Assumptions RANKED lowest-confidence first.
+  3. Flag the 1–2 where your confidence is lowest, each with why + cost.
+Never: resolve an ambiguity by guessing.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Framings weighed noted; every required behavior stated.
 - [ ] Every rejection has a named error code; success state-change described.
-- [ ] Assumptions ordered least-sure first; the 1–2 `⚠` flags carry why + cost — or an honest
+- [ ] Assumptions ordered lowest-confidence first; the 1–2 `⚠` flags carry why + cost — or an honest
       "none material" that still names the single biggest risk (never a blank "none").
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/2-scenarios.md

@@ -6,6 +6,7 @@ generated from it. Fill **§2 SCENARIOS** in TASK.md.
 
 ## Produce (in TASK.md §2)
 
+<output_format>
 ```gherkin
 Scenario: <short name>
   Given <starting situation>
@@ -15,20 +16,29 @@ Scenario: <short name>
 ```
 
 The `And ... unchanged` clause catches corrupting partial failures (e.g. a balance
-deducted before a check fails). Never omit it on a rejection.
+deducted before a check fails). Include it on every rejection.
+</output_format>
 
 ## AI prompt
 
-> Role: a specification tester. Read §1 and GLOSSARY. Write one scenario per Must
-> and per Reject rule. For every rejection add an And-clause asserting what must NOT
-> change. Results must be specific and observable — never "then it works".
+<prompt>
+Role: a specification tester.
+Read first: §1 · GLOSSARY.
+Objective: one scenario per Must and per Reject rule, each result specific and observable.
+Steps:
+  1. Write one scenario per Must rule and one per Reject rule.
+  2. For every rejection add an And-clause asserting what must NOT change.
+Never: settle for a vague result ("then it works") — results must be specific and observable.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One scenario per Must rule.
 - [ ] One scenario per Reject rule.
 - [ ] Each result is a specific, observable fact.
 - [ ] Every rejection asserts what stays unchanged.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/3-contract.md

@@ -1,12 +1,13 @@
 # Phase 3 — Contract (freeze the shape)
 
 Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE
-it. This is the seam that makes the AI-led build safe: below it code is
+it. This is the decision point that makes the AI-led build safe: below it code is
 disposable; above it nothing breaks because the shape does not move. Fill
 **§3 CONTRACT** in TASK.md.
 
 ## Produce (in TASK.md §3)
 
+<output_format>
 - Interfaces (endpoints/functions/messages) with inputs/outputs.
 - Request/response shapes + persistent schema (note transactional needs).
 - Names drawn from `GLOSSARY.md` (same concept = same name everywhere).
@@ -14,42 +15,56 @@ disposable; above it nothing breaks because the shape does not move. Fill
 
 Then mark `Status: FROZEN @ v1`. Generate a mock + contract tests so dependent
 work can start before the real code exists.
+</output_format>
 
-**The freeze is the one approval.** This seam is where the single human approval lands, over the
-whole bundle (§1–§4). Before asking for it, present the bundle **least-sure first**: the 1–2 points
+**The freeze is the one approval.** This decision point is where the single human approval lands, over the
+whole bundle (§1–§4). Before asking for it, present the bundle **lowest-confidence first**: the 1–2 points
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
-eye before they freeze. See `run.md`.
+eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md` so the
+human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
+The approval also freezes the §5 Scope (may touch) + Strategy declarations — the bundle covers them.
 
 ## The freeze review checklist
 
-The human's one minute, aimed. Walk these six before saying yes:
+The human's one minute, aimed. Walk these seven before saying yes:
 
-- **⚠ flags first** — read the least-sure flags; accept each knowing its cost if wrong.
+- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong.
+  The engine refuses an unflagged freeze before build: a frozen §3 with no well-formed
+  lowest-confidence flag is rejected (`unflagged_freeze`), and `audit` re-checks it on every
+  record that crossed.
 - **Intent** — does §1 say what you actually want built (and is anything you expected missing)?
 - **Cases** — does every Must and Reject have an observable §2 scenario you care about?
 - **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
+- **Grounded** — does §3 cite anchors that exist in the §0 GROUND map (real files/symbols), not invented ones? `status`/`check` surface this — measure, never block.
 - **Risk** — is this scope high-risk or method-defining? Then require
   `risk: high · autonomy: conservative` in the TASK.md header — the engine refuses an unguarded completion.
 - **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
 
-This checklist AIMS the one approval — never a second gate, no sign-off forms, no
+This checklist AIMS the one approval — the freeze stays the only gate: no sign-off forms, no
 extra documents. Reject any line and the bundle goes back to draft; that is
 backward-correction, not failure.
 
 ## AI prompt
 
-> Role: an interface architect; frozen contracts are immutable. Read §1, §2,
-> GLOSSARY. Produce §3: interfaces, shapes, schema named from the glossary; a
-> response for every Reject code; a mock returning the contracted shapes and
-> contract tests pinning them. Mark FROZEN. No business logic. Never change a
-> frozen contract — a change reopens Specify.
+<prompt>
+Role: an interface architect; frozen contracts are immutable.
+Read first: §1 · §2 · GLOSSARY.
+Objective: produce §3 — the frozen external shape, nothing more.
+Steps:
+  1. Define interfaces, shapes, and schema named from the glossary, with a response for every Reject code.
+  2. Generate a mock returning the contracted shapes and contract tests pinning them.
+  3. Mark FROZEN. No business logic.
+Never: change a frozen contract — a change reopens Specify.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Versioned and marked `FROZEN`.
 - [ ] Contract tests pass against the mock.
 - [ ] Every name matches the glossary.
 - [ ] Every spec rejection has a contracted response.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/4-tests.md

@@ -1,4 +1,4 @@
-# Phase 4 — Tests (red safety net)
+# Phase 4 — Tests (failing-first suite)
 
 Goal: turn scenarios + contract into automated tests and confirm they FAIL before
 any code exists. This operationalizes red/green TDD: red now, green only after
@@ -12,10 +12,12 @@ before code exists is testing nothing and will wave bad code through later.
 
 ## Produce
 
+<output_format>
 - One executable test per scenario (§2), asserting **behavior, not internals**.
 - Contract-conformance tests (shapes + error responses from §3).
 - Side-effect assertions on rejection paths (`assert balance unchanged`).
 - A recorded coverage target in §4.
+</output_format>
 
 ## Declaring where tests live
 
@@ -33,17 +35,25 @@ symlink escapes are never read.
 
 ## AI prompt
 
-> Role: a test author who writes tests before code. Read §2 and §3. Turn each
-> scenario into an executable test; add contract-conformance and edge-case tests;
-> run the suite and confirm it fails for the right reason. Record a coverage
-> target. Do NOT implement the feature. Never assert on internals.
+<prompt>
+Role: a test author who writes tests before code.
+Read first: §2 · §3.
+Objective: a red suite that fails for the right reason — behavior, not internals.
+Steps:
+  1. Turn each scenario into an executable test.
+  2. Add contract-conformance and edge-case tests.
+  3. Run the suite and confirm it fails for the right reason; record a coverage target.
+Never: implement the feature, or assert on internals.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One test per scenario.
 - [ ] Suite runs and is **red for the right reason**.
 - [ ] Tests assert observable behavior.
 - [ ] Coverage target recorded.
+</exit_gate>
 
 ## Next