@caddis/cli 0.4.87 → 0.4.89

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 (81) hide show
  1. package/README.md +46 -0
  2. package/bundles/antigravity-plugin/agents/preflight.md +4 -0
  3. package/bundles/antigravity-plugin/plugin.json +1 -1
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +28 -6
  16. package/bundles/antigravity-plugin/scripts/caddis_guide.json +2418 -0
  17. package/bundles/antigravity-plugin/scripts/caddis_handoff.py +370 -0
  18. package/bundles/antigravity-plugin/scripts/caddis_heartbeat.py +339 -0
  19. package/bundles/antigravity-plugin/scripts/caddis_hub_collect.py +60 -9
  20. package/bundles/antigravity-plugin/scripts/caddis_routing.py +36 -0
  21. package/bundles/antigravity-plugin/scripts/caddis_todo.py +101 -12
  22. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +46 -0
  23. package/bundles/antigravity-plugin/scripts/schemas/hub-plans.schema.json +27 -0
  24. package/bundles/antigravity-plugin/session_end_agy.py +26 -1
  25. package/bundles/antigravity-plugin/skills/coordinate/SKILL.md +5 -3
  26. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +47 -19
  27. package/bundles/antigravity-plugin/skills/fleet-open/SKILL.md +1 -1
  28. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +77 -6
  29. package/bundles/antigravity-plugin/skills/implement/SKILL.md +67 -5
  30. package/bundles/antigravity-plugin/warm_start_agy.py +29 -1
  31. package/bundles/manifest.json +2 -2
  32. package/dist/allowed-urls.txt +3 -2
  33. package/dist/cli.js +545 -274
  34. package/dist/export/assets/export-B7BBDg5I.js +150 -0
  35. package/dist/export/assets/export-HxTgj3z2.css +1 -0
  36. package/dist/export/assets/mark-anim-DZa95SHo.webp +0 -0
  37. package/dist/export/assets/mark-still-CcPgBc_-.png +0 -0
  38. package/dist/export/fonts/ibm-plex-mono-400.6d569bb7.woff2 +0 -0
  39. package/dist/export/fonts/ibm-plex-mono-700.9f478677.woff2 +0 -0
  40. package/dist/export/fonts/ibm-plex-sans-400.17fc1ce7.woff2 +0 -0
  41. package/dist/export/fonts/ibm-plex-sans-500.dcc69acf.woff2 +0 -0
  42. package/dist/export/fonts/ibm-plex-sans-600.d4dad061.woff2 +0 -0
  43. package/dist/export/fonts/ibm-plex-sans-700.40d9a530.woff2 +0 -0
  44. package/dist/export/index.html +2 -2
  45. package/dist/export/licenses/{OFL-MapleMono.txt → OFL-IBMPlexMono.txt} +4 -4
  46. package/dist/{ui/licenses/OFL-MapleMono.txt → export/licenses/OFL-IBMPlexSans.txt} +4 -4
  47. package/dist/ui/assets/{Activity-BgqFFOv1.js → Activity-DZKPMOeV.js} +1 -1
  48. package/dist/ui/assets/Guide-5ZFfL6sl.js +9 -0
  49. package/dist/ui/assets/Guide-Dnsb-TRd.css +1 -0
  50. package/dist/ui/assets/RoadmapTab-DPsiSmIF.js +31 -0
  51. package/dist/ui/assets/index-DGlNAmeA.css +1 -0
  52. package/dist/ui/assets/index-xl156OCN.js +231 -0
  53. package/dist/ui/assets/mark-anim-DZa95SHo.webp +0 -0
  54. package/dist/ui/assets/mark-still-CcPgBc_-.png +0 -0
  55. package/dist/ui/fonts/ibm-plex-mono-400.6d569bb7.woff2 +0 -0
  56. package/dist/ui/fonts/ibm-plex-mono-700.9f478677.woff2 +0 -0
  57. package/dist/ui/fonts/ibm-plex-sans-400.17fc1ce7.woff2 +0 -0
  58. package/dist/ui/fonts/ibm-plex-sans-500.dcc69acf.woff2 +0 -0
  59. package/dist/ui/fonts/ibm-plex-sans-600.d4dad061.woff2 +0 -0
  60. package/dist/ui/fonts/ibm-plex-sans-700.40d9a530.woff2 +0 -0
  61. package/dist/ui/index.html +2 -2
  62. package/dist/{export/licenses/OFL-Atkinson.txt → ui/licenses/OFL-IBMPlexMono.txt} +3 -3
  63. package/dist/ui/licenses/{OFL-Atkinson.txt → OFL-IBMPlexSans.txt} +3 -3
  64. package/package.json +4 -1
  65. package/dist/export/assets/export-Dro73_I7.js +0 -150
  66. package/dist/export/assets/export-N0paGhbL.css +0 -1
  67. package/dist/export/assets/mark-small-CwCIyjyC.svg +0 -8
  68. package/dist/export/fonts/atkinson-400.849ae6f0.woff2 +0 -0
  69. package/dist/export/fonts/atkinson-700.3a9cc18a.woff2 +0 -0
  70. package/dist/export/fonts/maple-mono-400.071799fd.woff2 +0 -0
  71. package/dist/export/fonts/maple-mono-700.1e17b237.woff2 +0 -0
  72. package/dist/ui/assets/Guide-Df0Kg8wI.js +0 -9
  73. package/dist/ui/assets/Guide-zcVFGUxR.css +0 -1
  74. package/dist/ui/assets/RoadmapTab-CV7WCGBL.js +0 -31
  75. package/dist/ui/assets/index-DEge93wH.css +0 -1
  76. package/dist/ui/assets/index-DQbpiY2a.js +0 -221
  77. package/dist/ui/assets/mark-small-CwCIyjyC.svg +0 -8
  78. package/dist/ui/fonts/atkinson-400.849ae6f0.woff2 +0 -0
  79. package/dist/ui/fonts/atkinson-700.3a9cc18a.woff2 +0 -0
  80. package/dist/ui/fonts/maple-mono-400.071799fd.woff2 +0 -0
  81. package/dist/ui/fonts/maple-mono-700.1e17b237.woff2 +0 -0
