@pilotspace/add 1.1.0 → 1.2.0

package/skill/add/SKILL.md

@@ -34,7 +34,7 @@ python3 .add/tooling/add.py status
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
   `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
-  `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human lock-down.
+  `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human baseline approval.
 - **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
   marker, and read the matching `phases/<n>-<phase>.md`. Work *only* that phase.
 - **No active task** → first SIZE the request (see Intake below), then create the
@@ -45,8 +45,9 @@ python3 .add/tooling/add.py status
 When the user brings a raw request, classify it BEFORE making a milestone or task:
 read `intake.md` and place it in exactly one bucket — `new-major` · `sub-milestone`
 · `task` · `change-request` — then propose `{ bucket, rationale, command }` and let
-the human confirm. This is the intake altitude (request → versioned scope); see
-`intake.md` for the rubric, the tie-break order, and worked examples.
+the human confirm. This is the intake level (request → versioned scope); see
+`intake.md` for the rubric, the tie-break order, and worked examples. A question or
+unsharp intent? **Interview before you size** — explore and suggest first (`intake.md`).
 
 Once a request is classified `new-major`/`sub-milestone`, drafting the actual
 `MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks) is the second
@@ -59,57 +60,55 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 
 | Phase | Guide | Produces (TASK.md section) | Who leads |
 |-------|-------|----------------------------|-----------|
-| setup | `phases/0-setup.md` | `.add/` + survivors + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the lock-down) |
-| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | AI drafts (co-specify)† |
+| setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
+| specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
 | scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
-| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the seam)† |
+| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
 | tests | `phases/4-tests.md` | §4 + red suite in `tests/` | AI drafts† |
 | build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
 | verify | `phases/6-verify.md` | §6 checks + gate record | **AI auto-gates on evidence**; human on residue/security‡ |
 | observe | `phases/7-observe.md` | §7 spec delta | human + AI |
 
-† **One-approval front (v7).** §1–§4 are drafted by the AI as a single bundle and frozen
-together; the human gives **one approval, at the contract freeze** (the autonomy seam) — not
-three separate sign-offs. The AI presents the bundle least-sure-first. See `run.md`.
-‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS once
-the evidence is complete (all tests green · loops dry · no residue) — recorded as *auto-resolved*,
-an explicit PASS, not a skip. **Security always escalates** (HARD-STOP), as do concurrency /
-architecture residue and `conservative` autonomy. See `run.md`.
+† **The specification bundle (v7).** §1–§4 are one bundle; the human gives **one approval at the
+contract freeze** (the decision point), presented lowest-confidence-first. See `run.md`.
+‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS on
+complete evidence — recorded as *auto-resolved*, an explicit PASS, not a skip. **Security always
+escalates** (HARD-STOP); so do concurrency / architecture residue and `conservative` autonomy.
+See `run.md`.
 
-Whenever you present a seam to the human in chat (intake · front approval · gate ·
-milestone close), follow `report-template.md` — SUMMARY → DECISION → ⚠ FLAGS →
-EVIDENCE → NEXT, engine-sourced facts, show-before-ask, never pre-stamp a seam.
+Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
+milestone close), follow `report-template.md` — open with the ARC (goal · done · plan,
+engine-sourced), then SUMMARY → DECISION → ⚠ FLAGS → EVIDENCE → NEXT, show-before-ask, never
+pre-stamp a decision point — and the question is a summary, never the artifact.
 
