@pilotspace/add 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -6,6 +6,108 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 
 ## [Unreleased]
 
+## [1.12.0] — 2026-06-26
+
+Multi-milestone polish release — the intake/roadmap front grows a real **queue**,
+the parallel-front residuals close, and the UDD loop gains a design-intake beat.
+Backward-compatible throughout; a single-active project sees no behavior change.
+
+### Added (multi-milestone-intake — a request that is several milestones)
+- **`queued` milestone status.** The milestone status enum becomes
+  **active · queued · done** (was active · done). A milestone can now exist
+  non-active, awaiting promotion — created with `new-milestone --queued` and made
+  active with an explicit `activate`. Migration-safe: an old state with no `queued`
+  milestones reads byte-identically.
+- **Roadmap intake.** `intake.md` now guides decomposing a request that is *several*
+  milestones into a roadmap that creates **all N — 1 active + N−1 queued** — instead
+  of only the first. Promotion stays human-gated; the whole set is never auto-activated.
+- **Queued-backlog resume cue.** `status` surfaces the queued backlog (active
+  milestone + what's queued next), so a multi-milestone session resumes cleanly. The
+  cue is present-only — byte-identical output when nothing is queued.
+
+### Added (multi-active-polish — close the parallel-front residuals)
+- **`waves --merge`** folds the active SET into one cross-milestone DAG and critical
+  path (today's `waves` is per-milestone only).
+- **`mine --all`** widens the ownership lens past the active milestones — every
+  not-done task you own or are assigned, across all milestones plus loose, with an
+  email-OR-name match. Plain `mine` (active-only) stays byte-identical.
+- **`doctor` value-domain checks.** `doctor` now flags a bad `gate` enum
+  (∉ {PASS, RISK-ACCEPTED, HARD-STOP}), a bad `phase`, archived inconsistency, or a
+  malformed owner/assignee — beyond the existing referential pointers. It **adds
+  findings only**; it never auto-fails or retro-reds grandfathered history.
+- **`new-milestone` add-and-focus.** Creating a milestone while one is active now
+  **preserves the active SET** (adds the new one and focuses it) instead of replacing
+  the set and evicting the others. `--queued` and single-active stay byte-identical.
+
+### Added (udd-design-intake)
+- **`design-intake` beat.** The UDD design loop opens with a new front beat that
+  interviews the human on four axes — **FIDELITY · CONCEPT · LAYOUT · VISUAL DESIGN**
+  — recorded in `DESIGN.md` before review-capture-confirm. Convention-only (the engine
+  never renders); identity values (brand color/type) stay human-owned — surfaced to
+  decide, never auto-picked.
+
+### Added / Changed (loose tasks since 1.11.0)
+- **Descriptive-slug nudge (`new-milestone`).** A milestone slug that is a bare
+  version number (`v2`, `v1-1`, `1.2` — matched by `^v?\d+([._-]\d+)*$`) prints an
+  advisory `note:` suggesting a short **descriptive** name (e.g. `payment-retries`) and
+  **still creates the milestone** — never blocks.
+- **Full-ISO `created:` stamp.** MILESTONE.md's `created:` line is the full UTC ISO
+  timestamp (`2026-06-26T03:47:28+00:00`); a single `_now()` instant feeds both the
+  rendered file and the `state.json` record.
+- **`add.py freeze`** — an engine-stamped human-approval write at the §3 contract
+  freeze (DRAFT → FROZEN @ vN with a structured actor line). A security finding remains
+  an un-forceable HARD-STOP.
+- **Queued + await-confirm reminder.** A milestone that is both `queued` and
+  `--await-confirm` now surfaces its `milestone-confirm` reminder at resume.
+- **Flow docs.** Book ch.02 gains a subsection explaining the milestone-scale
+  composition rule — tasks are **listed breadth-first up front** (the DAG), then each
+  **specified just-in-time**.
+
+This release bundles **3 closed milestones** (`udd-design-intake`,
+`multi-milestone-intake`, `multi-active-polish`) and the loose tasks above since
+1.11.0. Every milestone was built end-to-end through ADD's own
+spec→tests→build→verify flow.
+
+## [1.11.0] — 2026-06-26
+
+Engine-modularization + audit-hardening release — the 7k-line monolith becomes a
+navigable package, the verify/atomicity/coverage gates get five fixes, and the
+standalone (milestone-free) lane becomes first-class. **No behavior change** to the
+CLI, the flow, or any output: this is an internal architecture + hardening release.
+
+### Changed
+- **The engine is now a focused package.** `add-method/tooling/add.py` (7049 → 5640
+  lines, −20%) split into **13 `add_engine/*.py` modules** — `constants`, `io_state`,
+  `accessors`, `predicates`, `identity`, `guidelines`, `render`, `milestones`,
+  `components`, `version`, `release`, `taskdoc`, `autonomy` — behind a stable
+  re-export surface (`import add; add.<name>` still resolves, public AND `_`-prefixed,
+  so every existing test is untouched). `add.py` stays the runnable **orchestrator
+  entry** (the `load_state`/`save_state`/`report_data`/`cmd_*`/`main` spine). Each of
+  the 16 extractions was its own CI-green PR, proven verbatim by an AST source-segment
+  diff and gated by the full suite (1815 → 1959 green throughout, no test weakened).
+- **Two-pin integrity model.** Alongside `ENGINE_MD5` (md5 of `add.py`),
+  `ENGINE_PKG_MD5` is a manifest digest over every `add_engine/*.py`; both are literal
+  pins (never self-hashed) and are checked byte-identical across the 3-tree mirror
+  (canonical · `.add` · `_bundled`). `prepare_bundle` + both installers + the `.add`
+  mirror now ship the whole `add_engine/` package.
+
+### Fixed (audit-hardening)
+- Five gate/atomicity/coverage fixes: a phase-build guard, hardened save-state
+  atomicity, force-preserve self-healing, setup-tests-before-build ordering, and a
+  consumer-stale gate. A security finding remains an un-forceable HARD-STOP.
+
+### Added (the standalone / lightweight lane)
+- **`add.py todo`** — capture a milestone-free backlog item without scaffolding a task.
+- **`loose tasks:` release attribution** — a release now attributes *any* done,
+  milestone-free task on its `RELEASES.md` row (not only milestone membership), with a
+  separate status cue for releasable loose work.
+- **`fast` (task) + `auto` (mode) flag modes** — the standalone lane is first-class:
+  a minimal `TASK.fast.md`, freeze-gated under any milestone, with a flag-mode quick
+  reference.
+
+This release bundles **2 closed milestones** (`audit-hardening`,
+`engine-modularization`) and **27 loose tasks** since 1.10.0.
+
 ## [1.10.0] — 2026-06-25
 
 Component-aware major — ADD now models every codebase as a **graph of components**,

package/bin/cli.js

@@ -562,6 +562,57 @@ function writeGeminiSettings(target) {
   }
 }
 
+// Seed .add/SOUL.md from the bundled template if it does not yet exist. Mirror of
+// _installer.py:_seed_soul_md (npm <-> pip parity): skip-if-exists (SOUL.md is
+// user-owned — never clobber); fail-soft (warn + return, never abort install/update).
+function seedSoulMd(target) {
+  const dest = path.join(target, ".add", "SOUL.md");
+  if (fs.existsSync(dest)) return;                       // skip-if-exists (never clobber)
+  const source = path.join(PKG_ROOT, "tooling", "templates", "SOUL.md.tmpl");
+  if (!fs.existsSync(source)) {
+    warn("soul_seed_skipped: SOUL.md.tmpl not found in bundled tooling/templates/");
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(source, "utf8"));
+  } catch (e) {
+    warn("soul_seed_skipped: could not write .add/SOUL.md — " + (e && e.message ? e.message : e));
+  }
+}
+
+// Ensure .add/.gitignore lists the engine's transient artifacts. Seed it from the bundled
+// tooling/templates/gitignore.tmpl if absent; else APPEND-IF-ABSENT each pattern line the
+// template carries that the file lacks — additive only, never reorders/removes user lines,
+// idempotent; comment/blank lines are not appended to an existing file. Fail-soft. Twin of
+// _installer.py:_seed_gitignore.
+function seedGitignore(target) {
+  const source = path.join(PKG_ROOT, "tooling", "templates", "gitignore.tmpl");
+  if (!fs.existsSync(source)) {
+    warn("gitignore_seed_skipped: gitignore.tmpl not found in bundled tooling/templates/");
+    return;
+  }
+  const dest = path.join(target, ".add", ".gitignore");
+  try {
+    const body = fs.readFileSync(source, "utf8");
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, body);                       // seed-if-missing
+      return;
+    }
+    const current = fs.readFileSync(dest, "utf8");
+    const have = new Set(current.split("\n").map((l) => l.trim()));
+    const missing = body.split("\n").filter(
+      (l) => l.trim() && !l.trim().startsWith("#") && !have.has(l.trim())
+    );
+    if (missing.length === 0) return;                     // idempotent — nothing to add
+    const suffix = current === "" || current.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(dest, current + suffix + missing.join("\n") + "\n");
+  } catch (e) {
+    warn("gitignore_seed_skipped: could not update .add/.gitignore — " + (e && e.message ? e.message : e));
+  }
+}
+
 // The drop — now a RECONCILE: restore missing managed trees + refresh present ones
 // (sweep orphans) + report per-tree status. Byte-compatible handoff with the prior
 // installer. The interactive path resolves a target then calls straight into this.