@@ -182,6 +182,32 @@ def _plan_files(root: Path) -> list[Path]:
182
182
  return sorted(p for p in plans_dir.glob("*.md") if p.is_file() and not p.is_symlink())
183
183
 
184
184
 
185
+ _PHASE_HEADING = re.compile(r"^(#{2,3})\s+Phase\s+([^\s:—]+)\s*[:—-]?\s*(.*)$", re.M | re.I)
186
+
187
+
188
+ def phase_key(cell: str) -> str:
189
+ s = cell.replace("`", "").replace("*", "").strip()
190
+ s = re.sub(r"^phase\s+", "", s, flags=re.I)
191
+ s = re.split(r" -|[\s:—]", s, maxsplit=1)[0]
192
+ return s.rstrip(".").lower()
193
+
194
+
195
+ def phase_sections(text: str) -> dict[str, dict]:
196
+ out: dict[str, dict] = {}
197
+ for m in _PHASE_HEADING.finditer(text):
198
+ key = phase_key(m.group(2))
199
+ if key in out:
200
+ continue
201
+ title = m.group(3).rstrip(" \t\r\n⏳🔲✅\ufe0f").strip()
202
+ rest = text[m.end():]
203
+ stop = re.search(rf"^#{{1,{len(m.group(1))}}} ", rest, re.M)
204
+ body = (rest[:stop.start()] if stop else rest).strip()
205
+ if len(body) > 2000:
206
+ body = body[:2000] + "…"
207
+ out[key] = {"title": title, "text": body}
208
+ return out
209
+
210
+
185
211
  def _plan_entry(root: Path, path: Path) -> dict:
186
212
  return _plan_entry_text(path.relative_to(Path(root)).as_posix(), path.read_text(encoding="utf-8"))
187
213
 
@@ -205,15 +231,22 @@ def _plan_entry_text(rel: str, text: str) -> dict:
205
231
  if table is not None:
206
232
  columns, lines = table
207
233
  status_at = columns.index("status")
234
+ ms_at = columns.index("milestone") if "milestone" in columns else None
208
235
  for line in lines:
209
236
  if not line.strip().startswith("|") or caddis_tidy._TABLE_RULE_RE.match(line.strip()):
210
237
  continue
211
238
  cells = caddis_tidy._row_cells(line)
212
239
  if cells:
213
240
  cell = cells[status_at] if len(cells) > status_at else ""
214
- tracker.append({"phase": cells[0], "status": cell, "state": status_state(cell)})
241
+ row: dict = {"phase": cells[0], "key": phase_key(cells[0])}
242
+ if ms_at is not None:
243
+ row["milestone"] = cells[ms_at].strip() if len(cells) > ms_at else ""
244
+ row["status"] = cell
245
+ row["state"] = status_state(cell)
246
+ tracker.append(row)
215
247
  return {"path": rel, "title": title,
216
248
  "status": meta.get("status"), "feature": meta.get("feature"),
249
+ "phases": phase_sections(text),
217
250
  "tracker": tracker, "open_rows": sum(1 for row in tracker if not _is_done(row["status"]))}
218
251
 
219
252
 
@@ -263,16 +296,27 @@ def _tree_blobs(tree: bytes, oid_len: int) -> list[tuple[str, str]]:
263
296
  return out
264
297
 
265
298
 
266
- def _origin_plan_texts(root: Path, branch: str) -> list[tuple[str, str]] | None:
267
- """[(path, text)] of the plan files on origin/<branch>: `.caddis/plans/*.md`, else `.github/plans/*.md`, never
268
- `done/`. One git process for the whole read. None when git cannot read the ref."""
299
+ def _origin_plan_texts(root: Path, branch: str) -> tuple[str, int | None, list[tuple[str, str]]] | None:
300
+ """(commit_oid, commit_at, [(path, text)]) of the plan files on origin/<branch>: `.caddis/plans/*.md`, else
301
+ `.github/plans/*.md`, never `done/`. One git process for the whole read. None when git cannot read the ref."""
269
302
  try:
270
303
  batch = _Batch(root)
271
304
  except OSError:
272
305
  return None
273
306
  try:
274
- if batch.get(f"refs/remotes/origin/{branch}") is None:
307
+ commit_obj = batch.get(f"refs/remotes/origin/{branch}")
308
+ if commit_obj is None:
275
309
  return None
