@caddis/cli 0.4.68 → 0.4.70

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

@@ -38,6 +38,10 @@ DESIGN (locked, see the plan doc — do not re-litigate here)
   already in a repo never block an unrelated PR. It first refuses when any of those files has an
   uncommitted change (the check would read a file that is not what the PR ships), and a range git
   cannot read prints only that error, never an unfiltered list.
+- `--check` also reports three things it never fixes (tidy v2 Phase 4), each with a one-line fix: untracked
+  crash/scratch files at the repo root (`*.stackdump`, `run*.ps1`, `nul`, ...); a `.caddis/` file whose
+  `type:` belongs to another folder; a plan `status: current` with no commit for 14 days. The first is
+  repo-wide and so never appears under `--commit-range`; the other two follow the range like any file.
 - `--only <plan> [<plan> ...]` limits a run to those top-level plans: nothing else is moved or
   stamped. `/implement` closes the plan it finished with it, so another session's finished work
   is never swept into this PR.
@@ -60,6 +64,7 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import fnmatch
 import os
 import re
 import stat
@@ -84,7 +89,7 @@ except ModuleNotFoundError as exc:
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parent))
     import caddis_todo
-# caddis_todo has put its own dependencies on the path by now; this one ships beside it.
+# caddis_todo (through caddis_workstreams) has put its own dependencies on the path by now; this one ships beside it.
 from caddis_file_lock import atomic_write  # noqa: E402
 
 # No child process opens a console window on Windows (this runs under hooks and status lines that
@@ -155,9 +160,8 @@ def _parse_frontmatter(text: str) -> dict:
 def tracker_complete(text: str) -> bool:
     """True only when the `## Tracker` heading line has phase rows, all unique, all done.
 
-    The table is read by caddis_todo.tracker_table, the same reader the open-work view uses, and
-    a status cell is judged by the same `_is_done`. Stricter here on purpose: that view skips a
-    row it cannot read, while a row this cannot read BLOCKS completion. Wrongly moving a live plan
+    The table is read by caddis_todo.tracker_table, and a status cell is judged by its `_is_done`.
+    Strict on purpose: a row this cannot read BLOCKS completion. Wrongly moving a live plan
     hides it; wrongly keeping a finished one costs a look.
     """
     table = caddis_todo.tracker_table(text)
