@caddis/cli 0.2.6 → 0.3.0

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

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""caddis_inventory — enumerate what EXISTS in a repo, so a handover stops being a memory test.
+
+WHY
+---
+A succession prompt used to be composed from what the outgoing session remembered to mention.
+Anything it forgot, the incoming session never learned — and the incoming session cannot know what
+it was not told. Bringing one Hub to a usable state took **nine** corrective round trips, and the
+user caught six of the nine (`.caddis/parking-lot/004-handover-is-recalled-not-generated.md`).
+
+Look at what the user caught, because the pattern is the whole argument:
+
+    "the handover listed no reports, documents, KB notes or scripts"
+    "planned future work is absent"
+    "which prompt exists — the legacy one or the contract-shaped one?"
+
+None of those are judgement calls. Every one is a directory listing. They were missed because the
+agent was recalling *what it did* rather than enumerating *what exists*, and those are different
+sets. A generator cannot forget the report it never wrote.
+
+WHAT THIS IS NOT
+----------------
+This does not write the handover. Judgement — what matters, what to do next, what nearly went
+wrong — is the outgoing session's job and cannot be derived from disk. This produces the half that
+can be, so the human-written half is all judgement and no clerical work.
+
+STALENESS IS MEASURED IN COMMITS, NOT MTIMES
+--------------------------------------------
+A git checkout stamps every file with the checkout time, so mtimes say nothing about whether a
+generated report predates the feature it should describe. Last-commit time does. That exact failure
+is item 8 of the nine: reports committed before a feature was added and never rebuilt.
+
+Usage:
+  python scripts/caddis_inventory.py                    # markdown to stdout
+  python scripts/caddis_inventory.py --format json      # machine-readable
+  python scripts/caddis_inventory.py --with-tests       # also RUN the suite (never quote a
+                                                        # remembered test count — one handover
+                                                        # claimed 20 when there were 19)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+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")
+
+ART = ".caddis"
+
+# Artefact kinds worth enumerating, and what a reader needs from each. Order matters: it is the
+# order a reader wants them in, not alphabetical.
+PLAN_DIRS = ("plans", "prd", "prompts", "handoffs", "agent-docs")
+
+
+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=30)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def frontmatter(path: Path) -> dict[str, str]:
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore").lstrip("")
+    except OSError:
+        return {}
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    out: dict[str, str] = {}
+    for line in text[3:end if end > 0 else 800].splitlines():
+        if ":" in line and not line.startswith((" ", "\t")):
+            k, _, v = line.partition(":")
+            out[k.strip()] = v.strip()
+    return out
+
+
+def title_of(path: Path) -> str:
+    """First markdown H1, else the filename. What a reader scans for."""
+    try:
+        for line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
+            if line.startswith("# "):
+                return line[2:].strip()
+    except OSError:
+        pass
+    return path.stem
+
+
+@dataclass
+class Inventory:
+    repo: str = ""
+    branch: str = ""
+    uncommitted: int = 0
+    unpushed: int = 0
+    artifacts: dict[str, list[dict]] = field(default_factory=dict)
+    parking_lot: list[dict] = field(default_factory=list)
+    kb: list[dict] = field(default_factory=list)
+    comms_open: list[dict] = field(default_factory=list)
+    scripts: list[dict] = field(default_factory=list)
+    stale_artifacts: list[dict] = field(default_factory=list)
+    environment_map: str = "missing"
+    tests: str = "not measured — run the suite, never quote a remembered number"
+
+
+def scan_artifacts(root: Path) -> dict[str, list[dict]]:
+    out: dict[str, list[dict]] = {}
+    for kind in PLAN_DIRS:
+        d = root / ART / kind
+        if not d.is_dir():
+            continue
+        rows = []
+        for f in sorted(d.glob("*.md")):
+            if f.name.lower() == "readme.md":
+                continue
+            fm = frontmatter(f)
+            rows.append({"file": f"{ART}/{kind}/{f.name}",
+                         "title": title_of(f),
+                         "status": fm.get("status", "(none)")})
+        done = len(list((d / "done").glob("*.md"))) if (d / "done").is_dir() else 0
+        if rows or done:
+            out[kind] = rows
+            if done:
+                out[kind].append({"file": f"{ART}/{kind}/done/", "title": f"{done} finished",
+                                  "status": "archived"})
+    return out
+
+
+def scan_parking_lot(root: Path) -> list[dict]:
+    """The backlog. Listed separately from plans because a reader's question is different:
+    plans ask "what is running?", the parking lot asks "what did we agree to do and have not?"."""
+    d = root / ART / "parking-lot"
+    if not d.is_dir():
+        return []
+    rows = []
+    for f in sorted(d.glob("*.md")):
+        if f.name.lower() == "readme.md":
+            continue
+        fm = frontmatter(f)
+        rows.append({"file": f.name, "title": title_of(f),
+                     "status": fm.get("status", "(none)"),
+                     "severity": fm.get("severity", ""),
+                     "future": fm.get("future", "")})
+    # committed work first, then by severity — the order a reader needs, not the filesystem's
+    order = {"high": 0, "medium": 1, "low": 2, "": 3}
+    rows.sort(key=lambda r: (r["future"].lower() != "yes", order.get(r["severity"].lower(), 3)))
+    return rows
+
+
+def scan_kb(root: Path) -> list[dict]:
+    d = root / ART / "kb"
+    if not d.is_dir():
+        return []
+    return [{"file": f"{ART}/kb/{f.name}", "title": title_of(f)}
+            for f in sorted(d.glob("*.md")) if f.name != "DOC-MAP.md"]
+
+
+def environment_map_state(root: Path) -> str:
+    """`missing`, `empty` or `filled` — surfaced because an absent environment map is invisible.
+
+    Every other gap in a handover shows up as a section with nothing under it. This one shows up as
+    nothing at all, which reads exactly like "there was nothing to say". One session searched the
+    filesystem for a repository that lived in Gitea while the project's own docs cited a file inside
+    it by path — the fact existed, it just had no shelf.
+    """
+    f = root / ART / "kb" / "environment-map.md"
+    if not f.is_file():
+        return "missing"
+    try:
+        text = f.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return "missing"
+    # The scaffolded template is all headings and "(none recorded yet)" placeholders. A file that
+    # still carries every placeholder has never been filled in, and saying "present" would be a lie
+    # of exactly the kind this whole item is about.
+    return "empty" if "_(none recorded yet)_" in text and text.count("|") < 60 else "filled"
+
+
+def scan_comms(root: Path) -> list[dict]:
+    """Rows in the comms register that are not yet ACTIONED or DROPPED — an ask nobody is chasing
+    is indistinguishable from a forgotten one, which is the whole reason that register exists."""
+    reg = root / ART / "comms" / "register.md"
+    if not reg.is_file():
+        return []
+    out = []
+    for line in reg.read_text(encoding="utf-8", errors="ignore").splitlines():
+        if not line.startswith("|") or line.startswith("|---") or "_(none yet)_" in line:
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if len(cells) < 4 or cells[0].lower() in ("raised", "status"):
+            continue
+        status = cells[3].strip("`").upper()
+        if status in ("DRAFT", "SENT", "ANSWERED"):
+            out.append({"raised": cells[0], "audience": cells[1],
+                        "subject": cells[2], "status": status})
+    return out
+
+
+def scan_scripts(root: Path) -> list[dict]:
+    """Every script and the first line of its docstring. A handover that omits these makes the
+    next session re-discover the tooling it already owns."""
+    d = root / "scripts"
+    if not d.is_dir():
+        return []
+    out = []
+    for f in sorted(d.glob("*.py")):
+        first = ""
+        try:
+            text = f.read_text(encoding="utf-8", errors="ignore")
+            m = re.search(r'^\s*"""(.+?)$', text, re.M)
+            if m:
+                first = m.group(1).strip().rstrip('"')
+        except OSError:
+            pass
+        out.append({"file": f"scripts/{f.name}", "purpose": first})
+    return out
+
+
+# A path literal, not a bare filename. Requiring a directory separator is what stops a script that
+# merely MENTIONS "README.md" in a docstring from being reported as that file's generator — the
+# first version of this did exactly that, and a check with obvious false positives gets switched off
+# before it ever catches a real one.
+_OUTPUT_LITERAL = re.compile(r'["\']((?:[\w.-]+/)+[\w.-]+\.(?:html|json|csv|svg|png|md))["\']')
+# Names that are always somebody else's file, never a generated artefact.
+_NEVER_GENERATED = {"README.md", "AGENTS.md", "CLAUDE.md", "package.json", "pyproject.toml"}
+# A generator often builds its output path from parts (`_HERE.parent / ".caddis" / "page.html"`),
+# so the literal in the source is a bare filename. Accept that shape too, but ONLY for artefact
+# extensions and ONLY when the file really sits in the artefact dir — a bare `.md` literal is
+# almost always prose, which is how the README false positive got in.
+_BARE_ARTIFACT = re.compile(r'["\']([\w.-]+\.(?:html|json|csv|svg|png))["\']')
+
+
+def stale_artifacts(root: Path) -> list[dict]:
+    """Generated files whose last commit PREDATES their generator's last commit.
+
+    Pairing needs no new convention to maintain: a generator names the file it writes, so grepping
+    each script for a path literal that actually exists on disk finds the pair. A manifest would be
+    more precise and would rot the first time nobody updated it.
+
+    Uses git commit times, never mtimes — see the module docstring.
+    """
+    d = root / "scripts"
+    if not d.is_dir() or not (root / ".git").exists():
+        return []
+    out = []
+    for script in sorted(d.glob("*.py")):
+        try:
+            text = script.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        candidates = set(_OUTPUT_LITERAL.findall(text))
+        candidates |= {f"{ART}/{n}" for n in _BARE_ARTIFACT.findall(text)
+                       if (root / ART / n).is_file()}
+        for m in sorted(candidates):
+            if Path(m).name in _NEVER_GENERATED:
+                continue
+            target = root / m
+            if not target.is_file():
+                continue
+            t_art = _run(["git", "log", "-1", "--format=%ct", "--", m], root)
+            t_gen = _run(["git", "log", "-1", "--format=%ct", "--", f"scripts/{script.name}"], root)
+            if not t_art or not t_gen:
+                continue
+            if int(t_art) < int(t_gen):
+                out.append({"artifact": m, "generator": f"scripts/{script.name}",
+                            "behind_seconds": int(t_gen) - int(t_art)})
+    return out
+
+
+def collect(root: Path, with_tests: bool = False) -> Inventory:
+    inv = Inventory(repo=root.name)
+    inv.branch = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"], root)
+    inv.uncommitted = len([l for l in _run(["git", "status", "--short"], root).splitlines() if l])
+    upstream = _run(["git", "rev-parse", "--abbrev-ref", "@{upstream}"], root)
+    if upstream:
+        inv.unpushed = len(_run(["git", "log", "--oneline", f"{upstream}..HEAD"], root).splitlines())
+    inv.artifacts = scan_artifacts(root)
+    inv.parking_lot = scan_parking_lot(root)
+    inv.kb = scan_kb(root)
+    inv.comms_open = scan_comms(root)
+    inv.scripts = scan_scripts(root)
+    inv.stale_artifacts = stale_artifacts(root)
+    inv.environment_map = environment_map_state(root)
+    if with_tests:
+        # Run it. A handover once claimed 20 tests when there were 19, and the incoming Hub found
+        # the discrepancy before anyone else did.
+        out = _run([sys.executable, "-m", "pytest", "-q", "--tb=no"], root)
+        tail = [l for l in out.splitlines() if "passed" in l or "failed" in l]
+        inv.tests = tail[-1] if tail else "suite did not report a summary — investigate"
+    return inv
+
+
+def _table(rows: list[dict], cols: list[tuple[str, str]]) -> list[str]:
+    head = "| " + " | ".join(c[0] for c in cols) + " |"
+    sep = "|" + "|".join("---" for _ in cols) + "|"
+    body = ["| " + " | ".join(str(r.get(c[1], "") or "") for c in cols) + " |" for r in rows]
+    return [head, sep, *body, ""]
+
+
+def render_md(inv: Inventory) -> str:
+    L: list[str] = [
+        f"# Repository inventory — {inv.repo}", "",
+        "> Generated by `scripts/caddis_inventory.py`. **Do not hand-edit.** Everything here is a",
+        "> directory listing, not a judgement — regenerate it rather than correcting it. The",
+        "> judgement half of a handover (what matters, what nearly went wrong, what to do next) is",
+        "> written by a human or an agent and belongs above this section, not inside it.", "",
+        f"**Branch** `{inv.branch}` · **uncommitted** {inv.uncommitted} file(s) · "
+        f"**unpushed** {inv.unpushed} commit(s)", "",
+        f"**Tests:** {inv.tests}", "",
+    ]
+    if inv.environment_map != "filled":
+        why = ("does not exist" if inv.environment_map == "missing"
+               else "exists but has never been filled in")
+        L += [f"> **Environment map {why}.** Hosts, which login actually works, where other",
+              "> repositories really live — none of it is written down, so the next session starts",
+              "> from zero and asks you again. Write what you know to",
+              f"> `{ART}/kb/environment-map.md` before handing over.", ""]
+    if inv.stale_artifacts:
+        L += ["## ⚠ Generated artefacts older than their generator", "",
+              "Each of these was committed BEFORE the script that builds it last changed, so it may",
+              "describe a state that no longer exists. Rebuild before quoting any of them.", ""]
+        L += _table(inv.stale_artifacts, [("Artefact", "artifact"), ("Built by", "generator")])
+    for kind, rows in inv.artifacts.items():
+        if not rows:
+            continue
+        L += [f"## {kind}", ""] + _table(rows, [("File", "file"), ("Title", "title"),
+                                                ("Status", "status")])
+    if inv.parking_lot:
+        L += ["## Parking lot — the backlog", "",
+              "Committed work (`future: yes`) first, then by severity.", ""]
+        L += _table(inv.parking_lot, [("Item", "file"), ("Severity", "severity"),
+                                      ("Future", "future"), ("Status", "status")])
+    if inv.kb:
+        L += ["## KB notes", ""] + _table(inv.kb, [("File", "file"), ("Title", "title")])
+    if inv.comms_open:
+        L += ["## Outbound comms still open", "",
+              "Anything not yet ACTIONED or DROPPED. An unanswered ask looks exactly like a",
+              "forgotten one unless something tracks it.", ""]
+        L += _table(inv.comms_open, [("Raised", "raised"), ("Audience", "audience"),
+                                     ("Subject", "subject"), ("Status", "status")])
+    if inv.scripts:
+        L += ["## Scripts", ""] + _table(inv.scripts, [("Script", "file"), ("Purpose", "purpose")])
+    return "\n".join(L) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--repo-root", default=".")
+    ap.add_argument("--format", choices=("md", "json"), default="md")
+    ap.add_argument("--with-tests", action="store_true",
+                    help="RUN the suite and report its real result instead of a placeholder")
+    a = ap.parse_args(argv)
+    root = Path(a.repo_root).resolve()
+    inv = collect(root, with_tests=a.with_tests)
+    if a.format == "json":
+        print(json.dumps(inv.__dict__, indent=2))
+    else:
+        print(render_md(inv), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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())