-In **observe**, also emit **competency deltas** — learnings tagged by which of the five
+In **observe**, also emit **lessons learned** — learnings tagged by which of the five
 (`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
-You write them as `open`; the human folds them into `PROJECT.md`. Read `deltas.md` for the
-grammar and the status lifecycle. At milestone close (or on demand), run the fold ritual that
+You write them as `open`; the human consolidates them into `PROJECT.md`. Read `deltas.md` for the
+grammar and the status lifecycle. At milestone close (or on demand), run the retrospective consolidation that
 gathers confirmed deltas into a versioned foundation — read `fold.md`.
 
-## The dynamic run (v6–v7)
+## Beyond the bundle — load on demand
 
-Once **§3 CONTRACT is FROZEN**, the build→verify half runs as a dynamic, auto-gated run —
-fan-out + in-run convergence — instead of a manual build (`autonomy: auto` is the default; lower
-to `conservative` to keep a human at the gate). Read `run.md` for the trigger, the touch-boundary,
-the evidence auto-gate, and the autonomy dial. The human-led front still owns *direction*, but v7
-compresses it to a **single approval at the contract seam**; the run never edits a frozen contract
-and never auto-passes a security finding.
+Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
+(`autonomy: auto` default, lowered to `conservative` for a human gate) — read `run.md`. To
+pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
 
-## Parallel streams — pipelining independent tasks (opt-in)
+When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
+yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns
+open deltas + extras into the next tasks, proposed by you and confirmed by the human, until the goal is met.
 
-The default is one task at a time. When a milestone has several tasks whose `deps=` are
-already `PASS` and a human is ready to review, you MAY run them concurrently: read
-`streams.md`. It changes no `add.py` code — you compute a READY-QUEUE from `status`,
-spawn one worker per ready task (each in a worktree, building behind its own frozen
-contract), and keep the human seams (front approval · escalated Verify) on one serial
-REVIEW-QUEUE. The honest gain is pipelining (the reviewer never waits on a build), not
-N× speed; the autonomy dial sets how much actually overlaps.
+When `add.py status` prints **`MVP covered → propose graduation`** (every milestone done AND the
+stage-goal-criteria all `[x]`), the project is ready to graduate its stage — read `graduate.md` for the
+orchestration: gather `graduation-report` analytics → co-specify interview → draft ≥1 production
+milestone → human confirm → then (and only then) `stage production`. The flip is guarded
+(`stage_no_roadmap`) and is the FINAL step — never a bare label change.
 
 ## Non-negotiable rules (from the method)
 
+<constraints>
 1. **Direction before speed.** Never start Build until §1–§4 exist and tests are red.
 2. **Trust evidence, not inspection.** A feature is trusted because its tests pass
-   and the blind-spots (concurrency, security, architecture) were checked — not
+   and the non-functional risks (concurrency, security, architecture) were checked — not
    because the code reads plausibly.
 3. **Never weaken a test or edit a frozen contract to make the build pass.** That
    inverts the method. A real change is a *change request* back to Specify.
@@ -117,6 +116,7 @@ N× speed; the autonomy dial sets how much actually overlaps.
    `PASS`, `RISK-ACCEPTED` (signed, non-security only), or `HARD-STOP`. A security
    finding is always `HARD-STOP`.
 5. **Ask, don't guess.** If a requirement is unclear, stop and ask the user.
+</constraints>
 
 ## Advancing
 
@@ -136,9 +136,11 @@ The steps never change; their depth does. Read the stage from `add.py status`:
 - **prototype** — run light; code is throwaway; design/experience is the point.
 - **poc** — run contract/tests/build deeply on the single riskiest slice only.
 - **mvp** — full flow, narrow scope, light observation.
-- **production** — every step at full rigor + the observe loop.
+- **production** — every step at full rigor + the observe loop. Reach it via the graduation
+  orchestration (`graduate.md`) when status shows `MVP covered → propose graduation`, never a bare
+  `stage production` flip — the transition is guarded behind a human-confirmed roadmap.
 
-## The trust layer
+## The method rationale
 
 The full method (the *why* behind every rule) is the AIDD book in `.add/docs/`.
 When a phase decision is genuinely unclear, read the linked chapter — each phase

package/skill/add/adopt.md

@@ -3,8 +3,8 @@
 When ADD is pointed at a repo that already has code, onboarding is **silent**: the code
 answers the questions a greenfield interview would ask, so you read it rather than ask.
 This is the **brownfield path** of setup (the greenfield path keeps the 4-lens interview —
-see `phases/0-setup.md`). You fill the survivor files from evidence, then stop at the one
-human gate: the **lock-down** (`add.py lock`).
+see `phases/0-setup.md`). You fill the living-documentation files from evidence, then stop at the one
+human gate: the **baseline approval** (`add.py lock`).
 
 ## The signal — and arming the gate
 
@@ -14,7 +14,7 @@ Enter a brownfield repo with `--await-lock`:
 python3 .add/tooling/add.py init --await-lock
 ```
 
-`--await-lock` does two things. It seeds an **unlocked** setup, which *arms the lock-down gate*
+`--await-lock` does two things. It seeds an **unlocked** setup, which *arms the baseline-approval gate*
 — the engine then refuses a second task, crossing into build, and recording a gate until you
 `lock`. And init, being brownfield-aware, prints a line that begins:
 
@@ -29,9 +29,9 @@ code (a mechanical fact); it never reads or fills it — interpreting it is your
 
 ## The silent mapping
 
-Fill each survivor file in `.add/` from what the code actually shows — **ask nothing**:
+Fill each living-doc file in `.add/` from what the code actually shows — **ask nothing**:
 
-| Survivor | Read it from |
+| Living doc | Read it from |
 |----------|--------------|
 | `PROJECT.md` (foundation) | the domain nouns, entry points, the README, the first milestone the code implies |
 | `CONVENTIONS.md` | the languages, folder layout, naming, lint config, error style already in the tree |
@@ -41,19 +41,21 @@ Fill each survivor file in `.add/` from what the code actually shows — **ask n
 
 Two rules that never bend:
 
-1. **Never clobber a survivor.** `init` already skips any survivor that exists; if a human
+<constraints>
+1. **Never clobber a living doc.** `init` already skips any living-doc file that exists; if a human
    already wrote `PROJECT.md`, you READ it, you do not overwrite it. Add, never replace.
 2. **Tag every drafted decision `evidence-grounded` vs `guessed`.** A line you read from the
    code is *evidence-grounded* (cite the file). A line you inferred because the code was silent
-   is *guessed*. The human's single lock-down is only honest if they can see which is which —
+   is *guessed*. The human's single baseline approval is only honest if they can see which is which —
    the guesses are what they actually need to check. (The tags feed `SETUP-REVIEW.md`.)
+</constraints>
 
-## Where it ends — the lock-down
+## Where it ends — the baseline approval
 
 Brownfield onboarding draws no per-step approvals. You map the foundation, then draft the
-first milestone's scope and the first task's candidate front exactly as greenfield does, and
-present it all at **one** human gate. The human reviews the decisions (least-sure / `guessed`
-first) and signs:
+first milestone's scope and the first task's candidate specification bundle exactly as greenfield does, and
+present it all at **one** human gate. The human reviews the decisions (lowest-confidence / `guessed`
+first) and confirms in conversation; you run the lock with their name:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"

package/skill/add/deltas.md

@@ -1,12 +1,12 @@
-# Competency deltas — how each loop sharpens the foundation
+# Lessons learned — how each loop sharpens the foundation
 
-A **competency delta** is a single learning a task produces, tagged by which of ADD's five
+A **lesson learned** is a single learning a task produces, tagged by which of ADD's five
 competencies it improves. You write deltas in a task's **OBSERVE** phase; later, the
-`foundation-update-loop` gathers the confirmed ones and folds them into a versioned `PROJECT.md`.
+`foundation-update-loop` gathers the confirmed ones and consolidates them into a versioned `PROJECT.md`.
 This is how `DDD · SDD · UDD · TDD · ADD` stop being write-once and start converging.
 
 You (the AI) **emit** deltas as `open`. Only the **human** moves a delta to `folded` or `rejected`
-(folding into the foundation is judgment — see the verify/observe seam). You never self-fold.
+(consolidating into the foundation is judgment — see the verify/observe decision point). You never self-approve a consolidation.
 
 ## The grammar (frozen)
 
@@ -50,7 +50,7 @@ That is its home. Split genuinely separate learnings into separate deltas; never
 ```
 emit (OBSERVE)        human review (foundation-update-loop)
    open  ───────────▶  folded     (the learning is merged into PROJECT.md; version bumps)
-         └──────────▶  rejected   (considered and deliberately NOT folded — the trail is kept)
+         └──────────▶  rejected   (considered and deliberately NOT consolidated — the trail is kept)
 ```
 
 An `open` delta is a pending signal. `folded` and `rejected` are both human decisions; a `rejected`
@@ -60,9 +60,11 @@ delta is left in place (not deleted) so "we saw this and chose not to act" stays
 
 There is no engine validator yet, so before you record a delta, self-check it:
 
+<reject_codes>
 - `unknown_competency` — the tag is missing or not one of `DDD · SDD · UDD · TDD · ADD`. Fix the tag.
 - `no_evidence` — the `(evidence: …)` pointer is missing or empty. Add the proof, or drop the line.
 - `unknown_status` — the status is not `open | folded | rejected`. A fresh delta is `open`.
+</reject_codes>
 
 ## Worked example
 
@@ -75,5 +77,5 @@ A task that built a tenancy feature finished its OBSERVE phase with:
 ```
 
 Three learnings, three competencies, each with a pointer. At the next foundation update the human
-folded the DDD and TDD deltas into `PROJECT.md` (→ `folded`) and rejected the ADD one as a one-off
+consolidated the DDD and TDD deltas into `PROJECT.md` (→ `folded`) and rejected the ADD one as a one-off
 (→ `rejected`). The foundation got sharper; nothing was silently lost.

package/skill/add/fold.md

@@ -1,29 +1,29 @@
-# Folding deltas — how the foundation self-improves
+# Consolidating deltas — how the foundation self-improves
 
-This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` competency deltas in its
-OBSERVE phase); folding gathers the confirmed ones and writes them into a **versioned foundation**,
+This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` lessons learned in its
+OBSERVE phase); the retrospective consolidation gathers the confirmed ones and writes them into a **versioned foundation**,
 so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones instead of drifting.
 
-You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** fold.
-You never self-fold — folding is judgment (see the verify/observe seam).
+You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** consolidation.
+You never self-approve a consolidation — consolidating is judgment (see the verify/observe decision point).
 
-## When to fold
+## When to consolidate
 
 At **milestone close** (the natural "version bump to the foundation"), or **on demand** when open
-deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the ritual
+deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the consolidation
 lives here so the engine stays judgment-free.
 
 ## The ritual
 
-1. **Gather** — scan every task's OBSERVE `### Competency deltas` block for lines still `open`.
+1. **Gather** — scan every task's §7 OBSERVE block for lesson-learned lines still `open` (`add.py deltas` reads them by the machine heading).
 2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
 3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
 4. **Confirm** — the human accepts or declines each delta. No write happens without this.
 5. **Write** — append the accepted edits, flip each delta's status, and bump the version.
 
