@pilotspace/add 1.8.0 → 1.10.0

package/skill/add/deltas.md

@@ -1,16 +1,12 @@
 # Lessons learned — how each loop sharpens the foundation
 
-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 consolidates them into a versioned `PROJECT.md`.
-This is how `DDD · SDD · UDD · TDD · ADD` stop being write-once and start converging.
+A **lesson learned** is a single learning a task produces, tagged by which of ADD's five competencies it improves. Write deltas in a task's **OBSERVE** phase; later, `fold.md` gathers 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`
-(consolidating into the foundation is judgment — see the verify/observe decision point). You never self-approve a consolidation.
+You **emit** deltas as `open`. Only the **human** moves a delta to `folded` or `rejected`. You never self-approve a consolidation.
 
 ## The grammar (frozen)
 
-Each delta begins on its own **tag line**; the learning may wrap onto continuation lines:
+Each delta begins on its own **tag line**; the learning may wrap:
 
 ```
 - [<COMPETENCY> · <status>] <learning> (evidence: <pointer>)
@@ -18,14 +14,10 @@ Each delta begins on its own **tag line**; the learning may wrap onto continuati
 
 - `<COMPETENCY>` — exactly one of the five (below).
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
-- `<learning>` — the insight ("the domain model missed multi-tenancy"). It may run past one line;
-  the `- [COMPETENCY · status]` tag line must come **first**, and the `(evidence: …)` clause must
-  **close** the delta (on its last line).
-- `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review
-  note. No evidence → it is an opinion, not a delta.
+- `<learning>` — the insight. The `- [COMPETENCY · status]` tag line comes **first**; `(evidence: …)` **closes** the delta.
+- `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review note. No evidence → it is an opinion, not a delta.
 
-A long learning may wrap — the lint (`add.py check`) joins continuation lines, so this is **one**
-delta, not two:
+A long learning may wrap — `add.py check` joins continuation lines, so this is **one** delta:
 
 ```
 - [SDD · open] the export endpoint must reject a tenant-scoped token used cross-tenant,
@@ -42,23 +34,19 @@ delta, not two:
 | `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
 | `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
 
-If a learning seems to touch two, ask "which competency, once updated, would have PREVENTED this?"
-That is its home. Split genuinely separate learnings into separate deltas; never tag one twice.
+If a learning touches two, ask "which competency, once updated, would have PREVENTED this?" — that is its home. Split separate learnings into separate deltas; never tag one twice.
 
 ## Status lifecycle
 
 ```
 emit (OBSERVE)        human review (foundation-update-loop)
-   open  ───────────▶  folded     (the learning is merged into PROJECT.md; version bumps)
-         └──────────▶  rejected   (considered and deliberately NOT consolidated — the trail is kept)
+   open  ───────────▶  folded     (learning merged into PROJECT.md; version bumps)
+         └──────────▶  rejected   (considered and deliberately NOT consolidated — trail kept)
 ```
 
-An `open` delta is a pending signal. `folded` and `rejected` are both human decisions; a `rejected`
-delta is left in place (not deleted) so "we saw this and chose not to act" stays auditable.
+A `rejected` delta is left in place (not deleted) so "we saw this and chose not to act" stays auditable.
 
-## Reject codes (well-formedness — you are the first check, the human is the backstop)
-
-There is no engine validator yet, so before you record a delta, self-check it:
+## Reject codes
 
 <reject_codes>
 - `unknown_competency` — the tag is missing or not one of `DDD · SDD · UDD · TDD · ADD`. Fix the tag.
@@ -68,14 +56,10 @@ There is no engine validator yet, so before you record a delta, self-check it:
 
 ## Worked example
 
-A task that built a tenancy feature finished its OBSERVE phase with:
-
 ```
 - [DDD · open] the account model conflated org and workspace (evidence: scenario_cross_tenant_read failed)
 - [TDD · open] no scenario covered a deleted tenant's dangling sessions (evidence: review note, PR thread)
 - [ADD · open] the scaffold's allow-list missed the tenancy lib, slowing build (evidence: build log retry)
 ```
 
-Three learnings, three competencies, each with a pointer. At the next foundation update the human
-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.
+At the next foundation update the human consolidated the DDD and TDD deltas (→ `folded`) and rejected the ADD one (→ `rejected`). The foundation got sharper; nothing was silently lost.

package/skill/add/design.md

@@ -2,14 +2,13 @@
 
 When a **UI feature** reaches specify, design it before you build it. This loop takes the
 feature from the **domain** to a screen the human has **seen and confirmed** — a real captured
-image — *before* any implementation, so the build matches the expected layout instead of
-discovering it. It is loaded on demand (like `advisor.md` / `confidence.md`); the engine never
-runs it for you.
+image — *before* any implementation. It is loaded on demand (like `advisor.md` / `confidence.md`);
+the engine never runs it for you.
 
 Design before code is the UDD half of the method. The token + component foundation a UI project
 draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-tokens.md`),
