@caddis/cli 0.4.12 → 0.4.13

package/bundles/antigravity-plugin/guard_agy.py

@@ -79,8 +79,9 @@ def classify_write(file_path: str) -> tuple[str, str]:
 # subpath (E:\proj\dist falls through to ask).
 _CATASTROPHIC_TARGET = re.compile(
     r"--no-preserve-root"
-    r"|(?:^|\s)(?:/|/\*|~/|~|\$\{?HOME\}?)(?:\s|$|;|&|\|)"
-    r"|(?:^|\s)[A-Za-z]:[\\/]?(?:\s|$|;|&|\|)",
+    # A closing bracket also ends the target: `echo $(rm -rf ~)` was ask, not deny (review catch).
+    r"|(?:^|\s)(?:/|/\*|~/|~|\$\{?HOME\}?)(?:\s|$|;|&|\||[)}])"
+    r"|(?:^|\s)[A-Za-z]:[\\/]?(?:\s|$|;|&|\||[)}])",
     re.I,
 )
 _FORK_BOMB = re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:")
@@ -115,6 +116,61 @@ def _is_win_recursive_delete(cmd: str) -> bool:
     return ps_recurse_force or cmd_slash_s
 
 
+_FIND_DELETE = r"\bfind\b.*?(?:-delete\b|-exec\s+rm\b)"
+# Line continuations join a statement across physical lines: bash `\` and PowerShell backtick.
+_CONTINUATION = re.compile(r"[\\`]\r?\n")
+
+
+def _statements(c: str) -> list[str]:
+    """Split a command on `;`, `&&`, `||` and newlines — ONLY at the top level. Same rule as
+    hooks/guard.py: a separator inside quotes, a subshell/block or after a line continuation does
+    not end a statement, and an unclosed quote or bracket errs toward one statement (deny)."""
+    c = _CONTINUATION.sub(" ", c)
+    out: list[str] = []
+    cur: list[str] = []
+    quote, depth, i = "", 0, 0
+    while i < len(c):
+        ch = c[i]
+        if quote:
+            quote = "" if ch == quote else quote
+        elif ch in "'\"":
+            quote = ch
+        elif ch in "({":
+            depth += 1
+        elif ch in ")}" and depth:
+            depth -= 1
+        elif depth == 0 and (ch in ";\n" or c[i:i + 2] in ("&&", "||")):
+            out.append("".join(cur))
+            cur = []
+            i += 1 if ch in ";\n" else 2
+            continue
+        cur.append(ch)
+        i += 1
+    out.append("".join(cur))
+    return [_strip_quotes(s) for s in out]
+
+
+def _catastrophic_statement(c: str) -> str:
+    """The deny reason when ONE statement both destroys recursively and names a root, else ''.
+
+    Same rule as hooks/guard.py. Tested per statement, not per command: an unrelated `~` or `C:`
+    on another line used to turn a scratchpad cleanup into a root/home deny (found 2026-09-10)."""
+    for seg in _statements(c):
+        if not _CATASTROPHIC_TARGET.search(seg):
+            continue
+        sl = seg.lower()
+        if _is_rm_recursive_force(seg):
+            return "recursive force-delete of a root/home path (rm -rf)"
+        if re.search(_FIND_DELETE, sl):
+            return "find -delete from a root/home path"
+        if _is_win_recursive_delete(seg):
+            return "recursive force-delete of a root/home path (Windows Remove-Item/rmdir)"
+        if (re.search(r"\bchmod\b", sl) and _has_flag(seg, "r", "--recursive")
+                and re.search(r"\b0?777\b", sl)):
+            return "recursive chmod 777 on a root path"
+    return ""
+
+
 def classify_bash(command: str) -> tuple[str, str]:
     """Risk tier (deny|ask|allow) + reason for a shell command."""
     c = command.strip()
@@ -122,26 +178,19 @@ def classify_bash(command: str) -> tuple[str, str]:
     n = _strip_quotes(c)          # quote-normalized: defeats `rm '-rf' "/"` evasion
     nl = n.lower()
     rm_rf = _is_rm_recursive_force(n)
-    catastrophic = bool(_CATASTROPHIC_TARGET.search(n))
-    find_delete = bool(re.search(r"\bfind\b.*?(?:-delete\b|-exec\s+rm\b)", nl))
+    find_delete = bool(re.search(_FIND_DELETE, nl))
     win_del = _is_win_recursive_delete(n)
 
     # ── deny: catastrophic ──
-    if rm_rf and catastrophic:
-        return "deny", "recursive force-delete of a root/home path (rm -rf)"
-    if find_delete and catastrophic:
-        return "deny", "find -delete from a root/home path"
-    if win_del and catastrophic:
-        return "deny", "recursive force-delete of a root/home path (Windows Remove-Item/rmdir)"
+    why = _catastrophic_statement(c)
+    if why:
+        return "deny", why
     if re.search(r"\brmtree\s*\(\s*['\"]?(?:/|~|[A-Za-z]:\\?)['\"]?\s*\)", c, re.I):
         return "deny", "recursive tree delete of a root/home path (rmtree)"
     if _FORK_BOMB.search(c):
         return "deny", "fork bomb"
     if re.search(r"\bdd\b.*\bof=/dev/", nl) or re.search(r"\bmkfs", nl) or re.search(r">\s*/dev/sd[a-z]", nl):
         return "deny", "writes directly to a disk device"