@@ -569,6 +620,8 @@ function dropFiles(args, target, profile, intent) {
   profile = profile || detectAgent(process.env);
   log("Installing ADD into " + target);
   reconcile(args, target);
+  seedSoulMd(target);   // pip parity: re-seed a missing user-owned SOUL.md (never clobber)
+  seedGitignore(target);   // pip parity: seed/append-if-absent the engine-transient ignore lines
 
   // Agent detection: write THE detected agent's integration file (a marker-delimited
   // pointer init's sync-guidelines later supersedes) + tailor the closing next-step.
@@ -932,6 +985,8 @@ function cmdUpdate(args) {
     fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
   }
   reconcile(args, target);
+  seedSoulMd(target);   // pip parity: re-seed a missing user-owned SOUL.md (never clobber)
+  seedGitignore(target);   // pip parity: seed/append-if-absent the engine-transient ignore lines
   writeStamp(addDir, version);
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
       " · managed layer reconciled · your project state untouched.");

package/docs/02-the-flow.md

@@ -52,6 +52,16 @@ The shape is deliberate: the human-led steps establish direction, a frozen contr
 
 > **What changed in v7 (the diagrams above show the structural flow, which is unchanged).** The *steps* and their order are exactly as drawn — only **who resolves them** moved. The AI now drafts the whole specification bundle (steps 1–4) and a person approves it **once**, at the contract freeze (not a sign-off at each step); and **Verify is auto-gated on evidence** under `autonomy: auto` (the default), escalating security — always a `HARD-STOP` — and other residue to a person. Lower the autonomy level to `conservative` to keep a human at the Verify gate. See [11 Governance](./11-governance.md).
 
