@pilotspace/add 1.1.0 → 1.3.0

package/skill/add/streams.md

@@ -11,9 +11,9 @@ orchestrator*, drive several tasks at once by reading the dependency DAG that
 ## The honest frame — this is pipelining, not N× speed
 
 With **one human reviewer** you cannot beat `review_time × N_tasks` (the human-led
-seams are serial — `docs/10-setup-and-stages.md:91`). So the win is **not throughput**:
+decision points are serial — `docs/10-setup-and-stages.md:91`). So the win is **not throughput**:
 it is that the reviewer is **never blocked waiting on a build**. While the human reviews
-task A's frozen front, the builds for B·C·D run behind *their* frozen contracts. You hide
+task A's frozen bundle, the builds for B·C·D run behind *their* frozen contracts. You hide
 build latency under human latency. Do not promise more than that.
 
 ## The two queues
@@ -24,33 +24,34 @@ Compute both from one `python3 .add/tooling/add.py status` — no new state:
   `deps=` task already shows `gate=PASS`. These are the only tasks a worker may pick up.
   A task with unmet deps stays queued; a task finishing PASS unblocks its dependents on
   the next `status`.
-- **REVIEW-QUEUE** — the irreducibly serial part: the **one-approval front** (contract
+- **REVIEW-QUEUE** — the irreducibly serial part: the **bundle approval** (contract
   freeze) and any **Verify escalation**. One human, one queue. Present these one at a
-  time, never in a batch the human will rubber-stamp.
+  time, never in a batch the human will approve without reading.
 
 ```
   add.py status ─► READY-QUEUE ──spawn workers──► builds run ──► REVIEW-QUEUE ──► done
-  (deps=PASS?)     (machine span)                 (concurrent)   (human seams,
+  (deps=PASS?)     (machine span)                 (concurrent)   (decision points,
        ▲                                                          strictly serial)
        └──────────────── a task gating PASS unblocks its dependents ──────────────┘
 ```
 
-## The dial is the throttle (not a new flag)
+## The autonomy level is the throttle (not a new flag)
 
 How much concurrency you actually get is set by each task's `autonomy:` header
 (`run.md`), not by this rubric:
 
 | `autonomy` (TASK.md) | What serializes on the human | Concurrency |
 |----------------------|------------------------------|-------------|
-| `conservative` | one-approval front **+** every Verify | pure pipelining — builds overlap, both gates queue |
-| `auto` (default) | one-approval front **only**; Verify auto-PASSes on evidence | real concurrency — only the seam + residue escalations queue |
-| `auto` but **high-risk** | refused → forced `conservative` (`unguarded_high_risk_auto`) | back to pipelining, by design |
+| `conservative` / `manual` | bundle approval **+** every Verify | pure pipelining — builds overlap, both gates queue (`manual` is the strict floor; same streams behaviour) |
+| `auto` (default) | bundle approval **only**; Verify auto-PASSes on evidence | real concurrency — only the decision point + residue escalations queue |
+| `auto` but **high-risk** | refused → must lower to `conservative` / `manual` (`unguarded_high_risk_auto`) | back to pipelining, by design |
 
-The irreducible floor is **one human approval per task at the contract seam** — the seam
+The irreducible floor is **one human approval per task at the contract decision point** — the decision point
 never drops to zero (`run.md:22`). That floor is correct; do not engineer around it.
 
 ## Who writes what — the hard boundary
 
+<constraints>
 - **You (orchestrator)** own all shared writes: `MILESTONE.md`, and every
   `add.py advance <slug>` / `add.py gate <outcome> <slug>` call. **Always pass the explicit
   `<slug>`** — `advance`/`gate`/`phase` all take an optional task slug and act on it
@@ -62,21 +63,83 @@ never drops to zero (`run.md:22`). That floor is correct; do not engineer around
 - **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.
+</constraints>
 
 ## Design for failure (required)
 
 - **Fresh worktree base (verify base == HEAD)** — create each worker's worktree from current
-  `HEAD` **after** you commit the task's frozen front (spec · scenarios · contract · tests). A
+  `HEAD` **after** you commit the task's frozen specification bundle (spec · scenarios · contract · tests). A
   worktree forked from a stale base forces the worker to recreate the frozen artifacts by hand
   (the v10 dogfood hit exactly this). Before the worker starts, confirm `git -C <worktree>
   rev-parse HEAD` equals the orchestrator's `HEAD`; if it drifted, `git merge` the base in first.
-- **Lease + timeout** — record which worker holds which task; if a worker dies, release
-  the claim back to READY (re-spawn, do not assume partial work is sound).
+  On a runner that creates each worktree **at spawn** from a pool (e.g. Claude Code), that pool can hand
+  out a STALE base, so the pre-spawn `rev-parse` evidence cell is unsatisfiable. The `unverified_fork_base`
+  check then **shifts** — it never skips: the worker's **step-0** syncs to base (`git merge` the orchestrator's
+  `HEAD`) and re-echoes `rev-parse HEAD`, which the orchestrator verifies at **merge-time**, before merge-back.
+  The pre-spawn check stays the DEFAULT for fresh-`HEAD`-worktree runners; the merge-time path is the additive
+  ALTERNATIVE for spawn-time runners — never a replacement of the pre-spawn rule.
+  **The engine executes this gate** (engine-merge-base-enforcement): run
+  `python3 .add/tooling/add.py wave-verify` before the first merge-back — it refuses a mismatched or
+  pending echo (`unverified_fork_base`) and an off-template ledger (`wave_ledger_malformed`, fail-closed);
+  `add.py check` is the standing monitor (red at `status: merging`, `fork_base_pending` WARN at `live`).
+- **Lease + timeout** — record which worker holds which task (in the wave ledger, below);
+  if a worker dies, release the claim back to READY (re-spawn, do not assume partial work is sound).
 - **Failure isolates** — a worker that hits a STOP-and-escalate (below) blocks only its
   own task. Siblings keep running; the escalation joins the REVIEW-QUEUE.
 - **Circuit-breaker** — if N workers fail in a wave, stop fanning out and fall back to
   sequential. Repeated failure means the scope was wrong, not the parallelism.
 
