@pilotspace/add 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.4.0] — 2026-06-15
+
+The guided-onboarding release: starting and running an ADD project is now guided
+and self-tuning. Setup interviews you into a run mode and a first milestone and
+deepens each drive, the engine schedules parallel work into dependency waves,
+stale installs nudge any agent to update, and the AI carries a human-owned voice
+that improves itself. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **Guided, self-tuning setup** — `0-setup` now interviews instead of assuming:
+  it proposes a **run mode** (a parallel+auto vs. sequential comparison table,
+  confirm-to-keep the recommended default), sketches a **first milestone** as a
+  kickoff suggestion (goal + flow + scenarios, shown before it asks), and runs a
+  per-drive **domain deep-dive** (DDD · SDD · UDD · TDD) that captures the
+  decisions as ADRs. Onboarding stops being a blank page.
+- **`add.py waves` DAG scheduler** — a new read-only command that groups the
+  active milestone's open tasks into topological **waves** (a wave is the tasks
+  whose in-milestone dependencies have all landed), names the **critical path**,
+  emits an advisory **tier hint** (a scope-of-impact proxy for model selection,
+  never a gate), and surfaces a transitively-**blocked** set with what each task
+  is waiting on. It never mutates state and `streams.md` gains a "DAG strategy"
+  section that points at it.
+- **`SOUL.md` — a human-owned, self-improving voice** — `init` now scaffolds a
+  `.add/SOUL.md` voice doc (schema: Name · Tone · Communication style · Trust ·
+  Learns-from · Voice deltas) with a *proposed* "Trusting" starter voice that is
+  explicitly yours to rewrite — the tests assert the schema, never the tone words.
+  `status` points at it to read each session, and a new `soul.md` guide drives an
+  observe→confirm→rewrite **voice-delta loop** (the human is the only writer),
+  the voice-side sibling of the competency-delta→foundation loop.
+- **Agent-agnostic update nudge** — because every agent is told to run
+  `add.py status`/`guide` first each session, the engine uses that one universal
+  chokepoint to flag a stale install: on those orientation reads only, when a
+  launcher `.add-version` stamp is present and the registry's latest is newer, it
+  writes one `ACTION REQUIRED` line to **stderr** naming the channel-correct
+  command (`npx @pilotspace/add@latest update` / `pipx run pilotspace-add
+  update`). It is the engine's one deliberate, tightly-bounded network touch:
+  fail-open (offline/timeout → silent no-op), throttled once per 24 h via a
+  git-ignored `.update-cache.json`, inert without a launcher stamp, and silenced
+  by `ADD_NO_UPDATE_CHECK=1`. stdout and exit codes are never touched, so `--json`
+  stays clean. (Originated as community PR #17.)
+- **First-class `add.py autonomy show|set`** — autonomy was the only mutable
+  first-class state with no CLI verb, so an agent driving under `autonomy: auto`
+  could hallucinate the missing `add.py autonomy` command, hit `invalid choice`,
+  and derail an autonomous run. `autonomy show` prints declared · effective
+  (fallback-resolved) · project default · the verify-gate owner; `autonomy set
+  <level> [slug] [--project] [--yes]` is the first writer of the `autonomy:`
+  header token — an idempotent, atomic single-line rewrite (trailing comment
+  preserved, never appended) with three fail-closed guards run before any write:
+  an invalid level, raising the rung without `--yes` (raising is a human-owned
+  trust escalation), and raising a `risk: high` task to `auto`. The command-shaped
+  header-edit wording is de-shaped to cite the verb, and an `[enforced]`
+  `WORDING_RUBRIC` fence keeps the phantom phrasing from regressing.
+- **Foundation compaction across all four specs** — the living foundation now
+  stays relevant-first and short as a project grows. Every append-only sequence
+  (`PROJECT.md` §Spec · §Key-Decisions · `CONVENTIONS.md` learnings) reads
+  **newest-first**, and at milestone close the AI proposes collapsing each spec's
+  shipped, zero-open-residue tail into one per-spec **rolled-up settled line** —
+  the human confirms one line at a time; it summarizes and points to git, never
+  deletes, and every open residue stays expanded. A new `compact-foundation.md`
+  skill guide drives the ritual — convention-guided, with no new engine command,
+  and distinct from `add.py compact` (which archives finished-milestone files).
+  The loop chapter and glossary document it.
+- **Per-step Advisor + Confidence context** — every ADD step now carries a thin
+  pointer to two new shared skill guides: `advisor.md` (when and how to delegate
+  one plan-following subagent — vendor-neutral; the engine never spawns) and
+  `confidence.md` (an advisory 0–1 self-score across six dimensions, refine if any
+  dimension scores below 0.9). Both are advisory by construction — the self-score
+  is never a gate — making delegate-and-self-assess first-class guidance for any
+  agent driving the loop.
+- **`.add/.gitignore` scaffolded at init** — `init` now writes a co-located
+  `.add/.gitignore` so the engine's transient local artifacts (scope snapshots,
+  pre-archive backups, the update-nudge cache) never reach git. It is additive and
+  never clobbers an existing copy; edit it freely.
+
+### Changed
+- **Conversational-only install hand-off** — after `init`, the closing hint points
+  only at the conversational entry point: open your AI agent CLI, run `/add`, and
+  say what you want to build. The hand-off is tool-agnostic (Claude Code, Codex,
+  …) and no longer advertises a manual `add.py new-task` / `--await-lock` escape
+  as the primary path (the flag still exists; `/add` runs it internally).
+
 ## [1.3.0] — 2026-06-13
 
 The render-ready-foundation release: a UI project now gets a lintable design

