@caddis/cli 0.2.3 → 0.2.5

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

@@ -13,8 +13,10 @@ 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`** (a docket runner / non-interactive
-caller spawned this session — no human is present), the scope-check questions and any interview are
+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
+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 —
 write a complete best-effort plan anyway.
@@ -53,6 +55,36 @@ points), read it first. It's a free, token-zero project fingerprint that anchors
 exists instead of assumed. If the work fits comfortably in one session, say so and offer to just do it
 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
+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.
+
+Before writing any phase, tier each item:
+- **BLOCKER** — stop and ask the user. Do not plan around it.
+- **WARNING** — proceed, but the affected phases carry a stated assumption.
+- **OPTIONAL** — note its absence and continue.
+
+| # | Evidence | Tier |
+|---|---|---|
+| E1 | A mockup / wireframe / screenshot of the target UI, and is it frozen? | BLOCKER for UI-heavy work, WARNING otherwise |
+| E2 | A real data sample on the CURRENT schema, so field names are read not guessed | BLOCKER for any data binding, WARNING if a typed DTO/interface defines it |
+| E3 | The API contract for anything you will call — real request/response shapes | BLOCKER when integrating something you did not write |
+| E4 | Scaffold inventory: what already exists that these phases must fit into | WARNING — `.caddis/PROJECT-FACTS.md` fills this for free if present |
+
+**Free head-start:** `.caddis/PROJECT-FACTS.md` pre-fills E4 plus the run/test/build commands, env-var
+names and CI workflows at zero token cost — and grounds the `## Risks` table in what the scan actually
+shows rather than boilerplate.
+
+**If a PRD exists for this feature, read it FIRST.** Look for `.caddis/prd/<feature-slug>.md`.
+`/caddis:prd` ends by suggesting `/feature-plan <feature>`, and until now nothing on this side ever
+opened the file — so the whole chain's first handoff depended on the model happening to look. Carry
+its functional requirements into phases (they are written *"so a test can verify it"*, which is
+exactly what a phase's exit gate needs) and its `## Open questions` into `## Constraints & decisions`.
+A headless pipeline that plans straight from a bare title while a complete PRD sits on disk is the
+failure this closes.
+
 ## Step 2 — Design phases
 Break the work into **independently completable** phases (~30–60 min each, clear exit gate). Each phase
 follows the harness loop: **RED → GREEN → REFACTOR → VERIFY → COMMIT**. Front-load risk.
@@ -88,10 +120,54 @@ A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
   feature branch). The local-coder gate below exists exactly so these phases survive a weaker
   implementer — a phase may only take this lane if it passes that gate.
 - **review lane (every phase that touches code)** — cross-vendor review by a vendor that did NOT
-  write the code: `python .github/tools/oss_review.py --range main..HEAD --provider deepseek`
+  write the code: `/caddis:cross-review --range main..HEAD`
   (Claude or GLM implemented) or `--provider glm` / a Claude `code-reviewer` pass (DeepSeek-adjacent
   work). Never same-vendor.
 
+**The `Lane:` line is a routing directive read by `/caddis:implement`, not a note.** An interactive
+session that is handed a phase belonging to another lane spawns that lane rather than absorbing the
+work; a headless one records the deviation in the Tracker. Write the launch command out in full, per
+phase — it is executed verbatim.
+
+#### A phase may take a no-escalation lane only if its exit gate would fail on a spec error
+`glm-headless` cannot escalate: it does what the phase says. So completeness is only half the test —
+the other half is whether being **wrong** would be caught. Ask literally: *"if the instruction I just
+wrote were wrong, would this phase's exit gate go red?"*
+- **Yes** → pure logic with literal assertions: a parser, a computed value, an API shape assertion
+  (*"`expected_slots` returns exactly 96 and 1440"*). Safe for a no-escalation lane.
+- **No** → user-facing copy, nav/menu entries, status or badge flags, ordering, wording, config
+  defaults — anything whose only proof is a human looking at it. **Not safe, however completely it
+  is specified.**
+
+This is the failure the completeness gate cannot see, because **you wrote the spec**: if you could
+see the gap you would have filled it. Live case — a phase spelled out to 10 literal steps across 8
+files passed every bullet of the local-coder gate, and the spec itself was wrong twice (it shipped an
+internal repo path into stakeholder-facing copy, and set a `live` status flag that suppressed the
+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.)
+
+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.
+
+```markdown
+### Milestone M2 — <name>  (phases 4-7)
+**Ships:** <what actually lands — a version, a PR, a deploy>
+**Gate:** <the check that must pass before it ships>
+**Boundary:** handoff + fresh session before M3
+```
+
+Then give every phase a `**Milestone:** M2` line and add a `Milestone` column to the Tracker, so a
+resuming session can see at a glance which group it is in and what remains before the next ship.
+
 ### 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
