@pilotspace/add 1.11.0 → 1.12.0

package/CHANGELOG.md

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

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/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/appendix-c-glossary.md

@@ -84,6 +84,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`).
@@ -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.
 
+**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.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"

package/skill/add/SKILL.md

@@ -123,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/tooling/add.py

@@ -164,16 +164,20 @@ from add_engine.identity import (          # re-exported for `add.<name>` attr c
 )
 
 
-def _my_work(state: dict, me: dict) -> list[dict]:
-    """The "my work" lens (multi-active-UX): across ALL active milestones, the NOT-done tasks
-    whose owner OR assignee is `me`. Returns ordered rows {slug, milestone, phase, role} with
-    role in {owner, assignee, both}, sorted by active-milestone order then slug. PURE · no I/O."""
+def _my_work(state: dict, me: dict, scope_all: bool = False) -> list[dict]:
+    """The "my work" lens (multi-active-UX): the NOT-done tasks whose owner OR assignee is `me`.
+    By default the lens is the active SET; `scope_all=True` (mine-all-lens) widens it to EVERY
+    milestone plus loose (milestone-less) tasks. Returns ordered rows {slug, milestone, phase,
+    role} with role in {owner, assignee, both}, sorted by active-milestone order then slug
+    (non-active/loose sort after the active block, then by slug). PURE · no I/O."""
     active = list(state.get("active_milestones") or [])
     active_set = set(active)
     tasks = state.get("tasks") if isinstance(state.get("tasks"), dict) else {}
     rows: list[dict] = []
     for slug, t in tasks.items():
-        if not isinstance(t, dict) or t.get("milestone") not in active_set or _task_done(t):
+        if not isinstance(t, dict) or _task_done(t):
+            continue
+        if not scope_all and t.get("milestone") not in active_set:
             continue
         owns = identity._actor_matches(t.get("owner"), me)
         assigned = identity._actor_matches(t.get("assignee"), me)
@@ -461,6 +465,74 @@ def cmd_drop_delta(args: argparse.Namespace) -> None:
     print(_next_footer(root, state))
 
 
+# a §3 still carrying this template placeholder is NOT a drafted contract yet
+_CONTRACT_TEMPLATE_RE = re.compile(r"<METHOD>")
+
+
+def _next_freeze_version(state: dict, slug: str) -> str:
+    """v1 on the first freeze; N+1 of the highest prior freeze version recorded on the
+    task's state record on a re-freeze (after a change request). PURE — reads state only."""
+    prior = ((state.get("tasks") or {}).get(slug) or {}).get("freeze") or {}
+    m = re.fullmatch(r"v(\d+)", str(prior.get("version", "")))
+    return f"v{int(m.group(1)) + 1}" if m else "v1"
+
+
+def cmd_freeze(args: argparse.Namespace) -> None:
+    """The §3 contract-freeze write command — the 5th engine-WRITTEN human approval (task
+    freeze-actor-stamp), joining lock · gate · milestone-done · release. Flips the target
+    task's §3 `Status: DRAFT` -> `FROZEN @ vN — approved by <name>` AND records a structured
+    actor on the task's state record (mirrors cmd_lock's `setup.actor`), so the audit trail
+    has no hole at freeze. The human RUNS it as their approval — never pre-stamped.
+
+    validate-then-write: every refusal fires before any write. Writes TASK.md first, then
+    state; a crash between degrades to today's legacy text-only freeze (never corrupt state),
+    design-for-failure."""
+    root = _require_root()
+    state = load_state(root)
+    raw_slug = getattr(args, "slug", None)
+    if not raw_slug and not _active_task(state):
+        _die("no_active_task: no task given and no active task is set")
+    slug = _resolve_task(state, raw_slug)                  # unknown slug -> _die
+    task_md = root / "tasks" / slug / "TASK.md"
+    text = task_md.read_text(encoding="utf-8")
+    raw3 = _phase_spans(text).get(3, "")
+    phase = (state["tasks"].get(slug) or {}).get("phase", "specify")
+    # --- validate (no writes); error precedence: frozen -> not-drafted -> unflagged ---
+    if _contract_frozen(raw3):
+        _die(f"already_frozen: {slug}'s §3 is already FROZEN — re-freeze only via a change "
+             f"request back to SPECIFY")
+    if _phase_index(phase) < _phase_index("contract") or _CONTRACT_TEMPLATE_RE.search(raw3):
+        _die(f"contract_not_drafted: {slug}'s §3 is not a drafted contract yet — reach the "
+             f"`contract` phase and replace the template before freezing")
+    if not _flag_well_formed(raw3):
+        _die(f"unflagged_freeze: {slug}'s §3 must surface a well-formed lowest-confidence flag "
+             f"('Least-sure flag surfaced at freeze:' + a [part] tag) before it freezes")
+    # --- write ---
+    ver = _next_freeze_version(state, slug)
+    who = args.by or identity._actor_stamp(state)["name"]
+    # flip the `Status: DRAFT` line WITHIN the §3 region only — a bare `Status: DRAFT` in
+    # §1/§2 prose must never be frozen by mistake (refute-read finding). §3 span runs from
+    # its `## 3 ·` heading to the next `## `/`---`/EOF (same boundary as _phase_spans).
+    h3 = re.search(r"(?m)^##\s*3\s*·.*$", text)
+    if not h3:
+        _die(f"contract_not_drafted: {slug}'s TASK.md has no §3 CONTRACT section")
+    seg_start = h3.end()
+    nxt = re.search(r"(?m)^(?:##\s|---\s*$)", text[seg_start:])
+    seg_end = seg_start + (nxt.start() if nxt else len(text) - seg_start)
+    new_seg, n = re.subn(r"(?m)^(\s*)Status:\s*DRAFT\s*$",
+                         lambda m: f"{m.group(1)}Status: FROZEN @ {ver} — approved by {who}",
+                         text[seg_start:seg_end], count=1)
+    if n == 0:
+        _die(f"contract_not_drafted: {slug}'s §3 has no 'Status: DRAFT' line to freeze")
+    new_text = text[:seg_start] + new_seg + text[seg_end:]
+    _atomic_write(task_md, new_text)                       # TASK.md first (audit source of truth)
+    state["tasks"][slug]["freeze"] = {"version": ver, "frozen_at": _now(),
+                                      "approved_by": who, "actor": identity._actor_stamp(state)}
+    save_state(root, state)
+    print(f"froze §3 of {slug} @ {ver} — approved by {who}")
+    print(_next_footer(root, state))
+
+
 def _parse_deps(raw: str | None) -> list[str]:
     if not raw:
         return []