package/GETTING-STARTED.md

@@ -343,6 +343,10 @@ You just ran the method; now read *why* it's shaped this way:
 - Each step in depth — `.add/docs/03-step-1-specify.md` through `.add/docs/09-the-loop.md`
 - Operating it on a team — `.add/docs/11-governance.md`, `.add/docs/12-roles.md`
 - A fully worked example — `.add/docs/appendix-d-worked-example.md`
+- Building UI? The render-ready UDD foundation — `.add/DESIGN.md` is the prose
+  front-door to a lintable design system (`.add/design/` tokens · catalog ·
+  prototypes) the AI drafts from; `add.py check` lints it (delete `DESIGN.md` if
+  your project has no UI)
 
 The rule to remember: **build the right thing (direction), prove it's right
 (verification), and let the AI do the building in between.**

package/README.md

@@ -46,6 +46,12 @@ pilotspace-add init
 No flags needed — the project name is inferred from your folder and the stage
 defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
 
+**Already installed?** Refresh to the latest without a re-install —
+`npx @pilotspace/add@latest update` (or `pipx run pilotspace-add update`)
+re-materializes the skill, tooling, and book while leaving your project work
+(`.add/state.json`, `PROJECT.md`, milestones, tasks) untouched; add `--check` to
+see whether a project is behind the installed package.
+
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
 your first feature end to end.
 
@@ -56,11 +62,18 @@ This installs:
 | `.claude/skills/add/` | the `add` skill Claude loads (thin router + per-phase guides) |
 | `.add/tooling/add.py` | scaffolder + state tracker (Python, stdlib only) |
 | `.add/docs/` | the AIDD book — the method rationale |
+| `.add/DESIGN.md` | (UI projects) the prose front-door to the **render-ready UDD foundation** — delete it if your project has no UI |
+
+On a UI project, UDD gives the AI a frozen design ground to draft from: `DESIGN.md`
+plus a lintable JSON foundation under `.add/design/` (design tokens · component
+catalog · prototype trees). `add.py check` lints that foundation, going red with a
+named code on any layer, catalog, tree, or cross-file violation — and staying
+silent when a project has no design set.
 
 Project state (`.add/state.json`) and the living-documentation files (`CONVENTIONS.md`,
-`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`) are *not* created
-here — the installer drops files only; initialisation is the agent's first move
-when you run `/add`.
+`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, `SOUL.md` — the AI's
+human-owned voice) are *not* created here — the installer drops files only;
+initialisation is the agent's first move when you run `/add`.
 
 ## Use it
 

package/bin/cli.js

@@ -102,15 +102,10 @@ function cmdInit(args) {
   // (via `/add`) or a CLI user — a pre-run plain `add.py init` would grandfather-lock
   // the v12 lock-down gate before `/add` runs (see file header). So no Python is run here.
   log("\nDone. The `add` skill + tooling are installed (no project state yet — that's intentional).");
-  log("Next:  open Claude Code, run `/add`, and say what you want to build — the agent");
+  log("Next:  open your AI Agent CLI (like Claude Code, Codex, etc.), then run `/add`, and say what you want to build — the agent");
   log("       sets up the foundation, sizes it into a milestone, and drives the build with you;");
   log("       you sign off once, at the lock-down.");
   log("");
-  log("Prefer the CLI / not using Claude Code? Initialise it yourself (this arms the lock-down):");
-  const launcher = process.platform === "win32" ? "py" : "python3";
-  log(`  ${launcher} .add/tooling/add.py init --await-lock` +
-      (args.stage ? ` --stage ${args.stage}` : "") +
-      (args.name ? ` --name "${args.name}"` : ""));
 }
 
 // --- update: re-materialize the managed layer without a re-install -----------

package/docs/09-the-loop.md

@@ -47,10 +47,12 @@ A spec delta feeds the *next feature*. But a loop also teaches the **method itse
 
 Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evidence: a pointer)` — and the evidence is **required**: a failing scenario, a production signal, a review note. No evidence means it is an opinion, not a delta. The AI **emits** deltas as `open`; it never consolidates its own. Consolidation is judgment, and judgment is the human's — the same verify/observe decision point that keeps the AI from grading its own work.
 
