@pilotspace/add 1.7.3 → 1.9.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.9.0] — 2026-06-24
+
+Lean-pass major — make ADD's own surface (skill · flow · engine) the most-effective
+prompt at optimized token cost, *not* token-golf. Bundles four closed milestones:
+`skill-effectiveness` (M1), `flow-simplification` (M3), `flow-enforcement` (M4), and
+the `fast-lane` sub-milestone. The skill tree routes identically but loads lighter;
+the method's three fill-seams are now engine-enforced rather than convention; and a
+new opt-in **fast lane** collapses ceremony for small tasks without lowering the trust
+floor. Every new gate is opt-in or grandfathered — existing flows are byte-unchanged.
+
+### Added
+- **Fast lane (`fast-lane`)** — `add.py new-task <slug> --fast` runs a small task
+  through a minimal `TASK.fast.md` (sections {0,1,3,4,5,6}) that still freezes a
+  contract, proves a red→green, and reads back cold in a later session. The lane is
+  *collapse-never-skip*: a `--fast` task is freeze-gated under ANY milestone (the floor
+  fires on `_optin OR fast`). Human-triggered only — the engine never auto-classifies a
+  task as "small". New `phases/fast-lane.md` guide + a SKILL.md quick-ref document it.
+- **Freeze-before-build gate (`fast-lane`)** — crossing tests→build now refuses
+  `contract_not_frozen` when §3 is still DRAFT and the task is opted-in or fast, closing
+  the gap where a task could reach `gate=PASS` without an approved, frozen contract.
+- **Contract-fill + build-expectations gates (opt-in, `flow-enforcement`)** — under
+  `new-milestone --await-confirm`, the engine HOLDS a task whose §3 CONTRACT or §6
+  Build-expectations block is still a placeholder, so the method's fill-seams are
+  enforced rather than trusted. `await_confirm` is the master switch; without it no key
+  is written → grandfathered → byte-unchanged.
+- **Gate-record write-back (`flow-enforcement`)** — recording a verify gate now stamps
+  the verdict into the §6 GATE RECORD of the TASK.md for ALL tasks (grandfathered
+  backfill), so the file itself carries the outcome the Seam audit reads.
+- **Confirm-parent gate (opt-in, `flow-simplification`)** — `new-milestone <slug>
+  --await-confirm` seeds the milestone *unconfirmed*, so `new-task` is HELD (reject
+  `milestone_unconfirmed`) until you show the filled `MILESTONE.md`, get the human's go,
+  and run the new `add.py milestone-confirm <slug>`. Closes the gap where the AI would
+  detail a task's §0–§5 before the human had agreed the parent milestone. Mirrors
+  `init --await-lock` one level down.
+
+### Changed
+- **Skill tree 25% lighter (`skill-effectiveness`)** — the on-demand skill guides were
+  compacted tree-wide (164,333 → ~123,000 bytes) with zero routing, gate, reject-code,
+  threshold, or rule lost; an independent adversarial review confirmed every operative
+  element preserved (it flagged 6 dropped nuances → all restored). Same flow an agent
+  reads, fewer tokens to load.
+- **One home for the worker-spawn model tiers (`spawn-fold`)** — the tier→model mapping
+  (mid→sonnet / top→opus) now lives only in `streams.md`; `advisor.md` points at it
+  instead of copying. Advisor keeps its own advisory template.
+
+## [1.8.0] — 2026-06-23
+
+Team collaboration: ADD becomes git-native and multi-user, with N
+parallel-active milestones, plus a polish pass on the delta-resolution
+machinery. Additive and backward-compatible — `add.py` ships a one-way state
+migration (single-active → multi-active), and the non-interactive byte stream
+for existing single-user flows is preserved. Bundles six closed milestones.
+
+### Added
+- **Multi-active milestones (`team-collaboration`)** — work N milestones in
+  parallel: `add.py activate` / `deactivate` manage an active working SET,
+  `add.py mine` is a my-work lens over owned tasks, the `streams:` block shows a
+  per-stream owner, and waves can span all active milestones.
+- **Git-native user identity** — `add.py whoami` resolves the actor from git
+  config; tasks carry an owner.
+- **Ownership & assignment** — `add.py assign` / `unassign` attach a task to an
+  owner; ownership renders across status and reports.
+- **Git-merge safety** — merge-base enforcement guards a stale worker base; the
+  drift vectors a parallel-wave merge can introduce are pinned suite fixtures.
+- **Multi-file commit primitive** — `_atomic_write_many` is now true
+  all-or-nothing: stage every temp → fsync → rename-aside → rename-all, with
+  rollback-on-any-failure restoring prior bytes. `fold`, `release`, and the
+  delta seed all route through it, closing the prior mid-rename residual window.
+- **`--match <substr>` selector** — `add.py new-task --from-delta` and
+  `add.py drop-delta` accept `--match` to target ONE open SPEC delta among
+  several; a 0-match or ambiguous match is a named reject. First-open behavior
+  is byte-identical when `--match` is absent.
+- **`compact --force`** — `add.py compact --force` overrides the project-wide
+  `open_spec_deltas_unresolved` block ONLY (never a structural guard) so an
+  urgent compaction is not blocked by an UNRELATED open SPEC delta; the bypass
+  is warned and recorded as `force_bypassed_spec_deltas`.
+
+### Notes
+- One version tag publishes both channels: `@pilotspace/add` (npm) and
+  `pilotspace-add` (PyPI). The engine (`add.py`) is mirrored byte-identical
+  across all three trees with `ENGINE_MD5` re-pinned.
+
 ## [1.7.3] — 2026-06-18
 
 Multi-agent installer reach (`multi-agent-installer`). Additive; no breaking

