@pilotspace/add 1.10.0 → 1.12.0

package/tooling/add.py

@@ -30,274 +30,102 @@ try:                       # component-aware-add registry parse (Python 3.11+ st
 except ModuleNotFoundError:   # < 3.11: the registry is unsupported → degrade to opt-out
     tomllib = None
 
-# --- constants ---------------------------------------------------------------
-
-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"
-# release-altitude: the read-only cue `status` shows when ≥1 closed milestone is
-# unreleased. The 5th scope level (release.md). `{n}` is filled at print time; the
-# wording matches SKILL.md's "Beyond the bundle" cross-ref byte-for-byte.
-RELEASABLE_CUE = "releasable: {n} milestone(s) closed since last release"
-# the append-only release ledger lives at the PROJECT ROOT (the dir containing .add/),
-# a sibling of CHANGELOG.md — NOT inside .add/. The ledger IS the attribution source:
-# a milestone is "released" iff its slug appears on a `milestones:` row.
-RELEASES_FILE = "RELEASES.md"
-PHASES = ("ground", "specify", "scenarios", "contract", "tests", "build", "verify", "observe", "done")
-GATES = ("none", "PASS", "RISK-ACCEPTED", "HARD-STOP")
-# heal-then-escalate (verify-integrity): the bounded self-heal loop cap. A CONFIRMED cheat
-# (mechanical tripwire divergence, or an agent-reported semantic refute-read finding) returns
-# the task to BUILD for an honest redo; after HEAL_CAP such attempts the next confirmed cheat
-# forces a HARD-STOP escalation to the human. MONOTONIC — attempts never auto-resets (a gamed
-# green is never auto-passed; the loop is never unbounded).
-HEAL_CAP = 3
+# --- constants (moved to add_engine/constants.py — engine-modularization) ----
+from add_engine.constants import *  # noqa: F401,F403  (public constants via __all__)
+from add_engine.constants import (  # the _-prefixed names (import * skips them)
+    _GITIGNORE_BODY, _GUIDE_BEGIN, _GUIDE_END,
+    _RULE_REF_LINE, _FALLBACK_TASK, _FALLBACK_TASK_FAST,
+    _DEFAULT_WIDTH,
+    _DELTA_RE, _EVIDENCE_RE, _SPEC_DELTA_RE,   # shared delta regexes (taskdoc + deltas-web lint)
+    _AUTONOMY_LEVELS,   # shared (autonomy resolvers + _AUTONOMY_ORDER/cmd_autonomy)
+)
 
+# --- terminal-render primitives (moved to add_engine/render.py) -------------
+from add_engine.render import (
+    _bar, _phase_track, _use_ascii, _color_enabled, _term_width, _colorize, _clip, _wrap,
+)
 
-def _phase_index(name: str) -> int:
-    """Ordinal of a phase in PHASES; used to enforce forward-skip rules."""
-    return PHASES.index(name)
+# --- milestone-doc readers (moved to add_engine/milestones.py) --------------
+from add_engine.milestones import (
+    _has_production_roadmap, _project_goal, _milestone_doc, _exit_criteria,
+    _exit_criteria_cited, _stage_criteria, _all_milestones_done,
+)
 
-# `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 = {
-    "ground":    ("gather the real codebase the task touches — files, symbols, signatures, conventions, and the anchor points the contract will cite; defer to PROJECT.md/CONVENTIONS.md and gather only the task delta",
-                  "02-the-flow.md"),
-    "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"),
-    "contract":  ("freeze the shape — signature, fields, error codes; names match the glossary",
-                  "05-step-3-contract.md"),
-    "tests":     ("write one failing test per scenario; run them RED for the right reason",
-                  "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 + 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"),
-    "done":      ("this task is done — pick the next feature",
-                  "02-the-flow.md"),
-}
-# Phase -> who owns it, for the `--json` autonomy signal. An autonomous harness may run a
-# phase only when owner=="ai" (stop is false); every other phase is a checkpoint. The map
-# follows the book's who-does-what table (Verify is "human only"); `tests`/`build`/`observe`
-# are AI-led. A phase missing here is `unmapped_phase` (fail closed) — never defaulted.
-PHASE_OWNER = {
-    "ground": "ai",
-    "specify": "human", "scenarios": "human", "contract": "seam",
-    "tests": "ai", "build": "ai", "verify": "human", "observe": "ai", "done": "human",
-}
-SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md")
-
-# Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
-# never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
-# milestones/, archive/). These are working state, not records: scope-snapshot.json
-# is the tests->build touch baseline the verify scope-gate reads from disk (the
-# durable scope declaration is the state.json anchor); pre-archive-state.bak.json is
-# archive-milestone's pre-delete recovery net — needed on disk, never in history;
-# .update-cache.json is the update-nudge's once-a-day registry throttle. All stay on
-# disk; git-ignoring them is hygiene, never deletion.
-_GITIGNORE_BODY = """\
-# ADD engine transient artifacts — local working state, never committed.
-# (Scaffolded by `add.py init`; edit freely — init never clobbers an existing copy.)
-scope-snapshot.json
-pre-archive-state.bak.json
-.update-cache.json
-"""
+# --- component/federation subsystem (moved to add_engine/components.py) ------
+from add_engine.components import (
+    _confined, _components, _cite_region, _contracts, _federation,
+    _contract_snapshot, _in_scope,
+)
 
-# Guideline-injection targets + version-stable markers. NEVER change these marker
-# strings: a re-run finds the old block by exact match, so changing them would
-# orphan every block written by a prior version (see TASK guideline-inject).
-GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md")
-_GUIDE_BEGIN = "<!-- ADD:BEGIN — managed by `add.py sync-guidelines`; do not edit inside -->"
-_GUIDE_END = "<!-- ADD:END -->"
-
-# Rule-file mode (ccsk-style projects): instead of inlining the block into CLAUDE.md,
-# write it to a dedicated rule file under .claude/rules/ and leave a one-line reference
-# in CLAUDE.md's Workflows section. .claude/rules/ is a CLAUDE-only convention, so this
-# mode only ever relocates CLAUDE.md — AGENTS.md/.clinerules keep the inline block.
-RULES_FILE_REL = Path(".claude") / "rules" / "add-workflows.md"
-# Headings (most→least specific) a project may already use to group rule/workflow links.
-# Match is case-insensitive on the heading TEXT, at any `#` level.
-WORKFLOW_HEADINGS = ("Rules & Workflows", "Workflows", "Rules")
-_RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md"
-
-# Minimal embedded fallback so the tool still works if templates/ is missing
-# (circuit breaker: never hard-fail just because a template file was deleted).
-_FALLBACK_TASK = """# TASK: {title}
-
-slug: {slug} · created: {date} · stage: {stage}
-autonomy: auto
-phase: ground
-
-## 0 · GROUND
-Touches (files · symbols · signatures):
-Honors (patterns / conventions):
-Anchors the contract cites:
-
-## 1 · SPECIFY
-Feature:
-Framings weighed:
-Must:
-Reject:
-After:
-Assumptions — lowest-confidence first:
-  ⚠ <most likely wrong> — lowest confidence because <why>; if wrong: <cost>
-
-## 2 · SCENARIOS
-## 3 · CONTRACT
-Status: DRAFT
-## 4 · TESTS
-## 5 · BUILD
-## 6 · VERIFY
-### GATE RECORD
-Outcome:
-## 7 · OBSERVE
-### Spec delta
-### Competency deltas
-"""
+# --- update-nudge version helpers (moved to add_engine/version.py) ----------
+from add_engine.version import (
+    _read_json_safe, _version_gt, _fetch_latest_version,
+)
 
+# --- changelog/RELEASES render helpers (moved to add_engine/release.py) -----
+from add_engine.release import (
+    _releases_path, _closed_milestones, _key_decisions_for,
+    _build_in_flight, _render_changelog_block, _render_releases_row,
+)
 
-# Fast-lane fallback: the minimal TASK.md variant (sections {0,1,3,4,5,6}; §2 + §7 dropped).
-# Mirrors templates/TASK.fast.md.tmpl's section set (circuit-breaker parity); a deleted
-# templates/ never hard-fails the fast lane. Keeps the trust floor: §3 freeze-flag + Status,
-# §6 GATE RECORD/Outcome, §0 Anchors, §4 red-before-build, §5 Scope.
-_FALLBACK_TASK_FAST = """# TASK: {title}
-
-slug: {slug} · created: {date} · stage: {stage}
-autonomy: auto
-phase: ground
-fast: true
-
-## 0 · GROUND
-Touches (files · symbols):
-Anchors the contract cites:
-
-## 1 · SPECIFY
-Feature:
-Must:
-Reject:
-Accept:
-Assumptions: ⚠ <most likely wrong> — why; if wrong: <cost>
-
-## 3 · CONTRACT
-Least-sure flag surfaced at freeze:
-Status: DRAFT
-
-## 4 · TESTS
-Plan:
-Tests live in: `./tests/` · MUST run red before Build.
-
-## 5 · BUILD
-Scope (may touch): `./src/`
-
-## 6 · VERIFY
-Build expectations (from §1 Accept + §3 CONTRACT):
-### GATE RECORD
-Outcome:
-Reviewed by:
-"""
+# --- TASK.md structural readers (moved to add_engine/taskdoc.py) ------------
+from add_engine.taskdoc import (
+    _task_header, _count_test_defs, _primary_test_files, _tests_count,
+    _declared_test_files, _declared_tests_count, _tests_info, _task_prose,
+    _phase_spans, _raw_phase_bodies, _spec_delta_entries,
+)
 
+# --- autonomy-level resolvers (moved to add_engine/autonomy.py) -------------
+from add_engine.autonomy import (
+    _autonomy_level, _effective_autonomy, _project_autonomy, _project_autonomy_token,
+)
 
-# --- low-level IO (designed for failure: atomic, no silent clobber) ----------
 
-def _now() -> str:
-    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+def _phase_index(name: str) -> int:
+    """Ordinal of a phase in PHASES; used to enforce forward-skip rules."""
+    return PHASES.index(name)
 
+# --- low-level IO (moved to add_engine/io_state.py — engine-modularization) -
+from add_engine.io_state import (  # re-exported as module globals: callers use bare
+    _now, _atomic_write, _atomic_write_bytes, _atomic_write_many,  # names so patches
+    find_root, _require_root, _migrate_state, _state_text_or_die,  # on add.<name>
+    _die,                                                          # still resolve;
+    _CONFLICT_MARKER_RE,                                            # conflict-marker re
+    _load_state_for_json,                                          # --json state loader
+    _md5_text, _md5_file,                                          # md5 hashing helpers
+)
 