-**The consolidation.** At milestone close (or on demand, when open deltas pile up), a person runs the retrospective consolidation: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas consolidate into the matching section of `PROJECT.md`; `TDD`/`ADD` consolidate into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** consolidation also appends one row to `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
+**The consolidation.** At milestone close (or on demand, when open deltas pile up), a person runs the retrospective consolidation: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only, newest-first (the newest record prepended at the top) — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas consolidate into the matching section of `PROJECT.md`; `TDD`/`ADD` consolidate into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** consolidation also prepends one row at the top of `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
 
 **Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be consolidated is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. There is deliberately **no `add.py fold`**: the engine stays judgment-free, and the ritual lives with the human who owns it.
 
+**Foundation compaction.** The consolidation *prepends* new learnings; **foundation compaction** is the separate, later step that *shrinks* the result. At milestone close (or on demand, once a foundation spec grows past one screen), the AI proposes collapsing the stable, shipped, zero-residue tail of each foundation spec into ONE per-spec **rolled-up settled line** at the bottom — and the human confirms, one line at a time, exactly as with the consolidation. It never deletes: a settled line summarizes the prose and keeps a `see git` pointer, so the record is lossy on wording but lossless on traceability, and any OPEN residue always stays live. Each spec collapses in its own **per-spec shape** — `PROJECT.md` §Spec version bullets, §Key-Decisions rows, `CONVENTIONS.md` learnings, the `GLOSSARY.md` definition, the `MODEL_REGISTRY.md` rows — under one shared eligibility rule. Because every append-only sequence is **newest-first** (newest record on top), compaction collapses *upward from the bottom*: the settled line anchors at the tail (the oldest end). Like the consolidation it is convention-guided — there is deliberately no `add.py` command for it (read `compact-foundation.md`) — and it is distinct from the engine's `add.py compact <slug>`, which archives a finished milestone's files rather than shrinking a living spec.
+
 ## Re-entrancy: the loop is the whole point
 
 Two principles converge here. *The flow is re-entrant* — any step can send you back to an earlier one — and *the flow is a loop* — production feeds the next specification. Together they mean the artifacts you built are never "finished"; they are living documents that the next cycle refines.

package/docs/appendix-c-glossary.md

@@ -100,6 +100,14 @@
 
 **Verification capacity / review throughput** — the rate at which a team can confirm AI output is correct; the real ceiling on safe speed.
 