+## Many features, one at a time — listed up front, specified just-in-time
+
+The flow above runs *one* feature. A milestone holds many, and they compose by one rule: **list every task up front, specify each just-in-time.**
+
+- **Listed up front (breadth-first).** When a milestone is created it is decomposed **breadth-first** into a task *list* — `slug · depends-on · one line` each. That is the whole plan and its dependency DAG (`add.py waves` views the order and the critical path). The milestone living-doc (`MILESTONE.md`) holds this list plus the shared decisions and the exit criteria, and it stays **thin** — no per-task detail lives there.
+- **Specified just-in-time.** Each listed task runs the full seven-step flow (0 Ground … 6 Verify) only when work reaches it. Its specification bundle — §1–§4 — is written then, **not** bundled for every task before any build begins.
+- **Why just-in-time.** A later task's spec absorbs what earlier tasks' Observe step taught (a sharper contract, a convention that emerged, a delta fed back), and a bundle written too early rots before you arrive at it. This is the same backward-correction principle — Observe → Specify — applied at milestone scale rather than within one feature. So: list all the tasks, then specify each in turn.
+
+The sequence is therefore **decompose the milestone → schedule the task DAG → run each task's seven-step flow just-in-time → close the milestone** — breadth planned once, depth earned one task at a time.
+
 ## Why the order is the order
 
 Each step produces exactly one artifact, and each artifact is the input to the next step. The order is not a preference; it is a dependency chain.

package/docs/09-the-loop.md

@@ -51,7 +51,7 @@ Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evide
 
 **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.
+**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. `add.py fold [--task <slug>] [--comp <TAG>]` mechanizes the consolidation — flip + transcribe + route + bump, validate-all-then-write so a reject leaves the tree byte-unchanged; running it **is** the human's confirmation, and the engine never self-approves *which* lessons to keep.
 
 **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.
 