package/docs/appendix-c-glossary.md

@@ -22,6 +22,8 @@
 
 **Foundation version** — a monotonic integer marker in `PROJECT.md` that advances by one each time confirmed lessons learned are consolidated into the foundation. It makes the living documentation's evolution auditable: a rising version with fewer new deltas per milestone is the signal that a competency is converging rather than drifting. Bumped only by the retrospective consolidation (see the `add` skill's `fold.md`).
 
+**Fast lane** — the collapsed, opt-in task path for small, low-risk work. `add.py new-task <slug> --fast` scaffolds a minimal `TASK.fast.md` (sections {0,1,3,4,5,6}; scenarios and observe dropped) and the specification bundle is approved in one freeze. It runs the SAME flow with fewer sections — it never drops the trust floor: a `--fast` task is held to a frozen contract, a red test before build, and a recorded verify gate under any milestone. Collapse, never skip; the human opts in (the engine never auto-classifies a task as small). See the `add` skill's `phases/fast-lane.md`.
+
 **Gate** — a checkpoint with an explicit pass/fail exit. Its outcome is `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`.
 
 **Ground (phase-0 preamble)** — the per-task phase *before* Specify in which the AI gathers the real current codebase the task touches — files, symbols, signatures, patterns, conventions — into a lean **grounding map**, surfacing the **anchors** the frozen contract will cite. It is AI-owned and adds no approval (the one approval stays at the contract freeze); it precedes the seven steps as step 0 so the contract, tests, and build are grounded in the code as it actually is, not in assumption. Lives in the `add` skill's `phases/0-ground.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.7.3",
+  "version": "1.9.0",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -15,79 +15,64 @@ user-invocable: true
 when_to_use: "Invoke in any repo with a `.add/` directory, or when the user wants spec/tests-first feature work, resumes ADD work, or asks to start/advance a task."
 category: workflows
 keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, scenarios, verify, milestone, task-orchestration]
-argument-hint: "[describe your goals] OR [describe what is your expectation] (e.g., implement authentication flows for both server api and client side to handle email + Google OAuth login, session refresh, RBAC guards, and a profile page that survives page reloads)"
+argument-hint: "status | init | continue | [describe new short goals or expectation]"
 license: MIT
 metadata:
   author: add
-  version: "1.0.0"
+  version: "1.8.0"
 ---
 
 # ADD — the orchestration engine
 
 You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
-(spec, scenarios, contract, failing tests) **before** the build, and trusting
-the result through passing evidence rather than a plausible-looking diff.
+(spec, scenarios, contract, failing tests) **before** the build, and trusting the
+result through passing evidence rather than a plausible-looking diff.
 