@@ -1303,6 +1375,14 @@ def cmd_status(args: argparse.Namespace) -> None:
             _so = _fmt_actor(_owner_rec) if _owner_rec.get("name") else ""
             _own_frag = f"  · owner: {_so}" if _so else ""
             print(f"  {_mk} {_m:<20} task={_tk or '(none)'}  phase={_ph}{_tag}{_own_frag}")
+    # queued backlog (queue-resume-surface): surface milestones awaiting promotion so a
+    # multi-milestone session resumes cleanly — `active` is what you're on, `queued` is what's
+    # next. ADDITIVE + present-only: silent when zero queued (byte-identical), exactly like the
+    # release/loose/streams cues; reads state, writes nothing, changes no command decision.
+    _queued = [ms for ms, m in milestones.items() if m.get("status") == "queued"]
+    if _queued:
+        print(f"queued  : {len(_queued)} milestone(s) next — {', '.join(_queued)}")
+        print(f"          promote next: add.py activate {_queued[0]}")
     # surface the active task's autonomy level (task explicit-autonomy-dial) so the human
     # reads the throttle every session; "unset" when no explicit `autonomy:` line is present.
     if active and active in tasks:
@@ -2239,6 +2319,39 @@ def _doctor_findings(root: Path) -> list[str]:
         if m is not None and m not in milestones:
             findings.append(f"task '{slug}' references missing milestone '{m}' — fix: set its "
                             "milestone to a real one (or none)")