@@ -471,9 +475,9 @@ class Resolution:
 def _parked_target(root: Path, name: str) -> tuple[Path | None, str | None]:
     """Where a trailer value points: (open item, None), (None, None) when it is already in done/,
     or (None, reason) when it is refused or missing. Only a top-level item of this repo's
-    `.caddis/parking-lot/` is ever a target, named bare, as `parking-lot/<file>` (what
-    `caddis_todo.py done` prints) or by its repo-relative path. The last word is
-    caddis_todo._resolves_path, the check `caddis_todo add --resolves` already applies."""
+    `.caddis/parking-lot/` is ever a target, named bare, as `parking-lot/<file>` (what the
+    retired `caddis_todo.py done` printed) or by its repo-relative path. The last word is
+    caddis_todo._resolves_path."""
     lot = root / ".caddis" / PARKING_LOT_DIR
     posix = name.replace("\\", "/")
     if not posix:
@@ -735,6 +739,116 @@ def _check_parking_lot_item(item: Item, report: Report) -> None:
                                 "into its own file and move the resolved history to done/.")
 
 
+# ── wider --check (tidy v2 Phase 4): report only, nothing here moves or deletes a file ──────────
+# Names that crash tools and one-off scripts leave at a repo root. Each one is a file nobody chose to
+# keep, so an untracked, un-ignored match is a stray. Matched case-insensitively (Windows).
+_STRAY_PATTERNS = (
+    ("*.stackdump", "a Git Bash/Cygwin crash dump"),
+    ("*.tmp", "an editor or tool temp file"),
+    ("*.bak", "a hand-made or tool backup copy"),
+    ("*.orig", "a merge or patch tool's pre-change copy"),
+    ("*.rej", "a rejected patch hunk"),
+    ("run*.ps1", "a one-off launcher script written during a session"),
+    ("tmp*.py", "a throwaway probe script"),
+    ("scratch*", "a scratch file or folder note"),
+    ("nul", "a Windows device name that a bad redirect (`> nul` run from a bash shell) wrote as a real file"),
+)
+STRAY_FIX = "delete it, or add it to .gitignore if it is meant to stay"
+
+# Folder-defining `type:` values -> the `.caddis/` folder that holds them (None: no folder, the file is
+# a root-level one such as relay.md). Only these can be misfiled. Generic types (note, reference, design,
+# analysis, handoff, ...) are legitimately spread over plans/, kb/ and reviews/ in real repos, so they
+# are never flagged. parking-lot/ is left to `_check_parking_lot_item`, which already enforces its type.
+_TYPE_HOME = {
+    "plan": "plans", "prd": "prd", "prompt": "prompts", "review": "reviews", "rca": "rca",
+    "adr": "decisions", "decision": "decisions", "parking-lot": "parking-lot",
+    "relay": None, "session-state": None,
+}
+# The types each known folder accepts of those above. `relay/` holds relays; kb/ accepts none of them.
+_FOLDER_TYPES = {
+    "plans": {"plan"}, "prd": {"prd"}, "prompts": {"prompt"}, "reviews": {"review"}, "rca": {"rca"},
+    "decisions": {"adr", "decision"}, "relay": {"relay"}, "kb": set(),
+}
+STALE_PLAN_DAYS = 14
+
+
+def is_stray_name(name: str) -> bool:
+    """True when a root-level file name matches a crash/scratch pattern."""
+    low = name.lower()
+    return any(fnmatch.fnmatchcase(low, pat) for pat, _ in _STRAY_PATTERNS)
+
+
+def _check_root_strays(repo_root: Path, report: Report) -> None:
+    """Untracked, un-ignored files directly at the repo root whose name looks like crash/scratch debris.
+    Repo-wide: a stray is local, so a `--commit-range` filter drops it (no commit can contain it).
+    Untracked files in subfolders are out of scope (too noisy). `--directory` collapses an untracked
+    folder to one `name/` entry, which has a slash and is skipped."""
+    if not _is_git_repo(repo_root):
+        return
+    done = _git_run(repo_root, "ls-files", "--others", "--exclude-standard", "--directory",
+                    "--no-empty-directory", "-z")
+    if done is None or done.returncode != 0:
+        return
+    for name in sorted(done.stdout.decode("utf-8", "replace").split("\0")):
+        if name and "/" not in name and is_stray_name(name):
+            report._flag(repo_root / name, f"untracked stray file at the repo root; fix: {STRAY_FIX}")
+
+
+def _doc_type(path: Path) -> str:
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+    return str(_parse_frontmatter(text).get("type") or "").split("#")[0].strip().lower()
+
+
+def _check_wrong_folder(repo_root: Path, report: Report) -> None:
+    """A `.caddis/` file whose `type:` names another folder's kind. Looks at the files directly in
+    `.caddis/` and in each known folder; `done/` and other subfolders are history and are skipped, and
+    so is a file with no frontmatter (most folders never require it). Under `--commit-range` it
+    applies to the files the range changed, like every other per-file check."""
+    caddis = repo_root / ".caddis"
+    if not caddis.is_dir():
+        return
+    for folder in ("", *_FOLDER_TYPES):
+        d = caddis / folder if folder else caddis
+        if not d.is_dir():
+            continue
+        for f in sorted(d.glob("*.md")):
+            kind = _doc_type(f) if f.name.lower() != "readme.md" and f.is_file() else ""
+            if kind not in _TYPE_HOME or kind in _FOLDER_TYPES.get(folder, ()):
+                continue
+            home = _TYPE_HOME[kind]
+            if not folder and home is None:
+                continue  # relay.md and session-state*.md live at the `.caddis/` root
+            where = f".caddis/{folder}" if folder else ".caddis"
+            fix = f"git mv {f.relative_to(repo_root).as_posix()} .caddis/{home}/" if home else "move it"
+            report._flag(f, f"type is `{kind}`, which does not belong in {where}/; fix: {fix}")
+
+
+def _check_stale_current_plans(repo_root: Path, report: Report) -> None:
+    """Plans `status: current` with no commit in 14 days. Reuses caddis_inventory.stale_plans, which
+    ships beside this file in every runtime. A plan a `--commit-range` changed has a fresh commit,
+    so a range check drops these naturally."""
+    try:
+        import caddis_inventory
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_inventory":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_inventory
+    for entry in caddis_inventory.stale_plans(repo_root, days=STALE_PLAN_DAYS, statuses=("current",)):
+        report._flag(repo_root / entry["file"],
+                     f"status current, but no commit for {entry['days']} days; fix: set status: "
+                     "done/superseded/draft in its frontmatter, or commit progress to it")
+
+
+def _check_wider(repo_root: Path, report: Report) -> None:
+    _check_root_strays(repo_root, report)
+    _check_wrong_folder(repo_root, report)
+    _check_stale_current_plans(repo_root, report)
+
+
 def tidy(repo_root: Path, apply: bool = False, check: bool = False,
           kinds: tuple[str, ...] = _KINDS, commit_range: str | None = None,
           only: list[str] | None = None) -> Report:
@@ -829,6 +943,8 @@ def tidy(repo_root: Path, apply: bool = False, check: bool = False,
                 report.stale_suspects.append(item.path)
     if commit_range is not None and PARKING_LOT_DIR in kinds:
         _plan_parked(repo_root, commit_range, report, moves, rewrites)
+    if check:
+        _check_wider(repo_root, report)
     if check and report.in_range is not None:
         _limit_check_to(repo_root, report, report.in_range)
     if only_set is not None:
@@ -1139,7 +1255,9 @@ def main(argv: list[str] | None = None) -> int:
     ap.add_argument("--apply", action="store_true", help="actually move files (default: dry-run report)")
     ap.add_argument("--check", action="store_true",
                      help="conformance check - exit 1 if any top-level artifact lacks a known "
-                          "status, or a plan's Tracker is all done while its status is active")
+                          "status, a plan's Tracker is all done while its status is active, a stray "
+                          "crash/scratch file sits at the repo root, a .caddis file is in the wrong "
+                          "folder, or a `current` plan has no commit for 14 days (report only)")
     ap.add_argument("--commit-range", default=None,
                      help="also read Resolves-Parked / Partly-Resolves-Parked trailers in these "
                           "commits only, e.g. origin/main..HEAD (default: read no trailers); "

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

@@ -1,29 +1,32 @@
-"""Locked, local to-do lists and a read-only view of active plan work."""
+"""The active plan and the plan Tracker reader, for commands, tidy and the gates.
+
+3-store model (owner decision, 21 Oct 2026): the session task list (`.caddis/relay/<name>.tasks.md`), the
+parking lot and the roadmap with the plan Tracker. The `.caddis/todo-list/` store and the open-work view
+are retired, with the `add`, `done`, `list` and `open-work` sub-commands. `reconcile` stays one more
+release as a no-op, because an older /handoff still calls it from its Step 6.
+"""
 
 from __future__ import annotations
 
 import argparse
-import json
 import os
 import re
 import subprocess
 import sys
-import uuid
 from pathlib import Path
 
 try:
     import caddis_exit
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
-    from caddis_frontmatter import parse, split_document
+    from caddis_frontmatter import parse
     from caddis_workstreams import _artifact, _name
 except ModuleNotFoundError as exc:
     if exc.name not in {"caddis_exit", "caddis_file_lock", "caddis_frontmatter", "caddis_workstreams"}:
         raise
+    # caddis_tidy imports caddis_file_lock after this module: these two folders stay on the path.
     sys.path.insert(0, str(Path(__file__).resolve().parent))
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
     import caddis_exit
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
-    from caddis_frontmatter import parse, split_document
+    from caddis_frontmatter import parse
     from caddis_workstreams import _artifact, _name
 
 
@@ -31,81 +34,9 @@ except ModuleNotFoundError as exc:
 # have no console). Inline, not scripts/no_window.py: in the source tree this file does not sit beside it.
 _NO_WINDOW = 0x08000000 if os.name == "nt" else 0
 
-_ITEM = re.compile(r'^- \[([ x])\] (.+?) <!-- caddis: (\{.*\}) -->$')
 _PHASE = re.compile(r'^\|\s*(\d+)\s*\|', re.M)
-_WORD = re.compile(r'[a-z0-9]{3,}')
 _PLAN_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,150}")
-# Trailing status markers on phase headings: arrows/clocks (U+2300-U+27BF), emoji, VS16.
-_STATUS_MARKER = re.compile("[\\s\u2300-\u27bf\U0001f300-\U0001faff\ufe0f]+$")
-
-
-def _path(root: Path, workstream: str | None) -> tuple[Path, Path]:
-    artifact = _artifact(root)
-    name = _name(workstream) if workstream is not None else "inbox"
-    folder = artifact / "todo-list"
-    # Only a folder that EXISTS can point elsewhere. Resolving one that does not exist yet raced a concurrent
-    # writer creating it: on Windows the two paths could resolve differently (a short 8.3 name on one side), and a
-    # safe add failed with this error (main CI, 20 Oct 2026, test_concurrent_inbox_add_loses_no_item).
-    if folder.is_symlink() or (folder.exists() and not folder.resolve().is_relative_to(artifact.resolve())):
-        raise ValueError("todo-list path escapes artifact root")
-    path = folder / f"{name}.md"
-    # Reads are unlocked, so refuse here as well as in locked_path. On Windows a writer replacing the file
-    # makes this probe (and the read below) fail with PermissionError for an instant, so both retry.
-    if retry_denied(path.is_symlink):
-        raise ValueError("to-do file may not be a symlink")
-    return artifact, path
-
-
-def _read(path: Path, workstream: str | None) -> list[dict]:
-    if not retry_denied(path.exists):
-        return []
-    text = retry_denied(lambda: path.read_text(encoding="utf-8"))
-    header, body = split_document(text)
-    name = workstream or "inbox"
-    if header.get("type") != "todo" or header.get("workstream") != name or header.get("status") not in {"current", "done"}:
-        raise ValueError(f"invalid to-do header: {path}")
-    items = []
-    for line in body.splitlines():
-        if not line.strip() or line == "# To-dos":
-            continue
-        match = _ITEM.fullmatch(line)
-        if not match:
-            raise ValueError(f"invalid to-do row: {path}")
-        data = json.loads(match.group(3))
-        if not isinstance(data, dict) or not isinstance(data.get("id"), str):
-            raise ValueError(f"invalid to-do item: {path}")
-        uuid.UUID(data["id"])
-        if "resolves" in data:
-            _resolves_path(path.parents[2], data["resolves"])
-        items.append({"id": data["id"], "title": match.group(2), "done": match.group(1) == "x",
-                      **{key: data[key] for key in ("resolves", "partial") if key in data}})
-    if len({item["id"] for item in items}) != len(items):
-        raise ValueError(f"duplicate to-do id: {path}")
-    expected = "done" if workstream not in (None, "inbox") and items and all(item["done"] for item in items) else "current"
-    if header["status"] != expected:
-        raise ValueError(f"to-do status mismatch: {path}")
-    return items
-
-
-def _write(path: Path, root: Path, workstream: str | None, items: list[dict]) -> None:
-    status = "done" if workstream not in (None, "inbox") and items and all(item["done"] for item in items) else "current"
-    lines = ["---", "type: todo", f"status: {status}", f"workstream: {workstream or 'inbox'}",
-             "---", "", "# To-dos", ""]
-    for item in items:
-        metadata = {"id": item["id"]}
-        for key in ("resolves", "partial"):
-            if key in item:
-                metadata[key] = item[key]
-        box = "x" if item["done"] else " "
-        lines.append(f'- [{box}] {item["title"]} <!-- caddis: {json.dumps(metadata, sort_keys=True)} -->')
-    atomic_write(path, "\n".join(lines) + "\n", root=root)
-
-
-def _title(value: str) -> str:
-    title = " ".join(value.split())
-    if not title or len(title) > 300 or "<!--" in title or "-->" in title:
-        raise ValueError("to-do text must be one plain line (1-300 characters)")
-    return title
+RECONCILE_RETIRED = "caddis_todo: reconcile is retired (3-store model); nothing to do"
 
 
 def _resolves_path(root: Path, value: str) -> Path:
@@ -123,58 +54,6 @@ def _resolves_path(root: Path, value: str) -> Path:
     return target
 
 
-def _suggest(root: Path, title: str) -> list[str]:
-    parking = _artifact(root) / "parking-lot"
-    if not parking.is_dir() or parking.is_symlink():
-        return []
-    words = set(_WORD.findall(title.lower()))
-    found = []
-    for path in sorted(parking.glob("*.md")):
-        if path.is_symlink() or path.name == "README.md":
-            continue
-        if words & set(_WORD.findall(path.stem.lower())) or path.name.lower() in title.lower():
-            found.append(f"parking-lot/{path.name}")
-    return found
-
-
-def add(root: Path, title: str, workstream: str | None = None, *, resolves: str | None = None,
-        partial: bool = False) -> dict:
-    title = _title(title)
-    artifact, path = _path(root, workstream)
-    if partial and not resolves:
-        raise ValueError("--partial requires --resolves")
-    linked = f"parking-lot/{_resolves_path(root, resolves).name}" if resolves else None
-    with locked_path(path, root=artifact):
-        items = _read(path, workstream)
-        item = {"id": str(uuid.uuid4()), "title": title, "done": False}
-        if linked:
-            item["resolves"] = linked
-            if partial:
-                item["partial"] = True
-        items.append(item)
-        _write(path, artifact, workstream, items)
-    return item
-
-
-def done(root: Path, item_id: str, workstream: str) -> dict:
-    artifact, path = _path(root, workstream)
-    with locked_path(path, root=artifact):
-        items = _read(path, workstream)
-        matches = [item for item in items if item["id"] == item_id]
-        if not matches:
-            raise ValueError("unknown to-do id")
-        item = matches[0]
-        if not item["done"]:
-            item["done"] = True
-            _write(path, artifact, workstream, items)
-        return item
-
-
-def list_items(root: Path, workstream: str | None = None) -> list[dict]:
-    _, path = _path(root, workstream)
-    return [item for item in _read(path, workstream) if not item["done"]]
-
-
 def _is_done(status: str) -> bool:
     """A Tracker status cell that means done: "done", "done (note)" or a leading check mark.
     A cell that says work is still pending is not done (owner decision 2026-09-27)."""
@@ -276,7 +155,7 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
 
     None when there is no Tracker heading line, no `| Phase |` header or no Status column. The
     lines are every line of the section except the header; callers pick the rows they trust.
-    One reader, so the open-work view and caddis_tidy never disagree about the same table.
+    One reader, so caddis_tidy and any later caller never disagree about the same table.
     """
     # A real heading line only: plan prose may mention "## Tracker" inline before the section.
     heading = re.search(r"^## Tracker\b.*$", text, re.M)