-def _atomic_write(path: Path, text: str) -> None:
-    """Write via a temp file in the same dir, then atomically replace.
 
-    Avoids a half-written file if the process dies mid-write.
-    """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            fh.write(text)
-        os.replace(tmp, path)
-    finally:
-        if os.path.exists(tmp):
-            os.unlink(tmp)
-
-
-def _atomic_write_bytes(path: Path, data: bytes) -> None:
-    """Binary sibling of `_atomic_write` — lands `data` UNCHANGED (no newline translation), so a
-    byte-for-byte copy stays exact. Same temp-then-replace crash-safety."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+# --- active milestone/task accessors (moved to add_engine/accessors.py) -------
+from add_engine.accessors import (
+    _active_milestone, _active_task, _set_active_milestone,
+    _set_active_task, _activate_milestone, _deactivate_milestone,
+)
+
+# --- state load/save (KEPT in add.py: write-path pinned by add._atomic_write tests) -
+
+def load_state(root: Path) -> dict:
+    """Load + parse state.json, failing CLOSED. A git-conflicted file dies with a merge-specific
+    'state_conflicted'; any other corrupt/unreadable file dies with a clean 'state_invalid'
+    message (never a raw traceback), so every command that loads state degrades gracefully
+    (design-for-failure). The parsed state is forward-migrated to the multi-active schema."""
     try:
-        with os.fdopen(fd, "wb") as fh:
-            fh.write(data)
-        os.replace(tmp, path)
-    finally:
-        if os.path.exists(tmp):
-            os.unlink(tmp)
-
-
-def _atomic_write_many(writes: list[tuple[Path, str]]) -> None:
-    """True all-or-nothing commit across N files — design-for-failure for a multi-file write.
-
-    Phase 1 STAGES every (path, text) to a sibling `.tmp`, flushing + fsync-ing each, so the
-    realistic IO failures (disk full, permission denied) surface HERE, before any target changes —
-    and on any stage failure every staged temp is removed, so NOTHING is committed. Phase 2 then
-    COMMITS each file by renaming any existing target ASIDE to a sibling `.bak`, then `os.replace`-ing
-    the staged `.tmp` into place. If ANY commit rename raises, every file already committed is rolled
-    back IN REVERSE (remove the landed new file, rename its `.bak` back, or leave it absent) and the
-    original error re-raised — so the whole set is all-or-nothing: either every file holds its new
-    text, or every file holds its prior content. Restoring is an atomic rename of an already-written
-    `.bak` (no content held in memory, no re-write), the cheapest recovery under failing IO. Leftover
-    `.tmp`/`.bak` siblings are removed on every exit path.
-    """
-    staged: list[tuple[str, Path]] = []
-    committed: list[list] = []                    # [path, bak_or_None, new_landed] per committed file
+        return _migrate_state(json.loads(_state_text_or_die(root)))
+    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 save_state(root: Path, state: dict) -> None:
+    state["updated"] = _now()
     try:
-        for path, text in writes:                 # phase 1: stage every temp (fsync'd before any commit)
-            path.parent.mkdir(parents=True, exist_ok=True)
-            fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
-            staged.append((tmp, path))            # track BEFORE write so a write/fsync failure still cleans it
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                fh.write(text)
-                fh.flush()
-                os.fsync(fh.fileno())
-        try:
-            for tmp, path in staged:              # phase 2: commit via rename-aside
-                bak = None
-                existed = path.exists()
-                if existed:
-                    fd2, bak = tempfile.mkstemp(dir=str(path.parent), suffix=".bak")
-                    os.close(fd2)
-                committed.append([path, bak, False])   # track .bak NOW so cleanup never leaks it
-                if existed:
-                    os.replace(path, bak)         # move the existing target aside
-                os.replace(tmp, path)             # move the new file in
-                committed[-1][2] = True
-        except OSError:
-            for path, bak, landed in reversed(committed):   # roll back, newest-first
-                try:
-                    if landed and path.exists():
-                        os.unlink(path)           # drop the new file we put in
-                    if bak is not None and not path.exists():
-                        os.replace(bak, path)     # restore the prior target (atomic rename)
-                except OSError:
-                    pass                          # best-effort restore under already-failing IO
-            raise
-    finally:
-        for tmp, _ in staged:                     # leftover .tmp (failed/aborted stage) never persists
-            if os.path.exists(tmp):
-                os.unlink(tmp)
-        for path, bak, landed in committed:       # leftover .bak (success, or orphaned post-rollback)
-            if bak is not None and os.path.exists(bak):
-                os.unlink(bak)
+        _atomic_write(root / STATE_FILE, json.dumps(state, indent=2) + "\n")
+    except OSError as e:
+        # Fail CLOSED like load_state: a named, recoverable error — never a raw traceback. The
+        # atomic temp+replace leaves the prior state.json byte-unchanged, so it is safe to retry.
+        _die(f"state_write_failed: could not write {root / STATE_FILE} "
+             f"({e.__class__.__name__}) — the prior state.json is intact; "
+             "free disk / fix permissions and re-run")
 
 
 def _templates_dir() -> Path:
@@ -322,221 +150,37 @@ def _render_template(name: str, **subs: str) -> str:
         text = text.replace("{{" + key + "}}", val)
     return text
 
+# --- state/markdown predicates (moved to add_engine/predicates.py) -----------
+from add_engine.predicates import (
+    _phase_owner, _setup_locked, _milestone_confirmed, _section_unfilled,
+    _task_done,
+)
 
-# --- state -------------------------------------------------------------------
-
-def find_root(start: Path | None = None) -> Path | None:
-    """Walk up from cwd to find a .add/ project root."""
-    cur = (start or Path.cwd()).resolve()
-    for d in (cur, *cur.parents):
-        if (d / ROOT_DIRNAME / STATE_FILE).exists():
-            return d / ROOT_DIRNAME
-    return None
-
-
-def _require_root() -> Path:
-    root = find_root()
-    if root is None:
-        _die("no .add/ project found. Run `add.py init` first.")
-    return root
-
-
-def _migrate_state(state: dict) -> dict:
-    """Forward-migrate a single-active state to the multi-active schema (team-collaboration
-    foundation). PURE · idempotent · TOTAL · never raises · no I/O.
-
-    A state lacking the `active_milestones` key gains it — DERIVED from the scalar
-    `active_milestone` (grandfather-by-missing-key, mirroring `_setup_locked`): None -> [],
-    "x" -> ["x"]. A per-milestone active-task map `active_tasks` is added; the old global
-    `active_task` is placed under its owning active milestone only when it genuinely belongs
-    there, else it stays as the top-level scalar fallback (orphan rule, FROZEN decision (a)).
-    The scalar `active_milestone` / `active_task` keys are KEPT as the N<=1 mirror so the
-    not-yet-routed readers keep working. An already-migrated state (key present) is returned
-    unchanged — never re-derived, never clobbered. Corrupt parsing stays the loader's job.
-
-    PURE in the observable sense: the caller's dict is NEVER mutated — a state that needs
-    migrating is upgraded on a fresh top-level copy (nested objects are shared but only read)."""
-    if not isinstance(state, dict) or "active_milestones" in state:
-        return state
-    migrated = dict(state)
-    active_ms = migrated.get("active_milestone")
-    migrated["active_milestones"] = [] if active_ms is None else [active_ms]
-    active_task = migrated.get("active_task")
-    tasks = migrated.get("tasks") or {}
-    owns = (active_ms is not None and active_task is not None
-            and isinstance(tasks.get(active_task), dict)
-            and tasks[active_task].get("milestone") == active_ms)
-    migrated["active_tasks"] = {active_ms: active_task} if owns else {}
-    return migrated
-
-
-# --- active milestone/task accessor seam (multi-active foundation) -----------
-#
-# Every engine call site reads & writes the active milestone(s)/task through these
-# four helpers, so multi-active SEMANTICS can land in one place later. Today they
-# preserve single-active behavior exactly: reads return the scalar mirror, writes
-# keep the scalar AND the new active_milestones/active_tasks structures in sync.
-
-def _active_milestone(state: dict) -> str | None:
-    """The primary active milestone — the N<=1 scalar mirror (== active_milestones[0])."""
-    return state.get("active_milestone")
-
-
-def _active_task(state: dict, milestone: str | None = None) -> str | None:
-    """The active task: per-milestone when `milestone` is given (partial-state -> None),
-    else the global/primary scalar active task. Total — never raises."""
-    if milestone is None:
-        return state.get("active_task")
-    return (state.get("active_tasks") or {}).get(milestone)
-
-
-def _set_active_milestone(state: dict, slug: str | None) -> None:
-    """Set the primary active milestone, keeping `active_milestones` consistent (N<=1 sync)."""
-    state["active_milestone"] = slug
-    state["active_milestones"] = [] if slug is None else [slug]
-
-
-def _set_active_task(state: dict, slug: str | None, milestone: str | None = None) -> None:
-    """Set the active task, keeping the scalar mirror AND the per-milestone map in sync.
-    With no owning active milestone the active task is scalar-only (the migration's orphan
-    rule); clearing (slug is None) pops the milestone's entry."""
-    state["active_task"] = slug
-    ms = milestone if milestone is not None else _active_milestone(state)
-    tasks_map = state.setdefault("active_tasks", {})
-    if ms is None:
-        return
-    if slug is None:
-        tasks_map.pop(ms, None)
-    else:
-        tasks_map[ms] = slug
-
-
-def _activate_milestone(state: dict, slug: str) -> None:
-    """Add a milestone to the active SET (idempotent) and make it the primary focus,
-    syncing the scalar active_task to that milestone's entry. Does NOT remove other members
-    (this is how a user reaches N>=2 active milestones)."""
-    ms_list = state.setdefault("active_milestones", [])
-    if slug not in ms_list:
-        ms_list.append(slug)
-    state["active_milestone"] = slug
-    state["active_task"] = (state.get("active_tasks") or {}).get(slug)
-
-
-def _deactivate_milestone(state: dict, slug: str) -> None:
-    """Remove a milestone from the active SET, pop its active-task entry, and (if it was the
-    primary) repoint the primary to the most-recent remaining member (or None when empty)."""
-    ms_list = state.setdefault("active_milestones", [])
-    if slug in ms_list:
-        ms_list.remove(slug)
-    (state.setdefault("active_tasks", {})).pop(slug, None)
-    if state.get("active_milestone") == slug:
-        new = ms_list[-1] if ms_list else None
-        state["active_milestone"] = new
-        state["active_task"] = (state.get("active_tasks") or {}).get(new) if new else None
-
-
-def _git_config(key: str) -> str | None:
-    """Read one `git config --get <key>`, STRICTLY fail-soft: the engine's FIRST git call,
-    so it never raises, never hangs, never shells. Returns the trimmed value, or None when
-    git is absent / errors / times out / the value is empty."""
-    if shutil.which("git") is None:
-        return None
-    try:
-        out = subprocess.run(
-            ["git", "config", "--get", key],
-            capture_output=True, text=True, timeout=2,
-        ).stdout.strip()
-    except (OSError, subprocess.SubprocessError, ValueError):
-        # OSError: git vanished between which() and run() / spawn error · SubprocessError:
-        # TimeoutExpired · ValueError: a non-UTF-8 config value (latin-1 legacy name) makes
-        # text=True decoding raise UnicodeDecodeError (a ValueError) — all fail soft to None.
-        return None
-    return out or None
-
-
-def _os_user() -> str:
-    """The guaranteed non-empty OS floor. getpass.getuser() reads LOGNAME/USER/... then
-    falls back to the passwd database — but in a bare container (no env var AND no passwd
-    entry) CPython raises KeyError (OSError only on 3.13+). Catch broadly and return a
-    sentinel so _whoami stays TOTAL: it always yields a non-empty name, never crashes."""
-    try:
-        return getpass.getuser() or "unknown"
-    except (KeyError, OSError):
-        return "unknown"
-
-
-def _whoami(state: dict) -> dict:
-    """Resolve the current git-native ACTOR -> {name, email, source}. Priority:
-    (1) an `actor_override` (whoami --set) with a non-blank name -> source 'override';
-    (2) `git config user.name`/`user.email` -> source 'git';
-    (3) the OS user (_os_user) -> source 'os', the guaranteed non-empty floor.
-    Total: always returns a dict with a non-empty name; `email` may be None."""
-    ov = state.get("actor_override")
-    if ov and (ov.get("name") or "").strip():
-        return {"name": ov["name"], "email": ov.get("email"), "source": "override"}
-    name = _git_config("user.name")
-    if name:
-        return {"name": name, "email": _git_config("user.email"), "source": "git"}
-    return {"name": _os_user(), "email": None, "source": "os"}
-
-
-def _actor_stamp(state: dict) -> dict:
-    """The SINGLE source of the structured-actor stamp every engine-WRITTEN human action
-    records — lock · gate · milestone-done · release (user-identity actor-stamping). It IS
-    `_whoami(state)`: a TOTAL {name,email,source} (always a non-empty name), so a stamp can
-    never fail or block a write. Descriptive only — no command's decision reads it."""
-    return _whoami(state)
-
-
-def _render_actor_line(state: dict) -> str:
-    """Render the actor stamp as one human-readable line: name, an optional angle-bracketed
-    email, then the source in parens — used on the RELEASES.md row (no state.json write)."""
-    a = _actor_stamp(state)
-    email = f" <{a['email']}>" if a.get("email") else ""
-    return f"{a['name']}{email} ({a['source']})"
-
-
-def _parse_actor_arg(s: str) -> dict:
-    """Parse an `assign --owner`/`--assignee` value into a {name, email, source: "assigned"}
-    actor (ownership-assignment). "Name <email>" -> both; a bare "Name" -> email None. TOTAL:
-    a malformed value (no closing bracket) never raises — the whole stripped string is the name.
-    `source` is "assigned" — a human typed this name (not git-resolved nor an ADD override)."""
-    m = re.match(r"^\s*(.*?)\s*<([^>]*)>\s*$", s)
-    if m:
-        return {"name": m.group(1), "email": m.group(2) or None, "source": "assigned"}
-    return {"name": s.strip(), "email": None, "source": "assigned"}
-
-
-def _actor_matches(rec_actor: dict | None, me: dict) -> bool:
-    """Does a recorded owner/assignee actor identify the SAME person as `me` (multi-active-UX)?
-    Email-first (the stabler key): when BOTH carry a non-empty email, emails decide; otherwise
-    fall back to name-equality. Both comparisons are stripped + case-insensitive. TOTAL — a None,
-    non-dict, or blank-name record returns False (an unowned/garbage slot is no one's)."""
-    if not isinstance(rec_actor, dict):
-        return False
-    rec_name = (rec_actor.get("name") or "").strip()
-    if not rec_name:
-        return False
-    rec_email = (rec_actor.get("email") or "").strip()
-    me_email = (me.get("email") or "").strip()
-    if rec_email and me_email:
-        return rec_email.lower() == me_email.lower()
-    return rec_name.lower() == (me.get("name") or "").strip().lower()
+# --- git-native identity/actor seam (moved to add_engine/identity.py) --------
+from add_engine import identity            # qualified calls: identity._whoami(...)
+from add_engine.identity import (          # re-exported for `add.<name>` attr compat
+    _git_config, _os_user, _whoami, _actor_stamp,
+    _render_actor_line, _parse_actor_arg, _actor_matches,
+)
 
 
-def _my_work(state: dict, me: dict) -> list[dict]:
-    """The "my work" lens (multi-active-UX): across ALL active milestones, the NOT-done tasks
-    whose owner OR assignee is `me`. Returns ordered rows {slug, milestone, phase, role} with
-    role in {owner, assignee, both}, sorted by active-milestone order then slug. PURE · no I/O."""
+def _my_work(state: dict, me: dict, scope_all: bool = False) -> list[dict]:
+    """The "my work" lens (multi-active-UX): the NOT-done tasks whose owner OR assignee is `me`.
+    By default the lens is the active SET; `scope_all=True` (mine-all-lens) widens it to EVERY
+    milestone plus loose (milestone-less) tasks. Returns ordered rows {slug, milestone, phase,
+    role} with role in {owner, assignee, both}, sorted by active-milestone order then slug
+    (non-active/loose sort after the active block, then by slug). PURE · no I/O."""
     active = list(state.get("active_milestones") or [])
     active_set = set(active)
     tasks = state.get("tasks") if isinstance(state.get("tasks"), dict) else {}
     rows: list[dict] = []
     for slug, t in tasks.items():
-        if not isinstance(t, dict) or t.get("milestone") not in active_set or _task_done(t):
+        if not isinstance(t, dict) or _task_done(t):
             continue
-        owns = _actor_matches(t.get("owner"), me)
-        assigned = _actor_matches(t.get("assignee"), me)
+        if not scope_all and t.get("milestone") not in active_set:
+            continue
+        owns = identity._actor_matches(t.get("owner"), me)
+        assigned = identity._actor_matches(t.get("assignee"), me)
         if not (owns or assigned):
             continue
         role = "both" if owns and assigned else ("owner" if owns else "assignee")
@@ -550,106 +194,6 @@ def _my_work(state: dict, me: dict) -> list[dict]:
 # A git conflict marker BEGINS a line with 7 of `<`, `=`, or `>` (`(?m)^…`). An unresolved
 # merge writes these into state.json, making it invalid JSON; the line-anchor keeps a
 # legitimate value (always on an INDENTED JSON line) from false-tripping the guard.
-_CONFLICT_MARKER_RE = re.compile(r"(?m)^(<{7}|={7}|>{7})")
-
-
-def _state_text_or_die(root: Path) -> str:
-    """Read state.json's raw text, failing CLOSED with a merge-SPECIFIC `state_conflicted`
-    message when it carries git conflict markers (an unresolved merge — the major's #1 failure
-    mode). A genuine read OSError is NOT swallowed: it propagates to the caller, which maps it
-    to its own existing code (state_invalid / no_state). The guard only READS — never writes."""
-    text = (root / STATE_FILE).read_text(encoding="utf-8")
-    if _CONFLICT_MARKER_RE.search(text):
-        _die(f"state_conflicted: {root / STATE_FILE} has unresolved git merge markers "
-             f"(<<<<<<< / ======= / >>>>>>>) — resolve them (or "
-             f"`git checkout --ours/--theirs {STATE_FILE}`), then run `add.py doctor` to verify")
-    return text
-
-
-def load_state(root: Path) -> dict:
-    """Load + parse state.json, failing CLOSED. A git-conflicted file dies with a merge-specific
-    'state_conflicted'; any other corrupt/unreadable file dies with a clean 'state_invalid'
-    message (never a raw traceback), so every command that loads state degrades gracefully
-    (design-for-failure). The parsed state is forward-migrated to the multi-active schema."""
-    try:
-        return _migrate_state(json.loads(_state_text_or_die(root)))
-    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]:
-    """Fail-closed state load for `--json` paths: a missing project or unparseable
-    state.json -> `no_state` on stderr + exit 1, with EMPTY stdout (never a partial
-    JSON object a harness might parse). Built from State only — reads no docs/ chapter.
-    The parsed state is forward-migrated to the multi-active schema before it is returned."""
-    root = find_root()
-    if root is None:
-        _die("no_state")
-    try:
-        return root, _migrate_state(json.loads(_state_text_or_die(root)))
-    except (json.JSONDecodeError, OSError):
-        _die("no_state")
-
-
-def _phase_owner(phase: str) -> str:
-    """Map a phase to its owner (human|seam|ai); `unmapped_phase` if absent (fail closed)."""
-    owner = PHASE_OWNER.get(phase)
-    if owner is None:
-        _die("unmapped_phase")
-    return owner
-
-
-def save_state(root: Path, state: dict) -> None:
-    state["updated"] = _now()
-    _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 _milestone_confirmed(state: dict, mslug: str) -> bool:
-    """True when milestone `mslug` is confirmed — i.e. the new-task gate is OPEN.
-
-    Mirrors `_setup_locked` one level down. A milestone record with NO "confirmed" key is
-    GRANDFATHERED-confirmed: every milestone created WITHOUT `--await-confirm` (and every
-    pre-existing one) is never gated. Opt-in: `new-milestone --await-confirm` seeds confirmed:false,
-    so the gate is active in exactly one case: the record is present AND confirmed is False. An
-    unknown milestone is treated as confirmed here (existence is cmd_new_task's separate check)."""
-    m = (state.get("milestones") or {}).get(mslug)
-    if not isinstance(m, dict) or "confirmed" not in m:
-        return True
-    return m["confirmed"] is True
-
-
-def _section_unfilled(md_text: str, header: str) -> bool:
-    """True iff the `header` section is PRESENT but UNFILLED — empty (no real bullet) or
-    still a `<…>` template placeholder. ABSENT section -> False (grandfathered legacy);
-    a filled section (>=1 real bullet, no `<…>`) -> False. Pure predicate — the shared
-    placeholder test the fill gates use (contract-fill at confirm; build-expectations at build)."""
-    body, in_sec, present = [], False, False
-    for ln in md_text.splitlines():
-        if ln.startswith(header):
-            in_sec, present = True, True
-            continue
-        if in_sec:
-            if ln.startswith("#"):          # ANY next header (## or ###) ends our section
-                break
-            if ln.lstrip().startswith(">"):  # skip blockquote GUIDANCE — it is not content
-                continue
-            body.append(ln)
-    if not present:
-        return False                        # absent -> grandfather
-    text = "\n".join(body).strip()
-    if not text:
-        return True                         # present but empty
-    return bool(re.search(r"<[^>\n]+>", text))   # a <…> placeholder remains
 
 
 def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None:
@@ -668,7 +212,7 @@ def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None
         return                                   # unreadable -> no-op (never blocks the gate)
     if "### GATE RECORD" not in text:
         return                                   # nothing to mirror into