-`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop is how you *fill* that
-foundation for a feature and earn the human's sign-off on the look before build.
+`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop fills that foundation
+for a feature and earns the human's sign-off on the look before build.
 
 ## The loop — four beats
 
@@ -20,52 +19,47 @@ review-domain  →  research-components  →  wireframe  →  render-capture-con
 Run the beats in order. Each feeds the next; the last ends at a human design-confirm.
 
 ### 1 · review-domain
-Start from the **domain**, not from a blank canvas. Read the domain model — entities, flows, the
+Start from the **domain**, not a blank canvas. Read the domain model — entities, flows, the
 ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
 needs and the **regions** each screen holds. Map each domain entity to a *presentational*
 component (it shows state; it does not own a domain decision). The screen list + per-screen
-regions are this beat's output, and they are grounded in the domain you just read.
+regions are this beat's output, grounded in the domain you just read.
 
 ### 2 · research-components (reuse before you invent)
-Check `catalog.json` **first** and **reuse** the components already there — that is what keeps
-screens consistent. Research a reference UI (a websearch over pattern galleries / component
-libraries for this kind of screen) only to fill a **genuine gap**, and propose a **new** catalog
+Check `catalog.json` **first** and **reuse** the components already there — that keeps screens
+consistent. Research a reference UI only to fill a **genuine gap**, and propose a **new** catalog
 component for that gap with a **cited** reference. Reuse before invention; a new component is the
-exception, named and justified, not the default.
+exception, not the default.
 
 ### 3 · wireframe
 Draw a **low-fi**, **structural** layout for each screen — regions and component slots, no
-styling, no color. This is the cheapest possible artifact that shows the *expected layout*, so
-the human can correct the structure before a pixel is styled. Confirm the wireframe, then move on.
+styling, no color. This is the cheapest artifact that shows the *expected layout*, so the human
+can correct structure before a pixel is styled. Confirm the wireframe, then move on.
 
 ### 4 · render-capture-confirm
 Render the screen as a **self-contained HTML mock** — the project's component library via CDN,
 bound to `tokens.json` (resolved to CSS variables), composed from the **reusable per-component
 kit** (one token-bound partial per catalog component), populated with realistic **mock** data.
-**Capture** a real image of it (a headless screenshot) and present that image to the human for
+**Capture** a real image (a headless screenshot) and present that image to the human for
 **design-confirm** — show-before-ask, **before build**. On confirm, record the layout back to
 `prototypes/<name>.json` + `catalog.json`, save the captured image to
-`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`**
-(alongside the §6 evidence) — so the screen the human approved is traceable from the task that
-builds it. The HTML mock is the *visible evidence*; the json-render tree is the
-*machine-checkable* record of the same screen.
+`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`** —
+so the screen the human approved is traceable from the task that builds it. The HTML mock is the
+*visible evidence*; the json-render tree is the *machine-checkable* record.
 
 ## Tool-agnostic capture
 