+## Wave ledger — the wave's resume point
+
+A single task resumes from `state.json`; a wave used to resume from nothing — the
+task ↔ lease ↔ fork-base ↔ autonomy ↔ merge-order mapping lived only in the orchestrator's
+chat context, and the v12-1 recurrence proved that discipline without an artifact fails
+(the base check existed in prose and never ran). The ledger fixes both: it is the file you
+re-orient from, and its evidence cells cannot be filled without executing the checks.
+
+**The file** — `.add/milestones/<m>/WAVE.md`, orchestrator-owned like `MILESTONE.md` and
+`state.json`. ONE live wave per milestone at a time; opening a second while one is live is
+refused (`wave_already_live`). **Workers never read WAVE.md** — the orchestrator copies the
+relevant mid-wave decisions into each worker's PROMPT.md at spawn/respawn, so the worker
+contract below stays unchanged and no worker widens into sibling state.
+
+```markdown
+# WAVE.md — transient wave ledger (orchestrator-owned · one live wave per milestone)
+wave: <n> · opened: <date> · status: live|merging
+base: <orchestrator HEAD at spawn — the sha every fork must equal>
+
+### Roster (lease ledger)
+| task   | lease (worker) | fork-base (pasted)                          | autonomy | spawned | timeout |
+|--------|----------------|---------------------------------------------|----------|---------|---------|
+| <slug> | wt-a           | <paste `git -C <wt> rev-parse HEAD` output> | auto     | <time>  | <dur>   |
+
+### Mid-wave decisions
+- <date> <decision a later or respawned worker must honor — copy it into that worker's PROMPT.md>
+
+### Merge order (serial; integration Verify per merge)
+1. <slug> → 2. <slug>
+```
+
+**Evidence cells, not ticks.** The fork-base cell holds the PASTED output of
+`git -C <worktree> rev-parse HEAD`, and it must equal `base:`. A tick is not evidence; a row
+you can only fill by running the command is the fresh-worktree-base check EXECUTING — the
+v12-1 lesson (words-exist ≠ method-works) closed structurally. Spawning a worker whose roster
+row lacks that evidence is refused (`unverified_fork_base`). On a spawn-time pool runner this
+PRE-spawn paste is unsatisfiable (the pooled base is stale until the worker syncs), so the cell
+instead holds the worker's **step-0** post-sync echo (still `== base:`) and the `unverified_fork_base`
+refusal **shifts to merge-time**, before merge-back — it shifts, it never lifts.
+
+**Lifecycle — open → consume → digest → delete.** Open the ledger when the first worker
+spawns. The serial integration Verify consumes it (the merge order is read from it, one
+worktree at a time). At wave close, absorb the evidence digest — wave base · roster→fork-base
+evidence · merge order · integration-Verify outcome — into `MILESTONE.md` as an append-only
+`## Wave log` block (this is the integration-Verify *record*, previously homeless), and only
+then remove the file. Removing WAVE.md before the digest is absorbed is refused
+(`digest_not_absorbed`) — the proof the checks ran must outlive the file.
+
+**Resume rule.** On session start, a live WAVE.md is the wave's resume point: re-orient from
+the file — roster, bases, decisions, merge order — never from conversational memory.
+
 ## Merge is serial — integration Verify
 
 Parallel build, **serial integration**. After workers return, you merge the worktrees
@@ -85,8 +148,8 @@ checks that `run.md:102` says automation cannot judge. Two green tasks in isolat
 still conflict when merged; this step is where that surfaces. Never auto-pass it.
 
 Each worktree carries a full copy of `.add/`. Merge back **only** `src/`, `tests/`, and the
-worker's own `.add/tasks/<slug>/` (TASK.md · SUMMARY.md) — `.add/state.json` and
-`MILESTONE.md` stay orchestrator-owned, or a parallel merge will drag stale state back.
+worker's own `.add/tasks/<slug>/` (TASK.md · SUMMARY.md) — `.add/state.json`, `MILESTONE.md`,
+and the live `WAVE.md` stay orchestrator-owned, or a parallel merge will drag stale state back.
 
 ## The worker contract — portable across coding agents
 