-## Fold routing (every competency has a home)
+## Consolidation routing (every competency has a home)
 
-| competency | folds into | how |
+| competency | consolidates into | how |
 |------------|-----------|-----|
 | `DDD` | `PROJECT.md` §Domain (DDD) | refine/append a model bullet |
 | `SDD` | `PROJECT.md` §Spec / Living Document (SDD) | refine/append a settled-vs-open line |
@@ -31,7 +31,7 @@ lives here so the engine stays judgment-free.
 | `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
 | `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
 
-**Every** fold — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
+**Every** consolidation — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
 (date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
 
 ## Status transitions & version
@@ -39,16 +39,18 @@ lives here so the engine stays judgment-free.
 - on **confirm**: the delta moves `open` → `folded` (and its edit is appended to the routed target).
 - on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
   so "we considered this and chose not to act" stays auditable.
-- a fold is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
-- each fold session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
+- a consolidation is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
+- each consolidation session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
 
 ## Reject codes (the AI is first check, the human the backstop)
 
+<reject_codes>
 - `no_open_deltas` — nothing is `open` anywhere. The ritual is a no-op; do **not** bump the version.
 - `unconfirmed_fold` — a write was attempted without recorded human confirmation. The AI proposes;
-  it never self-folds. Stop and get confirmation.
-- `unroutable_delta` — a delta's competency is not one of the five, so it has no fold target. Fix the
-  delta (it is malformed per `deltas.md`) before folding.
+  it never self-approves one. Stop and get confirmation.
+- `unroutable_delta` — a delta's competency is not one of the five, so it has no consolidation target. Fix the
+  delta (it is malformed per `deltas.md`) before consolidating.
+</reject_codes>
 
 ## Worked example (from this repo's own history)
 
@@ -60,7 +62,7 @@ which have no PROJECT.md section:
 - [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
 ```
 
-At the next fold the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
+At the next consolidation the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
 tree + assert md5 parity" convention), appends a §Key Decisions row for each, flips them to `folded`,
 and bumps `foundation-version` 1 → 2. The two competencies the foundation never tracked before now
 have a home — which is exactly why v5 routes TDD/ADD to `CONVENTIONS.md`.

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-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,57 @@ 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`.
 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