@pilotspace/add 1.8.0 → 1.10.0

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,67 @@ 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.
+- **Monorepo / multi-repo** — a milestone spans more than one green bar (a BE + its FE, services across
+  repos) → the **component pillar**: declare components in `.add/components.toml`, gate each task on its
+  component's green-bar, freeze cross-component contracts (`produces:`/`consumes:`), hold the FE until the
+  BE freezes, and `federate pull` a contract across repos — `components.md`. Opt-in; no components = today.
 
 ## 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 +161,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.

package/skill/add/components.md

@@ -0,0 +1,54 @@
+# Components — monorepo and multi-repo slices
+
+Opt-in pillar for a milestone that spans **more than one green bar** — a backend
+and its frontend, a shared lib and two apps, services across repos. A project
+that declares no components is byte-identical to a single-codebase project. Reach
+for this only when one milestone genuinely crosses components. Full narrative:
+book chapter `17-components.md`.
+
+## Declare (never inferred)
+
+`.add/components.toml`:
+
+```toml
+[component.gateway]
+root      = "apps/gateway"
+green-bar = "pytest + pyright"
+[component.dashboard]
+root      = "apps/web"
+green-bar = "vitest + a11y"
+```
+
+A task binds with a `component: <name>` header line → that root joins its §5
+Scope, and verify holds it to that component's green-bar.
+
+## The loop
+
+1. **Per-component verify.** A bound task must CITE its component's green-bar in
+   the §6 Build-expectations evidence, or the gate refuses
+   `component_green_bar_uncited`. The engine never runs the suite — you run the
+   right one; the gate checks the right bar was cited.
+2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
+   (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
+   The producer's freeze (contract→tests) writes the immutable snapshot
+   `.add/contracts/<id>.json`; the consumer pins its hash. A changed re-freeze
+   flags consumers `contract_consumer_stale`; a missing/malformed snapshot
+   HARD-STOPS — never build against an unfrozen shape.
+3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
+   scenarios→contract (`producer_contract_unfrozen`) until the producer's
+   snapshot exists. The FE stays downstream of the frozen BE endpoint, in one
+   milestone.
+4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
+   (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
+   byte-for-byte copy of the producer repo's published snapshot locally, where it
+   behaves as in a monorepo. Fail-loud: unknown id / unreadable source / invalid
+   snapshot / version mismatch each HARD-STOPS and lands nothing.
+
+## Hold the line
+
+- **Declared, not inferred** — no scanning `apps/*`.
+- **No central server / no shared mutable state** — federation copies an
+  immutable snapshot; each repo keeps its own git-native `state.json`.
+- **No new approval** — these are engine-enforced gates on the existing six-step
+  flow, not extra human checkpoints. Ownership/autonomy per component is the
+  identity story (`streams.md`, governance), layered on this graph.

package/skill/add/confidence.md

@@ -1,13 +1,10 @@
 # Confidence — the self-score that aims attention
 
-The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact
-— a spec, a contract, a build, or a verdict returned by a spawned subagent — *before* it
-presents it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a
-gate. Score it privately, refine while it is cheap, then surface what stayed uncertain.
+The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact — a spec, a contract, a build, or a subagent verdict — *before* presenting it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a gate.
 
 ## The six dimensions
 
-Score each from 0 to 1 (0–1), honestly, on the artifact you are about to hand over:
+Score each 0–1 honestly on the artifact you are about to hand over:
 
 - **Completeness** — did it cover every rule, scenario, and rejection the task asked for?
 - **Clarity** — would the next reader understand it without you in the room?
@@ -16,33 +13,20 @@ Score each from 0 to 1 (0–1), honestly, on the artifact you are about to hand
 - **Edge cases** — did it name the failure modes, the concurrency, the empty/oversized inputs?
 - **Self-evaluation** — does it carry its own refine step — a way to catch its own mistakes?
 
-If **any** dimension scores **< 0.9**, refine the artifact before you present it (or before you
-return from a spawned subagent), then re-score. The point is to spend the cheap iteration now,
-not after a human has read past the weak spot.
+If **any** dimension scores **< 0.9**, refine the artifact before presenting, then re-score.
 
 ## Where it plugs in
 
-- It **feeds the lowest-confidence flag** (run.md · phases/1-specify.md): the lowest-scoring
-  dimension or point is what you surface ⚠-first at the contract freeze. The self-score is the
-  private computation; the lowest-confidence flag is the public surfacing of its weakest point —
-  this rubric only *aims* that flag, it does not redefine it.
-- A persistently low score on a risky scope is a signal to **recommend lowering the autonomy
-  level** (auto → conservative / manual; run.md). Recommend it — never force it; choosing the
-  autonomy level stays the human's call.
+- It **feeds the lowest-confidence flag** (run.md · 1-specify.md): the lowest-scoring dimension is what you surface ⚠-first at the contract freeze.
+- A persistently low score on a risky scope is a signal to **recommend** lowering the autonomy level (auto → conservative / manual; run.md). Recommend it — the autonomy level stays the human's call.
 
 ## The hard rule — advisory, never a gate
 
 <constraints>
-The confidence self-score is advisory only — it is never a gate. It never:
-- auto-PASSes a verify or blocks a run — the verify outcome rests on evidence (passing tests,
-  the non-functional review), not on a number the agent assigned itself;
+The confidence self-score is advisory only — never a gate. It never:
+- auto-pass a verify or block a run — the verify outcome rests on evidence (passing tests, the non-functional review), not a self-assigned number;
 - substitutes for evidence or for the human decision point;
-- is recorded as a score the human "agreed to" — a self-asserted score that gated would only
-  move an unread approval one level up (run.md).
+- is recorded as a score the human "agreed to" — a self-asserted score that gated would only move an unread approval one level up (run.md).
 
-What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend lowering
-the autonomy level. The gate itself stays evidence-based and human-owned.
+What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend an autonomy adjustment. The gate itself stays evidence-based and human-owned.
 </constraints>
-
-> Used per step: each phase guide's Confidence hook points here, so an agent self-scores in the
-> idiom of the phase it is in (see the per-step hooks).