-**One file = one task.** Each feature lives in a single `.add/tasks/<slug>/TASK.md`
-with a §0 ground preamble and seven step sections. You fill them top to bottom; the Python tool tracks where
-you are so context never rots across sessions.
+**One file = one task.** Each feature is one `.add/tasks/<slug>/TASK.md` — a §0 ground
+preamble plus seven step sections, filled top to bottom. The Python tool tracks where you
+are so context never rots across sessions.
 
 ## Always start here (orient — do not skip)
 
-The engine lives at `.add/tooling/add.py` and the book at `.add/docs/`. Make sure the
-engine is in this project before anything else:
+Engine: `.add/tooling/add.py` · book: `.add/docs/`. Ensure the engine is in the project first:
 
-- If `.add/tooling/add.py` exists, go straight to `status` below.
-- If it does NOT exist, ADD was installed as a Claude Code plugin — the engine and the
-  book ride in the plugin, not the project. Materialize them into the project once, before
-  any other step:
+- It exists → go straight to `status` below.
+- It does NOT (ADD installed as a Claude Code plugin — engine + book ride in the plugin) →
+  materialize once: `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`. That drops
+  `.add/tooling/` (engine) + `.add/docs/` (book) + the agent-agnostic `CLAUDE.md` block — like an
+  npm/pip install; the skill stays in the plugin, nothing duplicated.
 
-  ```bash
-  node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill
-  ```
-
-  That drops `.add/tooling/` (the engine) and `.add/docs/` (the book) here, so the engine,
-  the book, and the agent-agnostic guideline block in `CLAUDE.md` all work for every agent
-  and for a human at the shell — exactly like an npm or pip install. The skill itself stays
-  in the plugin, so nothing is duplicated.
-
-Run the tool to find the resume point instead of re-reading the repo:
+Find the resume point from the tool, not by re-reading the repo:
 
 ```bash
 python3 .add/tooling/add.py status
 ```
 
-`status` points at two things to read when orienting: `.add/PROJECT.md` (the foundation) and
-`.add/SOUL.md` (your **voice** — tone, communication style, what keeps the human's trust). Read
-`.add/SOUL.md` each session and let it shape how you speak; it is human-owned and self-improving
-(the `soul-self-improve` path proposes voice deltas the human confirms).
-
-- **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**: first, if `.add/.intent` exists, read it — the
-  one-line first-build intent the user gave the installer (a NOTE, never an init trigger) — and let it seed
-  your kickoff suggestion (`phases/0-setup.md`); then 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 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
-  right scope: `python3 .add/tooling/add.py new-task <slug> --title "..."`.
+`status` names two files to read when orienting: `.add/PROJECT.md` (the foundation) and `.add/SOUL.md`
+(your **voice** — tone, style, what keeps the human's trust; read it each session — human-owned and
+self-improving via the `soul-self-improve` path). Then branch on state:
 
-## Intake — size a request before creating scope
+- **No `.add/state.json` yet** (`status` says `no .add/ project found`) → **autonomous setup**: if
+  `.add/.intent` exists, read it — the installer's one-line first-build intent (a NOTE, never an init
+  trigger) — to seed your kickoff; then YOU run init — `add.py init --name "<inferred>" --stage <picked>
+  --await-lock` — and read `phases/0-setup.md` to draft the foundation + §1–§3 through to the human
+  baseline approval.
+- **A task is active** → open its `.add/tasks/<active>/TASK.md`, read the `phase:` marker, load the
+  matching `phases/<n>-<phase>.md`. Work *only* that phase.
+- **No active task** → first SIZE the request (Intake below), then `add.py new-task <slug> --title "..."`.
 