310
+ commit_oid = commit_obj[0]
311
+ commit_at: int | None = None
312
+ for line in commit_obj[2].decode("utf-8", errors="replace").splitlines():
313
+ if not line:
314
+ break
315
+ if line.startswith("committer "):
316
+ try:
317
+ commit_at = int(line.split()[-2])
318
+ except (IndexError, ValueError):
319
+ commit_at = None
276
320
  for folder in (".caddis/plans", ".github/plans"):
277
321
  tree = batch.get(f"refs/remotes/origin/{branch}:{folder}")
278
322
  if tree is None or tree[1] != "tree":
@@ -286,14 +330,50 @@ def _origin_plan_texts(root: Path, branch: str) -> list[tuple[str, str]] | None:
286
330
  if blob is None:
287
331
  return None
288
332
  texts.append((f"{folder}/{name}", blob[2].decode("utf-8", errors="replace").replace("\r\n", "\n")))
289
- return texts
290
- return []
333
+ return commit_oid, commit_at, texts
334
+ return commit_oid, commit_at, []
291
335
  except (OSError, ValueError):
292
336
  return None
293
337
  finally:
294
338
  batch.close()
295
339
 
296
340
 
341
+ # How far back the hub looks for a plan's last change. An older plan gets no time and sorts last.
342
+ _CHANGED_SINCE = "400.days"
343
+
344
+
345
+ def _origin_plan_times(root: Path, branch: str, folder: str) -> dict[str, int]:
346
+ """{path: commit time} of the last commit on origin/<branch> that touched each plan file in `folder`.
347
+ One local git process (no network). Empty when git fails: the time is a sort hint, never required."""
348
+ try:
349
+ out = subprocess.run(
350
+ ["git", "-C", str(root), "-c", "core.quotepath=off", "log", f"--since={_CHANGED_SINCE}",
351
+ "--format=%x00%ct", "--name-only", f"refs/remotes/origin/{branch}", "--", folder],
352
+ capture_output=True, timeout=30, creationflags=_NO_WINDOW,
353
+ )
354
+ except (OSError, subprocess.SubprocessError):
355
+ return {}
356
+ if out.returncode != 0:
357
+ return {}
358
+ times: dict[str, int] = {}
359
+ for chunk in out.stdout.decode("utf-8", errors="replace").split("\x00")[1:]:
360
+ lines = chunk.strip().splitlines()
361
+ try:
362
+ when = int(lines[0])
363
+ except (ValueError, IndexError):
364
+ continue
365
+ for name in lines[1:]:
366
+ times.setdefault(name.strip(), when) # git log is newest first: the first time seen is the last change
367
+ return times
368
+
369
+
370
+ def _file_time(path: Path) -> int | None:
371
+ try:
372
+ return int(path.stat().st_mtime)
373
+ except OSError:
374
+ return None
375
+
376
+
297
377
  def _entry_or_error(rel: str, read) -> dict:
298
378
  try:
299
379
  return read()
@@ -309,12 +389,21 @@ def plans_json(root: Path, branch: str | None = None) -> dict:
309
389
  does not parse gives `{"path", "error"}`; the other plans still come back.
