@caddis/cli 0.2.6 → 0.4.0

package/bundles/antigravity-plugin/scripts/caddis_migrate_dir.py

@@ -0,0 +1,270 @@
+"""caddis_migrate_dir — rename a repo's legacy `.claudster/` artifact dir to `.caddis/`.
+
+The `.claudster` → `.caddis` rename is OPT-IN, per repo, and never automatic: `git mv`-ing a
+directory under a concurrent session would move files out from under its in-flight writes (a Stop
+hook appending `usage-log.jsonl`, an agent writing a plan). So the SessionStart hook only *nudges*;
+this command does the work when you say so.
+
+Everything keeps working either way — every caddis reader tries `.caddis` then `.claudster`, and
+every writer writes where the repo already lives. Migration is about consistency, not function.
+
+Behavior (per target repo):
+  • SIMPLE CASE — only `.claudster/` exists: one `git mv .claudster .caddis` (history preserved).
+  • BOTH EXIST (the straggler case — an out-of-date session or teammate recreated `.claudster/`
+    after a migration): per-CHILD merge into `.caddis/`. A child that exists only in the legacy dir
+    is moved. A child that exists in BOTH is merged by kind:
+      - `.jsonl` append-logs (usage-log / agent-log / memory)  → CONCATENATED, legacy lines FIRST
+        (they are older), so no session's history is dropped;
+      - directories → recursed, same rules;
+      - anything else → left in place and REPORTED (a human decides; we never clobber content).
+    An emptied `.claudster/` is removed at the end; one with unresolved conflicts is kept.
+  • LIVE REFS are rewritten so the migrated repo's own artifacts don't point at the old dir:
+    `.caddis/workstreams.json` (parked-workstream plan paths) and `relay.md`.
+  • Idempotent: a re-run on a migrated repo is a no-op. `--dry-run` is the DEFAULT (`--apply`
+    executes). Refuses a dirty tree unless `--allow-dirty` — the git mv must be reviewable.
+
+Usage:
+    python scripts/caddis_migrate_dir.py [target]           # dry-run (default)
+    python scripts/caddis_migrate_dir.py [target] --apply   # execute
+    python scripts/caddis_migrate_dir.py [target] --check   # exit 1 if a legacy dir remains (gate)
+
+Exit codes: 0 ok / nothing to do · 1 unresolved conflicts (or --check found a legacy dir) · 2 bad
+target / not a git repo / dirty tree.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+NEW_DIR = ".caddis"
+OLD_DIR = ".claudster"
+
+#: Append-only JSONL logs: safe to concatenate when both dirs carry one (legacy lines first).
+JSONL_MERGE_NAMES = frozenset({"usage-log.jsonl", "agent-log.jsonl", "memory.jsonl"})
+
+#: Files whose CONTENT may name the old dir and is read live after the migration. Historical
+#: artifacts (plans, handoffs, past reviews) are deliberately NOT rewritten — they are a record of
+#: what was true then, and rewriting them would churn the diff for no functional gain.
+LIVE_REF_FILES = ("workstreams.json", "relay.md")
+
+
+# ── git helpers (mirrors claudster_migrate_rules.py) ─────────────────────────
+def _git(target: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=str(target), capture_output=True, text=True)
+
+
+def _in_git_repo(target: Path) -> bool:
+    r = _git(target, "rev-parse", "--is-inside-work-tree")
+    return r.returncode == 0 and r.stdout.strip() == "true"
+
+
+def _is_dirty(target: Path) -> bool:
+    return bool(_git(target, "status", "--porcelain").stdout.strip())
+
+
+def _is_tracked(target: Path, rel: str) -> bool:
+    return _git(target, "ls-files", "--error-unmatch", "--", rel).returncode == 0
+
+
+def _move(target: Path, src_rel: str, dst_rel: str, apply: bool, report: list[str]) -> None:
+    """Move one path, preferring `git mv` so history follows the file."""
+    report.append(f"move: {src_rel} -> {dst_rel}")
+    if not apply:
+        return
+    dst = target / dst_rel
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if _is_tracked(target, src_rel) and _git(target, "mv", src_rel, dst_rel).returncode == 0:
+        return
+    # untracked (or git mv refused): a plain move keeps the content; git sees add+delete
+    shutil.move(str(target / src_rel), str(dst))
+
+
+# ── merge (the both-exist case) ──────────────────────────────────────────────
+def _concat_jsonl(old: Path, new: Path, apply: bool) -> int:
+    """Prepend `old`'s lines to `new` (legacy is older). Returns the number of lines merged.
+
+    Blank lines are dropped and a trailing newline is guaranteed, so a half-written last line in
+    either file can't glue two records together.
+    """
+    old_lines = [ln for ln in old.read_text(encoding="utf-8", errors="replace").splitlines() if ln.strip()]
+    if not apply:
+        return len(old_lines)
+    new_lines = [ln for ln in new.read_text(encoding="utf-8", errors="replace").splitlines() if ln.strip()]
+    new.write_text("\n".join(old_lines + new_lines) + "\n", encoding="utf-8")
+    return len(old_lines)
+
+
+def _merge_tree(target: Path, old_rel: str, new_rel: str, apply: bool,
+                report: list[str], conflicts: list[str]) -> None:
+    """Merge `<old_rel>/` into `<new_rel>/`, child by child. Both are repo-relative posix paths."""
+    old_dir = target / old_rel
+    for child in sorted(old_dir.iterdir()):
+        c_old = f"{old_rel}/{child.name}"
+        c_new = f"{new_rel}/{child.name}"
+        dest = target / c_new
+        if not dest.exists():
+            _move(target, c_old, c_new, apply, report)
+            continue
+        if child.is_dir() and dest.is_dir():
+            _merge_tree(target, c_old, c_new, apply, report, conflicts)
+            continue
+        if child.is_file() and dest.is_file() and child.name in JSONL_MERGE_NAMES:
+            n = _concat_jsonl(child, dest, apply)
+            report.append(f"merge: {c_old} -> {c_new} ({n} legacy line(s), oldest first)")
+            if apply:
+                _remove(target, c_old)
+            continue
+        conflicts.append(c_old)
+        report.append(f"CONFLICT: {c_old} and {c_new} both exist and cannot be merged — left in place")
+
+
+def _remove(target: Path, rel: str) -> None:
+    """Delete a merged-away file, via `git rm` when tracked so the index stays consistent."""
+    if _is_tracked(target, rel) and _git(target, "rm", "-q", "-f", "--", rel).returncode == 0:
+        return
+    try:
+        (target / rel).unlink()
+    except OSError:
+        pass
+
+
+def _prune_empty(target: Path, rel: str) -> bool:
+    """Remove `<rel>` if it is now empty (depth-first). True when it is gone."""
+    d = target / rel
+    if not d.is_dir():
+        return True
+    for child in sorted(d.iterdir()):
+        if child.is_dir():
+            _prune_empty(target, f"{rel}/{child.name}")
+    try:
+        d.rmdir()
+        return True
+    except OSError:
+        return False
+
+
+# ── live-reference rewriting ─────────────────────────────────────────────────
+def rewrite_refs_text(text: str) -> str:
+    """Replace `.claudster/` path prefixes with `.caddis/` in a live artifact's text. Pure.
+
+    Only the dir followed by a separator is rewritten, so prose about "the .claudster rename"
+    survives intact while `.claudster/plans/foo.md` becomes `.caddis/plans/foo.md`. Backslash
+    separators are handled too — a Windows-written workstreams.json can carry either.
+    """
+    return (text.replace(f"{OLD_DIR}/", f"{NEW_DIR}/")
+                .replace(f"{OLD_DIR}\\", f"{NEW_DIR}\\"))
+
+
+def rewrite_live_refs(target: Path, apply: bool, report: list[str]) -> None:
+    """Rewrite `.claudster/...` paths inside the migrated dir's live state files."""
+    for name in LIVE_REF_FILES:
+        p = target / NEW_DIR / name
+        if not p.is_file():
+            continue
+        original = p.read_text(encoding="utf-8", errors="replace")
+        updated = rewrite_refs_text(original)
+        if updated == original:
+            continue
+        n = original.count(f"{OLD_DIR}/")
+        report.append(f"rewrite: {NEW_DIR}/{name} ({n} legacy path ref(s) -> {NEW_DIR}/)")
+        if apply:
+            p.write_text(updated, encoding="utf-8")
+    # workstreams.json must stay valid JSON — verify, and roll back the rewrite if it doesn't.
+    ws = target / NEW_DIR / "workstreams.json"
+    if apply and ws.is_file():
+        try:
+            json.loads(ws.read_text(encoding="utf-8"))
+        except Exception:
+            report.append(f"WARNING: {NEW_DIR}/workstreams.json is not valid JSON after rewriting "
+                          "— check it by hand")
+
+
+# ── the migration ────────────────────────────────────────────────────────────
+def migrate(target: Path, apply: bool) -> tuple[int, list[str]]:
+    """Migrate `target`. Returns `(exit_code, report_lines)`."""
+    report: list[str] = []
+    conflicts: list[str] = []
+    old, new = target / OLD_DIR, target / NEW_DIR
+
+    if not old.is_dir():
+        report.append(f"nothing to do: no {OLD_DIR}/ in this repo"
+                      + (f" ({NEW_DIR}/ already present)" if new.is_dir() else ""))
+        return 0, report
+
+    if not new.exists():
+        _move(target, OLD_DIR, NEW_DIR, apply, report)
+    else:
+        report.append(f"both {OLD_DIR}/ and {NEW_DIR}/ exist — merging per child "
+                      "(a straggler dir recreated by an out-of-date session)")
+        _merge_tree(target, OLD_DIR, NEW_DIR, apply, report, conflicts)
+        if apply:
+            if _prune_empty(target, OLD_DIR):
+                report.append(f"removed: empty {OLD_DIR}/")
+            else:
+                report.append(f"kept: {OLD_DIR}/ still holds {len(conflicts)} unmerged path(s)")
+
+    rewrite_live_refs(target, apply, report)
+
+    if conflicts:
+        report.append(f"\n{len(conflicts)} conflict(s) need a human: " + ", ".join(conflicts))
+        return 1, report
+    return 0, report
+
+
+def main(argv: list[str] | None = None) -> int:
+    for _stream in (sys.stdout, sys.stderr):  # Windows cp1252 can't encode the em-dashes below
+        if hasattr(_stream, "reconfigure"):
+            _stream.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(
+        description=f"Migrate a repo's legacy {OLD_DIR}/ artifact dir to {NEW_DIR}/.")
+    ap.add_argument("target", nargs="?", default=".", type=Path)
+    ap.add_argument("--apply", action="store_true", help="Execute (default is --dry-run).")
+    ap.add_argument("--allow-dirty", action="store_true", help="Proceed even if the tree is dirty.")
+    ap.add_argument("--check", action="store_true",
+                    help=f"Report only; exit 1 if {OLD_DIR}/ is still present (gate mode).")
+    args = ap.parse_args(argv)
+
+    target = args.target.resolve()
+    if not target.is_dir():
+        print(f"ERROR: target not a directory: {target}", file=sys.stderr)
+        return 2
+
+    if args.check:
+        if (target / OLD_DIR).is_dir():
+            print(f"  legacy {OLD_DIR}/ present — run /caddis:migrate-dir to convert it.")
+            return 1
+        print(f"No legacy {OLD_DIR}/ — this repo is on {NEW_DIR}/.")
+        return 0
+
+    apply = args.apply
+    if not _in_git_repo(target):
+        print(f"ERROR: {target} is not a git repository (the migration uses git mv to keep history).",
+              file=sys.stderr)
+        return 2
+    # The dirty-tree refusal only applies when there is actually a rename to make — a re-run on an
+    # already-migrated repo is a no-op and must not fail just because the tree has unrelated edits.
+    if apply and (target / OLD_DIR).is_dir() and _is_dirty(target) and not args.allow_dirty:
+        print("ERROR: working tree is dirty — commit/stash first, or pass --allow-dirty.\n"
+              "       (A rename mixed into unrelated edits is unreviewable, and this repo's tree "
+              "may be shared with a live session.)", file=sys.stderr)
+        return 2
+
+    print(f"=== caddis-migrate-dir -> {target} {'(APPLY)' if apply else '(dry-run)'}")
+    rc, report = migrate(target, apply)
+    for line in report:
+        print(f"   {line}")
+    if not apply:
+        print("\n(dry-run — no files changed; pass --apply to execute)")
+    elif rc == 0:
+        print("\nMigrated. Review with `git status` / `git diff --staged`, then commit.")
+    print(f"\nresult: {'CONFLICTS' if rc else 'ok'}")
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/caddis_spawn.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""caddis_spawn — shared machinery for handing work to a fresh session.
+
+WHY THIS IS ONE MODULE AND NOT TWO
+----------------------------------
+`/caddis:spawn-hub` and `/caddis:spawn-session` transfer different things — a validation ROLE and
+the WORK itself — but they fail the same way and defend against it with the same four mechanisms:
+
+  1. capture from the repo, never from recall
+  2. a self-check whose naive answer is WRONG, so a successor that skimmed fails visibly
+  3. no stored answer key: re-derive at validation time, which checks the DOCUMENT as well
+  4. refuse to write anything that goes stale (a commit hash, a test count) as a fact
+
+Built as one module so a fix lands in both. The alternative was already visible in the codebase:
+`succession.md` §J had the trap idea and `spawn-session` was about to grow a second copy of it.
+
+THE FAILURE MODE, PRECISELY
+---------------------------
+A long session does not forget. It **recalls superseded facts fluently**. Measured in one session:
+two throughput figures the agent had itself withdrawn were re-quoted days later; "E8 is blocked on
+F1" was repeated for three days without a re-test; a commit hash written into a handover went stale
+within the hour. None of that is amnesia, and none of it is caught by asking the outgoing agent
+what it knows — because the failure mode IS what it knows.
+
+Usage:
+  python scripts/caddis_spawn.py preflight              # refuse to spawn from an unsafe state
+  python scripts/caddis_spawn.py fingerprint            # head + counts, for stale-paste detection
+  python scripts/caddis_spawn.py check --doc <file>     # round 0: the parent checks its own handover
+  python scripts/caddis_spawn.py verify-question --answer-in <file> --needle <text>
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+EXIT_OK, EXIT_REFUSED = 0, 1
+
+ART = ".caddis"
+SPAWN_DIR = f"{ART}/spawn-session"
+
+
+def _run(args: list[str], cwd: Path) -> str:
+    try:
+        r = subprocess.run(args, cwd=str(cwd), capture_output=True, text=True,
+                           encoding="utf-8", errors="replace", timeout=120)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+# ── things that go stale ────────────────────────────────────────────────────────────────────
+#
+# A 7-to-40 character hex run is a commit hash. A handover that states one as a fact is wrong
+# within the hour — measured twice in one session. The fix is not a fresher hash, it is to write
+# the COMMAND that produces it, so the reader gets today's answer instead of yesterday's.
+_HASH = re.compile(r"(?<![0-9a-zA-Z/])[0-9a-f]{7,40}(?![0-9a-zA-Z/])")
+# "1,066 tests" / "821 passed". Same problem: true when written, false an hour later.
+_COUNT = re.compile(r"\b\d[\d,]*\s+(?:tests?|passed|failed|skipped)\b", re.I)
+
+# A fingerprint is a MEASUREMENT, explicitly stamped at a moment, and it exists precisely so a
+# stale paste can be detected. That is the opposite of a fact stated as durable, so it is exempt.
+#
+# ANCHORED TO `SPAWN`, AND ONLY THAT. The first version also exempted any line starting with
+# `head` — which exempts "HEAD is currently abc1234", the single most common way of writing the
+# exact thing this check exists to catch. Its own test found it. An exemption is a hole in a check,
+# so it gets the narrowest possible shape: the literal first token of `fingerprint_line()`.
+_FINGERPRINT_LINE = re.compile(r"^\s*SPAWN\b", re.I)
+
+
+# THE DISTINCTION THAT KEEPS THIS CHECK SWITCHED ON.
+#
+# A hash naming a PAST commit ("shipped in abc1234") is immutable and perfectly safe. A hash
+# offered as CURRENT STATE ("HEAD is abc1234", "we are currently at abc1234") is wrong within the
+# hour — that is the failure 007 recorded, twice. The first version of this flagged both and
+# produced seven findings on one real handover, every one a historical citation. A check with that
+# hit rate gets switched off before it ever catches the one that matters.
+_CURRENT_STATE = re.compile(
+    r"\b(head|current|currently|latest|now at|tip of|as of now|at present|working tree)\b", re.I)
+
+
+def _is_exempt(line: str, in_fence: bool) -> bool:
+    """Fenced blocks are commands and transcripts — quoting a hash there is the CURE, not the bug."""
+    return in_fence or bool(_FINGERPRINT_LINE.match(line))
+
+
+@dataclass
+class DocFindings:
+    """`stale_prone` refuses; `historical` only advises.
+
+    Two tiers because the cost of each error differs. A current-state hash that goes stale sends
+    the successor to the wrong commit — block it. A historical citation is durable and merely worth
+    a second look — flagging it as a failure is how a check earns a reputation for crying wolf.
+    """
+    stale_prone: list[tuple[int, str]] = field(default_factory=list)
+    historical: list[tuple[int, str]] = field(default_factory=list)
+    missing_paths: list[str] = field(default_factory=list)
+
+    def ok(self) -> bool:
+        return not self.stale_prone and not self.missing_paths
+
+
+_DOC_PATH = re.compile(r"`([^`\s<>{}*?]+?\.(?:md|py|ts|tsx|json|ya?ml|sh|ps1|html|toml|sql))`")
+
+
+def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
+    """Round 0: the parent validates its OWN handover before anyone reads it.
+
+    This is the cheapest round and the one issue 004 is really about. In the manual run a child
+    caught a stale commit hash the parent could have caught alone — a wasted relay trip, and the
+    relay trip is the expensive part of the whole exercise.
+
+    Fails closed: a claim that cannot survive this does not go in the handover.
+    """
+    out = DocFindings()
+    in_fence = False
+    for n, line in enumerate(text.splitlines(), 1):
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            continue
+        if _is_exempt(line, in_fence):
+            continue
+        for m in _HASH.finditer(line):
+            # A bare decimal number is not a hash; require at least one a-f digit so version
+            # strings and dates do not produce a check nobody can ever get to green.
+            if not any(c in "abcdef" for c in m.group(0)):
+                continue
+            if _CURRENT_STATE.search(line):
+                out.stale_prone.append((n, f"commit hash `{m.group(0)}` given as CURRENT state — "
+                                           "wrong within the hour, twice. Write the command "
+                                           "(`git rev-parse --short HEAD`) instead"))
+            else:
+                out.historical.append((n, f"commit hash `{m.group(0)}` — reads as a historical "
+                                          "citation, which is durable. Check that it is not "
+                                          "standing in for current state"))
+        for m in _COUNT.finditer(line):
+            out.stale_prone.append((n, f"`{m.group(0)}` stated as a fact — write the command "
+                                       "instead; this was wrong within the hour, twice"))
+    if repo_root is not None:
+        for raw in sorted(set(_DOC_PATH.findall(text))):
+            cand = next((tok for tok in raw.split() if "/" in tok or tok.endswith(".md")), raw)
+            cand = cand.strip("(),;:'\"")
+            if cand.startswith(("http://", "https://", "~", "$")) or ".." in cand:
+                continue
+            if not (repo_root / cand).exists():
+                out.missing_paths.append(cand)
+    return out
+
+
+# ── refusals ────────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Preflight:
+    refusals: list[str] = field(default_factory=list)
+    dirty: int = 0
+    parking_open: int | None = None
+
+    def ok(self) -> bool:
+        return not self.refusals
+
+
+def preflight(repo_root: Path) -> Preflight:
+    """Conditions under which a spawn must not happen at all.
+
+    A dirty tree is the sharp one: the successor starts by pulling, so **uncommitted work is
+    invisible to it**. It will then either redo that work or build on a state that does not exist.
+    """
+    p = Preflight()
+    status = _run(["git", "status", "--short"], repo_root)
+    p.dirty = len([l for l in status.splitlines() if l.strip()])
+    if p.dirty:
+        p.refusals.append(
+            f"{p.dirty} uncommitted file(s). The successor pulls, so uncommitted work is invisible "
+            "to it — it will redo the work or build on a state that does not exist. Commit first.")
+
+    d = repo_root / ART / "parking-lot"
+    if d.is_dir():
+        p.parking_open = len([f for f in d.glob("*.md") if f.name.lower() != "readme.md"])
+    else:
+        # The count is the INTEGRITY CHECK on the handover: a successor that revives 13 of 15 has
+        # silently dropped two, and nothing else would show it.
+        p.refusals.append(
+            f"no {ART}/parking-lot/ — the open-item count is the integrity check on a handover, "
+            "and without it a dropped item is undetectable.")
+    return p
+
+
+# ── fingerprint ─────────────────────────────────────────────────────────────────────────────
+
+def fingerprint(repo_root: Path, with_tests: bool = False) -> dict:
+    """A stamp the child echoes back, so the parent can spot a stale or mismatched paste.
+
+    NOT a fact for the handover body — a measurement, at a moment, for exactly one purpose.
+    """
+    fp = {
+        "head": _run(["git", "rev-parse", "--short", "HEAD"], repo_root) or "unknown",
+        "branch": _run(["git", "rev-parse", "--abbrev-ref", "HEAD"], repo_root) or "unknown",
+        "parking_open": preflight(repo_root).parking_open,
+        "tests": "not measured",
+    }
+    if with_tests:
+        out = _run([sys.executable, "-m", "pytest", "-q", "--tb=no"], repo_root)
+        tail = [l for l in out.splitlines() if "passed" in l or "failed" in l]
+        fp["tests"] = tail[-1] if tail else "suite reported no summary"
+    return fp
+
+
+def fingerprint_line(fp: dict) -> str:
+    return (f"SPAWN | head {fp['head']} ({fp['branch']}) | parking-lot open {fp['parking_open']} "
+            f"| tests: {fp['tests']}")
+
+
+# ── question answerability ──────────────────────────────────────────────────────────────────
+
+def verify_answerable(repo_root: Path, answer_in: str, needle: str) -> tuple[bool, str]:
+    """A question must be answerable from a COMMITTED file, or it tests memory.
+
+    Testing memory is the thing being replaced, so a question that fails this is not a harder
+    question — it is the old failure wearing an exam's clothes.
+    """
+    path = repo_root / answer_in
+    if not path.is_file():
+        return False, f"{answer_in} does not exist — the answer is not written down anywhere"
+    tracked = _run(["git", "ls-files", "--error-unmatch", answer_in], repo_root)
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError as exc:
+        return False, f"{answer_in} unreadable: {type(exc).__name__}"
+    if needle.lower() not in text.lower():
+        return False, f"{answer_in} does not contain {needle!r} — the answer is not in that file"
+    if not tracked:
+        return True, (f"{answer_in} contains the answer, but is NOT COMMITTED — the successor "
+                      "pulls and will not see it")
+    return True, f"{answer_in} contains {needle!r} and is committed"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name in ("preflight", "fingerprint"):
+        s = sub.add_parser(name)
+        s.add_argument("--repo-root", default=".")
+        if name == "fingerprint":
+            s.add_argument("--with-tests", action="store_true")
+    c = sub.add_parser("check")
+    c.add_argument("--doc", required=True)
+    c.add_argument("--repo-root", default=".")
+    q = sub.add_parser("verify-question")
+    q.add_argument("--answer-in", required=True)
+    q.add_argument("--needle", required=True)
+    q.add_argument("--repo-root", default=".")
+    a = ap.parse_args(argv)
+    root = Path(a.repo_root).resolve()
+
+    if a.cmd == "preflight":
+        p = preflight(root)
+        if p.ok():
+            print(f"[spawn] ready — clean tree, {p.parking_open} open parking-lot item(s)")
+            return EXIT_OK
+        sys.stderr.write("[spawn] REFUSING to spawn:\n")
+        for r in p.refusals:
+            sys.stderr.write(f"    {r}\n")
+        return EXIT_REFUSED
+
+    if a.cmd == "fingerprint":
+        print(fingerprint_line(fingerprint(root, with_tests=a.with_tests)))
+        return EXIT_OK
+
+    if a.cmd == "check":
+        doc = Path(a.doc)
+        if not doc.is_file():
+            sys.stderr.write(f"[spawn] no document at {doc}\n")
+            return EXIT_REFUSED
+        f = check_document(doc.read_text(encoding="utf-8", errors="ignore"), root)
+        for n, msg in f.historical:
+            print(f"  note  line {n}: {msg}")
+        if f.ok():
+            print(f"[spawn] {doc.name} passes round 0 — nothing stale-prone, every path exists")
+            return EXIT_OK
+        sys.stderr.write(f"[spawn] {doc.name} FAILS round 0:\n")
+        for n, msg in f.stale_prone:
+            sys.stderr.write(f"    line {n}: {msg}\n")
+        for p_ in f.missing_paths:
+            sys.stderr.write(f"    names a path that does not exist: {p_}\n")
+        sys.stderr.write("  A claim that cannot be re-derived does not go in the handover.\n")
+        return EXIT_REFUSED
+
+    ok, msg = verify_answerable(root, a.answer_in, a.needle)
+    (print if ok else sys.stderr.write)(f"[spawn] {msg}" + ("" if ok else "\n"))
+    return EXIT_OK if ok else EXIT_REFUSED
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())