@pilotspace/add 1.3.0 → 1.5.0

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

@@ -49,15 +49,41 @@ Ask only the live ones; skip what the request already answers. Rank your drafts
 one notation every scope level shares — `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — and
 tag thin or inferred answers `guessed`.
 
+## 2c · Domain deep-dive — per-drive, across multiple turns (deepens §2b)
+
+§2b gets a foundation from one question per lens; this step DEEPENS it across **multiple
+turns**, one deep-dive per **drive** — naming all four, including the one §2b's lens list omitted:
+
+| Drive | Deepen |
+|-------|--------|
+| **DDD** (domain) | core nouns → model: the entities, the invariants, the bounded edges |
+| **SDD** (spec) | the milestone outcome → the behaviors and the explicit non-goals |
+| **UDD** (users) | the primary user → the jobs, the surface, the one flow that must feel right |
+| **TDD** (trust) | what "done & trusted" means: the risks to prove, the evidence that closes them |
+
+Capture each surfaced decision as an **ADR** (architecture decision record) into `PROJECT.md`
+**Key Decisions** as it lands — the Decisions lens becomes explicit ADR capture (the *why*, not just the *what*).
+
+**Under `autonomy: auto` with full context, auto-complete all four drives in one pass** — draft
+each without stopping to interview, still lowest-confidence-first, surfacing the top **flag**. Ask
+only the live drives; skip what the request already answered. This deepens **drafting**, never the
+gate: auto-complete NEVER skips the human baseline approval — the `lock` (§4) stays the one decision.
+
 ## 3 · Draft to the lock (both paths)
 
 1. **Fill the living documentation** (it outlives all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
    milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
    `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
-   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI).
+   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI;
+   the design-definition loop that fills it — domain → components → wireframe → a captured screen confirmed before build — is `design.md`).
    Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
-2. **Size the first milestone** (read `scope.md`) and draft its `MILESTONE.md` — goal · scope · exit criteria
-   · breadth-first tasks.
+2. **Propose, then size it.** You just read the codebase (brownfield) or interviewed (greenfield) — so
+   don't silently draft. First float a **kickoff suggestion** for the first milestone the human reacts to:
+   a **goal** (one outcome sentence), a **flow** (the breadth-first task order that gets there), and
+   **scenarios** (concrete examples of what the user can DO once it ships). Keep it a lightweight react-to
+   sketch — a few bullets, NOT the frozen `MILESTONE.md` or per-task §2 suites. This is show-before-ask:
+   the human reacts (confirm / adjust / redirect); you do not auto-create. On their reaction, draft its
+   `MILESTONE.md` (read `scope.md`) — goal · scope · exit criteria · breadth-first tasks.
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash
    python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
@@ -68,6 +94,28 @@ tag thin or inferred answers `guessed`.
 4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every decision you drafted (foundation, scope,
    first contract), **lowest-confidence-first**, each tagged `guessed` | `evidence-grounded`.
 