@@ -133,6 +209,7 @@ Creating Model: <model-id>
 ### Phase 1 — <name>  ⏳
 > ⚠️ **Switch model/lane BEFORE starting this phase** — the *active* model does the work, not the
 > one named here. Lane `claude`: run `/model <alias>`. Lane `glm-headless`: run the exact command below.
+**Milestone:** M1  *(omit on plans without milestones)*
 **Model:** <tier> (`/model <alias>`) — <one-line rationale tied to this phase's difficulty>
 **Lane:** claude — this session  |  glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
 **Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
@@ -144,10 +221,11 @@ Creating Model: <model-id>
   - GREEN: <minimal implementation>
   - REFACTOR: <what to clean if needed>
 **Verify (subagents):** dispatch `tester` (must return passed), then `code-reviewer` (verdict: approved)
-**Cross-review:** `python .github/tools/oss_review.py --range main..HEAD --provider <vendor that did NOT implement>` → REVIEW: CLEAN
+**Cross-review:** `/caddis:cross-review --range main..HEAD` → REVIEW: CLEAN
 **Exit gate:** <specific, testable — e.g. "GET /api/x returns 200 with {shape}", not "tests pass">
 **Commit:** `<conventional commit message>`
-**Then:** update the Tracker row (status + hash) → `/caddis:handoff` if ending the session here.
+**Then:** update the Tracker row (status + hash). If this phase ends the session, WRITE the handoff
+yourself (relay + Tracker) before stopping — do not hand back "run `/caddis:handoff`" as the next action.
 
 ### Phase 2 — <name>  🔲
 <same structure>
@@ -155,9 +233,36 @@ Creating Model: <model-id>
 ## Execution protocol (standing rules — this plan is the memory, not anyone's head)
 - 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.
-- **Session boundaries:** `/caddis:handoff` after any phase that ends a sitting. Start a FRESH
+- **Session boundaries:** the executor WRITES the handoff (durable `relay.md` + Tracker) after any
+  phase that ends a sitting — it performs the work, it does not suggest the command. Start a FRESH
   session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or whenever
   context feels heavy. Resume with exactly: `read <this plan's path> and implement the next ⏳ phase`.
+- **Run to a boundary, not to a phase.** The executor implements phase after phase, committing each,
+  and stops only at a marked boundary. Do not plan a stop after every phase — that is the friction
+  this structure exists to remove.
+- **The four halts, and nothing else:**
+  1. **A milestone boundary** — its `Gate:` passed and it is ready to ship.
+  2. **A phase marked `Session: fresh`** — context is heavy or the work changes shape.
+  3. **After a `risk: high` phase** — *after*, never before. The phase is executed and committed
+     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.
+  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
+  the result. It used to need a human only because the routing was inert.
+- **At every halt, leave both:** the executor PERFORMS the handoff (writes `relay.md`, updates the
+  Tracker) and then prints the **halt block** — the single thing the human acts on. A next action of
+  "do a handoff" / "update the relay" is a DEFECT, not a handoff: it names the work instead of doing
+  it, and the context needed to do it is gone the moment the session ends:
+  ```
+  === HALT — <one-line reason> ===
+  Done:    phases 4-7 (M2) · commits <sha>, <sha>
+  Blocked: <what, or "nothing">
+  You:     /clear, then paste ↓
+           read <plan path> and implement Phase 8
+  ```
+  A run that trails off without this costs a human the work of reconstructing where it got to.
 - **Ship gate:** NEVER push or merge to main from a phase — phases only commit to the feature branch.
   When all phases are ✅: `/caddis:ship-pr` (stops at green CI), then STOP and wait for the human's
   explicit go before `/caddis:ship-merge`.
