@pilotspace/add 1.0.0 → 1.2.0

package/tooling/add.py

@@ -12,6 +12,7 @@ existing artifacts unless --force is given.
 from __future__ import annotations
 
 import argparse
+import getpass
 import json
 import os
 import re
@@ -25,7 +26,14 @@ from pathlib import Path
 ROOT_DIRNAME = ".add"
 STATE_FILE = "state.json"
 MILESTONE_FILE = "MILESTONE.md"
+# The project GOAL (v20) is read live from PROJECT.md — never copied into state.json
+# (single-source; the foundation is the truth). A missing/blank source degrades to
+# this sentinel so the read-only orientation surfaces never blank or crash.
+GOAL_UNSET = "(unset — add a 'goal:' line to PROJECT.md)"
 STAGES = ("prototype", "poc", "mvp", "production")
+# v22 stage-graduation: the read-only cue `status` shows when the MVP is covered.
+# Worded as the ACTION (never a file) so it stands before graduate.md exists.
+GRADUATION_CUE = "MVP covered → propose graduation"
 PHASES = ("specify", "scenarios", "contract", "tests", "build", "verify", "observe", "done")
 GATES = ("none", "PASS", "RISK-ACCEPTED", "HARD-STOP")
 
@@ -37,7 +45,7 @@ def _phase_index(name: str) -> int:
 # `add.py guide` copy: per-phase (concrete next action, book chapter to read).
 # Keep the action wording aligned with each phase's EXIT line in the TASK template.
 PHASE_GUIDE = {
-    "specify":   ("state every rule — Must / Reject (+ named code) / After; rank assumptions least-sure first and flag the biggest risk",
+    "specify":   ("state every rule — Must / Reject (+ named code) / After; rank assumptions lowest-confidence first and flag the biggest risk",
                   "03-step-1-specify.md"),
     "scenarios": ("write one Given/When/Then per Must AND per Reject; every result observable",
                   "04-step-2-scenarios.md"),
@@ -47,7 +55,7 @@ PHASE_GUIDE = {
                   "06-step-4-tests.md"),
     "build":     ("write the minimum code to pass the tests; change no test and no contract",
                   "07-step-5-build.md"),
-    "verify":    ("run the suite + blind-spot checks, then record the gate",
+    "verify":    ("run the suite + non-functional checks, then record the gate",
                   "08-step-6-verify.md"),
     "observe":   ("note what to watch + the spec delta for the next loop",
                   "09-the-loop.md"),
@@ -84,8 +92,8 @@ Framings weighed:
 Must:
 Reject:
 After:
-Assumptions — least-sure first:
-  ⚠ <most likely wrong> — least sure because <why>; if wrong: <cost>
+Assumptions — lowest-confidence first:
+  ⚠ <most likely wrong> — lowest confidence because <why>; if wrong: <cost>
 
 ## 2 · SCENARIOS
 ## 3 · CONTRACT
@@ -162,7 +170,14 @@ def _require_root() -> Path:
 
 
 def load_state(root: Path) -> dict:
-    return json.loads((root / STATE_FILE).read_text(encoding="utf-8"))
+    """Load + parse state.json, failing CLOSED. A corrupt or unreadable state file
+    dies with a clean 'state_invalid' message (never a raw traceback), so every
+    command that loads state degrades gracefully (design-for-failure)."""
+    try:
+        return json.loads((root / STATE_FILE).read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        _die(f"state_invalid: {root / STATE_FILE} is corrupt or unreadable "
+             f"({e.__class__.__name__}) — restore it from git or a backup")
 
 
 def _load_state_for_json() -> tuple[Path, dict]:
@@ -191,6 +206,15 @@ def save_state(root: Path, state: dict) -> None:
     _atomic_write(root / STATE_FILE, json.dumps(state, indent=2) + "\n")
 
 
+def _setup_locked(state: dict) -> bool:
+    """True when the project's setup is locked — i.e. the build-boundary gate is OPEN.
+
+    A state with NO "setup" key is GRANDFATHERED-locked: plain `init` and every legacy
+    project are never gated (the lock is opt-in via `init --await-lock`). The gate is
+    therefore active in exactly one case: "setup" present AND locked is False."""
+    return ("setup" not in state) or (state["setup"].get("locked") is True)
+
+
 def _die(msg: str, code: int = 1) -> None:
     print(f"add: error: {msg}", file=sys.stderr)
     raise SystemExit(code)
@@ -205,27 +229,37 @@ def _die(msg: str, code: int = 1) -> None:
 # 20%+ more cost), so the stable pointer is the whole point.
 
 def _guideline_block() -> str:
-    """The canonical ADD block (markers + body, no trailing newline)."""
+    """The canonical ADD block (markers + body, no trailing newline).
+
+    Agent-agnostic by design (v14 agent-portability): the routing steps depend
+    only on the CLI and plain files, so any agent — Claude, Cursor, Copilot,
+    Codex — can follow them. Claude additionally gets the `add` skill."""
     return (
         f"{_GUIDE_BEGIN}\n"
         "## ADD — how to work in this repo\n"
         "\n"
         "This project uses **ADD (AI-Driven Development)**: you, the AI, drive the build;\n"
-        "the human owns direction and verification. Before you change code:\n"
+        "the human owns direction and verification. The loop below works for any agent —\n"
+        "Claude, Cursor, Copilot, Codex — through the CLI alone. Before you change code:\n"
         "\n"
         "1. Run `python3 .add/tooling/add.py status` — where the project is and what's\n"
         "   next (the resume point; read it first every session).\n"
         "2. Read `.add/PROJECT.md` — the foundation (domain · spec · UI/UX) every task\n"
         "   builds on.\n"
-        "3. Let the **`add` skill drive the flow**: INTAKE sizes the request into a\n"
-        "   milestone, then each task runs the **one-approval front** — you draft Spec +\n"
-        "   Scenarios + Contract + Tests as one bundle, the human gives ONE approval at the\n"
-        "   frozen contract — followed by a self-driving build→verify run. `add.py` is your\n"
-        "   hands (scaffold + track state); the human talks to you, not the CLI.\n"
+        "3. Run `python3 .add/tooling/add.py guide` — it names the phase and the exact\n"
+        "   phase-guide file to read (the `guide  :` line). Work ONLY that phase — each\n"
+        "   guide ends with its exit gate and the command to move on.\n"
         "\n"
-        "The full method (the book) is in `.add/docs/`; the `add` skill loads the right\n"
-        "phase guide on demand. This block is generated by `add.py sync-guidelines`; edit\n"
-        "outside the markers, not inside.\n"
+        "The flow: INTAKE sizes a request into a milestone; each task runs the\n"
+        "**specification bundle** — Spec+Scenarios+Contract+Tests as one bundle,\n"
+        "ONE human approval at the frozen contract — then a self-driving build→verify\n"
+        "run. Non-negotiable for every agent:\n"
+        "Never weaken a test or edit a frozen contract to make a build pass; a security\n"
+        "finding is always HARD-STOP — never auto-passed.\n"
+        "\n"
+        "On Claude Code the `add` skill drives this loop automatically; other agents\n"
+        "follow the three steps. The book is in `.add/docs/`. This block is generated\n"
+        "by `add.py sync-guidelines`; edit outside the markers, not inside.\n"
         f"{_GUIDE_END}"
     )
 
@@ -294,6 +328,24 @@ def _inject_guidelines(project_root: Path) -> list[tuple[str, str]]:
 
 # --- commands ----------------------------------------------------------------
 
+_INIT_EXCLUDE = {
+    ".add", "AGENTS.md", "CLAUDE.md", ".git",
+    ".gitignore", ".gitattributes", ".github", ".editorconfig",  # VCS/CI/editor scaffolding — no domain signal
+    "LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING",            # legal boilerplate — no domain signal
+}  # README/docs/source are NOT excluded: they carry domain content adopt.md maps -> brownfield
+
+
+def _is_brownfield(base: Path) -> bool:
+    """True when `base` already holds project content beyond the tool's own scaffolding.
+
+    Judgment-free: a mechanical fact (does the dir hold a non-excluded entry?), so the
+    autonomous-onboarding flow knows to map existing code into the living documentation. INTERPRETING
+    that code stays with the AI (skill/add/adopt.md) — the engine only detects + signals."""
+    if not base.is_dir():
+        return False
+    return any(child.name not in _INIT_EXCLUDE for child in base.iterdir())
+
+
 def cmd_init(args: argparse.Namespace) -> None:
     base = Path(args.dir).resolve()
     root = base / ROOT_DIRNAME
@@ -330,14 +382,24 @@ def cmd_init(args: argparse.Namespace) -> None:
         "created": _now(),
         "updated": _now(),
     }
+    if getattr(args, "await_lock", False):
+        # opt-in: seed an UNLOCKED setup so the build-boundary gate is active until
+        # `add.py lock`. Plain init omits this key entirely (grandfathered-locked).
+        state["setup"] = {"locked": False, "locked_at": None, "locked_by": None, "layers": []}
     save_state(root, state)
     # zero-config: give any agent a stable pointer into the ADD runtime.
     for name, action in _inject_guidelines(base):
         if action != "unchanged":
             print(f"{action:>9}  {name}")
     print(f"initialised ADD project '{state['project']}' (stage: {state['stage']}) at {root}")
-    print("next: open Claude Code, run `/add`, and say what you want to build —")
-    print("      the `add` skill sizes it into a milestone and drives the build with you.")
+    if _is_brownfield(base):
+        # Existing code present — the AI maps it SILENTLY into the survivors (skill/add/adopt.md),
+        # then the human locks it down. The engine only flags it; it never reads or fills the code.
+        print("brownfield: existing code detected — the `add` skill maps it into your")
+        print("            foundation (silent), then you lock it down: add.py lock")
+    else:
+        print("next: open Claude Code, run `/add`, and say what you want to build —")
+        print("      the `add` skill sizes it into a milestone and drives the build with you.")
 
 
 def cmd_sync_guidelines(args: argparse.Namespace) -> None:
@@ -349,6 +411,9 @@ def cmd_sync_guidelines(args: argparse.Namespace) -> None:
 def cmd_new_task(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
+    # build-boundary gate: pre-lock, EXACTLY one first task may be drafted; refuse a 2nd.
+    if not _setup_locked(state) and state.get("tasks"):
+        _die("setup_unlocked: lock the foundation first — add.py lock")
     slug = args.slug
     if not slug.replace("-", "").replace("_", "").isalnum():
         _die("slug must be alphanumeric with - or _ only")
@@ -453,6 +518,24 @@ def cmd_advance(args: argparse.Namespace) -> None:
     if idx >= len(PHASES) - 1:
         _die(f"task '{slug}' already at final phase ({cur})")
     nxt = PHASES[idx + 1]
+    # build-boundary gate: pre-lock the front (specify..tests) is allowed, but crossing
+    # into build/verify/observe/done is refused until `add.py lock`.
+    if not _setup_locked(state) and nxt in ("build", "verify", "observe", "done"):
+        _die("setup_unlocked: lock the foundation first — add.py lock")
+    # flag-first freeze guard (task unflagged-freeze): a FROZEN §3 may not cross
+    # into build without a WELL-FORMED lowest-confidence flag. On pass, stamp the
+    # verified marker so `audit` enforces the flag on THIS record only (open/new
+    # freezes — the unmarked predecessors are never retro-redded). REFUSE writes
+    # nothing (fail-closed); below the build boundary the flag is never checked.
+    if nxt == "build":
+        raw3 = _raw_phase_bodies(root, slug).get(3, "")
+        if _contract_frozen(raw3):
+            if not _flag_well_formed(raw3):
+                _die("unflagged_freeze: a frozen §3 must surface a well-formed "
+                     "'Least-sure flag surfaced at freeze:' unit (>=1 [part] tag "
+                     "+ substantive content; bare 'none' only as 'none material — "
+                     "biggest risk: X') before crossing into build")
+            state["tasks"][slug]["flag_verified"] = True
     state["tasks"][slug]["phase"] = nxt
     state["tasks"][slug]["updated"] = _now()
     _sync_task_marker(root, slug, nxt)
@@ -460,10 +543,33 @@ def cmd_advance(args: argparse.Namespace) -> None:
     print(f"task '{slug}' phase {cur} -> {nxt}")
 
 
+# The mechanized high-risk guard (run.md, v14): judging WHAT is high-risk stays
+# human — a scope declares `risk: high` in its TASK.md header at the freeze. The
+# engine then enforces the pure token contradiction: risk: high WITHOUT
+# autonomy: conservative is unguarded, and completion is refused. Tokens are
+# read from the header region (text before the first section heading) with HTML
+# comments stripped — a documentation comment is never a declaration.
+_RISK_HIGH_RE = re.compile(r"\brisk:\s*high\b")
+_AUTONOMY_CONSERVATIVE_RE = re.compile(r"\bautonomy:\s*conservative\b")
+
+
+def _task_header(root: Path, slug: str) -> str:
+    """The TASK.md header region — where declared tokens (risk · autonomy)
+    live — with HTML comments stripped. Missing file -> '' (no tokens)."""
+    try:
+        text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    return re.sub(r"<!--.*?-->", "", text.split("\n## ", 1)[0], flags=re.S)
+
+
 def cmd_gate(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
     slug = _resolve_task(state, args.slug)
+    # build-boundary gate: no verdict may be recorded before the setup is locked.
+    if not _setup_locked(state):
+        _die("setup_unlocked: lock the foundation first — add.py lock")
     if args.outcome not in GATES:
         _die(f"outcome must be one of: {', '.join(GATES)}")
     # Completing outcomes (PASS, RISK-ACCEPTED) are the VERIFY step's verdict, so they
@@ -478,6 +584,14 @@ def cmd_gate(args: argparse.Namespace) -> None:
                     else "gate_risk_accepted_before_verify")
             _die(f"{code}: task '{slug}' is at '{current}'; reach the verify phase "
                  f"first (or `add.py phase verify {slug}` to override)")
+        # the mechanized high-risk guard: an unguarded high-risk header refuses
+        # COMPLETION (PASS / RISK-ACCEPTED) until the dial is lowered and a human
+        # owns the gate. HARD-STOP is never blocked — stopping is always allowed.
+        hdr = _task_header(root, slug)
+        if _RISK_HIGH_RE.search(hdr) and not _AUTONOMY_CONSERVATIVE_RE.search(hdr):
+            _die(f"unguarded_high_risk_auto: task '{slug}' declares risk: high "
+                 "without autonomy: conservative — lower the autonomy level in the TASK.md "
+                 "header; a human must own a high-risk gate (run.md guard)")
     if args.outcome == "RISK-ACCEPTED":
         # A waiver must be SIGNED: owner, ticket, expiry (glossary). Stored in state
         # so a later `check` can read/expire it. Refuse a partial waiver outright.
@@ -499,19 +613,111 @@ def cmd_gate(args: argparse.Namespace) -> None:
         print("HARD-STOP recorded: return to BUILD; nothing ships on a failing/security gate.")
 
 
+def cmd_reopen(args: argparse.Namespace) -> None:
+    """Return an already-`done` task to an earlier phase with a never-silent record.
+
+    The flow already permits backward correction (book ch02: "any phase may return
+    to an earlier one"); `done` is terminal EXCEPT via this recorded action. reopen
+    sets the phase back, resets the gate to "none" (the task must re-earn its
+    verdict), and appends an append-only `reopens` entry recording WHY. A done task
+    done via RISK-ACCEPTED carries a live `waiver`; reopen records it inside the entry
+    (prior_gate / prior_waiver) and drops the live key, so no signed waiver lingers
+    without a verdict. Judgement of WHEN to reopen stays the resolver's; the engine
+    only enforces the recorded, coherent transition.
+    """
+    root = _require_root()
+    state = load_state(root)
+    slug = _resolve_task(state, args.slug)
+    t = state["tasks"][slug]
+    if t.get("phase") != "done":
+        _die(f"reopen_not_done: task '{slug}' is at '{t.get('phase')}', not done — "
+             "backward correction inside a live run is `add.py phase` / HARD-STOP, not reopen")
+    reason = (args.reason or "").strip()
+    if not reason:
+        _die("reopen_reason_required: reopen records WHY — supply a non-empty --reason")
+    target = args.to
+    if target not in PHASES[:7]:        # specify..observe; never "done", never an unknown name
+        _die(f"reopen_target_invalid: --to must be one of {', '.join(PHASES[:7])} (got {target!r})")
+    now = _now()
+    entry = {"from": "done", "to": target, "reason": reason, "at": now,
+             "prior_gate": t.get("gate", "none")}
+    if t.get("waiver"):                 # void verdict's waiver -> history, drop the live key
+        entry["prior_waiver"] = t.pop("waiver")
+    t.setdefault("reopens", []).append(entry)
+    t["phase"] = target
+    t["gate"] = "none"
+    t["updated"] = now
+    _sync_task_marker(root, slug, target)
+    save_state(root, state)
+    print(f"task '{slug}' reopened: done -> {target} (reason recorded); gate reset to none")
+
+
+def cmd_lock(args: argparse.Namespace) -> None:
+    """The human baseline approval: freeze the autonomously-drafted setup in ONE atomic write.
+
+    Setup-level analog of the contract freeze — the only new human action onboarding
+    needs. `add.py lock` is judgment-free (it records the signature; it does NOT inspect
+    the artifacts): the human's signature IS the gate."""
+    root = _require_root()
+    state = load_state(root)
+    # idempotent-guarded: the predicate also treats a grandfathered (no "setup" key)
+    # project as already locked, so a bare re-lock there refuses too.
+    if _setup_locked(state) and not args.force:
+        _die("already_locked: setup is already locked (use --force to re-lock)")
+    # parse layers BEFORE any write so an invalid request never half-locks (design-for-failure).
+    raw = args.layers if args.layers is not None else "foundation,scope,contract"
+    layers = [s.strip() for s in raw.split(",") if s.strip()]
+    if not layers:
+        _die("layers_invalid: --layers must name at least one lock layer")
+    who = args.by or getpass.getuser()
+    when = _now()
+    # ONE atomic write — no partial lock state.
+    state["setup"] = {"locked": True, "locked_at": when, "locked_by": who, "layers": layers}
+    save_state(root, state)
+    if getattr(args, "json", False):
+        print(json.dumps(
+            {"locked": True, "locked_at": when, "locked_by": who, "layers": layers},
+            separators=(",", ":")))
+    else:
+        print(f"locked setup ({','.join(layers)}) by {who} @ {when}")
+
+
+def _has_production_roadmap(state: dict) -> bool:
+    """True iff ≥1 milestone in state has stage == "production" (STATUS-AGNOSTIC).
+    The single source of the stage-graduation floor (v22 graduate-guide): the guard counts
+    that a production-roadmap RECORD exists — it never judges whether those milestones are
+    done/good/sufficient (gather-not-judge). An archived-out-of-state roadmap falls to --force."""
+    return any(m.get("stage") == "production"
+               for m in state.get("milestones", {}).values())
+
+
 def cmd_stage(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
     if args.stage not in STAGES:
         _die(f"stage must be one of: {', '.join(STAGES)}")
+    # v22 stage-graduation guard: the →production TRANSITION refuses without a roadmap — a tally
+    # check (≥1 production milestone exists), never a readiness judgment. Scoped to production
+    # ONLY; every other flip is the existing bare flip, byte-unchanged. --force overrides
+    # (precedent: lock --force). The flip is graduate.md's FINAL, confirmed-roadmap step.
+    forced = getattr(args, "force", False)
+    bypassing = False
+    if args.stage == "production":
+        roadmap = _has_production_roadmap(state)
+        if not roadmap and not forced:
+            _die("stage_no_roadmap: no production milestone drafted. Draft ≥1 via "
+                 "graduate.md (new-milestone --stage production), or use --force to override.")
+        bypassing = forced and not roadmap
     state["stage"] = args.stage
     save_state(root, state)
     print(f"project stage -> {args.stage}")
+    if bypassing:
+        print("(--force: bypassed roadmap check — no production milestone drafted)")
 
 
 def cmd_status(args: argparse.Namespace) -> None:
     if getattr(args, "json", False):
-        _, state = _load_state_for_json()
+        root, state = _load_state_for_json()
         tasks = state.get("tasks") or {}
         milestones = state.get("milestones") or {}
         ms_list = []
@@ -520,22 +726,43 @@ def cmd_status(args: argparse.Namespace) -> None:
             ms_list.append({"slug": mslug, "status": m.get("status", "active"),
                             "done": sum(1 for t in members if _task_done(t)),
                             "total": len(members)})
+        grad_ready, grad_met, grad_total = _graduation_ready(root, state)
         print(json.dumps({
             "project": state.get("project"), "stage": state.get("stage"),
             "active_task": state.get("active_task"),
             "milestones": ms_list,
             "tasks": [{"slug": s, "phase": t.get("phase"), "gate": t.get("gate"),
-                       "milestone": t.get("milestone")} for s, t in tasks.items()]}))
+                       "milestone": t.get("milestone")} for s, t in tasks.items()],
+            "graduation_ready": grad_ready,
+            "stage_criteria": {"met": grad_met, "total": grad_total}}))
         return
     root = _require_root()
     state = load_state(root)
     active = state.get("active_task")
     tasks = state.get("tasks", {})