-    if (re.search(r"\bchmod\b", nl) and _has_flag(n, "r", "--recursive")
-            and re.search(r"\b0?777\b", nl) and catastrophic):
-        return "deny", "recursive chmod 777 on a root path"
 
     # ── ask: destructive-but-legit ──
     if rm_rf:

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.101",
+  "version": "1.3.103",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

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

@@ -325,12 +325,16 @@ def _run_tests(cmd: list[str], cwd: Path, timeout: int = 900) -> tuple[str, str]
         return (f"could not run the suite ({type(exc).__name__})", shown)
 
     blob = (r.stdout or "") + chr(10) + (r.stderr or "")
-    # pytest's summary line is the last one naming passed/failed/error.
+    # The summary is the last line naming passed/failed/error. Case-insensitive, because Pester
+    # capitalises it (`Tests Passed: 22, Failed: 0`) — found 2026-09-10 in an all-Pester repo.
     tail = [l.strip() for l in blob.splitlines()
-            if ("passed" in l or "failed" in l or "error" in l.lower()) and "==" not in l[:2]]
+            if any(w in l.lower() for w in ("passed", "failed", "error")) and "==" not in l[:2]]
     if tail:
         return (tail[-1], shown)
-    return (f"suite did not report a summary (exit {r.returncode}) — investigate", shown)
+    # Say WHAT was run and how to change it. A bare "no summary" read as "this repo has no tests"
+    # when the truth was "the tool and the repo disagree about how to run them".
+    return (f"no test summary from `{shown}` (exit {r.returncode}) — if this repo's tests are "
+            "not pytest, set [handover] test_cmd in .caddis/config.toml", shown)
 
 
 def _test_command(root: Path) -> list[str]:

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

@@ -104,6 +104,9 @@ class DocFindings:
     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)
+    # Bare filenames that match NO file in this repo. Advisory: in one real handover every such
+    # name was a file in another repository, which no local check could ever satisfy.
+    unresolved_names: list[str] = field(default_factory=list)
     # A THIRD refusing tier, kept separate from stale_prone so the message can say something
     # different. A stale hash is an accident the successor will notice; a stored answer key
     # defeats the exercise SILENTLY — it certifies a reader who understood nothing.