+**Foundation compaction** — the retrospective shrink: collapse a foundation spec's stable, shipped, zero-residue tail into one rolled-up settled line; the AI proposes and the human confirms; summarize and point, never delete; a SEPARATE step from the retrospective consolidation; distinct from the engine `add.py compact` (which archives finished-milestone files). See **Rolled-up settled line**, **Per-spec shape**.
+
+**Rolled-up settled line** — the single line a compaction leaves in place of a collapsed run of records: lossy on prose, lossless on traceability (it carries a `see git` pointer).
+
+**Per-spec shape** — each foundation spec's own tailored rolled-line format (PROJECT §Spec bullets · §Key-Decisions rows · CONVENTIONS learnings · GLOSSARY definition · MODEL_REGISTRY rows), all sharing one eligibility rule: shipped + zero open residues.
+
+**Newest-first append-only** — every append-only foundation sequence prepends the newest record at the top; the rolled-up settled line anchors at the bottom (the oldest end), so compaction collapses upward.
+
 ---
 
 ## Optional mapping to formal phase names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -31,6 +31,11 @@ Run the tool to find the resume point instead of re-reading the repo:
 python3 .add/tooling/add.py status
 ```
 
+`status` points at two things to read when orienting: `.add/PROJECT.md` (the foundation) and
+`.add/SOUL.md` (your **voice** — tone, communication style, what keeps the human's trust). Read
+`.add/SOUL.md` each session and let it shape how you speak; it is human-owned and self-improving
+(the `soul-self-improve` path proposes voice deltas the human confirms).
+
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
   `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