-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 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`).
+**Quick ref** — `status` resume · `init` bootstrap · `advance` continue · `gate PASS` at verify.
+**Opt-in flags** (human picks, never auto): `new-task --fast` = fast lane (minimal template, freeze-gated) · `new-milestone --await-confirm` = confirm-gate the milestone's tasks.
+
+## Intake — size a request before creating scope
 
-Once a request is classified `new-major`/`sub-milestone`, drafting the actual
-`MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks) is the second
-half of intake: read `scope.md` for how to fill it well, the per-outcome behavior,
-and the confirm-before-create rule. Or if it's classified `task`/`change-request`, 
-create the task with `add.py new-task` and then read the phase guide for the first phase (probably `0-setup.md`).
-You propose the draft; the human confirms.
+Classify a raw request BEFORE any milestone or task: read `intake.md`, place it in one bucket —
+`new-major` · `sub-milestone` · `task` · `change-request` — propose `{ bucket, rationale, command }`;
+the human confirms. A question or unsharp intent? **Interview before you size** (`intake.md`). Once
+`new-major`/`sub-milestone`, draft the `MILESTONE.md` (goal · scope · exit criteria · breadth-first
+tasks) — read `scope.md`. Create it `new-milestone --await-confirm`, then `milestone-confirm <slug>`
+gates `new-task` until the parent is agreed. For `task`/`change-request`: `add.py new-task` then the
+first phase guide.
 
 ## The flow and which file to load
 
@@ -106,77 +91,63 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 | observe | `phases/7-observe.md` | §7 spec delta | human + AI |
 
 † **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 a lowered autonomy level (`conservative` / `manual`).
-See `run.md`.
-
-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 → DECIDED → EVIDENCE → NEXT, show-before-ask, never
-pre-stamp a decision point — and the question is a summary, never the artifact.
-
-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 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`. Then (or on demand) compact the stable tail of each foundation spec into a rolled-up settled line — read `compact-foundation.md` (a SEPARATE step, run after `fold.md`).
-
-Observe also tunes your **voice**: propose a confirmable **voice delta** from the human's wordings +
-flow that, once they confirm, rewrites `SOUL.md` (the human is the only writer) — read `soul.md`.
+contract freeze**, lowest-confidence-first — see `run.md`.
+‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (default) a run may auto-PASS on complete
+evidence (*auto-resolved* — an explicit PASS, not a skip). **Security always escalates** (HARD-STOP);
+so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`) — `run.md`.
+
+At every human decision point (intake · bundle approval · gate · milestone close) follow
+`report-template.md`: open with the ARC (goal · done · plan, engine-sourced), then SUMMARY → DECISION →
+FLAGS → DECIDED → EVIDENCE → NEXT; show-before-ask; never pre-stamp; the question is a summary, never the artifact.
+
+In **observe**, emit **lessons learned** tagged by which of the five (`DDD · SDD · UDD · TDD · ADD`)
+they improve (write them `open`; the human consolidates into `PROJECT.md`) — grammar + lifecycle in
+`deltas.md`. At milestone close (or on demand) the retrospective consolidation gathers confirmed deltas
+into a versioned foundation — `fold.md`; then (separately, after) compact each foundation spec's stable
+tail — `compact-foundation.md`. Observe also tunes your voice: propose a confirmable voice delta that,
+once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `soul.md`.
 
 ## Beyond the bundle — load on demand
 
-Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
-(`autonomy: auto` default, lowered to `conservative` or `manual` for a human gate) — read `run.md`. To
-pipeline several ready tasks behind their own frozen contracts, read `streams.md`. To delegate
-one piece of your plan to a subagent that follows it — when to spawn, the plan-following prompt
-template, the tier pick — read `advisor.md`; and at any decision point self-score your draft
-(0–1 across six dimensions, refine if any < 0.9) with `confidence.md`. Both are advisory: the
-engine never spawns, and the self-score is never a gate.
-
-When a **UI feature** reaches specify, run the **design-definition loop** in `design.md` (UDD):
-review the domain → research and reuse components → wireframe → render a real captured screen the
-human confirms **before** build — so the build matches the expected layout. Tool-agnostic; the
-engine never renders.
-
-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.
-
-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.
-
-When one or more milestones have closed since the last release, `add.py status` prints
-**`→ releasable: N milestone(s) closed since last release`** — read `release.md` for the 5th scope
-level: gather `release-report` → draft notes from the consolidated deltas → meet the readiness floor
-(security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
-(CHANGELOG + `RELEASES.md` ledger + milestone attribution) → watch. The engine records; the human runs
-the tag / publish / deploy. A release bundles ≥1 milestone and is orthogonal to stage.
+- **§3 CONTRACT FROZEN** → build→verify is a dynamic, auto-gated run (`autonomy: auto` default; lower to
+  `conservative`/`manual` for a human gate) — `run.md`. Pipeline several ready tasks behind their frozen
+  contracts — `streams.md`. Delegate one piece of your plan to a subagent (when to spawn, the prompt
+  template, the tier) — `advisor.md`. Self-score a draft (0–1 across six dimensions, refine if any < 0.9)
+  — `confidence.md`. Both advisory: the engine never spawns; the self-score is never a gate.
+- **Small, low-risk task**, less ceremony → the **fast lane**: `new-task --fast` scaffolds the minimal
+  `TASK.fast.md`, bundle approved in one freeze — `phases/fast-lane.md`. Floor held (frozen contract ·
+  red test · verify gate; `--fast` is freeze-gated under any milestone). Collapse, never skip; opt-in.
+- **UI feature** at specify → the **design-definition loop** (UDD): review the domain → research and
+  reuse components → wireframe → a real captured screen the human confirms **before** build — `design.md`.
+  Tool-agnostic; the engine never renders.
+- Tasks all done but the milestone **goal** unmet → `milestone-done` holds it open; the loop turns open
+  deltas + extras into the next tasks (you propose, the human confirms) until the goal is met — `loop.md`.
+- `status` prints **`MVP covered → propose graduation`** (every milestone done AND stage criteria all
+  `[x]`) → `graduate.md`: `graduation-report` → co-specify interview → draft ≥1 production milestone →
+  human confirm → then `stage production`. Guarded (`stage_no_roadmap`); the FINAL step, never a bare flip.
+- `status` prints **`→ releasable: N milestone(s) closed since last release`** → `release.md` (the 5th
+  scope level): `release-report` → draft notes from the consolidated deltas → meet the readiness floor
+  (security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
+  (CHANGELOG + `RELEASES.md` ledger + milestone attribution). The engine records; the human runs the
+  tag / publish / deploy. A release bundles ≥1 milestone and is orthogonal to stage.
 
 ## 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 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.
-4. **No silent skips.** Every Verify ends in exactly one recorded outcome:
-   `PASS`, `RISK-ACCEPTED` (signed, non-security only), or `HARD-STOP`. A security
-   finding is always `HARD-STOP`.
+2. **Trust evidence, not inspection.** A feature is trusted because its tests pass 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.
+4. **No silent skips.** Every Verify ends in exactly one recorded outcome: `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
 
-After a phase's exit gate is met, advance the state (this also syncs the marker
-inside TASK.md):
+After a phase's exit gate is met, advance the state (this also syncs the TASK.md marker):
 
 ```bash
 python3 .add/tooling/add.py advance            # next phase of the active task
@@ -186,17 +157,16 @@ python3 .add/tooling/add.py use <slug>         # switch the active task (e.g. ac
 
 ## Depth by stage
 
-The steps never change; their depth does. Read the stage from `add.py status`:
+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. 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.
+- **production** — every step at full rigor + the observe loop. Reach it via the `graduate.md`
+  orchestration when status shows `MVP covered → propose graduation`, never a bare `stage production` flip.
 
 ## 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
-guide points to its chapter. Do not duplicate the book here; load it on demand.
+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 guide points to its chapter. Do not duplicate
+the book here; load it on demand.

package/skill/add/adopt.md

@@ -1,10 +1,6 @@
 # Adopt — map an existing repo into the foundation (silent)
 
-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 living-documentation files from evidence, then stop at the one
-human gate: the **baseline approval** (`add.py lock`).
+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. 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,54 +10,37 @@ 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 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:
+`--await-lock` seeds an **unlocked** setup, *arming the baseline-approval gate* — the engine refuses crossing into build until you `lock`. Init prints:
 
 ```
 brownfield: existing code detected — the `add` skill maps it into your foundation …
 ```
 
-That line is your cue to run this guide. **Always use `--await-lock` for brownfield onboarding**:
-a plain `init` writes no setup and is grandfathered-locked, so its gate never arms *and* the
-closing `lock` below would refuse with `already_locked`. The engine only *detects* the existing
-code (a mechanical fact); it never reads or fills it — interpreting it is your job.
+That line is your cue. **Always use `--await-lock` for brownfield**: a plain `init` is grandfathered-locked, so its gate never arms *and* the closing `lock` would refuse with `already_locked`.
 
 ## The silent mapping
 
-Fill each living-doc file in `.add/` from what the code actually shows — **ask nothing**:
+Fill each living-doc file in `.add/` from what the code shows — **ask nothing**:
 
 | 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 |
-| `GLOSSARY.md` | the recurring names in modules, models, and public APIs (one name per concept) |
-| `MODEL_REGISTRY.md` | leave the active model record; note any AI-authored code you can detect |
-| `dependencies.allowlist` | the manifests already in the repo (package.json, pyproject, go.mod, …) |
-
-Two rules that never bend:
+| `PROJECT.md` (foundation) | domain nouns, entry points, README, first milestone the code implies |
+| `CONVENTIONS.md` | languages, folder layout, naming, lint config, error style in the tree |
+| `GLOSSARY.md` | recurring names in modules, models, and public APIs (one name per concept) |
+| `MODEL_REGISTRY.md` | leave the active model record; note any AI-authored code you detect |
+| `dependencies.allowlist` | manifests already in the repo (package.json, pyproject, go.mod, …) |
 
 <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 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`.)
+1. **Never clobber a living doc.** `init` already skips any living-doc file that exists; if a human already wrote `PROJECT.md`, READ it, 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 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 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 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:
+Brownfield onboarding draws no per-step approvals: map the foundation, draft the first milestone's scope and first task's candidate specification bundle, then present it all at **one** human gate. The human reviews decisions (`guessed` first) and confirms; you run the lock:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"
 ```
 
-`lock` freezes the foundation + scope + first contract in one atomic write and opens the build.
-Until it is run, the engine refuses a second task, crossing into build, and recording a gate —
-so nothing is built on an unreviewed map. That gate is the only thing brownfield onboarding asks
-of a human; everything before it, you did from the code.
+`lock` freezes the foundation + scope + first contract in one atomic write and opens the build. Until it runs, the engine refuses crossing into build.

package/skill/add/advisor.md

@@ -10,16 +10,15 @@ engine never spawns; this is your judgment to make per step.
 
 Spawn a subagent when the piece is **separable and worth the round-trip**:
 
-- **Broad / expensive sweep** — gather a wide map cheaply, return a compact result (the `0-ground`
-  broad sweep is the canonical case).
-- **Independent adversarial review** — a fresh context argues *against* your result (the `6-verify`
-  earned-green refute-read), so the check is not graded by the author.
+- **Broad / expensive sweep** — gather a wide map cheaply, return a compact result.
+- **Independent adversarial review** — a fresh context argues *against* your result (the
+  `6-verify` earned-green refute-read), so the check is not graded by the author.
 - **A well-scoped delegable batch** — a self-contained slice with a clear contract and return shape.
 - **Context offload** — work that would bloat your context but compresses to a small verdict.
 
 Do **not** spawn when the work is narrow and cheap enough to do in-context: a small sweep, a
-two-file read, a quick edit. A spawn costs a round-trip and a fresh context — pay it only when
-the piece is big or independent enough to earn it. When in doubt, do it in-context.
+two-file read, a quick edit. A spawn costs a round-trip — pay it only when the piece is big or
+independent enough to earn it. When in doubt, do it in-context.
 
 ## The plan-following prompt template
 
@@ -54,10 +53,10 @@ Do NOT run add.py or write any shared state — you propose, the orchestrator re
 
 ## Choosing the model — vendor-neutral tiers
 
-Reuse `streams.md`'s tiers, never a new vocabulary: **mid** (Claude Code: `sonnet`) for ordinary,
-well-scoped pieces with a clear contract; **top** (Claude Code: `opus`) for complex, ambiguous, or
-cross-cutting pieces. The tier maps to the runner's model id through the same adapter `streams.md`
-defines. A stronger model never buys back a human gate: high-risk scope still escalates.
+Pick the tier from `streams.md`'s vocabulary: **mid** for an ordinary, well-scoped piece; **top**
+for a complex, ambiguous, or cross-cutting one. The tier→model-id mapping and the spawn adapter
+live there — one home, not repeated here. A stronger model never buys back a human gate: high-risk
+scope still escalates.
 
 ## The hard rule — you delegate, you do not abdicate
 

package/skill/add/compact-foundation.md

@@ -1,53 +1,40 @@
 # Foundation compaction — collapse the stable tail
 
-This is the **retrospective shrink**. `fold.md` PREPENDS new learnings (newest-first); foundation
-compaction later COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — so
-PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md keep to one screen as the project grows.
+`fold.md` PREPENDS new learnings (newest-first); foundation compaction COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — keeping PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md to one screen as the project grows.
 
-You (the AI) **gather and propose**; the **human confirms**; you then write the settled line. This is a
-**convention**, not a command — there is no `add.py compact-foundation` (the engine stays judgment-free).
-It is DISTINCT from the engine `add.py compact <slug>` (the archive recovery-bundle move).
+You **gather and propose**; the **human confirms**; you then write the settled line. This is a **convention**, not a command — there is no `add.py compact-foundation`. It is DISTINCT from engine `add.py compact <slug>` (the archive recovery-bundle move).
 
 ## When
 
-At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen.
-Compaction is a SEPARATE step from `fold.md` — never merged into the retrospective consolidation.
+At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen. Always a SEPARATE step from `fold.md`.
 
-## Eligibility (one shared test)
+## Eligibility
 
-An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries
-**zero open residues**/deltas. An unshipped or open-residue entry is NOT eligible — leave it live
-(`open-residue-version`).
+An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries **zero open residues**/deltas. Unshipped or open-residue entries are NOT eligible (`open-residue-version`).
 
 ## The ritual
 
-1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec (its oldest entries).
-2. **Propose** — draft the per-spec rolled-up settled line (see the shapes below) and show the human.
-3. **Confirm** — the human accepts or declines. No write happens without confirmation.
-4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records
-   stay on top, the settled line anchors at the tail), carrying a git/archive pointer.
+1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec.
+2. **Propose** — draft the per-spec rolled-up settled line and show the human.
+3. **Confirm** — no write happens without confirmation.
+4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records stay on top, settled line anchors at the tail), carrying a git/archive pointer.
 
