@pilotspace/add 1.2.0 → 1.4.0

package/skill/add/run.md

@@ -28,7 +28,7 @@ What the human is actually approving in that one gate: that the drafted Spec cap
 that the Scenarios cover the cases that matter, and that the Contract shape is the one to freeze. Reject
 any part and the bundle goes back to draft — that is backward-correction (principle 4), not failure.
 Approve, and the run begins. The decision-point guide (`phases/3-contract.md`) carries the
-**freeze review checklist** — six lines that walk the human through exactly this, ⚠-first.
+**freeze review checklist** — seven lines that walk the human through exactly this, ⚠-first.
 
 **The lowest-confidence flag — aiming the one approval.** A single approval over a whole bundle is easy to
 grant without reading. So the AI presents the bundle **lowest-confidence first**: of everything it is asking the human
@@ -117,6 +117,34 @@ The auto-gate NEVER writes a human signature it did not get. An auto-PASS is log
 honestly — the line between a pass and a skip is the recorded outcome, not a forged name.
 </constraints>
 
+## The bounded self-heal loop — a confirmed cheat returns to build
+
+The auto-gate trusts evidence; but evidence can be **gamed**. A build can make the unchanged red suite
+pass without EARNING it — a test or the frozen contract edited after the red run, src **overfit** to the
+fixtures, **vacuous** asserts, or real logic **stubbed away**. That is a **confirmed cheat**, and a cheat
+is **HARD-STOP-class**: never auto-passed, never RISK-ACCEPTED-waived (like a security finding). But a
+first cheat is not yet a stop — it is a chance to redo honestly.
+
+So a confirmed cheat enters a **bounded self-heal loop**: the engine returns the task to **build** for an
+honest redo, **counts** the attempt, and **caps** it. After **3** honest re-build attempts a fourth
+confirmed cheat forces a **HARD-STOP that escalates to the human** — never an auto-PASS, never an unbounded
+loop. The engine COUNTS, CAPS, and ESCALATES; the **agent** does the honest re-build (the engine never
+auto-fixes). The counter is **monotonic** — it never auto-resets, so the cap cannot be cleared by
+re-crossing a phase; only an honest build (no cheat) escapes the loop, and an honest build PASSes even at
+the third attempt (the cap bites a *continued* cheat, never a recovery).
+
+Two findings enter the loop:
+- **mechanical** (enforced) — the tamper tripwire (`tamper-tripwire`): at the gate the engine re-hashes the
+  red test files + the frozen §3 against the `tests→build` snapshot; any divergence is a cheat, routed to
+  the loop before any completing outcome is recorded.
+- **semantic** (honor-system, necessary-not-sufficient) — the **adversarial refute-read** (`6-verify.md`):
+  an independent reviewer argues "the green was NOT earned" and, on a confirmed overfit/vacuous/stub, the
+  agent reports it with `add.py heal <slug> --reason "<finding>"`. The engine cannot SEE a judgment cheat,
+  so this entry is the agent's honest report — the human verify gate stays the real backstop.
+
+The mechanical entry returns-to-build automatically at the gate; the `heal` verb is how a *reported* cheat
+enters the same bounded loop. Either way: ≤3 honest redos, then escalate. A gamed green never ships.
+
 ## Emitting deltas — feeding the foundation back
 
 The completeness-critic does not discard what it finds. Every gap, surprise, or convention that helped
@@ -137,14 +165,19 @@ How much a run may auto-gate is a **per-scope setting**, not a global switch (pr
 earned per scope). A task declares its level in its `TASK.md` header:
 
 ```
-autonomy: auto | conservative
+autonomy: manual | conservative | auto
 ```
 
-- **auto (the default)** — the run may auto-PASS when the evidence + residue checks above are
+An ordered ladder — `manual < conservative < auto` — declared once in the header and reviewed at the freeze:
+
+- **auto (the seeded default)** — the run may auto-PASS when the evidence + residue checks above are
   satisfied. Security still always escalates. This is the default starting point: a frozen contract
   flips the task into a self-driving run that converges and auto-gates on evidence.
 - **conservative** — the deliberate *lowering*: the run does all the work and converges, but STOPS at
   the verify gate for a human. Auto-PASS is disabled. Choose it wherever evidence is thin or risk is high.
