@pilotspace/add 1.9.0 → 1.11.0

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/phases/0-ground.md

@@ -47,11 +47,17 @@ Never: invent a file, symbol, or signature you have not opened.
 ## Exit gate
 
 <exit_gate>
-- [ ] The real files/symbols the task touches are named (from the code, not assumed).
-- [ ] The conventions to honor are cited (task-delta only; no architecture re-scan).
-- [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
+- [ ] **Touches** — the real files/symbols the task touches are named (from the code, not assumed).
+- [ ] **Context** (working folder) — the non-code artifacts the task touches (docs · todos · config · data) are named, task-delta only.
+- [ ] **Honors** — the patterns/conventions to honor are cited (task-delta only; no architecture re-scan).
+- [ ] **Anchors** — the anchors §3 will cite are listed — §3 names only anchors that exist here.
 </exit_gate>
 
+**Grounding is complete when** all four fields are filled from real assets: a STRONG grounding cites
+actual files/symbols/docs/conventions you opened; a WEAK one leaves a `<…>` placeholder or names what you
+assume. All four are non-optional — skipping **Context** (the working folder beyond code) is the usual
+silent gap. §3 may cite only anchors that appear here.
+
 > **Advisor · Confidence** — a broad sweep is the canonical spawn case (advisor.md); self-score your grounding before you specify against it (confidence.md).
 
 ## Next

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

@@ -57,7 +57,7 @@ Capture each surfaced decision as an **ADR** into `PROJECT.md` **Key Decisions**
    ```bash
    python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
    ```
-   Draft §1 · §2 · §3. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: bundle → lock → build.
+   Draft the full bundle **§1–§4** — incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL **before build** (never start Build until §1–§4 exist and tests are red).
 4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every drafted decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
 
 ## Run mode — how the build will be driven (propose parallel + auto; confirm to keep)
@@ -93,7 +93,7 @@ Typing it themselves stays the **escape hatch** — the decision is always the h
 <exit_gate>
 - [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
 - [ ] Living docs filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
-- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
+- [ ] First task created; **§1–§4 drafted — the red suite (per `phases/4-tests.md`) runs RED before build opens**; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
 - [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name; first task §3 `FROZEN @ v1`; build open.
 </exit_gate>
 

package/skill/add/scope.md

@@ -19,7 +19,7 @@
 
 Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
 
-1. **Ground in current assets.** Read the goal against `PROJECT.md` (domain · spec · UI/UX), the code it touches, and existing docs — the goal must reflect what the project already is.
+1. **Ground in current assets.** Read the goal against what exists — the goal must reflect what the project already is. Ground as rigorously as a task's §0 (`phases/0-ground.md`), using the **same four fields** at milestone scope: **Touches** (the subsystems/files the milestone spans) · **Context** (the docs · todos · config · data it works against) · **Honors** (the `PROJECT.md` / `CONVENTIONS.md` invariants it must respect) · **Anchors** (the existing contracts/symbols its tasks will cite). Grounding is complete when each is named from real assets, not assumed.
 2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
 3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.