@@ -293,235 +172,39 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
     return columns, table[:at] + table[at + 1:]
 
 
-def _plan_rows(plan: Path | None) -> list[dict]:
-    if plan is None:
-        return []
-    text = plan.read_text(encoding="utf-8")
-    table = tracker_table(text)
-    if table is None:
-        return []
-    columns, lines = table
-    rows = []
-    for line in lines:
-        match = _PHASE.match(line)
-        if not match:
-            continue
-        cells = [cell.strip() for cell in line.strip("|").split("|")]
-        if len(cells) != len(columns) or _is_done(cells[columns.index("status")]):
-            continue
-        number = match.group(1)
-        heading = re.search(rf"^### Phase {number}\s+[-—]\s+(.+)$", text, re.M)
-        # Drop the heading's trailing status marker (🔲, ⏳, ✅ ...): status lives in the Tracker.
-        title = _STATUS_MARKER.sub("", heading.group(1)) if heading else f"Phase {number}"
-        rows.append({"id": f"phase:{number}", "kind": "phase", "title": title})
-    return rows
-
-
-def _split_cells(line: str) -> list[str]:
-    r"""Stripped cells of one table line, split on unescaped pipes only (`a \| b` is one cell)."""
-    parts = re.split(r"(?<!\\)\|", line.strip())
-    if parts and parts[0] == "":
-        parts.pop(0)
-    if parts and parts[-1] == "":
-        parts.pop(-1)
-    return [part.strip() for part in parts]
-
-
-def _open_work_rows(root: Path) -> list[dict]:
-    path = _artifact(root) / "open-work.md"
-    if path.is_symlink() or not path.is_file():
-        return []
-    text = path.read_text(encoding="utf-8", errors="replace")
-    header, body = split_document(text)
-    if header.get("type") != "open-work":
-        return []
-    rows: list[dict] = []
-    columns: list[str] | None = None
-    id_idx = status_idx = title_idx = 0
-    for raw_line in body.splitlines():
-        line = raw_line.strip()
-        if not line.startswith("|"):
-            columns = None
-            continue
-        cells = _split_cells(line)  # unescaped pipes only, as caddis_rows.split_cells
-        if not cells or all(c and set(c) <= set("-: ") and "-" in c for c in cells):
-            continue
-        if columns is None:
-            lowered = [c.lower() for c in cells]
-            if "id" in lowered and "status" in lowered:
-                columns = lowered
-                id_idx = columns.index("id")
-                status_idx = columns.index("status")
-                title_idx = next(
-                    (i for i, col in enumerate(columns) if col in {"task", "title", "item"}),
-                    id_idx + 1,
-                )
-            continue
-        if len(cells) != len(columns):
-            continue
-        status = cells[status_idx].strip().lower()
-        first = status.split(" ", 1)[0] if status else ""
-        if _is_done(status) or first in {"not-needed", "✓", "✔"}:
-            continue
-        row_id = cells[id_idx].replace("**", "").replace("__", "").replace("`", "").strip()
-        if not row_id:
-            continue
-        title = cells[title_idx] if title_idx < len(cells) else ""
-        rows.append({"id": row_id, "kind": "open-work", "title": title})
-    return rows
-
-
-def open_work(root: Path, workstream: str | None = None) -> list[dict]:
-    rows = _plan_rows(_active_plan(root, workstream))
-    for name in (None, workstream) if workstream and workstream != "inbox" else (None,):
-        rows.extend({"id": item["id"], "kind": "todo", "title": item["title"],
-                     **{key: item[key] for key in ("resolves", "partial") if key in item}}
-                    for item in list_items(root, name))
-    rows.extend(_open_work_rows(root))
-    return rows
-
-
-def _extract_completed_ids(text: str) -> set[str]:
-    """Open-work ids of the done rows in a session-state file's "## Tasks" table.
-
-    Only the marker session_state.py writes after a task's subject counts, as in
-    ``| 3 | done | Fix x <!-- caddis: {"id": "..."} --> |``. A UUID that merely appears in a
-    task's text is never trusted: "depends on <uuid>" must not close that other item.
-    """
-    ids: set[str] = set()
-    in_tasks = False
-    for line in text.splitlines():
-        row = line.strip()
-        if row.startswith("## "):
-            in_tasks = row == "## Tasks"
-            continue
-        if not in_tasks or not row.startswith("|") or row.startswith("|---"):
-            continue
-        cells = [cell.strip() for cell in row.strip("|").split("|")]
-        # Status is the second cell; a "|" inside the subject only shifts later cells.
-        if len(cells) < 3 or cells[1].lower() not in {"done", "completed"}:
-            continue
-        marker = re.search(r"<!--\s*caddis:\s*(\{.*?\})\s*-->\s*\|?$", row)
-        if not marker:
-            continue
-        try:
-            value = json.loads(marker.group(1)).get("id")
-        except (ValueError, AttributeError):
-            continue
-        if isinstance(value, str) and value:
-            ids.add(value.lower())
-    return ids
-
-
-def reconcile(root: Path, session_state: Path) -> list[str]:
-    """Reconcile completed task rows from session-state into todo-lists.
-
-    Marks ad-hoc todo items done by metadata ID.
-    Never edits the Tracker; phase rows are ignored.
-    """
-    if not session_state.is_file():
-        return []
-
-    text = session_state.read_text(encoding="utf-8", errors="replace")
-    completed_ids = _extract_completed_ids(text)
-    if not completed_ids:
-        return []
-
-    artifact = _artifact(root)
-    todo_dir = artifact / "todo-list"
-    if not todo_dir.is_dir():
-        return []
-
-    reconciled: list[str] = []
-    # Ignore phase rows — Tracker is never edited!
-    adhoc_ids = {cid for cid in completed_ids if not cid.startswith("phase:")}
-    if not adhoc_ids:
-        return []
-
-    wanted = {a.lower() for a in adhoc_ids}
-    for todo_file in todo_dir.glob("*.md"):
-        if todo_file.is_symlink() or not todo_file.is_file():
-            continue
-        workstream_name = todo_file.stem
-        try:
-            items = _read(todo_file, workstream_name)
-        except (ValueError, OSError):
-            continue  # a hand-edited file caddis cannot read; the others still reconcile
-        for item in items:
-            item_id = item.get("id")
-            if item_id and item_id.lower() in wanted and not item.get("done"):
-                done(root, item_id, workstream_name)
-                reconciled.append(item_id)
-
-    return reconciled
-
-
 def main(argv: list[str] | None = None) -> int:
-    # Titles carry non-ASCII text; a Windows console defaults to a legacy code page.
+    # Plan paths may carry non-ASCII text; a Windows console defaults to a legacy code page.
     for stream in (sys.stdout, sys.stderr):
         if hasattr(stream, "reconfigure"):
             stream.reconfigure(encoding="utf-8", errors="replace")
-    parser = argparse.ArgumentParser(description=__doc__)
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     parser.add_argument("--root", type=Path, default=Path.cwd(), help=argparse.SUPPRESS)
     commands = parser.add_subparsers(dest="command", required=True)
-    listing = commands.add_parser("list")
-    listing.add_argument("workstream", nargs="?")
-    adding = commands.add_parser("add")
-    adding.add_argument("text")
-    adding.add_argument("--workstream")
-    adding.add_argument("--resolves")
-    adding.add_argument("--partial", action="store_true")
-    finishing = commands.add_parser("done")
-    finishing.add_argument("id")
-    finishing.add_argument("--workstream", required=True)
-    view = commands.add_parser("open-work")
-    view.add_argument("--workstream")
-    view.add_argument("--json", action="store_true")
-    reconcile_p = commands.add_parser("reconcile")
-    reconcile_p.add_argument("--session-state", type=Path, required=True)
     commands.add_parser("active-plan")
