@caddis/cli 0.4.96 → 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.
- package/README.md +2 -0
- package/bundles/antigravity-plugin/plugin.json +1 -1
- package/bundles/antigravity-plugin/repo_hygiene.py +134 -20
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/caddis_fleet.py +31 -21
- package/bundles/antigravity-plugin/scripts/caddis_gate.py +18 -1
- package/bundles/antigravity-plugin/scripts/caddis_guide.json +2 -2
- package/bundles/antigravity-plugin/scripts/caddis_handoff.py +235 -0
- package/bundles/antigravity-plugin/scripts/caddis_hub_collect.py +67 -15
- package/bundles/antigravity-plugin/scripts/caddis_lanes.py +154 -130
- package/bundles/antigravity-plugin/scripts/caddis_review.py +12 -0
- package/bundles/antigravity-plugin/scripts/caddis_tidy.py +152 -51
- package/bundles/antigravity-plugin/scripts/caddis_todo.py +314 -18
- package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +117 -1
- package/bundles/antigravity-plugin/scripts/schemas/hub-plans.schema.json +117 -1
- package/bundles/antigravity-plugin/scripts/setup_project_ai.py +60 -2
- package/bundles/antigravity-plugin/scripts/templates/coordinator.md +3 -3
- package/bundles/antigravity-plugin/skills/coordinate/SKILL.md +4 -1
- package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +6 -0
- package/bundles/antigravity-plugin/skills/handoff/SKILL.md +101 -23
- package/bundles/antigravity-plugin/skills/implement/SKILL.md +6 -0
- package/bundles/antigravity-plugin/skills/park/SKILL.md +7 -2
- package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -0
- package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -0
- package/bundles/manifest.json +2 -2
- package/dist/cli.js +276 -76
- package/dist/export/assets/export-B3cUoxL1.js +150 -0
- package/dist/export/assets/export-DQss44R1.css +1 -0
- package/dist/export/index.html +2 -2
- package/dist/ui/assets/Activity-CvEIJlnE.js +6 -0
- package/dist/ui/assets/{Guide-Czn5sK0f.js → Guide-BxS9L55s.js} +1 -1
- package/dist/ui/assets/Guide-DTd261-c.css +1 -0
- package/dist/ui/assets/RoadmapTab-CqlWs7dJ.js +31 -0
- package/dist/ui/assets/index-9pdDzLVp.css +1 -0
- package/dist/ui/assets/index-DSxeWPax.js +231 -0
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/export/assets/export-CMtV-slT.css +0 -1
- package/dist/export/assets/export-DtlDFN4L.js +0 -150
- package/dist/ui/assets/Activity-BDjet2xd.js +0 -6
- package/dist/ui/assets/Guide-D-Zy4cUT.css +0 -1
- package/dist/ui/assets/RoadmapTab-Bd8geyQx.js +0 -31
- package/dist/ui/assets/index-Bd0Z4jR8.css +0 -1
- package/dist/ui/assets/index-CmngQ8Mk.js +0 -231
- package/dist/ui/assets/time-D00tu2ZP.js +0 -1
|
@@ -37,6 +37,87 @@
|
|
|
37
37
|
}
|
|
38
38
|
]
|
|
39
39
|
},
|
|
40
|
+
"overlay": {
|
|
41
|
+
"type": "object",
|
|
42
|
+
"required": [
|
|
43
|
+
"state",
|
|
44
|
+
"reason",
|
|
45
|
+
"count"
|
|
46
|
+
],
|
|
47
|
+
"properties": {
|
|
48
|
+
"state": {
|
|
49
|
+
"enum": [
|
|
50
|
+
"on",
|
|
51
|
+
"off"
|
|
52
|
+
]
|
|
53
|
+
},
|
|
54
|
+
"reason": {
|
|
55
|
+
"type": [
|
|
56
|
+
"string",
|
|
57
|
+
"null"
|
|
58
|
+
]
|
|
59
|
+
},
|
|
60
|
+
"count": {
|
|
61
|
+
"type": "integer"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
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
|
+
},
|
|
40
121
|
"plans": {
|
|
41
122
|
"type": "array",
|
|
42
123
|
"items": {
|
|
@@ -98,6 +179,12 @@
|
|
|
98
179
|
"done",
|
|
99
180
|
"moved"
|
|
100
181
|
]
|
|
182
|
+
},
|
|
183
|
+
"source": {
|
|
184
|
+
"enum": [
|
|
185
|
+
"main",
|
|
186
|
+
"branch"
|
|
187
|
+
]
|
|
101
188
|
}
|
|
102
189
|
}
|
|
103
190
|
}
|
|
@@ -106,8 +193,37 @@
|
|
|
106
193
|
"type": "integer"
|
|
107
194
|
},
|
|
108
195
|
"changed_at": {
|
|
109
|
-
"type": [
|
|
196
|
+
"type": [
|
|
197
|
+
"integer",
|
|
198
|
+
"null"
|
|
199
|
+
],
|
|
110
200
|
"description": "Unix time of the last change: the commit time on origin, or the file time in the working tree. null when unknown."
|
|
201
|
+
},
|
|
202
|
+
"overlay": {
|
|
203
|
+
"type": "object",
|
|
204
|
+
"required": [
|
|
205
|
+
"pr",
|
|
206
|
+
"draft",
|
|
207
|
+
"head_ref",
|
|
208
|
+
"also"
|
|
209
|
+
],
|
|
210
|
+
"properties": {
|
|
211
|
+
"pr": {
|
|
212
|
+
"type": "integer"
|
|
213
|
+
},
|
|
214
|
+
"draft": {
|
|
215
|
+
"type": "boolean"
|
|
216
|
+
},
|
|
217
|
+
"head_ref": {
|
|
218
|
+
"type": "string"
|
|
219
|
+
},
|
|
220
|
+
"also": {
|
|
221
|
+
"type": "array",
|
|
222
|
+
"items": {
|
|
223
|
+
"type": "integer"
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
}
|
|
111
227
|
}
|
|
112
228
|
}
|
|
113
229
|
},
|
|
@@ -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
|
|
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` -
|
|
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}")
|
|
@@ -38,7 +38,7 @@ What the keys mean:
|
|
|
38
38
|
| `deploy.never_health_path` | A path that looks healthy even when the API is dead. Never used as a health check. |
|
|
39
39
|
| `deploy.render_check` | How the PR's session checks a served page: 0 console errors and one value checked against its source. |
|
|
40
40
|
| `deploy.wait` | How to wait for the deploy run. No fixed sleep. |
|
|
41
|
-
| `owner_reserved` | Changes that only the owner may approve. |
|
|
41
|
+
| `owner_reserved` | Changes that only the owner may approve. The coordinator reads each class through the critical checklist (coordinator design, section 6): for example `permission change` means an EXISTING permission changes; a new permission is routine. A class that the checklist does not name is a rule reserved by name and always goes to the owner. |
|
|
42
42
|
| `stall.busy_silent_min` | Minutes a busy session may stay silent before the coordinator asks. |
|
|
43
43
|
| `stall.ready_no_ready_msg_min` | Minutes a green PR may wait for its session's ready message. |
|
|
44
44
|
| `quiet.coordination` | Quiet hours for merges (`none`: no quiet hours). |
|
|
@@ -80,8 +80,8 @@ What the keys mean:
|
|
|
80
80
|
"wait": "gh run watch"
|
|
81
81
|
},
|
|
82
82
|
"owner_reserved": [
|
|
83
|
-
"schema change or data write on prod",
|
|
84
|
-
"permission change",
|
|
83
|
+
"schema change or data write on prod (checklist items 1 and 2)",
|
|
84
|
+
"permission change (checklist item 3: an existing permission)",
|
|
85
85
|
"any open blocking review finding",
|
|
86
86
|
"<fill: a rule the owner reserved by name; one string per rule, or delete this line>"
|
|
87
87
|
],
|
|
@@ -352,7 +352,10 @@ Stalls (design 7.4): one nudge for a busy, silent session that holds a queue ite
|
|
|
352
352
|
python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --what '<gate>' --decision approve --by coordinator --window <N> --reason '<why it passes>' --json
|
|
353
353
|
```
|
|
354
354
|
2. The owner-only list (design 6, plus config `owner_reserved`) goes to the owner. Never approve it
|
|
355
|
-
yourself.
|
|
355
|
+
yourself. Decide with the design 6 critical checklist, and read each config `owner_reserved` class
|
|
356
|
+
through it (for example "permission change" is item 3: an EXISTING permission changes; a new one is
|
|
357
|
+
routine). When the diff shows clearly that every item is false, the change is routine: do step 1 with
|
|
358
|
+
the checklist item in `--reason`. When you cannot tell from the diff, ask the owner. Send it with:
|
|
356
359
|
```
|
|
357
360
|
recommendation: approve | hold
|
|
358
361
|
reason: <one or two sentences>
|
|
@@ -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:
|
|
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
|
-
`
|
|
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
|
|
|
@@ -132,7 +134,8 @@ lists each wave member's phase, worktree, branch, last commit and next card.
|
|
|
132
134
|
|
|
133
135
|
**What finish prints.** `=== CHECKPOINT CHECKLIST ===` with the same 12 rows as Step 8, in the same order.
|
|
134
136
|
Rows 5, 6, 8, 9, 10 and 12 print `skipped: checkpoint tier`. Then it prints the RESUME block (Step 9) as its
|
|
135
|
-
last output. Print that block as it is, with
|
|
137
|
+
last output. Print that block as it is, with both labelled copy blocks and their labels unchanged and nothing
|
|
138
|
+
after it, then ask the owner for `/clear`.
|
|
136
139
|
|
|
137
140
|
**When finish fails** (exit 1):
|
|
138
141
|
- `CHECKPOINT: row 3 relay failed`: the relay is NOT written. A peer changed the relay after prepare: the
|
|
@@ -331,18 +334,80 @@ tasks file exists and is not named. If you wrote the relay before running this,
|
|
|
331
334
|
Step 3, point 5.
|
|
332
335
|
|
|
333
336
|
## Step 4 — tidy finished artifacts
|
|
334
|
-
Flip
|
|
335
|
-
finished it — that is your judgment call
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
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**
|
|
344
405
|
(`done/<name>` already exists) is reported by the script, not fatal — surface it, do not fail the
|
|
345
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.
|
|
346
411
|
|
|
347
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:
|
|
348
413
|
```
|
|
@@ -409,7 +474,7 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_budget.py" check --root . --report
|
|
|
409
474
|
`caddis_budget.py` lists each handoff-grown file over its size budget (`OVER <path>: ...; fix: <rule>`); the
|
|
410
475
|
`fix:` text is the one-line fix for that row.
|
|
411
476
|
List each violation they print with a one-line command that fixes it (for example `/caddis:kb` for an
|
|
412
|
-
un-indexed note, or `caddis_tidy.py --apply
|
|
477
|
+
un-indexed note, or `caddis_tidy.py --apply --only <path>` for a finished artifact in the wrong folder). A violation is
|
|
413
478
|
not a failure of the handoff: the row is `done` when all three ran. If a script is missing, the row is
|
|
414
479
|
`skipped: <script> not installed`.
|
|
415
480
|
|
|
@@ -511,27 +576,39 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_fleet.py" resume-block --name <name
|
|
|
511
576
|
`<name>` is the workstream name from Step 3. It reads the relay's `## Resume prompt` block verbatim, and
|
|
512
577
|
the session name (`session-state/<session-id>.name` when `whoami` wrote it, else the first 8 characters of
|
|
513
578
|
the id). It prints, and you print its output as it is, with nothing after it:
|
|
514
|
-
|
|
579
|
+
````
|
|
515
580
|
Model for next session: <model>, effort <effort>
|
|
516
581
|
=== RESUME ===
|
|
517
582
|
Session: <session name> (<session id>)
|
|
518
583
|
Workstream: <name>
|
|
519
584
|
Repo: <absolute repo root>
|
|
520
|
-
|
|
521
|
-
|
|
585
|
+
After /clear in this window, paste this:
|
|
586
|
+
```text
|
|
587
|
+
<the resume prompt on one line> <the announce sentence>
|
|
588
|
+
```
|
|
589
|
+
In a new terminal, paste this:
|
|
590
|
+
```bash
|
|
522
591
|
cd "<absolute repo root>"; claude --model <model> --effort <effort> --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
|
|
523
592
|
```
|
|
593
|
+
````
|
|
594
|
+
Print BOTH fenced blocks, each under its label line, with the label text unchanged. Never merge them, reorder
|
|
595
|
+
them, drop one, or add colour. The owner picks by what they do next:
|
|
596
|
+
- **Same window, after `/clear`:** paste only the first block (the prompt). The window already has the folder, the
|
|
597
|
+
model and the name.
|
|
598
|
+
- **New terminal:** paste the second block (the whole line). It changes to the repo, starts claude with the
|
|
599
|
+
model, effort and name, and passes the same prompt.
|
|
524
600
|
`<model>` and `<effort>` come from `caddis_routing.py session` (Rules, "Model for the next session").
|
|
525
601
|
The `cd` makes the relay's repo-relative paths work from any terminal folder (`;`, not `&&`: Windows PowerShell 5.1 has no `&&`).
|
|
526
602
|
- **The announce sentence.** In a normal handoff the one-line start line also ends with a sentence that tells
|
|
527
603
|
the new session to run `caddis_fleet.py whoami` with its new name, then `caddis_fleet.py peers`, and to send
|
|
528
604
|
each named live peer in the same repo (the checkout and its worktrees) one `SendMessage`:
|
|
529
|
-
`<name> started in <folder>: <next action>. No reply needed.`
|
|
530
|
-
session
|
|
605
|
+
`<name> started in <folder>: <next action>. No reply needed.` Both copy blocks end with this sentence, so a
|
|
606
|
+
session started from either one announces itself. The sentence names the stable launcher
|
|
531
607
|
(`~/.caddis/bin/caddis_run.py`), because a new session cannot expand `${CLAUDE_PLUGIN_ROOT}` and a versioned
|
|
532
608
|
plugin path is gone after the next update.
|
|
533
609
|
- **Fleet close.** When this handoff runs because a peer sent `FLEET CLOSE from <coordinator>`, add
|
|
534
|
-
`--fleet`. The
|
|
610
|
+
`--fleet`. The block then holds the relay's prompt in one fenced block and ends with
|
|
611
|
+
`Start line: from the restart sheet`, with no copy blocks: the restart sheet is the only
|
|
535
612
|
start line in a fleet close, and `/caddis:fleet-open` already greets the peers, so it has no announce
|
|
536
613
|
sentence. The `FLEET-ACK` reply is a separate message and does not change.
|
|
537
614
|
- **Exit 1** (no `## Resume prompt` block, or no relay) prints nothing on stdout. The handoff is not
|
|
@@ -553,7 +630,7 @@ The `cd` makes the relay's repo-relative paths work from any terminal folder (`;
|
|
|
553
630
|
`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role <role>` prints `<model> <effort>`.
|
|
554
631
|
The role is `orchestrator` to run an approved plan and `plan-writer` to write a plan or design.
|
|
555
632
|
`resume-block` (Step 9) reads the same table: it prints `Model for next session: <model>, effort <effort>`
|
|
556
|
-
as its first line and puts `--model <model> --effort <effort>` in the
|
|
633
|
+
as its first line and puts `--model <model> --effort <effort>` in the full line (the second copy block). Pass `--role plan-writer`
|
|
557
634
|
for plan or design work. Do not print a second model line.
|
|
558
635
|
- **One next action, by priority ladder.** `## Next step` names exactly ONE action — not a menu. Pick it in
|
|
559
636
|
order: (1) interrupted mid-phase work → finish + commit it; else (2) the active plan's next not-started
|
|
@@ -561,7 +638,8 @@ The `cd` makes the relay's repo-relative paths work from any terminal folder (`;
|
|
|
561
638
|
- Only verified facts and real paths. Mark anything unconfirmed as `Unknown`.
|
|
562
639
|
- Update the plan's tracker rows too (status + last commit) — relay and tracker must agree. In a shared
|
|
563
640
|
checkout, edit the Tracker in the Step 0 worktree, never in this checkout.
|
|
564
|
-
- Don't commit unless asked
|
|
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.
|
|
565
643
|
- **Prune the Done section — two rules, both apply:**
|
|
566
644
|
1. **Merge-based:** Phases already merged to `main` (confirmed by a tag or commit) must be compressed
|
|
567
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.
|
|
155
|
-
|
|
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>`).
|
|
@@ -97,6 +97,7 @@ hands back here.
|
|
|
97
97
|
Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-tier --range <base>...HEAD` and review by its tier (rule 3).
|
|
98
98
|
`<base>` is `origin/<default branch>` (on the default branch itself, the commit before this change). Tier 0 or 1-small: no model review. Tier 1: one `/caddis:cross-review`. Tier 2: one `/caddis:cross-review` by one other vendor (two only when the owner asks). No `TIER:` line means tier 2.
|
|
99
99
|
<!-- /shared:cross-review-trigger -->
|
|
100
|
+
When `review-tier` prints `AREA: security-analyst`, also dispatch `security-analyst` on the diff. `ui-design-reviewer` never runs per PR.
|
|
100
101
|
|
|
101
102
|
## Step 4 — Rebase-safe currency
|
|
102
103
|
|
|
@@ -126,6 +126,7 @@ source checkout; skip this step if the script is missing or the repo has no `.ca
|
|
|
126
126
|
Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-tier --range <base>...HEAD` and review by its tier (rule 3).
|
|
127
127
|
`<base>` is `origin/<default branch>` (on the default branch itself, the commit before this change). Tier 0 or 1-small: no model review. Tier 1: one `/caddis:cross-review`. Tier 2: one `/caddis:cross-review` by one other vendor (two only when the owner asks). No `TIER:` line means tier 2.
|
|
128
128
|
<!-- /shared:cross-review-trigger -->
|
|
129
|
+
When `review-tier` prints `AREA: security-analyst`, also dispatch `security-analyst` on the diff. `ui-design-reviewer` never runs per PR.
|
|
129
130
|
|
|
130
131
|
> **Why this is mechanical and not "consider a review here".** a fleet app shipped four
|
|
131
132
|
> production releases in one day — sixteen fixes across SQL, caches, refresh jobs and React — and
|