@pilotspace/add 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -6,6 +6,118 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 
 ## [Unreleased]
 
+## [1.13.0] — 2026-06-28
+
+Two method milestones make ADD's loop more **self-auditing** and more **honest**:
+the observe step now harvests a decision record automatically, and every flow gate
+is either mechanically enforced or plainly disclosed where it is not. Plus the npm
+release pipeline moves to tokenless **Trusted Publishing**. Backward-compatible
+throughout; nothing retro-changes an existing task or milestone record.
+
+### Added (adr-at-observe — a decision record, harvested not hand-written)
+- **`### Decisions (ADR)` harvested at the gate.** On `add.py gate PASS`, the engine
+  harvests a §7 Architecture-Decision-Record block from §1/§3/§5/§6 — one
+  actor-tagged line per decision (`[AI] specify · [human] freeze · [AI] build ·
+  [human] verify`), refilled only while the placeholder stands (never hand-edited).
+- **`add.py audit` checks the ADR at done.** A done task whose §7 ADR block is unfilled
+  is surfaced — presence-only, never a semantic judgment of the decisions themselves.
+- **Strategy write-back.** The §6 GATE RECORD is stamped with the git actor + date, and
+  the §5 "Strategy actually used" line is harvested into the ADR as the `[AI] build` row.
+
+### Added (flow-honesty — every gate engine-true or honestly disclosed)
+- **Two structural holes became real, forceable gates.** A **universal freeze gate**
+  (`contract_not_frozen` fires for every task at tests→build, with a recorded
+  `--skip-freeze` escape) and a **delta-drain release floor**
+  (`release_build_in_flight`, `--force`-able but loud) — the two places the method
+  promised enforcement and now delivers it.
+- **Four honor-system edges became plain disclosures + measure-not-block lints.**
+  `add.py audit` now surfaces `shallow_deep_check`, `risk_unset`, and
+  `refute_unrecorded` (presence-only, never blocking); the guides + book state plainly
+  that a *missed* security finding is invisible to the engine (a human spot-audit is
+  the only backstop under `auto`); reject-code names read honestly
+  (`release_tests_red`→`release_build_in_flight`).
+- **The earned-green refute-read is now a recorded verdict.** Under `auto`, the §6
+  `### Refute-read verdict` block records `EARNED | NOT-EARNED`; the engine measures it
+  is filled but never spawns the read — the resolver still does the judging.
+- **Stale guidance synced to the shipped engine.** The 5-build "scope gate deferred"
+  note is gone (the scope gate enforces today); the auto-PASS precondition list is now
+  identical across `run.md`, `6-verify.md`, and the book.
+
+### Added (loose tasks)
+- **`/add --todo` flag** (`skill-todo-flag`) — capture/list/close backlog todos.
+- **§5 Strategy fed into spawns** (`build-strategy-solutions` · `streams-strategy-pull`)
+  — the planned build order + known-problem fixes flow into subagent prompts.
+- **`<strategy>` softened** (`strategy-soft-not-hard`) — §5 is the *preferred* plan; the
+  builder may self-improve during build and reports the strategy actually used for audit.
+
+### Changed (release infrastructure)
+- **npm Trusted Publishing (OIDC).** `publish.yml` drops the stored npm token (no more
+  ~90-day rotation), publishes via OIDC (`id-token: write`, Node 24 + npm ≥ 11.5.1),
+  and generates provenance automatically (`--provenance` no longer needed). A guard test
+  locks the tokenless shape. PyPI already used OIDC.
+
+## [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

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/03-step-1-specify.md

@@ -3,7 +3,7 @@
 [← 02 The flow](./02-the-flow.md) · [Contents](./README.md) · Next: [04 Step 2 Scenarios →](./04-step-2-scenarios.md)
 
 > **Purpose:** state, in plain language, what the feature must do and what it must reject, with no ambiguity left for the AI to resolve by guessing.