@@ -139,6 +142,18 @@ _INLINE_ANSWER = re.compile(r"\bQ\s*\d{1,2}\b.*?\b(?:A|Ans|Answer)\s*[:.\)]", re
 
 _DOC_PATH = re.compile(r"`([^`\s<>{}*?]+?\.(?:md|py|ts|tsx|json|ya?ml|sh|ps1|html|toml|sql))`")
 
+# A count QUOTED FROM an earlier document ("a previous handover said '1,066 tests'") is a citation,
+# not a claim about now — found 2026-09-10, when the sentence warning the reader not to quote
+# counts had to lose its example to pass. Quotation marks alone are NOT enough: `status: "312
+# tests passed"` is a current claim in quotes (review catch). So three things must hold: the count
+# sits inside a quoted span, a reporting verb comes BEFORE that span, and the line makes no
+# now-claim. A single quote only opens a span at a word boundary, so "it's" cannot start one.
+_QUOTED = re.compile(r"(?<!\w)'[^'\n]*'(?!\w)|\"[^\"\n]*\"|“[^”\n]*”|‘[^’\n]*’")
+_REPORTED = re.compile(r"\b(?:said|says|claimed|claims|wrote|reported|quoted|stated)\b", re.I)
+_NOW_CLAIM = re.compile(
+    r"\b(?:now|still|currently|current|today|at present|as of|remains?|unchanged|holds|stands"
+    r"|nothing has changed)\b", re.I)
+
 
 def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
     """Round 0: the parent validates its OWN handover before anyone reads it.
@@ -185,17 +200,42 @@ def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
                 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"))
+        cited = [] if _NOW_CLAIM.search(line) else [
+            (q.start(), q.end()) for q in _QUOTED.finditer(line)
+            if _REPORTED.search(line[:q.start()])]
         for m in _COUNT.finditer(line):
+            if any(a <= m.start() and m.end() <= b for a, b in cited):
+                out.historical.append((n, f"`{m.group(0)}` quoted from an earlier document — "
+                                          "reads as a citation. Check it is not standing in for "
+                                          "current state"))
+                continue
             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:
+        tracked: list[str] | None = 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():
+            if (repo_root / cand).exists():
+                continue
+            if "/" in cand or "\\" in cand:
                 out.missing_paths.append(cand)
+                continue
+            # A BARE filename. Block only when it names a file this repo has — that is the catch
+            # worth keeping (`deploy.ps1` named the canonical copy when the task was about another
+            # file). A name found nowhere is far more likely a file in another repository.
+            if tracked is None:
+                tracked = _run(["git", "ls-files"], repo_root).splitlines()
+            hits = [t for t in tracked if t.rsplit("/", 1)[-1] == cand]
+            if not hits:
+                out.unresolved_names.append(cand)
+            elif len(hits) == 1:
+                out.missing_paths.append(f"{cand} — did you mean `{hits[0]}`? Name the full path")
+            else:
+                out.missing_paths.append(f"{cand} — matches {len(hits)} files ("
+                                         + ", ".join(hits[:3]) + "). Name the full path")
     return out
 
 
@@ -256,6 +296,29 @@ class Preflight:
         return not self.refusals
 
 
+def in_flight_branches(repo_root: Path) -> list[str]:
+    """Local branches holding commits the successor cannot see: never pushed, or ahead of upstream.
+
+    Found 2026-09-10: the parent had an unmerged branch correcting a plan the successor was told to
+    edit next. The successor caught it by luck — branching off main would have reverted the fix.
+    Empty when the repo has no remote, where every branch is local by design and naming them all
+    would be noise. Open PRs are NOT detected: that needs `gh` and the right account.
+    """
+    if not _run(["git", "remote"], repo_root):
+        return []
+    out = _run(["git", "for-each-ref",
+                "--format=%(refname:short)|%(upstream:short)|%(upstream:track)", "refs/heads"],
+               repo_root)
+    found: list[str] = []
+    for line in out.splitlines():
+        name, up, track = (line.split("|") + ["", ""])[:3]
+        if not up:
+            found.append(f"{name} (never pushed)")
+        elif "ahead" in track:
+            found.append(f"{name} ({track.strip('[]')} of {up})")
+    return found
+
+
 def preflight(repo_root: Path, context_pct: float | None = None) -> Preflight:
     """Conditions under which a spawn must not happen at all.
 
@@ -273,6 +336,12 @@ def preflight(repo_root: Path, context_pct: float | None = None) -> Preflight:
         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.")
+    flight = in_flight_branches(repo_root)
+    if flight:
+        p.notes.append(
+            "in-flight work the successor cannot see: " + ", ".join(flight) + ". Push each one, "
+            "name it in the relay, and say whether the successor must wait for it. Open PRs are "
+            "not detected here — list them yourself.")
 
     d = repo_root / ART / "parking-lot"
     if d.is_dir():
@@ -352,9 +421,22 @@ def fingerprint(repo_root: Path, with_tests: bool = False) -> dict:
         "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"
+        # The inventory's runner, not a second copy of it. The copy that lived here hard-coded
+        # pytest and ran it through `_run`, which returns "" on a non-zero exit — so a Pester repo
+        # AND a red pytest suite both read "suite reported no summary" (found 2026-09-10).
+        # caddis_inventory had already fixed both: `[handover] test_cmd`, and a runner that keeps
+        # a failing suite's summary. The two files sit side by side in source and in the bundle.
+        # Loaded by FILE, not by name: a `caddis_inventory` already imported from another path
+        # would otherwise be silently reused, and sys.path would be changed for the whole process.
+        import importlib.util
+        spec = importlib.util.spec_from_file_location(
+            "_caddis_inventory_for_spawn", Path(__file__).resolve().parent / "caddis_inventory.py")
+        _inv = importlib.util.module_from_spec(spec)
+        # Registered BEFORE exec: `@dataclass` looks its module up in sys.modules while the class
+        # body runs, and fails with "'NoneType' object has no attribute '__dict__'" otherwise.
+        sys.modules[spec.name] = _inv
+        spec.loader.exec_module(_inv)
+        fp["tests"], _shown = _inv._run_tests(_inv._test_command(repo_root), repo_root)
     return fp
 
 
@@ -398,6 +480,26 @@ def verify_answerable(repo_root: Path, answer_in: str, needle: str) -> tuple[boo
 PARENT_RELAY = "parent-relay.md"
 PARENT_STATE = "parent-session-state.md"
 
+# One task per line, `- [ ]` open and `- [x]` done. Counted so the successor's read-back can be
+# checked against the file instead of taken on trust.
+_TASK_LINE = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+\[([ xX])\]", re.M)
+
+
+def count_open_tasks(repo_root: Path) -> int | None:
+    """Open checkbox items in the parent's task list, or None when there is nothing to count.
+
+    None covers "no file" and "a file with no checkbox lines". Either way there is nothing to
+    compare a reported count with, and refusing would demand a format the parent never used.
+    """
+    try:
+        text = (repo_root / ART / PARENT_STATE).read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return None
+    marks = _TASK_LINE.findall(text)
+    if not marks:
+        return None
+    return sum(1 for m in marks if m == " ")
+
 
 def _mtime(path: Path) -> float | None:
     try:
@@ -428,18 +530,24 @@ def capture_order(repo_root: Path, spawn_id: str) -> tuple[list[str], list[str]]
         return refusals, notes
 
     if t_state is None:
-        notes.append(f"no {ART}/{PARENT_STATE}. A task widget does not survive a `/clear` and this "
-                     "project has already lost one — if the list is genuinely empty, SAY so in the "
-                     "handover rather than leaving the reader to infer it.")
+        notes.append(f"no {ART}/{PARENT_STATE}. Task state is per-session — the successor's "
+                     "tracker starts empty, so this file is the only way the list reaches it. If "
+                     "the list is genuinely empty, SAY so in the handover rather than leaving the "
+                     "reader to infer it.")
     elif t_state > t_relay:
         refusals.append(f"{PARENT_STATE} is NEWER than {PARENT_RELAY}. The relay cites the task "
                         "list, so a list written afterwards means the relay describes a state "
-                        "that never existed. Rewrite the relay, do not re-touch the list.")
+                        "that never existed. Rewrite the relay, do not re-touch the list. If you "
+                        "corrected the list on purpose, re-read the relay against it and re-save "
+                        "the relay — a save that only moves its timestamp is the sanctioned fix.")
 
     if t_relay > t_prompt:
         refusals.append(f"{PARENT_RELAY} is NEWER than the prompt. The questions must target what "
                         "the relay actually says — derived from a relay that has since changed, "
-                        "they test your memory of it, which is the thing under suspicion.")
+                        "they test your memory of it, which is the thing under suspicion. If you "
+                        "corrected the relay on purpose, re-check the questions against it and "
+                        "re-save the prompt — a save that only moves its timestamp is the "
+                        "sanctioned fix.")
 
     # Anything the relay quotes that moved after it was written.
     for sub_dir in ("kb", "parking-lot"):