-How you render and capture is **your** choice, not the engine's: a headless browser
-(Playwright / Puppeteer), an `html2image`-style renderer, a browser-automation skill, a design
-tool, or a hosted screenshot service — whatever the agent has. The recommended default is the
-self-contained HTML mock above, captured headless, because it needs no app build yet still wears
-the project's real tokens and component vocabulary. For a project that renders json-render, the
-recommended default is **`@json-render/image`** (Satori → PNG/SVG, no browser) — a deterministic
-`Spec` → image. The captured image is a **design-confirm evidence** artifact the human approves;
-it is never an engine output, and the engine never renders. This keeps the loop tool-agnostic and
-the method renderer-free.
-
-Captures live at **`.add/design/captures/<name>.<ext>`** (one per prototype) and are
-attached/mentioned in the feature's `TASK.md`. `add.py check` raises a never-red
-`missing_capture` WARN for any prototype under `.add/design/prototypes/` that still lacks a
-capture — a nudge to render + confirm it, never a blocker.
+How you render and capture is **your** choice: a headless browser (Playwright / Puppeteer), an
+`html2image`-style renderer, a browser-automation skill, a design tool, or a hosted screenshot
+service. The recommended default is the self-contained HTML mock above, captured headless,
+because it needs no app build yet still wears the project's real tokens and component vocabulary.
+For a project that renders json-render, the recommended default is **`@json-render/image`**
+(Satori → PNG/SVG, no browser). The captured image is **design-confirm evidence** the human
+approves; the engine never renders. This keeps the loop tool-agnostic and the method renderer-free.
+
+Captures live at **`.add/design/captures/<name>.<ext>`** and are attached/mentioned in the
+feature's `TASK.md`. `add.py check` raises a never-red `missing_capture` WARN for any prototype
+under `.add/design/prototypes/` that still lacks a capture — a nudge to render + confirm it.
 
 The loop **binds** the existing UDD contracts **read-only**: `tokens.json`, `catalog.json`, and
 `prototypes/<name>.json` are read and composed, never reshaped — the `prototypes/<name>.json`

package/skill/add/fold.md

@@ -1,86 +1,61 @@
 # Consolidating lessons — how the foundation self-improves
 
