@pilotspace/add 1.16.0 → 1.17.0

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

@@ -52,7 +52,7 @@ Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** a
 ## 3 · Draft to the lock (both paths)
 
 1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec · UI/UX · Key Decisions), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (delete if no UI; `design.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
-   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber.
+   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber. Still unseeded later? `status`/`check`/`new-milestone`'s hint means: return here, draft every missing project persona — not just one.
 2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one sentence), a **flow** (task order), **scenarios** (examples of what ships). Not the frozen `MILESTONE.md`. On their reaction, draft `MILESTONE.md` (read `scope.md`).
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash
@@ -61,16 +61,16 @@ Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** a
    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 build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL before build.
 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)
+## Run mode — how the build will be driven (propose sequential + auto; confirm to keep)
 
 Before the lock, surface the **run mode** — autonomy + streams (`run.md` · `streams.md`):
 
 | Run mode | Human gates | Concurrency |
 |----------|-------------|-------------|
+| **sequential · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | one task at a time |
 | **sequential · manual/conservative** | contract freeze **and** every Verify | one task; safest |
-| **parallel · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | `add.py waves` overlaps independent builds behind frozen contracts |
 
-**Propose `parallel + auto`; confirm-to-keep** (or downgrade: `add.py autonomy set conservative --project` + `add.py streams set sequential --project`). Record in **`PROJECT.md` Key Decisions**.
+**Propose `sequential + auto`; confirm-to-keep** (raise the gate: `add.py autonomy set conservative --project`; opt into parallel streaming for a milestone with independent tasks — `add.py streams set parallel --project`, then `add.py waves` schedules the fan-out). Record in **`PROJECT.md` Key Decisions**.
 
 Floor: **one human approval per contract**.
 

package/skill/add/phases/4-tests.md

@@ -1,12 +1,17 @@
 # Phase 4 — Tests (failing-first suite)
 
-Goal: turn scenarios + contract into automated tests and confirm they FAIL before any code exists — red now, green only after Build. Fill **§4 TESTS** and write the suite into `.add/tasks/<slug>/tests/`.
+Goal: tests from scenarios + contract that FAIL before any code exists. Fill **§4 TESTS**; the suite lives in `.add/tasks/<slug>/tests/`.
 
 ## The must-fail principle
 
-Run the suite now, with no implementation — it must be **red for the right
-reason** (missing implementation, not a broken harness). A test that passes
-before code exists is testing nothing and will wave bad code through later.
+Run the suite now, with no implementation — **red for the right reason**
+(missing implementation, not a broken harness). A test green before code
+exists is testing nothing.
+
+**A test is any machine-checkable assertion**, not only xUnit code —
+a metric threshold (ML/data), a reconciliation query (data integrity),
+a plan-diff (infra/IaC), a rendered-screen diff (UI). Red-first holds
+for each: the assertion must FAIL before the change exists.
 
 ## Produce
 
@@ -15,29 +20,26 @@ before code exists is testing nothing and will wave bad code through later.
 - Contract-conformance tests (shapes + error responses from §3).
 - Side-effect assertions on rejection paths (`assert balance unchanged`).
 - A recorded coverage target in §4.
+- §6 **Build expectations** filled now, BEFORE build — observable outcomes from §2 + §3.
 </output_format>
 
 ## Declaring where tests live
 
 §4's `Tests live in:` line is machine-read: with no local `tests/`, `add.py report`
-counts test functions at the declared backticked paths instead (FIRST `Tests live in:`
-line only). Resolution: `./…` → this task's dir · a token with `/` → the project root
-(parent of `.add/`) · a bare name → a sibling of the previous token's dir (else the
-task dir). A directory token counts the `*.py` files directly inside it (non-recursive); a `.py`
-file counts itself; else ignored. Resolved files dedupe; declared counts marked `†`. Paths
-are confined: anything resolving outside the project root counts 0 — `..` traversal, absolute
-paths, and symlink escapes are never read.
+counts test functions at the declared backticked paths (FIRST such line only).
+`./…` → this task dir · a token with `/` → the project root · a bare name → a
+sibling of the previous token's dir. A directory counts its `*.py` files
+(non-recursive); a `.py` file counts itself. Resolved files dedupe; declared counts
+marked `†`. Paths are confined: outside the project root counts 0 — `..` traversal,
+absolute paths, and symlink escapes are never read.
 
 ## AI prompt
 
 <prompt>
 Role: a test author who writes tests before code.
 Read first: §2 · §3.
-Objective: a red suite that fails for the right reason — behavior, not internals.
-Steps:
-  1. Turn each scenario into an executable test.
-  2. Add contract-conformance and edge-case tests.
-  3. Run the suite and confirm it fails for the right reason; record a coverage target.
+Steps: turn each scenario into an executable test; add contract-conformance and
+edge cases; run the suite red for the right reason; record a coverage target.
 Never: implement the feature, or assert on internals.
 </prompt>
 
@@ -51,7 +53,7 @@ Never: implement the feature, or assert on internals.
 </exit_gate>
 
 > **Persona** — let the fit persona's `## Success Metrics` shape the red suite (advisory).
-> **Advisor · Confidence** — spawn a test-author for a broad red suite (advisor.md); score Completeness — one test per scenario, every rejection covered (confidence.md).
+> **Advisor · Confidence** — spawn a test-author for a broad red suite (advisor.md); score Completeness honestly (confidence.md).
 
 ## Next
 

package/skill/add/phases/7-observe.md

@@ -4,10 +4,10 @@ Goal: release deliberately, watch reality, turn what you learn into the next spe
 
 ## Do
 
-1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout.
+1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout
 2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
    define what you alert on: overall error rate, each rejection's rate (a spike is a
-   signal), latency of the risky op under load.
+   signal), latency of the risky op.
 3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
    change that re-enters the flow at Specify (a new task).
 4. **Propose a voice delta** — note where your voice diverged from the human's (wordings +