-    print(f"project : {state['project']}")
-    print(f"stage   : {state['stage']}")
+    # Compute once: True when setup is present AND locked is False (the lock-gate window).
+    # Reuses the canonical helper — do NOT write a parallel predicate.
+    unlocked = not _setup_locked(state)
+    print(f"project : {state.get('project', '(unknown)')}")
+    print(f"stage   : {state.get('stage', '(unknown)')}")
+    # project GOAL + active-milestone goal (v20) — the loop's orientation anchor, read
+    # LIVE from PROJECT.md / MILESTONE.md (never state.json). Additive: every existing
+    # line stays put. A missing source degrades to a sentinel — one never blanks the other.
+    print(f"goal    : {_project_goal(root)}")
+    _active_ms = state.get("active_milestone")
+    if _active_ms:
+        print(f"m-goal  : {_milestone_doc(root, _active_ms)[1]}   (← {_active_ms})")
     # foundation pointer — read the cross-milestone context first (anti-rot)
     if (root / "PROJECT.md").exists():
         print("context : .add/PROJECT.md  (foundation: domain · spec · UI/UX — read first)")
+    # wave resume hint — a live ledger outranks memory (streams.md "Wave ledger").
+    # Existence-only: no open/read/parse, so the hint adds no IO failure path; a
+    # non-file at the path is not a ledger. One line PER live ledger — more than
+    # one live wave is an anomaly the orchestrator must see, never a line we hide.
+    for _wave in sorted((root / "milestones").glob("*/WAVE.md")):
+        if _wave.is_file():
+            print(f"wave    : LIVE — .add/milestones/{_wave.parent.name}/WAVE.md"
+                  "  (wave resume point — re-orient from the ledger first)")
 
     # milestone rollup (only when milestones are in use)
     milestones = state.get("milestones") or {}
@@ -548,6 +775,12 @@ def cmd_status(args: argparse.Namespace) -> None:
             mark = "*" if mslug == active_ms else " "
             print(f"  {mark} {mslug:<20} {done}/{len(members)} tasks done"
                   f"   status={m.get('status', 'active')}")
+        # graduation cue (v22): project-global + read-only. Fires only when every milestone
+        # is done AND the human's PROJECT.md stage-goal-criteria are all checked — additive
+        # (a new line solely when ready; the non-ready output is byte-identical to before).
+        grad_ready, _gm, _gt = _graduation_ready(root, state)
+        if grad_ready:
+            print(f"  → {GRADUATION_CUE}")
 
     # archived rollup — one line keeps state visible without re-bloating status
     archived = state.get("archived") or []
@@ -560,13 +793,18 @@ def cmd_status(args: argparse.Namespace) -> None:
     print(f"active  : {active or '(none)'}")
     if not tasks:
         # First-run panel: a brand-new project's status is the moment a user is most
-        # lost. Lead with the AI-first move (/add), keep the CLI as the escape hatch —
-        # mirrors `init`'s next-hint so the entry point is actionable, not a bare line.
+        # lost. When the setup is unlocked, the only correct next move is review+lock —
+        # suppress the generic /add hint and name the two steps that matter.
         print("tasks   : (none yet)")
         print()
