@pilotspace/add 1.9.0 → 1.11.0

package/tooling/add_engine/guidelines.py

@@ -0,0 +1,252 @@
+"""add_engine.guidelines — the guidelines / CLAUDE.md-injection subsystem (engine-modularization 8/N).
+
+Inject one stable, marker-delimited ADD block into the project root's AGENTS.md and
+CLAUDE.md. DYNAMIC-BY-REFERENCE: the block tells the agent to run `add.py status` and
+read PROJECT.md — it never embeds live state. A closed, self-contained cluster (8 fns +
+the cluster-private _INIT_EXCLUDE); transitive-closure AST scan: ZERO outbound calls to
+non-cluster add fns. Deps: constants + _atomic_write (io_state) + stdlib. None patched.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+from add_engine.constants import (
+    GUIDELINE_FILES, RULES_FILE_REL, WORKFLOW_HEADINGS,
+    _GUIDE_BEGIN, _GUIDE_END, _RULE_REF_LINE,
+)
+from add_engine.io_state import _atomic_write
+
+
+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())

package/tooling/add_engine/identity.py

@@ -0,0 +1,107 @@
+"""add_engine.identity — the git-native actor/identity seam (engine-modularization 6/N).
+
+The 7 identity/actor functions, moved verbatim from add.py: git/OS actor resolution
+(`_git_config` · `_os_user` · `_whoami`), the structured stamp every human-written
+action records (`_actor_stamp` · `_render_actor_line`), and ownership parsing/matching
+(`_parse_actor_arg` · `_actor_matches`).
+
+NOT a pure-move leaf: add.py commands call `_whoami` BOTH directly and via `_actor_stamp`,
+so add.py QUALIFIES its call sites to `identity._whoami(...)` and the identity tests patch
+`add_engine.identity.<name>` — one target that reaches every call path (direct + internal).
+Stdlib-only deps (getpass/re/shutil/subprocess); no add_engine imports (a leaf).
+"""
+from __future__ import annotations
+
+import getpass
+import re
+import shutil
+import subprocess
+
+
+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()

package/tooling/add_engine/io_state.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""add_engine.io_state — low-level IO + state primitives for the ADD engine.
+
+The 4 atomic-write primitives (designed for failure: temp-then-rename, no silent
+clobber, all-or-nothing for the many-writer). Extracted from add.py (engine-
+modularization 2/N); add.py re-exports them as module globals so callers and
+monkeypatch sites (`add._atomic_write = spy`) keep resolving unchanged.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from add_engine.constants import ROOT_DIRNAME, STATE_FILE
+
+_CONFLICT_MARKER_RE = re.compile(r"(?m)^(<{7}|={7}|>{7})")  # git merge-conflict markers in state
+
+
+# --- low-level IO (designed for failure: atomic, no silent clobber) ----------
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+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")
+    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
+    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)
+
+
+# --- root finding + state load/save + the shared error primitive ------------
+
+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
+
+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 _die(msg: str, code: int = 1) -> None:
+    print(f"add: error: {msg}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+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 _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

package/tooling/add_engine/milestones.py

@@ -0,0 +1,108 @@
+"""add_engine.milestones — MILESTONE.md / state milestone readers (engine-modularization 10/N).
+
+Goal, exit-criteria (and how many cite verify-evidence), stage-criteria, all-milestones-done,
+and the production-roadmap check. A closed, unpatched cluster (transitive-closure AST = zero
+outbound). The cluster-private _VERIFY_CITE_RE lives here. Deps: constants + stdlib (no add).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from add_engine.constants import GOAL_UNSET, MILESTONE_FILE
+
+_VERIFY_CITE_RE = re.compile(r"\(verify:\s*\S.*?\)", re.I)
+
+
+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 _project_goal(root: Path) -> str:
+    """The project GOAL — the value of the first `goal:` line in PROJECT.md, else
+    GOAL_UNSET. Read-only and fail-closed: a missing/unreadable foundation or a
+    blank value degrades to the sentinel (orientation never raises). Mirrors how
+    _milestone_doc reads the milestone goal — the foundation is the single source."""
+    f = root / "PROJECT.md"
+    try:
+        for line in f.read_text(encoding="utf-8").splitlines():
+            if line.startswith("goal:"):
+                return line.split(":", 1)[1].strip() or GOAL_UNSET
+    except OSError:
+        pass
+    return GOAL_UNSET
+
+def _milestone_doc(root: Path, mslug: str) -> tuple[str, str]:
+    """(title, goal) from MILESTONE.md; ('(unknown)','(unknown)') if the doc is gone."""
+    f = root / "milestones" / mslug / MILESTONE_FILE
+    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
+
+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 _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())