@@ -22,11 +22,8 @@ Goal: release deliberately, watch reality, turn what you learn into the next spe
 <prompt>
 Role: a reliability analyst feeding the next cycle.
 Read first: telemetry · objectives · incidents.
-Objective: turn what production shows into the next SPEC delta.
-Steps:
-  1. Report error-budget burn.
-  2. Cluster errors and surface the top real-world failures.
-  3. Draft a SPEC delta with evidence links.
+Steps: 1. report error-budget burn · 2. cluster errors, surface the top real failures ·
+  3. draft a SPEC delta with evidence links.
 Never: auto-roll-back — recommend; a human owns the production decision.
 </prompt>
 
@@ -38,10 +35,11 @@ Never: auto-roll-back — recommend; a human owns the production decision.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
 </exit_gate>
 
-> **Persona** — tag a lesson `· persona:<slug> ·` so `add.py fold` grows the persona.
+> **Persona** — tag `· persona:<slug> · critical-rule|success-metric|anti-pattern|ability`;
+> `fold` grows that section — a HOW-an-agent-behaves lesson belongs in a persona, not the shared pile.
 > **Advisor · Confidence** — spawn a reviewer to mine the run for lessons (advisor.md); score Self-evaluation — did this loop teach the foundation? (confidence.md).
 
 ## Next
 
-Loop. The artifacts you built are living docs the next cycle refines.
-Book: `docs/09-the-loop.md`.
+Loop — the artifacts are living docs the next cycle refines.
+Map: `self-improve.md` · book: `docs/09-the-loop.md`

package/skill/add/phases/fast-lane.md

@@ -20,6 +20,9 @@ cross-cutting, or anything you are not yet sure is small. In doubt, run the full
 3. Write a **red** test (§4), run it failing for the right reason.
 4. Build (§5) to green, then record the **verify gate** (§6).
 
+Both human gates (freeze, verify) render `report-template.md` too — the fast lane collapses
+sections, never the report.
+
 ## Floor kept, only collapsed
 
 Three things never move, on either lane: a **frozen** §3 before build · a **red** test before build ·