package/docs/11-governance.md

@@ -31,7 +31,7 @@ Every checkpoint produces three short reports — **Test** (does it pass?), **Qu
 
 - **`PASS`** — criteria met; proceed.
 - **`RISK-ACCEPTED`** — proceed with a signed waiver carrying a named owner, a linked ticket, and an expiry. Allowed for non-security gaps only.
-- **`HARD-STOP`** — cannot proceed. Triggered by any failing test or any security finding; overridable only by the most senior accountable owner, and never for security.
+- **`HARD-STOP`** — cannot proceed. Triggered by any failing test or any security finding. A non-security limitation may proceed only with a signed `RISK-ACCEPTED` record carrying an owner and an expiry; security is never waved through.
 
 The rule behind the protocol is *no silent skips.* A report nobody is accountable for approving is just a document; an outcome with an owner is governance.
 

package/docs/14-foundation.md

@@ -49,14 +49,16 @@ the method already names, made explicit as three concerns.
 
 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**
+and confirmed before build*. Its five beats are `design-intake → review-domain →
+research-components → wireframe → render-capture-confirm`: interview the human on the
+four design axes (fidelity · concept · layout · visual design) so the look is directed
+not guessed, 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`.
+lives in the `add` skill's `design.md` and the `udd-wireframe.md` template (`tooling/templates/`).
 
 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

package/docs/16-releasing.md

@@ -11,8 +11,8 @@ them *ship*. This chapter names the act every project eventually performs and th
 now, never formalized: bundling closed milestones into a versioned, user-facing release whose notes
 are evidence-backed, whose risk is disclosed, and whose behaviour is then watched.
 
-Releasing is the **fifth scope level** — after the task, the milestone, the foundation/setup level,
-and stage graduation. Like every scope level it runs the same shape: **gather → propose → the human
+Releasing is the **fifth scope level** — after setup, intake, the milestone loop, and stage graduation.
+Like every scope level it runs the same shape: **gather → propose → the human
 confirms → the engine records and enforces a floor.** And like graduation, it ends with an outward
 act the human owns. The operational recipe lives in the `release.md` skill guide; this chapter is the
 *why* behind it.

package/docs/appendix-c-glossary.md

@@ -84,7 +84,11 @@
 
 **Baseline approval** (formerly "the lock-down") — the single human gate ending autonomous setup: an explicit yes that freezes the foundation, first scope, and first contract together; runs as `add.py lock --by <name>`.
 
-**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level · release level (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
+**Queued milestone** — a milestone created non-active: its status is `queued` (the milestone status enum is **active · queued · done**). It is recorded with its `MILESTONE.md` on disk but does not hold the active focus; `add.py new-milestone --queued <slug>` creates it, and `add.py activate <slug>` promotes it queued→active one at a time. A queued milestone is not `done`, so it does not satisfy the graduation gate.
+
+**Roadmap** — the multi-milestone intake artifact: when a request decomposes into N>1 milestones of the same line, the AI proposes the ordered roadmap and, on human confirm, creates all N — the first active, the rest **queued** — then promotes each with `activate` as it is started. Distinct from `split_required` (which spans different buckets). Lives in the `add` skill's `intake.md`.
+
+**Scope level** (formerly "altitude") — the granularity a decision lives at, as one ordered ladder of five: **setup/foundation** · **intake** (request → versioned scope) · **the milestone loop** (the task is its inner unit) · **stage graduation** (changes rigor, not version; see **Stage graduation**) · **release** (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). One ⚠-assumption notation is shared across every scope level.
 
 **Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
 
@@ -134,13 +138,15 @@
 
 **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 intake** — beat 0 of the UDD **design-definition loop**: the agent interviews the human on four design **axes** *before* reading the domain, so the look is directed not guessed. **Fidelity** (lo-fi wireframe · hi-fi mockup · production — how far the design renders), **Concept** (idea · mood · direction), **Layout** (structure · grid · hierarchy), and **Visual design** (color · type · spacing · imagery — surfaced for the human, never auto-picked). Recorded as project defaults in `DESIGN.md`'s `## Design intake` and per-screen overrides in the prototype note. Fidelity is recorded intent, not an engine gate.