@@ -171,9 +276,9 @@ Creating Model: <model-id>
 |---|---|
 
 ## Tracker (update as you go — this is the resume signal)
-| Phase | Model | Lane | Status | Commit | Cross-review | Notes |
-|---|---|---|---|---|---|---|
-| 1 | mid | claude | not started | — | — | |
+| Phase | Milestone | Model | Lane | Status | Commit | Cross-review | Notes |
+|---|---|---|---|---|---|---|---|
+| 1 | M1 | mid | claude | not started | — | — | |
 ```
 
 ## Plan quality gate — local-coder ready (MANDATORY)
@@ -195,9 +300,59 @@ done:
   the literal launch command for glm phases) and a cross-review provider that is a different vendor
   than the implementer. A glm-headless phase MUST pass every bullet of this gate — that lane has no
   slack for reasoning out gaps.
+- **Launch command is spawnable** — every `glm-headless` phase's command carries **`-p`** (or
+  `--print`) and ends with **`— Phase N only`**. Both are load-bearing, not style: the launchers set
+  `CADDIS_HEADLESS` *only* on `-p`, and that variable is the guard that stops a spawned session
+  spawning another one forever; the `Phase N only` suffix is what stops the child running to the end
+  of the plan. The command is executed verbatim by a model with no slack to notice a missing flag,
+  and `/caddis:implement` now refuses a command without `-p` rather than running it.
+- **Gate-detectable** — if this phase's instruction were WRONG, its exit gate would go red. A phase
+  whose gates pass either way (copy, nav entries, badges, ordering, wording, config defaults) must
+  not take a lane that cannot escalate, no matter how completely it is specified. Every other bullet
+  here checks that the spec is COMPLETE; only this one checks that a mistake would be noticed.
 
 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).`