310
390
  """
311
391
  root = Path(root)
312
- texts = _origin_plan_texts(root, branch) if branch else None
313
- if texts is not None:
392
+ origin = _origin_plan_texts(root, branch) if branch else None
393
+ if origin is not None:
394
+ commit, commit_at, texts = origin
314
395
  plans = [_entry_or_error(rel, lambda rel=rel, text=text: _plan_entry_text(rel, text)) for rel, text in texts]
315
- return {"schema": 1, "source": f"origin/{branch}", "plans": plans}
316
- plans = [_entry_or_error(path.relative_to(root).as_posix(), lambda path=path: _plan_entry(root, path))
317
- for path in _plan_files(root)]
396
+ times = _origin_plan_times(root, branch, texts[0][0].rsplit("/", 1)[0]) if texts else {}
397
+ for plan in plans:
398
+ if "error" not in plan:
399
+ plan["changed_at"] = times.get(plan["path"])
400
+ return {"schema": 1, "source": f"origin/{branch}", "commit": commit[:12], "commit_at": commit_at, "plans": plans}
401
+ plans = []
402
+ for path in _plan_files(root):
403
+ plan = _entry_or_error(path.relative_to(root).as_posix(), lambda path=path: _plan_entry(root, path))
404
+ if "error" not in plan:
405
+ plan["changed_at"] = _file_time(path)
406
+ plans.append(plan)
318
407
  return {"schema": 1, "source": "working-tree", "plans": plans}
319
408
 
320
409
 
@@ -341,6 +341,29 @@
341
341
  "source": {
342
342
  "type": "string"
343
343
  },
344
+ "commit": {
345
+ "type": "string"
346
+ },
347
+ "fetched_at": {
348
+ "oneOf": [
349
+ {
350
+ "type": "integer"
351
+ },
352
+ {
353
+ "type": "null"
354
+ }
355
+ ]
356
+ },
357
+ "commit_at": {
358
+ "oneOf": [
359
+ {
360
+ "type": "integer"
361
+ },
362
+ {
363
+ "type": "null"
364
+ }
365
+ ]
366
+ },
344
367
  "plans": {
345
368
  "type": "array",
346
369
  "items": {
@@ -408,6 +431,10 @@
408
431
  },
409
432
  "open_rows": {
410
433
  "type": "integer"
434
+ },
435
+ "changed_at": {
436
+ "type": ["integer", "null"],
437
+ "description": "Unix time of the last change: the commit time on origin, or the file time in the working tree. null when unknown."
411
438
  }
412
439
  }
413
440
  },
@@ -588,6 +615,25 @@
588
615
  "type": "string"
589
616
  }
590
617
  }
618
+ },
619
+ {
620
+ "type": "object",
621
+ "required": [
622
+ "path",
623
+ "fingerprint",
624
+ "unchanged"
625
+ ],
626
+ "properties": {
627
+ "path": {
628
+ "type": "string"
629
+ },
630
+ "fingerprint": {
631
+ "type": "string"
632
+ },
633
+ "unchanged": {
634
+ "type": "boolean"
635
+ }
636
+ }
591
637
  }
592
638
  ]
593
639
  }
@@ -14,6 +14,29 @@
14
14
  "source": {
15
15
  "type": "string"
16
16
  },
17
+ "commit": {
18
+ "type": "string"
19
+ },
20
+ "fetched_at": {
21
+ "oneOf": [
22
+ {
23
+ "type": "integer"
24
+ },
25
+ {
26
+ "type": "null"
27
+ }
28
+ ]
29
+ },
30
+ "commit_at": {
31
+ "oneOf": [
32
+ {
33
+ "type": "integer"
34
+ },
35
+ {
36
+ "type": "null"
37
+ }
38
+ ]
39
+ },
17
40
  "plans": {
18
41
  "type": "array",
19
42
  "items": {
@@ -81,6 +104,10 @@
81
104
  },
82
105
  "open_rows": {
83
106
  "type": "integer"
107
+ },
108
+ "changed_at": {
109
+ "type": ["integer", "null"],
110
+ "description": "Unix time of the last change: the commit time on origin, or the file time in the working tree. null when unknown."
84
111
  }
85
112
  }
86
113
  },
@@ -2,7 +2,8 @@
2
2
  """caddis `session_end` hook for agy (Antigravity) — Stop event.
3
3
 
4
4
  Ports claude-harness/hooks/session_end.py to agy's contract. On Stop, appends ONE session-end record to
5
- the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`). Self-contained (the agy bundle does not
5
+ the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`), and marks the session `waiting` in
6
+ its status file `~/.caddis/sessions/<conversationId>.json` (the caddis hub's session list). Self-contained (the agy bundle does not
6
7
  ship claudster_config.py), stdlib-only, and fully defensive:
7
8
  a Stop hook must never fail the turn, and must not print a non-JSON line to stdout (agy parses Stop-hook
8
9
  stdout as a `{"decision":…}` object — a stray string trips its "unsupported hook decision" path). So this
@@ -86,6 +87,28 @@ def _hook_note(feature, exc, root=None):
86
87
  pass
87
88
 
88
89
 
90
+
91
+ def _status_beat(data, status):
92
+ """Write this agy session's status for the caddis hub (~/.caddis/sessions/). Never raises, never prints.
93
+
94
+ caddis_heartbeat.py ships under scripts/ in the agy bundle; in the source repo it is in
95
+ claude-harness/scripts/. Headless runs (review and lane runs) write nothing.
96
+ """
97
+ try:
98
+ if str(os.environ.get("CADDIS_HEADLESS", "")).strip():
99
+ return
100
+ _here = os.path.dirname(os.path.abspath(__file__))
101
+ for _cand in (os.path.join(_here, "scripts"),
102
+ os.path.join(os.path.dirname(_here), "scripts")):
103
+ if os.path.isfile(os.path.join(_cand, "caddis_heartbeat.py")):
104
+ if _cand not in sys.path:
105
+ sys.path.insert(0, _cand)
106
+ break
107
+ import caddis_heartbeat as _hb # noqa: E402
108
+ _hb.agy_beat(data, status, plugin_root=_here) # the bundle's plugin.json sits beside the hook
109
+ except Exception as _exc:
110
+ _hook_note("agy session status", _exc)
111
+
89
112
  def _workspace_roots(data):