-    actor = _actor_stamp(state)
+    actor = identity._actor_stamp(state)
     today = date.today().isoformat()
     # each rule matches ONLY a line still carrying a `<…>` placeholder -> grandfather a resolved line.
     rules = [
@@ -695,251 +239,11 @@ def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None
         _atomic_write(f, new)
 
 
-def _die(msg: str, code: int = 1) -> None:
-    print(f"add: error: {msg}", file=sys.stderr)
-    raise SystemExit(code)
-
-
-# --- guideline injection (dynamic-by-reference; designed for failure) --------
-#
-# Inject one stable, marker-delimited ADD block into the project root's AGENTS.md
-# and CLAUDE.md. The block is DYNAMIC-BY-REFERENCE: it tells the agent to run
-# `add.py status` and read PROJECT.md — it never embeds live state (slug, phase,
-# gate). Auto-updated context files measurably hurt (ETH-Zurich: ~3% lower success,
-# 20%+ more cost), so the stable pointer is the whole point.
-
-def _guideline_block() -> str:
-    """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. 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. 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"
-        "**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}"
-    )
-
-
-def _inject_block(path: Path) -> str:
-    """Write the ADD block into `path`. Returns created|updated|unchanged.
-
-    - unchanged: on-disk block already matches -> no write, no .bak (idempotent).
-    - updated:   existing content changes -> back up the original to <path>.bak first.
-    - created:   file did not exist -> write the block, no .bak.
-    User content outside the markers is always preserved.
-    """
-    block = _guideline_block()
-    if path.exists():
-        current = path.read_text(encoding="utf-8")
-        begin = current.find(_GUIDE_BEGIN)
-        if begin != -1:
-            end = current.find(_GUIDE_END, begin)
-            if end != -1:                      # replace only the marked region
-                end += len(_GUIDE_END)
-                new = current[:begin] + block + current[end:]
-            else:                              # begin without end: corrupt — append fresh
-                print(f"add: warning: {path.name}: found an ADD:BEGIN with no ADD:END "
-                      "— appending a fresh block; review the result", file=sys.stderr)
-                new = current.rstrip("\n") + "\n\n" + block + "\n"
-        else:                                  # no block yet — append, keep user content
-            new = current.rstrip("\n") + "\n\n" + block + "\n"
-        if new == current:
-            return "unchanged"
-        _atomic_write(Path(str(path) + ".bak"), current)   # rollback path before mutate
-        _atomic_write(path, new)
-        return "updated"
-    _atomic_write(path, block + "\n")
-    return "created"
-
-
-def _rule_file_mode(project_root: Path, flag: bool = False) -> bool:
-    """True when the ADD block should live in .claude/rules/add-workflows.md (referenced
-    from CLAUDE.md) instead of inline. Re-derived from disk EACH phase — no persisted
-    state — so an explicit `--rule-file` at install carries into init via the rule file it
-    leaves behind. Three triggers: the explicit flag, a ccsk project (.ccsk/ sibling to
-    .claude/), or a rule file already written by a prior run. Pure + fail-soft."""
-    if flag:
-        return True
-    try:
-        if (project_root / ".ccsk").is_dir():
-            return True
-        if (project_root / RULES_FILE_REL).exists():
-            return True
-    except OSError:
-        pass
-    return False
-
-
-def _strip_inline_block(text: str) -> str:
-    """Remove an inline ADD:BEGIN..ADD:END region (migration to rule-file mode), collapsing
-    the blank-line gap it leaves behind. An unterminated BEGIN (no END) is left as-is rather
-    than eating the rest of the file (design-for-failure)."""
-    begin = text.find(_GUIDE_BEGIN)
-    if begin == -1:
-        return text
-    end = text.find(_GUIDE_END, begin)
-    if end == -1:
-        return text
-    end += len(_GUIDE_END)
-    head = text[:begin].rstrip("\n")
-    tail = text[end:].lstrip("\n")
-    if head and tail:
-        return head + "\n\n" + tail
-    return head or tail
-
-
-def _insert_rule_reference(text: str) -> str:
-    """Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a
-    fresh '## Workflows' section when none is found. Caller guarantees the bullet is absent."""
-    lines = text.split("\n")
-    heading_idx = -1
-    for i, line in enumerate(lines):
-        m = re.match(r"^(#{1,6})\s+(.*?)\s*$", line)
-        if m and any(m.group(2).strip().lower() == h.lower() for h in WORKFLOW_HEADINGS):
-            heading_idx = i
-            break
-    if heading_idx == -1:                       # no section — append a fresh one
-        body = text.rstrip("\n")
-        sep = "\n\n" if body else ""
-        return f"{body}{sep}## Workflows\n\n{_RULE_REF_LINE}\n"
-    level = len(re.match(r"^(#{1,6})", lines[heading_idx]).group(1))
-    end = len(lines)                            # section ends at next same/higher heading or EOF
-    for j in range(heading_idx + 1, len(lines)):
-        m = re.match(r"^(#{1,6})\s+", lines[j])
-        if m and len(m.group(1)) <= level:
-            end = j
-            break
-    insert_at = heading_idx + 1                 # after the last non-blank line in the section
-    for j in range(heading_idx + 1, end):
-        if lines[j].strip():
-            insert_at = j + 1
-    lines.insert(insert_at, _RULE_REF_LINE)
-    return "\n".join(lines)
-
-
-def _ensure_claude_reference(claude_md: Path) -> str:
-    """Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating
-    any prior inline ADD block out. Returns created|updated|unchanged.
-
-    - Strips a prior inline ADD:BEGIN..END block (rule-file mode supersedes inline).
-    - If a reference to add-workflows.md already exists -> no bullet change.
-    - Else inserts the bullet into the first matching section, or appends '## Workflows'.
-    .bak on change; idempotent. User content outside the touched region is preserved.
-    """
-    existed = claude_md.exists()
-    current = claude_md.read_text(encoding="utf-8") if existed else ""
-    new = _strip_inline_block(current)
-    if "add-workflows.md" not in new:
-        new = _insert_rule_reference(new)
-    if not new.endswith("\n"):
-        new += "\n"
-    if new == current:
-        return "unchanged"
-    if existed:
-        _atomic_write(Path(str(claude_md) + ".bak"), current)   # rollback path before mutate
-    _atomic_write(claude_md, new)
-    return "updated" if existed else "created"
-
-
-def _inject_guidelines(project_root: Path, rule_file: bool = False) -> list[tuple[str, str]]:
-    """Inject the block into each guideline file under `project_root`.
-
-    Symlink-dedup: targets resolving (os.path.realpath) to the same inode are
-    written once, against the REAL file (never replacing the symlink with a
-    regular file). Per-target OSError is isolated (warn+skip) so one unwritable
-    file never aborts the run or `init`.
-
-    Rule-file mode (ccsk projects / `--rule-file`): CLAUDE.md's full block is relocated
-    to .claude/rules/add-workflows.md and CLAUDE.md keeps only a reference bullet. This is
-    CLAUDE-only — AGENTS.md (and any other guideline file) keeps the inline block.
-    """
-    results: list[tuple[str, str]] = []
-    seen: set[str] = set()
-    mode = _rule_file_mode(project_root, rule_file)
-    for name in GUIDELINE_FILES:
-        if name == "CLAUDE.md" and mode:
-            rules_path = project_root / RULES_FILE_REL
-            real = os.path.realpath(rules_path)
-            if real not in seen:
-                seen.add(real)
-                try:
-                    action = _inject_block(rules_path)
-                except (OSError, UnicodeDecodeError) as exc:
-                    print(f"add: warning: could not sync {RULES_FILE_REL} — {exc}; skipped",
-                          file=sys.stderr)
-                    action = "skipped"
-                results.append((str(RULES_FILE_REL), action))
-            try:
-                ref_action = _ensure_claude_reference(project_root / "CLAUDE.md")
-            except (OSError, UnicodeDecodeError) as exc:
-                print(f"add: warning: could not sync CLAUDE.md — {exc}; skipped",
-                      file=sys.stderr)
-                ref_action = "skipped"
-            results.append(("CLAUDE.md", ref_action))
-            continue
-        target = project_root / name
-        real = os.path.realpath(target)
-        if real in seen:
-            continue
-        seen.add(real)
-        write_target = Path(real) if target.is_symlink() else target
-        try:
-            action = _inject_block(write_target)
-        except (OSError, UnicodeDecodeError) as exc:
-            # design for failure: an unwritable target OR a non-UTF-8 existing file
-            # (e.g. a UTF-16 CLAUDE.md from a Windows editor) must not crash init or
-            # abort the other target — warn and skip this one.
-            print(f"add: warning: could not sync {name} — {exc}; skipped",
-                  file=sys.stderr)
-            action = "skipped"
-        results.append((name, action))
-    return results
-
-
-# --- 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())
-
-
+# --- guidelines / CLAUDE.md-injection subsystem (moved to add_engine/guidelines.py) -
+from add_engine.guidelines import (
+    _guideline_block, _inject_block, _rule_file_mode, _strip_inline_block,
+    _insert_rule_reference, _ensure_claude_reference, _inject_guidelines, _is_brownfield,
+)
 def cmd_init(args: argparse.Namespace) -> None:
     base = Path(args.dir).resolve()
     root = base / ROOT_DIRNAME
@@ -1003,6 +307,10 @@ def cmd_init(args: argparse.Namespace) -> None:
     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.")
+    # setup hygiene (both branches): the .add/ folder IS the shared project state — commit it
+    # so the team shares one source of truth; its transient working files are already gitignored.
+    print("tip:  commit the .add/ folder to git so your team shares the ADD state "
+          "(its transient files are already .gitignored).")
 
 
 def cmd_sync_guidelines(args: argparse.Namespace) -> None:
@@ -1088,6 +396,11 @@ def cmd_new_task(args: argparse.Namespace) -> None:
               f"autonomy token; new task seeded fail-safe '{autonomy}' "
               "(fix it with `add.py autonomy set <level> --project`)", file=sys.stderr)
 
+    # F8 (force-preserve-heal): a --force overwrite RE-CREATES the record; capture the prior
+    # MONOTONIC heal counter first so it survives. Else a task that accrued heal attempts (or
+    # was HARD-STOP escalated) could launder the cap (HEAL_CAP) to zero by re-creating itself —
+    # a zero-human cap bypass (the same invariant _heal_or_escalate guards: "never auto-resets").
+    prior_heal = state["tasks"].get(slug, {}).get("heal") if args.force else None
     state["tasks"][slug] = {
         "title": title,
         "phase": "ground",
@@ -1097,6 +410,8 @@ def cmd_new_task(args: argparse.Namespace) -> None:
         "created": _now(),
         "updated": _now(),
     }
+    if prior_heal is not None:
+        state["tasks"][slug]["heal"] = prior_heal   # monotonic — survives the --force re-create
     if from_delta:
         state["tasks"][slug]["from_delta"] = from_delta     # lineage: seeded from <prior>
     if fast:
@@ -1107,6 +422,11 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     if milestone:
         print(f"linked to milestone '{milestone}'" +
               (f", depends-on {depends_on}" if depends_on else ""))
+    elif fast:
+        # blessed milestone-free fast lane (standalone-fast-task): a --fast task with no owning
+        # milestone is a DELIBERATE low-ceremony lane, not an orphan to nag — AFFIRM it.
+        print(f"standalone fast task '{slug}' — milestone-free by design (low-ceremony lane); "
+              f"attach later with `add.py set-milestone {slug} --milestone <id>` if it grows")
     else:
         # warn-never-block: the task is created (escape hatch), but nudge back toward the
         # intake -> milestone flow. Speaks of STRUCTURE (not attached), never the act.
@@ -1145,22 +465,80 @@ def cmd_drop_delta(args: argparse.Namespace) -> None:
     print(_next_footer(root, state))
 
 
+# a §3 still carrying this template placeholder is NOT a drafted contract yet
+_CONTRACT_TEMPLATE_RE = re.compile(r"<METHOD>")
+
+
+def _next_freeze_version(state: dict, slug: str) -> str:
+    """v1 on the first freeze; N+1 of the highest prior freeze version recorded on the
+    task's state record on a re-freeze (after a change request). PURE — reads state only."""
+    prior = ((state.get("tasks") or {}).get(slug) or {}).get("freeze") or {}
+    m = re.fullmatch(r"v(\d+)", str(prior.get("version", "")))
+    return f"v{int(m.group(1)) + 1}" if m else "v1"
+
+
+def cmd_freeze(args: argparse.Namespace) -> None:
+    """The §3 contract-freeze write command — the 5th engine-WRITTEN human approval (task
+    freeze-actor-stamp), joining lock · gate · milestone-done · release. Flips the target
+    task's §3 `Status: DRAFT` -> `FROZEN @ vN — approved by <name>` AND records a structured
+    actor on the task's state record (mirrors cmd_lock's `setup.actor`), so the audit trail
+    has no hole at freeze. The human RUNS it as their approval — never pre-stamped.
+
+    validate-then-write: every refusal fires before any write. Writes TASK.md first, then
+    state; a crash between degrades to today's legacy text-only freeze (never corrupt state),
+    design-for-failure."""
+    root = _require_root()
+    state = load_state(root)
+    raw_slug = getattr(args, "slug", None)
+    if not raw_slug and not _active_task(state):
+        _die("no_active_task: no task given and no active task is set")
+    slug = _resolve_task(state, raw_slug)                  # unknown slug -> _die
+    task_md = root / "tasks" / slug / "TASK.md"
+    text = task_md.read_text(encoding="utf-8")
+    raw3 = _phase_spans(text).get(3, "")
+    phase = (state["tasks"].get(slug) or {}).get("phase", "specify")
+    # --- validate (no writes); error precedence: frozen -> not-drafted -> unflagged ---
+    if _contract_frozen(raw3):
+        _die(f"already_frozen: {slug}'s §3 is already FROZEN — re-freeze only via a change "
+             f"request back to SPECIFY")
+    if _phase_index(phase) < _phase_index("contract") or _CONTRACT_TEMPLATE_RE.search(raw3):
+        _die(f"contract_not_drafted: {slug}'s §3 is not a drafted contract yet — reach the "
+             f"`contract` phase and replace the template before freezing")
+    if not _flag_well_formed(raw3):
+        _die(f"unflagged_freeze: {slug}'s §3 must surface a well-formed lowest-confidence flag "
+             f"('Least-sure flag surfaced at freeze:' + a [part] tag) before it freezes")
+    # --- write ---
+    ver = _next_freeze_version(state, slug)
+    who = args.by or identity._actor_stamp(state)["name"]
+    # flip the `Status: DRAFT` line WITHIN the §3 region only — a bare `Status: DRAFT` in
+    # §1/§2 prose must never be frozen by mistake (refute-read finding). §3 span runs from
+    # its `## 3 ·` heading to the next `## `/`---`/EOF (same boundary as _phase_spans).
+    h3 = re.search(r"(?m)^##\s*3\s*·.*$", text)
+    if not h3:
+        _die(f"contract_not_drafted: {slug}'s TASK.md has no §3 CONTRACT section")
+    seg_start = h3.end()
+    nxt = re.search(r"(?m)^(?:##\s|---\s*$)", text[seg_start:])
+    seg_end = seg_start + (nxt.start() if nxt else len(text) - seg_start)
+    new_seg, n = re.subn(r"(?m)^(\s*)Status:\s*DRAFT\s*$",
+                         lambda m: f"{m.group(1)}Status: FROZEN @ {ver} — approved by {who}",
+                         text[seg_start:seg_end], count=1)
+    if n == 0:
+        _die(f"contract_not_drafted: {slug}'s §3 has no 'Status: DRAFT' line to freeze")
+    new_text = text[:seg_start] + new_seg + text[seg_end:]
+    _atomic_write(task_md, new_text)                       # TASK.md first (audit source of truth)
+    state["tasks"][slug]["freeze"] = {"version": ver, "frozen_at": _now(),
+                                      "approved_by": who, "actor": identity._actor_stamp(state)}
+    save_state(root, state)
+    print(f"froze §3 of {slug} @ {ver} — approved by {who}")
+    print(_next_footer(root, state))
+
+
 def _parse_deps(raw: str | None) -> list[str]:
     if not raw:
         return []
     return [d.strip() for d in raw.split(",") if d.strip()]
 
 
-def _task_done(t: dict) -> bool:
-    # Matrix 3: a task is done when Verify reads PASS *or a signed RISK-ACCEPTED*.
-    # Both completing gates advance phase to "done" (cmd_gate), and a waiver is
-    # signed at gate time — so a verdict gate is enough here; we need not re-read
-    # the waiver. HARD-STOP never reaches "done". A bare `phase done` (escape
-    # hatch, gate still "none") deliberately does NOT count: completion needs a
-    # recorded verdict, not just a phase marker.
-    return t.get("phase") == "done" and t.get("gate") in ("PASS", "RISK-ACCEPTED")
-
-
 def _archived_task_slugs(state: dict) -> set[str]:
     """Slugs of tasks that left active state via archive — all were PASS-done at
     archive time, so a dep on one of them counts as satisfied (not dangling).
@@ -1184,16 +562,94 @@ def _resolve_task(state: dict, slug: str | None) -> str:
     return slug
 
 
+def _build_entry(root: Path, state: dict, slug: str) -> None:
+    """The shared tests->build entry guards + snapshots (task phase-build-guard, F4).
+
+    Extracted VERBATIM from cmd_advance's `nxt == "build"` block so BOTH `advance` and the
+    `phase build` admin override run the identical gate stack — the freeze gate, the
+    build-expectations gate, the unflagged-freeze check + flag stamp, the tamper tripwire, and
+    the §5 scope snapshot. validate-then-write: every `_die` precedes the first state mutation,
+    so a refused entry leaves the task byte-unchanged. The heal loop sets phase=build DIRECTLY
+    and never routes here, so it stays exempt.
+    """
+    # the OPTED-IN crossing guards (fast-lane + flow-enforcement): a task whose PARENT
+    # milestone opted into --await-confirm is held to the trust floor at tests->build. A
+    # task under a plain / no milestone is never gated (every existing advance-to-build flow
+    # stays green). validate-then-write — every refusal runs BEFORE the tripwire/scope
+    # snapshots below, writing nothing; the task stays at `tests`.
+    _ms = state["tasks"][slug].get("milestone")
+    _optin = bool(_ms) and (state.get("milestones") or {}).get(_ms, {}).get("await_confirm") is True
+    raw3 = _raw_phase_bodies(root, slug).get(3, "")
+    # freeze-before-build gate (fast-lane): "collapse-never-skip" made REAL — the freeze is
+    # engine-enforced for an opted-in milestone OR any --fast task (the fast arm, fast-new-task-flag:
+    # a fast task is held to the floor under ANY milestone, so the lighter lane never drops the
+    # trust seam). PRECEDES build-expectations: you freeze §3 before pre-declaring §6's outcomes.
+    _freeze_gated = _optin or state["tasks"][slug].get("fast") is True
+    if _freeze_gated and not _contract_frozen(raw3):
+        _die("contract_not_frozen: freeze §3 before crossing into build — approve "
+             f"the contract in {slug}'s TASK.md (Status: FROZEN @ vN)")
+    # build-expectations gate (flow-enforcement): an opted-in task may not enter build until
+    # its §6 `### Build expectations` are pre-declared — so verify checks the build is RIGHT,
+    # not just green. Same opt-in switch as the contract-fill gate, one level out.
+    if _optin:
+        if _section_unfilled(_raw_phase_bodies(root, slug).get(6, ""), "### Build expectations"):
+            _die("build_expectations_unfilled: fill the §6 '### Build expectations' block "
+                 f"of {slug}'s TASK.md before crossing into build")
+    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
+    # tamper tripwire (verify-integrity): snapshot the red test files + the frozen
+    # §3 md5s so the verify gate can prove the green was EARNED, not edited into
+    # place. UNCONDITIONAL overwrite — a legit change-request that re-crosses
+    # tests->build re-snapshots cleanly. Co-witnessed by flag_verified (above).
+    state["tasks"][slug]["tripwire"] = _tripwire_snapshot(root, slug, raw3)
+    # §5 scope gate (build-scope-lock): when the task declares its Scope, freeze
+    # the project tree into a sidecar (payload) + a state.json anchor (md5 of the
+    # sidecar bytes). Same UNCONDITIONAL-overwrite semantics as the tripwire.
+    # UNDECLARED (no Scope line) takes no snapshot — grandfathered, never retro-red
+    # — and CLEANS UP a previous declaration's leftovers (v3): a declared->
+    # undeclared re-cross pops the stale anchor + unlinks the stale sidecar, so
+    # "UNDECLARED is never refused" holds on every path.
+    declared = _declared_scope(root, slug)
+    side = root / "tasks" / slug / "scope-snapshot.json"
+    if declared is not None:
+        payload = json.dumps({"version": 1,
+                              "files": _scope_walk(root.parent.resolve())},
+                             sort_keys=True)
+        _atomic_write(side, payload)   # temp+replace, like save_state — a crash can't leave a
+                                       # torn sidecar (payload verbatim, no newline → md5 anchor holds)
+        state["tasks"][slug]["scope"] = {"declared": declared,
+                                         "snapshot_md5": _md5_text(payload)}
+    else:
+        state["tasks"][slug].pop("scope", None)
+        try:
+            side.unlink()
+        except OSError:
+            pass
+
+
 def cmd_phase(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
     slug = _resolve_task(state, args.slug)
     if args.phase not in PHASES:
         _die(f"phase must be one of: {', '.join(PHASES)}")
+    # phase-build-guard (F4): the admin override is NOT a backdoor around the tests->build gate
+    # stack — setting a task to build runs the SAME _build_entry guards `advance` runs (freeze
+    # gate · build-expectations · flag check · tamper tripwire · scope snapshot), so verify's
+    # _tamper_guard is armed and a freeze-gated DRAFT §3 is refused. Other targets are unchanged.
+    # validate-then-write: a refusal raises BEFORE the phase is set, so nothing moves. The heal
+    # loop sets phase=build directly (never via cmd_phase) and so stays exempt.
+    if args.phase == "build":
+        _build_entry(root, state, slug)
     state["tasks"][slug]["phase"] = args.phase
     state["tasks"][slug]["updated"] = _now()
-    _sync_task_marker(root, slug, args.phase)
-    save_state(root, state)
+    save_state(root, state)                    # F12: durable state FIRST (source of truth) — may _die
+    _sync_task_marker(root, slug, args.phase)  # then mirror into TASK.md (best-effort) — no split-brain
     print(f"task '{slug}' phase -> {args.phase}")
     print(_next_footer(root, state))
 
@@ -1230,63 +686,10 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # 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":
-        # the OPTED-IN crossing guards (fast-lane + flow-enforcement): a task whose PARENT
-        # milestone opted into --await-confirm is held to the trust floor at tests->build. A
-        # task under a plain / no milestone is never gated (every existing advance-to-build flow
-        # stays green). validate-then-write — every refusal runs BEFORE the tripwire/scope
-        # snapshots below, writing nothing; the task stays at `tests`.
-        _ms = state["tasks"][slug].get("milestone")
-        _optin = bool(_ms) and (state.get("milestones") or {}).get(_ms, {}).get("await_confirm") is True
-        raw3 = _raw_phase_bodies(root, slug).get(3, "")
-        # freeze-before-build gate (fast-lane): "collapse-never-skip" made REAL — the freeze is
-        # engine-enforced for an opted-in milestone OR any --fast task (the fast arm, fast-new-task-flag:
-        # a fast task is held to the floor under ANY milestone, so the lighter lane never drops the
-        # trust seam). PRECEDES build-expectations: you freeze §3 before pre-declaring §6's outcomes.
-        _freeze_gated = _optin or state["tasks"][slug].get("fast") is True
-        if _freeze_gated and not _contract_frozen(raw3):
-            _die("contract_not_frozen: freeze §3 before crossing into build — approve "
-                 f"the contract in {slug}'s TASK.md (Status: FROZEN @ vN)")
-        # build-expectations gate (flow-enforcement): an opted-in task may not enter build until
-        # its §6 `### Build expectations` are pre-declared — so verify checks the build is RIGHT,
-        # not just green. Same opt-in switch as the contract-fill gate, one level out.
-        if _optin:
-            if _section_unfilled(_raw_phase_bodies(root, slug).get(6, ""), "### Build expectations"):
-                _die("build_expectations_unfilled: fill the §6 '### Build expectations' block "
-                     f"of {slug}'s TASK.md before crossing into build")
-        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
-        # tamper tripwire (verify-integrity): snapshot the red test files + the frozen
-        # §3 md5s so the verify gate can prove the green was EARNED, not edited into
-        # place. UNCONDITIONAL overwrite — a legit change-request that re-crosses
-        # tests->build re-snapshots cleanly. Co-witnessed by flag_verified (above).
-        state["tasks"][slug]["tripwire"] = _tripwire_snapshot(root, slug, raw3)
-        # §5 scope gate (build-scope-lock): when the task declares its Scope, freeze
-        # the project tree into a sidecar (payload) + a state.json anchor (md5 of the
-        # sidecar bytes). Same UNCONDITIONAL-overwrite semantics as the tripwire.
-        # UNDECLARED (no Scope line) takes no snapshot — grandfathered, never retro-red
-        # — and CLEANS UP a previous declaration's leftovers (v3): a declared->
-        # undeclared re-cross pops the stale anchor + unlinks the stale sidecar, so
-        # "UNDECLARED is never refused" holds on every path.
-        declared = _declared_scope(root, slug)
-        side = root / "tasks" / slug / "scope-snapshot.json"
-        if declared is not None:
-            payload = json.dumps({"version": 1,
-                                  "files": _scope_walk(root.parent.resolve())},
-                                 sort_keys=True)
-            side.write_text(payload, encoding="utf-8")
-            state["tasks"][slug]["scope"] = {"declared": declared,
-                                             "snapshot_md5": _md5_text(payload)}
-        else:
-            state["tasks"][slug].pop("scope", None)
-            try:
-                side.unlink()
-            except OSError:
-                pass
+        # the tests->build entry guards + snapshots now live in the shared _build_entry helper
+        # (task phase-build-guard, F4) so `advance` and the `phase build` admin override run the
+        # IDENTICAL gate stack. Behavior here is byte-unchanged — this is a pure extraction.
+        _build_entry(root, state, slug)
     # cross-component contract artifact (cross-component-contract): the contract->tests crossing
     # is the producer's freeze-approval moment. A `produces:` task WRITES the immutable snapshot;
     # a `consumes:` task PINS the live hash — a missing/unreadable snapshot HARD-STOPS here (the
@@ -1327,8 +730,8 @@ def cmd_advance(args: argparse.Namespace) -> None:
             state["tasks"][slug]["contract_pin"] = {"id": _cons, "hash": pinned}
     state["tasks"][slug]["phase"] = nxt
     state["tasks"][slug]["updated"] = _now()
-    _sync_task_marker(root, slug, nxt)
-    save_state(root, state)
+    save_state(root, state)             # F12: durable state FIRST (source of truth) — may _die
+    _sync_task_marker(root, slug, nxt)  # then mirror into TASK.md (best-effort) — no split-brain
     print(f"task '{slug}' phase {cur} -> {nxt}")
     if nxt == "observe":
         # OBSERVE is where this loop's lessons get captured (TASK.md §7) — suggest routing
@@ -1356,12 +759,10 @@ _RISK_HIGH_RE = re.compile(r"(?:^|·)[ \t]*risk:[ \t]*high\b", re.MULTILINE)
 
 # the explicit 3-mode autonomy dial (task explicit-autonomy-dial): an ordered ladder
 # manual < conservative < auto, declared as a per-task `autonomy:` header token.
-_AUTONOMY_LEVELS = ("manual", "conservative", "auto")
 # anchored to a DECLARATION position — line-start `autonomy:` OR the inline slug-line form
 # `… · autonomy: conservative` (the `·`-preceded shape) — never a title/prose substring; the
 # value stops at space/`<`/`#`/`|` so an unfilled `<manual | … >` placeholder captures nothing
 # and reads as UNSET.
-_AUTONOMY_LINE_RE = re.compile(r"(?:^|·)[ \t]*autonomy:[ \t]*([^\s<#|]+)", re.MULTILINE)
 
 # component-aware-add: a task binds to a registered component via a `component: <name>`
 # header token — the SAME anchored grammar as autonomy (line-start or the `·`-inline
@@ -1372,45 +773,12 @@ _PRODUCES_LINE_RE = re.compile(r"(?:^|·)[ \t]*produces:[ \t]*([^\s<#|]+)", re.M
 _CONSUMES_LINE_RE = re.compile(r"(?:^|·)[ \t]*consumes:[ \t]*([^\s<#|]+)", re.MULTILINE)
 
 
-def _autonomy_level(hdr: str):
-    """The declared autonomy rung from a TASK.md header region (HTML comments
-    already stripped by _task_header). Returns a member of _AUTONOMY_LEVELS, or
-    None when no `autonomy:` line is present (UNSET — an unfilled `<…>` placeholder,
-    whose value the regex declines, counts as unset), or "?" when a REAL token outside
-    the set was written (unknown). PURE."""
-    m = _AUTONOMY_LINE_RE.search(hdr)
-    if not m:
-        return None
-    tok = m.group(1).strip().lower()
-    return tok if tok in _AUTONOMY_LEVELS else "?"
-
-
 def _autonomy_lowered(hdr: str) -> bool:
     """True iff the declared rung is high-risk-safe (manual or conservative). A
     high-risk scope must be lowered to one of these; `auto` and UNSET are not."""
     return _autonomy_level(hdr) in ("manual", "conservative")
 
 
-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 _effective_autonomy(root: Path, state: dict, slug: str) -> str:
-    """The autonomy rung that governs `slug` right now: the task's own declared rung,
-    falling back to the project default when the task line is UNSET (None) or an
-    unrecognized token ("?") — the same fail-safe chain cmd_new_task seeds from
-    (_project_autonomy: absent -> auto, garbled -> conservative). PURE. `state` is unused
-    today; it is kept in the signature beside _driver_stop for symmetry."""
-    lvl = _autonomy_level(_task_header(root, slug))
-    return lvl if lvl in _AUTONOMY_LEVELS else _project_autonomy(root)
-
-
 def _driver_stop(root: Path, state: dict, slug: str, phase: str) -> bool:
     """True iff a HUMAN owns the next step for `phase` under the effective autonomy — the
     SINGLE source the footer marker and the guide TEXT marker both render (task
@@ -1469,6 +837,10 @@ def cmd_gate(args: argparse.Namespace) -> None:
         # §5 scope gate (build-scope-lock): touched ⊆ declared, or a named refusal —
         # same placement discipline as the tripwire (before the waiver, never on HARD-STOP).
         _scope_guard(root, state, slug)
+        # consumer-stale gate (consumer-stale-gate): a `consumes:` task whose pinned producer
+        # contract hash has drifted from the live snapshot built against an out-of-date shape —
+        # refuse the completing outcome (same before-the-waiver discipline). Re-pin to recover.
+        _consumer_stale_guard(root, state, slug)
         # per-component verify (component-aware-add): a component-bound task with a declared
         # green_bar must CITE that bar in its §6 evidence before a completing outcome — the
         # engine never runs the suite, it checks the right bar was recorded. Unbound / no
@@ -1493,11 +865,12 @@ def cmd_gate(args: argparse.Namespace) -> None:
         }
     if completing:
         state["tasks"][slug]["phase"] = "done"
-        _sync_task_marker(root, slug, "done")
     state["tasks"][slug]["gate"] = args.outcome
-    state["tasks"][slug]["gate_actor"] = _actor_stamp(state)   # WHO recorded the verdict (every outcome)
+    state["tasks"][slug]["gate_actor"] = identity._actor_stamp(state)   # WHO recorded the verdict (every outcome)
     state["tasks"][slug]["updated"] = _now()
-    save_state(root, state)
+    save_state(root, state)                                # F12: durable state FIRST (source of truth) — may _die
+    if completing:
+        _sync_task_marker(root, slug, "done")             # then mirror the phase into TASK.md — no split-brain
     _stamp_gate_record(root, state, slug, args.outcome)   # mirror the verdict into §6 (Finding C)
     print(f"task '{slug}' gate -> {args.outcome}")
     _gbar = _task_green_bar(root, slug)                   # per-component-verify: surface the bound bar
@@ -1582,6 +955,45 @@ def cmd_autonomy(args: argparse.Namespace) -> None:
     _print_autonomy(root, state, slug)
 
 
+def cmd_todo(args: argparse.Namespace) -> None:
+    """Capture / list / close a lightweight backlog todo (task: todo-capture).
+
+    A todo is a JOTTED IDEA, not a task — it carries no spec/contract/gate. It lets you
+    record an intent without sizing it. Promote one to a real task with
+    `add.py new-task <slug> --fast` when you decide to build it. Stored in state["todos"]
+    as {id (1-based = max+1), text, created, status:"open"|"done"}.
+    """
+    root = _require_root()                                   # reused -> "no .add/ project found …"
+    state = load_state(root)
+    todos = state.get("todos")
+    if not isinstance(todos, list):                          # absent / corrupt -> fresh list (drift-safe)
+        todos = state["todos"] = []
+    done_id = getattr(args, "done", None)
+    if done_id is not None:                                  # --done <id> : close an OPEN todo
+        for t in todos:
+            if isinstance(t, dict) and t.get("id") == done_id and t.get("status") == "open":
+                t["status"] = "done"
+                save_state(root, state)
+                print(f"todo #{done_id} done")
+                return
+        _die(f"todo_unknown: no open todo #{done_id}")
+    if args.text is not None:                                # capture attempt (text positional present)
+        text = args.text.strip()
+        if not text:
+            _die("todo_empty: a todo needs text")
+        new_id = max((t.get("id", 0) for t in todos if isinstance(t, dict)), default=0) + 1
+        todos.append({"id": new_id, "text": text, "created": _now(), "status": "open"})
+        save_state(root, state)
+        print(f"captured todo #{new_id}: {text}")
+        return
+    open_todos = [t for t in todos if isinstance(t, dict) and t.get("status") == "open"]
+    if not open_todos:                                       # bare `todo` -> list OPEN todos
+        print("no open todos")
+        return
+    for t in open_todos:
+        print(f"#{t.get('id')}  {t.get('text')}")
+
+
 def cmd_reopen(args: argparse.Namespace) -> None:
     """Return an already-`done` task to an earlier phase with a never-silent record.
 
@@ -1616,8 +1028,8 @@ def cmd_reopen(args: argparse.Namespace) -> None:
     t["phase"] = target
     t["gate"] = "none"
     t["updated"] = now
-    _sync_task_marker(root, slug, target)
-    save_state(root, state)
+    save_state(root, state)                # F12: durable state FIRST (source of truth) — may _die
+    _sync_task_marker(root, slug, target)  # then mirror into TASK.md (best-effort) — no split-brain
     print(f"task '{slug}' reopened: done -> {target} (reason recorded); gate reset to none")
     print(_next_footer(root, state))
 
@@ -1668,7 +1080,7 @@ def cmd_lock(args: argparse.Namespace) -> None:
     when = _now()
     # ONE atomic write — no partial lock state.
     state["setup"] = {"locked": True, "locked_at": when, "locked_by": who, "layers": layers,
-                      "actor": _actor_stamp(state)}   # structured actor alongside the free-text locked_by
+                      "actor": identity._actor_stamp(state)}   # structured actor alongside the free-text locked_by
     save_state(root, state)
     if getattr(args, "json", False):
         print(json.dumps(
@@ -1695,7 +1107,7 @@ def cmd_whoami(args: argparse.Namespace) -> None:
             _die("actor_name_blank")
         state["actor_override"] = {"name": args.name, "email": args.email or None}
         save_state(root, state)
-    who = _whoami(state)
+    who = identity._whoami(state)
     if getattr(args, "json", False):
         print(json.dumps(who, separators=(",", ":")))
         return
@@ -1724,14 +1136,14 @@ def cmd_assign(args: argparse.Namespace) -> None:
         _die("unknown_slug")
     # parse + validate ALL flags BEFORE the first write — a blank name is rejected on the
     # PARSED name (so "<>" or " <a@x.io>", whose name parses empty, is caught like "   ").
-    parsed_owner = _parse_actor_arg(args.owner) if args.owner is not None else None
-    parsed_assignee = _parse_actor_arg(args.assignee) if args.assignee is not None else None
+    parsed_owner = identity._parse_actor_arg(args.owner) if args.owner is not None else None
+    parsed_assignee = identity._parse_actor_arg(args.assignee) if args.assignee is not None else None
     if parsed_owner is not None and not parsed_owner["name"].strip():
         _die("owner_name_blank")
     if parsed_assignee is not None and not parsed_assignee["name"].strip():
         _die("assignee_name_blank")
     if parsed_owner is None and parsed_assignee is None:
-        who = _whoami(state)
+        who = identity._whoami(state)
         rec["owner"] = dict(who)
         rec["assignee"] = dict(who)
     else:
@@ -1765,15 +1177,6 @@ def cmd_unassign(args: argparse.Namespace) -> None:
     print(f"unassigned {args.slug} ({', '.join(roles)})")
 
 
-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)
@@ -1846,7 +1249,7 @@ def cmd_status(args: argparse.Namespace) -> None:
         grad_ready, grad_met, grad_total = _graduation_ready(root, state)
         print(json.dumps({
             "project": state.get("project"), "stage": state.get("stage"),
-            "actor": _whoami(state),
+            "actor": identity._whoami(state),
             "active_task": _active_task(state),
             "active_milestones": list(state.get("active_milestones") or []),
             "active_tasks": dict(state.get("active_tasks") or {}),
@@ -1871,7 +1274,7 @@ def cmd_status(args: argparse.Namespace) -> None:
     print(f"project autonomy: {_project_autonomy(root)}   (default — new tasks inherit)")
     # git-native actor (user-identity): who ADD sees you as this session — the identity every
     # human-owned stamp records. Always present (the resolver is TOTAL). Read-only, no write.
-    _who = _whoami(state)
+    _who = identity._whoami(state)
     _who_email = f" <{_who['email']}>" if _who.get("email") else ""
     print(f"actor   : {_who['name']}{_who_email} (source: {_who['source']})")
     print(f"stage   : {state.get('stage', '(unknown)')}")
@@ -1938,6 +1341,12 @@ def cmd_status(args: argparse.Namespace) -> None:
     _rel = _releasable(root, state)
     if _rel:
         print(f"  → {RELEASABLE_CUE.format(n=len(_rel))}")
+    # loose-task release cue (loose-task-release): a SEPARATE additive line — done milestone-free
+    # tasks not yet attributed to a RELEASES.md `loose tasks:` row. Peer to the milestone cue (its
+    # constant is untouched); fires even with zero releasable milestones. Fail-open ledger read.
+    _loose = _releasable_loose_tasks(root, state)
+    if _loose:
+        print(f"  → releasable: {len(_loose)} loose task(s) since last release")
 
     # fast-lane marker (fast-new-task-flag): tag an ACTIVE fast task so the lane is visible at a
     # glance. Presentation-only, existence-gated — a plain/absent active task is byte-unchanged.
@@ -1966,6 +1375,14 @@ def cmd_status(args: argparse.Namespace) -> None:
             _so = _fmt_actor(_owner_rec) if _owner_rec.get("name") else ""
             _own_frag = f"  · owner: {_so}" if _so else ""
             print(f"  {_mk} {_m:<20} task={_tk or '(none)'}  phase={_ph}{_tag}{_own_frag}")
+    # queued backlog (queue-resume-surface): surface milestones awaiting promotion so a
+    # multi-milestone session resumes cleanly — `active` is what you're on, `queued` is what's
+    # next. ADDITIVE + present-only: silent when zero queued (byte-identical), exactly like the
+    # release/loose/streams cues; reads state, writes nothing, changes no command decision.
+    _queued = [ms for ms, m in milestones.items() if m.get("status") == "queued"]
+    if _queued:
+        print(f"queued  : {len(_queued)} milestone(s) next — {', '.join(_queued)}")
+        print(f"          promote next: add.py activate {_queued[0]}")
     # surface the active task's autonomy level (task explicit-autonomy-dial) so the human
     # reads the throttle every session; "unset" when no explicit `autonomy:` line is present.
     if active and active in tasks:
@@ -2624,6 +2041,7 @@ def cmd_check(args: argparse.Namespace) -> None:
     milestones = state.get("milestones") if isinstance(state.get("milestones"), dict) else {}
     archived_slugs = _archived_task_slugs(state)   # archived deps still resolve
     warnings: list[tuple[str, str]] = []  # (name, reason) — nudges that NEVER feed `failed`
+    infos: list[tuple[str, str]] = []     # (name, reason) — affirmations; NEVER feed `warned`/`failed`
     for slug, t in tasks.items():
         task_md = root / "tasks" / slug / "TASK.md"
         checks.append((task_md.exists(), f"task '{slug}' has TASK.md", "file missing"))
@@ -2635,6 +2053,10 @@ def cmd_check(args: argparse.Namespace) -> None:
         if ms is not None:
             checks.append((ms in milestones, f"task '{slug}' milestone resolves",
                            f"unknown milestone {ms!r}"))
+        elif t.get("fast"):
+            # blessed milestone-free fast lane (standalone-fast-task): a --fast task with no
+            # milestone is DELIBERATE — a soft INFO affirmation, never a WARN/orphan nudge.
+            infos.append((f"task '{slug}'", "— standalone fast lane (milestone-free by design)"))
         else:
             # warn-never-block: a task outside a milestone is a structural nudge back toward
             # the intake flow — NOT a failure. Names structure, never the act of intake.
@@ -2824,10 +2246,15 @@ def cmd_check(args: argparse.Namespace) -> None:
     passed = sum(1 for ok, _, _ in checks if ok)
     failed = len(checks) - passed
     if as_json:
+        # `infos`/`informed` are ADDITIVE (standalone-fast-task) — affirmations that never feed
+        # `warned`/`failed`; existing keys are untouched so prior consumers keep working.
         print(json.dumps({"passed": passed, "failed": failed,
                           "warned": len(warnings),
                           "warnings": [{"name": name, "reason": reason}
                                        for name, reason in warnings],
+                          "informed": len(infos),
+                          "infos": [{"name": name, "reason": reason}
+                                    for name, reason in infos],
                           "checks": [{"ok": ok, "name": desc,
                                       "reason": reason if not ok else ""}
                                      for ok, desc, reason in checks]}))
@@ -2836,6 +2263,8 @@ def cmd_check(args: argparse.Namespace) -> None:
             print(f"PASS  {desc}" if ok else f"FAIL  {desc}: {reason}")
         for name, reason in warnings:
             print(f"WARN  {name} {reason}")
+        for name, reason in infos:
+            print(f"INFO  {name} {reason}")
         summary = f"check: {passed} passed, {failed} failed"
         if warnings:
             summary += f" ({len(warnings)} warnings)"   # frozen §3: summary gains "(N warnings)"
@@ -2890,6 +2319,39 @@ def _doctor_findings(root: Path) -> list[str]:
         if m is not None and m not in milestones:
             findings.append(f"task '{slug}' references missing milestone '{m}' — fix: set its "
                             "milestone to a real one (or none)")
+    # value-domain checks (doctor-value-checks): gate/phase enum (required) · owner/assignee
+    # shape (optional) · archived consistency. Present-but-invalid + missing-required only;
+    # absent owner/assignee is fine. Pure/total — .get-guarded, isinstance-checked, never raises.
+    for slug, t in tasks.items():
+        if not isinstance(t, dict):
+            continue
+        g = t.get("gate")
+        if g is None:
+            findings.append(f"task '{slug}' is missing its gate — fix: one of {', '.join(GATES)}")
+        elif g not in GATES:
+            findings.append(f"task '{slug}' has invalid gate '{g}' — fix: one of {', '.join(GATES)}")
+        p = t.get("phase")
+        if p is None:
+            findings.append(f"task '{slug}' is missing its phase — fix: one of {', '.join(PHASES)}")
+        elif p not in PHASES:
+            findings.append(f"task '{slug}' has invalid phase '{p}' — fix: one of {', '.join(PHASES)}")
+        for role in ("owner", "assignee"):
+            v = t.get(role)
+            if v is not None and not (isinstance(v, dict) and isinstance(v.get("name"), str) and v.get("name")):
+                findings.append(f"task '{slug}' has a malformed {role} — fix: an actor object "
+                                "{name, email, source} or remove it")
+    archived = state.get("archived") if isinstance(state.get("archived"), list) else []
+    for a in archived:
+        if not isinstance(a, dict):
+            continue
+        aslug = a.get("slug")
+        if aslug is not None and aslug in milestones:
+            findings.append(f"archived milestone '{aslug}' is also a live milestone — fix: remove "
+                            "the live duplicate or the archived entry")
+        ts = a.get("task_slugs")
+        if isinstance(ts, list) and isinstance(a.get("tasks"), int) and a.get("tasks") != len(ts):
+            findings.append(f"archived milestone '{aslug}' task count {a.get('tasks')} ≠ {len(ts)} "
+                            "listed — fix: reconcile its task_slugs")
     return findings
 
 
@@ -2910,25 +2372,29 @@ def cmd_doctor(args: argparse.Namespace) -> None:
 
 
 def cmd_mine(args: argparse.Namespace) -> None:
-    """Read-only `add.py mine`: across all active milestones, the not-done tasks owned-by or
-    assigned-to the resolved actor (`_whoami`, or `--actor "Name <email>"`). Text or `--json`.
-    An empty queue is a plain exit-0 line, not an error. NEVER writes state."""
+    """Read-only `add.py mine`: the not-done tasks owned-by or assigned-to the resolved actor
+    (`_whoami`, or `--actor "Name <email>"`). Default lens is the active SET; `--all` widens it
+    to EVERY milestone plus loose (milestone-less) tasks. Text or `--json`. An empty queue is a
+    plain exit-0 line, not an error. NEVER writes state."""
     root = find_root()
     if root is None:
         _die("no_project")
     state = load_state(root)
-    me = _parse_actor_arg(args.actor) if getattr(args, "actor", None) else _whoami(state)
-    rows = _my_work(state, me)
+    me = identity._parse_actor_arg(args.actor) if getattr(args, "actor", None) else identity._whoami(state)
+    scope_all = getattr(args, "all", False)
+    rows = _my_work(state, me, scope_all=scope_all)
     if getattr(args, "json", False):
         print(json.dumps({"actor": me, "tasks": rows}))
         return
+    scope = "all" if scope_all else "active"
     who = _fmt_actor(me) or me.get("name", "you")
     if not rows:
-        print(f"mine: no open tasks for {who} across active milestones")
+        print(f"mine: no open tasks for {who} across {scope} milestones")
         return
-    print(f"mine: {who} — {len(rows)} open task(s) across active milestones:")
+    print(f"mine: {who} — {len(rows)} open task(s) across {scope} milestones:")
     for r in rows:
-        print(f"  {r['slug']:<24} [{r['milestone']}]  phase={r['phase']}  ({r['role']})")
+        loc = f"[{r['milestone']}]" if r["milestone"] else "[loose]"
+        print(f"  {r['slug']:<24} {loc}  phase={r['phase']}  ({r['role']})")
 
 
 # ---------------------------------------------------------------------------
@@ -3075,6 +2541,12 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     slug = args.slug
     if not slug.replace("-", "").replace("_", "").isalnum():
         _die("bad_slug")
+    # Prefer a short DESCRIPTIVE slug over a bare version (v2, v1-1, 1.2): a descriptive
+    # name keeps the milestones list legible. Advisory only — never blocks (matches the
+    # engine's `note:` convention); a deliberate version slug still creates.
+    if re.match(r"^v?\d+([._-]\d+)*$", slug, re.IGNORECASE):
+        print(f"note: slug '{slug}' looks like a bare version — prefer a short "
+              f"descriptive name (e.g. 'payment-retries'). Creating anyway.")
     state.setdefault("milestones", {})
     mdir = root / "milestones" / slug
     mfile = mdir / MILESTONE_FILE
@@ -3082,17 +2554,24 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
         _die("milestone_exists")
     mdir.mkdir(parents=True, exist_ok=True)
     title = args.title or slug.replace("-", " ").replace("_", " ").title()
+    # One _now() instant feeds BOTH the MILESTONE.md render and the state record, so the
+    # human-facing `created:` is a full ISO timestamp provably equal to state.json.
+    now = _now()
     _atomic_write(mfile, _render_template(
         "MILESTONE.md", title=title, goal=args.goal or "<goal>",
-        stage=args.stage, date=date.today().isoformat()))
+        stage=args.stage, date=now))
     # confirm-parent gate (OPT-IN, mirrors `init --await-lock`): `--await-confirm` seeds the
     # milestone UNCONFIRMED so new-task is held until `add.py milestone-confirm`. WITHOUT the flag
     # NO `confirmed` key is written → grandfathered-confirmed → no gate (so the existing engine
     # tests stay byte-green). The guided skill flow passes the flag at the human-review point.
     await_confirm = bool(getattr(args, "await_confirm", False))
+    # --queued (OPT-IN): create the milestone non-active (status=queued) without stealing focus.
+    # The active set is left UNCHANGED so the default path (no flag) stays byte-identical. Promote
+    # later with `activate` (queued→active). Foundation for roadmap intake (1 active + N queued).
+    queued = bool(getattr(args, "queued", False))
     record = {
         "title": title, "goal": args.goal or "", "stage": args.stage,
-        "status": "active", "created": _now(), "updated": _now(),
+        "status": "queued" if queued else "active", "created": now, "updated": now,
     }
     if await_confirm:
         # `await_confirm` is the STABLE opt-in marker (set ONLY here, at creation). `confirmed`
@@ -3100,11 +2579,22 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
         # milestone too, so a later build-entry gate must key on `await_confirm`, not `confirmed`.
         record.update(confirmed=False, confirmed_at=None, confirmed_by=None, await_confirm=True)
     state["milestones"][slug] = record
-    _set_active_milestone(state, slug)
+    if not queued:
+        # PRESERVE the active SET (new-milestone-add-focus): ADD this milestone + focus it, rather
+        # than REPLACING the set and evicting the others. Single-active is identical ([] -> [slug]);
+        # a user who already had P active now keeps P active alongside the new primary.
+        _activate_milestone(state, slug)
     save_state(root, state)
     print(f"created milestone '{slug}' -> {mfile}")
-    print("active milestone set." + ("" if not await_confirm else
-          "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
+    if queued:
+        print(f"queued (not active) — promote it with: add.py activate {slug}")
+        # surface the recorded confirm gate for a queued+await_confirm milestone (queued-await-confirm-hint):
+        # additive — prints ONLY when await_confirm, so plain `--queued` output stays byte-identical.
+        if await_confirm:
+            print(f"  (unconfirmed — after promote: add.py milestone-confirm {slug})")
+    else:
+        print("active milestone set." + ("" if not await_confirm else
+              "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 
@@ -3136,7 +2626,7 @@ def cmd_milestone_confirm(args: argparse.Namespace) -> None:
     m["confirmed"] = True
     m["confirmed_at"] = _now()
     m["confirmed_by"] = who
-    m["actor"] = _actor_stamp(state)   # structured actor alongside the free-text confirmed_by
+    m["actor"] = identity._actor_stamp(state)   # structured actor alongside the free-text confirmed_by
     m["updated"] = _now()
     save_state(root, state)
     print(f"confirmed milestone '{slug}' (by {who}) — new-task is now open for it.")
@@ -3193,25 +2683,34 @@ def cmd_ready(args: argparse.Namespace) -> None:
 
 
 def _wave_schedule(state: dict, mslug: str) -> dict:
-    """Pure, total: derive the DAG schedule for milestone `mslug` from state — never
-    mutates, never raises on dict input. Returns one of:
+    """One-element wrapper: a single milestone's schedule is the merge over just [mslug].
+    Output is byte-identical to the historical per-milestone scheduler (the suite is the oracle)."""
+    return _wave_schedule_merged(state, [mslug])
+
+
+def _wave_schedule_merged(state: dict, mslugs: list[str]) -> dict:
+    """Pure, total: derive ONE DAG schedule over the UNION of open members across `mslugs`
+    (a single-element list is the historical per-milestone case) — never mutates, never raises
+    on dict input. Returns one of:
       {"cycle": [slug, ...]}                                       — unschedulable cycle
       {"waves", "critical_path", "critical_path_len", "tiers", "blocked"}  — a schedule
 
     A dep is SATISFIED (does not block) if it is archived or `_task_done` — the SAME
-    predicate cmd_ready uses. A not-done dep that is an OPEN MEMBER of this milestone
-    forces a later wave. A not-done dep that is NOT an open member (external/unknown)
-    is UNSATISFIABLE here -> the task is `blocked`, never scheduled. Critical path is the
-    longest chain (most tasks) through the scheduled sub-DAG; ties break by sorted slug.
-    Tier is advisory: `top` on the critical path, `mid` elsewhere (scheduled tasks only)."""
+    predicate cmd_ready uses. A not-done dep that is an OPEN MEMBER of ANY target milestone
+    forces a later wave (so a cross-milestone dep ORDERS, it does not block). A not-done dep
+    that is NOT an open member of any target (external/unknown) is UNSATISFIABLE here -> the
+    task is `blocked`, never scheduled. Critical path is the longest chain (most tasks) through
+    the scheduled sub-DAG; ties break by sorted slug. Tier is advisory: `top` on the critical
+    path, `mid` elsewhere (scheduled tasks only)."""
     tasks = state.get("tasks") or {}
     archived = _archived_task_slugs(state)
+    targetset = set(mslugs)
 
     def _ok(d: str) -> bool:                       # satisfied externally / already done
         return d in archived or (d in tasks and _task_done(tasks[d]))
 
     open_members = {s: t for s, t in tasks.items()
-                    if t.get("milestone") == mslug and not _task_done(t)}
+                    if t.get("milestone") in targetset and not _task_done(t)}
 
     # partition open members into blocked vs schedulable — to a FIXED POINT, so blocking
     # propagates transitively: a task is blocked if any dep is unsatisfiable here, where
@@ -3312,16 +2811,71 @@ def _wave_block_lines(state: dict, mslug: str, sched: dict) -> list[str]:
     return lines
 
 
+def _wave_block_lines_merged(state: dict, mslugs: list[str], sched: dict) -> list[str]:
+    """The text lines `waves --merge` renders for ONE unified schedule over the milestone SET:
+    a `merged: …` header naming the set + each scheduled task tagged with its `[milestone]` so
+    cross-milestone tasks are unambiguous. Critical-path / tier-hint / blocked lines mirror
+    `_wave_block_lines`."""
+    n = len(mslugs)
+    lines = [f"merged: {' + '.join(mslugs)} ({n} milestone{'s' if n != 1 else ''})"]
+    if not sched["waves"]:
+        if sched["blocked"]:
+            for s in sched["blocked"]:
+                lines.append(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+        else:
+            lines.append("all tasks done — nothing to schedule")
+        return lines
+    scheduled_set = {x for w in sched["waves"] for x in w}
+    for i, wave in enumerate(sched["waves"], start=1):
+        parts = []
+        for s in wave:
+            label = f"{s} [{state['tasks'][s].get('milestone')}]"
+            md = sorted(d for d in (state["tasks"][s].get("depends_on") or [])
+                        if d in scheduled_set)
+            parts.append(f"{label} (deps: {', '.join(md)})" if md else label)
+        lines.append(f"wave {i}: {', '.join(parts)}")
+    crit = sched["critical_path"]
+    lines.append(f"critical path: {' → '.join(crit)}  ({sched['critical_path_len']} tasks)")
+    tops = [s for s, tier in sched["tiers"].items() if tier == "top"]
+    mids = [s for s, tier in sched["tiers"].items() if tier == "mid"]
+    lines.append(f"tier hint: top → {', '.join(tops)}; mid → {', '.join(mids) or '(none)'}")
+    for s in sched["blocked"]:
+        lines.append(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+    return lines
+
+
 def cmd_waves(args: argparse.Namespace) -> None:
     """READ-ONLY DAG scheduler: print the topological waves, critical path, advisory tier hint,
-    and blocked set. With no --milestone it spans EVERY active milestone (cross-active-waves);
-    a single target / --milestone renders byte-identically. Writes nothing; no `next:` footer."""
+    and blocked set. With no --milestone it spans EVERY active milestone (cross-active-waves)
+    as SEPARATE streams; a single target / --milestone renders byte-identically. With --merge it
+    unifies the active SET into ONE schedule so cross-milestone deps order, not block.
+    Writes nothing; no `next:` footer."""
     is_json = getattr(args, "json", False)
     if is_json:
         _, state = _load_state_for_json()
     else:
         state = load_state(_require_root())
     mslug_arg = getattr(args, "milestone", None)
+    if getattr(args, "merge", False):
+        if mslug_arg:                                  # explicit target → a 1-milestone merge (NOT a conflict)
+            if mslug_arg not in (state.get("milestones") or {}):
+                _die(f"unknown_milestone: '{mslug_arg}' is not a milestone in this project")
+            targets = [mslug_arg]
+        else:
+            primary = _active_milestone(state)
+            if not primary:
+                _die("no_active_milestone: no active milestone and no --milestone given")
+            targets = [primary] + [m for m in (state.get("active_milestones") or [])
+                                   if m != primary]
+        sched = _wave_schedule_merged(state, targets)
+        if "cycle" in sched:
+            _die(f"dependency_cycle: not-done deps form a cycle "
+                 f"({' -> '.join(sched['cycle'])}) — no valid schedule")
+        if is_json:
+            print(json.dumps({"merged": targets, **sched}))
+        else:
+            print("\n".join(_wave_block_lines_merged(state, targets, sched)))
+        return
     if mslug_arg:
         targets = [mslug_arg]                          # explicit single target — unchanged
     else:
@@ -3389,7 +2943,7 @@ def cmd_milestone_done(args: argparse.Namespace) -> None:
     # Stamp WHO closed it BEFORE rendering the retro, so the persisted exit report records
     # the closer (identity-in-status: the retro IS the report `report <ms>` re-renders, so both
     # must reflect the same final state). In-memory only here — save_state below commits it.
-    state["milestones"][slug]["done_actor"] = _actor_stamp(state)
+    state["milestones"][slug]["done_actor"] = identity._actor_stamp(state)
     # 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.
@@ -3589,6 +3143,11 @@ def cmd_activate(args: argparse.Namespace) -> None:
         _die("unknown_milestone")
     if state["milestones"][slug].get("status") == "done":
         _die("milestone_done")
+    # PROMOTE a queued milestone: activating it flips queued→active (human-gated promotion —
+    # the chosen verb, reusing `activate` rather than a separate `promote`). An already-active
+    # milestone is just refocused (status unchanged), keeping the default path byte-identical.
+    if state["milestones"][slug].get("status") == "queued":
+        state["milestones"][slug]["status"] = "active"
     _activate_milestone(state, slug)
     save_state(root, state)
     print(f"activated '{slug}' — active: {', '.join(state['active_milestones'])}")
@@ -3692,165 +3251,14 @@ def _sync_task_marker(root: Path, slug: str, phase: str) -> None:
 # state.json; prose (observe delta, deltas) is parsed from each TASK.md and
 # fails CLOSED to `(unknown)` rather than omitting silently.
 
-_DEFAULT_WIDTH = 72       # fixed width for the persisted/canonical render (RETRO.md)
 # Two glyph tiers. Alignment is correct only with ASCII in column-positioned
 # cells (every ASCII char is 1 display cell); Unicode glyphs sit at line-END
 # (the PROGRESS track) or in non-aligned rows, where width can't break columns.
 _UNICODE = {"reached": "●", "current": "◉", "pending": "○", "h": "═", "rule": "─", "bullet": "•"}
 _ASCII = {"reached": "#", "current": ">", "pending": ".", "h": "=", "rule": "-", "bullet": "*"}
 _GATE_SHORT = {"PASS": "PASS", "RISK-ACCEPTED": "RISK", "HARD-STOP": "STOP", "none": "—"}
-_ANSI = {"green": "\x1b[32m", "yellow": "\x1b[33m", "red": "\x1b[31m",
-         "dim": "\x1b[2m", "reset": "\x1b[0m"}
-
-
-def _bar(num: int, den: int, cells: int, g: dict) -> str:
-    """A progress bar; 0/0 -> all-empty (no divide-by-zero)."""
-    filled = 0 if den <= 0 else round(num / den * cells)
-    filled = max(0, min(cells, filled))
-    return g["reached"] * filled + g["pending"] * (cells - filled)
-
-
-def _phase_track(phase: str, g: dict) -> str:
-    """Compact 9-cell pipeline (no labels — a single legend explains it):
-    reached · current · pending. A done task -> all reached."""
-    try:
-        ci = PHASES.index(phase)
-    except ValueError:
-        ci = 0
-    cells = []
-    for i in range(len(PHASES)):
-        if phase == "done" or i < ci:
-            cells.append(g["reached"])
-        elif i == ci:
-            cells.append(g["current"])
-        else:
-            cells.append(g["pending"])
-    return "".join(cells)
-
-
-def _use_ascii() -> bool:
-    """ASCII tier when the terminal can't render Unicode (non-UTF-8 / dumb)."""
-    enc = (getattr(sys.stdout, "encoding", "") or "").lower()
-    return ("utf" not in enc) or (os.environ.get("TERM") == "dumb")
-
-
-def _color_enabled() -> bool:
-    """Color only on an interactive tty, honoring NO_COLOR and TERM."""
-    return (sys.stdout.isatty() and not os.environ.get("NO_COLOR")
-            and os.environ.get("TERM", "") not in ("dumb", ""))
-
-
-def _term_width() -> int:
-    try:
-        import shutil
-        return min(max(shutil.get_terminal_size().columns, 64), 100)
-    except Exception:
-        return _DEFAULT_WIDTH
-
-
-def _colorize(s: str) -> str:
-    """Apply ANSI to status tokens — redundant to the text, never the sole signal.
-    Applied ONLY to tty stdout; the persisted RETRO.md string stays plain."""
-    c = _ANSI
-    s = re.sub(r"\bDONE\b", c["green"] + "DONE" + c["reset"], s)
-    s = re.sub(r"\bBLOCKED\b", c["red"] + "BLOCKED" + c["reset"], s)
-    s = re.sub(r"\bPASS\b", c["green"] + "PASS" + c["reset"], s)
-    s = re.sub(r"\bRISK\b", c["yellow"] + "RISK" + c["reset"], s)
-    s = re.sub(r"\bSTOP\b", c["red"] + "STOP" + c["reset"], s)
-    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 _project_autonomy_token(root: Path):
-    """The RAW autonomy declaration in PROJECT.md — a recognized rung, None when no
-    declaration line is present, or "?" for a real-but-unrecognized token. Uses the
-    anchored _autonomy_level (a title/prose substring is never a declaration) with
-    HTML comments stripped. Unreadable foundation -> None. Read-only and PURE."""
-    try:
-        text = (root / "PROJECT.md").read_text(encoding="utf-8")
-    except OSError:
-        return None
-    return _autonomy_level(re.sub(r"<!--.*?-->", "", text, flags=re.S))
-
-
-def _project_autonomy(root: Path) -> str:
-    """The autonomy rung a new task INHERITS from the project default. Fail-SAFE:
-    no declaration -> "auto" (the method default; v7: absent = auto); an unrecognized
-    token -> "conservative" (NEVER silently "auto"); an unreadable foundation -> "auto".
-    Read-only and PURE — mirrors _project_goal; the seed source for cmd_new_task."""
-    tok = _project_autonomy_token(root)
-    return "auto" if tok is None else ("conservative" if tok == "?" else tok)
-
-
-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
-    if not f.exists():
-        return "(unknown)", "(unknown)"
-    title, goal = "(unknown)", "(unknown)"
-    for line in f.read_text(encoding="utf-8").splitlines():
-        if line.startswith("# MILESTONE:"):
-            title = line.split(":", 1)[1].strip() or "(unknown)"
-        elif line.startswith("goal:"):
-            goal = line.split(":", 1)[1].strip() or "(unknown)"
-            break
-    return title, goal
-
-
-def _exit_criteria(root: Path, mslug: str) -> tuple[int, int]:
-    """(met, total) checkbox tally inside MILESTONE.md's 'Exit criteria' section."""
-    f = root / "milestones" / mslug / MILESTONE_FILE
-    if not f.exists():
-        return 0, 0
-    m = re.search(r"## Exit criteria.*?(?=\n## |\Z)", f.read_text(encoding="utf-8"), 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
-
-
 # A non-empty `(verify: <citation>)` on an exit-criterion line — at least one non-whitespace
 # char inside, so a bare `(verify:)`/`(verify: )` does NOT count (the mid-text substring trap).
-_VERIFY_CITE_RE = re.compile(r"\(verify:\s*\S.*?\)", re.I)
-
-
-def _exit_criteria_cited(root: Path, mslug: str) -> tuple[int, int]:
-    """(cited, total) over MILESTONE.md's 'Exit criteria' section. total = every
-    `- [ ]`/`- [x]` criterion line; cited = those carrying a NON-EMPTY
-    `(verify: <citation>)`. Read-only and PURE; missing file/section -> (0, 0).
-    Mirrors _exit_criteria (the checkbox tally) — an ADDITIVE classification beside
-    it; it never touches `milestone_goal_unmet`."""
-    f = root / "milestones" / mslug / MILESTONE_FILE
-    if not f.exists():
-        return 0, 0
-    m = re.search(r"## Exit criteria.*?(?=\n## |\Z)", f.read_text(encoding="utf-8"), re.S)
-    if not m:
-        return 0, 0
-    cited = total = 0
-    for ln in m.group(0).splitlines():
-        if re.match(r"\s*- \[[ x]\]", ln):
-            total += 1
-            if _VERIFY_CITE_RE.search(ln):
-                cited += 1
-    return cited, total
-
-
 def _goal_auto_ready(root: Path, mslug: str) -> bool:
     """True iff the milestone goal is AUTO-READY: its Exit criteria has >= 1 criterion
     AND every one cites a verifier (cited == total) — so the engine can self-verify the
@@ -3860,32 +3268,6 @@ def _goal_auto_ready(root: Path, mslug: str) -> bool:
     return total >= 1 and cited == 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
@@ -3895,93 +3277,6 @@ def _graduation_ready(root: Path, state: dict) -> tuple[bool, int, int]:
     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 _primary_test_files(root: Path, slug: str) -> list[Path]:
-    """The PRIMARY test set — *.py directly in the task's tests/ dir (the stable
-    path). A list so the tamper tripwire can hash exactly what the engine counts."""
-    d = root / "tasks" / slug / "tests"
-    if not d.is_dir():
-        return []
-    return sorted(d.glob("*.py"))
-
-
-def _tests_count(root: Path, slug: str) -> int:
-    return sum(_count_test_defs(f) for f in _primary_test_files(root, slug))
-
-
-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_test_files(root: Path, slug: str) -> list[Path]:
-    """Resolve the §4 'Tests live in:' declared path(s) to a deduped file list. PURE.
-    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 yields the *.py files directly inside it; resolved files are deduped.
-    v2 confinement: every path must resolve inside the project root — '..' traversal,
-    absolute tokens, and symlink escapes are all dropped, 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 []
-    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 files
-
-
-def _declared_tests_count(root: Path, slug: str) -> int:
-    """Count tests at the §4 'Tests live in:' declared path(s). PURE, fail-closed 0."""
-    return sum(_count_test_defs(f) for f in _declared_test_files(root, slug))
-
-
-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 _resolved_test_files(root: Path, slug: str) -> list[Path]:
     """The file set the engine treats as this task's tests — the PRIMARY set wins
     when it yields any test defs, else the §4-declared set (mirrors _tests_info's
@@ -3992,19 +3287,6 @@ def _resolved_test_files(root: Path, slug: str) -> list[Path]:
     return _declared_test_files(root, slug)
 
 
-def _md5_text(s: str) -> str:
-    return hashlib.md5(s.encode("utf-8")).hexdigest()
-
-
-def _md5_file(p: Path) -> str | None:
-    """md5 of a file's bytes; None on ANY read error (fail-closed — a tracked file
-    that cannot be read counts as DIVERGED at the gate, never a crash)."""
-    try:
-        return hashlib.md5(p.read_bytes()).hexdigest()
-    except OSError:
-        return None
-
-
 def _tripwire_snapshot(root: Path, slug: str, raw3: str) -> dict:
     """Freeze the md5 of the resolved red test files + the frozen §3 contract — the
     tamper baseline (verify-integrity). Keys are project-root-relative paths (stable
@@ -4058,31 +3340,6 @@ _SCOPE_EXCLUDE_SUFFIXES = (".pyc", ".tsbuildinfo")
 # OPT-IN + DEGRADE-SAFE: with no .add/components.toml every reader is byte-identical to
 # pre-component ADD. A read NEVER raises (absent/unreadable/malformed → {} / dropped
 # cover); the loud surface is _component_findings, consumed by the scope gate (cmd_check).
-def _components(root: Path) -> dict[str, dict]:
-    """The registry from .add/components.toml → {name: {root, verify, green_bar,
-    language}}. `root` required per entry; an entry missing it is skipped (the finding
-    surface reports it). `verify` is stored OPAQUE — parsed as data, NEVER executed. PURE."""
-    if tomllib is None:
-        return {}
-    try:
-        raw = (root / "components.toml").read_bytes()
-    except OSError:
-        return {}
-    try:
-        data = tomllib.loads(raw.decode("utf-8"))
-    except (tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for name, spec in (data.get("component") or {}).items():
-        # "?" is the reserved unknown-binding sentinel (_task_component) — a component
-        # named "?" would collide and silently drop cover, so it never registers.
-        if name == "?" or not isinstance(spec, dict) or not isinstance(spec.get("root"), str):
-            continue
-        out[name] = {"root": spec["root"], "verify": spec.get("verify"),
-                     "green_bar": spec.get("green_bar"), "language": spec.get("language")}
-    return out
-
-
 def _component_root(root: Path, name: str) -> str | None:
     """Project-root-relative path (trailing '/') of component `name`'s root, or None
     when the name is absent OR the root escapes the project (fail-closed — grants no
@@ -4120,22 +3377,6 @@ def _task_green_bar(root: Path, slug: str) -> str | None:
     return (_components(root).get(comp) or {}).get("green_bar") or None
 
 
-def _cite_region(body: str) -> str:
-    """The user-authored "Build expectations" evidence region of a §6 body, stamp-stripped —
-    the only place a per-component green-bar cite counts (per-component-verify, v3). PURE.
-
-    The marker matches BOTH template shapes: the standard "### Build expectations …" heading AND
-    the fast-lane bare "Build expectations (from …):" line, running up to the GATE RECORD sub-block.
-    So the top-of-§6 checklist ("- [ ] all tests pass") and the "Outcome: <PASS|…>" placeholder are
-    excluded, and a component-bound FAST task is still citable. The trailing strip removes the
-    engine's own "component: … · expected green-bar: …" stamp wherever it landed, so a stamp that
-    fell inside the region can never self-satisfy the gate. No marker -> "" (fail-closed for a bound
-    task: it must declare its evidence)."""
-    m = re.search(r"(?im)^#*[ \t]*Build expectations\b.*?(?=\n#+[ \t]*GATE RECORD\b|\Z)", body, re.DOTALL)
-    region = m.group(0) if m else ""
-    return re.sub(r"(?m)^component:.*·.*expected green-bar:.*$", "", region)
-
-
 def _component_findings(root: Path) -> list[tuple[str, str]]:
     """The loud gate surface for the registry — the codes a degrade-safe read passes
     over silently. Consumed by cmd_check (the scope_violation surface). [] when clean."""
@@ -4178,46 +3419,6 @@ def _component_findings(root: Path) -> list[tuple[str, str]]:
 # ── cross-component contracts (cross-component-contract) ──────────────────────────────────
 # OPT-IN + DEGRADE-SAFE, like the component readers: no [contract.*] / no produces|consumes
 # header ⇒ every path below is byte-identical to pre-contract ADD. A read NEVER raises.
-def _contracts(root: Path) -> dict[str, dict]:
-    """[contract.<id>] from .add/components.toml -> {id: {producer: str, consumers: list[str]}}.
-    A malformed entry (producer not a str) is skipped (the finding surface reports it). PURE."""
-    if tomllib is None:
-        return {}
-    try:
-        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
-    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for cid, spec in (data.get("contract") or {}).items():
-        if not isinstance(spec, dict) or not isinstance(spec.get("producer"), str):
-            continue
-        cons = spec.get("consumers")
-        out[cid] = {"producer": spec["producer"],
-                    "consumers": [c for c in cons if isinstance(c, str)] if isinstance(cons, list) else []}
-    return out
-
-
-def _federation(root: Path) -> dict[str, dict]:
-    """[federation.<id>] from .add/components.toml -> {id: {source: str, pin: str|None}}.
-    The cross-REPO join: a consumer repo names where a producer repo's published snapshot lives.
-    A malformed entry (no string source) is skipped; a non-string `pin` degrades to None. Degrade-safe
-    — never raises. PURE. On Python < 3.11 (no tomllib) this returns {} like the other component
-    readers, so `federate` reports federation_unknown — components.toml needs a 3.11+ runtime."""
-    if tomllib is None:
-        return {}
-    try:
-        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
-    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for fid, spec in (data.get("federation") or {}).items():
-        if not isinstance(spec, dict) or not isinstance(spec.get("source"), str):
-            continue
-        pin = spec.get("pin")
-        out[fid] = {"source": spec["source"], "pin": pin if isinstance(pin, str) else None}
-    return out
-
-
 def _task_produces(root: Path, slug: str) -> str | None:
     m = _PRODUCES_LINE_RE.search(_task_header(root, slug))
     return m.group(1).strip() if m else None
@@ -4228,10 +3429,6 @@ def _task_consumes(root: Path, slug: str) -> str | None:
     return m.group(1).strip() if m else None
 
 
-def _contract_snapshot(root: Path, cid: str) -> Path:
-    return root / "contracts" / f"{cid}.json"
-
-
 def _contract_body_hash(raw3: str) -> str:
     """md5 of the §3 contract SHAPE — the first ```fenced``` block, whitespace-normalized. The
     version stamp + freeze flags are excluded (fallback strips Status:/flag/change-request lines)
@@ -4304,18 +3501,6 @@ def _declared_scope(root: Path, slug: str) -> list[str] | None:
     return out
 
 
-def _in_scope(rel: str, declared: list[str]) -> bool:
-    """True when rel falls under any declared token — exact match for a file
-    token, whole-subtree prefix containment for a directory token ('…/')."""
-    for tok in declared:
-        if tok.endswith("/"):
-            if rel.startswith(tok) or rel == tok.rstrip("/"):
-                return True
-        elif rel == tok:
-            return True
-    return False
-
-
 def _scope_walk(rootp: Path) -> dict[str, str]:
     """{project-root-relative path: md5} over the project tree, pruning
     _SCOPE_EXCLUDE_DIRS at any depth and skipping bytecode/OS junk +
@@ -4446,6 +3631,28 @@ def _heal_or_escalate(root: Path, state: dict, slug: str, *, reason: str, source
     raise SystemExit(3)                       # redo signal (distinct from _die's 1, argparse's 2)
 
 
+def _consumer_stale_guard(root: Path, state: dict, slug: str) -> None:
+    """Refuse a COMPLETING gate when a `consumes:` task's pinned producer contract hash is STALE
+    (the producer re-froze a CHANGED shape since the pin) — the consumer built against an
+    out-of-date contract (consumer-stale-gate, the gate twin of cmd_check's contract_consumer_stale
+    warning). Recoverable, not a cheat: re-pin by re-crossing contract->tests after reviewing the
+    new frozen shape. Degrade-safe — an unreadable/missing live snapshot is NOT decided here (it
+    stays a cmd_check warning + the advance-time contract_snapshot_missing HARD-STOP); only a
+    CONFIRMED hash drift blocks. Placed with the other completing guards, BEFORE the waiver write,
+    so a stale pin is never launderable through RISK-ACCEPTED; HARD-STOP never reaches here."""
+    pin = state["tasks"][slug].get("contract_pin")
+    if not pin:
+        return
+    try:
+        live = json.loads(_contract_snapshot(root, pin["id"]).read_text(encoding="utf-8")).get("hash")
+    except (OSError, ValueError, KeyError, TypeError, AttributeError):
+        return  # unreadable -> surfaced by cmd_check, not confirmable as stale here
+    if live is not None and live != pin.get("hash"):
+        _die(f"contract_consumer_stale: task '{slug}' pinned contract '{pin['id']}' changed shape "
+             "since the pin (the producer re-froze) — re-pin by re-crossing contract->tests after "
+             "reviewing the producer's new frozen shape; never complete against a stale contract")
+
+
 def _tamper_guard(root: Path, state: dict, slug: str) -> None:
     """HARD-STOP a COMPLETING gate when the tripwire shows tampering — the method's
     first mechanical cheat block (verify-integrity). Tri-state, co-witnessed by
@@ -4472,89 +3679,6 @@ def _tamper_guard(root: Path, state: dict, slug: str) -> None:
                           reason="tamper_detected:" + ",".join(diffs), source="tamper")
 
 
-def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
-    """(observe_delta, [delta lines]) from the task's TASK.md §7 — captured at FULL
-    fidelity: both fields wrap across physical lines in real files, so continuation
-    lines are JOINED. Scoped to the OBSERVE section so we read the FIELD, not §1 prose
-    that names it. Fail-closed to '(unknown)' on a missing file / `<...>` placeholder."""
-    f = root / "tasks" / slug / "TASK.md"
-    if not f.exists():
-        return "(unknown)", []
-    text = f.read_text(encoding="utf-8")
-    m7 = re.search(r"##\s*7\s*·\s*OBSERVE.*\Z", text, re.S)
-    section = m7.group(0) if m7 else text
-    lines = section.splitlines()
-    # observe: prefer the first OPEN SPEC delta from the "### Spec delta" block; fall
-    # back to the legacy "Spec delta for the next loop:" free-text field (archived
-    # tasks predate the block); else "(unknown)".
-    observe = "(unknown)"
-    for unit in _spec_delta_entries(section):
-        m = _SPEC_DELTA_RE.match(unit[0])
-        if m.group(2) != "open":
-            continue
-        tail = " ".join([m.group(3).strip(), *unit[1:]]).strip()
-        em = _EVIDENCE_RE.match(tail)
-        first = (em.group(1).strip() if em else tail)
-        if first and not first.startswith("<"):
-            observe = first
-            break
-    if observe == "(unknown)":
-        for i, ln in enumerate(lines):
-            m = re.match(r"\s*Spec delta for the next loop:\s*(.*)", ln)
-            if not m:
-                continue
-            parts = [m.group(1).strip()]
-            for nxt in lines[i + 1:]:
-                t = nxt.strip()
-                if not t or t.startswith("#") or t.startswith("- ") or t.startswith("Watch"):
-                    break
-                parts.append(t)
-            joined = " ".join(p for p in parts if p).strip()
-            if joined and not joined.startswith("<"):
-                observe = joined
-            break
-
-    # deltas: each "- [COMP · status] ..." plus its indented continuation lines
-    deltas, i = [], 0
-    while i < len(lines):
-        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_RE.match(lines[j]):
-                break
-            parts.append(t)
-            j += 1
-        deltas.append(f"{m.group(1)} · {m.group(2)} · {' '.join(parts).strip()}")
-        i = j
-    return observe, deltas
-
-
-def _clip(s: str, maxlen: int) -> str:
-    """Trim a string to fit a fixed-width frame, ellipsizing if it overruns."""
-    return s if len(s) <= maxlen else s[:maxlen - 1].rstrip() + "…"
-
-
-def _wrap(text: str, width: int, label: str) -> list[str]:
-    """Wrap `text` to `width`; the first line carries `label`, continuations are
-    blank-indented to the same width (so a multi-line goal shows 'goal' once)."""
-    cont = " " * len(label)
-    lines, cur = [], ""
-    for w in text.split():
-        if cur and len(cur) + 1 + len(w) > width:
-            lines.append(cur)
-            cur = w
-        else:
-            cur = f"{cur} {w}".strip()
-    if cur:
-        lines.append(cur)
-    lines = lines or ["(unknown)"]
-    return [(label if i == 0 else cont) + ln for i, ln in enumerate(lines)]
-
-
 def report_data(root: Path, state: dict, mslug: str) -> dict:
     """The single source of FACTS for a milestone report — pure, NO writes.
     Both the text dashboard (render_report) and `report --json` render from this,
@@ -4636,43 +3760,6 @@ def _clean_phase_body(body: str) -> str:
     return "\n".join(lines) if meaningful else "(empty)"
 
 
-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)."""
-    lines = text.splitlines()
-    head = re.compile(r"^##\s*(\d+)\s*·")
-    starts: dict[int, int] = {}
-    for idx, ln in enumerate(lines):
-        m = head.match(ln)
-        if m:
-            n = int(m.group(1))
-            if 0 <= n <= 7 and n not in starts:
-                starts[n] = idx
-    out: dict[int, str] = {}
-    for n, idx in starts.items():
-        body_lines = []
-        for ln in lines[idx + 1:]:
-            if re.match(r"^##\s", ln) or re.match(r"^---\s*$", ln):
-                break
-            body_lines.append(ln)
-        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 §0–§7 into eight
     blocks ground→observe. PURE — NO writes. Each entry is
@@ -5259,10 +4346,6 @@ _DELTA_STATUSES = ("open", "folded", "rejected")
 # 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*$")
 
 # SPEC-delta track — a SEPARATE resolution lifecycle from the competency deltas
 # above. SPEC shares the "- [TAG · status]" LINE shape but its statuses are
@@ -5271,9 +4354,6 @@ _EVIDENCE_RE = re.compile(r"^(.*?)\s*\(evidence:\s*(.*?)\)\s*$")
 # tag to its legal status set so the ONE lint can reject a cross-set pairing
 # ([SPEC · folded], [SDD · seeded]) without a parallel grammar.
 _SPEC_STATUSES = ("open", "seeded", "dropped")
-_SPEC_DELTA_RE = re.compile(
-    r"\s*-\s*\[\s*(SPEC)\s*·\s*(open|seeded|dropped)\s*\]\s*(.+)$"
-)
 _STATUS_SETS = {**{c: _DELTA_STATUSES for c in _COMPETENCY_ORDER}, "SPEC": _SPEC_STATUSES}
 
 # Broad structural tag detector: finds ANY "- [tok · tok]" line (valid OR malformed).
@@ -5429,32 +4509,6 @@ def _collect_open_deltas(root: Path) -> dict[str, list[dict]]:
     return by_comp
 
 
-def _spec_delta_entries(text: str) -> list[list[str]]:
-    """Group a "### Spec delta" block into entries (tag line + continuation lines).
-
-    Same grouping discipline as _collect_open_deltas' competency pass, keyed on
-    _SPEC_DELTA_RE: a tag line starts an entry; a non-"- " line continues it; a
-    blank/comment or a new "- " item ends it. Returns [] when the block is absent."""
-    bm = re.search(r"###\s*Spec delta\s*\n(.*?)(?=\n##|\Z)", text, re.S)
-    if not bm:
-        return []
-    entries: list[list[str]] = []
-    current: list[str] | None = None
-    for line in bm.group(1).splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("<!--"):
-            current = None
-            continue
-        if _SPEC_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 entry
-        else:
-            current = None                   # a new / malformed list item ends the run
-    return entries
-
-
 def _collect_open_spec_deltas(root: Path) -> list[dict]:
     """Scan every .add/tasks/*/TASK.md "### Spec delta" block for OPEN SPEC deltas.
 
@@ -5782,6 +4836,15 @@ def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
         elif gate != "none" and outcomes[0] != gate:
             f(slug, "gate_record_mismatch",
               f"§6 records {outcomes[0]} but state.json records {gate}")
+        elif gate == "none":
+            # F13 ungated_verdict: §6 carries a verdict the engine never gated.
+            # cmd_gate is the ONLY writer of `gate` (it also marks done), so a
+            # done/observe task at gate=="none" reached its verdict without the
+            # engine — a hand-stamped §6 or an `advance` past verify. Constraint 4
+            # requires a RECORDED outcome; a §6 verdict without one is not trusted.
+            f(slug, "ungated_verdict",
+              f"§6 records {outcomes[0]} but state.json recorded no gate (gate=none) — "
+              f"the verdict was written without the engine 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)
@@ -5967,12 +5030,6 @@ def cmd_graduation_report(args: argparse.Namespace) -> None:
     print("\n".join(L))
 
 
-def _releases_path(root: Path) -> Path:
-    """The append-only release ledger — at the PROJECT ROOT (root IS the .add dir, so its
-    parent), a sibling of CHANGELOG.md. NOT inside .add/."""
-    return root.parent / RELEASES_FILE
-
-
 def _released_milestones(root: Path) -> set[str]:
     """Slugs already attributed to a release — the union of every `milestones:` row in
     RELEASES.md. Fail-OPEN: a missing/unreadable/malformed ledger yields the empty set, so
@@ -5993,21 +5050,6 @@ def _released_milestones(root: Path) -> set[str]:
     return out
 
 
-def _closed_milestones(state: dict) -> list[dict]:
-    """Every CLOSED milestone (its milestone-done gate passed): LIVE done milestones
-    (status == 'done', still in state) + ARCHIVED milestones (all were PASS-done before
-    archive — see _archived_task_slugs). Each: {slug, title, tier}."""
-    out: list[dict] = []
-    for slug, m in (state.get("milestones") or {}).items():
-        if m.get("status") == "done":
-            out.append({"slug": slug, "title": m.get("title", slug), "tier": "live"})
-    for rec in state.get("archived") or []:
-        if rec.get("slug"):
-            out.append({"slug": rec["slug"], "title": rec.get("title", rec["slug"]),
-                        "tier": "archived"})
-    return out
-
-
 def _releasable(root: Path, state: dict) -> list[dict]:
     """Closed milestones NOT yet attributed to any RELEASES.md row — the cut's candidate
     bundle. Drives BOTH the `→ releasable: N` status cue and release-report. READ-ONLY."""
@@ -6015,19 +5057,38 @@ def _releasable(root: Path, state: dict) -> list[dict]:
     return [m for m in _closed_milestones(state) if m["slug"] not in released]
 
 
-def _key_decisions_for(root: Path, slug: str) -> list[str]:
-    """Best-effort §Key-Decisions rows from PROJECT.md that NAME this milestone slug — the
-    consolidated decisions the changelog can cite. Fail-open: a missing section / unreadable
-    foundation / no slug match -> [] (a gather never raises). READ-ONLY."""
+def _released_loose_tasks(root: Path) -> set[str]:
+    """Slugs already attributed to a release as LOOSE tasks — the union of every
+    `loose tasks:` row in RELEASES.md. The exact parallel of _released_milestones:
+    fail-OPEN (a missing/unreadable/malformed ledger yields the empty set, so every
+    done loose task reads as still-releasable). READ-ONLY."""
     try:
-        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+        text = _releases_path(root).read_text(encoding="utf-8")
     except OSError:
-        return []
-    m = re.search(r"^#{1,6}[^\n]*key decision[^\n]*$(.*?)(?=^#{1,6}\s|\Z)", text, re.S | re.M | re.I)
-    if not m:
-        return []
-    return [st.lstrip("-* ").strip() for st in (ln.strip() for ln in m.group(1).splitlines())
-            if st.startswith(("-", "*")) and slug in st]
+        return set()                         # no ledger -> nothing released yet
+    out: set[str] = set()
+    for line in text.splitlines():
+        st = line.strip()
+        if st.lower().startswith("loose tasks:"):
+            for tok in re.split(r"[,\s]+", st.split(":", 1)[1]):
+                tok = tok.strip()
+                if tok and tok.lower() != "none":
+                    out.add(tok)
+    return out
+
+
+def _releasable_loose_tasks(root: Path, state: dict) -> list[dict]:
+    """Done milestone-free tasks NOT yet attributed to any RELEASES.md `loose tasks:` row —
+    the loose half of the cut's candidate bundle, peer to _releasable. A loose task is a
+    first-class releasable item: milestone-free (a standalone, fast OR full) AND done (a
+    completing gate). Drives the loose status cue + release_data["loose"]. READ-ONLY."""
+    released = _released_loose_tasks(root)
+    out: list[dict] = []
+    for slug, t in (state.get("tasks") or {}).items():
+        if (isinstance(t, dict) and t.get("milestone") is None and _task_done(t)
+                and slug not in released):
+            out.append({"slug": slug, "title": t.get("title", slug)})
+    return out
 
 
 def release_data(root: Path, state: dict) -> dict:
@@ -6092,15 +5153,19 @@ def release_data(root: Path, state: dict) -> dict:
                 monitors.append({"slug": slug, "watch": st})
                 break
 
+    # loose — done milestone-free tasks not yet attributed (the cut's loose bundle, peer to releasable)
+    loose = _releasable_loose_tasks(root, state)
+
     return {
         "releasable": releasable,
         "changed": changed,
         "waivers": waivers,
         "blockers": blockers,
         "monitors": monitors,
+        "loose": loose,
         "summary": {
             "releasable": len(releasable), "changed": len(changed), "waivers": len(waivers),
-            "blockers": len(blockers), "monitors": len(monitors),
+            "blockers": len(blockers), "monitors": len(monitors), "loose": len(loose),
         },
     }
 
@@ -6144,14 +5209,6 @@ def cmd_release_report(args: argparse.Namespace) -> None:
     print("\n".join(L))
 
 
-def _build_in_flight(state: dict) -> bool:
-    """release_tests_red proxy (PURE): is any ACTIVE task mid-build without a recorded green gate
-    — phase ∈ {build, verify} AND gate == 'none'? The tool-agnostic engine never runs the suite,
-    so an entered-but-ungated build is the recorded-evidence stand-in for 'the suite is red'."""
-    return any(t.get("phase") in ("build", "verify") and t.get("gate") == "none"
-               for t in (state.get("tasks") or {}).values())
-
-
 def _prepend_block(existing: str, header: str, block: str) -> str:
     """Newest-first prepend: insert `block` directly under the top H1 `header`, creating the
     header when `existing` is empty / headerless. Existing content is preserved VERBATIM
@@ -6164,37 +5221,6 @@ def _prepend_block(existing: str, header: str, block: str) -> str:
     return f"{block}{existing}"               # no recognized header -> block goes on top, verbatim tail
 
 
-def _render_changelog_block(version: str, day: str, bundle: list[dict],
-                            changed_by_slug: dict) -> str:
-    """A CHANGELOG block: `## <version> — <date>` + one bullet per bundled milestone (title +
-    carried-delta / key-decision counts from release_data['changed'])."""
-    lines = [f"## {version} — {day}", ""]
-    if bundle:
-        for m in bundle:
-            c = changed_by_slug.get(m["slug"], {})
-            lines.append(f"- {m['title']} — {c.get('carried_deltas', 0)} carried · "
-                         f"{len(c.get('key_decisions', []))} key decision(s)")
-    else:
-        lines.append("- (no milestone bundled)")
-    return "\n".join(lines) + "\n\n"
-
-
-def _render_releases_row(version: str, day: str, bundle: list[dict],
-                         waiver_slugs: list[str], evidence: str | None,
-                         actor: str | None = None) -> str:
-    """One append-only RELEASES.md row — the attribution source (`milestones:` membership).
-    The `actor:` line records WHO cut the release (structured-actor stamping); absent on a
-    legacy row (back-compat) when no actor is supplied."""
-    ms = ", ".join(m["slug"] for m in bundle) if bundle else "none"
-    wv = ", ".join(waiver_slugs) if waiver_slugs else "none"
-    actor_line = f"actor: {actor}\n" if actor else ""
-    return (f"## {version} — {day}\n"
-            f"milestones: {ms}\n"
-            f"waivers: {wv}\n"
-            f"{actor_line}"
-            f"evidence: {evidence or 'recorded by add.py release'}\n\n")
-
-
 def cmd_release(args: argparse.Namespace) -> None:
     """GUARDED, record-only: cut a version. Enforce the 4-code readiness floor, then RECORD by
     prepending CHANGELOG.md + an append-only RELEASES.md row (whose `milestones:` line attributes
@@ -6218,9 +5244,11 @@ def cmd_release(args: argparse.Namespace) -> None:
         _die("release_tests_red: a build is in flight without a recorded green gate — finish and "
              "gate it first, or pass --force to override.")
     bundle = _releasable(root, state)
-    if not forced and not bundle:
+    loose_bundle = _releasable_loose_tasks(root, state)
+    if not forced and not bundle and not loose_bundle:
         _die("release_no_closed_milestone: nothing closed-and-unreleased to bundle — the cut "
-             "would be a no-op. Close a milestone first, or pass --force to override.")
+             "would be a no-op. Close a milestone (or a standalone task) first, or pass --force "
+             "to override.")
     if not forced and d["waivers"] and not disclosed:
         _die("release_undisclosed_waiver: a RISK-ACCEPTED waiver rides into this release — pass "
              "--with-waivers to disclose it in the notes, or --force to override.")
@@ -6238,7 +5266,7 @@ def cmd_release(args: argparse.Namespace) -> None:
     new_rel = _prepend_block(rel_before, "# Releases",
                              _render_releases_row(args.version, day, bundle, waiver_slugs,
                                                   getattr(args, "evidence", None),
-                                                  _render_actor_line(state)))
+                                                  identity._render_actor_line(state), loose_bundle))
     try:                                              # CHANGELOG + RELEASES as one all-or-nothing commit
         _atomic_write_many([(changelog_path, new_cl), (releases_path, new_rel)])
     except OSError as e:
@@ -6247,7 +5275,9 @@ def cmd_release(args: argparse.Namespace) -> None:
 
     # NO save_state — attribution lives in RELEASES.md (the cue re-reads it), never state.json
     ms = ", ".join(m["slug"] for m in bundle) if bundle else "none"
-    print(f"released {args.version} — recorded {len(bundle)} milestone(s): {ms}")
+    lt = ", ".join(t["slug"] for t in loose_bundle) if loose_bundle else "none"
+    print(f"released {args.version} — recorded {len(bundle)} milestone(s): {ms} "
+          f"+ {len(loose_bundle)} loose task(s): {lt}")
     print("  CHANGELOG.md + RELEASES.md updated (project root). The engine records; "
           "you run the tag / publish / deploy.")
     if forced:
@@ -6422,6 +5452,14 @@ def build_parser() -> argparse.ArgumentParser:
     pl.add_argument("--json", action="store_true", help="emit one JSON object instead of text")
     pl.set_defaults(func=cmd_lock)
 
+    pfz = sub.add_parser("freeze",
+                         help="freeze a task's §3 contract (the human approval) — stamps "
+                              "FROZEN @ vN + a structured actor on the task record")
+    pfz.add_argument("slug", nargs="?", default=None,
+                     help="task to freeze (default: the active task)")
+    pfz.add_argument("--by", default=None, help="approver name (default: the resolved actor)")
+    pfz.set_defaults(func=cmd_freeze)
+
     pwho = sub.add_parser("whoami",
                           help="show / set the git-native actor (git config -> OS user; --name to override)")
     # --name (set) and --unset (clear) are mutually exclusive — argparse rejects the