+    # value-domain checks (doctor-value-checks): gate/phase enum (required) · owner/assignee
+    # shape (optional) · archived consistency. Present-but-invalid + missing-required only;
+    # absent owner/assignee is fine. Pure/total — .get-guarded, isinstance-checked, never raises.
+    for slug, t in tasks.items():
+        if not isinstance(t, dict):
+            continue
+        g = t.get("gate")
+        if g is None:
+            findings.append(f"task '{slug}' is missing its gate — fix: one of {', '.join(GATES)}")
+        elif g not in GATES:
+            findings.append(f"task '{slug}' has invalid gate '{g}' — fix: one of {', '.join(GATES)}")
+        p = t.get("phase")
+        if p is None:
+            findings.append(f"task '{slug}' is missing its phase — fix: one of {', '.join(PHASES)}")
+        elif p not in PHASES:
+            findings.append(f"task '{slug}' has invalid phase '{p}' — fix: one of {', '.join(PHASES)}")
+        for role in ("owner", "assignee"):
+            v = t.get(role)
+            if v is not None and not (isinstance(v, dict) and isinstance(v.get("name"), str) and v.get("name")):
+                findings.append(f"task '{slug}' has a malformed {role} — fix: an actor object "
+                                "{name, email, source} or remove it")
+    archived = state.get("archived") if isinstance(state.get("archived"), list) else []
+    for a in archived:
+        if not isinstance(a, dict):
+            continue
+        aslug = a.get("slug")
+        if aslug is not None and aslug in milestones:
+            findings.append(f"archived milestone '{aslug}' is also a live milestone — fix: remove "
+                            "the live duplicate or the archived entry")
+        ts = a.get("task_slugs")
+        if isinstance(ts, list) and isinstance(a.get("tasks"), int) and a.get("tasks") != len(ts):
+            findings.append(f"archived milestone '{aslug}' task count {a.get('tasks')} ≠ {len(ts)} "
+                            "listed — fix: reconcile its task_slugs")
     return findings
 
 
@@ -2259,25 +2372,29 @@ def cmd_doctor(args: argparse.Namespace) -> None:
 
 
 def cmd_mine(args: argparse.Namespace) -> None:
-    """Read-only `add.py mine`: across all active milestones, the not-done tasks owned-by or
-    assigned-to the resolved actor (`_whoami`, or `--actor "Name <email>"`). Text or `--json`.
-    An empty queue is a plain exit-0 line, not an error. NEVER writes state."""
+    """Read-only `add.py mine`: the not-done tasks owned-by or assigned-to the resolved actor
+    (`_whoami`, or `--actor "Name <email>"`). Default lens is the active SET; `--all` widens it
+    to EVERY milestone plus loose (milestone-less) tasks. Text or `--json`. An empty queue is a
+    plain exit-0 line, not an error. NEVER writes state."""
     root = find_root()
     if root is None:
         _die("no_project")
     state = load_state(root)
     me = identity._parse_actor_arg(args.actor) if getattr(args, "actor", None) else identity._whoami(state)
-    rows = _my_work(state, me)
+    scope_all = getattr(args, "all", False)
+    rows = _my_work(state, me, scope_all=scope_all)
     if getattr(args, "json", False):
         print(json.dumps({"actor": me, "tasks": rows}))
         return
+    scope = "all" if scope_all else "active"
     who = _fmt_actor(me) or me.get("name", "you")
     if not rows:
-        print(f"mine: no open tasks for {who} across active milestones")
+        print(f"mine: no open tasks for {who} across {scope} milestones")
         return
