@caddis/cli 0.2.3 → 0.2.5

package/bundles/antigravity-plugin/skills/spawn-hub/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: spawn-hub
+description: Hand the Advisory Hub role to a fresh session — run the mechanical audit, then generate the succession prompt with a context self-check the new Hub must pass
+---
+
+# /caddis:spawn-hub — hand the Hub role to a fresh session
+
+> **The Hub is a ROLE, not a conversation.** It outlives any one session and hands to the next through
+> **files** — never chat history. This command is the handoff. Until it existed, every Hub was spawned
+> by a hand-written prompt, which meant the pattern only worked for someone who already knew what to
+> put in one.
+
+**This command does not start the new session.** It leaves the outgoing Hub's context in a state a
+fresh one can pick up, then prints the prompt to paste. The human runs it.
+
+---
+
+## When to spawn — do not guess, and do not wait for the crash
+
+**The default seam is a MILESTONE BOUNDARY.** A milestone ends with a deploy, a smoke test and a
+handoff; that is already the plan's own `/handoff` → `/clear` point. Carrying a Hub across a deploy is
+where staleness bites — the outgoing Hub's picture of prod is exactly what just changed.
+
+**Spawn at the next milestone boundary if ANY of these is true:**
+
+- the current Hub has validated **≥5 phases**
+- it has executed **≥2 deploys**
+- it has done substantial work *outside* phase validation (fleet changes, tooling, plugin releases) —
+  that consumes context far faster than validation does
+- **its own context is filling** — this one overrides the milestone seam entirely
+
+> **Observed, not theorised:** on the reference project, Hubs 1–4 each ended because context ran out,
+> never because a milestone did. A Hub covers roughly **4–6 phases / 1–2 milestones** before that
+> happens. So treat the milestone as the *planned* seam and context as the *real* constraint, and run
+> this command at whichever arrives first.
+
+**Do not wait until context is nearly gone.** Step 1 is a real audit that needs room to run, and the
+outgoing Hub is the only session that can do it. A handoff written from a nearly-full context is the
+one most likely to omit exactly what the next Hub needs.
+
+---
+
+## Step 0 — resolve the context file, and refuse cleanly when you cannot
+
+Use `$ARGUMENTS` if given. Otherwise look for `<plan-stem>-advisory-context.md` beside every plan in
+`.caddis/plans/`.
+
+- **None found → STOP and say so.** This project is not running an Advisory Hub, so there is no role to
+  hand over. Do not scaffold one here: that decision belongs to `/caddis:feature-plan` Step 3b, at
+  planning time, when the phase count and risk are actually known.
+- **More than one → ask which**, listing them with each plan's status. Never guess: handing over the
+  wrong plan's Hub is worse than not handing over.
+- **Already handed over?** Check the succession table. If the last row has no end reason, this is a
+  fresh handover. **If the last row is already closed and a new one opened, STOP** — a previous run
+  completed and re-running would double-close it and re-open a duplicate. Re-running this command is
+  safe only when the tree still shows the outgoing Hub as current.
+
+## Step 1 — the mechanical audit (MANDATORY, and it is not a formality)
+
+**Do not ask yourself "are there gaps?" — assume there are, and find them mechanically.** The outgoing
+Hub's instinct is always *"yes, this is ready"*, because it is judging against its own memory of the
+session rather than against the document. **That instinct is wrong by default.** On the reference
+project the first answer to "can we hand off" was yes; a mechanical audit then found **seven gaps** —
+including that mutation testing, by then the single highest-value technique in use, was written down
+nowhere a fresh Hub would find it.
+
+1. **List every technique, decision and correction actually used this session** — from your own
+   actions, not from the context doc. Re-ran a cross-review with a second provider after a timeout?
+   Mutation-tested a seam? Fixed something directly rather than only flagging it? Corrected a gate
+   rather than the code? Each is a candidate line item.
+2. **For each, check whether the advisory context already tells a fresh Hub to do the same thing.**
+   Not "does the word appear" — whether *the instruction* is there.
+3. **Land every real gap as a durable rule** in the advisory context — its *Standing gotchas*,
+   *Hub techniques*, *Environment facts* or *Succession* section. **Cite sections BY NAME, never by
+   number:** numbers drift between a project's hand-grown file and the shipped template, and this
+   command previously named §7/§9/§13, which matched one project and no template.
+   **A correction that lives only in a verdict file dies with the session that wrote it.**
+4. **Audit in BOTH directions.** As well as what is missing, look for what is now **obsolete** — a
+   gotcha since promoted to `AGENTS.md`, or one a committed test now enforces, compresses to a line
+   and a pointer. The context doc is append-only by design and every incoming Hub must read it end to
+   end; without a diet it becomes the thing it exists to prevent.
+
+> **The caveat that will burn you: a literal-string grep over prose throws false MISSINGs.** The same
+> audit that found seven real gaps also produced three false negatives — content that *was* present,
+> phrased differently. `0 matches` means "not this exact string", not "not covered". Search by concept
+> and read the surrounding paragraph.
+
+## Step 2 — close the record
+
+- Every validated phase has a **verdict file**, and its `verdict:` frontmatter is one of
+  `accept` / `accept-with-correction` / `reject`.
+- Every **ACCEPT-WITH-CORRECTION** either has its corrections landed, or they are in the carried-open
+  list. An unlanded correction that nobody is tracking is the worst thing to hand over.
+- The plan's **Tracker rows** match reality. Check them; they get silently skipped, and on the
+  reference project four completed rows were reverted to "not started" by a stray staged edit and only
+  caught two milestones later.
+- `git status` is clean, or every uncommitted change is deliberate and named in the handoff.
+
+## Step 3 — update the succession table
+
+In the advisory context's succession section: close the outgoing Hub's row (what it covered, why it
+ended) and open the next one.
+
+**Then update the carried-open list — APPEND AND CLOSE, never rewrite.**
+
+Each Hub used to *rewrite* this list, which means an open item can vanish between generations with
+nothing to show it ever existed. Nobody notices, because the only evidence was the list itself.
+
+So: every item gets a stable id and is **never deleted**.
+
+```markdown
+- **[C7] Break-glass is DB-engine-dependent** — raised Hub 4. <what, and enough to act on>
+  → **CLOSED by Hub 6**: fixed in `abc1234`, verified on prod.
+- **[C9] `files.py` sibling-prefix traversal** — raised Hub 4. <detail>
+  → still open.
+```
+
+Closing an item requires **saying who closed it and why** — a line, not a deletion. That makes a
+disappearance impossible: an item either carries a close reason or it is still open, and both are
+visible. It also lets a later Hub see that something was closed *wrongly*, which a deletion hides
+forever.
+
+**ARTIFACT CONSERVATION — the same check, for the files you wrote.** The ledger check above catches
+an id that *disappeared*. Nothing caught a file that *exists and is invisible*, which is the inverted
+failure and just as silent:
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" hub-artifacts --reports .caddis/advisory-hub-reports
+```
+
+Exit 1 means you wrote a phase prompt the successor will never learn about. It will find no prompt,
+write a fresh one, and lose whatever reasoning yours carried — plausibly and completely. Name every
+prompt you authored in this spawn doc before handing over. (Degrades open: no handover yet, or no
+script, means proceed.)
+
+**CONSERVATION CHECK — mechanical, and it fails the spawn.** Every id in the predecessor's ledger
+must appear in the outgoing one as either still-open or closed-with-a-reason. An id that is simply
+absent is a silent loss: **stop and restore it before handing over.** Do not ask "did anything
+vanish?" — diff the ids. That is the same design move as the handoff audit, for the same reason.
+
+**One ledger, one home.** A verdict may *raise* an item, but it is not raised until it has an id in
+the context doc's ledger, in the same commit. Two uncoordinated lists drift, and the drift is
+invisible.
+
+Carry the whole list forward, closed items included. It is short, and its history is the cheapest
+audit trail this pattern has.
+
+## Step 4 — generate the prompt
+
+**"From the files, not from memory" is an instruction you cannot follow by intending to. Run the
+generator:**
+
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_inventory.py" --with-tests
+```
+(falls back to `scripts/caddis_inventory.py` in a source checkout; skip the step if absent — it
+degrades open like every other machine step here.)
+
+Paste its output into the prompt as a **Repository inventory** section, verbatim. 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. `--with-tests`
+runs the suite instead of reporting a remembered number — one handover claimed 20 tests when there
+were 19, and the incoming Hub found the discrepancy before anyone else.
+
+**Why a generator and not care.** Nine corrective round trips were needed to bring one Hub to a
+usable state, and the user caught six of the nine: no reports listed, no documents, no KB notes, no
+scripts, planned work absent, and confusion over which of two prompts actually existed. Every one of
+those is a directory listing. They were missed because an outgoing agent recalls *what it did*
+rather than enumerating *what exists* — and the incoming Hub cannot know what it was not told.
+
+Then write the judgement half yourself. It must contain:
+
+1. **The role and the one rule** — re-derive, do not trust; validate, do not implement.
+2. **The read order**: advisory context (all of it, especially the succession section and the
+   carried-open list) → the plan's milestones / execution protocol / tracker → the project's
+   measurement rules → the most recent 2–3 verdicts.
+3. **A context self-check the new Hub must answer BEFORE touching a phase**, from the files, including:
+   - re-derive **one anchor number live** (not quote it)
+   - name the decisions that are **accepted but reversible**, and what would reverse them
+   - state **where the next deploy gate is and how it determined that** (read the milestone table —
+     never state a deploy boundary from memory)
+   - name **one thing a green automated check does NOT prove**, with the example that taught it
+   - **verify the tree independently** — `git fetch`, count divergence, and `git status`/diff any dirty
+     file before treating it as authority
+4. **At least one question whose naive answer is WRONG.** This is the load-bearing part. A Hub that
+   only skimmed must fail *visibly* rather than silently.
+
+   > **USE A DIFFERENT TRAP THAN THE PREVIOUS HUB'S.** Check the last spawn prompt in
+   > `.caddis/advisory-hub-reports/` and pick a fresh one. A trap reused across generations stops
+   > testing comprehension and starts testing whether the new Hub read the old prompt — which it can
+   > pass while understanding nothing. Rotate it, and prefer a fact the *most recent* milestone
+   > established, since that is what the incoming Hub is least likely to have absorbed.
+
+   Good traps share a shape: a figure that looks obvious, a correct value that differs, and a reason
+   rooted in the data rather than in the code. On the reference project, one generation asked why the
+   funnel's `offered` is not `SUM(OfferedInd)` (naive 3,814, correct 4,783 — the raw flags do not
+   nest); the next asked why an abandonment rate moved from 7.6% to 5.9% (the old figure was not a
+   rate at all — 72% of its numerator sat outside its own denominator).
+5. **What is carried open — INLINE THE OPEN ITEMS VERBATIM, do not link to them.** (Closed items stay
+   in the context file for the audit trail; they do not belong in the prompt.) A pointer costs a file hop at
+   exactly the moment the new Hub has least context, and a carried-open item that is not read is
+   indistinguishable from one that was closed.
+6. **The next work**, with its batching (`Session: continue` = batchable, `fresh` = not) and any
+   standing constraint the new Hub would not otherwise know — a stalled upstream load, a deploy hold,
+   an environment that is mid-change.
+7. **The standing authorisations**: deploys are user-authorised **every time**; a previous yes does not
+   carry.
+8. **What comes after this, and why the order matters.** Not only what is done and what is carried
+   open — **what this is building towards**, for the next two or three phases. A Hub that does not
+   know what comes next can design the current phase in a way that blocks it, and it will never find
+   out, because nothing it can read says so. One live handover omitted a planned model comparison
+   entirely; the user caught it. A section covering only the past reads complete and is not.
+9. **The deliverable.** Name the thing this workstream must eventually produce, and the step that
+   produces it. One handover carried every phase faithfully and never mentioned the report that was
+   the whole point of the exercise. The user caught that too.
+10. **A standing instruction to maintain the tracker.** Put this in the prompt, in these words or
+    close to them:
+
+    > **Maintain the tracker.** Your in-session task list does not survive this session.
+    > `.caddis/relay.md` does. Mirror your working list into it as you go, and include its current
+    > state in every progress report. Anything not written there is lost.
+
+    The succession table records **who held the role**; `relay.md` records **where the work is**. The
+    table is written when a Hub *ends*, so nothing covers the hours while a Hub is *working* — which
+    is the whole period this mechanism exists to protect. A real spawned Hub read `relay.md`,
+    answered a thirteen-question context check correctly, found four genuine defects in its
+    handover, **and created no tracker at all**, because nothing asked it to.
+
+    Note for the incoming Hub: `relay.md` is gitignored and machine-local. Anything a successor **on
+    another machine** will need belongs in the advisory context or the next spawn prompt, not only
+    there.
+11. **`.caddis/kb/environment-map.md`, INLINE AND VERBATIM.** Hosts, which login works, where other
+    repositories actually live. It is short, it is the first thing an incoming Hub needs, and it is
+    the category most often missing — one incoming Hub searched the filesystem for a repository that
+    lived in Gitea, and the user had to stop it. A pointer is not enough here: this is exactly the
+    file a cold session does not know to open.
+
+**Write it to `.caddis/advisory-hub-reports/hub-NN.spawn.md`** (frontmatter `type: hub-spawn`,
+`hub: NN`), then print it. Until this file existed, every succession prompt lived and died in chat —
+which made two of this command's own instructions unimplementable: "rotate the trap by checking the
+last spawn prompt" had nothing to check, and the ledger conservation check below had nothing to diff
+against.
+
+Print the prompt in a fenced block, ready to paste. **Say plainly that it starts a NEW session** — a
+Hub spawned inside the outgoing session's context inherits exactly the staleness this whole mechanism
+exists to shed.
+
+### Check the prompt before you hand it over
+
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" handover-check \
+  --doc .caddis/advisory-hub-reports/hub-NN.spawn.md
+```
+
+It fails when the prompt names a file that does not exist. **Validate the DOCUMENT, not just the
+reader.** The context self-check in Step 4 proves the incoming Hub read carefully; it proves nothing
+about whether what it read was true. One incoming Hub passed a thirteen-question check on a handover
+containing four factual errors — it found them *despite* the check, not because of it.
+
+### The single-writer rule — state it in the prompt
+
+**The outgoing Hub stops writing to the repository the moment the succession prompt is issued.** Say
+so in the prompt itself, so both sides know which one owns the tree.
+
+This is not tidiness. Two sessions committed to one repository concurrently and the incoming Hub's
+work landed inside the outgoing Hub's commit. Only committed objects are safe from another session's
+checkout; a shared working tree is process-shared state, not session-private.
+
+## Step 5 — report
+
+Output: the audit result (candidates → gaps → where each landed), the succession table update, what is
+carried open, and the prompt. Then stop.
+
+**Do not begin validating the next phase.** You are the outgoing Hub; that work belongs to the session
+about to be spawned, and doing it here re-creates the context problem you just solved.
+
+---
+
+## Anti-patterns
+
+- **Spawning without the audit.** The prompt will look fine and quietly omit the session's best
+  technique.
+- **Writing the prompt from memory.** Build it from the files; memory is what is being discarded.
+- **Handing over a stale carried-open list.** An item that was closed hours ago and still appears
+  teaches the new Hub to distrust the whole list.
+- **Waiting until context is nearly gone.** The audit needs room. Spawn early and cheaply.
+- **Continuing to work after generating the prompt.** Two Hubs holding the role is worse than one.

package/bundles/antigravity-plugin/skills/validate-phase/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: validate-phase
+description: Advisory Hub phase validation — consume a phase report, RE-DERIVE its claims independently, and return ACCEPT / ACCEPT-WITH-CORRECTION / REJECT
+---
+
+# /caddis:validate-phase — the Advisory Hub validates a phase (never trusts it)
+
+> **THE RULE: re-derive, do not trust.** A phase report is a self-assessment. Reading it and nodding
+> makes you a rubber stamp, and a rubber stamp is worse than no check at all — it manufactures false
+> confidence. Every step below exists to prevent exactly that. Skipping the re-derivation is the one way
+> this command can fail at its actual job while still producing a plausible-looking verdict.
+
+Full methodology, templates, and rationale: the **`advisory-hub`** skill. This command is the thin,
+operational driver — run it after an implementing session (usually `/caddis:implement` in Advisory-Hub
+mode) has filed a phase report.
+
+## Step 0 — resolve inputs
+
+Use **$ARGUMENTS** if given. Otherwise, find the newest `phase-*.report.md` file in
+`.caddis/advisory-hub-reports/` that has no matching `phase-NN.verdict.md` sibling yet — that is the
+one awaiting validation. Read its `PLAN:` and `ADVISORY CTX:` header fields and load both files.
+
+**If no `<slug>-advisory-context.md` exists** for the plan named in the report: say so explicitly, offer
+to bootstrap one from the `advisory-hub` skill's §A template, and continue in **degraded mode** — state in
+the verdict exactly which checks (§4 locked-decision adjudication, §5 safety-rule re-check) were
+unavailable without it. Never silently skip a check without recording that you skipped it.
+
+**A degraded verdict must be machine-distinguishable, not just annotated in prose.** Write
+`verdict: accept-degraded` (not plain `accept`) in the frontmatter. `/caddis:implement` reads only the
+`verdict:` field to decide whether the next phase may start, so a degraded accept spelled `accept` is
+indistinguishable from a full one — the gate cannot tell a partial check from a real one, which is
+precisely the false confidence this whole pattern exists to prevent. Use `reject-degraded` likewise if
+you are rejecting without the context doc.
+
+## Step 1 — read the report once as a document
+
+Before validating a single claim, check the report against itself: does CROSS-REVIEW agree with
+DEVIATIONS? Does MODEL/LANE name a vendor's model that doesn't match the claimed lane? On the reference
+run this pattern's design was validated against, two of three real findings in one phase came from
+exactly this kind of internal contradiction — not from re-checking the code.
+
+## Step 2 — re-derive (the Hub validation checklist)
+
+Run every item in the `advisory-hub` skill's §D checklist yourself:
+1. Re-derive every VALUE CHECK using the method advisory-context §3a names — actually run it, don't read
+   the reported result.
+2. Re-run the exit gates, at minimum the fast ones (unit tests, lint, type-check).
+3. `git log` / `git show --stat` the commits — do they match the phase's claimed touches? Anything
+   unexpected, especially tooling/config/CI that never appeared in DEVIATIONS?
+4. Re-check every rule in advisory-context §5, or record `N/A — none declared`.
+5. Flag any deviation that touches a §4 locked decision — this is step 3 below, not your call to make here.
+6. Flag any surprise that contradicts the plan's `## Current state` — this is step 4 below.
+7. If this milestone boundary ships to a real deployed environment, smoke-test it there, not in dev.
+
+Also apply the `advisory-hub` skill's §E techniques where they fit — mutation-test any seam a new test
+claims to prove, and if a cross-review provider timed out, try the other configured provider before
+recording "inconclusive."
+
+## Step 3 — adjudicate deviations
+
+For each deviation the report lists: is it a locked decision in advisory-context §4? If so, this is a
+**Hub decision, never the implementer's** — rule allowed / reverted / plan amended, and record the reason.
+
+## Step 4 — plan drift
+
+If the report's SURPRISES / CONTRADICTIONS section is non-empty: correct the plan file's
+`## Current state` **now, in this step** — do not defer it to a note in the verdict. This is the Hub's
+job and the step most likely to be skipped (`advisory-hub` skill §F).
+
+## Step 5 — write the verdict
+
+Write `.caddis/advisory-hub-reports/phase-NN.verdict.md` beside the report, using the `advisory-hub`
+skill's §C template in full, including the mandatory **WHAT IS NOW STRUCTURAL** table.
+
+> **Give it OKF frontmatter — `type` is REQUIRED and its absence is a defect.**
+> Keep it flat (scalar `key: value` only; nested maps and lists defeat simple parsers):
+> ```yaml
+> ---
+> type: phase-verdict
+> plan: <path to the plan>
+> phase: 12          # or 10-11 for a batched pair
+> milestone: M4
+> verdict: accept | accept-with-correction | reject
+> ---
+> ```
+> `verdict` is the one field a tool can read to answer *"was this phase signed off"* without parsing prose — and a prose scraper gets that wrong quietly.
+
+
+## Step 6 — push every correction into `advisory-context.md`
+
+A correction that lives only in this verdict file dies with the session that reads it; a correction told
+to the implementing session dies with that session too, which has already closed. Every correction in
+"WHAT IS NOW STRUCTURAL" must actually be landed in the named section of `advisory-context.md` in this
+step, not just described.
+
+## Step 7 — update the reports-directory index
+
+Add or update this phase's row in `.caddis/advisory-hub-reports/README.md` (Phase | Report | Verdict |
+Outcome | Date).
+
+## Rules
+
+- **Fail closed.** A gate you could not re-run is `NOT RE-RUN`, never `PASS`. A claim you could not
+  reproduce is `UNVERIFIABLE`, never `AGREES: YES`.
+- **Never accept a claim on the report's own word.** That is the one failure mode this command exists to
+  prevent.
+- If a cross-review provider times out, try the other configured provider before recording
+  "inconclusive" — a single provider's outage is not grounds for skipping independent review.
+- **The Hub is not exempt from its own contract.** If a fault traces back to advice the Hub itself gave
+  earlier, the verdict says so plainly rather than attributing it to the implementer.
+- Read-only toward the implementing session — it has already closed. Corrections land in files
+  (`advisory-context.md`, the plan), never fed back to a session that no longer exists.