-This **closes the loop**. `deltas.md` lets a task EMIT lessons (`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.
+This **closes the loop**. `deltas.md` lets a task EMIT lessons (`open` lessons learned in OBSERVE); retrospective consolidation gathers the confirmed ones and writes them into a **versioned foundation**, so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones.
 
-Since v3 this is mechanized by a command — `add.py fold` — but the command stays **judgment-free**:
-it only ever TRANSCRIBES each lesson's OWN captured text into its routed home and bumps the version.
-It NEVER composes or merges prose, and it never **self-approves** a consolidation — running the
-command records the human's confirmation, it does not replace their judgment. Deciding WHICH lessons
-to keep, and later polishing the raw transcribed bullets into lean one-screen prose, remain the
-human's work — the latter via the **compaction door** (`compact-foundation.md`).
+`add.py fold` is **judgment-free**: it only TRANSCRIBES each lesson's own captured text into its routed home and bumps the version. It NEVER composes or merges prose, and it **never self-approves** a consolidation — running the command records the human's confirmation. Deciding WHICH lessons to keep, and polishing raw transcribed bullets into lean one-screen prose, remain the human's work — the latter via the **compaction door** (`compact-foundation.md`).
 
 ## When to consolidate
 
-At **milestone close** (the natural "version bump to the foundation"), or **on demand** when open
-lessons have piled up. One run of `add.py fold` is ONE consolidation session: it bumps
-`foundation-version` exactly once and stamps every lesson it resolves with that one new version.
+At **milestone close** (the natural version bump), or **on demand** when open lessons pile up. One run of `add.py fold` = ONE consolidation session: bumps `foundation-version` exactly once and stamps every resolved lesson with that version.
 
 ## The ritual
 
-1. **Gather** — `add.py deltas` reads every task's OBSERVE block for lessons still `open` (by the machine heading).
-2. **Confirm** — decide which to keep; a lesson you do NOT want is marked `rejected` and left in place
-   (see below). Running `add.py fold` over the rest IS your confirmation — the command needs no separate flag.
+1. **Gather** — `add.py deltas` reads every task's OBSERVE block for lessons still `open`.
+2. **Confirm** — decide which to keep; a lesson you do NOT want is marked `rejected` and left in place. Running `add.py fold` over the rest IS your confirmation.
 3. **Write** — `add.py fold [--task <slug>] [--comp <TAG>]` performs the mechanical write atomically:
    - flips each selected `open` lesson to `folded` and stamps it `[folded foundation-version N]`;
-   - transcribes each lesson VERBATIM as one bullet at the TOP (newest-first) of its routed section (below);
+   - transcribes each lesson VERBATIM as one bullet at the TOP (newest-first) of its routed section;
    - prepends one row to §Key Decisions (date · what · why · outcome);
    - bumps `foundation-version` by one.
-   Validate-all-then-write: if any precondition fails the command writes NOTHING (the tree stays byte-identical).
-4. **Propose & polish** — the transcribed bullets are RAW; afterward you consolidate/merge them into
-   lean prose (append-only, newest-first) via the compaction door. The engine never does this editorial step.
+   Validate-all-then-write: if any precondition fails the command writes NOTHING.
+4. **Propose & polish** — transcribed bullets are RAW; afterward consolidate/merge into lean prose (append-only, newest-first) via the compaction door.
 
-## Consolidation routing (every competency has a home)
+## Consolidation routing
 
 | competency | consolidates into | how |
 |------------|-----------|-----|
-| `DDD` | `PROJECT.md` §Domain | a transcribed bullet at the top |
-| `SDD` | `PROJECT.md` §Spec | a transcribed bullet at the top |
-| `UDD` | `PROJECT.md` §Users | a transcribed bullet at the top |
-| `TDD` | `CONVENTIONS.md` §Method learnings | a transcribed bullet (no PROJECT.md section — it is the engine) |
-| `ADD` | `CONVENTIONS.md` §Method learnings | a transcribed bullet (likewise the engine) |
+| `DDD` | `PROJECT.md` §Domain | transcribed bullet at the top (newest-first) |
+| `SDD` | `PROJECT.md` §Spec | transcribed bullet at the top |
+| `UDD` | `PROJECT.md` §Users | transcribed bullet at the top |
+| `TDD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
+| `ADD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
 
-**Every** consolidation — whatever the competency — ALSO prepends one row at the TOP of `PROJECT.md`
-**§Key Decisions** (newest-first) (date · decision · why · outcome): the universal, auditable trail of
-what the foundation learned.
+Every consolidation ALSO prepends one row at the TOP of `PROJECT.md` §Key Decisions: date · decision · why · outcome.
 
 ## Status transitions & version
 
-- on **confirm**: the lesson moves `open` → `folded` (its text transcribed at the top of the routed target, newest-first).
-- on **decline**: the lesson moves `open` → `rejected` and is **left in place** — never deleted —
-  so "we considered this and chose not to act" stays auditable.
-- a consolidation is **append-only (newest-first)**: it PREPENDS new bullets/rows at the top and never
-  silently rewrites existing foundation text — EXCEPT via the recorded **compaction door** (`compact-foundation.md`):
-  eligible (shipped + zero open residues) stable entries collapse upward into a rolled-up settled line at the tail.
-- each `add.py fold` run **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
+- **confirm**: `open` → `folded` (text transcribed at top of routed target, newest-first).
+- **decline**: `open` → `rejected`, left in place — "we considered and chose not to act" stays auditable.
+- Consolidation is **append-only (newest-first)**: PREPENDS new bullets/rows, never silently rewrites — EXCEPT via the recorded compaction door.
+- Each `add.py fold` run **bumps** `foundation-version:` in `PROJECT.md` by one (monotonic int).
 
-## Reject codes (the command is fail-closed; validate-all-then-write)
+## Reject codes
 
 <reject_codes>
-- `no_open_deltas` — nothing is `open` in the selected scope. The session is a no-op; the version is NOT bumped.
-- `missing_route_section` — a lesson routes to a foundation section that does not exist (e.g. a `UDD`
-  lesson with no `## Users` section). Fail-closed: add the section header, then re-run. Nothing is written.
+- `no_open_deltas` — nothing is `open` in the selected scope. Version is NOT bumped.
+- `missing_route_section` — a lesson routes to a foundation section that does not exist. Add the section header, then re-run. Nothing is written.
 - `no_foundation_version` — `PROJECT.md` carries no parseable `foundation-version:` marker to bump.
 </reject_codes>
 
-The convention-era codes `unconfirmed_fold` and `unroutable_delta` are **retired** (bridged here, not
-silently dropped): invoking `add.py fold` IS the confirmation, so `unconfirmed_fold` no longer applies;
-and routing is total over the five competencies, so a missing destination surfaces as the more precise
-`missing_route_section` rather than `unroutable_delta`.
+Convention-era codes `unconfirmed_fold` and `unroutable_delta` are **retired**: invoking `add.py fold` IS the confirmation; a missing destination surfaces as `missing_route_section`.
 
-## Worked example (from this repo's own history)
+## Worked example
 
-The `competency-deltas` task closed its OBSERVE with two lessons — the homeless ones, `TDD`/`ADD`,
-which have no PROJECT.md section:
+The `competency-deltas` task closed its OBSERVE with two lessons:
 
 ```
 - [ADD · open] dogfood .add/tooling template can silently diverge from canonical (evidence: md5 mismatch this build)
 - [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
 ```
 
-At the next consolidation the human keeps both and runs `add.py fold`. Routing transcribes each into
-`CONVENTIONS.md` §Method learnings, prepends a §Key Decisions row, flips them to `folded` with a
-`[folded foundation-version N]` stamp, and bumps `foundation-version` 1 → 2 — all in one atomic write.
-The two competencies the foundation never tracked before now have a home — which is exactly why v5
-routes `TDD`/`ADD` to `CONVENTIONS.md`.
+The human keeps both and runs `add.py fold`. Routing transcribes each into `CONVENTIONS.md` §Method learnings, prepends a §Key Decisions row, flips them to `folded` with `[folded foundation-version N]`, and bumps `foundation-version` 1 → 2 — all in one atomic write.

package/skill/add/graduate.md

@@ -1,75 +1,39 @@
 # 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.
+A project graduates when the MVP is genuinely covered AND a human-confirmed roadmap of production work exists. This is the **4th scope level** — after setup, intake/scope, and the milestone loop. 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.
+You **gather and propose**; the **human confirms and judges**; the engine only counts tallies and enforces the floor. The engine never decides "ready" — that is judgment, and it belongs to the interview.
 
-## The cue (what starts this)
+## The cue
 
-When every milestone is `done` AND the human's stage-goal-criteria in `PROJECT.md` are all `[x]`,
-`add.py status` prints:
+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).
+Before both tallies complete, status is silent. A project with no stage-goal-criteria block is 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. Render the roadmap as a guided choice — the recommended path
-   + its described alternatives (per `report-template.md`). 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.
+1. **Gather** — run `add.py graduation-report` (`--json` to branch on it). Clusters the MVP loop's evidence: open deltas by competency · open RISK-ACCEPTED waivers · RETRO records · verify residue · observe-loop coverage gaps. Gathers, never judges.
+2. **Co-specify interview** — synthesize *"what production means HERE"* WITH the human, using the gathered records as the agenda. 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: `add.py new-milestone <slug> --stage production --goal "…"`, then write its exit criteria. The roadmap is **≥1** milestone containing the hardening work (SLOs, rollback tests, incident runbooks).
+4. **Human confirms** — present the roadmap via `report-template.md`, opening with the ARC (goal · done · plan). Render as a guided choice (per `report-template.md`). Nothing advances on an unconfirmed draft.
+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.
 