@@ -6481,6 +5519,10 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--goal", default=None, help="one-sentence outcome")
     pm.add_argument("--stage", default="mvp", choices=STAGES)
     pm.add_argument("--force", action="store_true", help="overwrite MILESTONE.md if present")
+    pm.add_argument("--queued", action="store_true",
+                    help="create the milestone QUEUED (status=queued), not active: it is recorded "
+                         "and its MILESTONE.md written, but the active focus is unchanged. Promote it "
+                         "later with `activate <slug>`. Foundation for roadmap intake (1 active + N queued).")
     pm.add_argument("--await-confirm", action="store_true",
                     help="opt into the confirm-parent gate: seed the milestone unconfirmed so "
                          "new-task is held until `milestone-confirm` (mirrors `init --await-lock`); "
@@ -6501,6 +5543,8 @@ def build_parser() -> argparse.ArgumentParser:
                                        "waves + critical path + advisory tier hint")
     pwa.add_argument("--milestone", default=None,
                      help="milestone slug to schedule (default: the active milestone)")
+    pwa.add_argument("--merge", action="store_true",
+                     help="unify the active SET into ONE schedule (cross-milestone deps order, not block)")
     pwa.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pwa.set_defaults(func=cmd_waves)
 
@@ -6568,6 +5612,13 @@ def build_parser() -> argparse.ArgumentParser:
                      help="confirm a RAISE toward auto (a human-owned trust escalation)")
     pan.set_defaults(func=cmd_autonomy, _opt_positionals=("a1", "a2"))
 