@@ -86,13 +91,20 @@ In **observe**, also emit **lessons learned** — learnings tagged by which of t
 (`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
 You write them as `open`; the human consolidates them into `PROJECT.md`. Read `deltas.md` for the
 grammar and the status lifecycle. At milestone close (or on demand), run the retrospective consolidation that
-gathers confirmed deltas into a versioned foundation — read `fold.md`.
+gathers confirmed deltas into a versioned foundation — read `fold.md`. Then (or on demand) compact the stable tail of each foundation spec into a rolled-up settled line — read `compact-foundation.md` (a SEPARATE step, run after `fold.md`).
+
+Observe also tunes your **voice**: propose a confirmable **voice delta** from the human's wordings +
+flow that, once they confirm, rewrites `SOUL.md` (the human is the only writer) — read `soul.md`.
 
 ## Beyond the bundle — load on demand
 
 Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
 (`autonomy: auto` default, lowered to `conservative` or `manual` for a human gate) — read `run.md`. To
-pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
+pipeline several ready tasks behind their own frozen contracts, read `streams.md`. To delegate
+one piece of your plan to a subagent that follows it — when to spawn, the plan-following prompt
+template, the tier pick — read `advisor.md`; and at any decision point self-score your draft
+(0–1 across six dimensions, refine if any < 0.9) with `confidence.md`. Both are advisory: the
+engine never spawns, and the self-score is never a gate.
 
 When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
 yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns

package/skill/add/advisor.md

@@ -0,0 +1,75 @@
+# Advisor — spawning one subagent to follow your plan
+
+The **advisor** strategy is for the orchestrating agent: spawn a *single* subagent to execute
+one piece of your plan, then merge its verdict back in. It is the single-subagent companion to
+`streams.md` — streams pipelines *many* independent tasks in parallel worktrees; the advisor
+delegates *one* well-scoped piece (a sweep, a review, a batch) while you stay in the loop. The
+engine never spawns; this is your judgment to make per step.
+
+## When to spawn — and when not
+
+Spawn a subagent when the piece is **separable and worth the round-trip**:
+
+- **Broad / expensive sweep** — gather a wide map cheaply, return a compact result (the `0-ground`
+  broad sweep is the canonical case).
+- **Independent adversarial review** — a fresh context argues *against* your result (the `6-verify`
+  earned-green refute-read), so the check is not graded by the author.
+- **A well-scoped delegable batch** — a self-contained slice with a clear contract and return shape.
+- **Context offload** — work that would bloat your context but compresses to a small verdict.
+
+Do **not** spawn when the work is narrow and cheap enough to do in-context: a small sweep, a
+two-file read, a quick edit. A spawn costs a round-trip and a fresh context — pay it only when
+the piece is big or independent enough to earn it. When in doubt, do it in-context.
+
+## The plan-following prompt template
+
+Give the subagent the *piece of your plan it owns* and a fixed return shape. This reuses
+`streams.md`'s worker-contract tags for a single advisory subagent — the contract is identical
+on any runner; only the spawn adapter (see `streams.md`) changes.
+
+```xml
+<objective>
+Execute THIS piece of the orchestrator's plan: {{PIECE}}. You own only this piece — not the
+surrounding decisions. Return a verdict; do not record state.
+</objective>
+
+<persona>
+You are a {{DOMAIN}} engineer. Correctness over speed; a wrong-but-plausible result is expensive.
+Work step by step, following the plan:
+1. Load the context files; confirm you understand the piece you own.
+2. Do the work in small steps, honoring the orchestrator's plan and constraints.
+3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
+</persona>
+
+<context_files>
+the plan / task files the piece needs (read-only unless the piece says otherwise)
+</context_files>
+
+<return>
+End with a structured verdict the orchestrator parses and RECORDS:
+{ piece, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
+Do NOT run add.py or write any shared state — you propose, the orchestrator records.
+</return>
+```
+
+## Choosing the model — vendor-neutral tiers
+
+Reuse `streams.md`'s tiers, never a new vocabulary: **mid** (Claude Code: `sonnet`) for ordinary,
+well-scoped pieces with a clear contract; **top** (Claude Code: `opus`) for complex, ambiguous, or
+cross-cutting pieces. The tier maps to the runner's model id through the same adapter `streams.md`
+defines. A stronger model never buys back a human gate: high-risk scope still escalates.
+
+## The hard rule — you delegate, you do not abdicate
+
+<constraints>
+The engine never spawns — spawning is the orchestrating agent's choice (tool-agnostic). And:
+- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared
+  state (state.json, MILESTONE.md, a sibling's files): you read its verdict and record the outcome;
+- delegation never lowers a gate — a SECURITY finding still HARD-STOPs, and high-risk scope still
+  escalates to the human, whoever (or whatever tier) did the work;
+- the spawned subagent returns its confidence.md self-score; a low score is a signal to refine or
+  re-spawn, never a pass.
+</constraints>
+
+> Used per step: each phase guide's Advisor hook points here, so an agent spawns in the idiom of
+> the phase it is in (see the per-step hooks).

package/skill/add/compact-foundation.md

@@ -0,0 +1,53 @@
+# Foundation compaction — collapse the stable tail
+
+This is the **retrospective shrink**. `fold.md` PREPENDS new learnings (newest-first); foundation
+compaction later COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — so
+PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md keep to one screen as the project grows.
+
+You (the AI) **gather and propose**; the **human confirms**; you then write the settled line. This is a
+**convention**, not a command — there is no `add.py compact-foundation` (the engine stays judgment-free).
+It is DISTINCT from the engine `add.py compact <slug>` (the archive recovery-bundle move).
+
+## When
+
+At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen.
+Compaction is a SEPARATE step from `fold.md` — never merged into the retrospective consolidation.
+
+## Eligibility (one shared test)
+
+An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries
+**zero open residues**/deltas. An unshipped or open-residue entry is NOT eligible — leave it live
+(`open-residue-version`).
+
+## The ritual
+
+1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec (its oldest entries).
+2. **Propose** — draft the per-spec rolled-up settled line (see the shapes below) and show the human.
+3. **Confirm** — the human accepts or declines. No write happens without confirmation.
+4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records
+   stay on top, the settled line anchors at the tail), carrying a git/archive pointer.
+
+## Per-spec rolled-line shapes (from the frozen compaction-contract)
+
+- **PROJECT.md §Spec** — a run of stable `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
+- **PROJECT.md §Key-Decisions** — matching shipped rows → one `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` row at the tail.
+- **CONVENTIONS.md** — a run of stable `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
+- **GLOSSARY.md** — a verbose, stable definition → its terse canonical line + `(rationale: see git)`. *(forward-looking — small today.)*
+- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`. *(forward-looking — nothing to compact yet.)*
+
+## Preservation (every collapse)
+
+- **Never delete** — summarize and point; a settled line is lossy on prose, lossless on traceability.
+- A surviving **git**/archive pointer is mandatory (`trail-loss` if dropped).
+- **OPEN residues stay** live; the audit trail is summarized-not-deleted.
+
+## Reject codes (judgment-checked — the AI proposes, the human confirms)
+
+- `open-residue-version` — the entry is unshipped or has ≥1 open delta/residue; leave it live.
+- `trail-loss` — the collapse would drop the git/archive pointer or the audit summary.
+- `wrong-order` — a record is not newest-first, or the settled line is not at the tail.
+
+## Distinct from `add.py compact`
+
+Foundation compaction ≠ engine `add.py compact <slug>`. It mirrors `fold.md`'s "AI proposes, human
+confirms" voice and stays convention-guided — no engine command, no `add.py check` enforcement.

package/skill/add/confidence.md

@@ -0,0 +1,48 @@
+# Confidence — the self-score that aims attention
+
+The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact
+— a spec, a contract, a build, or a verdict returned by a spawned subagent — *before* it
+presents it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a
+gate. Score it privately, refine while it is cheap, then surface what stayed uncertain.
+
+## The six dimensions
+
+Score each from 0 to 1 (0–1), honestly, on the artifact you are about to hand over:
+
+- **Completeness** — did it cover every rule, scenario, and rejection the task asked for?
+- **Clarity** — would the next reader understand it without you in the room?
+- **Practicality** — is it feasible and implementable as written, against the real code?
+- **Optimization** — does it balance correctness, simplicity, and cost — no gold-plating, no corner cut?
+- **Edge cases** — did it name the failure modes, the concurrency, the empty/oversized inputs?
+- **Self-evaluation** — does it carry its own refine step — a way to catch its own mistakes?
+
+If **any** dimension scores **< 0.9**, refine the artifact before you present it (or before you
+return from a spawned subagent), then re-score. The point is to spend the cheap iteration now,
+not after a human has read past the weak spot.
+
+## Where it plugs in
+
+- It **feeds the lowest-confidence flag** (run.md · phases/1-specify.md): the lowest-scoring
+  dimension or point is what you surface ⚠-first at the contract freeze. The self-score is the
+  private computation; the lowest-confidence flag is the public surfacing of its weakest point —
+  this rubric only *aims* that flag, it does not redefine it.
+- A persistently low score on a risky scope is a signal to **recommend lowering the autonomy
+  level** (auto → conservative / manual; run.md). Recommend it — never force it; choosing the
+  autonomy level stays the human's call.
+
+## The hard rule — advisory, never a gate
+
+<constraints>
+The confidence self-score is advisory only — it is never a gate. It never:
+- auto-PASSes a verify or blocks a run — the verify outcome rests on evidence (passing tests,
+  the non-functional review), not on a number the agent assigned itself;
+- substitutes for evidence or for the human decision point;
+- is recorded as a score the human "agreed to" — a self-asserted score that gated would only
+  move an unread approval one level up (run.md).
+
+What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend lowering
+the autonomy level. The gate itself stays evidence-based and human-owned.
+</constraints>
+
+> Used per step: each phase guide's Confidence hook points here, so an agent self-scores in the
+> idiom of the phase it is in (see the per-step hooks).

package/skill/add/fold.md

@@ -19,7 +19,7 @@ lives here so the engine stays judgment-free.
 2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
 3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
 4. **Confirm** — the human accepts or declines each delta. No write happens without this.
-5. **Write** — append the accepted edits, flip each delta's status, and bump the version.
+5. **Write** — prepend the accepted edits at the top (newest-first), flip each delta's status, and bump the version.
 
 ## Consolidation routing (every competency has a home)
 
@@ -31,15 +31,15 @@ lives here so the engine stays judgment-free.
 | `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
 | `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
 
-**Every** consolidation — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
+**Every** consolidation — whatever the competency — ALSO prepends one row at the TOP of `PROJECT.md` **§Key Decisions** (newest-first)
 (date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
 
 ## Status transitions & version
 
-- on **confirm**: the delta moves `open` → `folded` (and its edit is appended to the routed target).
+- on **confirm**: the delta moves `open` → `folded` (and its edit is prepended at the top of the routed target, newest-first).
 - on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
   so "we considered this and chose not to act" stays auditable.
-- a consolidation is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
+- a consolidation is **append-only (newest-first)**: it PREPENDS new bullets/rows at the top and never silently rewrites existing foundation text — EXCEPT via the recorded **compaction door** (`compact-foundation.md`): eligible (shipped + zero open residues) stable entries collapse upward into a rolled-up settled line at the tail. Reject: `open-residue-version` · `trail-loss` · `wrong-order`.
 - each consolidation session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
 
 ## Reject codes (the AI is first check, the human the backstop)

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

@@ -60,6 +60,8 @@ Never: invent a file, symbol, or signature you have not opened.
 - [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
 </exit_gate>
 
+> **Advisor · Confidence** — a broad sweep is the canonical spawn case (advisor.md); self-score your grounding before you specify against it (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/1-specify.md`.

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

@@ -49,6 +49,26 @@ 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
@@ -56,8 +76,13 @@ tag thin or inferred answers `guessed`.
    `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).
    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 +93,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

@@ -63,6 +63,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.