-> **Produces:** `SPEC.md` for the feature.
+> **Produces:** the **§1 SPECIFY** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `SPEC.md`).
 > **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *lowest-confidence flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
 
 ---

package/docs/04-step-2-scenarios.md

@@ -3,7 +3,7 @@
 [← 03 Step 1 Specify](./03-step-1-specify.md) · [Contents](./README.md) · Next: [05 Step 3 Contract →](./05-step-3-contract.md)
 
 > **Purpose:** rewrite each rule from the spec as a concrete, pass-or-fail scenario.
-> **Produces:** `features/<name>.feature`.
+> **Produces:** the **§2 SCENARIOS** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `features/<name>.feature`).
 > **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
 
 > **Part of the specification bundle (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once** (the one approval), at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).

package/docs/08-step-6-verify.md

@@ -18,7 +18,7 @@ This needs care, because it is easy to misread. "Not by inspection" does not mea
 
 Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy level):
 
-- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
+- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold — the **same canonical list run.md owns**: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, the completeness-critic clean, the deep check filled, the earned-green refute-read verdict recorded (the §6 `### Refute-read verdict` field, under auto), and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
 - **Human.** When `autonomy: conservative`, or whenever the run finds residue it cannot judge, the gate stops for a person; the two parts below are theirs.
 
 **Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the non-functional risks — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
@@ -40,7 +40,7 @@ Automated tests are excellent at behavior on defined inputs and poor at a few sp
 
 - **Concurrency and timing.** Is the operation correct when two of them happen at once? Tests usually run serially and miss races.
   - ▶ *Example: the balance update must be one atomic transaction. Confirm that two simultaneous transfers from the same account cannot both pass the balance check and overdraw it.* This is the single most important check for this feature, and it is the reason the build prompt named atomicity explicitly.
-- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names.
+- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names. A security finding is always a `HARD-STOP`, never a waiver — and it escalates only if it is *written down*: `add.py audit`'s `unescalated_security_note` check fires on a **marked** note that slipped through as an auto-gate PASS, but a finding you **never marked** is invisible to the engine, escalated to no one. That is the honest limit of the auto-gate: under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding — the same backstop named for an unrecorded earned-green refute-read.
 - **Architecture conformance.** Does the change respect the layering and dependency rules in `CONVENTIONS.md`? Speed with no architectural check produces a fast-growing tangle that becomes unmaintainable within months.
 
 ## Part three — the deep check (do not skim)
@@ -59,6 +59,8 @@ Passing tests say the code satisfies the cases you wrote down. They do not say i
 
 A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological — green even against an empty implementation), and real logic stubbed away (the function returns a constant the tests happen to accept). These cheats are invisible to the mechanical tamper tripwire, which only sees edited files. Score them with an adversarial refute-read: an independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never spawns one — prompted to argue the green was NOT earned from outside the build context. This is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
 
+Under `autonomy: auto` there is no human at the gate to confirm the refute-read happened, so the verdict is **recorded** — a `### Refute-read verdict` field in §6 (`Verdict: EARNED | NOT-EARNED`, plus who read it and what they adversarially probed). This closes an honesty gap the auto-gate would otherwise leave open: the method *says* an auto-PASS rests on an earned-green check, but nothing made that check visible. Now `add.py audit` surfaces a verify-or-later task whose verdict block is still a placeholder as `refute_unrecorded` — a **measure, not a gate**: it never blocks the run (a hard gate on this universal completion path would break far too much to justify it, and the engine cannot read whether a self-graded `EARNED` is *true* anyway — only whether it was written). The honest backstop is the same one named for a missed security finding: a human **spot-audit** reading the diff. A `NOT-EARNED` verdict is not a dead end — it routes through `add.py heal` for an honest redo, never an auto-PASS. The discipline this records is simple: under auto, you are the accountable owner of the gate, so you leave the trace of the check you owe.
+
 ## Recording the outcome
 
 Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:

package/docs/09-the-loop.md