-        print("next    : you're set up. In Claude Code, run /add and say what you want to")
-        print("          build — the `add` skill sizes it into a milestone and drives the")
-        print('          build with you. Escape hatch: add.py new-task <slug> --title "..."')
+        if unlocked:
+            print("setup   : UNLOCKED — review .add/SETUP-REVIEW.md (lowest-confidence first),"
+                  " then sign: add.py lock")
+            print("          (the build-boundary gate is closed until the foundation is locked)")
+        else:
+            print("next    : you're set up. In Claude Code, run /add and say what you want to")
+            print("          build — the `add` skill sizes it into a milestone and drives the")
+            print('          build with you. Escape hatch: add.py new-task <slug> --title "..."')
         return
     print("tasks   :")
     for slug, t in tasks.items():
@@ -575,7 +813,18 @@ def cmd_status(args: argparse.Namespace) -> None:
         dep_s = f"  deps={','.join(deps)}" if deps else ""
         ms_s = f"  [{t['milestone']}]" if t.get("milestone") else ""
         print(f"  {mark} {slug:<24} phase={t['phase']:<10} gate={t['gate']}{ms_s}{dep_s}")
-    if active:
+    # fold-pressure nudge: surface unfolded competency deltas so emission can't
+    # silently outrun the human fold (read-only; v11). Silent when none are open.
+    open_deltas = sum(len(v) for v in _collect_open_deltas(root).values())
+    if open_deltas:
+        print(f"deltas  : {open_deltas} open — consolidate at milestone close (add.py deltas)")
+    # When the setup is unlocked, the only terminal guidance that matters is
+    # review+lock; suppress the generic resume block so it does not compete.
+    if unlocked:
+        print("\nsetup   : UNLOCKED — review .add/SETUP-REVIEW.md (lowest-confidence first),"
+              " then sign: add.py lock")
+        print("          (the build-boundary gate is closed until the foundation is locked)")
+    elif active and active in tasks:
         ph = tasks[active]["phase"]
         if ph == "done":
             print(f"\nresume  : task '{active}' is done ({tasks[active]['gate']}).")
@@ -585,18 +834,42 @@ def cmd_status(args: argparse.Namespace) -> None:
             print(f"          read .add/tasks/{active}/TASK.md and continue that phase.")
 
 
+# Agent-portability (v14): `guide` names the PHASE PLAYBOOK file — the same
+# guides the Claude skill loads, installed as plain markdown by every channel
+# at .claude/skills/add/phases/ — so ANY agent (Cursor, Copilot, Codex) can be
+# routed there through the CLI alone. Never a dead pointer: the path is printed
+# only if the file exists; a missing tree gets an install hint instead.
+_PHASE_GUIDE_FILES = {
+    "specify": "1-specify.md", "scenarios": "2-scenarios.md",
+    "contract": "3-contract.md", "tests": "4-tests.md",
+    "build": "5-build.md", "verify": "6-verify.md", "observe": "7-observe.md",
+}
+_SKILL_PHASES_DIR = Path(".claude") / "skills" / "add" / "phases"
+
+
+def _phase_guide_path(project_root: Path, phase: str) -> str | None:
+    """Relative path to the phase playbook if it exists, else None.
+    done/unknown phases have no playbook (the `then:` line routes onward)."""
+    fname = _PHASE_GUIDE_FILES.get(phase)
+    if fname is None:
+        return None
+    rel = _SKILL_PHASES_DIR / fname
+    return str(rel) if (project_root / rel).is_file() else None
+
+
 def cmd_guide(args: argparse.Namespace) -> None:
     """Answer "what do I do next?" for the active (or named) task.
 
     Strictly read-only: load_state only — never save_state, never writes a TASK.md.
     """
     if getattr(args, "json", False):
-        _, state = _load_state_for_json()
+        json_root, state = _load_state_for_json()
         slug = args.slug or state.get("active_task")
         if not slug:
             print(json.dumps({"task": None, "phase": None, "owner": "human", "stop": True,
                               "next_step": "start your first feature -> add.py new-task <slug>",
-                              "chapter": ".add/docs/02-the-flow.md", "gate": None}))
+                              "chapter": ".add/docs/02-the-flow.md", "gate": None,
+                              "guide": None}))
             return
         t = (state.get("tasks") or {}).get(slug)
         if t is None:
@@ -606,7 +879,8 @@ def cmd_guide(args: argparse.Namespace) -> None:
         action, chapter = PHASE_GUIDE[phase]   # phase is mapped, so PHASE_GUIDE has it too
         print(json.dumps({"task": slug, "phase": phase, "owner": owner,
                           "stop": owner != "ai", "next_step": action,
-                          "chapter": f".add/docs/{chapter}", "gate": t.get("gate")}))
+                          "chapter": f".add/docs/{chapter}", "gate": t.get("gate"),
+                          "guide": _phase_guide_path(json_root.parent, phase)}))
         return
     root = _require_root()
     state = load_state(root)
@@ -624,8 +898,14 @@ def cmd_guide(args: argparse.Namespace) -> None:
         _die(f"task '{slug}' has unknown phase '{phase}' (state.json corrupted?)")
     action, chapter = entry
     print(f"active : {slug}  (phase: {phase})")
+    print(f"goal   : {_project_goal(root)}")   # v20 — the next-step surface still shows what the work is FOR
     print(f"next   : {action}")
     print(f"read   : .add/docs/{chapter}")
+    gp = _phase_guide_path(root.parent, phase)
+    if gp is not None:
+        print(f"guide  : {gp}")
+    elif phase in _PHASE_GUIDE_FILES:
+        print("guide  : (phase guides not installed — npx @pilotspace/add init)")
     if phase == "verify":
         print("then   : add.py gate PASS | RISK-ACCEPTED | HARD-STOP")
     elif phase == "done":
@@ -698,6 +978,13 @@ def cmd_check(args: argparse.Namespace) -> None:
             except (ValueError, TypeError):
                 ok, reason = False, f"waiver_expired (unparseable expires={exp!r})"
             checks.append((ok, f"task '{slug}' waiver not expired", reason))
+        # delta-lint: validate all OPEN entries in the "### Competency deltas" block.
+        # Fail-closed; folded/rejected entries are skipped (open-only). Only emits a
+        # check when at least one delta-attempt is present in the block.
+        lint_result = _lint_task_deltas(root, slug)
+        if lint_result is not None:
+            ok, reason = lint_result
+            checks.append((ok, f"task '{slug}' deltas well-formed", reason))
 
     # drift: a done milestone must have no unfinished tasks
     for mslug, m in milestones.items():
@@ -822,6 +1109,17 @@ def cmd_milestone_done(args: argparse.Namespace) -> None:
             t = members[s]
             print(f"  - {s} (phase={t.get('phase')}, gate={t.get('gate')})", file=sys.stderr)
         _die("milestone_incomplete")
+    # Goal-gate (v20 dynamic-task-loop): a milestone holds until its exit criteria are
+    # met. The engine READS the checkbox tally (the human's goal-met affirmation, like a
+    # gate=PASS) — it never judges the goal. Fires ONLY when criteria exist, so a
+    # criteria-less milestone and every pre-v20 close path stay valid. milestone-done is
+    # the SOLE status->done transition; archive-milestone/compact already refuse a
+    # non-done milestone, so this single gate has no back door. Refuse BEFORE any write.
+    met, total = _exit_criteria(root, slug)
+    if total > 0 and met < total:
+        _die(f"milestone_goal_unmet: milestone '{slug}' has {met}/{total} exit criteria met "
+             f"— check the remaining boxes in MILESTONE.md (the goal-gate holds the loop "
+             f"open) or propose the next tasks (add.py deltas)")
     # Fail-closed: render+persist the exit report (RETRO.md) BEFORE committing the
     # status flip, so a write failure rolls back naturally (status never commits ->
     # no done-without-retro state). The retro step is read-only on state.json.
@@ -837,6 +1135,12 @@ def cmd_milestone_done(args: argparse.Namespace) -> None:
     print(f"milestone '{slug}' -> done ({len(members)} tasks complete{tail}).")
     print(f"wrote {retro_path.relative_to(root.parent)}  (milestone exit report)")
     print("Confirm the MILESTONE.md exit criteria are checked, then archive/start the next.")
+    # fold-pressure nudge: milestone close is the natural fold point for open deltas (v11)
+    open_deltas = sum(len(v) for v in _collect_open_deltas(root).values())
+    if open_deltas:
+        noun = "delta" if open_deltas == 1 else "deltas"
+        print(f"note: {open_deltas} open {noun} to consolidate into the foundation "
+              f"— review with: add.py deltas")
 
 
 def cmd_archive_milestone(args: argparse.Namespace) -> None:
@@ -861,6 +1165,15 @@ def cmd_archive_milestone(args: argparse.Namespace) -> None:
             t = tasks[s]
             print(f"  - {s} (phase={t.get('phase')}, gate={t.get('gate')})", file=sys.stderr)
         _die("milestone_has_incomplete_tasks")