-## The floor (what the engine enforces)
+## The floor
 
-`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.
+`add.py stage production` is **guarded**: refuses with `stage_no_roadmap` when zero milestones have `stage: production`. The check is a tally, never a readiness judgment. `--force` overrides for grandfathered/edge cases.
 
-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.
+Guard is on the `→production` transition only. Flips to prototype/poc/mvp are unchanged. `add.py init --stage production` is an explicit at-creation declaration — out of scope of the guard.
 
-## Invariants (never break these)
+## Invariants
 
-- **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.
+- **The flip is the final step**, never called outside this confirmed-roadmap path.
+- **No auto-flip.** Every step 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.** Once you draft the first production milestone, `status` stops printing the cue. Do NOT re-await the cue; carry 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.
+The same orchestration serves prototype→poc and poc→mvp; **mvp→production** is the rigorous proof case. At lower stages, run it light — same shape, less depth.

package/skill/add/intake.md

@@ -1,18 +1,16 @@
 # 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 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.
+Before a task exists, ADD turns a raw request into correctly-sized, versioned scope — the
+**intake level** (the per-task flow is phases 0–7; intake is the step *before* a 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.
+When the request arrives as a question, or its intent is not 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
 
@@ -25,40 +23,38 @@ Classify every request into exactly ONE bucket:
 | `task` | fits within the ACTIVE milestone's stated scope | `add.py new-task <slug>` |
 | `change-request` | modifies ALREADY-FROZEN scope (a frozen contract or a shipped promise) | `add.py phase specify\|contract <affected>` |
 
-**Tie-break order: the frozen-scope test runs FIRST, before the size test.**
-First ask "does this change already-frozen scope?" → if yes, it is a `change-request`
-(never re-size frozen work as new scope). Only if no, apply the size test: a new theme
-→ `new-major`; a slice of a live theme → `sub-milestone`; fits the active milestone
-→ `task`.
+**Tie-break order: the frozen-scope test runs FIRST, before the size test.** Ask "does this change
+already-frozen scope?" → if yes it is a `change-request` (never re-size frozen work as new scope).
+Only if no, apply the size test: a new theme → `new-major`; a slice of a live theme → `sub-milestone`;
+fits the active milestone → `task`.
 
-**One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's
-stated scope, do NOT force it into `sub-milestone` (which requires "too big for one task").
-Instead: create a new micro-milestone to house it (`new-milestone` + `new-task`). The
-micro-milestone gives the task ledger attribution and clear exit criteria without inflating scope.
+**One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's stated
+scope, do not force it into `sub-milestone` (which requires "too big for one task"): create a new
+micro-milestone to house it (`new-milestone` + `new-task`) — that gives the task ledger attribution
+and clear exit criteria without inflating scope.
 
 ## 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.
-Render the proposal as a guided choice — the recommended bucket + its described alternatives (per `report-template.md`).
+Present the proposal 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. Render it as a guided
+choice — the recommended bucket + its described alternatives (per `report-template.md`). For every
+request, emit ONE of:
 
-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, emitting one of the closed set:
+- **a classification** — `{ bucket, rationale, command }` — `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 }` — create nothing, from this 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.
+- `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.
+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.
 
 ## Worked examples (from this project's own history)
 

