@caddis/cli 0.4.51 → 0.4.53

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -13,9 +13,8 @@ The plan file is the **durable spine of the harness** — it must let any future
 agent, on any tool) resume with zero re-discovery. Optimize for that.
 
 ## Headless mode
-When the invocation contains the marker **`HEADLESS RUN RULES`**, **or `CADDIS_HEADLESS` /
-`DOCKET_PLAN` / `DOCKET_BRANCH` is set in the environment** (the caddis OSS launchers export
-`CADDIS_HEADLESS` on claude's `-p`/`--print`; the docket runner sets the others) — a non-interactive
+When the invocation contains the marker **`HEADLESS RUN RULES`**, **or `CADDIS_HEADLESS` is set in
+the environment** (the caddis OSS launchers export it on claude's `-p`/`--print`) — a non-interactive
 caller spawned this session and no human is present, so the scope-check questions and any interview are
 **suspended and forbidden**. This mode exists for one-line ideas: the card may be a short title with **no
 description**, and there may be **no codebase, PROJECT-FACTS, or prior PRD** to read. That is expected —
@@ -39,13 +38,6 @@ Absolute rules in this mode (they override everything below):
   a bullet under `## Constraints & decisions` — never a question to the user.
 - **Honor the caller's output path and slug** (falling back to `.caddis/plans/<feature-slug>.md`);
   set `feature: <slug>` in the frontmatter to that slug.
-- **Also emit a visual companion** — a self-contained, scannable HTML page at `<artifact_dir>/<slug>.html`
-  presenting the plan visually (a goal card, phases as cards with their steps, an affected-files table,
-  and a risks/decisions section). **Use inline `<style>` ONLY** — the visual is rendered in a *sandboxed*
-  iframe with no script execution, so a `<script>`/CDN (e.g. the Tailwind browser CDN) would NOT run and
-  the page would appear unstyled. Keep it fully portable — no external `<script>`/`<link>`, no local
-  asset files, no `/`-rooted paths. This is the visual the human reviews in docket alongside the markdown.
-  Write it after the `.md`; the runner finds it by the matching `<slug>.html` name.
 - **Always write the plan file, then end with exactly one fenced `json` highlights block** — nothing
   after it:
   ```json
@@ -63,7 +55,7 @@ exists instead of assumed. If the work fits comfortably in one session, say so a
 instead of planning. Only produce a plan for genuinely multi-phase work.
 
 ### Evidence gate — do not write plan content while a BLOCKER is unresolved
-Absorbed from `golden-plan`, whose strongest idea this is, and the direct counter to the failure
+This is the direct counter to the failure
 mode that makes a plan dangerous: **you write the spec, so you cannot see its gaps.** A phase built
 on guessed field names or an imagined API is confidently wrong, passes every completeness check,
 and only fails at the exit gate — or worse, doesn't.
@@ -164,9 +156,11 @@ of that role and write its Lane line as follows:
 - `sonnet`: `claude — /model sonnet`
 - `claude`: `claude — this session`
 - `codex`: codex — `codex exec --ephemeral --sandbox workspace-write "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
-- `agy`: agy — `agy --mode accept-edits --dangerously-skip-permissions --add-dir . --print-timeout 20m --output-format text -p "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
+- `agy`: agy — `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spend.py" run --caller lane-pN -- agy --mode accept-edits --dangerously-skip-permissions --add-dir . --print-timeout 20m --output-format json -p "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
 
-Replace `<plan path>` and `N` with this plan's path and phase number. If the routing command fails
+Replace `<plan path>` and `N` (also in `lane-pN`) with this plan's path and phase number. The agy line
+always starts with `caddis_spend.py run`: it books the call against the global EUR spend cap, and
+`caddis_gate.py lane-check` refuses a bare `agy` Lane line. If the routing command fails
 or exits 3, use `claude — this session` and state the reason in that phase.
 
 #### A phase may take a no-escalation lane only if its exit gate would fail on a spec error
@@ -186,14 +180,9 @@ internal repo path into stakeholder-facing copy, and set a `live` status flag th
 framework's own "Soon" badge). `tsc` clean, 632/632 tests green, cross-review CLEAN, exit gate
 satisfied. A headless run following it literally would have committed both, entirely green.
 
-In an Advisory-Hub plan, treat your lane as **provisional**: the Hub writes each `phase-NN.prompt.md`
-before the phase runs, and that is the first time anyone but the spec's author reads it. Let that
-read confirm or downgrade the lane. It costs nothing — the prompt is being written anyway.
-
 ### Group phases into MILESTONES — only when the plan is big enough
 **Add milestones when the plan has ~8+ phases OR spans multiple sessions.** Below that, phases and a
-Tracker are enough; a three-phase feature gains nothing from ceremony. (Same sizing instinct as the
-Advisory-Hub test, deliberately — one threshold to remember, not two.)
+Tracker are enough; a three-phase feature gains nothing from ceremony.
 
 A milestone is **a group of phases that ship together**. It answers "what lands when this is done?",
 which is the question a long plan otherwise leaves the executor guessing at.
@@ -211,9 +200,10 @@ resuming session can see at a glance which group it is in and what remains befor
 ### Flag high-risk phases (`risk:` — a marker, not a mechanism)
 Each phase may carry **`risk: normal|high`** (default `normal` — omit the line unless the phase is
 `high`), meaning only "this is a phase where a wrong answer is expensive" — security/authz, a
-correctness-critical algorithm, an ambiguous spec, or an irreversible change. It is **inert**: it
-selects no model, spawns no agents, and implies no fan-out — it exists so the executor can decide **at
-runtime** whether an extra cross-check is worth it. Do not emit orchestration, lane fan-out, or
+correctness-critical algorithm, an ambiguous spec, or an irreversible change. It selects no model and
+implies no fan-out. It has one effect: the roadmap/plan runner reviews a finished `risk: high` phase
+twice (`caddis_review.py --plan --phase --runs 2`), gives it one fix session on blocking
+findings, and stops `BLOCKED review` when findings remain. Roadmap mode reviews before it publishes the PR. Do not emit orchestration, lane fan-out, or
 `Workflow` scripts from this command; the runtime decision rules and the intent→model map live in one
 place, the `agent-orchestration` skill's *Multi-model fan-out* section.
 
@@ -275,7 +265,10 @@ yourself (relay + Tracker) before stopping — do not hand back "run `/caddis:ha
 Three rules: one attempt, one review.
 1. **Think before you send.** Before a task goes to any coder, write its edge cases and check the facts it depends on (one query or one file read).
 2. **Run it before review.** The coder runs the same checks as CI (name the exact commands in the task). Then run the change once on real data.
-3. **Review once.** Use whatever reviewer is available. Stop at the first CLEAN. After two blocking reviews, ask the owner.
+3. **Review by tier.** Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-tier --range <base>...HEAD` (add `--plan <plan> --phase <N>` inside a plan; no `TIER:` line means tier 2).
+   Tier 0: gates only. Tier 1-small: your self-check only. Tier 1: one review by another vendor; stop at
+   the first CLEAN. Tier 2: two reviewers of two other vendors, in one round. Fix blocking findings only;
+   park the rest. Re-review only the fix diff, and only when the fix changed logic. After 3 rounds, ask the owner.
 
 - One phase at a time: read this plan → run the phase on its **Lane** → RED→GREEN→VERIFY→CROSS-REVIEW→
   COMMIT → update the **Tracker** row. The Tracker is the resume signal for every future session.
@@ -293,6 +286,10 @@ Three rules: one attempt, one review.
      normally; the halt stops anything being **built on top of it** before a human has looked. Blast
      radius stays one reviewable, revertable commit. Halting *beforehand* buys nothing: the phase has
      to be executed either way, and a well-specced high-risk phase is as executable as any other.
+     One exception: when the session prompt says the runner reviews `risk: high` phases (the
+     runner's `plan-resume-prompt.md` says so), the runner's review gate replaces this halt: the
+     session ends `STATUS: CONTINUE`, and the runner reviews the phase twice before anything builds
+     on it. A headless marker (`CADDIS_HEADLESS=1`) alone does not lift the halt.
   4. **A failed or blocked phase** — tests red, exit gate unmet, or the plan turned out wrong. Stop;
      do not build on it.
 - **A lane change is NOT a halt.** `/caddis:implement` spawns the assigned lane itself and verifies
@@ -366,66 +363,15 @@ done:
 
 If any phase relies on the implementer *reasoning out* a gap, close the gap in the plan now.
 
-## Step 3b — Does this plan need an Advisory Hub? (ask once, here)
-
-The Advisory Hub is **opt-in per plan**, gated on a single file: `<plan-stem>-advisory-context.md`
-beside the plan. `/caddis:implement`, `/caddis:handoff` and `/caddis:validate-phase` all check for it;
-**no file → no behaviour change, ever.** But nothing has ever *asked* whether to create it, so the
-pattern only ever gets used by someone who already knows it exists. This step closes that gap.
-
-**Ask it here** — at the end of planning is the only moment the phase count, risk levels and session
-boundaries are all known.
-
-> **You MUST call `Skill(advisory-hub)` and read *"When it earns its keep"* before deciding.**
-> Do not decide from memory, and do not decide from any summary — including one in this file.
-> The test is stated in exactly one place on purpose: two copies of a rule drift on the first edit,
-> and the copy that used to live here had already drifted. It compressed the REQUIRED leg to the
-> phrase *"expensive-to-reverse"* and dropped the enumeration that defines it — which reads as
-> *"can I `git revert` this?"*, and under that reading a plan that publishes € figures to business
-> stakeholders scores "no stakes". That is the one leg that fires on reporting, analytics and
-> dashboard work, i.e. most of what this fleet builds. Load the skill.
-
-If the test passes, tell the user plainly what it costs and what it buys, and offer to scaffold the
-context doc from the `advisory-hub` skill's template. **Do not create it silently** — an opt-in
-pattern that switches itself on is no longer opt-in.
-
-**In headless mode, never offer and never create.** Headless forbids asking anything, so an "offer"
-is impossible there. Instead record the result as a line under `## Constraints & decisions` —
-*"Advisory Hub: test passed (N phases, <criteria>) — not scaffolded, headless run; create
-`<plan-stem>-advisory-context.md` to enable"* — so the decision reaches a human rather than being
-silently dropped or silently taken.
-
-If it does not pass, say nothing **to the user** — a three-phase feature should never hear about
-this. But **always record the determination in the plan, pass or fail**: one line under
-`## Constraints & decisions`, naming which REQUIRED trigger was or was not hit.
-
-> `Advisory Hub: not applicable — no REQUIRED trigger (not a migration / security change /
-> production data correctness / numbers published to stakeholders).`
-
-### If the test FAILS but this repo already runs a Hub for another plan
-
-Check for an existing `*-advisory-context.md` in `.caddis/plans/` belonging to a **different** plan.
-If one exists, add a second line under `## Constraints & decisions`:
-
-> `Hub conventions: this repo runs Advisory Hub for <other-plan>. This plan does NOT — if it borrows
-> the phase-NN.prompt.md / .report.md / CONTINUE GATE conventions, the lightweight rule applies: the
-> session that files a report must not write the next prompt without an independent re-check.`
-
-**Why this line exists.** A repo with one Hub plan has its artefacts sitting there as the most recent
-example of "how we structure a multi-session plan here", and the next plan copies them by analogy.
-It inherits the file names and none of the safety, because the safety was never in the names.
-Measured once already: an implementing session filed its own batch report and then wrote the next
-batch's prompt in the same session, with nobody having looked in between. Nothing was wrong that
-time — and nothing checked either.
-
-This is the cheapest possible place to catch it: when the second plan is created, before any
-artefact-mimicry has happened. See *"Failing this test correctly does not mean no discipline"* in the
-`advisory-hub` skill for the rule itself. Do not restate the rule here — one home, or the copies
-drift.
-
-Silent to the human, auditable in the artifact. "Say nothing" once meant *leave no trace anywhere*,
-and a wrong negative was then invisible — no line in the plan, no line in the chat, nothing for
-anyone to challenge. A rule whose failures leave no artifact cannot be reviewed.
+A `risk: high` phase gets two independent review runs: run by the roadmap/plan runner automatically (from caddis-next Phase 11), and by hand in an interactive `/caddis:implement` run (`caddis_review.py --plan <plan> --phase <n> --runs 2`, from Phase 10). Only a `blocking` finding fails that review (exit 1); `should-fix` and `nit` findings go on a follow-up list and do not stop the merge. A phase gets 3 completed review rounds (a run that did not complete uses none); the 4th ends with exit 5, "stop, the owner decides". The advisory hub is retired; do not plan a separate validation session.
+
+## Programme triggers
+
+Small work that does not meet a trigger skips its block.
+
+**Trigger: Always.** Add one open-work row for the plan in `.caddis/open-work.md`. Set its cells with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_rows.py" set --file <open-work.md> --id <row id> --col Status=todo`, never with a regex edit.
+
+**Trigger: The plan records a decision.** Record it with `/caddis:decide`.
 
 ## Step 4 — Report
 Output the plan path (`.caddis/plans/<feature-slug>.md`), the phase list (one line each, with each

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

@@ -8,6 +8,42 @@ description: End-of-session handoff — capture exact state so the next session
 You are ending a work session. Produce/refresh this workstream's resume doc (`.caddis/relay/<name>.md`) so the next session
 (you, a future you, or another agent on any tool) can resume immediately. This is the anti-context-rot checkpoint.
 
+## Step 0 — is this a shared checkout?
+Another session may have uncommitted edits in this checkout. A handoff that commits here can carry
+them into its commit, so check first, before Step 1.
+
+1. Write this session's own files to a temp file: copy the list under `## Files changed this session`
+   in `.caddis/session-state/<session-id>.md` (the `` - `path` `` lines can be copied as they are).
+   No state file or no list means an empty file.
+2. Run:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_checkout_guard.py" shared --root . --own-files <temp-file>
+   ```
+   It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when the root `AGENTS.md`
+   has a line `Shared checkout: yes`, or when `git status` lists a path this session did not change.
+3. **On `SHARED: no`,** do the steps below as written.
+4. **On `SHARED: yes`,** write NO tracked file in this checkout. Run:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_docs_pr.py" start --repo .
+   ```
+   It makes a new worktree from `origin/<default>` on a `docs/handoff-<utc>` branch and prints
+   `WORKTREE: <path>`. That worktree is this session's only; no other session's edits can enter it.
+   Then, in the steps below:
+   - Step 1: tell the `knowledge-transfer` subagent to edit files ONLY under the `WORKTREE:` path.
+   - Step 3, point 4: run `caddis_rows.py set --file <worktree>/.caddis/open-work.md ...`, and make the
+     plan's Tracker edit in `<worktree>/.caddis/plans/<feature>.md`, not in this checkout.
+   - Step 4: skip `caddis_tidy.py --apply` (report `skipped: shared checkout`).
+   - Step 6b: skip `session_state.py prune` (report `skipped: shared checkout`).
+   - The relay stays in this checkout: `.caddis/relay/` is local and gitignored.
+   After Step 6b, run:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_docs_pr.py" finish --worktree <path> --title "docs(handoff): <name> session notes" --body "Handoff doc edits from a shared checkout."
+   ```
+   It commits only the worktree's changed files, pushes, opens a PR, and prints `PR: <url>` and one
+   `FILE: <path>` line per file (or `PR: none` when nothing changed). It always removes the worktree, and
+   it never merges. On a failure it prints `PATCH: <path>` with the edits; report that path. Put the
+   `PR:` line and the file list in your final report, under `Docs PR needed:`.
+
 ## Step 1 — capture learnings FIRST (knowledge-transfer)
 **Before** gathering git signals or writing relay.md, decide on `knowledge-transfer` — and the default
 is to run it.
@@ -36,7 +72,7 @@ committed before its generator last changed. Paste the parts a next session need
 them from memory.
 
 **Why this step is mechanical.** A handover used to be composed from what the outgoing session
-remembered, so it was only ever as complete as that memory. Bringing one Hub to a usable state took
+remembered, so it was only ever as complete as that memory. Bringing one successor session to a usable state took
 nine corrective round trips and the user caught six of them — including *"the handover listed no
 reports, documents, KB notes or scripts"*. None of those are judgement calls; every one is a
 directory listing. An agent recalls **what it did**; a generator enumerates **what exists**, and
@@ -53,39 +89,7 @@ clean phase boundary and lose or double-do the work.
 tracker shows plan A in progress, but the work moved to plan B), suggest the user run `/digress` to park
 plan A on the workstream stack — so its exact resume point survives and `/catchup [name]` can pop it back later.
 
-## Step 2b — Advisory-Hub handoff audit (conditional — skip silently if not applicable)
-
-**Trigger:** the active plan found in Step 2 has a sibling `<slug>-advisory-context.md`. **No such file
-→ skip this step entirely and silently** — no extra work on an ordinary handoff.
-
-> **First, say which command the user actually wants.** A context doc means a Hub is running, and
-> handing over a Hub is `/caddis:spawn-hub`, not this command. The two look interchangeable from
-> outside and are not: `/handoff` writes a resume doc for the same workstream, while `spawn-hub`
-> ends the Hub's tenure, runs the mechanical audit, conserves the carried-open ledger, and files
-> `hub-NN.spawn.md` in `.caddis/advisory-hub-reports/`. Tell the user plainly, then continue only if
-> they still want a plain handoff.
-
-**Why it is a distinct step:** a context doc is written *before* the work happens, so it is **always
-stale by the time it is needed**. The outgoing Hub's instinct is always "yes, this doc is designed for
-exactly this" — **that instinct has been measured and found wrong**: a real audit found seven gaps in a
-context file the outgoing Hub believed was current, including the single highest-value technique the Hub
-had developed by then.
-
-**Do not ask "are there gaps?" Assume there are, and find them mechanically** (full detail: the
-`advisory-hub` skill's §G):
-1. **List every technique, decision, and correction you actually used this session** — from your own
-   actions in this transcript, not by re-reading the context doc.
-2. **For each, check whether the context doc's instruction itself already covers it** — not whether the
-   word appears. Would a fresh Hub, reading only that file, be told to do the same thing?
-3. **The caveat that will burn you:** a literal-string grep over prose produces **false MISSINGs**. A
-   `0 matches` result means "this exact string isn't here," not "this isn't covered." **Read the section
-   before believing a 0-match grep.**
-4. **Land every real gap as a durable rule** in the right section of the advisory-context, carrying the
-   specific failure that earned it — a note left for later is not a fix.
-
-Record the outcome in relay.md's `## Learnings captured` line (below).
-
-## Step 2c — was any of it the harness?
+## Step 2b — was any of it the harness?
 
 <!-- shared:harness-friction-question — keep byte-identical across commands; a test pins it -->
 **One question, asked here because here is where you are already reflecting.** The observations
@@ -111,7 +115,7 @@ Nothing to say is the normal answer. Say nothing and move on — this must not b
 > `session_id` and `--session-id`. Never guess one: a wrong id disables session matching.
 >
 > 1. **Name the workstream** (active plan's `feature`, else the branch; the script prints nothing
->    on the default branch with no plan — then ask the user for a short name):
+>    on the default branch with no plan — run `caddis_workstreams.py list` (`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" list`) to show existing workstreams, then ask the user which one to use or for a short name):
 >    `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" resolve --plan <feature> --branch <branch> --default-branch <main>`
 > 2. **Legacy repo:** if `.caddis/relay.md` exists and does not start with
 >    `<!-- caddis-workstream-index-v1 -->`, or an old `/digress` stack `.caddis/workstreams.json`
@@ -120,11 +124,21 @@ Nothing to say is the normal answer. Say nothing and move on — this must not b
 >    to the user and stop.
 > 3. **Read the stored version's hash** before you compose: `caddis_workstreams.py hash <name>`
 >    (prints `none` for a new workstream).
-> 4. **Write** the relay below to a temp file, then
->    `caddis_workstreams.py write <name> <temp-file> --expected-hash <hash>`. Exit 1 means another
->    session changed the relay since step 3: it prints the diff and writes nothing. Show the diff,
->    merge by hand, and retry with the new hash. Never force it.
-> 5. **Refresh the index:** `caddis_workstreams.py render-index --session-id <id> --branch <branch>`.
+> 4. **Open-work rows** (only when `.caddis/open-work.md` exists and its frontmatter says
+>    `type: open-work`): first set each row this session
+>    finished, by id and column name, never by hand:
+>    `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_rows.py" set --file .caddis/open-work.md --id <row id> --col Status=done --col Evidence=<evidence>`.
+>    In a shared checkout (Step 0), use `--file <worktree>/.caddis/open-work.md` instead.
+>    **Order of work:** when the repo has a roadmap (`caddis_roadmap.py list` prints a slug), the
+>    roadmap on origin is the order of work. Write the relay's "Next step (exact)" as
+>    `next: top open item of roadmap <slug> (caddis_roadmap.py status --roadmap <slug>)`. Never copy a
+>    list of open items into the relay.
+> 5. **Write** the relay below to a temp file, then
+>    `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" put <name> <temp-file> --require-status --expected-hash <hash>`.
+>    It refuses a relay whose last line is not a valid status line (see "Programme triggers" below).
+>    Exit 1 also means another session changed the relay since step 3: it prints the diff and writes
+>    nothing. Show the diff, merge by hand, and retry with the new hash. Never force it.
+> 6. **Refresh the index:** `caddis_workstreams.py render-index --session-id <id> --branch <branch>`.
 >
 > (Source checkout: `scripts/caddis_workstreams.py`.) A repo still on the pre-rename `.claudster/`
 > won't see this relay until it's converted — `/caddis:migrate-dir` does that.
@@ -154,6 +168,7 @@ generated:
 <The single next action. Include the command/phase. Add a fallback if blocked.>
 
 ## Read first on resume
+Paths are relative to the repo root.
 - `<path>` — why it matters
 - `.caddis/plans/<feature>.md` — the plan + tracker
 
@@ -165,18 +180,26 @@ generated:
 
 ## Learnings captured
 knowledge-transfer: <✓ ran → files written | ✗ skipped → reason>
-advisory-context audit: <N candidates → M gaps → landed in <path>> | n/a (no advisory-context for this plan)
 
 ## Resume prompt
 \`\`\`
 Read .caddis/relay/<name>.md, then the plan it points to. Continue from <phase/step>. Next action: <exact>.
 \`\`\`
+
+STATUS: <CONTINUE | OWNER-GATE <P>-OG<n> | BLOCKED <owner> | FAILED <reason>>
 ```
 
+## Programme triggers
+
+Small work that does not meet a trigger skips its block.
+
+**Trigger: Always.** The relay ends with a status line, the last non-empty line, and it is exactly one of `STATUS: CONTINUE`, `STATUS: OWNER-GATE <P>-OG<n>`, `STATUS: BLOCKED <owner>` or `STATUS: FAILED <reason>`. In Step 3, point 5, write the relay with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" put <name> <temp-file> --require-status --expected-hash <hash>` instead of `write` (in short: put --require-status), with the same hash Step 3 read, so a peer's newer relay is never overwritten. It rejects a relay with no valid status line, and renders the index. When the repo has `.caddis/open-work.md` with `type: open-work` in its frontmatter, also set each open-work row's status with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_rows.py" set --file <open-work.md> --id <row id> --col Status=<status>` (in a shared checkout, the copy in the Step 0 worktree). When the status is `done`, also pass `--col Evidence=<commit, PR or test>`: caddis_rows.py refuses `done` with no Evidence.
+
 ## Step 4 — tidy finished artifacts
 Flip any plan/prompt's frontmatter `status:` to `done` (or `superseded`) if this session actually
 finished it — that is your judgment call; the script below never makes it and never auto-flips
-status. Then run:
+status. In a shared checkout (Step 0), make the `status:` flip in the Step 0 worktree copy of the plan,
+never in this checkout. Then run (skip it in a shared checkout, Step 0: it moves tracked files):
 ```
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply
 ```
@@ -184,7 +207,13 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply
 skip this step** — it degrades open, same as the other machine gates; an older install must not
 be blocked by a script it does not have. Include its report in your output. A **collision**
 (`done/<name>` already exists) is reported by the script, not fatal — surface it, do not fail the
-handoff over it.
+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.
+
+After step 4, for each item this session closed (a phase `<plan>#<n>`, a plan slug, or an open-work row id), run `mentions` to check whether another relay's Next step still names it:
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" mentions --item "<item>" --except <name>
+```
+Print a `WARNING:` line per hit (`WARNING: relay <other> still names closed item <item> in its Next step`). Never edit another workstream's relay (`caddis_workstreams.py mentions` only reads).
 
 ## Step 5 — check the handover you just wrote
 
@@ -197,7 +226,7 @@ report that repo's paths as missing, which is the tool being right about the wro
 
 It fails when the handover names a file that does not exist. The incoming session has **no other
 source** for those paths, so it cannot tell a typo from a real file: one live handover sent an
-incoming Hub looking for a prompt that was never written. Fix what it lists, then re-run.
+incoming session looking for a prompt that was never written. Fix what it lists, then re-run.
 
 It also notes any generated artefact committed before its generator last changed. That is advisory,
 not blocking — but do not quote a report the note names without rebuilding it first.
@@ -219,7 +248,8 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/session_state.py" prune
 `usage` finds this session's transcript by its id and appends one token-and-skill record to
 `.caddis/usage-log.jsonl`, which `/usage-review` reads. Pass `--transcript <path>` if you know the
 path and it is not under the Claude config folder. `prune` keeps the newest 8 files in
-`.caddis/session-state/`; run it after Step 6, which reads this session's file. Include the
+`.caddis/session-state/`; run it after Step 6, which reads this session's file. Skip `prune` in a
+shared checkout (Step 0). Include the
 `[USAGE]` line in your output. Both always exit 0; if the script is missing, skip this step.
 
 Then list old local state (falls back to `scripts/caddis_tidy.py`; skip if missing):
@@ -247,10 +277,9 @@ On the other machine, `/catchup <name>` fetches it.
   order: (1) interrupted mid-phase work → finish + commit it; else (2) the active plan's next not-started
   phase; else (3) the top open question/decision. Everything else is context, not the next step.
 - Only verified facts and real paths. Mark anything unconfirmed as `Unknown`.
-- Update the plan's tracker rows too (status + last commit) — relay and tracker must agree.
+- Update the plan's tracker rows too (status + last commit) — relay and tracker must agree. In a shared
+  checkout, edit the Tracker in the Step 0 worktree, never in this checkout.
 - Don't commit unless asked. Report which `.caddis/relay/<name>.md` was written and the one next action.
-- **Never hand off a Hub session on the strength of "the context doc is designed for this."** That is the
-  one instinct that has been measured and found wrong. Run Step 2b's audit instead.
 - **Prune the Done section — two rules, both apply:**
   1. **Merge-based:** Phases already merged to `main` (confirmed by a tag or commit) must be compressed
      to a single line: `- **RW-N**: merged to main as vYYYY.MM.DD.N (<commit>) ✅`. Only the current