@@ -33,6 +33,10 @@ Every defect, surprise, or new need is written up as a change to the specificati
 
 This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
 
+## The decision record (ADR)
+
+Observe is also where the loop's **decisions** become durable. At the gate the engine harvests §7's **Decisions (ADR)** block from the stamps the task already carries — the §1 framing it chose (and the alternatives it rejected), the §3 contract a person froze, the §5 strategy it actually used, and the §6 gate outcome — tagging each line `[human]` or `[AI]`. It is *harvested, not authored*: the engine writes no decision of its own, only what the task already recorded, so the trail can never drift from what actually happened. The result is one consolidated, auditable record of who decided what — and `add.py audit` flags a done task whose block never harvested (`adr_record_missing`), so the record cannot silently go missing.
+
 ## Lessons learned and the retrospective consolidation
 
 A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **lessons learned**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.

package/docs/11-governance.md

@@ -23,7 +23,7 @@ The **per-scope default is auto-with-evidence behind a one-approval decision poi
 
 The engine expresses this per task as an explicit three-rung level — `autonomy: manual | conservative | auto`, an ordered ladder `manual < conservative < auto` declared in the `TASK.md` header and reviewed at the freeze. `auto` is auto-with-evidence behind the one approval (the seeded default); `conservative` is the deliberate lowering that keeps a person at the verify gate; `manual` is the strict floor where the human owns the gate and nothing auto-resolves. A high-risk or method-defining scope refuses an unguarded `auto` (`unguarded_high_risk_auto`) — it must be lowered to `conservative` or `manual`. The prose here and that engine token are one rule: prose ≡ enforcement.
 
-**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite that *earns* trust, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
+**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures citation presence*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite for a meaningful self-verifying run, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
 
 ## The gate-fail protocol and the three reports
 

package/docs/14-foundation.md

@@ -49,10 +49,12 @@ 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)

package/docs/16-releasing.md

@@ -86,7 +86,7 @@ refusing with a non-zero exit and leaving every file byte-unchanged on any of fo
 
 - `release_security_open` — an open security `HARD-STOP` exists. This is the non-negotiable one: a
   security finding is never shipped. Resolve it first, as a change request back to Specify.
-- `release_tests_red` — the suite is not green. A release ships on evidence, not on a plausible diff.
+- `release_build_in_flight` — a build is in flight: a task sits in build/verify with no recorded green gate. A release ships on evidence, not on a plausible diff.
 - `release_no_closed_milestone` — nothing new since the last release. The cut would be a no-op; do not
   bump a version to mark time.
 - `release_undisclosed_waiver` — a `RISK-ACCEPTED` waiver rides into the release but is missing from the

package/docs/appendix-c-glossary.md

@@ -46,6 +46,8 @@
 
 **Onboarding** (formerly "on-ramp") — the path a new user walks from install to their first milestone: install → `/add` → describe the goal → the agent runs intake (sizing the request into a milestone the human confirms) → the specification bundle → the self-driving run. The AI-first entry to the method; the human talks to the agent rather than hand-typing `add.py`.
 