@@ -530,6 +638,10 @@ def handshake_open(repo_root: Path, spawn_id: str, transport: str = "auto",
         # exist yet. The parent fills it in from the `from-name` of the child's first message,
         # which is the only moment either side reliably knows that name.
         "peer": peer,
+        # Tells the caddis guard to refuse tree-moving git commands until `close` stamps
+        # `closed_at`. An explicit flag, so handshake files written before the lock existed —
+        # which never got a `closed_at` — do not suddenly lock a tree.
+        "tree_lock": True,
         "opened_at": int(time.time()),
         "history": [],
     }
@@ -550,7 +662,8 @@ MAX_REJECTS = 2
 
 
 def handshake_record(repo_root: Path, spawn_id: str, event: str,
-                     peer: str = "", verdict: str = "") -> tuple[dict | None, str]:
+                     peer: str = "", verdict: str = "",
+                     revived: int | None = None) -> tuple[dict | None, str]:
     """Advance the handshake. One step forward, with exactly one named exception.
 
     **REJECT sends it back to `awaiting-answers`, and that is the whole point of this function
@@ -612,10 +725,28 @@ def handshake_record(repo_root: Path, spawn_id: str, event: str,
                        + ("skip a step" if there > here + 1 else "move backwards")
                        + " — refusing rather than rewriting, because a skipped step here is a "
                          "gate that never ran.")
+    # The task list crosses the session boundary only as a file. Task state is per-session, so the
+    # successor's tracker starts empty — measured 2026-09-10: a parent board of 59 tasks, and the
+    # child's `TaskList` said "No tasks found". So the read-back must say how many items the child
+    # rebuilt from the file. Required on `readback` (spawn-session's parent-first flow). Optional
+    # on child-first `answers`, because spawn-hub shares that flow and hands over a role, not a list.
+    if event == "readback" and revived is None:
+        return state, (f"a read-back must say how many open tasks the successor rebuilt from "
+                       f"{ART}/{PARENT_STATE} into its own tracker. Ask for the number, then record "
+                       "it with `--revived <n>` (0 is a valid answer when the list is empty).")
+    if revived is not None:
+        expected = count_open_tasks(repo_root)
+        if expected is not None and revived != expected:
+            return state, (f"the successor reports {revived} revived task(s), but "
+                           f"{ART}/{PARENT_STATE} has {expected} open. A successor that revives "
+                           "fewer has dropped some silently. Ask it to re-read the file and "
+                           "report again.")
+        state["revived"] = revived
     if peer:
         state["peer"] = peer
     state["history"].append({"event": event, "at": int(time.time()),
                              **({"verdict": verdict} if event == "verdict" and verdict else {}),
+                             **({"revived": revived} if revived is not None else {}),
                              **({"peer": peer} if peer else {})})
     state["state"] = target
     _handshake_path(repo_root, spawn_id).write_text(
@@ -677,7 +808,13 @@ def handshake_close(repo_root: Path, spawn_id: str) -> tuple[bool, str]:
                        "ALIVE until the child confirms it has the verdict — closing on an "
                        "unanswered handshake is the same as never running one. (It may stop "
                        "WRITING to the repo now; that is a different rule and both hold.)")
-    return True, "acknowledged — the parent may close"
+    # Stamp it. The guard's shared-tree lock holds while a handshake is open and lifts on this.
+    if not state.get("closed_at"):
+        state["closed_at"] = int(time.time())
+        _handshake_path(repo_root, spawn_id).write_text(
+            json.dumps(state, indent=2) + chr(10), encoding="utf-8")
+    return True, ("acknowledged — closed. Commit and push the handshake file, send the child one "
+                  "last message saying you are stopping, then EXIT (see \"The parent's ending\")")
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -714,6 +851,10 @@ def main(argv: list[str] | None = None) -> int:
     h.add_argument("--peer", default="",
                    help="the child's name as ListAgents shows it — take it from the `from-name` "
                         "of its first message; that is the only moment it is reliably known")
+    h.add_argument("--revived", type=int, default=None,
+                   help="with `--event readback` (required) or `--event answers` (optional): how "
+                        "many open tasks the successor rebuilt from parent-session-state.md. "
+                        "Checked against the file's `- [ ]` lines")
     q = sub.add_parser("verify-question")
     q.add_argument("--answer-in", required=True)
     q.add_argument("--needle", required=True)
@@ -746,6 +887,9 @@ def main(argv: list[str] | None = None) -> int:
         f = check_document(doc.read_text(encoding="utf-8", errors="ignore"), root)
         for n, msg in f.historical:
             print(f"  note  line {n}: {msg}")
+        for name in f.unresolved_names:
+            print(f"  note  `{name}` matches no file in this repo — fine if it lives elsewhere; "
+                  "give the full path if it is here")
         if f.ok():
             print(f"[spawn] {doc.name} passes round 0 — nothing stale-prone, every path exists")
             return EXIT_OK
@@ -785,8 +929,9 @@ def main(argv: list[str] | None = None) -> int:
                   f"({st['transport_reason']}), state `{st['state']}`")
             if st["state"] == HANDSHAKE_STATES[0]:
                 print(f"  PARENT-FIRST. You have the address, so message \"{st['peer']}\" now: "
-                      "tell it what to read, then ask it to reply with WHICH FILES it opened "
-                      "before it answers anything. Record that with `--event readback`.")
+                      "tell it what to read, then ask it to reply with WHICH FILES it opened, and "
+                      f"how many open tasks it rebuilt from {ART}/{PARENT_STATE}, before it "
+                      "answers anything. Record that with `--event readback --revived <n>`.")
             elif st["transport"] == "message" and not st["peer"]:
                 print("  No --peer given, so this is the child-first flow: print the prompt and "
                       "wait. If you already started the child, re-open with `--peer <its "
@@ -814,7 +959,7 @@ def main(argv: list[str] | None = None) -> int:
             if not a.event:
                 sys.stderr.write("[spawn] --event is required for `record`" + chr(10))
                 return EXIT_REFUSED
-            st, err = handshake_record(root, a.id, a.event, a.peer, a.verdict)
+            st, err = handshake_record(root, a.id, a.event, a.peer, a.verdict, a.revived)
             if err:
                 sys.stderr.write("[spawn] " + err + chr(10))
                 return EXIT_REFUSED

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

@@ -192,7 +192,7 @@ def extract_docmap_entries(docmap_text: str) -> set[str]:
 # the other; the instruction file carries the mapping. Legacy synonyms included so old docs stay quiet.
 TRUST_STATUS_VALUES: frozenset[str] = frozenset({
     "draft", "stable", "deprecated",                      # OKF v0.2
-    "current", "done", "superseded", "ready",             # caddis
+    "current", "done", "superseded", "ready", "proposed", # caddis
     "shipped", "implemented",                             # caddis legacy synonyms for `done`
     "open", "doing", "dropped",                           # caddis parking-lot (`done` shared above)
 })
@@ -675,6 +675,43 @@ def insert_table_rows(text: str, heading_contains: str, rows: list[str]) -> str:
     return out + "\n" if text.endswith("\n") else out   # preserve trailing newline (git-clean)
 
 
+# A link to a SIBLING note — `[x](x.md)` or `[x](./x.md)` — is what marks a table as the KB index.
+# A link that climbs out (`../../docs/guide.md`) marks a table of other docs, which must not get
+# KB rows appended to it.
+_SIBLING_NOTE_LINK = re.compile(r"\]\((?:\./)?[^/()\s]+\.md\)")
+
+
+def insert_into_note_table(text: str, rows: list[str]) -> str:
+    """Append ``rows`` to the first table that already links sibling KB notes, whatever its heading.
+
+    The fallback for a DOC-MAP written by hand before the scaffold existed. Found 2026-09-10 in
+    a consumer repo: a working 15-row table with no ``## Knowledge base`` heading, invisible to
+    ``insert_table_rows``, so every new note had to be indexed by hand. Returns ``text`` unchanged
+    when no such table exists. Pure.
+    """
+    if not rows:
+        return text
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        if not lines[i].strip().startswith("|"):
+            i += 1
+            continue
+        start = i
+        while i < len(lines) and lines[i].strip().startswith("|"):
+            i += 1
+        end = i - 1
+        if end - start < 1 or set(lines[start + 1].strip()) - set("|-: "):
+            continue                                      # no |---| separator: not a table
+        first_cells = [r.split("|")[1] for r in lines[start + 2:end + 1] if r.count("|") > 1]
+        if any(_SIBLING_NOTE_LINK.search(c) for c in first_cells):
+            head = lines[start:start + 2]
+            body = [b for b in lines[start + 2:end + 1] if not _is_placeholder_row(b)]
+            out = "\n".join(lines[:start] + head + body + rows + lines[end + 1:])
+            return out + "\n" if text.endswith("\n") else out
+    return text
+
+
 def build_docmap(root: Path, project_name: str = "project") -> str:
     """Full DOC-MAP text for a fresh repo: scaffold + discovered reference docs + existing KB notes.
 
