@caddis/cli 0.4.97 → 0.4.98

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/bundles/antigravity-plugin/plugin.json +1 -1
  2. package/bundles/antigravity-plugin/repo_hygiene.py +134 -20
  3. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/caddis_gate.py +18 -1
  15. package/bundles/antigravity-plugin/scripts/caddis_guide.json +2 -2
  16. package/bundles/antigravity-plugin/scripts/caddis_handoff.py +235 -0
  17. package/bundles/antigravity-plugin/scripts/caddis_hub_collect.py +23 -12
  18. package/bundles/antigravity-plugin/scripts/caddis_review.py +12 -0
  19. package/bundles/antigravity-plugin/scripts/caddis_tidy.py +152 -51
  20. package/bundles/antigravity-plugin/scripts/caddis_todo.py +136 -17
  21. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +60 -1
  22. package/bundles/antigravity-plugin/scripts/schemas/hub-plans.schema.json +60 -1
  23. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +60 -2
  24. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +6 -0
  25. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +80 -15
  26. package/bundles/antigravity-plugin/skills/implement/SKILL.md +6 -0
  27. package/bundles/antigravity-plugin/skills/park/SKILL.md +7 -2
  28. package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -0
  29. package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -0
  30. package/bundles/manifest.json +2 -2
  31. package/dist/cli.js +71 -14
  32. package/dist/export/assets/export-B3cUoxL1.js +150 -0
  33. package/dist/export/assets/export-DQss44R1.css +1 -0
  34. package/dist/export/index.html +2 -2
  35. package/dist/ui/assets/Activity-CvEIJlnE.js +6 -0
  36. package/dist/ui/assets/{Guide-D-lZVEKf.js → Guide-BxS9L55s.js} +1 -1
  37. package/dist/ui/assets/Guide-DTd261-c.css +1 -0
  38. package/dist/ui/assets/RoadmapTab-CqlWs7dJ.js +31 -0
  39. package/dist/ui/assets/index-9pdDzLVp.css +1 -0
  40. package/dist/ui/assets/index-DSxeWPax.js +231 -0
  41. package/dist/ui/index.html +2 -2
  42. package/package.json +1 -1
  43. package/dist/export/assets/export-B5Lzo-9e.css +0 -1
  44. package/dist/export/assets/export-PF4z_ff4.js +0 -150
  45. package/dist/ui/assets/Activity-DN1XBfsH.js +0 -6
  46. package/dist/ui/assets/Guide-D-Zy4cUT.css +0 -1
  47. package/dist/ui/assets/RoadmapTab-tqQd2sYq.js +0 -31
  48. package/dist/ui/assets/index-CWslZIzV.js +0 -231
  49. package/dist/ui/assets/index-CwgRPpjT.css +0 -1
  50. package/dist/ui/assets/time-D00tu2ZP.js +0 -1
@@ -344,24 +344,30 @@ class _Batch:
344
344
  self.proc.stdout.close()
345
345
 
346
346
 
347
- def _tree_blobs(tree: bytes, oid_len: int) -> list[tuple[str, str]]:
348
- """[(name, blob oid)] from a raw tree object: `<mode> <name>\\0<oid bytes>` repeated. Files only."""
349
- out: list[tuple[str, str]] = []
347
+ def _tree_entries(tree: bytes, oid_len: int) -> list[tuple[bytes, str, str]]:
348
+ """[(mode, name, oid)] from a raw tree object: `<mode> <name>\\0<oid bytes>` repeated."""
349
+ out: list[tuple[bytes, str, str]] = []
350
350
  at = 0
351
351
  while at < len(tree):
352
352
  space = tree.index(b" ", at)
353
353
  nul = tree.index(b"\0", space)
354
354
  mode, name = tree[at:space], tree[space + 1:nul].decode("utf-8", errors="replace")
355
- oid = tree[nul + 1:nul + 1 + oid_len].hex()
355
+ out.append((mode, name, tree[nul + 1:nul + 1 + oid_len].hex()))
356
356
  at = nul + 1 + oid_len
357
- if mode in (b"100644", b"100755"):
358
- out.append((name, oid))
359
357
  return out
360
358
 
361
359
 
362
- def _origin_plan_texts(root: Path, branch: str) -> tuple[str, int | None, list[tuple[str, str]]] | None:
363
- """(commit_oid, commit_at, [(path, text)]) of the plan files on origin/<branch>: `.caddis/plans/*.md`, else
364
- `.github/plans/*.md`, never `done/`. One git process for the whole read. None when git cannot read the ref."""
360
+ def _tree_blobs(tree: bytes, oid_len: int) -> list[tuple[str, str]]:
361
+ """[(name, blob oid)] from a raw tree object. Files only."""
362
+ return [(name, oid) for mode, name, oid in _tree_entries(tree, oid_len) if mode in (b"100644", b"100755")]
363
+
364
+
365
+ def _origin_plan_texts(root: Path, branch: str
366
+ ) -> tuple[str, int | None, list[tuple[str, str]], str | None] | None:
367
+ """(commit_oid, commit_at, [(path, text)], done_tree) of the plan files on origin/<branch>: `.caddis/plans/*.md`,
368
+ else `.github/plans/*.md`, never `done/`. `done_tree` is the oid of `<folder>/done` for the folder that held the
369
+ plans (`.caddis/plans` when none did), read from the folder's tree object, or None when there is no such tree.
370
+ One git process for the whole read. None when git cannot read the ref."""
365
371
  try:
366
372
  batch = _Batch(root)
367
373
  except OSError:
@@ -380,12 +386,18 @@ def _origin_plan_texts(root: Path, branch: str) -> tuple[str, int | None, list[t
380
386
  commit_at = int(line.split()[-2])
381
387
  except (IndexError, ValueError):
382
388
  commit_at = None
383
- for folder in (".caddis/plans", ".github/plans"):
389
+ default_done: str | None = None # the done tree of `.caddis/plans` when no folder holds a current plan
390
+ for folder in (_PLANS_DIR, ".github/plans"):
384
391
  tree = batch.get(f"refs/remotes/origin/{branch}:{folder}")
385
392
  if tree is None or tree[1] != "tree":
386
393
  continue
387
- names = sorted((name, oid) for name, oid in _tree_blobs(tree[2], len(tree[0]) // 2) if name.endswith(".md"))
394
+ entries = _tree_entries(tree[2], len(tree[0]) // 2)
395
+ done_tree = next((oid for mode, name, oid in entries if name == "done" and mode == b"40000"), None)
396
+ names = sorted((name, oid) for mode, name, oid in entries
397
+ if mode in (b"100644", b"100755") and name.endswith(".md"))
388
398
  if not names:
399
+ if folder == _PLANS_DIR:
400
+ default_done = done_tree
389
401
  continue
390
402
  texts: list[tuple[str, str]] = []
391
403
  for name, oid in names:
@@ -393,8 +405,8 @@ def _origin_plan_texts(root: Path, branch: str) -> tuple[str, int | None, list[t
393
405
  if blob is None:
394
406
  return None
395
407
  texts.append((f"{folder}/{name}", blob[2].decode("utf-8", errors="replace").replace("\r\n", "\n")))
396
- return commit_oid, commit_at, texts
397
- return commit_oid, commit_at, []
408
+ return commit_oid, commit_at, texts, done_tree
409
+ return commit_oid, commit_at, [], default_done
398
410
  except (OSError, ValueError):
399
411
  return None
400
412
  finally:
@@ -430,6 +442,106 @@ def _origin_plan_times(root: Path, branch: str, folder: str) -> dict[str, int]:
430
442
  return times
431
443
 
432
444
 
445
+ _PR_SUFFIX = re.compile(r"\(#(\d+)\)")
446
+ _PR_MERGE = re.compile(r"\bMerge pull request #(\d+)\b")
447
+ _TITLE_SUFFIX = re.compile(r"\s+[—–-]+\s*Implementation Plan\s*$", re.I)
448
+
449
+
450
+ def pr_of_subject(subject: str) -> int | None:
451
+ """D3: the PR a commit subject names: the last `(#n)` (squash and Gitea merges), else `Merge pull request #n`."""
452
+ found = _PR_SUFFIX.findall(subject)
453
+ if found:
454
+ return int(found[-1])
455
+ merge = _PR_MERGE.search(subject)
456
+ return int(merge.group(1)) if merge else None
457
+
458
+
459
+ def done_entry(rel: str, text: str, closed_at: int | None, pr: int | None) -> dict:
460
+ """D5: one done-plan row. Title from the first `# ` heading less ` — Implementation Plan`; phases = Tracker
461
+ rows, else unique `Phase` headings."""
462
+ entry = _plan_entry_text(rel, text)
463
+ title = entry["title"] if isinstance(entry["title"], str) and entry["title"].strip() else None
464
+ title = (_TITLE_SUFFIX.sub("", title).strip() if title else "") or rel.rsplit("/", 1)[-1].removesuffix(".md")
465
+ return {"path": rel, "title": title, "closed_at": closed_at,
466
+ "phases": len(entry["tracker"]) or len(entry["phases"]), "pr": pr}
467
+
468
+
469
+ def _origin_done_adds(root: Path, branch: str, folder: str) -> dict[str, tuple[int, int | None]]:
470
+ """{path: (commit time, PR)} of the newest first-parent commit on origin/<branch> that ADDED each file under
471
+ `<folder>/done` (D3). One local git process. Empty when git fails: the date is shown as unknown."""
472
+ try:
473
+ out = subprocess.run(
474
+ ["git", "-C", str(root), "-c", "core.quotepath=off", "log", "--no-renames", "--first-parent",
475
+ "--diff-merges=first-parent", "--diff-filter=A", "--format=%x00%ct%x09%s", "--name-only",
476
+ f"refs/remotes/origin/{branch}", "--", f"{folder}/done"],
477
+ capture_output=True, timeout=30, creationflags=_NO_WINDOW,
478
+ )
479
+ except (OSError, subprocess.SubprocessError):
480
+ return {}
481
+ if out.returncode != 0:
482
+ return {}
483
+ adds: dict[str, tuple[int, int | None]] = {}
484
+ for chunk in out.stdout.decode("utf-8", errors="replace").split("\x00")[1:]:
485
+ lines = chunk.splitlines()
486
+ if not lines:
487
+ continue
488
+ when, _, subject = lines[0].partition("\t")
489
+ try:
490
+ at = int(when)
491
+ except ValueError:
492
+ continue
493
+ pr = pr_of_subject(subject)
494
+ for name in lines[1:]:
495
+ if name.strip():
496
+ adds.setdefault(name.strip(), (at, pr)) # git log is newest first: the first add seen is the newest
497
+ return adds
498
+
499
+
500
+ def done_plans(root: Path, branch: str, folder: str, tree_oid: str) -> dict:
501
+ """`{"tree": tree_oid, "plans": [...]}`: every `<folder>/done/*.md` in the tree, newest close first, then path
502
+ A-Z; no close date sorts last (D4). One `git log` and one `cat-file --batch`. A file that fails gives
503
+ `{"path", "error"}`."""
504
+ adds = _origin_done_adds(root, branch, folder)
505
+ rows: list[dict] = []
506
+ batch = _Batch(root)
507
+ try:
508
+ tree = batch.get(tree_oid)
509
+ if tree is None or tree[1] != "tree":
510
+ raise ValueError(f"{folder}/done is not a tree on origin/{branch}")
511
+ for name, oid in sorted(_tree_blobs(tree[2], len(tree[0]) // 2)):
512
+ if not name.endswith(".md"):
513
+ continue
514
+ rel = f"{folder}/done/{name}"
515
+ blob = batch.get(oid)
516
+ if blob is None:
517
+ rows.append({"path": rel, "error": "the file is missing from the git store"})
518
+ continue
519
+ text = blob[2].decode("utf-8", errors="replace").replace("\r\n", "\n")
520
+ closed_at, pr = adds.get(rel, (None, None))
521
+ rows.append(_entry_or_error(rel, lambda rel=rel, text=text, closed_at=closed_at, pr=pr:
522
+ done_entry(rel, text, closed_at, pr)))
523
+ finally:
524
+ batch.close()
525
+
526
+ def order(row: dict) -> tuple:
527
+ at = adds.get(row["path"], (None, None))[0]
528
+ return (at is None, -(at or 0), row["path"])
529
+
530
+ return {"tree": tree_oid, "plans": sorted(rows, key=order)}
531
+
532
+
533
+ def _done_slot(root: Path, branch: str, folder: str, tree: str | None, known: str | None) -> dict:
534
+ """D2/D6: the `done` value of an origin source."""
535
+ if tree is None:
536
+ return {"tree": None, "plans": []}
537
+ if tree == known:
538
+ return {"tree": tree, "unchanged": True}
539
+ try:
540
+ return done_plans(root, branch, folder, tree)
541
+ except Exception as exc: # done plans must never hide the current plans
542
+ return {"error": (str(exc).splitlines() or [type(exc).__name__])[0]}
543
+
544
+
433
545
  def _file_time(path: Path) -> int | None:
434
546
  try:
435
547
  return int(path.stat().st_mtime)
@@ -548,26 +660,33 @@ def _overlay_prs(root: Path, branch: str, plans: list[dict], prs: list[dict]) ->
548
660
  return count
549
661
 
550
662
 
551
- def plans_json(root: Path, branch: str | None = None, prs: list[dict] | None = None) -> dict:
663
+ def plans_json(root: Path, branch: str | None = None, prs: list[dict] | None = None,
664
+ done_known: str | None = None) -> dict:
552
665
  """Every current plan as data: `{"schema": 1, "source": ..., "plans": [...]}`. Never prints, never exits.
553
666
 
554
667
  With `branch`, read the plans from the local `origin/<branch>` ref (the hub: a pushed Tracker edit shows with
555
668
  no pull); when git cannot read that ref, read the working tree. `source` names which one was read. A file that
556
669
  does not parse gives `{"path", "error"}`; the other plans still come back.
557
670
 
671
+ An origin source also carries `done` (the finished plans in `<folder>/done`): `{"tree": None, "plans": []}`
672
+ with no done tree, `{"tree": t, "unchanged": True}` when `t == done_known` (the caller keeps its list),
673
+ `{"tree": t, "plans": [...]}` (`done_plans`), or `{"error": ...}`. A working-tree source has no `done` key.
674
+
558
675
  With `prs` (the open PRs, D2 items) and an origin source, plans a PR branch changed get that branch's Tracker
559
676
  laid over main's (`overlay_plan`) and the result carries `overlay`. Without `prs` the output has no overlay key.
560
677
  """
561
678
  root = Path(root)
562
679
  origin = _origin_plan_texts(root, branch) if branch else None
563
680
  if origin is not None:
564
- commit, commit_at, texts = origin
681
+ commit, commit_at, texts, done_tree = origin
682
+ folder = texts[0][0].rsplit("/", 1)[0] if texts else _PLANS_DIR
565
683
  plans = [_entry_or_error(rel, lambda rel=rel, text=text: _plan_entry_text(rel, text)) for rel, text in texts]
566
- times = _origin_plan_times(root, branch, texts[0][0].rsplit("/", 1)[0]) if texts else {}
684
+ times = _origin_plan_times(root, branch, folder) if texts else {}
567
685
  for plan in plans:
568
686
  if "error" not in plan:
569
687
  plan["changed_at"] = times.get(plan["path"])
570
- data = {"schema": 1, "source": f"origin/{branch}", "commit": commit[:12], "commit_at": commit_at, "plans": plans}
688
+ data = {"schema": 1, "source": f"origin/{branch}", "commit": commit[:12], "commit_at": commit_at, "plans": plans,
689
+ "done": _done_slot(root, branch, folder, done_tree, done_known)}
571
690
  if prs is not None:
572
691
  count = _overlay_prs(root, branch, plans, prs)
573
692
  data["overlay"] = {"state": "on", "reason": None, "count": count}
@@ -389,6 +389,62 @@
389
389
  }
390
390
  }
391
391
  },
392
+ "done": {
393
+ "description": "Finished plans from origin/<default>:.caddis/plans/done (origin source only). unchanged: the tree equals --done-known.",
394
+ "type": "object",
395
+ "properties": {
396
+ "tree": {
397
+ "type": [
398
+ "string",
399
+ "null"
400
+ ]
401
+ },
402
+ "unchanged": {
403
+ "const": true
404
+ },
405
+ "error": {
406
+ "type": "string"
407
+ },
408
+ "plans": {
409
+ "type": "array",
410
+ "items": {
411
+ "type": "object",
412
+ "required": [
413
+ "path"
414
+ ],
415
+ "properties": {
416
+ "path": {
417
+ "type": "string"
418
+ },
419
+ "title": {
420
+ "type": [
421
+ "string",
422
+ "null"
423
+ ]
424
+ },
425
+ "closed_at": {
426
+ "type": [
427
+ "integer",
428
+ "null"
429
+ ]
430
+ },
431
+ "phases": {
432
+ "type": "integer"
433
+ },
434
+ "pr": {
435
+ "type": [
436
+ "integer",
437
+ "null"
438
+ ]
439
+ },
440
+ "error": {
441
+ "type": "string"
442
+ }
443
+ }
444
+ }
445
+ }
446
+ }
447
+ },
392
448
  "plans": {
393
449
  "type": "array",
394
450
  "items": {
@@ -464,7 +520,10 @@
464
520
  "type": "integer"
465
521
  },
466
522
  "changed_at": {
467
- "type": ["integer", "null"],
523
+ "type": [
524
+ "integer",
525
+ "null"
526
+ ],
468
527
  "description": "Unix time of the last change: the commit time on origin, or the file time in the working tree. null when unknown."
469
528
  },
470
529
  "overlay": {
@@ -62,6 +62,62 @@
62
62
  }
63
63
  }
64
64
  },
65
+ "done": {
66
+ "description": "Finished plans from origin/<default>:.caddis/plans/done (origin source only). unchanged: the tree equals --done-known.",
67
+ "type": "object",
68
+ "properties": {
69
+ "tree": {
70
+ "type": [
71
+ "string",
72
+ "null"
73
+ ]
74
+ },
75
+ "unchanged": {
76
+ "const": true
77
+ },
78
+ "error": {
79
+ "type": "string"
80
+ },
81
+ "plans": {
82
+ "type": "array",
83
+ "items": {
84
+ "type": "object",
85
+ "required": [
86
+ "path"
87
+ ],
88
+ "properties": {
89
+ "path": {
90
+ "type": "string"
91
+ },
92
+ "title": {
93
+ "type": [
94
+ "string",
95
+ "null"
96
+ ]
97
+ },
98
+ "closed_at": {
99
+ "type": [
100
+ "integer",
101
+ "null"
102
+ ]
103
+ },
104
+ "phases": {
105
+ "type": "integer"
106
+ },
107
+ "pr": {
108
+ "type": [
109
+ "integer",
110
+ "null"
111
+ ]
112
+ },
113
+ "error": {
114
+ "type": "string"
115
+ }
116
+ }
117
+ }
118
+ }
119
+ }
120
+ },
65
121
  "plans": {
66
122
  "type": "array",
67
123
  "items": {
@@ -137,7 +193,10 @@
137
193
  "type": "integer"
138
194
  },
139
195
  "changed_at": {
140
- "type": ["integer", "null"],
196
+ "type": [
197
+ "integer",
198
+ "null"
199
+ ],
141
200
  "description": "Unix time of the last change: the commit time on origin, or the file time in the working tree. null when unknown."
142
201
  },
143
202
  "overlay": {
@@ -1603,7 +1603,7 @@ life. `future` asks whether we have committed to it. An item can be `status: ope
1603
1603
  |---|---|
1604
1604
  | `open` | Raised, not started. |
1605
1605
  | `doing` | Someone is on it now. |
1606
- | `done` | Finished. `caddis_tidy.py --apply` moves it to `done/`. |
1606
+ | `done` | Finished. `caddis_tidy.py --apply --only <this item>` moves it to `done/`. |
1607
1607
  | `dropped` | Deliberately abandoned. **Write why in the body**, or the next session re-raises it. |
1608
1608
 
1609
1609
  The list is closed on purpose. `wip`, `todo` and `pending` are not accepted, because "how many open
@@ -1629,7 +1629,8 @@ items?" has no answer when one state has three spellings.
1629
1629
 
1630
1630
  - `/caddis:park` - file an item correctly, or list what is open.
1631
1631
  - `python scripts/caddis_tidy.py --check` - fails (exit 1) on any item that breaks the contract.
1632
- - `python scripts/caddis_tidy.py --apply` - sweeps `done` and `dropped` items into `done/`.
1632
+ - `python scripts/caddis_tidy.py --apply --only .caddis/parking-lot/<item>.md` - moves your own `done` or
1633
+ `dropped` item into `done/`. A bare `--apply` exits 1; `--apply --all` sweeps every finished item (the owner's call).
1633
1634
  """
1634
1635
 
1635
1636
 
@@ -2080,6 +2081,60 @@ def ensure_superpowers_deny(dry: bool, home: Path | None = None) -> str:
2080
2081
  return f"superpowers deny rules: {verb} {len(missing)} to permissions.deny in {path}"
2081
2082
 
2082
2083
 
2084
+ # ── Orca worktree cache ─────────────────────────────────────────────────────────────────────
2085
+ # The session-start hook (claude-harness/hooks/repo_hygiene.py) waits at most 3 s for `orca worktree list`. A cold
2086
+ # call can take longer (9.5 s on the owner's server), so the hook keeps the answer in this file. Setup fills it once,
2087
+ # with a long time limit, so the first session start on a new machine already has an answer.
2088
+ ORCA_CACHE_NAME = "orca-worktrees.json" # must equal repo_hygiene.ORCA_CACHE_NAME (a test checks)
2089
+ ORCA_WARM_TIMEOUT_S = 30.0
2090
+
2091
+
2092
+ def warm_orca_cache(dry: bool, home: Path | None = None, run=None, which=shutil.which) -> str:
2093
+ """Ask orca for its worktree list once and write `~/.caddis/orca-worktrees.json`. Writes only a complete list
2094
+ (`ok` true, not truncated). Every failure is a "skipped" line, never an error: setup goes on.
2095
+ `CADDIS_NO_ORCA_WARM` skips it."""
2096
+ if os.environ.get("CADDIS_NO_ORCA_WARM"):
2097
+ return "orca cache: skipped (CADDIS_NO_ORCA_WARM set)"
2098
+ exe = which("orca")
2099
+ if not exe:
2100
+ return "orca cache: skipped (orca not on PATH)"
2101
+ root = home or Path(os.environ.get("CADDIS_HOME") or Path.home())
2102
+ dest = root / ".caddis" / ORCA_CACHE_NAME
2103
+ if dry:
2104
+ return f"orca cache: would ask orca once and write {dest}"
2105
+ import subprocess
2106
+ argv = [exe, "worktree", "list", "--limit", "10000", "--json"]
2107
+ kw = {"capture_output": True, "text": True, "encoding": "utf-8", "errors": "replace",
2108
+ "timeout": ORCA_WARM_TIMEOUT_S, "stdin": subprocess.DEVNULL, "check": False}
2109
+ try:
2110
+ if run is not None: # the test seam
2111
+ proc = run(argv, **kw)
2112
+ else:
2113
+ proc = subprocess.run(argv, **kw, creationflags=0x08000000 if os.name == "nt" else 0)
2114
+ except subprocess.TimeoutExpired:
2115
+ return f"orca cache: skipped (orca took longer than {ORCA_WARM_TIMEOUT_S:g} s)"
2116
+ except OSError as exc:
2117
+ return f"orca cache: skipped (orca could not start: {exc})"
2118
+ if proc.returncode != 0:
2119
+ last = (proc.stderr or proc.stdout or "").strip().splitlines()
2120
+ return f"orca cache: skipped ({last[-1].strip() if last else f'orca exited {proc.returncode}'})"
2121
+ try:
2122
+ data = json.loads(proc.stdout)
2123
+ except ValueError:
2124
+ data = None
2125
+ result = data.get("result") if isinstance(data, dict) and data.get("ok") is True else None
2126
+ if not isinstance(result, dict) or not isinstance(result.get("worktrees"), list) or result.get("truncated"):
2127
+ return "orca cache: skipped (orca did not return a complete worktree list)"
2128
+ try:
2129
+ dest.parent.mkdir(parents=True, exist_ok=True)
2130
+ tmp = dest.with_name(f"{dest.name}.{os.getpid()}.tmp")
2131
+ tmp.write_text(proc.stdout, encoding="utf-8")
2132
+ os.replace(tmp, dest)
2133
+ except OSError as exc:
2134
+ return f"orca cache: skipped (could not write {dest}: {exc})"
2135
+ return f"orca cache: wrote {dest} ({len(result['worktrees'])} worktrees)"
2136
+
2137
+
2083
2138
  CLEANUP_PERIOD_KEY = "cleanupPeriodDays"
2084
2139
  CLEANUP_PERIOD_DAYS = 120
2085
2140
 
@@ -2438,6 +2493,9 @@ def main() -> int:
2438
2493
  print(f" {ensure_cleanup_period(args.dry_run)}")
2439
2494
  print(f" {ensure_superpowers_deny(args.dry_run)}")
2440
2495
 
2496
+ print("-- Orca worktree cache (so the first session start does not wait for orca)")
2497
+ print(f" {warm_orca_cache(args.dry_run)}")
2498
+
2441
2499
  print("-- doc-coverage discipline (DOC-MAP + page guide + checker)")
2442
2500
  for line in emit_doc_discipline(target, ident, args.force, args.dry_run):
2443
2501
  print(f" {line}")
@@ -126,6 +126,12 @@ a reason.
126
126
  the first CLEAN. Tier 2: one review by another vendor (two only when the owner asks). Fix blocking findings only;
127
127
  park the rest. Re-review only the fix diff, and only when the fix changed logic. After 3 rounds, ask the owner.
128
128
 
129
+ **Area reviewers.** `review-tier` also prints an `AREA:` line. For each name on it, dispatch that subagent once, at the end of the phase, after the tier review.
130
+ - `security-analyst`: review `git diff <base>...HEAD`.
131
+ - `ui-design-reviewer`: give it the app URL from the phase exit gate, or the run command in `.caddis/PROJECT-FACTS.md`. If no app is running, write `UI review skipped: no running app` in the review file.
132
+ - Security findings of `critical` or `high` severity are blocking. UI findings that break use or WCAG AA are blocking. Fix them under the same 3-round limit. Park all other findings in the parking lot.
133
+ - `AREA: none`: run nothing extra.
134
+
129
135
  A diff over the batch ceiling is split into batches. Each batch prompt lists every file in the
130
136
  change, so a batch does not report the others as missing.
131
137
 
@@ -42,7 +42,8 @@ them into its commit, so check first, before Step 1.
42
42
  - Step 1: tell the `knowledge-transfer` subagent to edit files ONLY under the `WORKTREE:` path.
43
43
  - Step 3, point 4: make the plan's Tracker edit in `<worktree>/.caddis/plans/<feature>.md`, and write
44
44
  any new parking-lot item under `<worktree>/.caddis/parking-lot/`, not in this checkout.
45
- - Step 4: skip `caddis_tidy.py --apply` (report `skipped: shared checkout`).
45
+ - Step 4: run the tidy in the worktree (`--repo-root <worktree>`), never in this checkout. With no
46
+ worktree (no remote), skip it (report `skipped: shared checkout`).
46
47
  - Step 6b: skip `session_state.py prune` (report `skipped: shared checkout`).
47
48
  - Step 6c: run `--reindex` in the worktree (it edits the tracked `DOC-MAP.md`).
48
49
  - Step 6d: runs as written. It never writes a file in this checkout; it only removes worktrees and
@@ -70,13 +71,14 @@ Step 8 prints all 12 in this order. Never drop a row from the report, even when
70
71
  | 5 | `kb-index` | Step 6c: refresh the KB index | in the Step 0 worktree |
71
72
  | 6 | `violations-report` | Step 6c: report standing violations, each with a one-line fix command | runs (report only) |
72
73
  | 7 | `usage-record` | Step 6b: `session_state.py usage` | runs |
73
- | 8 | `tidy-apply` | Step 4: `caddis_tidy.py --apply` | `skipped: shared checkout` |
74
+ | 8 | `tidy-apply` | Step 4: `caddis_tidy.py --apply --only` this session's own finished artifacts | in the Step 0 worktree; no worktree: `skipped: shared checkout` |
74
75
  | 9 | `state-prune` | Step 6b: `session_state.py prune` | `skipped: shared checkout` |
75
76
  | 10 | `prune-list` | Step 6b: `caddis_tidy.py --prune --temp`, list only | runs (lists, never applies) |
76
77
  | 11 | `handover-check` | Step 5 | runs |
77
78
  | 12 | `own-cleanup` | Step 6d: `caddis_created.py cleanup --apply` removes this session's merged, clean worktrees and scratch folders; lists the rest with a reason | runs (only this session's recorded worktrees and scratch) |
78
79
 
79
- `tidy-apply` and `state-prune` run only on `SHARED: no`. Handoff never runs
80
+ `state-prune` runs only on `SHARED: no`; `tidy-apply` writes in this checkout only on `SHARED: no` and off the
81
+ default branch (Step 4). Handoff never runs a bare `caddis_tidy.py --apply` (it exits 1) nor `--apply --all`, and never runs
80
82
  `caddis_tidy.py --prune --apply` on its own, in any checkout (nor `--prune --temp --apply`); only the user can ask for it (Step 6b). In a
81
83
  shared checkout the report also lists every tracked file Step 1 changed, under `Docs PR needed:`.
82
84
 
@@ -332,18 +334,80 @@ tasks file exists and is not named. If you wrote the relay before running this,
332
334
  Step 3, point 5.
333
335
 
334
336
  ## Step 4 — tidy finished artifacts
335
- Flip any plan/prompt's frontmatter `status:` to `done` (or `superseded`) if this session actually
336
- finished it — that is your judgment call; the script below never makes it and never auto-flips
337
- status. In a shared checkout (Step 0), make the `status:` flip in the Step 0 worktree copy of the plan,
338
- never in this checkout. Then run (skip it in a shared checkout, Step 0: it moves tracked files):
339
- ```
340
- python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply
341
- ```
342
- (falls back to `scripts/caddis_tidy.py` from a source checkout). **If the script is missing,
343
- skip this step** — it degrades open, same as the other machine gates; an older install must not
344
- be blocked by a script it does not have. Include its report in your output. A **collision**
337
+ Flip a prompt's or parking-lot item's frontmatter `status:` to `done` (or `superseded` / `dropped`) only if
338
+ this session actually finished it — that is your judgment call. The script sets a plan's `status: done` by
339
+ itself only when every `## Tracker` row is `done`. In a shared checkout (Step 0), make the `status:` flip in
340
+ the Step 0 worktree copy, never in this checkout.
341
+
342
+ **Close only this session's own artifacts.** On 2026-11-07 a bare `caddis_tidy.py --apply` here moved and
343
+ staged 5 finished items that other sessions owned. A bare `--apply` now exits 1; never pass `--all` here (that
344
+ is the owner's sweep).
345
+
346
+ 1. List this session's own finished artifacts from the Step 0 own-files temp file (in a shared checkout, add
347
+ `--root <worktree>`):
348
+ ```
349
+ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" tidy-targets --own-files <temp-file>
350
+ ```
351
+ It prints one repo-relative path per line: each top-level plan, prompt or parking-lot item in this
352
+ session's own files that tidy would move or holds for open Tracker rows. Another session's finished item
353
+ is never printed. **If it prints
354
+ nothing,** row 8 is `skipped: this session closed no artifact`; go on to the `mentions` check below. The
355
+ own-files list holds only the last 12 files this session edited, so an item may be missing; it then stays
356
+ in place, and the SessionStart nudge still lists it. That is the safe side.
357
+ 2. Pick the checkout to run in:
358
+ - **Shared checkout, Step 0 made a worktree:** the worktree, where this session made its status flips.
359
+ The Step 0 `finish` commits the moves in the docs PR. No worktree (no remote): skip, row 8 is
360
+ `skipped: shared checkout`.
361
+ - **`SHARED: no` and this checkout is on the default branch** (`git branch --show-current` equals
362
+ `<default>`: `git symbolic-ref --short refs/remotes/origin/HEAD` with the `origin/` prefix removed):
363
+ never leave staged moves here, where any session's next commit takes them. Work in a docs-PR
364
+ worktree, in this order. Each step runs only when the one before it succeeded:
365
+ 1. List only what tidy can move now (no held plan, no collision; those stay here, untouched, and the
366
+ point 1 list still reports them):
367
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" tidy-targets --own-files <temp-file> --movable`.
368
+ If it prints nothing, row 8 reports the point 1 list and no worktree is made.
369
+ 2. `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_docs_pr.py" start --repo .` prints `WORKTREE: <path>`.
370
+ 3. The worktree comes from `origin/<default>`, so it lacks this session's local status flips. Copy the
371
+ movable paths into it (`CARRIED: <path>` per file). `carry` only copies: it never changes this checkout.
372
+ If one copy fails, it puts the worktree back and exits 1.
373
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" carry --to <worktree> <path> [<path> ...]`
374
+ 4. Run tidy (point 3) with `--repo-root <worktree>` and the same paths.
375
+ 5. Read the branch name with `git -C <worktree> branch --show-current`, then open the docs PR:
376
+ ```
377
+ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_docs_pr.py" finish --worktree <path> --title "docs(tidy): move finished artifacts to done/" --body "Handoff Step 4: this session's own finished artifacts only."
378
+ ```
379
+ Report its `PR:` line (or `PATCH:`).
380
+ 6. Only after `finish` printed `PR: <url>`, restore those paths in this checkout:
381
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" release --branch <branch> <path> [<path> ...]`.
382
+ It fetches the branch and restores a path only when the branch holds its moved copy in `done/` with the
383
+ same content; it prints `released: <path>` or `kept: <path> (<reason>)`. Report each `kept` line.
384
+
385
+ **If `carry`, tidy or `finish` fails, do not run `release`:** this checkout still holds every edit. Still
386
+ run `finish` after a failed `carry` or tidy, because it removes the worktree (with no change it prints
387
+ `PR: none`; a PR it opens holds only this session's copied edits). Row 8 is then `failed: <step>`.
388
+ **If `start` exits 3 (no remote), do not run tidy in this checkout:** row 8 is
389
+ `skipped: no remote; moves not staged on the default branch`. Print the dry run, which changes nothing:
390
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --repo-root . --only <path> [<path> ...]`.
391
+ - **Otherwise** (a feature branch): this checkout.
392
+ 3. Run tidy with every printed path after `--only` (`<checkout>` is `.` or the worktree path):
393
+ ```
394
+ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --repo-root <checkout> --apply --only <path> [<path> ...]
395
+ ```
396
+ 4. **After a run in this checkout,** the moves are staged, not committed. Tidy prints one
397
+ `STAGED: <old> -> <new>` line per move and the exact pathspec command
398
+ `git commit -m "chore(tidy): ..." -- <old> <new> ...`. Show those lines and tell the user: commit the moves
399
+ with that command (it commits only those paths), or undo each one with `git mv <new> <old>`. Never leave
400
+ them staged on the default branch.
401
+
402
+ (Both scripts fall back to `scripts/` from a source checkout.) **If a script is missing, or `tidy-targets` is
403
+ unknown (an older install), skip this step** — it degrades open, same as the other machine gates; an older install must not
404
+ be blocked by a script it does not have. Include the tidy report in your output. A **collision**
345
405
  (`done/<name>` already exists) is reported by the script, not fatal — surface it, do not fail the
346
406
  handoff over it. Exit 2 means a plan is held because its Tracker still has open rows (`held (open Tracker rows): ...` lines, from Phase 3): show those lines; finish, park (`.caddis/parking-lot/<file>.md` in the row) or mark the rows `dropped: <reason>`, or set the plan status back. Do not fail the handoff over it.
407
+ Exit 1 with `the index already holds staged changes` means tidy moved nothing: row 8 is
408
+ `failed: index holds staged changes`. Report the paths; never unstage or commit them yourself (they may be
409
+ another session's). A file `--only` names moves even with an uncommitted edit (this session's status
410
+ flip): tidy stages its working copy at the new path. Only an `--all` sweep skips files with uncommitted edits.
347
411
 
348
412
  After step 4, for each item this session closed (a phase `<plan>#<n>`, a plan slug, or a parking-lot slug), run `mentions` to check whether another relay's Next step still names it:
349
413
  ```
@@ -410,7 +474,7 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_budget.py" check --root . --report
410
474
  `caddis_budget.py` lists each handoff-grown file over its size budget (`OVER <path>: ...; fix: <rule>`); the
411
475
  `fix:` text is the one-line fix for that row.
412
476
  List each violation they print with a one-line command that fixes it (for example `/caddis:kb` for an
413
- un-indexed note, or `caddis_tidy.py --apply` for a finished artifact in the wrong folder). A violation is
477
+ un-indexed note, or `caddis_tidy.py --apply --only <path>` for a finished artifact in the wrong folder). A violation is
414
478
  not a failure of the handoff: the row is `done` when all three ran. If a script is missing, the row is
415
479
  `skipped: <script> not installed`.
416
480
 
@@ -574,7 +638,8 @@ The `cd` makes the relay's repo-relative paths work from any terminal folder (`;
574
638
  - Only verified facts and real paths. Mark anything unconfirmed as `Unknown`.
575
639
  - Update the plan's tracker rows too (status + last commit) — relay and tracker must agree. In a shared
576
640
  checkout, edit the Tracker in the Step 0 worktree, never in this checkout.
577
- - Don't commit unless asked. Report which `.caddis/relay/<name>.md` was written and the one next action.
641
+ - Don't commit unless asked (the docs PRs that Step 0 and Step 4 open from their own worktrees are the
642
+ exception). Report which `.caddis/relay/<name>.md` was written and the one next action.
578
643
  - **Prune the Done section — two rules, both apply:**
579
644
  1. **Merge-based:** Phases already merged to `main` (confirmed by a tag or commit) must be compressed
580
645
  to a single line: `- **RW-N**: merged to main as vYYYY.MM.DD.N (<commit>) ✅`. Only the current
@@ -163,6 +163,12 @@ A headless session (`CADDIS_HEADLESS` set) never starts a wave: it is a wave mem
163
163
  4. Error paths return or raise. None is swallowed.
164
164
  5. The diff touches only the phase's files.
165
165
 
166
+ **Area reviewers.** `review-tier` also prints an `AREA:` line. For each name on it, dispatch that subagent once, at the end of the phase, after the tier review.
167
+ - `security-analyst`: review `git diff <base>...HEAD`.
168
+ - `ui-design-reviewer`: give it the app URL from the phase exit gate, or the run command in `.caddis/PROJECT-FACTS.md`. If no app is running, write `UI review skipped: no running app` in the review file.
169
+ - Security findings of `critical` or `high` severity are blocking. UI findings that break use or WCAG AA are blocking. Fix them under the same 3-round limit. Park all other findings in the parking lot.
170
+ - `AREA: none`: run nothing extra.
171
+
166
172
  This run is headless, so "ask the owner" (after 3 rounds) means: stop the phase, do not commit it, and record the
167
173
  blocking findings of the 3 rounds in the review file.
168
174
 
@@ -151,5 +151,10 @@ If the directory is empty, say so in one line. Do not invent items.
151
151
  3. **For `dropped`, append a `## Why dropped` section.** This is not optional. An item deleted with
152
152
  no reason gets re-raised by the next session that has the same idea; an item kept with "no,
153
153
  because ..." does not.
154
- 4. Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply`, which moves it into `.caddis/parking-lot/done/`.
155
- 5. Report the file's new path in one line.
154
+ 4. Move only this item, never another session's finished item (a bare `--apply` exits 1; never pass `--all`):
155
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply --only .caddis/parking-lot/<slug>.md`.
156
+ It moves it into `.caddis/parking-lot/done/` and stages the move together with the uncommitted status
157
+ edit from steps 2 and 3 (a file `--only` names moves with its edit). If it refuses because the index holds
158
+ other staged changes, report the paths and stop; never unstage or commit them yourself.
159
+ 5. Report the file's new path in one line, with tidy's `STAGED:` line and its `git commit ... -- <old> <new>`
160
+ line, so the user can commit the move (or undo it with `git mv <new> <old>`).