+**Decisions (ADR)** — the engine-harvested record in a task's §7 OBSERVE: one actor-tagged line per key decision, gathered at the gate from the stamps already in the task — §1 framing `[AI]` (the choice + the rejected alternatives), §3 freeze `[human]`, §5 strategy-actually-used `[AI]`, §6 gate `[human|AI]`. *Harvested, never authored* — the engine invents no decision content, only mirrors what the task recorded — and scoped to the §7 OBSERVE placeholder alone. The durable who-decided-what trail that separates human direction from AI building; `add.py audit` flags a done task whose block never harvested (`adr_record_missing`).
+
 **Decision point** (formerly "seam") — a place where the flow stops for human judgment: the contract-freeze approval (the one approval), an escalated verify gate, intake confirmation, milestone close. The machine layer keeps the legacy name: the `--json` owner enum `seam`, the decide-digest key `seam`, and the `seam-audit` CI job.
 
 **The decision arc** — the three engine-sourced lines a gate report opens with at every **decision point**: `goal:` the milestone goal the work serves · `done:` the achievement, the proven progress toward it (the gate reports render this line as `done`) · `plan:` what comes next. What `done` reports adapts per gate (verify: tests + evidence · milestone close: exit-criteria met · intake: the request sized) while the three-part shape stays constant. Rendered first, above the report's summary, so the human confirms with sight of the whole trajectory, not a local snapshot. Engine-sourced like all evidence — goal · done · plan are pulled from `add.py` output, never re-typed. Presentation only: it never adds a gate or changes a `PASS` / `RISK-ACCEPTED` / `HARD-STOP` / freeze outcome. The report it opens is the chat report a person reads at a decision point — distinct from the three Test/Quality/Risk reports a verify gate produces ([11 Governance](./11-governance.md)). See the `add` skill's `report-template.md`.
@@ -84,6 +86,10 @@
 
 **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>`.
 
+**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`).
@@ -96,7 +102,7 @@
 
 **Release steps** — the AI-defined, per-milestone ordered hints to ship a closed milestone, of which `merge` is one small step (a pull request, an exported hand-off document, a tag or a publish are others). Defined at close and **fed** into the release scope (see **Release**), never a second flow.
 
-**Readiness floor** — the engine-enforced pre-cut gate `add.py release` applies before it records anything: a green suite, zero open security `HARD-STOP`, a closed-and-unreleased milestone to bundle, and every riding `RISK-ACCEPTED` waiver disclosed in the notes. Its four rejects are `release_security_open` (un-forceable) · `release_tests_red` · `release_no_closed_milestone` · `release_undisclosed_waiver`; `--force` may override every reject except the security stop.
+**Readiness floor** — the engine-enforced pre-cut gate `add.py release` applies before it records anything: a green suite, zero open security `HARD-STOP`, a closed-and-unreleased milestone to bundle, and every riding `RISK-ACCEPTED` waiver disclosed in the notes. Its four rejects are `release_security_open` (un-forceable) · `release_build_in_flight` · `release_no_closed_milestone` · `release_undisclosed_waiver`; `--force` may override every reject except the security stop.
 
 **RELEASES.md ledger** — the append-only, newest-first trail of release rows at the project root (date · version · milestones · waivers shipped · evidence). Like the §Key Decisions log it is never rewritten; a superseded or yanked version is recorded as a new row. The ledger is the attribution source — a milestone is "released" because a row says so — which is why the `→ releasable` cue never has to read a milestone file.
 
@@ -134,13 +140,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.
 
+**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 `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.11.0",
+  "version": "1.13.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"

package/skill/add/SKILL.md

@@ -15,7 +15,7 @@ user-invocable: true
 when_to_use: "Invoke in any repo with a `.add/` directory, or when the user wants spec/tests-first feature work, resumes ADD work, or asks to start/advance a task."
 category: workflows
 keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, scenarios, verify, milestone, task-orchestration]
-argument-hint: "status | init | continue | [describe new short goals or expectation]"
+argument-hint: "status | init | continue | --todo <text> | [describe new short goals or expectation]"
 license: MIT
 metadata:
   author: add
@@ -32,6 +32,10 @@ result through passing evidence rather than a plausible-looking diff.
 preamble plus seven step sections, filled top to bottom. The Python tool tracks where you
 are so context never rots across sessions.
 
+**The `--todo` fast-path.** When the skill ARGUMENTS begin with `--todo`, skip orienting: route to
+`add.py todo` and print its output — `--todo <text>` captures · `--todo` lists open todos ·
+`--todo --done <id>` closes (engine errors surfaced verbatim) — then STOP.
+
 ## Always start here (orient — do not skip)
 
 Engine: `.add/tooling/add.py` · book: `.add/docs/`. Ensure the engine is in the project first:
@@ -123,8 +127,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/advisor.md

@@ -24,7 +24,7 @@ independent enough to earn it. When in doubt, do it in-context.
 
 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.
+on any runner; only the spawn adapter (see `streams.md`) changes. The `<strategy>` block mirrors the task's §5 (Strategy + Known-problem fixes) as the subagent's PREFERRED path — it self-improves on that plan and reports the strategy it actually used.
 
 ```xml
 <objective>