package/bundles/antigravity-plugin/skills/writing-plans/SKILL.md

@@ -16,7 +16,10 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Context:** This should be run in a dedicated worktree (created by brainstorming skill).
 
-**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+> **Prefer `/caddis:feature-plan`.** It is the canonical planning entry point and produces a plan
+> the harness can resume, track and gate. This skill remains for free-form planning prose.
+
+**Save plans to:** `.caddis/plans/YYYY-MM-DD-<feature-name>.md`
 
 **Document metadata:** Before creating or updating a plan, apply `.github/instructions/document-frontmatter.instructions.md`. The YAML frontmatter block must be the first content in the file. New plans require `Original Author`, `Creation Date`, and `Creating Model`; revised plans must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
 
@@ -215,7 +218,7 @@ The "Current State" column tells agents what exists and whether to modify or lea
 
 - `path/to/file.ext` — {why this file is needed}
 - `path/to/file.ext` (from Phase N-1)
-- `.github/plans/{this-plan}.md` (this file)
+- `.caddis/plans/{this-plan}.md` (this file)
 
 ### Phase Prompt
 
@@ -333,7 +336,7 @@ Walk through every FR, NFR, risk, and design decision from ALL input documents.
 **Agent context:** You are the `@{agent-name}` agent. Load `.github/project-config.md` before starting.
 
 **Read these files FIRST (in order):**
