@pilotspace/add 1.0.0 → 1.1.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
@@ -162,7 +163,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 +199,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 +222,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 flow: INTAKE sizes a request into a milestone; each task runs the\n"
+        "**one-approval front** — 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"
-        "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"
+        "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 +321,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 survivors. 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 +375,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 +404,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 +511,10 @@ 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")
     state["tasks"][slug]["phase"] = nxt
     state["tasks"][slug]["updated"] = _now()
     _sync_task_marker(root, slug, nxt)
@@ -460,10 +522,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 +563,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 dial 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,6 +592,36 @@ def cmd_gate(args: argparse.Namespace) -> None:
         print("HARD-STOP recorded: return to BUILD; nothing ships on a failing/security gate.")
 
 
+def cmd_lock(args: argparse.Namespace) -> None:
+    """The human lock-down: freeze the autonomously-drafted setup in ONE atomic write.
+
+    Setup-altitude 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 cmd_stage(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
@@ -531,8 +654,11 @@ def cmd_status(args: argparse.Namespace) -> None:
     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)')}")
     # 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)")
@@ -560,13 +686,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 (least-sure 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 +706,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 — fold 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 (least-sure 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 +727,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 +772,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)
@@ -626,6 +793,11 @@ def cmd_guide(args: argparse.Namespace) -> None:
     print(f"active : {slug}  (phase: {phase})")
     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 +870,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():
@@ -837,6 +1016,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 competency {noun} to fold into the foundation "
+              f"— review with: add.py deltas")
 
 
 def cmd_archive_milestone(args: argparse.Namespace) -> None:
@@ -861,6 +1046,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({
@@ -900,6 +1094,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
@@ -1057,12 +1265,80 @@ def _exit_criteria(root: Path, mslug: str) -> tuple[int, int]:
     return 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 +1352,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 +1372,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 +1426,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 +1434,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 +1461,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 +1483,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 +1499,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 +1558,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 +1670,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 +1694,217 @@ 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())
+
+
+def decide_data(root: Path, state: dict, mslug: str, slug: str) -> dict:
+    """FACTS for the task-level decision-seam digest (frozen shape). The seam 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 seam: 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-seam 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} · seam: {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 -> fold+archive
+    -> first seam-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"]:
+        return f"fold 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 +1918,309 @@ 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 competency deltas.
+
+    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 seams 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>'")
+        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 seams for well-formedness. Exit 0 clean,
+    exit 1 with findings — the enforcement seam 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 cmd_deltas(args: argparse.Namespace) -> None:
+    """Read-only: report all open competency deltas 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 competency deltas ({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 +2252,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 +2266,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 +2319,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 lock-down) 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,6 +2362,10 @@ 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")
@@ -1557,8 +2423,26 @@ 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-seam digest: what needs the human's judgment NOW "
+                          "(task -> seam 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 competency deltas grouped by competency")
+    pdt.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    pdt.set_defaults(func=cmd_deltas)
+
+    pau = sub.add_parser("audit",
+                         help="read-only: verify human seams left well-formed records "
+                              "(exit 1 on findings — the CI enforcement seam)")
+    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