package/skill/add/report-template.md

@@ -39,8 +39,8 @@ Its facts are engine-sourced (goal = `m-goal` · done = exit-criteria + tasks do
 
 ### Per-gate examples
 
-- **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6 green · `plan:` PASS → wire the arc into every gate → goal.
-- **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence flag surfaced · `plan:` freeze §3 → build → goal.
+- **verify** — `goal:` ship the arc · `done:` tests 6/6 green · `plan:` PASS → every gate → goal.
+- **contract-freeze** — `done:` bundle drafted, flag surfaced · `plan:` freeze §3 → build → goal.
 
 ## PLAN / SHAPE — when there's more than one step, or a shape to freeze
 
@@ -62,10 +62,10 @@ SHAPE   <task title, bold> — v<N>  (DRAFT — not yet frozen)
   <error case / reject token>  <what triggers it>
 ```
 
-- **Collapse done to a count.** Never enumerate finished tasks by name — the human already trusts what's shipped; re-listing it is noise.
-- **Cap live items at ~5–7**, in dependency order; footer `+N more queued` rather than listing everything.
+- **Collapse done to a count.** Never enumerate finished tasks by name.
+- **Cap live items at ~5–7**, dependency-ordered; footer `+N more queued`.
 - **One line per item** — slug + what it does or blocks on; never restate the whole TASK.md.
-- **Glyphs are fixed** — ✅ done · 🔄 active/in-progress · ⬜ pending · ⚠ blocked or flagged. Do not invent new glyphs.
+- **Glyphs are fixed** — ✅ done · 🔄 active · ⬜ pending · ⚠ blocked/flagged; never invent new ones.
 - **Sourced from the engine, summarized by you** — pull from `add.py status`'s `tasks:`/`streams:` output; never paste it verbatim into chat.
 - **SHAPE is freeze-only** — the concrete thing being locked, so the human reviews the actual shape, not just commentary about it.
 
@@ -105,7 +105,7 @@ APPROVE  <the question>
 ```
 
 - **Exactly one** option carries `▶ … (recommended)`. `confidence.md` self-score informs which; the human overrides freely.
-- **1–3 real alternatives** only — no strawmen; if there is genuinely one path, show one — never invent filler to reach three.
+- **1–3 real alternatives** only — no strawmen, no filler; one genuine path → show one.
 - **Every option is described** — pick and each alternative carry a one-line description.
 - **Human gates only** — render at `[human gate]` points; not at `[you drive]` steps.
 
@@ -121,6 +121,7 @@ APPROVE  <the question>
 - **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or blank until the answer returns: show → ask → stamp → advance.
 - **Never dump raw engine output as the plan.** Summarize `add.py status`/`report` through PLAN/SHAPE (or prose) — the engine's full verbosity is for `add.py` itself, not the chat message wrapped around it.
 - **One report per decision point.** After an approval, point at the frozen artifact — do not re-render the bundle.
+- **Batch, don't serialize.** N same-gate decisions ready together (intake items · ready-to-freeze contracts) render as ONE report: PLAN lists each item with its own lowest-confidence flag; APPROVE covers the batch in one ask, and any item can be held back by name.
 - **Honest scope.** "Done" means the request, not the last task: report "task 2/3", never "done" while approved scope remains.
 - **The question is a summary, never the artifact.** A compact SUMMARY · FLAGS block sits in chat immediately before the ask; the question text itself is two lines at most — intent + what "yes" means + flag count — pointing at the report above.
 - **NEXT is not a second gate.** The single decision stays in APPROVE; NEXT is ranked recommendations only.

package/skill/add/run.md

@@ -7,23 +7,13 @@ Scenarios · Contract) still owns *direction*. The engine stays judgment-free: t
 
 ## The specification bundle (v7)
 