@@ -779,7 +816,10 @@ def reindex(
     # Index orphan KB notes (additive). Report success ONLY if the rows actually landed — insert is a
     # no-op when the "Knowledge base" heading/table is absent, and we must not claim work we didn't do.
     if orphans:
-        after = insert_table_rows(updated, "Knowledge base", kb_note_rows(root, entries))
+        new_rows = kb_note_rows(root, entries)
+        after = insert_table_rows(updated, "Knowledge base", new_rows)
+        if after == updated:
+            after = insert_into_note_table(updated, new_rows)   # a hand-made map, no heading
         if after != updated:
             updated = after
             summary.append(f"indexed {len(orphans)} KB note(s): " + ", ".join(orphans))
@@ -886,6 +926,20 @@ def run(root: Path, check: bool) -> int:
     return 0
 
 
+def run_reindex(root: Path, prune: bool = False) -> int:
+    """Run the reindex, print its summary, and return the exit code.
+
+    Non-zero when any part of the work was NOT done — a note it could not index, or a DOC-MAP it
+    could not write. Until 2026-09-10 this always exited 0, so a partial success looked exactly
+    like a full one and a repo could sit with unindexed notes indefinitely.
+    """
+    root = Path(root)
+    _changed, summary = reindex(root, root.name, prune=prune)
+    for line in summary:
+        print(f"[kb] {line}")
+    return 1 if any(s.startswith(("could not", "WARNING")) for s in summary) else 0
+
+
 def main() -> None:
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")  # Windows cp1252 can't encode some doc names
@@ -909,12 +963,10 @@ def main() -> None:
     )
     args = parser.parse_args()
     root = _repo_root()