+    # pre-archive snapshot (design-for-failure): the archived record below keeps only a
+    # slug-list, so capture the full milestone + member task records to a .bak BEFORE the
+    # destructive deletes — an accidental archive stays recoverable (phase/gate/waiver/deps
+    # the record drops). Mirrors the .bak the guideline injector writes before mutating.
+    _atomic_write(
+        root / "milestones" / slug / "pre-archive-state.bak.json",
+        json.dumps({"milestone": ms, "tasks": {s: tasks[s] for s in members},
+                    "archived_at": _now()}, indent=2) + "\n",
+    )
     # a slug-list summary (never task bodies) so the active state can't regrow,
     # yet cross-milestone deps on these tasks still resolve (see _archived_task_slugs)
     state.setdefault("archived", []).append({
@@ -882,6 +1195,70 @@ def cmd_archive_milestone(args: argparse.Namespace) -> None:
     print("files on disk are untouched; see `add.py status` for the archived rollup.")
 
 
+def cmd_compact(args: argparse.Namespace) -> None:
+    """Heavy archive (step two, after `archive-milestone`): move a light-archived
+    milestone's files — MILESTONE.md + siblings + every rollup-member task dir — into
+    one recovery bundle `.add/archive/<slug>/`. Validate-all-then-move: any reject
+    leaves the tree AND state.json byte-for-byte unchanged. Compact never deletes,
+    only renames; recovery = reverse move, no state edit (state already dropped these
+    at light archive). Preserves the _archived_task_slugs invariant: `task_slugs` is
+    never touched — archived ⇒ was PASS-done keeps resolving cross-milestone deps."""
+    root = _require_root()
+    state = load_state(root)
+    slug = args.slug
+    # validate before any mutation — a reject must leave tree + state byte-for-byte unchanged
+    if slug in state.get("milestones", {}):
+        _die(f"milestone_not_archived: '{slug}' is still active — "
+             f"run `add.py archive-milestone {slug}` first (light archive is step one)")
+    entry = next((e for e in state.get("archived", []) if e.get("slug") == slug), None)
+    if entry is None:
+        _die("unknown_milestone")
+    if entry.get("compacted"):
+        _die(f"already_compacted: '{slug}' was compacted {entry['compacted']} — "
+             f"see .add/archive/{slug}/")
+    dest = root / "archive" / slug
+    if dest.exists():
+        _die(f"archive_destination_exists: .add/archive/{slug}/ exists without a "
+             "compacted stamp — resolve the collision by hand before compacting")
+    ms_dir = root / "milestones" / slug
+    members = list(entry.get("task_slugs") or [])
+    missing = [str(p.relative_to(root)) for p in
+               [ms_dir, *(root / "tasks" / t for t in members)] if not p.is_dir()]
+    if missing:
+        _die("source_files_missing: " + " · ".join(missing))
+    # deltas folded first: an `open` lesson inside the bundle would silently vanish
+    # from `add.py deltas` (_collect_open_deltas globs tasks/*/TASK.md) once moved.
+    member_set = set(members)
+    offenders = sorted({e["task"] for v in _collect_open_deltas(root).values()
+                        for e in v if e["task"] in member_set})
+    if offenders:
+        _die("open_deltas_unfolded: consolidate the open lessons first (`add.py deltas`) — "
+             "open in: " + " · ".join(offenders))
+    # every precondition passed — move (same-filesystem renames, never a delete)
+    def _files(d: Path) -> int:
+        return sum(1 for f in d.rglob("*") if f.is_file())
+    moved: list[tuple[str, int]] = []
+    (root / "archive").mkdir(exist_ok=True)
+    n = _files(ms_dir)
+    ms_dir.rename(dest)                       # the milestone dir becomes the bundle root
+    moved.append((f"milestones/{slug}/", n))
+    (dest / "tasks").mkdir(exist_ok=True)
+    for t in members:
+        src = root / "tasks" / t
+        n = _files(src)
+        src.rename(dest / "tasks" / t)
+        moved.append((f"tasks/{t}/", n))
+    # state write is the LAST step: additive stamp only — task_slugs untouched
+    entry["compacted"] = date.today().isoformat()
+    save_state(root, state)
+    total = sum(n for _, n in moved)
+    print(f"compacted milestone '{slug}' -> .add/archive/{slug}/ "
+          f"({len(members)} task dirs, {total} files moved)")
+    for path, n in moved:
+        print(f"  moved {path} ({n} files)")
+    print("recovery: reverse the moves (mv the bundle's parts back) — state needs no edit.")
+
+
 def cmd_set_milestone(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
@@ -900,6 +1277,20 @@ def cmd_set_milestone(args: argparse.Namespace) -> None:
     print(f"task '{task}' -> milestone '{new}'" if new else f"task '{task}' -> milestone (none)")
 
 
+def cmd_use(args: argparse.Namespace) -> None:
+    """Set the active task to an EXISTING task (switch focus) without scaffolding a new
+    one or hand-editing state.json. advance/gate/phase still take an explicit slug; `use`
+    just moves the default focus, closing the only gap that forced manual state edits."""
+    root = _require_root()
+    state = load_state(root)
+    slug = args.slug
+    if slug not in state.get("tasks", {}):
+        _die("unknown_task")
+    state["active_task"] = slug
+    save_state(root, state)
+    print(f"active task -> '{slug}' (phase={state['tasks'][slug]['phase']})")
+
+
 def _find_cycle(tasks: dict) -> list[str] | None:
     """Return a cycle path in the depends_on graph, or None. Ignores unknown deps."""
     WHITE, GRAY, BLACK = 0, 1, 2
@@ -1028,6 +1419,21 @@ def _colorize(s: str) -> str:
     return s
 
 
+def _project_goal(root: Path) -> str:
+    """The project GOAL — the value of the first `goal:` line in PROJECT.md, else
+    GOAL_UNSET. Read-only and fail-closed: a missing/unreadable foundation or a
+    blank value degrades to the sentinel (orientation never raises). Mirrors how
+    _milestone_doc reads the milestone goal — the foundation is the single source."""
+    f = root / "PROJECT.md"
+    try:
+        for line in f.read_text(encoding="utf-8").splitlines():
+            if line.startswith("goal:"):
+                return line.split(":", 1)[1].strip() or GOAL_UNSET
+    except OSError:
+        pass
+    return GOAL_UNSET
+
+
 def _milestone_doc(root: Path, mslug: str) -> tuple[str, str]:
     """(title, goal) from MILESTONE.md; ('(unknown)','(unknown)') if the doc is gone."""
     f = root / "milestones" / mslug / MILESTONE_FILE
@@ -1057,12 +1463,115 @@ def _exit_criteria(root: Path, mslug: str) -> tuple[int, int]:
     return met, total
 
 
+def _stage_criteria(root: Path) -> tuple[int, int]:
+    """(met, total) checkbox tally inside PROJECT.md's 'Stage goal criteria' section — the
+    PROJECT.md analog of _exit_criteria (v22): the human's stage-covered affirmation. Read-only
+    and fail-closed to (0, 0): a missing file, a missing section, or any read error never raises
+    and never fabricates a cue (so an unreadable foundation withholds graduation, design-for-failure)."""
+    try:
+        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+    except OSError:
+        return 0, 0
+    m = re.search(r"## Stage goal criteria.*?(?=\n## |\Z)", text, re.S)
+    if not m:
+        return 0, 0
+    sec = m.group(0)
+    met = len(re.findall(r"- \[x\]", sec))
+    total = met + len(re.findall(r"- \[ \]", sec))
+    return met, total
+
+
+def _all_milestones_done(state: dict) -> bool:
+    """True when the project HAS milestones and EVERY one is status=done (v22). Archived
+    milestones are absent from state['milestones'] (removed by the archive lifecycle), so they
+    do not count; a project with zero milestones is not 'covered' and returns False."""
+    ms = state.get("milestones") or {}
+    return bool(ms) and all(m.get("status") == "done" for m in ms.values())
+
+
+def _graduation_ready(root: Path, state: dict) -> tuple[bool, int, int]:
+    """(ready, met, total) for the stage-graduation cue (v22): every milestone done AND the
+    human's stage-goal-criteria all checked (total>0 and met==total). The SINGLE source the
+    text and --json status branches share, so the cue and the json signal can never disagree."""
+    met, total = _stage_criteria(root)
+    ready = _all_milestones_done(state) and total > 0 and met == total
+    return ready, met, total
+
+
+def _count_test_defs(f: Path) -> int:
+    """`def test_` occurrences in one file — the ONE counting regex (primary and
+    §4-declared fallback share it by construction). OSError -> 0, fail-closed."""
+    try:
+        return len(re.findall(r"^\s*def test_", f.read_text(encoding="utf-8"), re.M))
+    except OSError:
+        return 0
+
+
 def _tests_count(root: Path, slug: str) -> int:
     d = root / "tasks" / slug / "tests"
     if not d.is_dir():
         return 0
-    return sum(len(re.findall(r"^\s*def test_", f.read_text(encoding="utf-8"), re.M))
-               for f in d.glob("*.py"))
+    return sum(_count_test_defs(f) for f in d.glob("*.py"))
+
+
+def _confined(p: Path, rootp: Path) -> bool:
+    """True only if p resolves (symlinks followed) inside rootp; errors -> False.
+    The v2 confinement check — no read is attempted on a path that fails it."""
+    try:
+        return p.resolve().is_relative_to(rootp)
+    except OSError:
+        return False
+
+
+def _declared_tests_count(root: Path, slug: str) -> int:
+    """Count tests at the §4 'Tests live in:' declared path(s). PURE, fail-closed 0.
+    Tokens are the backticked spans on the FIRST declaring line of the raw §4 body.
+    Resolution: './…' -> task dir · contains '/' -> project root (parent of .add) ·
+    bare name -> sibling of the previous resolved token (else task dir). A directory
+    token counts the *.py files directly inside it; resolved files are deduped.
+    v2 confinement: every file read must resolve inside the project root — '..'
+    traversal, absolute tokens, and symlink escapes all contribute 0, fail-closed."""
+    body = _raw_phase_bodies(root, slug).get(4, "")
+    m = re.search(r"^\s*Tests live in:.*$", body, re.M)
+    if not m:
+        return 0
+    tdir = root / "tasks" / slug
+    rootp = root.parent.resolve()
+    files: list[Path] = []
+    prev_dir = None
+    for tok in re.findall(r"`([^`]+)`", m.group(0)):
+        tok = tok.strip()
+        if tok.startswith("./"):
+            p = tdir / tok[2:]
+        elif "/" in tok:
+            p = root.parent / tok
+        else:
+            p = (prev_dir or tdir) / tok
+        try:
+            if not _confined(p, rootp):
+                continue
+            if p.is_dir():
+                cand, prev_dir = sorted(f for f in p.glob("*.py")
+                                        if _confined(f, rootp)), p
+            elif p.is_file() and p.suffix == ".py":
+                cand, prev_dir = [p], p.parent
+            else:
+                continue
+        except OSError:
+            continue
+        files.extend(f for f in cand if f not in files)
+    return sum(_count_test_defs(f) for f in files)
+
+
+def _tests_info(root: Path, slug: str) -> tuple[int, bool]:
+    """(count, declared). The tests/ dir count ALWAYS wins when > 0; otherwise the
+    §4-declared fallback — flagged True only when it supplied a non-zero count, so
+    a true zero stays a bare, honest 0."""
+    primary = _tests_count(root, slug)
+    if primary > 0:
+        return primary, False
+    declared = _declared_tests_count(root, slug)
+    return (declared, True) if declared > 0 else (0, False)
 
 
 def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
@@ -1076,8 +1585,6 @@ def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
     text = f.read_text(encoding="utf-8")
     m7 = re.search(r"##\s*7\s*·\s*OBSERVE.*\Z", text, re.S)
     lines = (m7.group(0) if m7 else text).splitlines()
-    _delta_start = re.compile(r"\s*-\s*\[\s*(DDD|SDD|UDD|TDD|ADD)\s*·\s*(open|folded|rejected)\s*\]\s*(.+)$")
-
     # observe: the field value + continuation lines until a blank line / heading / list
     observe = "(unknown)"
     for i, ln in enumerate(lines):
@@ -1098,14 +1605,14 @@ def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
     # deltas: each "- [COMP · status] ..." plus its indented continuation lines
     deltas, i = [], 0
     while i < len(lines):
-        m = _delta_start.match(lines[i])
+        m = _DELTA_RE.match(lines[i])
         if not m:
             i += 1
             continue
         parts, j = [m.group(3).strip()], i + 1
         while j < len(lines):
             t = lines[j].strip()
-            if not t or t.startswith("#") or _delta_start.match(lines[j]):
+            if not t or t.startswith("#") or _DELTA_RE.match(lines[j]):
                 break
             parts.append(t)
             j += 1
@@ -1152,6 +1659,7 @@ def report_data(root: Path, state: dict, mslug: str) -> dict:
         observe, deltas = _task_prose(root, slug)
         phase = t.get("phase", "specify")
         gate = t.get("gate", "none")
+        n_tests, t_declared = _tests_info(root, slug)
         row = {
             "slug": slug,
             "title": t.get("title", slug),
@@ -1159,7 +1667,8 @@ def report_data(root: Path, state: dict, mslug: str) -> dict:
             "phase_index": PHASES.index(phase) if phase in PHASES else 0,
             "done": _task_done(t),
             "gate": gate,
-            "tests": _tests_count(root, slug),
+            "tests": n_tests,
+            "tests_declared": t_declared,
             "observe": observe,
             "deltas": deltas,
             "waiver": t.get("waiver"),
@@ -1185,6 +1694,9 @@ def report_data(root: Path, state: dict, mslug: str) -> dict:
         "tasks": task_rows,
         "waivers": waivers,
         "deltas": all_deltas,
+        # additive (v13-1): MILESTONE.md-planned slugs with no TASK.md yet —
+        # the plan-vs-state diff DECIDE NEXT was blind to; [] when none
+        "planned_unscaffolded": _planned_unscaffolded(root, mslug),
     }
 
 
@@ -1204,22 +1716,13 @@ def _clean_phase_body(body: str) -> str:
     return "\n".join(lines) if meaningful else "(empty)"
 
 
-def task_phases(root: Path, slug: str) -> list[dict]:
-    """The frozen per-task PHASE-DETAIL shape (v9-1): parse TASK.md §1–§7 into seven
-    blocks specify→observe. PURE — NO writes. Each entry is
-    { "phase": <name>, "n": <1..7>, "body": <cleaned text | "(empty)"> }.
-
-    Sections are matched on the NUMBER (`^##\\s*<n>\\s*·`, case/locale-proof, the phase
-    word maps n->PHASES[n-1]); a body runs from its heading to the next `## `/`---`/EOF.
-    Missing file / missing section / placeholder-only body -> "(empty)" (fail-closed).
+def _phase_spans(text: str) -> dict[int, str]:
+    """Split a TASK.md into RAW §1–§7 bodies keyed by section number — the ONE
+    canonical heading scan (`^##\\s*<n>\\s*·`, case/locale-proof); a body runs from
+    its heading to the next `## `/`---`/EOF. RAW = byte-faithful lines, no cleaning:
+    the decision-marker extractor (decide-digest) depends on byte-verbatim text.
     KNOWN LIMIT: a §body containing a line-start `## ` or bare `---` truncates early —
     today's TASK.md bodies don't (box-chars ─═, `### ` sub-heads)."""
-    names = PHASES[:7]  # specify..observe; "done" is a terminal STATE, not a section
-    f = root / "tasks" / slug / "TASK.md"
-    try:
-        text = f.read_text(encoding="utf-8")
-    except OSError:   # missing OR unreadable -> every phase fail-closed to "(empty)"
-        return [{"phase": names[n - 1], "n": n, "body": "(empty)"} for n in range(1, 8)]
     lines = text.splitlines()
     head = re.compile(r"^##\s*(\d+)\s*·")
     starts: dict[int, int] = {}
@@ -1229,21 +1732,47 @@ def task_phases(root: Path, slug: str) -> list[dict]:
             n = int(m.group(1))
             if 1 <= n <= 7 and n not in starts:
                 starts[n] = idx
-    out = []
-    for n in range(1, 8):
-        if n not in starts:
-            out.append({"phase": names[n - 1], "n": n, "body": "(empty)"})
-            continue
+    out: dict[int, str] = {}
+    for n, idx in starts.items():
         body_lines = []
-        for ln in lines[starts[n] + 1:]:
+        for ln in lines[idx + 1:]:
             if re.match(r"^##\s", ln) or re.match(r"^---\s*$", ln):
                 break
             body_lines.append(ln)
-        out.append({"phase": names[n - 1], "n": n,
-                    "body": _clean_phase_body("\n".join(body_lines))})
+        out[n] = "\n".join(body_lines)
     return out
 
 
+def _raw_phase_bodies(root: Path, slug: str) -> dict[int, str]:
+    """RAW §bodies for one task (byte-faithful, for marker extraction). PURE.
+    Missing/unreadable TASK.md -> {} (fail-closed, like task_phases)."""
+    f = root / "tasks" / slug / "TASK.md"
+    try:
+        return _phase_spans(f.read_text(encoding="utf-8"))
+    except OSError:
+        return {}
+
+
+def task_phases(root: Path, slug: str) -> list[dict]:
+    """The frozen per-task PHASE-DETAIL shape (v9-1): parse TASK.md §1–§7 into seven
+    blocks specify→observe. PURE — NO writes. Each entry is
+    { "phase": <name>, "n": <1..7>, "body": <cleaned text | "(empty)"> }.
+
+    The heading scan lives in _phase_spans (shared with the decide digest); this view
+    CLEANS each body. Missing file / missing section / placeholder-only body ->
+    "(empty)" (fail-closed)."""
+    names = PHASES[:7]  # specify..observe; "done" is a terminal STATE, not a section
+    f = root / "tasks" / slug / "TASK.md"
+    try:
+        text = f.read_text(encoding="utf-8")
+    except OSError:   # missing OR unreadable -> every phase fail-closed to "(empty)"
+        return [{"phase": names[n - 1], "n": n, "body": "(empty)"} for n in range(1, 8)]
+    spans = _phase_spans(text)
+    return [{"phase": names[n - 1], "n": n,
+             "body": _clean_phase_body(spans[n]) if n in spans else "(empty)"}
+            for n in range(1, 8)]
+
+
 def _task_title(root: Path, slug: str) -> str:
     """The task's display title from TASK.md line 1 `# TASK: <title>` (fail-soft: the
     slug if the file or the header line is missing)."""
@@ -1262,10 +1791,20 @@ def _task_title(root: Path, slug: str) -> str:
 def _detail_body(body: str, width: int) -> list[str]:
     """Indent a phase body under its block, soft-wrapping over-long physical lines on
     spaces while preserving blank lines + each line's leading indent (so scenarios and
-    contract code keep their shape). Drill-down = reading is the point, never clipped."""
+    contract code keep their shape). Fenced ``` blocks are exempt: delimiter lines and
+    everything inside an open fence emit BYTE-VERBATIM (indent + raw — no wrap, no
+    whitespace collapse, even past width) so a copied contract round-trips after
+    stripping the uniform indent; an unclosed fence runs verbatim to the §body end
+    (fail-open). Drill-down = reading is the point, never clipped."""
     indent = "   "
     out: list[str] = []
+    fenced = False
     for raw in body.split("\n"):
+        is_delim = raw.lstrip().startswith("```")
+        if fenced or is_delim:
+            fenced = fenced != is_delim   # delimiter toggles; content keeps state
+            out.append(indent + raw if raw.strip() else "")
+            continue
         if not raw.strip():
             out.append("")
             continue
@@ -1364,10 +1903,13 @@ def render_report(root: Path, state: dict, mslug: str, *,
         for r in d["tasks"]:
             slug = _clip(r["slug"], 27)
             gate = _GATE_SHORT.get(r["gate"], r["gate"])
+            tests = f"{r['tests']}†" if r.get("tests_declared") else str(r["tests"])
             L.append(f" {slug:<27} {r['phase']:<9} {gate:<4} "
-                     f"{str(r['tests']):<5} {_phase_track(r['phase'], g)}")
+                     f"{tests:<5} {_phase_track(r['phase'], g)}")
         L.append(f" legend  {g['reached']} reached  {g['current']} current  "
                  f"{g['pending']} pending   spec→…→done")
+        if any(r.get("tests_declared") for r in d["tasks"]):
+            L.append(" † counted at the §4-declared path")
     else:
         L.append(" (no tasks yet)")
     L.append("")
@@ -1385,6 +1927,256 @@ def render_report(root: Path, state: dict, mslug: str, *,
             L.extend(_wrap(x, W - 5, f"   {g['bullet']} "))
     else:
         L.append(" LEARNINGS      none")
+    L.append("")   # DECIDE NEXT footer (v13): always present, APPEND-ONLY
+    L.extend(_wrap(_decide_next_base(state, d), W - 15, " DECIDE NEXT  "))
+    if _planned_hint(d):   # own segment so the phrase never splits mid-token
+        L.extend(_wrap(_planned_hint(d).removeprefix(" — "), W - 15, " " * 14))
+    L.append(banner)
+    return "\n".join(L)
+
+
+# ---- decide digest (v13 decide-digest, frozen §3) ---------------------------
+# Decision markers: prose conventions surfaced VERBATIM. The engine EXTRACTS; it
+# never interprets, scores, or filters — add.py stays judgment-free, the human
+# signature is the gate.
+_MARKER_PREFIXES = (("⚠", "⚠"), ("- [~]", "[~]"), ("- [ ]", "[ ]"))
+_FRONT_PHASES = ("specify", "scenarios", "contract", "tests")
+
+
+def _decision_markers(body: str, section: int) -> list[dict]:
+    """Extract decision markers from a RAW §body: a line whose first non-space chars
+    are `⚠` / `- [~]` / `- [ ]`, PLUS its continuation lines (immediately following
+    non-blank lines indented deeper than the marker). text is BYTE-VERBATIM — never
+    re-wrapped, never clipped. Fail-open by design (a differently-worded item is
+    missed); the always-printed count keeps that visible."""
+    items: list[dict] = []
+    lines = body.split("\n")
+    i = 0
+    while i < len(lines):
+        ln = lines[i]
+        stripped = ln.lstrip()
+        tag = next((t for p, t in _MARKER_PREFIXES if stripped.startswith(p)), None)
+        if tag is None:
+            i += 1
+            continue
+        indent = len(ln) - len(stripped)
+        block = [ln]
+        j = i + 1
+        while j < len(lines):
+            nxt = lines[j]
+            ns = nxt.lstrip()
+            if ns and (len(nxt) - len(ns)) > indent:
+                block.append(nxt)
+                j += 1
+            else:
+                break
+        items.append({"marker": tag, "section": section, "text": "\n".join(block)})
+        i = j
+    return items
+
+
+def _contract_frozen(raw3: str) -> bool:
+    """§3's `Status:` line is the freeze signal (v12 precedent: the freeze is
+    artifact-observable; no engine flag). Missing Status -> DRAFT (fail-closed)."""
+    return any(re.match(r"\s*Status:\s*FROZEN", ln) for ln in raw3.splitlines())
+
+
+_FLAG_LABEL_RE = re.compile(r"Least-sure flag surfaced at freeze\s*:", re.I)
+_FLAG_PART_RE = re.compile(
+    r"\[(?:spec|scenario|contract|test)(?:/(?:spec|scenario|contract|test))*\]")
+_FLAG_NONE_ESCAPE_RE = re.compile(
+    r"none material\s*[—-]+\s*biggest risk\s*:\s*\S", re.I)
+
+
+def _flag_well_formed(raw3: str) -> bool:
+    """A FROZEN §3 must surface a WELL-FORMED lowest-confidence flag — the unit
+    that NAMES which part of the bundle is least certain. Well-formed := the label
+    phrase + a unit carrying >=1 [part] tag (part in spec/scenario/contract/test,
+    slash-joinable like [spec/contract]) + substantive content. A bare 'none' is
+    refused unless it takes the honest escape 'none material — biggest risk: X'.
+    why/cost stay a human-read convention, never machine keywords (evidence: the
+    lived flags use em-dash/prose, never literal because/if-wrong). HTML comments
+    (template hints) never count. PURE — fail-closed on a missing label."""
+    body = re.sub(r"<!--.*?-->", "", raw3, flags=re.S)
+    m = _FLAG_LABEL_RE.search(body)
+    if not m:
+        return False
+    unit = body[m.end():].strip()
+    if not unit:
+        return False
+    if _FLAG_NONE_ESCAPE_RE.search(unit):    # the honest-none escape — no tag needed
+        return True
+    if not _FLAG_PART_RE.search(unit):       # must name WHICH part is uncertain
+        return False
+    residue = _FLAG_PART_RE.sub("", unit).replace("⚠", "").strip(" -—·\n\t")
+    return len(residue) >= 3                  # substantive content beyond the tag(s)
+
+
+def decide_data(root: Path, state: dict, mslug: str, slug: str) -> dict:
+    """FACTS for the task-level decision-point digest (frozen shape). The decision comes
+    from STATE ONLY: recorded (gate set / observe / done) · front (specify→tests) ·
+    gate (build/verify). judgment = extracted markers, byte-verbatim. PURE."""
+    tasks = state.get("tasks") or {}
+    t = tasks.get(slug, {})
+    phase = t.get("phase", "specify")
+    gate = t.get("gate", "none")
+    if gate != "none" or phase in ("observe", "done"):
+        seam = "recorded"
+    elif phase in _FRONT_PHASES:
+        seam = "front"
+    else:
+        seam = "gate"
+    raw = _raw_phase_bodies(root, slug)
+    frozen = _contract_frozen(raw.get(3, ""))
+    if seam == "gate":   # the items closest to the gate lead: §6 first, then §1
+        judgment = _decision_markers(raw.get(6, ""), 6) + _decision_markers(raw.get(1, ""), 1)
+    elif seam == "front" and not frozen:
+        judgment = _decision_markers(raw.get(1, ""), 1) + _decision_markers(raw.get(3, ""), 3)
+    else:
+        judgment = []
+
+    members = [x for x in tasks.values() if x.get("milestone") == mslug]
+    done, total = sum(1 for x in members if _task_done(x)), len(members)
+    facts = {"phase": phase, "gate": gate,
+             "deps": [{"slug": d, "gate": tasks.get(d, {}).get("gate", "none")}
+                      for d in t.get("depends_on", [])],
+             "tests": _tests_info(root, slug)[0]}
+
+    if seam == "gate":
+        unlocks = f"gate PASS -> task done -> milestone {min(done + 1, total)}/{total}"
+        decide = "add.py gate PASS | RISK-ACCEPTED | HARD-STOP"
+    elif seam == "front" and not frozen:
+        unlocks = "freeze §3 -> the auto run takes build -> verify (autonomy: auto by default)"
+        decide = "approve -> freeze §3 (Status: FROZEN @ v1) -> auto run"
+    elif seam == "front":
+        unlocks = "none"
+        decide = "no decision pending — frozen; the run owns it. next decision point: verify gate"
+    else:
+        unlocks = "none"
+        decide = f"no decision pending — recorded gate: {gate}"
+    return {"seam": seam, "milestone": mslug, "task": slug, "phase": phase,
+            "gate": gate, "judgment": judgment, "facts": facts,
+            "unlocks": unlocks, "decide": decide}
+
+
+def render_decide(root: Path, state: dict, mslug: str, slug: str, *,
+                  width: int = _DEFAULT_WIDTH, ascii: bool = False) -> str:
+    """Text view of the decision-point digest — decisive facts FIRST: NEEDS YOUR
+    JUDGMENT (markers byte-verbatim, section-tagged) -> [front: §3 verbatim] ->
+    ENGINE FACTS -> UNLOCKS -> DECIDE. PURE — no writes; plain text (color is a
+    tty-only skin in cmd_report, like every report view)."""
+    d = decide_data(root, state, mslug, slug)
+    g = _ASCII if ascii else _UNICODE
+    banner = g["h"] * width
+    seam_label = {"gate": "VERIFY GATE", "front": "CONTRACT APPROVAL",
+                  "recorded": "RECORDED"}[d["seam"]]
+    L = [banner, f" DECIDE · {mslug or '—'} · {slug} · decision point: {seam_label}", banner]
+    if d["decide"].startswith("no decision pending"):
+        L.append(f" {d['decide']}")
+        L.append(f" GATE  {d['gate']}")
+        L.append(banner)
+        return "\n".join(L)
+    L.append(f" NEEDS YOUR JUDGMENT ({len(d['judgment'])})")
+    for item in d["judgment"]:
+        L.append(f"   [§{item['section']}]")
+        L.extend(item["text"].split("\n"))     # byte-verbatim — never wrapped/clipped
+    if d["seam"] == "front":
+        L.append("")
+        L.append(" CONTRACT (§3 verbatim)")
+        L.extend(_raw_phase_bodies(root, slug).get(3, "").split("\n"))
+        L.append(" STATUS DRAFT")
+    f = d["facts"]
+    deps_txt = " ".join(f"{x['slug']}:{x['gate']}" for x in f["deps"]) or "none"
+    L.append("")
+    L.append(f" ENGINE FACTS  phase {f['phase']} · gate {f['gate']} · "
+             f"deps {deps_txt} · tests {f['tests']}")
+    L.append(f" UNLOCKS       {d['unlocks']}")
+    L.append(f" DECIDE        {d['decide']}")
+    L.append(banner)
+    return "\n".join(L)
+
+
+def _planned_unscaffolded(root: Path, mslug: str) -> list[str]:
+    """Slugs MILESTONE.md plans (rows `- [ ] <slug> …`) that have no TASK.md yet —
+    the plan-vs-state diff. Only valid-slug first-tokens match (a template
+    placeholder like <slug> never does); file order, deduped; fail-closed []."""
+    md = root / "milestones" / mslug / "MILESTONE.md"
+    try:
+        text = md.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    out: list[str] = []
+    for sec in re.split(r"^## ", text, flags=re.M)[1:]:
+        if not sec.startswith("Tasks"):    # only the Tasks list — never exit criteria
+            continue
+        for m in re.finditer(r"^- \[[ x~]\] ([A-Za-z0-9_-]+)\b", sec, re.M):
+            slug = m.group(1)
+            if slug not in out and not (root / "tasks" / slug / "TASK.md").is_file():
+                out.append(slug)
+    return out
+
+
+def _decide_next(state: dict, d: dict) -> str:
+    """The rollup's DECIDE NEXT line (frozen precedence): HARD-STOP -> consolidate+archive
+    -> first decision-blocked task (ACTIVE task first, then state order) -> run-in-
+    progress. v2: when d carries planned_unscaffolded, the line gains a
+    plan-vs-state suffix — precedence itself stays state-only."""
+    return _decide_next_base(state, d) + _planned_hint(d)
+
+
+def _planned_hint(d: dict) -> str:
+    """The plan-vs-state suffix ('' when nothing is missing). Text renders emit it
+    as its OWN wrapped segment so the phrase never splits mid-token; the JSON
+    'decide' string carries it inline via _decide_next."""
+    planned = d.get("planned_unscaffolded") or []
+    if not planned:
+        return ""
+    return f" — {len(planned)} planned not yet scaffolded: " + " · ".join(planned)
+
+
+def _decide_next_base(state: dict, d: dict) -> str:
+    ms = d["milestone"]["slug"]
+    rows = d["tasks"]
+    if not rows:
+        return "none — no tasks yet"
+    stopped = [r for r in rows if r["gate"] == "HARD-STOP"]
+    if stopped:
+        return f"resolve HARD-STOP on {stopped[0]['slug']}"
+    s = d["summary"]
+    if s["tasks_done"] == s["tasks_total"]:
+        # tasks complete — but the milestone holds while the goal (exit criteria) is
+        # unmet (v20). Point at the feed-forward inventory the loop draws from, instead
+        # of "archive". Fires only when criteria exist; else the prompt is unchanged.
+        ec = s.get("exit_criteria") or {}
+        met, total = ec.get("met", 0), ec.get("total", 0)
+        if total > 0 and met < total:
+            return (f"goal not met ({met}/{total} exit criteria) — propose next tasks "
+                    f"from open deltas / the unscaffolded plan (add.py deltas)")
+        return f"consolidate learnings + archive-milestone {ms}"
+    active = state.get("active_task")
+    order = sorted(rows, key=lambda r: 0 if r["slug"] == active else 1)  # stable
+    for r in order:
+        if r["done"]:
+            continue
+        if r["phase"] in _FRONT_PHASES:
+            return (f"approve the contract of {r['slug']} — "
+                    f"add.py report {ms} {r['slug']} --decide")
+        if r["phase"] == "verify" and r["gate"] == "none":
+            return f"gate {r['slug']} — add.py report {ms} {r['slug']} --decide"
+    r = next(x for x in order if not x["done"])
+    return f"none — run in progress ({r['slug']} at {r['phase']})"
+
+
+def render_decide_next(root: Path, state: dict, mslug: str, *,
+                       width: int = _DEFAULT_WIDTH, ascii: bool = False) -> str:
+    """`report <ms> --decide`: ONLY the DECIDE NEXT block (no rollup table). PURE."""
+    g = _ASCII if ascii else _UNICODE
+    banner = g["h"] * width
+    d = report_data(root, state, mslug)
+    L = [banner, f" {mslug} · DECIDE NEXT", banner]
+    L.extend(_wrap(_decide_next_base(state, d), width - 4, "   "))
+    if _planned_hint(d):   # own segment so the phrase never splits mid-token
+        L.extend(_wrap(_planned_hint(d).removeprefix(" — "), width - 4, "   "))
     L.append(banner)
     return "\n".join(L)
 
@@ -1398,10 +2190,456 @@ def _write_retro(root: Path, state: dict, mslug: str) -> Path:
     trust the locale default), never mutates state.json."""
     content = render_report(root, state, mslug, width=_DEFAULT_WIDTH, ascii=False)
     path = root / "milestones" / mslug / "RETRO.md"
-    path.write_text(content, encoding="utf-8")
+    _atomic_write(path, content)   # honor the module's atomic-write contract (no half-write)
     return path
 
 
+_COMPETENCY_ORDER = ("DDD", "SDD", "UDD", "TDD", "ADD")
+_DELTA_STATUSES = ("open", "folded", "rejected")
+
+# Canonical delta grammar — the single compiled source for the enumerated
+# competency · status shape. Leading \s* is PERMISSIVE so _task_prose can feed
+# un-stripped lines directly; callers that pre-strip their input
+# (e.g. _collect_open_deltas, _lint_task_deltas) match the same way (\s*
+# matches zero). Anchored at line-start via re.match.
+_DELTA_RE = re.compile(
+    r"\s*-\s*\[\s*(DDD|SDD|UDD|TDD|ADD)\s*·\s*(open|folded|rejected)\s*\]\s*(.+)$"
+)
+_EVIDENCE_RE = re.compile(r"^(.*?)\s*\(evidence:\s*(.*?)\)\s*$")
+
+# Broad structural tag detector: finds ANY "- [tok · tok]" line (valid OR malformed).
+# A line with a `· ` bracket separator is a delta-attempt. Does NOT enumerate
+# competencies or statuses — a different abstraction from _DELTA_RE (no DRY violation).
+_TAG_BROAD_RE = re.compile(r"^\s*-\s*\[\s*([^\]·]+?)\s*·\s*([^\]·]+?)\s*\]\s*(.*)$")
+
+
+def _lint_task_deltas(root: Path, slug: str) -> tuple[bool, str] | None:
+    """Lint all open delta entries in a task's '### Competency deltas' block.
+
+    Returns:
+        None                    — no delta-attempts found; no check emitted.
+        (True, "")              — all open entries pass.
+        (False, "<code> -> <tag line>") — first failing entry with its failure code.
+
+    Contract rules (frozen §3, v1):
+    - SKIP HTML-comment lines and blank lines (they are never tag lines).
+    - Group lines into ENTRIES: a broad tag line starts an entry; following lines
+      until next tag / blank / end-of-block are its continuation.
+    - A line without a '· ' separator inside brackets (e.g. '- [x]') is NOT a tag.
+    - For each entry, skip folded/rejected (open-only — history not retrofitted).
+    - Validate the remaining (open) entries: COMP in _COMPETENCY_ORDER,
+      status in _DELTA_STATUSES, and '(evidence:' present SOMEWHERE in the unit.
+    - Fail-closed: an unparseable attempt FAILS (never silently passes).
+    """
+    task_md = root / "tasks" / slug / "TASK.md"
+    if not task_md.exists():
+        return None
+    try:
+        text = task_md.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    # Locate the "### Competency deltas" block.
+    block_match = re.search(r"###\s*Competency deltas\s*\n(.*?)(?=\n##|\Z)", text, re.S)
+    if not block_match:
+        return None
+
+    block = block_match.group(1)
+    raw_lines = block.splitlines()
+
+    # First pass: collect entries (tag line + continuations).
+    # HTML-comment lines are skipped entirely (invisible to the guard).
+    # Blank lines terminate the current entry, but are not tags themselves.
+    entries: list[tuple[str, list[str]]] = []  # (tag_line, [tag_line, *continuations])
+    current: list[str] | None = None
+    for raw_line in raw_lines:
+        stripped = raw_line.strip()
+        # Skip HTML-comment lines.
+        if stripped.startswith("<!--"):
+            continue
+        # Blank line terminates the current entry.
+        if not stripped:
+            current = None
+            continue
+        # Broad tag detection: any "- [tok · tok]" line starts a new entry.
+        m = _TAG_BROAD_RE.match(raw_line)
+        if m:
+            current = [stripped]
+            entries.append((stripped, current))
+        elif current is not None:
+            # Continuation line of the current entry.
+            current.append(stripped)
+        # else: non-blank, non-comment, non-tag line with no prior entry — ignore.
+
+    if not entries:
+        return None  # no delta-attempts → no check emitted
+
+    # Second pass: validate each entry.
+    for tag_line, unit_lines in entries:
+        m = _TAG_BROAD_RE.match(tag_line)
+        if not m:
+            # Should not happen, but fail-closed.
+            return False, f"malformed_delta -> {tag_line}"
+        raw_comp = m.group(1).strip()
+        raw_status = m.group(2).strip()
+
+        # Step 1: skip historical entries (folded/rejected) — open-only enforcement.
+        # MUST happen before competency/status validation per §3: "history not retrofitted".
+        if raw_status in ("folded", "rejected"):
+            continue
+
+        # Step 2: use _DELTA_RE (the canonical grammar, single source of truth) to test
+        # whether the tag line is a fully-valid delta shape. If it matches, check evidence
+        # only. If it fails, classify the failure via the raw tokens (never a parallel grammar).
+        unit_text = " ".join(unit_lines)
+        if _DELTA_RE.match(tag_line):
+            # Valid comp + status + non-empty tail — check evidence in the joined unit.
+            if "(evidence:" not in unit_text:
+                return False, f"no_evidence -> {tag_line}"
+        else:
+            # Classify why _DELTA_RE rejected it (open entries only — folded/rejected skipped).
+            if raw_comp not in _COMPETENCY_ORDER:
+                return False, f"unknown_competency -> {tag_line}"
+            if raw_status not in _DELTA_STATUSES:
+                return False, f"unknown_status -> {tag_line}"
+            # Comp and status are valid but the line still failed _DELTA_RE (e.g. empty tail).
+            return False, f"malformed_delta -> {tag_line}"
+
+    return True, ""
+
+
+def _collect_open_deltas(root: Path) -> dict[str, list[dict]]:
+    """Scan every .add/tasks/*/TASK.md for open lessons learned.
+
+    Returns a dict keyed by competency in canonical order; each value is a list
+    of {task, text, evidence} dicts. READ-ONLY — never mutates any file."""
+    by_comp: dict[str, list[dict]] = {c: [] for c in _COMPETENCY_ORDER}
+    tasks_dir = root / "tasks"
+    if not tasks_dir.is_dir():
+        return by_comp
+    for task_md in sorted(tasks_dir.glob("*/TASK.md")):
+        slug = task_md.parent.name
+        try:
+            text = task_md.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        # Locate the "### Competency deltas" block (may appear anywhere in the file).
+        block_match = re.search(r"###\s*Competency deltas\s*\n(.*?)(?=\n##|\Z)", text, re.S)
+        if not block_match:
+            continue
+        block = block_match.group(1)
+        # Group lines into entries (tag line + continuations) so a multi-line delta —
+        # whose learning wraps and whose (evidence: …) may land on a later line — is read
+        # in FULL, not truncated to its first line. A tag line starts an entry; a line
+        # that does not begin a new "- " list item continues it; a blank/comment or a
+        # new "- " item ends it (a trailing malformed item can't pollute a delta's text).
+        entries: list[list[str]] = []
+        current: list[str] | None = None
+        for line in block.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("<!--"):
+                current = None
+                continue
+            if _DELTA_RE.match(stripped):
+                current = [stripped]
+                entries.append(current)
+            elif current is not None and not stripped.startswith("-"):
+                current.append(stripped)  # genuine wrap of the current learning
+            else:
+                current = None             # a new / malformed list item ends the run
+        for unit in entries:
+            m = _DELTA_RE.match(unit[0])
+            comp, status = m.group(1), m.group(2)
+            if status != "open":
+                continue
+            # Join the tag line's tail with any continuation lines, then split evidence.
+            tail = " ".join([m.group(3).strip(), *unit[1:]]).strip()
+            em = _EVIDENCE_RE.match(tail)
+            if em:
+                delta_text, evidence = em.group(1).strip(), em.group(2).strip()
+            else:
+                delta_text, evidence = tail, ""
+            by_comp[comp].append({"task": slug, "text": delta_text, "evidence": evidence})
+    return by_comp
+
+
+_AUDIT_STAMP_RE = re.compile(r"Status:\s*FROZEN @ v\d+\s*[—-]+\s*approved by\s+\S+")
+_AUDIT_OUTCOME_RE = re.compile(r"^Outcome:\s*(PASS|RISK-ACCEPTED|HARD-STOP)\b", re.M)
+_AUDIT_SECURITY_RE = re.compile(
+    r"^\s*- \[[ x~]\] no exposed secrets.*(?:\n(?!\s*- \[|#).*)*", re.M)
+_AUDIT_REVIEWED_RE = re.compile(r"^Reviewed by:(.*)$", re.M)
+
+
+def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
+    """The gate-audit core: verify that human decision points left WELL-FORMED records.
+    Judgment-free — checks record SHAPE (a named human at the freeze, exactly one
+    gate outcome, prose ≡ state, a marked security note never auto-reviewed),
+    never re-decides an outcome. Scope: active tasks done/observe or gated; open
+    fronts skipped. PURE — reads only. Honest limit: shape, not engagement — a
+    forged name passes; CI wiring makes forgery explicit and attributable."""
+    tasks = state.get("tasks") or {}
+    checked, findings = 0, []
+
+    def f(slug: str, code: str, detail: str) -> None:
+        findings.append({"task": slug, "code": code, "detail": detail})
+
+    for slug in sorted(tasks):
+        t = tasks[slug]
+        phase, gate = t.get("phase", "specify"), t.get("gate", "none")
+        if phase not in ("done", "observe") and gate == "none":
+            continue   # the front is still open — nothing recorded to audit
+        checked += 1
+        raw = _raw_phase_bodies(root, slug)
+        s3, s6 = raw.get(3, ""), raw.get(6, "")
+        if not _AUDIT_STAMP_RE.search(s3):
+            f(slug, "unstamped_freeze",
+              "§3 lacks 'Status: FROZEN @ vN — approved by <name>'")
+        # verified-marker discriminator (task unflagged-freeze): enforce the
+        # lowest-confidence flag ONLY on records that crossed the guard (flag_verified).
+        # A marked record whose flag was deleted/corrupted post-freeze is
+        # tampering; unmarked predecessors are skipped — the board is never
+        # retro-redded.
+        if t.get("flag_verified") and not _flag_well_formed(s3):
+            f(slug, "unflagged_freeze",
+              "flag_verified record lost its well-formed "
+              "'Least-sure flag surfaced at freeze:' unit")
+        outcomes = _AUDIT_OUTCOME_RE.findall(s6)
+        if len(outcomes) != 1:
+            f(slug, "malformed_gate_record",
+              f"{len(outcomes)} Outcome lines in §6 (need exactly 1)")
+        elif gate != "none" and outcomes[0] != gate:
+            f(slug, "gate_record_mismatch",
+              f"§6 records {outcomes[0]} but state.json records {gate}")
+        sec = _AUDIT_SECURITY_RE.search(s6)
+        marked = bool(sec and ("NOTE" in sec.group(0) or "⚠" in sec.group(0)))
+        rev = _AUDIT_REVIEWED_RE.search(s6)
+        if marked and rev and "auto-gate" in rev.group(1):
+            f(slug, "unescalated_security_note",
+              "security-line note (NOTE/⚠) with an auto-gate reviewer")
+        # F7 unguarded_high_risk_auto (task high-risk-signal, v14): a declared
+        # high-risk record must show a guarded dial AND a human at the gate —
+        # catches post-gate header tampering and auto-resolved high-risk gates.
+        hdr = _task_header(root, slug)
+        if _RISK_HIGH_RE.search(hdr):
+            if not _AUTONOMY_CONSERVATIVE_RE.search(hdr):
+                f(slug, "unguarded_high_risk_auto",
+                  "risk: high declared but autonomy is not 'conservative'")
+            elif rev and "auto-gate" in rev.group(1):
+                f(slug, "unguarded_high_risk_auto",
+                  "risk: high task whose GATE RECORD reviewer is the auto-gate")
+        if outcomes == ["RISK-ACCEPTED"]:
+            if marked:
+                f(slug, "risk_accepted_security",
+                  "a waiver on a marked security item is never allowed")
+            if not all(re.search(rf"{k}:\s*(?!<)\S", s6)
+                       for k in ("owner", "ticket", "expires")):
+                f(slug, "waiver_incomplete",
+                  "RISK-ACCEPTED needs owner · ticket · expires")
+    return checked, findings
+
+
+def cmd_audit(args: argparse.Namespace) -> None:
+    """Read-only: audit recorded human decision points for well-formedness. Exit 0 clean,
+    exit 1 with findings — the enforcement gate CI consumes (audit-ci). Writes
+    NOTHING; every other command is byte-identical."""
+    root = _require_root()
+    checked, findings = _audit_findings(root, load_state(root))
+    if getattr(args, "json", False):
+        print(json.dumps({"checked": checked, "findings": findings},
+                         ensure_ascii=False, indent=2))
+    else:
+        if findings:
+            for x in findings:
+                print(f"audit: {x['code']} {x['task']} — {x['detail']}")
+        else:
+            print(f"audit: clean ({checked} tasks checked)")
+    if findings:
+        sys.exit(1)
+
+
+def _retro_carried(path: Path) -> int:
+    """Parse the 'LEARNINGS (N carried)' count from a RETRO.md; absent/unreadable -> 0.
+    READ-ONLY (the graduation harvest's carried-delta facet for the consolidated tier)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return 0
+    m = re.search(r"LEARNINGS \((\d+) carried\)", text)
+    return int(m.group(1)) if m else 0
+
+
+def graduation_data(root: Path, state: dict) -> dict:
+    """The single source of FACTS for the graduation harvest — PURE, NO writes (mirrors
+    report_data). Both the `graduation-report` text dashboard and `--json` render from this
+    one dict, so the human view and the machine view can never disagree.
+
+    GATHER, never JUDGE: every value is a RECORD the human verifies by looking; there is no
+    readiness/score/ranking field by construction (would_be_judging is structurally impossible).
+    Two tiers: LIVE = in-state (state + on-disk TASK.md); CONSOLIDATED = compacted milestones,
+    a RETRO record only. A missing/unreadable source is SKIPPED, never a crash (fail-closed)."""
+    tasks = state.get("tasks") or {}
+    milestones = state.get("milestones") or {}
+    archived = state.get("archived") or []
+
+    # a — open deltas by competency (reuse the project-wide harvester; compacted folded out)
+    by_comp = _collect_open_deltas(root)
+    open_deltas = {"total": sum(len(v) for v in by_comp.values()),
+                   "by_competency": {c: v for c, v in by_comp.items() if v}}
+
+    # b — open RISK-ACCEPTED waivers, soonest expiry first (missing/unparseable expiry sorts LAST)
+    waivers = []
+    for slug, t in tasks.items():
+        if t.get("gate") == "RISK-ACCEPTED" and t.get("waiver"):
+            w = t["waiver"]
+            waivers.append({"slug": slug, "owner": w.get("owner", "?"),
+                            "ticket": w.get("ticket", "?"), "expires": w.get("expires", "?")})
+
+    def _exp_key(wv):
+        try:
+            return (0, date.fromisoformat(wv["expires"]).isoformat())
+        except (ValueError, TypeError):
+            return (1, "")          # unparseable/missing -> after every real date
+    waivers.sort(key=_exp_key)
+
+    # c — RETRO records: LIVE under milestones/, CONSOLIDATED under archive/ (the compacted backbone)
+    retros = []
+    for sub_dir, tier in ((root / "milestones", "live"), (root / "archive", "consolidated")):
+        if sub_dir.is_dir():
+            for retro in sorted(sub_dir.glob("*/RETRO.md")):
+                if retro.is_file():     # a directory at the path is not a ledger (fail-closed)
+                    retros.append({"milestone": retro.parent.name,
+                                   "path": str(retro.relative_to(root)),
+                                   "carried_deltas": _retro_carried(retro), "tier": tier})
+
+    # d-i — residue gate records: the residue-class facet (RISK-ACCEPTED shares the waivers[] record)
+    residue_gates = [{"slug": s, "gate": t.get("gate")} for s, t in tasks.items()
+                     if t.get("gate") in ("RISK-ACCEPTED", "HARD-STOP")]
+
+    # d-ii — §6 disclosed residue: in-state tasks' '- [⚠]' VERIFY list items (the pinned rule)
+    # e   — coverage-gaps proxy: in-state §7 Watch still the '<error rate' placeholder head
+    residue_disclosed, coverage_gaps = [], []
+    for slug in tasks:
+        try:
+            text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+        except OSError:
+            continue                 # unreadable TASK.md -> skip this task's prose records
+        m = re.search(r"##\s*6\b.*?(?=\n##\s*\d|\Z)", text, re.S)   # the VERIFY section only
+        for line in (m.group(0) if m else "").splitlines():
+            st = line.strip()
+            if st.startswith("- [⚠]"):
+                residue_disclosed.append({"slug": slug, "line": st[len("- [⚠]"):].strip()})
+        for line in text.splitlines():
+            if line.startswith("Watch") and "<error rate" in line:  # unfilled <…> template head
+                coverage_gaps.append({"slug": slug})
+                break
+
+    return {
+        "open_deltas": open_deltas,
+        "waivers": waivers,
+        "retros": retros,
+        "residue_gates": residue_gates,
+        "residue_disclosed": residue_disclosed,
+        "coverage_gaps": coverage_gaps,
+        "summary": {
+            "open_deltas": open_deltas["total"], "waivers": len(waivers), "retros": len(retros),
+            "residue_gates": len(residue_gates), "residue_disclosed": len(residue_disclosed),
+            "coverage_gaps": len(coverage_gaps),
+            "milestones_live": len(milestones), "milestones_consolidated": len(archived),
+        },
+    }
+
+
+def cmd_graduation_report(args: argparse.Namespace) -> None:
+    """Read-only: GATHER the MVP loop's evidence into five labeled record-sets for the
+    graduate.md interview. text (default) or --json (the frozen JSON facts interface). Exit 0 ALWAYS —
+    a gather, not a gate; the ONLY non-zero exit is no_project. Judges nothing. NO writes."""
+    root = find_root()
+    if root is None:                 # frozen contract: fail-closed with a no_project signal
+        _die("no_project: no .add/ project found. Run `add.py init` first.")
+    state = load_state(root)
+    d = graduation_data(root, state)
+
+    if getattr(args, "json", False):
+        print(json.dumps(d, ensure_ascii=False, indent=2))
+        return
+
+    s = d["summary"]
+    L = ["GRADUATION REPORT — MVP-loop evidence (gather, not judge)", ""]
+    L.append(f"Open deltas ({s['open_deltas']}) — unfolded lessons by competency:")
+    for comp, entries in d["open_deltas"]["by_competency"].items():
+        for e in entries:
+            L.append(f"  - [{comp}] {e['text']}  [{e['task']}]")
+    L.append("")
+    L.append(f"Waivers ({s['waivers']}) — open RISK-ACCEPTED, soonest expiry first:")
+    for w in d["waivers"]:
+        L.append(f"  - {w['slug']}: {w['owner']} · {w['ticket']} · expires {w['expires']}")
+    L.append("")
+    _live_retros = sum(1 for r in d["retros"] if r["tier"] == "live")
+    _cons_retros = s["retros"] - _live_retros
+    L.append(f"RETRO records ({s['retros']}: {_live_retros} live · {_cons_retros} consolidated) — "
+             f"milestones: {s['milestones_live']} live · "
+             f"{s['milestones_consolidated']} represented by RETRO record:")
+    for r in d["retros"]:
+        L.append(f"  - {r['milestone']} [{r['tier']}]: {r['path']} ({r['carried_deltas']} carried)")
+    L.append("")
+    L.append(f"Verify residue — gate records ({s['residue_gates']}, RISK-ACCEPTED/HARD-STOP):")
+    for g in d["residue_gates"]:
+        L.append(f"  - {g['slug']}: {g['gate']}")
+    L.append(f"Verify residue — disclosed §6 lines ({s['residue_disclosed']}):")
+    for r in d["residue_disclosed"]:
+        L.append(f"  - {r['slug']}: {r['line']}")
+    L.append("")
+    L.append(f"Coverage gaps ({s['coverage_gaps']}) — PROXY (monitor not declared; §7 Watch unfilled):")
+    for c in d["coverage_gaps"]:
+        L.append(f"  - {c['slug']}")
+    print("\n".join(L))
+
+
+def cmd_deltas(args: argparse.Namespace) -> None:
+    """Read-only: report all open lessons learned grouped by competency.
+
+    Scans every .add/tasks/*/TASK.md '### Competency deltas' block for lines
+    matching the delta grammar; shows only `open` entries in canonical competency
+    order (DDD·SDD·UDD·TDD·ADD). --json emits one JSON object. Exit 0 ALWAYS.
+    Writes NOTHING."""
+    root = _require_root()
+    by_comp = _collect_open_deltas(root)
+    total = sum(len(v) for v in by_comp.values())
+
+    if getattr(args, "json", False):
+        payload: dict = {
+            "total": total,
+            "by_competency": {c: v for c, v in by_comp.items() if v},
+        }
+        print(json.dumps(payload, ensure_ascii=False))
+        return
+
+    if total == 0:
+        print("no open deltas.")
+        return
+
+    print(f"open lessons learned ({total} total):")
+    for comp in _COMPETENCY_ORDER:
+        entries = by_comp[comp]
+        if not entries:
+            continue
+        print(f"  {comp} ({len(entries)}):")
+        for e in entries:
+            print(f"    - {e['text']}  [{e['task']}]")
+
+
+def cmd_project(args: argparse.Namespace) -> None:
+    """Read-only: print .add/PROJECT.md (the read-first foundation) in one command.
+
+    Fail-closed: a missing foundation dies with a clear stderr message + a non-zero
+    exit, never a silent empty print. Writes NOTHING."""
+    root = _require_root()
+    foundation = root / "PROJECT.md"
+    if not foundation.exists():
+        _die("missing foundation: .add/PROJECT.md (run `add.py init` to scaffold it)")
+    print(foundation.read_text(encoding="utf-8"), end="")
+
+
 def cmd_report(args: argparse.Namespace) -> None:
     """Read-only: capture a milestone's raw data (--json) or render the text
     dashboard (color on a tty, ASCII when the terminal can't do Unicode, --plain
@@ -1433,6 +2671,12 @@ def cmd_report(args: argparse.Namespace) -> None:
                 _die(f"unknown_milestone: task '{name}' is not attached to a milestone")
         else:
             _die(f"unknown_milestone: '{name}' is not a milestone")
+    elif getattr(args, "decide", False):          # bare --decide -> the ACTIVE TASK
+        slug = state.get("active_task")
+        if not slug or slug not in tasks:
+            _die("no_active_task — name one: add.py report <milestone> <task> --decide")
+        drill_task = slug
+        mslug = tasks[slug].get("milestone") or ""
     else:                                         # no positional -> active milestone
         mslug = state.get("active_milestone")
         if not mslug:
@@ -1441,6 +2685,32 @@ def cmd_report(args: argparse.Namespace) -> None:
         if mslug not in milestones:
             _die(f"unknown_milestone: '{mslug}' is not a milestone")
 
+    if getattr(args, "decide", False):
+        # Decision-seam digest (v13): task -> seam digest; milestone -> DECIDE NEXT
+        # block only. PURE, like every report path.
+        if getattr(args, "json", False):
+            if drill_task:
+                payload = decide_data(root, state, mslug, drill_task)
+            else:   # milestone altitude: same frozen key set, task null
+                d = report_data(root, state, mslug)
+                payload = {"seam": "milestone", "milestone": mslug, "task": None,
+                           "phase": "", "gate": "none", "judgment": [],
+                           "facts": {"phase": "", "gate": "none", "deps": [], "tests": 0},
+                           "unlocks": "", "decide": _decide_next(state, d)}
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return
+        plain = getattr(args, "plain", False)
+        interactive = sys.stdout.isatty() and not plain
+        width = _term_width() if interactive else _DEFAULT_WIDTH
+        use_ascii = plain or _use_ascii()
+        out = (render_decide(root, state, mslug, drill_task, width=width, ascii=use_ascii)
+               if drill_task else
+               render_decide_next(root, state, mslug, width=width, ascii=use_ascii))
+        if not plain and _color_enabled():
+            out = _colorize(out)
+        print(out)
+        return
+
     if getattr(args, "json", False):
         # POLYMORPHIC by path: drill -> task_phases list; rollup -> report_data dict.
         payload = task_phases(root, drill_task) if drill_task \
@@ -1468,8 +2738,19 @@ def build_parser() -> argparse.ArgumentParser:
     pi.add_argument("--name", default=None, help="project name (default: dir name)")
     pi.add_argument("--stage", default="prototype", choices=STAGES)
     pi.add_argument("--force", action="store_true", help="reset state.json if present")
+    pi.add_argument("--await-lock", dest="await_lock", action="store_true",
+                    help="seed an unlocked setup; gates new-task/advance/gate until `add.py lock`")
     pi.set_defaults(func=cmd_init)
 
+    pl = sub.add_parser("lock",
+                        help="freeze the autonomous setup (the human baseline approval) and open the build")
+    pl.add_argument("--by", default=None, help="who is locking (default: current OS user)")
+    pl.add_argument("--layers", default=None,
+                    help="comma-separated lock layers (default: foundation,scope,contract)")
+    pl.add_argument("--force", action="store_true", help="re-lock an already-locked project")
+    pl.add_argument("--json", action="store_true", help="emit one JSON object instead of text")
+    pl.set_defaults(func=cmd_lock)
+
     pn = sub.add_parser("new-task", help="scaffold a new task (TASK.md + tests/ + src/)")
     pn.add_argument("slug")
     pn.add_argument("--title", default=None)
@@ -1500,11 +2781,21 @@ def build_parser() -> argparse.ArgumentParser:
     psm.add_argument("milestone", help="milestone slug, or 'none' to detach")
     psm.set_defaults(func=cmd_set_milestone)
 
+    pu = sub.add_parser("use", help="set the active task to an existing one (switch focus)")
+    pu.add_argument("slug")
+    pu.set_defaults(func=cmd_use)
+
     pam = sub.add_parser("archive-milestone",
                          help="collapse a done milestone out of active state (files stay on disk)")
     pam.add_argument("slug")
     pam.set_defaults(func=cmd_archive_milestone)
 
+    pco = sub.add_parser("compact",
+                         help="heavy archive: move an archived milestone's files into "
+                              ".add/archive/<slug>/ (recoverable reverse move)")
+    pco.add_argument("slug")
+    pco.set_defaults(func=cmd_compact)
+
     pp = sub.add_parser("phase", help="set a task's phase explicitly")
     pp.add_argument("phase", choices=PHASES)
     pp.add_argument("slug", nargs="?", default=None)
@@ -1522,8 +2813,18 @@ def build_parser() -> argparse.ArgumentParser:
     pg.add_argument("--expires", help="RISK-ACCEPTED waiver: expiry date")
     pg.set_defaults(func=cmd_gate)
 
+    pr = sub.add_parser("reopen", help="return a done task to an earlier phase with a recorded reason")
+    pr.add_argument("slug", nargs="?", default=None)
+    # --to / --reason are validated in-body (not argparse choices) so the named reject
+    # codes fire (reopen_target_invalid / reopen_reason_required), not a bare exit-2.
+    pr.add_argument("--to", default=None, help="target phase (specify..observe)")
+    pr.add_argument("--reason", default="", help="why the task is reopened (required, non-empty)")
+    pr.set_defaults(func=cmd_reopen)
+
     ps = sub.add_parser("stage", help="set the project stage")
     ps.add_argument("stage", choices=STAGES)
+    ps.add_argument("--force", action="store_true",
+                    help="override the →production roadmap guard (stage_no_roadmap)")
     ps.set_defaults(func=cmd_stage)
 
     pst = sub.add_parser("status", help="print where the project is (resume point)")
@@ -1557,8 +2858,33 @@ def build_parser() -> argparse.ArgumentParser:
                           "drill -> task_phases list of 7 phase dicts)")
     prp.add_argument("--plain", action="store_true",
                      help="ASCII, no color, fixed width (pipe / CI / screen-reader safe)")
+    prp.add_argument("--decide", action="store_true",
+                     help="decision-point digest: what needs the human's judgment NOW "
+                          "(task -> decision digest; milestone -> DECIDE NEXT only; "
+                          "bare -> the active task)")
     prp.set_defaults(func=cmd_report)
 
+    pdt = sub.add_parser("deltas",
+                         help="read-only report: open lessons learned grouped by competency")
+    pdt.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    pdt.set_defaults(func=cmd_deltas)
+
+    pgr = sub.add_parser("graduation-report",
+                         help="read-only: gather the MVP loop's evidence (deltas · waivers · RETROs · "
+                              "residue · coverage gaps) for a graduation interview — gathers, never judges")
+    pgr.add_argument("--json", action="store_true", help="emit the frozen JSON facts interface")
+    pgr.add_argument("--plain", action="store_true", help="ASCII/pipe-safe text (output is plain by default)")
+    pgr.set_defaults(func=cmd_graduation_report)
+
+    pau = sub.add_parser("audit",
+                         help="read-only: verify recorded human decision points left well-formed records "
+                              "(exit 1 on findings — the CI enforcement gate)")
+    pau.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    pau.set_defaults(func=cmd_audit)
+
+    ppj = sub.add_parser("project", help="print .add/PROJECT.md (the read-first foundation)")
+    ppj.set_defaults(func=cmd_project)
+
     return p