90
113
  """Every workspace root in the payload, as a list. Empty when the payload has none.
91
114
 
@@ -119,6 +142,8 @@ def main() -> None:
119
142
  data = {}
120
143
  if _headless():
121
144
  return
145
+ # The turn ended: the session waits for the user. `fullyIdle: false` means agy is not idle yet: it stays working.
146
+ _status_beat(data, "working" if isinstance(data, dict) and data.get("fullyIdle") is False else "waiting")
122
147
  try:
123
148
  roots = _workspace_roots(data) or [os.getcwd()]
124
149
  # A workspace folder may sit inside a repo: the artifact dir is the REPO ROOT's, not the sub-folder's.
@@ -29,11 +29,13 @@ Argument: **$ARGUMENTS**
29
29
  ## Keep this session cheap
30
30
 
31
31
  Measured 24-25 Oct 2026: each background wake-up re-reads the whole conversation.
32
- - Start the coordinator on Sonnet with low effort: `claude --model sonnet --effort low --name coordinator`,
33
- then `/caddis:coordinate start`.
32
+ - Start the coordinator on the model and effort of the session table:
33
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role coordinator` prints `<model> <effort>`
34
+ (today `sonnet low`). Then run `claude --model <model> --effort <effort> --name coordinator`, then
35
+ `/caddis:coordinate start`.
34
36
  - Post a peer message only when the queue or a PR state changes. Send no acknowledgement of an
35
37
  acknowledgement. The watcher already prints a line only on a change, so a quiet cycle wakes nobody.
36
- - Restart (handoff, `/clear`, `/caddis:coordinate`) when this conversation passes about 200k tokens, or once a day. The context_size hook prints a [caddis] warning at 200k and a restart notice at 350k.
38
+ - Restart with the full handoff (`/caddis:handoff`, `/clear`, `/caddis:coordinate`) when this conversation passes about 200k tokens, or once a day. The coordinator never runs the checkpoint: `caddis_handoff.py checkpoint` refuses the coordinator's relay. The context_size hook prints a [caddis] warning at 200k and a stop line at 280k.
37
39
 
38
40
  ## How to call the script
39
41
 
@@ -105,18 +105,32 @@ those phases. Put what the scan actually shows into the plan's `## Risks` table.
105
105
  Before writing the plan, consider dispatching the **preflight** subagent to validate your assumptions
106
106
  (paths, symbols, APIs, primitives) against the codebase — it routinely catches wrong assumptions early.
107
107
 
108
- ### Assign a model tier + effort per phase (don't default everything to the priciest)
109
- Match capability to each phase's difficulty — not one model for the whole plan. Use Claude Code's
110
- evergreen `/model` aliases so this never rots as model names change:
111
- - **cheap** (`/model haiku`) — mechanical, fully-specced, repeat-of-an-existing-pattern phases.
112
- - **mid** (`/model sonnet`) — standard feature work with clear specs. **This is the default.**
113
- - **frontier** (`/model opus`) — novel architecture, tricky algorithms, security-sensitive or
114
- judgment-heavy seams; also recommend a `code-reviewer` pass.
115
- - **ultra** (`/model fable`) — RARE: long-horizon / multi-step / can't-self-verify work (large-codebase
116
- reasoning, scientific). ~2× opus's rate-limit burn — reserve for the few phases that truly need it.
117
- Default to **mid**; reserve frontier/ultra for phases that earn them. Effort is a secondary knob: leave
118
- it at your session default and note **"bump to `high`"** only on a genuinely hard phase. `max` is manual
119
- escalation, never a planned default.
108
+ ### Assign a model and an effort per phase (don't default everything to the priciest)
109
+ Match capability to each phase's difficulty — not one model for the whole plan. Every `**Model:**` line
110
+ names the model AND the effort, in this form:
111
+ `**Model:** <model>, effort <low|medium|high> — <one-line reason tied to this phase's difficulty>`.
112
+ Take the default from the session table. It prints `<model> <effort>`:
113
+ ```
114
+ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role <role>
115
+ ```
116
+ (Source checkout: `claude-harness/scripts/caddis_routing.py`.) Pick the role by the phase:
117
+ - `mechanical-phase` — mechanical, fully specified phases that repeat an existing pattern.
118
+ - `coding-phase` — standard code with a clear spec and literal tests.
119
+ - `critical-phase` — novel architecture, tricky algorithms, security-sensitive or judgment-heavy seams;
120
+ also recommend a `code-reviewer` pass.
121
+ - `measure` — measurement and screenshot work.
122
+ The table also holds the session roles `orchestrator`, `plan-writer` and `coordinator`. Use Claude Code's
123
+ evergreen `/model` aliases (`haiku`, `sonnet`, `opus`) so a line never rots as model names change.
124
+ `/model fable` is RARE: long-horizon work that cannot verify itself, at about 2× opus's rate-limit burn.
125
+ Change the default only with a reason on the line. `max` effort is manual escalation, never a planned
126
+ default. If the command fails, write the model and the effort by hand and say why.
127
+
128
+ **Escalation.** Escalate to Opus through a SMALL subagent (by-reference brief, reply ≤ 10 lines), never `/model opus` mid-session (the prompt cache is per model, so a switch at 200k re-writes the whole cache), when: a card fails again after its one fix card; a measurement fails a rule (isolate the cause first, then give the owner options); a plan amendment changes the design, not only facts; a risk-high phase reaches review. A fresh Opus session only to write a new plan or a redesign.
129
+
130
+ ### Size rule: a phase fits one sitting
131
+ One agy card ≤ 6 files; one phase ≤ 12 files and ≤ 6 cards or tasks. Bigger: split (7a, 7b, each with a
132
+ Tracker row) or mark `**Programme phase:** yes — <why>`. A phase that grows past 6 cards during work is
133
+ split in the Tracker first.
120
134
 
121
135
  ### Assign an execution LANE per phase (which harness runs it — not just which model)
122
136
  A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
@@ -170,7 +184,8 @@ of that role and write its Lane line as follows:
170
184
  Replace `<plan path>` and `N` (also in `lane-pN`) with this plan's path and phase number. The agy line
171
185
  always starts with `caddis_spend.py run`: it books the call against the global EUR spend cap, and
172
186
  `caddis_gate.py lane-check` refuses a bare `agy` Lane line. If the routing command fails
173
- or exits 3, use `claude — this session` and state the reason in that phase.
187
+ or exits 3, use `claude — this session` and state the reason in that phase. When a phase has cards, a
188
+ prompt for one card names it by reference ("then Phase N card B"). Never paste card text into a prompt.
174
189
 
175
190
  #### A phase may take a no-escalation lane only if its exit gate would fail on a spec error
176
191
  `glm-headless` cannot escalate: it does what the phase says. So completeness is only half the test —
@@ -281,8 +296,10 @@ to the phase or task that owns the code. Write "none found" only after you check
281
296
 
282
297
  **Session rules for the orchestrator** (measured 24-25 Oct 2026: long Opus sessions re-read 400-600k tokens
283
298
  on every turn). Keep the context small: subagent replies under about 200 words, full reports in files,
284
- never paste or tail large outputs. At each phase end, write the handoff; continue in the same session only
285
- while the conversation is under about 200k tokens. The context_size hook prints a [caddis] warning at 200k and a restart notice at 350k. Run the phase review as
299
+ never paste or tail large outputs. Context rule: Above 200k: checkpoint at the next card end when 2 or more
300
+ cards are left; else finish the phase and run the full handoff. At 280k: checkpoint at the first moment no
301
+ agent or background command runs. (The checkpoint is the "Checkpoint" section of `/caddis:handoff`; the
302
+ context_size hook prints its exact command.) At each phase end that ends a sitting, write the full handoff. Run the phase review as
286
303
  `/caddis:cross-review --range <base>..HEAD`. Send a task marked mechanical (literal tests, moves, deletes,
287
304
  renames) to agy through `caddis_spend.py run`. Run one `ci-watch` per PR head; on a queued-run timeout watch
288
305
  that run once with `--run <id>`; write no "still waiting" turns.
@@ -291,11 +308,13 @@ that run once with `--run <id>`; write no "still waiting" turns.
291
308
  > ⚠️ **Switch model/lane BEFORE starting this phase** — the *active* model does the work, not the
292
309
  > one named here. Lane `claude`: run `/model <alias>`. Lane `glm-headless`: run the exact command below.
293
310
  **Milestone:** M1 *(omit on plans without milestones)*
294
- **Model:** <tier> (`/model <alias>`) — <one-line rationale tied to this phase's difficulty>. Orchestrator: Sonnet to run the plan (Opus only to write plans and designs).
311
+ **Model:** <model>, effort <low|medium|high> — <one-line rationale tied to this phase's difficulty> *(default: `caddis_routing.py session --role <role>`; the orchestrator runs on the `orchestrator` row, plans and designs on the `plan-writer` row)*
295
312
  **Lane:** claude — this session | glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
296
313
  **Type:** backend | hard | ui | tests | docs *(required when the Lane runs through caddis_lanes.py)*
297
314
  **Execution:** inline | per-task *(the rule in Step 2; per-task phases list their tasks below)*
298
315
  **Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
316
+ **Programme phase:** yes — <why> *(omit unless the phase breaks the size rule: one agy card ≤ 6 files; one phase ≤ 12 files and ≤ 6 cards or tasks)*
317
+ **Depends on:** Phase <x> *(optional: write it only when this phase does NOT need the phase before it; name the phase it does need, or "nothing". It is not a wave marker: the executor picks waves at run time, `/caddis:implement` "Waves")*
299
318
  **Risk:** high — token-verification seam; a wrong answer here is a silent auth bypass *(omit this line when normal)*
300
319
  **Goal:** <one sentence>
301
320
  **Touches:** `<files>`
@@ -340,12 +359,13 @@ Three rules: one attempt, one review.
340
359
  review between tasks. One cross-review, by one other vendor, runs at the end of the phase.
341
360
  - **Session boundaries:** the executor WRITES the handoff (durable `relay.md` + Tracker) after any
342
361
  phase that ends a sitting — it performs the work, it does not suggest the command. Start a FRESH
343
- session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or whenever
344
- context feels heavy. Resume with exactly: `read <this plan's path> and implement the next ⏳ phase`.
362
+ session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or when the
363
+ context rule says so (Session rules above: checkpoint above 200k at a card end, the full handoff at a
364
+ phase end). Resume with exactly: `read <this plan's path> and implement the next ⏳ phase`.
345
365
  - **Run to a boundary, not to a phase.** The executor implements phase after phase, committing each,
346
366
  and stops only at a marked boundary. Do not plan a stop after every phase — that is the friction
347
367
  this structure exists to remove.
348
- - **The four halts, and nothing else:**
368
+ - **The five halts, and nothing else:**
349
369
  1. **A milestone boundary** — its `Gate:` passed and it is ready to ship.
350
370
  2. **A phase marked `Session: fresh`** — context is heavy or the work changes shape.
351
371
  3. **After a `risk: high` phase** — *after*, never before. The phase is executed and committed
@@ -358,6 +378,9 @@ Three rules: one attempt, one review.
358
378
  on it. A headless marker (`CADDIS_HEADLESS=1`) alone does not lift the halt.
359
379
  4. **A failed or blocked phase** — tests red, exit gate unmet, or the plan turned out wrong. Stop;
360
380
  do not build on it.
381
+ 5. **The checkpoint after the 200k warning** — at a card end, when 2 or more cards are left in the
382
+ phase (`/caddis:handoff`, "Checkpoint"). Interactive sessions only: a headless session never
383
+ checkpoints; at 280k it ends `BLOCKED context <n>`.
361
384
  - **A lane change is NOT a halt.** `/caddis:implement` spawns the assigned lane itself and verifies
362
385
  the result. It used to need a human only because the routing was inert.
363
386
  - **At every halt, leave both:** the executor PERFORMS the handoff (writes `relay.md`, updates the
@@ -399,6 +422,11 @@ Status words (one vocabulary, `scripts/caddis_status.py`): done is `done`, `merg
399
422
  `in progress`, `blocked` and `moved` name the other states; anything else (`not started`, `☐`) is to do. A cell
400
423
  that says `pending` is never done.
401
424
 
425
+ ## Per-symbol grep preflight (before the plan is committed)
426
+ Check every name a card gives: each symbol, file, line number and CSS variable. Use one grep per name
427
+ (Grep, or `git grep -n`) before you commit the plan. Fix the card when a name or a line number differs.
428
+ The orchestrator re-checks a card's names the same way, one grep per name, before it sends the card.
429
+
402
430
  ## Plan quality gate — local-coder ready (MANDATORY)
403
431
  The plan must be executable by a **low-capability local coder model** (the planner→coder handoff: a
404
432
  strong model plans, a cheaper/local model implements). The plan carries the intelligence; the coder
@@ -34,7 +34,7 @@ mode.
34
34
  ## Step 2 — check this session's name before loading anything
35
35
 
36
36
  Run `ListAgents`. Its header line says `This session is <name>`; that is your name. The sheet row's
37
- Start line already names the session: `claude --name <expected> "/caddis:fleet-open <role>"`, where
37
+ Start line already names the session: `cd "<folder>"; claude --model <model> --effort <effort> --name <expected> "/caddis:fleet-open <role>"`, where
38
38
  `<expected>` is `new_name` of the role at the sheet's hour.
39
39
 
40
40
  - `<name>` equals `<expected>` → go on.
@@ -73,6 +73,70 @@ Step 8 prints all 12 in this order. Never drop a row from the report, even when
73
73
  `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
74
74
  shared checkout the report also lists every tracked file Step 1 changed, under `Docs PR needed:`.
75
75
 
76
+ ## Checkpoint (mid-phase, between cards)
77
+ The handoff has two tiers. The **full** tier is this whole command. The **checkpoint** tier is a cheap
78
+ mid-phase handoff: two script calls, about 3 model calls. It writes the relay and the tasks file and prints
79
+ the RESUME block. The next full handoff does the rest.
80
+
81
+ **When to checkpoint.** At a card end (or a task end), when one of these is true:
82
+ - The context_size hook printed the 200k warning, and 2 or more cards are left in the phase. When 1 card
83
+ or less is left, finish the phase and run the full handoff instead.
84
+ - The hook printed the 280k stop line. Start no new card. Checkpoint at the first moment no agent or
85
+ background command runs.
86
+ - You stop for more than 1 hour and the conversation is over 100k tokens.
87
+
88
+ **In a wave** (`/caddis:implement`, "Waves"), the card end is the safe point (rule 4): no child runs, and
89
+ each finished child is recorded. Checkpoint only there, and never `/clear` while a child runs. The relay
90
+ lists each wave member's phase, worktree, branch, last commit and next card.
91
+
92
+ **When not to checkpoint.** Run the full handoff, or do what the refusal says:
93
+ - A headless session (`CADDIS_HEADLESS` set). The script refuses (exit 1):
94
+ `CHECKPOINT: refused headless: return BLOCKED with your state`. An Agent-tool subagent also never runs
95
+ it; it returns `BLOCKED: <cards done, commits, next card>`.
96
+ - The coordinator's relay. The script refuses (exit 1): `CHECKPOINT: coordinator: run /caddis:handoff`.
97
+ It also refuses when it cannot run the coordinator check:
98
+ `CHECKPOINT: cannot tell if <name> is the coordinator relay (<why>): run /caddis:handoff`.
99
+ - A fleet close (`FLEET CLOSE from <coordinator>`). Always run the full handoff with `--fleet` (Step 9).
100
+ - An agent or a background command still runs. Finish without `--idle` refuses (exit 1):
101
+ `CHECKPOINT: wait until no agent or background command runs`.
102
+
103
+ **The two commands.**
104
+ 1. **Prepare.** It reads the relay hash before you compose the new relay:
105
+ ```
106
+ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" checkpoint --session-id <session-id> --plan <plan> --phase <N>
107
+ ```
108
+ (Source checkout: `scripts/caddis_handoff.py`. Add `--name <name>` when you know the workstream.) It
109
+ prints `workstream:`, `relay:`, `hash:`, `shared:`, `tasks:`, `budget: 4000` and `next:`.
110
+ 2. **Finish.** Write the new relay to a temp file with the Write tool (never a heredoc). Then run the
111
+ `next:` command as printed. Replace `<tmp>` with the temp file path. Set `--kt` to `done` or
112
+ `skipped:<reason>`. Keep `--idle` only when no agent or background command runs.
113
+
114
+ **What you write.** Only three things; the script does the rest:
115
+ - **The relay text.** Use the Step 3 format. It holds the current state only, and the Done-pruning rules
116
+ (Rules) apply. `## Next step` names the next card exactly. Keep it under 4,000 characters.
117
+ - **The Tracker Edit.** Set the phase's Tracker row to `in progress` and name the last card done. Finish
118
+ fails row 2 when the row does not say `in progress`. Do not commit the plan file: finish prints
119
+ `plan file modified, not committed`, and a "no stray files" card check exempts the plan path. In a
120
+ shared checkout (Step 0), make no Tracker edit: finish prints row 2 as
121
+ `skipped: shared checkout (card state is in the relay)`, so the checkpoint changes no tracked file.
122
+ - **The knowledge-transfer decision.** When a root cause, a workaround or a rejected approach is new since
123
+ the last handoff, dispatch the `knowledge-transfer` subagent (Step 1) first, then pass `--kt done`.
124
+ Else pass `--kt skipped:<reason>`.
125
+
126
+ **What finish prints.** `=== CHECKPOINT CHECKLIST ===` with the same 12 rows as Step 8, in the same order.
127
+ Rows 5, 6, 8, 9, 10 and 12 print `skipped: checkpoint tier`. Then it prints the RESUME block (Step 9) as its
128
+ last output. Print that block as it is, with nothing after it, then ask the owner for `/clear`.
129
+
130
+ **When finish fails** (exit 1):
131
+ - `CHECKPOINT: row 3 relay failed`: the relay is NOT written. A peer changed the relay after prepare: the
132
+ script prints the diff and writes nothing. Run prepare again for the new hash, merge by hand, and finish
133
+ again. Never force it.
134
+ - `CHECKPOINT: handover-check failed`: the relay is written, but it names a missing path or is over 4,000
135
+ characters. There is no RESUME block. Fix the relay, then run prepare and finish again.
136
+ - `ERROR after relay write: <reason>`: the relay is written (`relay written:` names it), but a later step
137
+ failed. Finish prints the RESUME block when it can. When there is none, resume from the relay path; do not
138
+ write the block by hand.
139
+
76
140
  ## Step 1 — capture learnings FIRST (knowledge-transfer)
77
141
  **Before** gathering git signals or writing relay.md, decide on `knowledge-transfer` — and the default
78
142
  is to run it.
@@ -435,13 +499,15 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_fleet.py" resume-block --name <name
435
499
  the session name (`session-state/<session-id>.name` when `whoami` wrote it, else the first 8 characters of
436
500
  the id). It prints, and you print its output as it is, with nothing after it:
437
501
  ```
502
+ Model for next session: <model>, effort <effort>
438
503
  === RESUME ===
439
504
  Session: <session name> (<session id>)
440
505
  Workstream: <name>
441
506
  <the resume prompt, in a fenced block>
442
507
  Start line:
443
- claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
508
+ claude --model <model> --effort <effort> --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
444
509
  ```
510
+ `<model>` and `<effort>` come from `caddis_routing.py session` (Rules, "Model for the next session").
445
511
  - **The announce sentence.** In a normal handoff the one-line start line also ends with a sentence that tells
446
512
  the new session to run `caddis_fleet.py whoami` with its new name, then `caddis_fleet.py peers`, and to send
447
513
  each named live peer in the same repo (the checkout and its worktrees) one `SendMessage`:
@@ -458,11 +524,16 @@ claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce
458
524
  `--role <role>` to set another.
459
525
 
460
526
  ## Rules
461
- - **Clear above 200k tokens.** A session whose conversation passes about 200k tokens writes this handoff at
462
- the next safe point and asks the owner for `/clear`. Each turn re-reads the whole conversation, so a long
463
- session costs more with every turn. The context_size hook prints a [caddis] warning at 200k and a restart notice at 350k.
464
- - **Model for the next session.** Print one line `Model for next session: ...` just before the RESUME block (the block stays the last output): Sonnet (effort medium) to run an approved
465
- plan; Opus to write a plan or design. Start line: `claude --model sonnet --effort medium --name <role>-<MMDD>-<HH>`.
527
+ - **Context rule.** Above 200k: checkpoint at the next card end when 2 or more cards are left; else finish
528
+ the phase and run the full handoff. At 280k: checkpoint at the first moment no agent or background command
529
+ runs. Then ask the owner for `/clear`. Each turn re-reads the whole conversation, so a long session costs
530
+ more with every turn. The context_size hook prints the exact command at 200k and at 280k ("Checkpoint" above).
531
+ - **Model for the next session.** Take the model and effort from the session table:
532
+ `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role <role>` prints `<model> <effort>`.
533
+ The role is `orchestrator` to run an approved plan and `plan-writer` to write a plan or design.
534
+ `resume-block` (Step 9) reads the same table: it prints `Model for next session: <model>, effort <effort>`
535
+ as its first line and puts `--model <model> --effort <effort>` in the Start line. Pass `--role plan-writer`
536
+ for plan or design work. Do not print a second model line.
466
537
  - **One next action, by priority ladder.** `## Next step` names exactly ONE action — not a menu. Pick it in
467
538
  order: (1) interrupted mid-phase work → finish + commit it; else (2) the active plan's next not-started
468
539
  phase; else (3) the top open question/decision. Everything else is context, not the next step.