-    # Reindex/prune are maintenance actions (the `/kb` command drives them), not a gate — run, exit 0.
+    # Reindex/prune are maintenance actions (the `/kb` command drives them), not a gate — but they
+    # still exit non-zero when part of the work could not be done.
     if args.reindex or args.prune:
-        _changed, summary = reindex(root, root.name, prune=args.prune)
-        for line in summary:
-            print(f"[kb] {line}")
-        sys.exit(0)
+        sys.exit(run_reindex(root, prune=args.prune))
     # Resolve the repo root from git (cwd fallback) — the pre-push gate runs from the repo root,
     # so this is correct wherever the checker is copied. Tests call run() with an explicit root.
     sys.exit(run(root, args.check))

package/bundles/antigravity-plugin/skills/kb/SKILL.md

@@ -21,6 +21,10 @@ It is **additive and safe** — never deletes your rows:
 - **Missing map** → creates `.caddis/kb/DOC-MAP.md` from a scaffold, pre-linking the repo's obvious
   reference docs (README, `docs/…`) and any existing `.caddis/kb/*.md` notes.
 - **Existing map** → indexes any KB note that isn't yet linked (adds a row with a placeholder description).
+  It appends to the `## Knowledge base` table, or — in a map written by hand with no such heading —
+  to the first table that already links sibling notes (`[x](x.md)`).
+- **Could not index a note** (no table of notes anywhere) → says so and **exits 1**. Report it; do not
+  treat the run as done.
 - **Dangling links** (a linked file that's gone) → **reported, not removed** — handle them in Step 3.
 
 ## Step 3 — finish by hand

package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md

@@ -49,7 +49,10 @@ human to carry, which meant the child did not exist yet and its address could no
 first message was itself proof it had read the handover. Here the parent speaks first, so that
 proof is a separate step: **your opening message asks the child to reply with WHICH FILES it
 opened, before it answers anything.** Ask for paths — a summary can be written without opening
-anything. Record it with `--event readback`; until you do, the handshake refuses `--event answers`.
+anything. **Ask also how many open tasks it rebuilt** from `.caddis/parent-session-state.md` into
+its own tracker, whatever tracker it has. Record both with `--event readback --revived <n>`. The
+handshake refuses a read-back with no count, and a count that disagrees with the file's `- [ ]`
+lines. Until the read-back is recorded, it refuses `--event answers`.
 
 **No name given?** The command falls back to the older printed-prompt flow. That is also the only
 route on agy and Codex, which have no `SendMessage`.
@@ -67,7 +70,7 @@ and the active plan).
 |---|---|---|
 | 1 | **Capture the knowledge** — KB notes for anything that generalises | FIRST, while the reasoning is still in context. Written last it becomes a summary of a summary |
 | 2 | **Update the durable state** — the register, the parking lot | These are the authority. The relay quotes them, so they must be true before it does |
