@pilotspace/add 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ 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.5.0] — 2026-06-16
+
+The UDD design-loop release: defining the design *before* the code is now a
+guided, evidence-backed loop inside the method. A new `design.md` drives the UDD
+beats to a confirmed screen, a wireframe + HTML-mock recipe renders a real screen
+the human approves before build, and the engine measures that the confirmation
+was actually captured. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **UDD design-definition loop (`design.md`)** — turns the foundation's UDD
+  concern into a runnable loop: a low-fi structural wireframe → a self-contained
+  HTML mock (resolve semantic tokens → one kit class per component → compose the
+  prototype tree → populate with mock data) → a captured screen the human
+  confirms *before* any build. Wired into `0-setup` and `1-specify`.
+- **Wireframe + HTML-mock recipe (`udd-wireframe.md`) + sample templates** — a
+  zero-dependency, any-stack floor for rendering a prototype tree into a real
+  screen, with a worked sample set (`tokens.sample.css`, `kit.sample.css`,
+  `welcome.sample.html`, `settings.sample.html` reusing the kit,
+  `wireframe.sample.txt`). One semantic-token flip re-themes every screen by
+  construction. An optional `@json-render/image` (Satori → PNG/SVG, no browser)
+  fast path is noted for JS-ecosystem projects.
+- **Capture-evidence convention + `missing_capture` WARN** — design captures live
+  at `.add/design/captures/<name>.<ext>`; `add.py check` emits a never-red
+  `missing_capture` warning for any prototype lacking a capture (silent when
+  absent, so non-UI projects stay clean). The engine *measures* capture presence;
+  it never renders.
+
+## [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/14-foundation.md

@@ -47,6 +47,17 @@ the method already names, made explicit as three concerns.
   test that behaviour; the foundation keeps the design intent that makes a screen
   worth building.
 
+When a milestone has screens, UDD is not only a static `DESIGN.md` — it runs a
+**design-definition loop** that turns the domain into a screen the human has *seen
+and confirmed before build*. Its four beats are `review-domain → research-components
+→ wireframe → render-capture-confirm`: read the domain into screens and regions,
+research and reuse components before inventing them, wireframe the structure low-fi,
+then render a real screen and **capture** it. That capture is the **design-confirm**
+evidence — a real image the person approves *before* implementation, so the build
+matches the layout instead of discovering it. The book keeps the *why*; the
+operational recipe (the wireframe format, the token-bound mock, the capture engines)
+lives in the `add` skill's `design.md` and `udd-wireframe.md`.
+
 These three foundation competencies, together with the **TDD ⇄ ADD** engine of
 [Part II](./02-the-flow.md), are ADD's five. The first four feed context to the
 fifth, where the AI executes on it:

package/docs/appendix-c-glossary.md

@@ -100,6 +100,22 @@
 
 **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.