+    pto = sub.add_parser("todo", help="capture / list / close a lightweight backlog todo (jot an idea)")
+    pto.add_argument("text", nargs="?", default=None,
+                     help="todo text to capture; omit to LIST open todos")
+    pto.add_argument("--done", type=int, default=None, metavar="ID",
+                     help="close an open todo by id")
+    pto.set_defaults(func=cmd_todo)
+
     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
@@ -6614,6 +5665,8 @@ def build_parser() -> argparse.ArgumentParser:
     pmine.add_argument("--actor", default=None, metavar="\"Name <email>\"",
                        help="inspect another actor's queue instead of your own")
     pmine.add_argument("--json", action="store_true", help="emit one JSON object instead of text")
+    pmine.add_argument("--all", action="store_true",
+                       help="widen past the active SET: every milestone + loose tasks, not just active")
     pmine.set_defaults(func=cmd_mine)
 
     pwv = sub.add_parser("wave-verify",
@@ -6739,16 +5792,6 @@ def _rebind_optional_positionals(parser: argparse.ArgumentParser,
 # silently does nothing and nothing is lost. It NEVER changes a command's stdout or exit.
 _UPDATE_CACHE = ".update-cache.json"
 _UPDATE_TTL = timedelta(hours=24)          # hit the registry at most once / day
-_REGISTRY_LATEST = "https://registry.npmjs.org/@pilotspace/add/latest"
-
-
-def _read_json_safe(path: Path):
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-
-
 def _write_json_safe(path: Path, obj) -> None:
     try:
         path.write_text(json.dumps(obj, indent=2) + "\n", encoding="utf-8")
@@ -6756,33 +5799,6 @@ def _write_json_safe(path: Path, obj) -> None:
         pass
 
 
-def _version_gt(a: str, b: str) -> bool:
-    """True if version a is newer than b (dotted numeric; prerelease suffix dropped)."""
-    def key(v: str):
-        out = []
-        for part in str(v).split("."):
-            part = part.split("-", 1)[0]
-            out.append((0, int(part)) if part.isdigit() else (1, part))
-        return out
-    try:
-        return key(a) > key(b)
-    except Exception:
-        return False
-
-
-def _fetch_latest_version(timeout: float = 1.5):
-    """GET the registry's latest version. Returns a string, or None on ANY failure
-    (offline, timeout, bad payload) — the caller treats None as 'unknown, skip'."""
-    try:
-        req = urllib.request.Request(_REGISTRY_LATEST, headers={"Accept": "application/json"})
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            data = json.loads(resp.read().decode("utf-8"))
-        v = data.get("version")
-        return v if isinstance(v, str) and v else None
-    except Exception:
-        return None
-
-
 def _cached_latest(add_dir: Path):
     """The registry's latest version, throttled: served from .update-cache.json within
     the TTL, else refreshed over the network (fail-open). None when unknown."""