-1. `.github/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
+1. `.caddis/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
 2. {Architecture/PRD doc} — {specific sections}
 3. {Target file(s)} — current state
 
@@ -370,7 +373,7 @@ Walk through every FR, NFR, risk, and design decision from ALL input documents.
 
 After saving the plan, offer execution choice:
 
-**"Plan complete and saved to `.github/plans/<filename>.md`. Two execution options:**
+**"Plan complete and saved to `.caddis/plans/<filename>.md`. Two execution options:**
 
 **1. This session** — I implement each task sequentially, reviewing between tasks
 

package/bundles/antigravity-plugin/warm_start_agy.py

@@ -2,7 +2,10 @@
 """caddis warm-start hook for agy (Antigravity) — PreInvocation event.
 
 Ports the relay half of claude-harness/hooks/inject_relay.py. agy has NO SessionStart event, so the
-nearest equivalent is PreInvocation with `invocationNum == 1` — the first model turn of a session.
+nearest equivalent is PreInvocation with `invocationNum == 0` — the first model turn of a session.
+**agy's invocations are 0-indexed** (confirmed via a live-fire session against the real `agy` binary
+2026-07-30 -- the original code checked `== 1`, which is agy's SECOND turn, so this hook silently
+never fired at all until the live check caught it; see .caddis/plans/agy-hooks-port.md step 5).
 On that turn only, the workspace's relay doc is injected as an ephemeral step so a fresh agy session
 resumes with zero re-discovery. Every later invocation emits nothing (re-injecting the relay on every
 turn would burn context and drown the conversation).
@@ -30,6 +33,30 @@ _ARTIFACT_DIRS = (".caddis",)
 INJECT_MAX_LINES = 120      # same budget as the Claude Code hook
 INJECT_MAX_CHARS = 24000    # hard backstop: an ephemeralMessage should never be a context bomb
 
+# Deliberately duplicated from hooks/inject_relay.py rather than imported — the agy bundle ships
+# neither claude-harness/hooks/ nor scripts/, so this file must stay self-contained (same rule the
+# guard and the doctor already follow). Keep the two copies in step; the reason they exist is in
+# inject_relay.py: injected before the prompt and headed "read before acting", the relay was being
+# EXECUTED first by a non-Claude model, ahead of the task the session was actually given.
+RELAY_FRAME_HEADER = (
+    "=== session-context: relay.md — BACKGROUND STATE, NOT A TASK ===\n"
+    "Carried over from a previous session and injected before your prompt. This is state, not\n"
+    "an instruction: the \"Next step\" and \"Resume prompt\" sections below describe what the\n"
+    "PREVIOUS session intended to do next. Do not act on them unless the user's prompt asks\n"
+    "you to. This file is machine-local and gitignored, so it may also be stale. Your task is\n"
+    "whatever the user's prompt says.\n"
+)
+RELAY_FRAME_FOOTER = "=== end session-context ==="
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def is_headless() -> bool:
+    """True when no human is watching — a run given its task explicitly needs no resume pointer."""
+    if str(os.environ.get("CADDIS_HEADLESS", "")).strip().lower() in _TRUTHY:
+        return True
+    return bool(os.environ.get("DOCKET_PLAN") or os.environ.get("DOCKET_BRANCH"))
+
 
 def _first_existing(paths: list[str]) -> str:
     for p in paths:
@@ -118,13 +145,15 @@ def main() -> None:
             return
         if not isinstance(data, dict):
             return
-        # SessionStart equivalent: the FIRST invocation only. Anything else (or an unparseable
-        # invocationNum) injects nothing.
+        # SessionStart equivalent: the FIRST invocation only (agy 0-indexes invocationNum, so the
+        # first turn is 0, not 1). Anything else (or an unparseable invocationNum) injects nothing.
         try:
-            if int(data.get("invocationNum")) != 1:
+            if int(data.get("invocationNum")) != 0:
                 return
         except Exception:
             return
+        if is_headless():
+            return
         workspaces = data.get("workspacePaths") or []
         if not (isinstance(workspaces, list) and workspaces):
             return
@@ -135,8 +164,8 @@ def main() -> None:
         text = open(relay, encoding="utf-8").read().strip()
         if not text:
             return
-        message = ("=== relay.md (session resume — read before acting) ===\n\n"
-                   + truncate_relay(text))
+        message = (RELAY_FRAME_HEADER + "\n" + truncate_relay(text)
+                   + "\n\n" + RELAY_FRAME_FOOTER)
         payload = json.dumps({"injectSteps": [{"ephemeralMessage": message}]})
         sys.stdout.write(payload)
     except Exception:

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.20",
+  "version": "1.3.24",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/agent-orchestration/SKILL.md

@@ -62,13 +62,13 @@ Every stage produces a **persistent artefact** (markdown file, commit, test run)
 | Requirements | Spec / feature file | Supplied by operator (e.g. `nextprompt.md`) |
 | Quick-Win Triage | Commit with passing tests | Git history |
 | Architecture | ADR (Architecture Decision Record) | Inside the plan document |
-| Planning | Plan document (phases, steps, files) | `.github/plans/<feature>.md` |
+| Planning | Plan document (phases, steps, files) | `.caddis/plans/<feature>.md` |
 | Fidelity Audit | Gap table (0 gaps = pass) | Inside the plan document |
 | Risk Assessment | Risk register (scored risks) | Inside the plan document |
 | Implementation Prompts | Embedded copy-paste prompts | Inside the plan document |
 | Implementation | Code + tests per phase | Git commits per phase |
 | Code Review | Review report | Chat session or plan annotation |
-| Debug / Polish | Fix-up plan (issues A–N) | `.github/plans/<feature>-fixup.md` |
+| Debug / Polish | Fix-up plan (issues A–N) | `.caddis/plans/<feature>-fixup.md` |
 
 ---
 
@@ -181,7 +181,7 @@ Spec Input
    - What to change (specific enough to implement without guessing)
    - Expected test additions
    - Verification command
-4. Place plan in `.github/plans/<feature-name>.md`
+4. Place plan in `.caddis/plans/<feature-name>.md`
 
 #### 2b. Fidelity Audit
 After authoring, audit the plan against the spec:
@@ -265,7 +265,7 @@ Score each identified risk:
 1. Start a **new chat session** (clean context)
 2. Provide the phase prompt:
    ```
-   Read .github/plans/<feature>.md and implement Phase N.
+   Read .caddis/plans/<feature>.md and implement Phase N.
    Run pytest after every file change. All tests must pass before commit.
    ```
 3. Implement Agent reads the plan, executes numbered steps
@@ -285,7 +285,7 @@ The plan document should contain **copy-paste prompts** for each phase. This rem
 ```markdown
 ### Phase 2 Prompt (copy into new chat)
 
-> Read `.github/plans/my-feature.md`, specifically Phase 2 (steps 5–9).
+> Read `.caddis/plans/my-feature.md`, specifically Phase 2 (steps 5–9).
 > Implement each step in order. Run `pytest tests/ -x -q` after each file edit.
 > When all steps pass, commit with message:
 > `feat(cards): phase 2 — insight card refactoring`
@@ -338,7 +338,7 @@ The plan document should contain **copy-paste prompts** for each phase. This rem
    - Root cause
    - Proposed fix (specific enough to implement)
    - Acceptance criteria
-3. **Write fix-up plan** — Place in `.github/plans/<feature>-fixup.md`
+3. **Write fix-up plan** — Place in `.caddis/plans/<feature>-fixup.md`
 4. **Execute** — Implement Agent works through issues sequentially
 5. **Verify** — Run full test suite + visual inspection
 6. **Commit** — `fix(<scope>): post-track cross-component polish`
@@ -562,7 +562,7 @@ Load .github/skills/workflow/agent-orchestration/SKILL.md for the methodology."
 ```
 Operator opens new chat:
 
-"Read .github/plans/<feature>.md and implement Phase N.
+"Read .caddis/plans/<feature>.md and implement Phase N.
 Run pytest after each file change. Commit when all tests pass.
 Use message: feat(<scope>): phase N — <summary>"
 ```
@@ -575,7 +575,7 @@ Operator opens new chat:
 "All implementation phases for <feature> are complete.
 Audit all changed files for cross-component issues.
 Catalogue each issue (A–N) with root cause, fix, and acceptance criteria.
-Write the fix-up plan to .github/plans/<feature>-fixup.md"
+Write the fix-up plan to .caddis/plans/<feature>-fixup.md"
 ```
 
 ### Absorbing Mid-Flight Changes
@@ -584,7 +584,7 @@ Write the fix-up plan to .github/plans/<feature>-fixup.md"
 Operator opens new chat:
 
 "I independently added <change> to <file(s)>.
-Read .github/plans/<feature>.md and update it to absorb this change.
+Read .caddis/plans/<feature>.md and update it to absorb this change.
 Trace every affected step, update embedded prompts, re-verify fidelity."
 ```