+## Run mode — how the build will be driven (propose parallel + auto; confirm to keep)
+
+Before the lock, surface ONE more choice so the human is aware of how ADD will drive the build:
+the **run mode**. Two settings compose it — the **autonomy** level (`add.py autonomy`, run.md: who owns
+the verify gate) and **streams** (`add.py waves` + `streams.md`: whether independent tasks pipeline).
+Show this table so the human sees the flow behavior of each, then PROPOSE the default:
+
+| Run mode | Human gates that fire | Concurrency / flow behavior |
+|----------|-----------------------|-----------------------------|
+| **sequential · manual/conservative** | the contract freeze **and** every Verify, one task at a time | one task start-to-finish before the next; safest, slowest; the reviewer waits on each build |
+| **parallel · auto** *(proposed default)* | the contract freeze **only** — Verify auto-PASSes on complete evidence (security/residue still escalate) | `add.py waves` schedules independent tasks into waves; builds overlap behind their frozen contracts while you review one bundle; the reviewer is never blocked on a build |
+
+**Propose `parallel + auto` as the default, and ask the human to confirm-to-keep** (or downgrade in
+one step — `add.py autonomy set conservative --project`, or just run tasks one at a time). This is a
+confirm, never a silent flip. Record the chosen mode in **`PROJECT.md` Key Decisions** (e.g. "run mode:
+parallel + auto (opt-out), confirmed by <name>") so every later session inherits it.
+
+What the default does **not** change: the irreducible floor still holds — **one human approval per
+contract** fires no matter the mode. `auto` + `parallel` change the *order and throttle* of the build
+(which tasks run when, and who gates Verify), never *whether* the contract decision point fires. A
+high-risk task still refuses `auto` and forces a lowered rung (run.md guard).
+
 ## 4 · The one human gate — the baseline approval
 
 Open the report with the ARC (goal · done · plan) per `report-template.md`, then present

package/skill/add/phases/1-specify.md

@@ -18,7 +18,9 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 **Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
 color, the core palette, the typeface — are human-owned. Surface them for discussion during
 Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
-is the user's call (`udd-tokens.md`).
+is the user's call (`udd-tokens.md`). For a UI feature with a screen, run the design-definition
+loop in `design.md` — domain → research and reuse components → wireframe → a real captured screen
+the human confirms before build — and carry the confirmed layout into the contract.
 
 ## Produce (in TASK.md §1)
 
@@ -63,6 +65,8 @@ Never: resolve an ambiguity by guessing.
       "none material" that still names the single biggest risk (never a blank "none").
 </exit_gate>
 
+> **Advisor · Confidence** — for an unfamiliar domain, spawn a researcher (advisor.md); self-score the spec and let the lowest dimension aim your ⚠ flag (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/2-scenarios.md`.

package/skill/add/phases/2-scenarios.md

@@ -40,6 +40,8 @@ Never: settle for a vague result ("then it works") — results must be specific
 - [ ] Every rejection asserts what stays unchanged.
 </exit_gate>
 
+> **Advisor · Confidence** — delegate a wide scenario sweep when the surface is large (advisor.md); score Edge cases honestly — a missing case surfaces there first (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/3-contract.md`.

package/skill/add/phases/3-contract.md

@@ -66,6 +66,8 @@ Never: change a frozen contract — a change reopens Specify.
 - [ ] Every spec rejection has a contracted response.
 </exit_gate>
 
+> **Advisor · Confidence** — a second opinion on a risky shape is worth a spawn (advisor.md); a low self-score is your cue to lower autonomy before you freeze (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/4-tests.md`.

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

@@ -55,6 +55,8 @@ Never: implement the feature, or assert on internals.
 - [ ] Coverage target recorded.
 </exit_gate>
 
+> **Advisor · Confidence** — spawn a test-author for a broad red suite (advisor.md); score Completeness — one test per scenario, every rejection covered (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/5-build.md`.

package/skill/add/phases/5-build.md

@@ -55,6 +55,8 @@ Never: change a test or the contract; use a package off the allow-list; or push
 - [ ] Change small enough to review in full.
 </exit_gate>
 
+> **Advisor · Confidence** — delegate an independent, well-scoped batch (advisor.md); self-score before you present green, and refine while it is cheap (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/6-verify.md`.

package/skill/add/phases/6-verify.md

@@ -82,6 +82,8 @@ before the ask — per that file's reconcile rule (verify is where a flag-vs-dig
   (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
 </exit_gate>
 
+> **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (advisor.md); score the verdict before you record the gate (confidence.md).
+
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done
 # or: add.py gate RISK-ACCEPTED   |   add.py gate HARD-STOP (return to Build)

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

@@ -12,6 +12,11 @@ about the feature finally appears. Fill **§7** in TASK.md.
    one is a signal), latency of the risky operation under load.
 3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
    concrete change that re-enters the flow at Specify (a new task).
+4. **Propose a voice delta** — you just worked a whole task alongside the human, so
+   notice where your voice diverged from theirs (their wordings + flow) and propose a
+   confirmable **voice delta** that tunes `SOUL.md`. Emit it `open`; the human confirms;
+   only then do you rewrite the routed SOUL.md section. Read `soul.md` for the grammar,
+   the routing, and the human-is-only-writer rule.
 
 ## AI prompt
 
@@ -34,6 +39,8 @@ Never: auto-roll-back — recommend; a human owns the production decision.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
 </exit_gate>
 
+> **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 documents the next cycle refines.

package/skill/add/soul.md

@@ -0,0 +1,77 @@
+# Self-improving the voice — how SOUL.md converges to the human
+
+`SOUL.md` is the AI's voice (tone · communication style · trust). It ships as a **proposed starter**
+and is **human-owned**; this doc is how it stops being write-once and starts converging to *this*
+human. It mirrors `deltas.md` (emit) + `fold.md` (confirm → rewrite), but a confirmed voice delta is
+consolidated into **SOUL.md**, not the foundation — because voice is not one of the five competencies.
+
+You (the AI) **emit** voice deltas as `open`. Only the **human** confirms one, and only a confirmed
+delta rewrites SOUL.md. **The human's confirm is the only writer** — you never self-approve a voice
+rewrite (rewriting someone's voice is theirs to approve, like a foundation consolidation).
+
+## What a voice delta is drawn from
+
+A voice delta is grounded in how the human actually shows up **in session**:
+- their **wordings** — the words they reach for, and the words they correct you on (they cross out a
+  bit of jargon and write the plain word over it);
+- their **flow** — what they skip, what they double-check, where they want the summary before the detail.
+
+NOT from their private **memory** files or anything outside the working session — SOUL learns from what
+you observed together, never from reading a personal store.
+
+## The grammar (mirrors deltas.md)
+
+Each voice delta begins on its own tag line; the observation may wrap, and a required `(evidence: …)`
+clause closes it:
+
+```
+- [VOICE · <status>] <observation about the voice> (evidence: <in-session pointer>)
+```
+
+- `<status>` — `open` | `confirmed` | `declined`. A newly emitted delta is **`open`**.
+- `<observation>` — what the voice should become ("lead with the decision, not the preamble").
+- `(evidence: …)` — **required**, non-empty: a moment in the session (a correction, a re-ask, a
+  visible preference). No evidence → it is a guess about the human, not a delta. Drop it.
+
+```
+- [VOICE · open] the human strips hedging from my drafts — cut "I think / it seems" and state it plainly
+  (evidence: they rewrote two replies this session to remove the qualifier)
+```
+
+## The loop — observe → confirm → rewrite
+
+1. **Emit** (OBSERVE) — at a task's observe phase (or on demand), propose 0–N voice deltas as `open`
+   from the session's wordings + flow. Surface them in the report; show-before-ask.
+2. **Confirm** — the human accepts or declines each. **No SOUL.md write happens without this.**
+3. **Rewrite** — on a confirmed delta, edit the routed SOUL.md section, then record the delta line
+   (status `confirmed`) at the **top** of the "Voice deltas" ledger (**newest-first**, append-only — a
+   declined delta flips to `declined` and stays in place, so "considered, chose not to" is auditable).
+
+## Routing — every voice delta has a SOUL.md home
+
+| the delta is about… | rewrite this SOUL.md section |
+|---------------------|------------------------------|
+| how I *sound* (warmth, directness, hedging) | **## Tone** |
+| how I *structure* what I say (summary-first, show-before-ask, length) | **## Communication style** |
+| what keeps the human's *trust* (gates, honesty, what I never do) | **## Trust** |
+
+The rewrite is surgical: refine or append the bullet the delta names; never silently rewrite the rest
+of the voice. Every confirmed delta also gets its line in **## Voice deltas** (newest-first).
+
+## Reject codes (the AI is first check, the human the backstop)
+
+<reject_codes>
+- `unconfirmed_voice_rewrite` — a SOUL.md write was attempted without a recorded human confirm. The AI
+  proposes; it never self-approves. Stop and get the confirm. (The identity-owned floor.)
+- `no_open_voice_deltas` — nothing is `open`. The loop is a no-op; do not touch SOUL.md.
+- `unroutable_voice_delta` — the observation maps to no SOUL.md section (not tone/style/trust). Fix the
+  delta or widen the routing before writing.
+</reject_codes>
+
+## Where it plugs in
+
+- **Emit**: `phases/7-observe.md` proposes voice deltas beside its competency/spec deltas.
+- **Target**: `SOUL.md` (scaffolded by setup) — its "## Voice deltas" ledger holds the confirmed history.
+- **Kin**: `deltas.md` (competency learnings → foundation) and `fold.md` (the same propose→confirm→write
+  discipline). This is the voice's version of that discipline; the engine stays judgment-free (no
+  `add.py` command writes the voice).

package/skill/add/streams.md

@@ -1,8 +1,11 @@
 # Parallel streams — pipelining independent tasks
 
-Load this **only** when a milestone has more than one task and you want to run them
-concurrently. The default ADD path is one task at a time; this rubric is the opt-in
-escape hatch for when independent tasks are queued and a human is ready to review.
+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. Either way it changes nothing below.
 
 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 that
@@ -35,6 +38,44 @@ Compute both from one `python3 .add/tooling/add.py status` — no new state:
        └──────────────── a task gating PASS unblocks its dependents ──────────────┘
 ```
 
+## The DAG strategy — let the engine schedule the waves (`add.py waves`)
+
+Do **not** eyeball the READY-QUEUE by hand once a milestone has more than a couple of
+tasks — the engine computes the whole schedule from the dependency DAG `status` already
+holds. `add.py waves` (read-only, writes nothing) groups the active milestone's not-done
+tasks into **topological waves**, names the **critical path**, and emits an advisory
+**tier hint** — exactly the inputs you need to fan out effectively:
+
+```
+$ add.py waves
+milestone: v13-onboarding-polish
+wave 1: dag-scheduler, setup-suggest-milestone, setup-domain-deepdive, soul-artifact
+wave 2: setup-run-mode (deps: dag-scheduler), soul-self-improve (deps: soul-artifact)
+critical path: dag-scheduler → setup-run-mode  (2 tasks)
+tier hint: top → dag-scheduler, setup-run-mode; mid → the rest
+```
+
+Read the schedule as a strategy, not a command:
+
+- **Wave = a fan-out batch.** Every task in a wave has all its in-milestone deps already
+  PASS, so the whole wave is spawnable at once (one worker per task, `isolation="worktree"`).
+  Finish a wave, gate its tasks PASS, then `add.py waves` again — the next wave is unblocked.
+- **Run the widest wave first.** It hides the most build latency under the human's review
+  latency (the honest frame above): more concurrent builds while the reviewer reads one bundle.
+- **Spend your strongest model on the critical path.** The critical-path tasks gate the most
+  downstream work, so a wrong-but-plausible result there is the costliest — give them the
+  **top** tier (`run.md` tiers); off-path tasks take **mid**. The tier hint is exactly this rule,
+  applied to the graph. It is **advisory** — graph position is a proxy for scope difficulty, not a
+  gate; override it when you know a task is harder than its position suggests.
+- **`--json`** (`{ milestone, waves, critical_path, critical_path_len, tiers, blocked }`) feeds a
+  runner that spawns the wave programmatically. `blocked` lists any task whose dep can never be
+  satisfied within this milestone (a cross-milestone dep) — surfaced, never silently dropped; a
+  `dependency_cycle` is refused with the offending members named (no schedule exists).
+
+What `waves` does **not** change: the irreducible floor below still holds — one human approval
+per contract, builds overlap but the review queue stays serial. `waves` decides *order and model*,
+never *whether the human gate fires*.
+
 ## The autonomy level is the throttle (not a new flag)
 
 How much concurrency you actually get is set by each task's `autonomy:` header