package/skill/add/loop.md

@@ -1,11 +1,11 @@
 # 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.
+This guide 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`
+You **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)
@@ -13,19 +13,19 @@ creates each one. The engine never decides what the next task is — that is jud
 `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.
+`- [x]`/`- [ ]` tally, it never judges whether the goal is met. 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.
+both refuse a milestone that is not done. 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:
+`goal not met (m/n exit criteria)`. That is the cue:
 
 1. **Gather** the carried inventory:
    - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
@@ -38,36 +38,32 @@ When every task is done but the goal is not, `add.py status` shows
    the normal flow (specify → … → verify).
 5. **Repeat** until the work the goal needs is done.
 6. **Close** — when the goal is genuinely met, run the **ship review** before you close:
-   - **Fill the ship review first** — write the milestone's `## Close — ship review` section (the
-     scaffold ships in `MILESTONE.md`): **Ship by domain** — what changed per bounded context
-     (`tooling` · `skill` · `book`, or "untouched"); **Cross-task evidence** — one row per task
-     (`gate` · `tests` · `residue`); and the **Goal met?** map — each exit criterion tied to the
-     evidence that satisfies it. This is the whole-milestone, cross-task evidence the human READS;
-     it is evidence, **not a new gate**.
+   - **Fill the ship review first** — write the milestone's `## Close — ship review` section:
+     **Ship by domain** — what changed per bounded context (`tooling` · `skill` · `book`, or
+     "untouched"); **Cross-task evidence** — one row per task (`gate` · `tests` · `residue`);
+     and the **Goal met?** map — each exit criterion tied to the evidence that satisfies it.
+     This is the whole-milestone cross-task evidence the human READS; it is evidence, not a gate.
    - **Check the boxes** — read that evidence, then check the exit-criteria boxes in `MILESTONE.md`
-     (the single affirmation — the same gate as ever), and `add.py milestone-done <slug>` succeeds
-     (then consolidate the open deltas and archive — the `milestone-done → fold → compact → archive`
-     lifecycle, per `fold.md` · `compact-foundation.md`).
-   - **Define the release steps** — write the milestone's `## Release steps` (merge is one small step
-     among them; PR, asset export, tag/publish are others — tool-agnostic hints the human runs).
-     These **feed** the release scope — read `release.md` for the cut; loop.md never re-specifies it.
-   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the milestone
-   goal, the exit-criteria met (with the ship-review evidence) that prove it, and the plan beyond the
-   close. Render the close as a guided choice — the recommended next move + its described alternatives
-   (per `report-template.md`).
+     (the single affirmation), and `add.py milestone-done <slug>` succeeds (then consolidate open
+     deltas and archive — the `milestone-done → fold → compact → archive` lifecycle, per
+     `fold.md` · `compact-foundation.md`).
+   - **Define the release steps** — write the milestone's `## Release steps` (merge is one small
+     step among them; PR, asset export, tag/publish are others). These **feed** the release scope —
+     read `release.md` for the cut; loop.md never re-specifies it.
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan) and
+   render as a guided choice (recommended next move + described alternatives).
 
 ## 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.
+When a deepened verify 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. 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.
+A reopen fired inside the loop happens while the milestone is still **active** — the goal-gate
+held it open, so it never reached done. 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,
+until a later task makes milestone reactivation first-class.