-| 3 | **Write the TASK LIST to a file** | A task widget does not survive a `/clear`. This project has already lost one |
+| 3 | **Write the TASK LIST to a file** — one task per line, `- [ ]` open, `- [x]` done | **Task state is per-session.** The successor's tracker starts empty: a parent board held 59 tasks and the child's `TaskList` said "No tasks found". The child may not even have the same tracker tool. The file is the only medium both sessions can read, so never tell the successor it shares your board |
 | 4 | **Write the relay** — what happened, who owns what, what is blocked | It CITES 1-3. Written earlier, it cites things that have since moved |
 | 5 | **Derive the questions** | LAST. They must target what steps 1-4 actually say. Questions written first test **your memory**, which is the thing under suspicion |
 
@@ -170,9 +173,19 @@ or from a file quoted by path.
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" check --doc .caddis/spawn-session/<id>-prompt.md
 ```
 
-It **blocks** on a commit hash or test count given as current state, and on any path that does not
-exist. It only **notes** a historical hash — those are durable, and flagging them was how the first
-version produced seven findings on one document and taught the reader to skim.
+It **blocks** on a commit hash or test count given as current state, and on a path that does not
+exist. It only **notes** three things:
+
+- a historical hash — durable;
+- a count quoted from an earlier document — `a previous handover said "1,066 tests"` is a citation,
+  not a claim. It needs a reporting verb before the quote and no now-claim on the line; quotation
+  marks alone still block;
+- a bare filename that matches no file in this repo — usually a file in another repository.
+
+A bare filename that DOES match a file here still blocks, and the refusal names the full path. That
+is the case that caught a real error: `deploy.ps1` named the canonical copy when the task was about
+a different file. Flagging citations was how the first version produced seven findings on one
+document and taught the reader to skim.
 
 **A claim that cannot be re-derived does not go in the handover.**
 
@@ -300,18 +313,54 @@ a handover, it is a file — and grading RE-DERIVES, so it audits the document a
 reader. In the manual run that pass found a defect in the parent's own handover. `/clear` in your
 terminal destroys the only thing that can do that.
 
-> **You stay ALIVE. You stop WRITING.** `/caddis:spawn-hub` carries a single-writer rule — the
-> outgoing session stops writing to the repository the moment the prompt is issued, because two
-> sessions committed to one repo concurrently and one's work landed inside the other's commit.
-> That is a different rule from this one and **both hold.** Said no other way, a reader reconciles
-> them by closing the parent early, which removes the grader.
+### Grading goes to a fresh subagent — not to you
+
+**This command's trigger is a nearly-full context, and grading is its most expensive step.** Round 1
+re-derives every answer from the repository, because no answer key is stored. In the first real run
+that was about 30 tool calls, and round 2 repeated it for the delivered work. A parent near its limit
+cannot finish that. It runs out mid-grade, while the successor waits for a verdict.
+
+Grading never needed your memory. It needs the repo, the questions and the child's answers. So send
+each round to a **fresh subagent** and keep only its verdict:
+
+> Grade `.caddis/spawn-session/<id>-answers.md` against the questions in
+> `.caddis/spawn-session/<id>-prompt.md`. Re-derive every answer from the repository — run the
+> commands, open the files — and do not trust the child's citations. Return ACCEPT, ACCEPT WITH
+> CORRECTIONS or REJECT, and for each wrong answer the file or command that proves it. List
+> separately any error you find in the handover documents themselves.
+
+Use a read-only agent that can open files and run commands (`caddis:anchor` fits). You relay the
+verdict, record it, and fix any handover document it proves wrong. On a runtime with no subagents,
+grade in a fresh session and say so. Never grade from a nearly-full context.
+
+**ALIVE until `handshake close`; not WRITING, with two named exceptions.** `/caddis:spawn-hub`
+carries a single-writer rule, because two sessions committed to one repo concurrently and one's work
+landed inside the other's commit. Here it has exactly two exceptions: your own handover artefacts,
+and a document a verdict proves wrong. **Commit and push each one before you reply.** Never hold an
+uncommitted change while the child is live, because a checkout on its side can take it with no copy
+anywhere.
 
 Note the handshake file lands in `.caddis/spawn-session/`, so commit it with the others before
 re-running `preflight`, which refuses on a dirty tree.
 
-### Tell the child it does not own the tree
+### The tree is never handed over while two sessions are attached
 
-**Say this in the prompt.** A fresh session's instinct on seeing a dirty tree is to tidy it, and
+**Stopping writing does not transfer the workspace.** Never tell the child "the tree is yours now".
+That sentence describes your intent at one moment; it is not a property of the tree. In the first
+real run the successor read it as permission and switched the shared checkout within the hour.
+
+**The guard enforces this in Claude Code.** While a handshake in `.caddis/spawn-session/` is open,
+the caddis guard denies `git switch`, `checkout`, `restore`, `stash`, `reset`, `rebase` and `clean`
+in either session, and names the worktree command instead. The lock lifts at `handshake close`. A
+handshake older than 24 hours is treated as abandoned and does not hold it. The agy guard does not
+carry this lock yet, so on agy the prompt below is the only protection.
+
+If the child needs another branch before close, it adds a worktree **at that moment**, not at spawn,
+and removes it when the work lands. Leftover worktrees already pile up on this machine, and one made
+eagerly adds to the pile. One consumer repo's `AGENTS.md` records that `git worktree remove --force`
+can follow a junction and delete its target, so check a worktree for junctions before removing it.
+
+**Still say it in the prompt.** A fresh session's instinct on seeing a dirty tree is to tidy it, and
 you are still in that tree.
 
 > While both sessions are live, do **not** run `git checkout`, `switch`, `stash`, `reset`,
@@ -331,7 +380,7 @@ See `.caddis/kb/shared-worktree-branch-switch.md` for detection and the recovery
 Three lines — messaged directly, or carried by the user on the paste route:
 
 ```