-    args = parser.parse_args(argv)
-    try:
-        if args.command == "add":
-            item = add(args.root, args.text, args.workstream, resolves=args.resolves, partial=args.partial)
-            print(item["id"])
-            if not args.resolves:
-                for suggestion in _suggest(args.root, item["title"]):
-                    print(f"Suggested parking item: {suggestion}")
-        elif args.command == "done":
-            item = done(args.root, args.id, args.workstream)
-            if "resolves" in item:
-                prefix = "Partly-Resolves-Parked" if item.get("partial") else "Resolves-Parked"
-                print(f'{prefix}: {item["resolves"]}')
-        elif args.command == "list":
-            for item in list_items(args.root, args.workstream):
-                print(f'{item["id"]} {item["title"]}')
-        elif args.command == "active-plan":
-            plan, candidates = active_plan(args.root)
-            if plan is None:
-                if candidates:
-                    print("caddis-todo: several current plans; name one:", file=sys.stderr)
-                    for candidate in candidates:
-                        print(f"  {candidate}", file=sys.stderr)
-                else:
-                    print("caddis-todo: no current plan in .caddis/plans", file=sys.stderr)
-                return caddis_exit.NOT_RUN
-            print(plan)
-        elif args.command == "reconcile":
-            reconciled = reconcile(args.root, args.session_state)
-            for rid in reconciled:
-                print(f"Reconciled: {rid}")
-        else:
-            rows = open_work(args.root, args.workstream)
-            if args.json:
-                print(json.dumps(rows, ensure_ascii=False))
-            else:
-                for row in rows:
-                    print(f'{row["id"]} [{row["kind"]}] {row["title"]}')
+    # Retired: kept one release so an older /handoff Step 6 does not fail. Takes its old flag, ignores it.
+    reconcile_p = commands.add_parser("reconcile", help=argparse.SUPPRESS)
+    reconcile_p.add_argument("--session-state", type=Path)
+    args, extra = parser.parse_known_args(argv)
+    if extra and args.command != "reconcile":
+        parser.error(f"unrecognized arguments: {' '.join(extra)}")  # only the retired no-op tolerates old flags
+    if args.command == "reconcile":
+        print(RECONCILE_RETIRED)
         return 0