@@ -107,7 +170,7 @@ changes. Fill every `{{...}}` per stream. The ADD-specific value is `<touch_boun
 Execute the LOCKED dynamic run for task '{{TASK_SLUG}}' in milestone {{MILESTONE}}:
 drive §4 TESTS red→green against the FROZEN contract {{CONTRACT_VERSION}}, converge, and
 resolve verify per autonomy={{AUTONOMY}}. You own ONLY the machine-led span — the two human
-seams (front approval · escalated Verify) are NOT yours.
+decision points (bundle approval · escalated Verify) are NOT yours.
 </objective>
 
 <persona>
@@ -126,12 +189,12 @@ Self-Eval; if any < 0.9, refine before returning.
 <touch_boundary>   <!-- from run.md:56-73; the worker's contract, identical on every runner -->
 MAY:  rewrite code in src/ · drive tests green WITHOUT weakening them · gather verify evidence.
 MUST NOT: edit the frozen CONTRACT or locked scope · weaken/delete/skip any test ·
-          touch §1–§3 front artifacts · write MILESTONE.md / state.json / any sibling stream.
+          touch §1–§3 bundle artifacts · write MILESTONE.md / state.json / any sibling stream.
 STOP-and-escalate (return your findings; do not decide):
   • a discovered scope/contract gap  → backward-correction, reopen Specify (principle 4)
   • any SECURITY finding              → HARD-STOP, always
   • a concurrency/timing OR architecture/layering risk the tests cannot exercise
-  • [include this bullet ONLY when autonomy=conservative] the verify gate itself — STOP for the human
+  • [include this bullet when autonomy is conservative OR manual — any lowered rung] the verify gate itself — STOP for the human
 Auto-PASS only if autonomy=auto AND: all tests green · coverage not decreased · no test weakened ·
   no contract edited · loops dry · completeness-critic clean · no residue above. Log it as
   auto-resolved, naming this run as owner — never forge a human signature.
@@ -154,9 +217,11 @@ ripgrep otherwise. Design every IO path for failure — timeouts, retries, rollb
 </tools>
 
 <return>   <!-- the worker PROPOSES; the orchestrator RECORDS. A worker never runs add.py. -->
-End with a structured verdict AND write the same into SUMMARY.md in the task dir:
+End with a structured verdict AND write the same into SUMMARY.md in the task dir, then
+**commit SUMMARY.md + deltas.md** in the worktree (uncommitted worktree files survive only by
+harness courtesy — commit them so the serial-integration merge-back carries your report):
 { task, outcome: PASS|RISK-ACCEPTED|HARD-STOP|ESCALATE, evidence: <tests+coverage>,
-  residue: [security|concurrency|architecture findings], deltas: [open competency deltas] }.
+  residue: [security|concurrency|architecture findings], deltas: [open lessons learned] }.
 Do NOT touch add.py or any shared file — the orchestrator gates on your verdict.
 </return>
 ```
@@ -169,10 +234,10 @@ The contract is identical whichever model runs it (the model is disposable, like
 | Tier | When | Claude Code | Any other runner |
 |------|------|-------------|------------------|
 | **mid** | ordinary, well-tested scope; clear contract | `sonnet` | the runner's balanced model |
-| **top** | complex / ambiguous / cross-cutting / large blast radius | `opus` | the runner's strongest reasoning model |
+| **top** | complex / ambiguous / cross-cutting / broad scope of impact | `opus` | the runner's strongest reasoning model |
 
 Two rules sit **above** model choice and never bend:
-- **High-risk ⇒ `conservative` autonomy, regardless of model** (`run.md` high-risk guard). A
+- **High-risk ⇒ a lowered rung (`conservative` or `manual`), regardless of model** (`run.md` high-risk guard). A
   stronger model does not buy back the human gate.
 - **Security residue always escalates** — no tier and no model auto-passes it.
 
@@ -186,7 +251,7 @@ worktree, then points the agent at that directory.
 |-----------|----------|----------------------------------|-----------------------------------------------|
 | spawn a worker | prompt + label | `Task(description=…, prompt=…)` | `cd $WT && <agent> run --prompt-file PROMPT.md` |
 | pick the model | tier → id | `model="opus"\|"sonnet"` | a `--model <id>` flag |
-| isolate | worktree | `isolation="worktree"` | `git worktree add $WT HEAD` (after committing the front; verify base == HEAD), then run inside it |
+| isolate | worktree | `isolation="worktree"` | `git worktree add $WT HEAD` (after committing the bundle; verify base == HEAD), then run inside it |
 | load context | files / cwd | `<context_files>` + repo cwd | run inside `$WT`; paths are relative |
 | domain expertise | skill / preamble | a Claude skill in `<expertise>` | a system-prompt / profile preamble |
 | return a verdict | structured | final message (optionally a schema) | stdout JSON the orchestrator parses |