@@ -40,6 +40,13 @@ Work step by step, following the plan:
 3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
 </persona>
 
+<strategy>
+The task's §5 plan — the Strategy (ordered batches) order and the Known-problem fixes — is
+your PREFERRED starting path, not a hard rule. Improve on it when a better strategy emerges
+as you build; on done, report the strategy you ACTUALLY used so the orchestrator can update
+§5 for the audit trail.
+</strategy>
+
 <context_files>
 the plan / task files the piece needs (read-only unless the piece says otherwise)
 </context_files>

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/5-build.md

@@ -16,7 +16,7 @@ tests, iterate to green. Keep each batch small enough to review in full.
 - **Scope (may touch)** — the allowlist of every file the build may write (backticked tokens). Needing a file outside the declared Scope is a **STOP → change request** back to Specify, never improvisation.
 - **Strategy (ordered batches)** — the planned build order. Guidance, not enforced.
 
-Deferral, named: the engine gate (touched ⊆ declared) lands in the `scope-gate-enforce` task — until it ships this section is prose discipline.
+Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal); `add.py check` surfaces it.
 
 ## The cardinal rule
 

package/skill/add/phases/6-verify.md

@@ -3,16 +3,15 @@
 Goal: establish trust and record an outcome. Passing tests are necessary, not
 sufficient. Fill **§6** in TASK.md including the GATE RECORD.
 
-> **Who resolves this gate depends on the `autonomy:` header (see `run.md`).**
-> Under `autonomy: auto` (the default) a run auto-PASSes once evidence is complete —
-> every test green, convergence loops dry, and **no residue** (security · concurrency · architecture) —
-> recorded as *auto-resolved* with the named run as accountable owner. **Security is
-> always a HARD-STOP and is never auto-passed.** Under `autonomy: conservative`, or
-> whenever residue is found, this phase is **human-led**.
+> **Who resolves this gate depends on the `autonomy:` header.** Under `autonomy: auto` (the default)
+> a run auto-PASSes on complete evidence with **no residue** (security · concurrency · architecture),
+> recorded *auto-resolved* with the named run as owner;
+> **security is always a HARD-STOP and is never auto-passed**. Under `conservative`, or whenever
+> residue is found, this phase is **human-led** (auto-PASS conditions: `run.md`).
 
 ## Before you build — declare the build expectations
 
-Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 SCENARIOS + §3 CONTRACT. At this gate, confirm each against real evidence (the `confirmed by` column). An expectation with no evidence is not yet verified.
+Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 + §3. At this gate, confirm each against real evidence (the `confirmed by` column) — one with no evidence is not yet verified.
 
 ## Part one — confirm the evidence
 
@@ -26,22 +25,22 @@ If any is false, stop and return to Build.
 ## Part two — check what tests miss
 
 - **Concurrency/timing** — correct when two run at once? (Tests run serially and miss races.)
-- **Security** — exposed secrets, injection openings, unexpected dependencies. A security finding is always `HARD-STOP`, never a waiver. ANY note here escalates to the human — start it with `NOTE` or `⚠` so `add.py audit` can see it (`unescalated_security_note`).
+- **Security** — exposed secrets, injection openings, unexpected dependencies. A security finding is always `HARD-STOP`, never a waiver. ANY note here escalates to the human — start it with `NOTE` or `⚠` so `add.py audit` can see it (`unescalated_security_note`). **But that check sees only what you wrote down:** it fires on a *marked* note that slipped through as an auto-gate PASS — a finding you never marked is **invisible** to the engine, escalated to no one. Honest disclosure, not false cover: under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding.
 - **Architecture** — respects layering/dependency rules in CONVENTIONS.md?
 
 ## Part three — the deep check (do not skim)
 