-v7 compresses the old three-approval flow to **one**. The AI **drafts the whole specification
-bundle in one pass** — Spec, Scenarios, Contract, and failing Tests — and presents it together.
-The human gives **one approval, at the frozen contract** (the decision point).
-
-Why one and not zero: the decision point **stays human**. The AI *drafts* the contract but never
-*freezes its own* — a person approves the frozen shape before any auto-run touches code: that the
-Spec captures real intent, the Scenarios cover the cases that matter, and the Contract shape is the
-one to freeze. Reject any part → back to draft (backward-correction, principle 4, not failure). The
-decision-point guide (`phases/3-contract.md`) carries the **freeze review checklist** — seven lines,
-⚠-first.
-
-**The lowest-confidence flag.** The AI presents the bundle **lowest-confidence first**: the
-**1–2 points most likely to be wrong**, tagged by part
-(`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — `because` names the §1
-assumption behind the doubt, `if wrong` its cost. If nothing is materially uncertain, the AI still
-names the single biggest risk — never a blank "none". This flag is honor-system: the lint cannot
-force engagement — closing that gap is a CI checker's job, not prose.
+v7 compresses the old three-approval flow to **one**: the AI drafts Spec · Scenarios ·
+Contract · failing Tests in one pass; the human gives **one approval, at the frozen
+contract** — the decision point stays human (the AI never freezes its own shape; a
+rejected part goes back to draft, backward-correction not failure). The freeze
+presentation — the bundle led **lowest-confidence first** by its ⚠ flag, the
+freeze review checklist (seven lines, ⚠-first) — lives in `phases/3-contract.md`,
+its one home; this rubric owns what happens AFTER the freeze.
 
 ## When the run begins — the scope-lock trigger
 

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 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.
+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. Touches spanning >1 app root (BE+FE, or multiple independently-testable dirs)? weigh `.add/components.toml` (`components.md`) now — before tasks decompose with flat cross-app paths.
 2. **Relate to the milestone map.** Run `add.py search <keyword> [<keyword> ...]` first — then 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`.
 

package/skill/add/self-improve.md

@@ -0,0 +1,20 @@
+# Self-improving ADD — the one map
+
+Every loop improves four artifacts. You emit `open`; the human confirms; the engine
+transcribes — nothing self-approves. Emission lives in observe (§7); every earlier step
+feeds it: ground surprises → §1 · the freeze's ⚠ flag → the next spec · a red-suite gap →
+a TDD lesson · build's strategy-actually-used → the ADR block · verify residue → a SPEC delta.
+
+| what improves | grammar (closes `(evidence: …)`) | consolidator |
+|---|---|---|
+| foundation — `PROJECT.md`/`CONVENTIONS.md` | `[DDD\|SDD\|UDD\|TDD\|ADD · open] lesson` | `add.py fold` → `fold.md` |
+| personas — the agents' stances | `… · persona:<slug> · critical-rule\|success-metric\|anti-pattern\|ability` | same `fold` run |
+| `SOUL.md` — your voice | a voice delta, `open` | human rewrite → `soul.md` |
+| the next scope | `[SPEC · open]` → seeded · dropped · carried | `loop.md` → `new-task` |
+
+Routing: `DDD`→§Domain · `SDD`→§Spec · `UDD`→§Users · `TDD`/`ADD`→§Method learnings
+(grammar: `deltas.md`). A HOW-an-agent-behaves lesson → a persona, not the shared pile.
+
+Convergence: `fold` prepends newest-first; the settled tail rolls via
+`compact-foundation.md`; `status` counts the debt — `carried:` · `compaction:`.
+Self-score before emitting — `confidence.md` (six dimensions; < 0.9 → refine).

package/skill/add/streams.md

@@ -1,11 +1,11 @@
 # Parallel streams — pipelining independent tasks
 
 Load this when a milestone has more than one task and you want to run them concurrently.
-**Default:** when a project confirms `parallel + auto` as its run mode at setup
-(`phases/0-setup.md` "Run mode"), parallel streaming is the project default — an **opt-out**, not
-the opt-in it once was; downgrade in one step (`add.py autonomy set conservative --project`, or
-just run tasks one at a time). A project that kept the conservative run mode still treats this
-rubric as the opt-in escape hatch.
+**Default:** `sequential + auto` is the project default at setup (`phases/0-setup.md` "Run
+mode") — one task at a time, but Verify still auto-PASSes on evidence. Parallel streaming is an
+**opt-in** for a milestone with genuinely independent tasks: `add.py streams set parallel
+--project`, then read on. A project that raised its gate to `conservative`/`manual` still treats
+this rubric as the same opt-in escape hatch.
 
 It changes **no `add.py` code and no phase semantics**. It is a way *you, the orchestrator*,
 drive several tasks at once by reading the dependency DAG `add.py status` already prints and
@@ -49,8 +49,8 @@ tier hint: top → dag-scheduler, setup-run-mode; mid → the rest
 ```
 
 - **Wave = a fan-out batch.** Every task in a wave has all in-milestone deps PASS, so the whole
-  wave is spawnable at once (`isolation="worktree"`). Finish a wave, gate tasks PASS, then
-  `add.py waves` again — the next wave is unblocked.
+  wave is spawnable at once — worktree isolation is the default for any spawn, not just a wave.
+  Finish a wave, gate tasks PASS, then `add.py waves` again — the next wave is unblocked.
 - **Run the widest wave first** to hide the most build latency under human review latency.
 - **Spend your strongest model on the critical path.** Critical-path tasks gate the most
   downstream work; off-path tasks take **mid**. The tier hint is advisory — override when you
@@ -85,8 +85,9 @@ floor never drops to zero (`run.md:22`). Do not engineer around it.
 - **A worker** owns only its own `.add/tasks/<slug>/` — it builds `src/`, drives tests green,
   gathers evidence, and writes `SUMMARY.md` + OBSERVE deltas. It touches **no sibling stream and
   no shared file** — never write shared state (state.json, MILESTONE.md, a sibling's files).
-- **Isolation**: spawn each worker with `isolation="worktree"` so concurrent builds cannot
-  collide. The worktree is discarded on failure; the task resets to its last-good phase.
+- **Isolation**: `isolation="worktree"` is the default for any agent-spawned step, not only a
+  wave — a shared-tree spawn needs a stated reason. The worktree is discarded on failure; the task
+  resets to its last-good phase.
 </constraints>
 
 ## Design for failure (required)
@@ -100,8 +101,8 @@ floor never drops to zero (`run.md:22`). Do not engineer around it.
   (`wave_ledger_malformed`); `add.py check` is the standing monitor.
 - **Materialize gitignored engine content** — `git worktree add` checks out TRACKED files only;
   `.add/tooling` (engine) and `.add/docs` (book) are gitignored and will be ABSENT even when the
-  worktree's HEAD matches — copy them in before the worker's first `add.py` call, or its
-  `phase`/`advance` commands have no engine to run at all (confirmed 3-for-3 this session).
+  worktree's HEAD matches. `add.py worktree-prep <slug>` mechanizes the recipe: cuts the
+  worktree, copies both trees in, and echoes the fork base for the ledger — one step.
 - **Lease + timeout** — record which worker holds which task (wave ledger); a dead worker releases
   its claim back to READY.
 - **Failure isolates** — a worker's STOP-and-escalate blocks only its own task; siblings run on, the
@@ -248,8 +249,8 @@ always escalates** — no tier auto-passes it.
 
 ## The spawn adapter — one thin mapping per runner
 
-ADD needs six capabilities from any runner. **Isolation ADD owns itself** (a git worktree), so
-streams stay portable even without a native sandbox.
+ADD needs six capabilities from any runner. **Isolation ADD owns itself** (a git worktree,
+default for any spawn), so streams stay portable even without a native sandbox.
 
 | ADD needs | Abstract | Claude Code (verified reference) | Any CLI agent — Codex · opencode · pi-mono · … |
 |-----------|----------|----------------------------------|-----------------------------------------------|