-SPAWN <id> | head <sha> | <n> tests | answers in .caddis/spawn-session/<id>-answers.md
+SPAWN <id> | head <sha> | <n> tests | <n> tasks revived | answers in .caddis/spawn-session/<id>-answers.md
 Q1-Q6 answered with citations. <n> commands run. <n> facts I could not find in a file.
 <one line: the single most important thing I believe about the current state>
 ```
@@ -378,7 +427,7 @@ means regenerate" was unenforceable, because nothing counted them.
 ### When the fault is yours, fix the class
 
 If validation finds an error that came from your handover, **fix the source document in the same
-turn** — and fix the class, not the instance. In the manual run a successor found a stale commit
+turn, and commit and push it before you reply** — and fix the class, not the instance. In the manual run a successor found a stale commit
 hash; the fix was not a fresher hash, it was to **remove hashes from both documents** and write the
 command instead. A handover patched per-instance goes stale again on the next commit.
 
@@ -402,8 +451,8 @@ Round 1's verdict sets round 2's size:
 | ACCEPT WITH CORRECTIONS | a **small, reversible** item that writes nothing permanent; review closely |
 | REJECT | no task — re-read and re-answer |
 
-Review the result **by re-deriving it**, exactly as you reviewed the answers — not by reading the
-successor's account of it.
+Review the result **by re-deriving it**, exactly as you reviewed the answers — through a fresh
+subagent, not by reading the successor's account of it.
 
 ### Then stop gating
 
@@ -414,6 +463,27 @@ to remove.
 
 ---
 
+## The parent's ending
+
+The first real run had no ending. The parent stayed live for hours after the handover: it graded
+twice, corrected four documents, merged two PRs and relayed decisions — still paying the token cost
+the handover exists to escape. The owner expected it to close once the successor was proven. It now
+does, in this order:
+
+1. **Before you issue the prompt, land or name your in-flight work.** `preflight` lists local
+   branches that were never pushed or are ahead of their upstream. Push each one and name it in the
+   relay, with what the successor must wait for. Open PRs are not detected — list them yourself. In
+   the first run the successor nearly reverted a fix that sat on the parent's unmerged PR.
+2. **After round 2's review is sent**, run `handshake close`. The handshake reaches `acknowledged`
+   in round 1, but do not close before round 2's review is out. `close` stamps `closed_at`, which
+   lifts the guard's tree lock.
+3. **Commit and push the handshake file.**
+4. **Send the child one last message:** what you handed over, and that you are stopping.
+5. **EXIT.** Tell the product owner the terminal can be closed. Do not stay on as an adviser. The
+   successor has the repo, and the repo is the record.
+
+---
+
 ## Files — all three committed
 
 ```
@@ -439,6 +509,9 @@ chat cannot be reviewed**, and cannot be re-read when the next handover asks wha
 | Write a question whose answer is not in a committed file | it would test memory |
 | Store an answer key | it freezes your belief, and the child can read it. **`check` enforces this** — see round 1 |
 | Grade your own answers | you validate; the child answers |
+| Grade from a nearly-full context | send each round to a fresh subagent; grading needs the repo, not your memory |
+| Tell the child the tree is its own | stopping writing does not transfer the workspace; the guard holds the lock until `close` |
+| Stay on after `close` | the parent's job ends there — see "The parent's ending" |
 | Close on an unanswered handshake | it is the same as never running one. `handshake close` refuses |
 | Read silence as success | a child that skipped the gate looks exactly like one still reading |
 | Proceed when the open-item count is unknown | that count is the integrity check |

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.101",
+  "poolVersion": "1.3.103",
   "bundles": {
-    "antigravity-plugin": "1.3.101",
+    "antigravity-plugin": "1.3.103",
     "antigravity-plugin-extras": "1.3.29",
     "codex": "unknown"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",