+
+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.
+
 ## Step 4 — Report
 Output the plan path (`.caddis/plans/<feature-slug>.md`), the phase list (one line each, with each
 phase's model tier + lane), confirm the local-coder gate passed (or list the phases that need

package/bundles/antigravity-plugin/skills/gate-preflight/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: gate-preflight
+description: Deterministic headless preflight — validates a plan against the actual codebase, self-contained (never depends on a skill activating)
+---
+
+# /caddis:gate-preflight — headless plan-vs-codebase validation (self-contained)
+
+Validate the implementation plan at **$ARGUMENTS** against the ACTUAL codebase before any code is
+written.
+
+This command exists because `/caddis:preflight` is a model-invoked `context: fork` **SKILL**, and
+skills do not reliably activate under headless `claude -p` — proven live (2026-07-08): a run saw
+the raw `/caddis:code-review <sha-range>` text, didn't recognise it, and replied "I don't see a
+specific task in your message." No review happened. This command spells the task and criteria out
+inline instead, so the check always happens whether or not the skill fires.
+
+**What to do:** read the plan, then verify every technical claim with your tools — do the file
+paths it cites exist (or are they correctly marked new)? Do referenced functions/classes/types
+exist with the exact names (grep them, don't trust the plan's spelling)? Do API/route shapes and
+data fields match what the codebase actually returns? Are required dependencies installed or
+explicitly scheduled for installation in an earlier phase? **A claim you cannot verify is a
+finding, not a pass.**
+
+If a `preflight` skill is available, use its methodology as a nudge — its 8-category framework is
+more thorough than the paragraph above. But do not wait on it or treat it as required: the check
+above is enough to produce a real verdict on its own.
+
+## HEADLESS RUN RULES (mandatory)
+- **Non-interactive. No human is present. NEVER ask a question.** Where the plan leaves a genuine
+  gap, that is itself a finding — note it and keep going.
+- **READ-ONLY.** Do NOT write or edit any code. Do NOT switch branches. Do NOT commit.
+- A plan **PASSES** only with zero blocking discrepancies.
+
+End with EXACTLY one line and nothing after it: `PREFLIGHT: PASS` or `PREFLIGHT: FAIL`.

package/bundles/antigravity-plugin/skills/gate-review/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gate-review
+description: Deterministic headless code review — adversarial diff review, self-contained (never depends on a skill activating)
+---
+
+# /caddis:gate-review — headless adversarial code review (self-contained)
+
+Perform an adversarial code review of **$ARGUMENTS** (a git range, e.g. `abc123..HEAD` — defaults
+to the current working diff when empty).
+
+This command exists because `/caddis:code-review` is a model-invoked `context: fork` **SKILL**, and
+skills do not reliably activate under headless `claude -p` — proven live (2026-07-08): a run saw
+the raw `/caddis:code-review <sha-range>` text, didn't recognise it, and replied "I don't see a
+specific task in your message." No review happened. This command spells the task and criteria out
+inline instead, so the review always happens whether or not the skill fires.
+
+**What to do:** inspect the diff (`git diff $ARGUMENTS`, and `git show <sha>` per commit as
+needed) and read the changed files in full context, not just the diff hunks. Judge, in priority
+order:
+1. **Correctness** — logic bugs, wrong results, missed edge cases.
+2. **Tests** — would a test actually fail without this change; are the stated behaviors covered.
+3. **Security** — injection, auth gaps, secret exposure, unvalidated input.
+4. **Conventions** — the repo's `AGENTS.md` rules (canonical; `CLAUDE.md` is an `@AGENTS.md` shim).
+5. **Simplicity** — unneeded abstraction, scope creep beyond what the diff needed to do.
+
+Classify each issue as **blocking** (must fix before merge), **should-fix**, or **nit**.
+
+If a `code-review` skill is available, use its methodology as a nudge. But do not wait on it or
+treat it as required: the checklist above is enough to produce a real verdict on its own.
+
+## HEADLESS RUN RULES (mandatory)
+- **Non-interactive. No human is present. NEVER ask a question.**
+- **READ-ONLY.** Do NOT edit code. Do NOT commit. Do NOT switch branches.
+- Report only; do not fix — that is a different session's job.
+
+End with EXACTLY one line and nothing after it: `REVIEW: CLEAN` (no blocking issues) or `REVIEW: BLOCKING` (one or more blocking issues).

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

@@ -6,6 +6,12 @@ description: "USE THIS SKILL whenever a user asks for a comprehensive implementa
 
 # Golden Plan
 
+> **`/caddis:feature-plan` is the canonical planning entry point.** It writes to `.caddis/plans/`,
+> which is what `/caddis:implement`, `/caddis:handoff`, `/caddis:digress` and `/caddis:resume`
+> actually read, and it now carries this skill's evidence gate. Reach for golden-plan when you
+> specifically need its heavier apparatus — the data-binding tables, the query catalog, the
+> self-sweep. For ordinary multi-phase work, feature-plan is the shorter path to the same place.
+
 ## When to Use
 
 Activate this skill when the request is for a **comprehensive implementation plan** that involves:
@@ -92,8 +98,8 @@ Run through the checklist below. For each item, determine its tier:
 - **Tier:** OPTIONAL. Skill paths that do not exist should be omitted from phase prompts - do not list phantom skills.
 
 #### E8 - Output Destination
-- Where should the plan file be saved? (Default: `.github/plans/<feature-slug>.md`)
-- Where should the associated tracker be saved? (Default: `.github/plans/tracker/<feature-slug>-tracker.md`)
+- Where should the plan file be saved? (Default: `.caddis/plans/<feature-slug>.md`)
+- Where should the associated tracker be saved? (Default: `.caddis/plans/tracker/<feature-slug>-tracker.md`)
 - Is there a `chain_id` to use? (Format: `FEAT-YYYY-MMDD-{slug}`)
 - **Tier:** OPTIONAL. Default path is used if not specified.
 
@@ -185,7 +191,7 @@ Creating Model: <exact runtime model identifier or display name>
 > **Visual reference:** [path to mockup or "N/A"]
 > **Data source:** [path to canonical data sample or "See E3 - API Contract section"]
 > **Output destination:** [path where plan is saved]
-> **Execution tracker:** `.github/plans/tracker/<feature-slug>-tracker.md`
+> **Execution tracker:** `.caddis/plans/tracker/<feature-slug>-tracker.md`
 > **Execution:** Manual - one agent session per phase. See protocol below.
 
 ---
@@ -335,7 +341,7 @@ Do not mark done unless all items pass. If any fail, fix and re-verify.
 After all items pass:
 1. Create the phase implementation commit: `git add -A && git commit -m "phase(N): [Name] complete"`.
 2. Capture the phase implementation commit hash with `git rev-parse HEAD`.
-3. Update the associated execution tracker declared in the plan header: `.github/plans/tracker/<feature-slug>-tracker.md`.
+3. Update the associated execution tracker declared in the plan header: `.caddis/plans/tracker/<feature-slug>-tracker.md`.
 4. Mark Phase N complete in the tracker row with status, gate, completed date, executor/model, changed files, validation evidence, commit hash, push state, and comments.
 5. Commit the tracker update or amend it into the phase commit according to the repository's commit policy.
 6. Do not consider the phase complete until the tracker row is updated after validation and commit, and the row includes the commit hash and comments.
@@ -378,7 +384,7 @@ git commit -m "phase(N): [Name] complete"
 git rev-parse HEAD
 
 # 3. Update tracker
-#    Use .github/plans/tracker/<feature-slug>-tracker.md and mark Phase N complete with:
+#    Use .caddis/plans/tracker/<feature-slug>-tracker.md and mark Phase N complete with:
 #    status, gate, completed date, executor/model, changed files,
 #    validation evidence, commit hash, push state, and comments.
 ```
@@ -506,14 +512,17 @@ When a new phase must be inserted into an **existing plan** (discovered mid-proj
 
 ## Output Destination
 
-Every generated plan MUST have an associated execution tracker. Put the tracker path in the plan header as `> **Execution tracker:** .github/plans/tracker/<feature-slug>-tracker.md`.
+Every generated plan MUST have an associated execution tracker. Put the tracker path in the plan header as `> **Execution tracker:** .caddis/plans/tracker/<feature-slug>-tracker.md`.
 
 Golden-plan must create both files together. Never emit the plan without creating its associated tracker in the same run.
 
 Save the completed plan to:
 
-- `.github/plans/<feature-slug>.md` - default for both modes
-- `.github/plans/backlog/<feature-slug>.md` - optional backlog location
+- `.caddis/plans/<feature-slug>.md` - default for both modes
+- **Not ready to execute?** It is not a plan yet — file it as one future-work item at
+  `.caddis/parking-lot/<feature-slug>.md` (`type: parking-lot`, `status: open`), or run
+  `/caddis:park`. `.caddis/plans/backlog/` is retired: a second backlog location meant no session
+  could answer "what is left to do?" without knowing both.
 
 If mode is **`junai-pipeline`**, additionally register the artefact in `.github/agent-docs/ARTIFACTS.md` with `status: current`.
 
@@ -521,7 +530,7 @@ When revising an existing plan file, preserve `Original Author`, `Creation Date`
 
 ### Plan Status Tracker
 
-Alongside the plan file, **always** create `.github/plans/tracker/<feature-slug>-tracker.md` using
+Alongside the plan file, **always** create `.caddis/plans/tracker/<feature-slug>-tracker.md` using
 this template (one row per phase, populated from the Pre-Flight Scan). The plan header must reference this exact tracker path:
 
 ```
@@ -533,14 +542,14 @@ Creating Model: <exact runtime model identifier or display name>
 
 # Plan Status - [Project Name]
 
-> Plan: `.github/plans/<feature-slug>.md`
-> Tracker: `.github/plans/tracker/<feature-slug>-tracker.md`
+> Plan: `.caddis/plans/<feature-slug>.md`
+> Tracker: `.caddis/plans/tracker/<feature-slug>-tracker.md`
 > Started: YYYY-MM-DDTHH:MM:SSZ
 > Last updated: YYYY-MM-DDTHH:MM:SSZ
 
 | Phase | Name | Agent | Model | Status | Gate | Completed | Changed files | Validation evidence | Commit | Push | Comments |
 |---|---|---|---|---|---|---|---|---|---|---|---|
-| 0 | Context & Decisions | - | - | Complete | passed | YYYY-MM-DDTHH:MM:SSZ | `.github/plans/<feature-slug>.md` | Evidence gate complete | - | not_required | Plan authored |
+| 0 | Context & Decisions | - | - | Complete | passed | YYYY-MM-DDTHH:MM:SSZ | `.caddis/plans/<feature-slug>.md` | Evidence gate complete | - | not_required | Plan authored |
 | 1 | [Name] | @[Agent] | [model] | Pending | not_run | - | | | | unknown | |
 | 2 | [Name] | @[Agent] | [model] | Pending | not_run | - | | | | unknown | |
 | N | [Name] | @[Agent] | [model] | Pending | not_run | - | | | | unknown | |
@@ -558,7 +567,7 @@ Creating Model: <exact runtime model identifier or display name>
 **Comments rule:** The `Comments` column is required for completed, blocked, or skipped phases. Use it for concise handoff notes, blockers, decisions, caveats, known limitations, or follow-up context discovered during the phase.
 
 **Plan Completion Protocol:** When every tracker row has `status: Complete`, the plan is done. The executing agent (or the Janitor backstop) MUST:
-1. Filesystem-move the plan file from `.github/plans/<feature-slug>.md` to `.github/plans/done/<feature-slug>.md` using `Move-Item`/`mv`/`run_command` — NOT `git mv` (the `done/` folder is gitignored in project repos).
+1. Filesystem-move the plan file from `.caddis/plans/<feature-slug>.md` to `.caddis/plans/done/<feature-slug>.md` using `Move-Item`/`mv`/`run_command` — NOT `git mv` (the `done/` folder is gitignored in project repos).
 2. Update the plan frontmatter: set `status: done` and add `Archived: <YYYY-MM-DD>`.
 3. Log the move in the tracker `Comments` field of the last completed phase row.
 4. Never delete plan files — only move to `done/`.

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

@@ -26,9 +26,23 @@ is to run it.
 git status --short
 git branch --show-current
 git log --oneline -5
+python scripts/caddis_inventory.py          # what EXISTS — do not compose this from memory
 ```
 Then read the active plan in `.caddis/plans/` (falling back to legacy `.github/plans/` if present) and its tracker.
 
+**Read the inventory before writing anything.** It enumerates plans, PRDs, prompts, handoffs, KB
+notes, the parking-lot backlog, open comms, every script and its purpose, and any generated artefact
+committed before its generator last changed. Paste the parts a next session needs; do not retype
+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
+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
+those are different sets. Your judgement is still needed for what matters and what to do next —
+that half cannot be derived and is the only half you should be writing.
+
 **Crash / interrupted-work check.** Cross-check the tracker against `git status` + `git log`: if a phase is
 marked in-progress but has **uncommitted changes** (work left mid-flight), or a phase is marked done with
 **no commit** to back it, the last session was interrupted. Say so explicitly in `## Next step` ("resume
@@ -39,6 +53,38 @@ 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 `/resume` 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 3 — write the resume doc (overwrite) with exactly these sections
 > **Where to write:** solo / single active branch → `.caddis/relay.md` (default).
 > **Team / parallel branches** → write `.caddis/relay/<current-branch>.md` instead, so two
@@ -74,6 +120,7 @@ plan A on the workstream stack — so its exact resume point survives and `/resu
 
 ## 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
 \`\`\`
@@ -81,6 +128,35 @@ Read relay.md, then the plan it points to. Continue from <phase/step>. Next acti
 \`\`\`
 ```
 
+## 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:
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply
+```
+(falls back to `scripts/caddis_tidy.py` from a source checkout). **If the script is missing,
+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.
+
+## Step 5 — check the handover you just wrote
+
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" handover-check --doc .caddis/relay.md
+```
+(falls back to `scripts/caddis_gate.py` in a source checkout; degrades open when the script is
+missing.) **Run it in the repo the handover is about** — a handover describing another repo will
+report that repo's paths as missing, which is the tool being right about the wrong question.
+
+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.
+
+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.
+
 ## Rules
 - **One next action, by priority ladder.** `## Next step` names exactly ONE action — not a menu. Pick it in
   order: (1) interrupted mid-phase work → finish + commit it; else (2) the active plan's next not-started
@@ -88,6 +164,8 @@ Read relay.md, then the plan it points to. Continue from <phase/step>. Next acti
 - 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.
 - Don't commit unless asked. Report where `relay.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