-    print(f"mine: {who} — {len(rows)} open task(s) across active milestones:")
+    print(f"mine: {who} — {len(rows)} open task(s) across {scope} milestones:")
     for r in rows:
-        print(f"  {r['slug']:<24} [{r['milestone']}]  phase={r['phase']}  ({r['role']})")
+        loc = f"[{r['milestone']}]" if r["milestone"] else "[loose]"
+        print(f"  {r['slug']:<24} {loc}  phase={r['phase']}  ({r['role']})")
 
 
 # ---------------------------------------------------------------------------
@@ -2424,6 +2541,12 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     slug = args.slug
     if not slug.replace("-", "").replace("_", "").isalnum():
         _die("bad_slug")
+    # Prefer a short DESCRIPTIVE slug over a bare version (v2, v1-1, 1.2): a descriptive
+    # name keeps the milestones list legible. Advisory only — never blocks (matches the
+    # engine's `note:` convention); a deliberate version slug still creates.
+    if re.match(r"^v?\d+([._-]\d+)*$", slug, re.IGNORECASE):
+        print(f"note: slug '{slug}' looks like a bare version — prefer a short "
+              f"descriptive name (e.g. 'payment-retries'). Creating anyway.")
     state.setdefault("milestones", {})
     mdir = root / "milestones" / slug
     mfile = mdir / MILESTONE_FILE
@@ -2431,17 +2554,24 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
         _die("milestone_exists")
     mdir.mkdir(parents=True, exist_ok=True)
     title = args.title or slug.replace("-", " ").replace("_", " ").title()
+    # One _now() instant feeds BOTH the MILESTONE.md render and the state record, so the
+    # human-facing `created:` is a full ISO timestamp provably equal to state.json.
+    now = _now()
     _atomic_write(mfile, _render_template(
         "MILESTONE.md", title=title, goal=args.goal or "<goal>",
-        stage=args.stage, date=date.today().isoformat()))
+        stage=args.stage, date=now))
     # confirm-parent gate (OPT-IN, mirrors `init --await-lock`): `--await-confirm` seeds the
     # milestone UNCONFIRMED so new-task is held until `add.py milestone-confirm`. WITHOUT the flag
     # NO `confirmed` key is written → grandfathered-confirmed → no gate (so the existing engine
     # tests stay byte-green). The guided skill flow passes the flag at the human-review point.
     await_confirm = bool(getattr(args, "await_confirm", False))
+    # --queued (OPT-IN): create the milestone non-active (status=queued) without stealing focus.
+    # The active set is left UNCHANGED so the default path (no flag) stays byte-identical. Promote
+    # later with `activate` (queued→active). Foundation for roadmap intake (1 active + N queued).
+    queued = bool(getattr(args, "queued", False))
     record = {
         "title": title, "goal": args.goal or "", "stage": args.stage,
-        "status": "active", "created": _now(), "updated": _now(),
+        "status": "queued" if queued else "active", "created": now, "updated": now,
     }
     if await_confirm:
         # `await_confirm` is the STABLE opt-in marker (set ONLY here, at creation). `confirmed`
@@ -2449,11 +2579,22 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
         # milestone too, so a later build-entry gate must key on `await_confirm`, not `confirmed`.
         record.update(confirmed=False, confirmed_at=None, confirmed_by=None, await_confirm=True)
     state["milestones"][slug] = record
-    _set_active_milestone(state, slug)
+    if not queued:
+        # PRESERVE the active SET (new-milestone-add-focus): ADD this milestone + focus it, rather
+        # than REPLACING the set and evicting the others. Single-active is identical ([] -> [slug]);
+        # a user who already had P active now keeps P active alongside the new primary.
+        _activate_milestone(state, slug)
     save_state(root, state)
     print(f"created milestone '{slug}' -> {mfile}")