-    except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+    try:
+        plan, candidates = active_plan(args.root)
+    except (OSError, UnicodeError, ValueError) as exc:
         print(f"caddis-todo: {exc}", file=sys.stderr)
         return 1
+    if plan is None:
+        if candidates:
+            print("caddis-todo: several current plans; name one:", file=sys.stderr)
+            for candidate in candidates:
+                print(f"  {candidate}", file=sys.stderr)
+        else:
+            print("caddis-todo: no current plan in .caddis/plans", file=sys.stderr)
+        return caddis_exit.NOT_RUN
+    print(plan)
+    return 0
 
 
 if __name__ == "__main__":

package/bundles/antigravity-plugin/skills/flow-studio/README.md

@@ -3,7 +3,7 @@
 The `flow-studio` skill: a model file (JSON) describes a flow, lifecycle or journey, and one
 engine draws it as a self-contained HTML page with pan and zoom, lanes, linked nodes, a slide-in
 inspector, scenario playback, metric overlays, live update, motion that carries state, and numbered implementation notes. The design is in
-`.caddis/plans/flow-studio-skill-design.md`; the S4 stage status is in `.caddis/plans/flow-studio-s4-status.md`.
+`.caddis/plans/done/flow-studio-skill-design.md`; the S4 stage status is in `.caddis/plans/flow-studio-s4-status.md`.
 `SKILL.md` is the current playbook.
 
 ## Use it

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/cli.test.mjs

@@ -1,7 +1,7 @@
-import { test } from "node:test";
+import { after, test } from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -25,6 +25,7 @@ const good = {
   links: [{ id: "a-b", from: "a", to: "b", state: "ok" }],
 };
 const dir = mkdtempSync(join(tmpdir(), "flow-studio-"));
+after(() => rmSync(dir, { recursive: true, force: true })); // a test run leaves nothing in the temp folder (tidy v2 Phase 5)
 const write = (name, value) => { const p = join(dir, name); writeFileSync(p, typeof value === "string" ? value : JSON.stringify(value)); return p; };
 
 test("validate: a good model exits 0 and prints OK", () => {