+
+**Wireframe** — the Stage-A low-fidelity, *structural* map of one screen: its regions and the component **slots** inside them, derived from `prototypes/<name>.json` *before* any color, type, or spacing — it answers "what goes where", not "what it looks like". Beat 3 of the UDD **design-definition loop**; the low-fi half of the two-stage fidelity that ends in a confirmed capture. See the `add` skill's `udd-wireframe.md` (Stage A).
+
+**Design mock** — the Stage-B high-fidelity, **self-contained** HTML render of a screen: the `catalog.json` components as a reusable token-bound kit, bound to `tokens.json` and populated with mock data, openable offline and screenshot-able. The human-facing *visible* evidence the human confirms (the frozen `prototypes/<name>.json` tree is its machine-checkable twin). Beat 4's hi-fi artifact; the recipe lives in the `add` skill's `udd-wireframe.md` (Stage B).
+
+**Capture** — the real rendered image (PNG/SVG) of a design mock: the **design-confirm evidence** artifact. Captures live at `.add/design/captures/<name>.<ext>` (one per prototype) and are attached or mentioned in the feature's `TASK.md`; `@json-render/image` (Satori → PNG/SVG, no browser) is the named default capture engine, otherwise the self-contained mock is screenshot headless. The engine never renders — it only MEASURES presence: `add.py check` raises a never-red `missing_capture` WARN for a prototype with no capture.
+
+**Design-confirm** — the human touchpoint closing the UDD **design-definition loop** (`review-domain → research-components → wireframe → render-capture-confirm`, beat 4 of the `add` skill's `design.md`): approving the captured screen image **before build**, show-before-ask, so the implementation matches the layout the human has already seen instead of discovering it.
+
 ---
 
 ## Optional mapping to formal phase names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.3.0",
+  "version": "1.5.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,25 @@ 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 **UI feature** reaches specify, run the **design-definition loop** in `design.md` (UDD):
+review the domain → research and reuse components → wireframe → render a real captured screen the
+human confirms **before** build — so the build matches the expected layout. Tool-agnostic; the
+engine never renders.
 
 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/design.md

@@ -0,0 +1,92 @@
+# Design — the design-definition loop (UDD)
+
+When a **UI feature** reaches specify, design it before you build it. This loop takes the
+feature from the **domain** to a screen the human has **seen and confirmed** — a real captured
+image — *before* any implementation, so the build matches the expected layout instead of
+discovering it. It is loaded on demand (like `advisor.md` / `confidence.md`); the engine never
+runs it for you.
+
+Design before code is the UDD half of the method. The token + component foundation a UI project
+draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-tokens.md`),
+`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop is how you *fill* that
+foundation for a feature and earn the human's sign-off on the look before build.
+
+## The loop — four beats
+
+```
+review-domain  →  research-components  →  wireframe  →  render-capture-confirm
+```
+
+Run the beats in order. Each feeds the next; the last ends at a human design-confirm.
+
+### 1 · review-domain
+Start from the **domain**, not from a blank canvas. Read the domain model — entities, flows, the
+ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
+needs and the **regions** each screen holds. Map each domain entity to a *presentational*
+component (it shows state; it does not own a domain decision). The screen list + per-screen
+regions are this beat's output, and they are grounded in the domain you just read.
+
+### 2 · research-components (reuse before you invent)
+Check `catalog.json` **first** and **reuse** the components already there — that is what keeps
+screens consistent. Research a reference UI (a websearch over pattern galleries / component
+libraries for this kind of screen) only to fill a **genuine gap**, and propose a **new** catalog
+component for that gap with a **cited** reference. Reuse before invention; a new component is the
+exception, named and justified, not the default.
+
+### 3 · wireframe
+Draw a **low-fi**, **structural** layout for each screen — regions and component slots, no
+styling, no color. This is the cheapest possible artifact that shows the *expected layout*, so
+the human can correct the structure before a pixel is styled. Confirm the wireframe, then move on.
+
+### 4 · render-capture-confirm
+Render the screen as a **self-contained HTML mock** — the project's component library via CDN,
+bound to `tokens.json` (resolved to CSS variables), composed from the **reusable per-component
+kit** (one token-bound partial per catalog component), populated with realistic **mock** data.
+**Capture** a real image of it (a headless screenshot) and present that image to the human for
+**design-confirm** — show-before-ask, **before build**. On confirm, record the layout back to
+`prototypes/<name>.json` + `catalog.json`, save the captured image to
+`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`**
+(alongside the §6 evidence) — so the screen the human approved is traceable from the task that
+builds it. The HTML mock is the *visible evidence*; the json-render tree is the
+*machine-checkable* record of the same screen.
+
+## Tool-agnostic capture
+
+How you render and capture is **your** choice, not the engine's: a headless browser
+(Playwright / Puppeteer), an `html2image`-style renderer, a browser-automation skill, a design
+tool, or a hosted screenshot service — whatever the agent has. The recommended default is the
+self-contained HTML mock above, captured headless, because it needs no app build yet still wears
+the project's real tokens and component vocabulary. For a project that renders json-render, the
+recommended default is **`@json-render/image`** (Satori → PNG/SVG, no browser) — a deterministic
+`Spec` → image. The captured image is a **design-confirm evidence** artifact the human approves;
+it is never an engine output, and the engine never renders. This keeps the loop tool-agnostic and
+the method renderer-free.
+
+Captures live at **`.add/design/captures/<name>.<ext>`** (one per prototype) and are
+attached/mentioned in the feature's `TASK.md`. `add.py check` raises a never-red
+`missing_capture` WARN for any prototype under `.add/design/prototypes/` that still lacks a
+capture — a nudge to render + confirm it, never a blocker.
+
+The loop **binds** the existing UDD contracts **read-only**: `tokens.json`, `catalog.json`, and
+`prototypes/<name>.json` are read and composed, never reshaped — the `prototypes/<name>.json`
+data contract stays **unchanged** (a change to it is a change request, not a design step). And
+**identity** values — brand color, palette, typeface — stay **human-owned**: surface them for the
+human to decide, never auto-pick a brand value (`udd-tokens.md`).
+
+## The hard rules
+
+<constraints>
+- **Domain first.** A screen is derived from the domain (beat 1), never sketched blind.
+- **Reuse before invent.** Beat 2 checks the catalog first; a new component is a justified,
+  cited exception — never the reflex.
+- **Confirm before build.** The captured image is approved by the human *before* implementation;
+  a design-confirm placed at or after build defeats the loop.
+- **The engine never renders.** Capture is a recommended, tool-agnostic recipe run by the
+  agent's own tools; the image is evidence, not an engine artifact.
+- **Bind, don't break.** The loop reads `tokens.json` / `catalog.json` / `prototypes/<name>.json`
+  read-only; the data contract is unchanged, and identity values stay human-owned.
+</constraints>
+
+> Used at specify for a UI feature: `phases/0-setup.md` scaffolds `DESIGN.md`, and
+> `phases/1-specify.md` points here when the feature has a screen — run the four beats, then
+> carry the confirmed layout into the contract.

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`.