+- **manual** — the strict floor: the human owns the verify gate and the engine never auto-resolves
+  (behaviourally the conservative floor with the explicit "I drive this decision; the AI proposes only"
+  name). Choose it for the highest-stakes scope; like `conservative`, it satisfies the high-risk guard.
 
 > **v7 reversal (recorded, not hidden).** Earlier the default was `conservative` and `auto` was the
 > earned exception; v7 flips this — `auto` is the default, `conservative` is the deliberate lowering.
@@ -154,7 +187,8 @@ autonomy: auto | conservative
 **The high-risk guard — `auto` is refused where it matters most.** The autonomy level is not a blank cheque. On a
 **high-risk or method-defining scope** — anything where a wrong-but-plausible result is expensive or
 hard to reverse (auth, money, data-loss paths, the method/trust-layer itself) — `auto` must be lowered
-to `conservative`; leaving it at `auto` there is the reject code **`unguarded_high_risk_auto`**. This
+to a stricter rung — `conservative` or `manual`; leaving it at `auto` there is the reject code
+**`unguarded_high_risk_auto`**. This
 closes the v6 dogfood gap, where the whole milestone ran at `auto` on the riskiest possible
 scope (defining the method) with no friction. The default is `auto` *for ordinary, well-tested scope*;
 high risk still earns a human gate.
@@ -163,9 +197,18 @@ Judging *what* is high-risk stays human — the scope declares **`risk: high`**
 header where the autonomy level lives, reviewed at the freeze like every header line (the engine never
 classifies scope). **Since v14 the guard is mechanical for the declared case:**
 the engine refuses the declared combination — `add.py gate` will not complete (`PASS`/`RISK-ACCEPTED`) a task whose header
-carries `risk: high` without `autonomy: conservative` (error `unguarded_high_risk_auto`; `HARD-STOP`
+carries `risk: high` without a lowered level — `conservative` or `manual` (error `unguarded_high_risk_auto`; `HARD-STOP`
 always records — stopping is never blocked), and `add.py audit` flags the same code on a finished
 record whose header was tampered or whose GATE RECORD reviewer is the auto-gate — which CI enforces
 (audit-ci). The honest limit mirrors the audit's: an **undeclared** high-risk scope passes; declaring
 is the human decision point, the engine enforces what was declared.
+
+**Autonomy is earned by goal-clarity — the auto-ready goal.** The level decides *who* resolves Verify;
+an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is
+auto-ready when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the
+run can check its own result against the goal without human judgment. `add.py check` raises a
+`goal_not_auto_ready` WARN (never red, the active milestone only) while criteria are uncited, and `status`
+prints a `goal-ready:` line every session. It **measures, never blocks** — it changes neither the freeze
+gate nor the autonomy level. The lint forces a citation slot per criterion (raising the floor) but cannot
+prove the citation is honest (`(verify: it works)` passes) — that judgment stays the human's.
 </constraints>

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
@@ -42,9 +83,9 @@ How much concurrency you actually get is set by each task's `autonomy:` header
 
 | `autonomy` (TASK.md) | What serializes on the human | Concurrency |
 |----------------------|------------------------------|-------------|
-| `conservative` | bundle approval **+** every Verify | pure pipelining — builds overlap, both gates queue |
+| `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 → forced `conservative` (`unguarded_high_risk_auto`) | back to pipelining, by design |
+| `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 decision point** — the decision point
 never drops to zero (`run.md:22`). That floor is correct; do not engineer around it.
@@ -72,6 +113,16 @@ never drops to zero (`run.md:22`). That floor is correct; do not engineer around
   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.
+  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
@@ -114,7 +165,10 @@ base: <orchestrator HEAD at spawn — the sha every fork must equal>
 `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`).
+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
@@ -181,7 +235,7 @@ 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.
@@ -204,7 +258,9 @@ 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 lessons learned] }.
 Do NOT touch add.py or any shared file — the orchestrator gates on your verdict.
@@ -222,7 +278,7 @@ The contract is identical whichever model runs it (the model is disposable, like
 | **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.