-Deep check — do not skim. If the task produced code, record that every new symbol is referenced (wiring) and that no new dead/unused code was introduced. If it produced prose or non-code, record a semantic read — what you read in full and what it confirmed. Which path applies is the resolver's judgement; the engine never classifies.
+If the task produced code, record that every new symbol is referenced (wiring) and that no new dead/unused code was introduced. If it produced prose or non-code, record a semantic read — what you read in full and what it confirmed. The resolver judges which path; the engine never classifies.
 
-Record it in the §6 **Deep checks** block. An unfilled Deep checks block is a **shallow verify**, not a PASS.
+Record it in the §6 **Deep checks** block — an unfilled one is a **shallow verify**, not a PASS.
 
 ## Part four — was the green earned?
 
-A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (tautological — green against an empty implementation), and real logic stubbed away. These are invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md).
+A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (green against an empty implementation), and real logic stubbed away — all invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md). Under `auto`, **record the verdict** in §6's `### Refute-read verdict` block — `add.py audit` flags an unrecorded `refute_unrecorded`, one of three measure-not-block shape lints it surfaces (also `shallow_deep_check` + `risk_unset`).
 
 ## Record exactly one outcome (no silent pass)
 
-When you present this gate, open with the ARC per `report-template.md`, render the DECISION as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count before the ask.
+Present this gate via `report-template.md`'s ARC, render DECISION as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count first.
 
 | Outcome | When |
 |---------|------|
@@ -53,10 +52,10 @@ When you present this gate, open with the ARC per `report-template.md`, render t
 
 <exit_gate>
 - [ ] Evidence confirmed, non-functional risks checked, outcome recorded — a person approved, or
-  (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
+  (under `autonomy: auto`, no residue) the run auto-resolved as 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).
+> **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (advisor.md); score it before recording the gate (confidence.md).
 
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done

package/skill/add/phases/7-observe.md

@@ -1,20 +1,21 @@
 # Phase 7 — Observe (feed the next loop)
 
-Goal: release deliberately, watch reality, and turn what you learn into the next spec. Fill **§7** in TASK.md.
+Goal: release deliberately, watch reality, turn what you learn into the next spec. Fill **§7** in TASK.md.
 
 ## Do
 
-1. **Release behind a scope-of-impact limit** — feature flag and/or gradual rollout.
+1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout.
 2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
-   define what you alert on: overall error rate, each rejection's rate (a spike in
-   one is a signal), latency of the risky operation under load.
+   define what you alert on: overall error rate, each rejection's rate (a spike is a
+   signal), latency of the risky op 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.
+   change that re-enters the flow at Specify (a new task).
+4. **Propose a voice delta** — note where your voice diverged from the human's (wordings +
+   flow); propose a confirmable **voice delta** tuning `SOUL.md`, emitted `open`. The human
+   confirms, then you rewrite the routed section. Read `soul.md` (grammar, routing,
+   human-is-only-writer).
+
+> **Decisions (ADR)** — at the gate the engine harvests §7's ADR block (§1/§3/§5/§6); `add.py audit` flags one never harvested.
 
 ## AI prompt
 

package/skill/add/release.md

@@ -35,7 +35,7 @@ One arc, seven steps: **cue → gather → draft notes → readiness floor → h
 
 <reject_codes>
 - `release_security_open` — open security HARD-STOP exists. Never shipped. `--force` does NOT override this.
-- `release_tests_red` — suite not green.
+- `release_build_in_flight` — a build is in flight, ungated.
 - `release_no_closed_milestone` — nothing new since last release.
 - `release_undisclosed_waiver` — a RISK-ACCEPTED waiver rides into the release but is absent from the notes.
 </reject_codes>