-    print("active milestone set." + ("" if not await_confirm else
-          "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
+    if queued:
+        print(f"queued (not active) — promote it with: add.py activate {slug}")
+        # surface the recorded confirm gate for a queued+await_confirm milestone (queued-await-confirm-hint):
+        # additive — prints ONLY when await_confirm, so plain `--queued` output stays byte-identical.
+        if await_confirm:
+            print(f"  (unconfirmed — after promote: add.py milestone-confirm {slug})")
+    else:
+        print("active milestone set." + ("" if not await_confirm else
+              "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 
@@ -2542,25 +2683,34 @@ def cmd_ready(args: argparse.Namespace) -> None:
 
 
 def _wave_schedule(state: dict, mslug: str) -> dict:
-    """Pure, total: derive the DAG schedule for milestone `mslug` from state — never
-    mutates, never raises on dict input. Returns one of:
+    """One-element wrapper: a single milestone's schedule is the merge over just [mslug].
+    Output is byte-identical to the historical per-milestone scheduler (the suite is the oracle)."""
+    return _wave_schedule_merged(state, [mslug])
+
+
+def _wave_schedule_merged(state: dict, mslugs: list[str]) -> dict:
+    """Pure, total: derive ONE DAG schedule over the UNION of open members across `mslugs`
+    (a single-element list is the historical per-milestone case) — never mutates, never raises
+    on dict input. Returns one of:
       {"cycle": [slug, ...]}                                       — unschedulable cycle
       {"waves", "critical_path", "critical_path_len", "tiers", "blocked"}  — a schedule
 
     A dep is SATISFIED (does not block) if it is archived or `_task_done` — the SAME
-    predicate cmd_ready uses. A not-done dep that is an OPEN MEMBER of this milestone
-    forces a later wave. A not-done dep that is NOT an open member (external/unknown)
-    is UNSATISFIABLE here -> the task is `blocked`, never scheduled. Critical path is the
-    longest chain (most tasks) through the scheduled sub-DAG; ties break by sorted slug.
-    Tier is advisory: `top` on the critical path, `mid` elsewhere (scheduled tasks only)."""
+    predicate cmd_ready uses. A not-done dep that is an OPEN MEMBER of ANY target milestone
+    forces a later wave (so a cross-milestone dep ORDERS, it does not block). A not-done dep
+    that is NOT an open member of any target (external/unknown) is UNSATISFIABLE here -> the
+    task is `blocked`, never scheduled. Critical path is the longest chain (most tasks) through
+    the scheduled sub-DAG; ties break by sorted slug. Tier is advisory: `top` on the critical
+    path, `mid` elsewhere (scheduled tasks only)."""
     tasks = state.get("tasks") or {}
     archived = _archived_task_slugs(state)
+    targetset = set(mslugs)
 
     def _ok(d: str) -> bool:                       # satisfied externally / already done
         return d in archived or (d in tasks and _task_done(tasks[d]))
 
     open_members = {s: t for s, t in tasks.items()
-                    if t.get("milestone") == mslug and not _task_done(t)}
+                    if t.get("milestone") in targetset and not _task_done(t)}
 
     # partition open members into blocked vs schedulable — to a FIXED POINT, so blocking
     # propagates transitively: a task is blocked if any dep is unsatisfiable here, where
@@ -2661,16 +2811,71 @@ def _wave_block_lines(state: dict, mslug: str, sched: dict) -> list[str]:
     return lines
 
 
+def _wave_block_lines_merged(state: dict, mslugs: list[str], sched: dict) -> list[str]:
+    """The text lines `waves --merge` renders for ONE unified schedule over the milestone SET:
+    a `merged: …` header naming the set + each scheduled task tagged with its `[milestone]` so
+    cross-milestone tasks are unambiguous. Critical-path / tier-hint / blocked lines mirror
+    `_wave_block_lines`."""
+    n = len(mslugs)
+    lines = [f"merged: {' + '.join(mslugs)} ({n} milestone{'s' if n != 1 else ''})"]
+    if not sched["waves"]:
+        if sched["blocked"]:
+            for s in sched["blocked"]:
+                lines.append(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+        else:
+            lines.append("all tasks done — nothing to schedule")
+        return lines
+    scheduled_set = {x for w in sched["waves"] for x in w}
+    for i, wave in enumerate(sched["waves"], start=1):
+        parts = []
+        for s in wave:
+            label = f"{s} [{state['tasks'][s].get('milestone')}]"
+            md = sorted(d for d in (state["tasks"][s].get("depends_on") or [])
+                        if d in scheduled_set)
+            parts.append(f"{label} (deps: {', '.join(md)})" if md else label)
+        lines.append(f"wave {i}: {', '.join(parts)}")
+    crit = sched["critical_path"]
+    lines.append(f"critical path: {' → '.join(crit)}  ({sched['critical_path_len']} tasks)")
+    tops = [s for s, tier in sched["tiers"].items() if tier == "top"]
+    mids = [s for s, tier in sched["tiers"].items() if tier == "mid"]
+    lines.append(f"tier hint: top → {', '.join(tops)}; mid → {', '.join(mids) or '(none)'}")
+    for s in sched["blocked"]:
+        lines.append(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+    return lines
+
+
 def cmd_waves(args: argparse.Namespace) -> None:
     """READ-ONLY DAG scheduler: print the topological waves, critical path, advisory tier hint,
-    and blocked set. With no --milestone it spans EVERY active milestone (cross-active-waves);
-    a single target / --milestone renders byte-identically. Writes nothing; no `next:` footer."""
+    and blocked set. With no --milestone it spans EVERY active milestone (cross-active-waves)
+    as SEPARATE streams; a single target / --milestone renders byte-identically. With --merge it
+    unifies the active SET into ONE schedule so cross-milestone deps order, not block.
+    Writes nothing; no `next:` footer."""
     is_json = getattr(args, "json", False)
     if is_json:
         _, state = _load_state_for_json()
     else:
         state = load_state(_require_root())
     mslug_arg = getattr(args, "milestone", None)
+    if getattr(args, "merge", False):
+        if mslug_arg:                                  # explicit target → a 1-milestone merge (NOT a conflict)
+            if mslug_arg not in (state.get("milestones") or {}):
+                _die(f"unknown_milestone: '{mslug_arg}' is not a milestone in this project")
+            targets = [mslug_arg]
+        else:
+            primary = _active_milestone(state)
+            if not primary:
+                _die("no_active_milestone: no active milestone and no --milestone given")
+            targets = [primary] + [m for m in (state.get("active_milestones") or [])
+                                   if m != primary]
+        sched = _wave_schedule_merged(state, targets)
+        if "cycle" in sched:
+            _die(f"dependency_cycle: not-done deps form a cycle "
+                 f"({' -> '.join(sched['cycle'])}) — no valid schedule")
+        if is_json:
+            print(json.dumps({"merged": targets, **sched}))
+        else:
+            print("\n".join(_wave_block_lines_merged(state, targets, sched)))
+        return
     if mslug_arg:
         targets = [mslug_arg]                          # explicit single target — unchanged
     else:
@@ -2938,6 +3143,11 @@ def cmd_activate(args: argparse.Namespace) -> None:
         _die("unknown_milestone")
     if state["milestones"][slug].get("status") == "done":
         _die("milestone_done")
+    # PROMOTE a queued milestone: activating it flips queued→active (human-gated promotion —
+    # the chosen verb, reusing `activate` rather than a separate `promote`). An already-active
+    # milestone is just refocused (status unchanged), keeping the default path byte-identical.
+    if state["milestones"][slug].get("status") == "queued":
+        state["milestones"][slug]["status"] = "active"
     _activate_milestone(state, slug)
     save_state(root, state)
     print(f"activated '{slug}' — active: {', '.join(state['active_milestones'])}")
@@ -5242,6 +5452,14 @@ def build_parser() -> argparse.ArgumentParser:
     pl.add_argument("--json", action="store_true", help="emit one JSON object instead of text")
     pl.set_defaults(func=cmd_lock)
 
+    pfz = sub.add_parser("freeze",
+                         help="freeze a task's §3 contract (the human approval) — stamps "
+                              "FROZEN @ vN + a structured actor on the task record")
+    pfz.add_argument("slug", nargs="?", default=None,
+                     help="task to freeze (default: the active task)")
+    pfz.add_argument("--by", default=None, help="approver name (default: the resolved actor)")
+    pfz.set_defaults(func=cmd_freeze)
+
     pwho = sub.add_parser("whoami",
                           help="show / set the git-native actor (git config -> OS user; --name to override)")
     # --name (set) and --unset (clear) are mutually exclusive — argparse rejects the
@@ -5301,6 +5519,10 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--goal", default=None, help="one-sentence outcome")
     pm.add_argument("--stage", default="mvp", choices=STAGES)
     pm.add_argument("--force", action="store_true", help="overwrite MILESTONE.md if present")
+    pm.add_argument("--queued", action="store_true",
+                    help="create the milestone QUEUED (status=queued), not active: it is recorded "
+                         "and its MILESTONE.md written, but the active focus is unchanged. Promote it "
+                         "later with `activate <slug>`. Foundation for roadmap intake (1 active + N queued).")
     pm.add_argument("--await-confirm", action="store_true",
                     help="opt into the confirm-parent gate: seed the milestone unconfirmed so "
                          "new-task is held until `milestone-confirm` (mirrors `init --await-lock`); "
@@ -5321,6 +5543,8 @@ def build_parser() -> argparse.ArgumentParser:
                                        "waves + critical path + advisory tier hint")
     pwa.add_argument("--milestone", default=None,
                      help="milestone slug to schedule (default: the active milestone)")
+    pwa.add_argument("--merge", action="store_true",
+                     help="unify the active SET into ONE schedule (cross-milestone deps order, not block)")
     pwa.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pwa.set_defaults(func=cmd_waves)
 
@@ -5441,6 +5665,8 @@ def build_parser() -> argparse.ArgumentParser:
     pmine.add_argument("--actor", default=None, metavar="\"Name <email>\"",
                        help="inspect another actor's queue instead of your own")
     pmine.add_argument("--json", action="store_true", help="emit one JSON object instead of text")
+    pmine.add_argument("--all", action="store_true",
+                       help="widen past the active SET: every milestone + loose tasks, not just active")
     pmine.set_defaults(func=cmd_mine)
 
     pwv = sub.add_parser("wave-verify",

package/tooling/templates/DESIGN.md.tmpl

@@ -31,6 +31,17 @@ The design intent the AI drafts UI against — the persona, the one job, the fee
 - **Design principles** — <!-- 3–5 lines, e.g. "one primary action per screen" · "never hide state" -->
 - **Accessibility floor** — <!-- e.g. WCAG AA contrast · focus-visible · hit-target ≥ 44px -->
 
+## Design intake
+
+The per-design picks the `design-intake` beat collects (see the `add` skill's `design.md`).
+These are project **defaults**; a screen records only its **overrides** in its prototype note.
+VISUAL DESIGN draws its color/type from **## Identity** above — don't restate the brand here.
+
+- **Fidelity** — <!-- lo-fi wireframe | hi-fi mockup | production — how far this design renders -->
+- **Concept** — <!-- the design idea / mood / direction, in a line -->
+- **Layout** — <!-- the structure / grid / hierarchy the screens lean on -->
+- **Visual design** — <!-- spacing scale · imagery style (color · type come from ## Identity) -->
+
 ## Screens
 
 An index of the app's screens — one `design/prototypes/<name>.json` per screen (a flat