-## Per-spec rolled-line shapes (from the frozen compaction-contract)
+## Per-spec rolled-line shapes
 
-- **PROJECT.md §Spec** — a run of stable `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
-- **PROJECT.md §Key-Decisions** — matching shipped rows → one `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` row at the tail.
-- **CONVENTIONS.md** — a run of stable `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
-- **GLOSSARY.md** — a verbose, stable definition → its terse canonical line + `(rationale: see git)`. *(forward-looking — small today.)*
-- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`. *(forward-looking — nothing to compact yet.)*
+- **PROJECT.md §Spec** — `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
+- **PROJECT.md §Key-Decisions** — shipped rows → `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` at the tail.
+- **CONVENTIONS.md** — `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
+- **GLOSSARY.md** — verbose stable definition → terse canonical line + `(rationale: see git)`.
+- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`.
 
-## Preservation (every collapse)
+## Preservation
 
 - **Never delete** — summarize and point; a settled line is lossy on prose, lossless on traceability.
-- A surviving **git**/archive pointer is mandatory (`trail-loss` if dropped).
-- **OPEN residues stay** live; the audit trail is summarized-not-deleted.
+- A git/archive pointer is mandatory (`trail-loss` if dropped).
+- OPEN residues stay live.
 
-## Reject codes (judgment-checked — the AI proposes, the human confirms)
+## Reject codes
 
-- `open-residue-version` — the entry is unshipped or has ≥1 open delta/residue; leave it live.
-- `trail-loss` — the collapse would drop the git/archive pointer or the audit summary.
+- `open-residue-version` — entry is unshipped or has ≥1 open delta/residue; leave it live.
+- `trail-loss` — the collapse would drop the git/archive pointer or audit summary.
 - `wrong-order` — a record is not newest-first, or the settled line is not at the tail.
-
-## Distinct from `add.py compact`
-
-Foundation compaction ≠ engine `add.py compact <slug>`. It mirrors `fold.md`'s "AI proposes, human
-confirms" voice and stays convention-guided — no engine command, no `add.py check` enforcement.