+
+**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 `udd-wireframe.md` template (`tooling/templates/`, 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).
+**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 `udd-wireframe.md` template (`tooling/templates/`, 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.
+**Design-confirm** — the human touchpoint closing the UDD **design-definition loop** (`design-intake → review-domain → research-components → wireframe → render-capture-confirm`, the final beat 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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -19,6 +19,9 @@
     "bin/",
     "skill/",
     "tooling/add.py",
+    "tooling/add_engine/",
+    "!tooling/add_engine/__pycache__",
+    "!**/*.pyc",
     "tooling/templates/",
     "docs/",
     "README.md",

package/skill/add/SKILL.md

@@ -62,7 +62,13 @@ self-improving via the `soul-self-improve` path). Then branch on state:
 - **No active task** → first SIZE the request (Intake below), then `add.py new-task <slug> --title "..."`.
 
 **Quick ref** — `status` resume · `init` bootstrap · `advance` continue · `gate PASS` at verify.
-**Opt-in flags** (human picks, never auto): `new-task --fast` = fast lane (minimal template, freeze-gated) · `new-milestone --await-confirm` = confirm-gate the milestone's tasks.
+**Flag mode** — two human-owned settings (never auto-picked): **fast** (task) · **auto** (mode).
+- **fast** — `new-task --fast`: minimal template, freeze-gated; a milestone-free `--fast` task is a
+  blessed standalone low-ceremony lane. Jot ideas first with `add.py todo "<text>"` (then `todo` to
+  list · `todo --done <id>`).
+- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; lower the autonomy level with
+  `add.py autonomy set conservative|manual` for a human gate · `new-milestone --await-confirm`
+  confirm-gates a milestone's tasks.
 
 ## Intake — size a request before creating scope
 
@@ -117,8 +123,8 @@ once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `
 - **Small, low-risk task**, less ceremony → the **fast lane**: `new-task --fast` scaffolds the minimal
   `TASK.fast.md`, bundle approved in one freeze — `phases/fast-lane.md`. Floor held (frozen contract ·
   red test · verify gate; `--fast` is freeze-gated under any milestone). Collapse, never skip; opt-in.
-- **UI feature** at specify → the **design-definition loop** (UDD): review the domain → research and
-  reuse components → wireframe → a real captured screen the human confirms **before** build — `design.md`.
+- **UI feature** at specify → the **design-definition loop** (UDD): intake the design axes → review the
+  domain → research and reuse components → wireframe → a captured screen the human confirms **before** build — `design.md`.
   Tool-agnostic; the engine never renders.
 - Tasks all done but the milestone **goal** unmet → `milestone-done` holds it open; the loop turns open
   deltas + extras into the next tasks (you propose, the human confirms) until the goal is met — `loop.md`.

package/skill/add/design.md

@@ -10,14 +10,29 @@ draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-toke
 `catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop fills that foundation
 for a feature and earns the human's sign-off on the look before build.
 
-## The loop — four beats
+## The loop — five beats
 
 ```
-review-domain  →  research-components  →  wireframe  →  render-capture-confirm
+design-intake  →  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.
 
+### 0 · design-intake
+Before you read the domain, interview the human on **four design axes** — so the look is
+*directed*, not guessed. Ask each, show the options, record the pick:
+
+- **FIDELITY** — how far this design goes: *lo-fi wireframe* · *hi-fi mockup* · *production*.
+  Recorded **intent** that **informs** how far the later beats render (it is not an engine gate).
+- **CONCEPT** — the design *idea / mood / direction* in a line.
+- **LAYOUT** — the *structure / grid / hierarchy* the screens lean on.
+- **VISUAL DESIGN** — *color · type · spacing · imagery*. **Surface** identity values for the
+  human to choose — never auto-pick a brand value (identity stays **human-owned**, `udd-tokens.md`).
+
+Record the answers **before** review-domain, at both levels: project **defaults** in DESIGN.md's
+`## Design intake` section; per-screen **overrides** (only the deltas) in the per-feature design
+note (the `prototypes/<name>.json` companion). Show-before-ask — confirm the picks, never assume.
+
 ### 1 · review-domain
 Start from the **domain**, not a blank canvas. Read the domain model — entities, flows, the
 ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
@@ -70,6 +85,8 @@ human to decide, never auto-pick a brand value (`udd-tokens.md`).
 ## The hard rules
 
 <constraints>
+- **Intake before domain.** The four axes (FIDELITY · CONCEPT · LAYOUT · VISUAL DESIGN) are
+  interviewed and recorded — DESIGN.md defaults + per-screen overrides — before beat 1.
 - **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.

package/skill/add/intake.md

@@ -56,6 +56,22 @@ request, emit ONE of:
 When confirmed, record the `rationale` in the artifact you create or affect — the new MILESTONE.md
 goal/body, the new TASK.md, or a note in the affected TASK.md — never in state.json.
 
+## Roadmap — a request that is several milestones
+
+Some requests decompose into **N>1 milestones of the same line** — a roadmap, not one milestone.
+Don't create only the first and lose the rest. Instead:
+
+1. **Propose** the roadmap — the ordered milestone list, each with a one-line goal. (AI proposes.)
+2. **Confirm** — the human confirms the roadmap before anything is created. Never auto-create N
+   milestones unprompted — the intake floor (`ask_human`) still holds.
+3. **Create** all N on confirm — the first with `add.py new-milestone <slug>` (active), the rest
+   with `add.py new-milestone --queued <slug>` (status `queued`, not focused).
+4. **Promote** one at a time — as each is started, `add.py activate <slug>` flips it queued→active.
+   You work one active milestone at a time; the queue is the agreed backlog, surfaced at resume.
+
+This is NOT `split_required`: that code is for a request spanning **different buckets** (propose the
+smallest correctly-sized set). A roadmap is several milestones of the **same line**, created queued.
+
 ## Worked examples (from this project's own history)
 
 | request | bucket | rationale |

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

@@ -47,11 +47,17 @@ Never: invent a file, symbol, or signature you have not opened.
 ## Exit gate
 
 <exit_gate>
-- [ ] The real files/symbols the task touches are named (from the code, not assumed).
-- [ ] The conventions to honor are cited (task-delta only; no architecture re-scan).
-- [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
+- [ ] **Touches** — the real files/symbols the task touches are named (from the code, not assumed).
+- [ ] **Context** (working folder) — the non-code artifacts the task touches (docs · todos · config · data) are named, task-delta only.
+- [ ] **Honors** — the patterns/conventions to honor are cited (task-delta only; no architecture re-scan).
+- [ ] **Anchors** — the anchors §3 will cite are listed — §3 names only anchors that exist here.
 </exit_gate>
 
+**Grounding is complete when** all four fields are filled from real assets: a STRONG grounding cites
+actual files/symbols/docs/conventions you opened; a WEAK one leaves a `<…>` placeholder or names what you
+assume. All four are non-optional — skipping **Context** (the working folder beyond code) is the usual
+silent gap. §3 may cite only anchors that appear here.
+
 > **Advisor · Confidence** — a broad sweep is the canonical spawn case (advisor.md); self-score your grounding before you specify against it (confidence.md).
 
 ## Next

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

@@ -57,7 +57,7 @@ Capture each surfaced decision as an **ADR** into `PROJECT.md` **Key Decisions**
    ```bash
    python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
    ```
-   Draft §1 · §2 · §3. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: bundle → lock → build.
+   Draft the full bundle **§1–§4** — incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL **before build** (never start Build until §1–§4 exist and tests are red).
 4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every drafted decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
 
 ## Run mode — how the build will be driven (propose parallel + auto; confirm to keep)
@@ -93,7 +93,7 @@ Typing it themselves stays the **escape hatch** — the decision is always the h
 <exit_gate>
 - [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
 - [ ] Living docs filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
-- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
+- [ ] First task created; **§1–§4 drafted — the red suite (per `phases/4-tests.md`) runs RED before build opens**; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
 - [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name; first task §3 `FROZEN @ v1`; build open.
 </exit_gate>
 

package/skill/add/scope.md

@@ -19,7 +19,7 @@
 
 Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
 
-1. **Ground in current assets.** Read the goal against `PROJECT.md` (domain · spec · UI/UX), the code it touches, and existing docs — the goal must reflect what the project already is.
+1. **Ground in current assets.** Read the goal against what exists — the goal must reflect what the project already is. Ground as rigorously as a task's §0 (`phases/0-ground.md`), using the **same four fields** at milestone scope: **Touches** (the subsystems/files the milestone spans) · **Context** (the docs · todos · config · data it works against) · **Honors** (the `PROJECT.md` / `CONVENTIONS.md` invariants it must respect) · **Anchors** (the existing contracts/symbols its tasks will cite). Grounding is complete when each is named from real assets, not assumed.
 2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
 3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.