@caddis/cli 0.2.3 → 0.2.5

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

@@ -43,11 +43,115 @@ folder you will touch (the canonical rules; `CLAUDE.md` is an `@AGENTS.md` shim)
 `.caddis/PROJECT-FACTS.md` if present (for the real run/test commands) —
 **read it, never edit it**. Identify the test command the plan/facts specify so you can run it yourself.
 
+**Run the machine gates first — they decide, not your reading of the prose below.**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" lane-check    --plan <plan> --phase <N>
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" verdict-gate  --plan <plan> --phase <N>
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" tracker-vs-git --plan <plan>
+```
+
+Obey the exit code: **0** proceed · **1** STOP and report why · **2** proceed but record the note it
+printed · **3** wrong lane — the launch command is on stdout, spawn it · **4** the launch command is
+malformed, do not run it.
+
+**If the script is missing, proceed** — it degrades open by design, and an older install or a
+plugin-only consumer must not be blocked by a gate it does not have. The prose below is the same
+contract in words, and remains the fallback.
+
+**Check the phase's `Lane:` before implementing anything.** The plan assigns every phase an
+execution lane, and until now nothing read it: on one 14-phase plan, Phases 1 and 2 were both
+assigned `glm-headless` and both ran on `claude`, silently, twice in a row — the plan advertised a
+cheap lane for 4 of 14 phases that executed nothing, and every cost assumption resting on it was
+quietly false. **The `Lane:` line is a routing directive, not a note.**
+
+You cannot always prove your own lane, but you can detect a known mismatch — a Claude session
+looking at `Lane: glm-headless`. Apply this **asymmetrically: act on a known mismatch, proceed when
+unsure.** On a known mismatch:
+
+- **Interactive session (no `CADDIS_HEADLESS`, no `DOCKET_PLAN`/`DOCKET_BRANCH` in the environment)
+  → spawn the assigned lane.** Run the phase's literal launch command yourself — e.g.
+  `claude-glm -p "/caddis:implement <plan> — Phase N only"` — wait for it, then verify it (below).
+  On Windows `claude-glm` is `claude-glm.ps1` and resolves only on the **PowerShell** PATH; a
+  Bash `command -v claude-glm` returns nothing and looks like "not installed", which it is not.
+  If the spawn fails for any reason, implement the phase here and record the deviation (below) —
+  a failed spawn must never silently become a skipped phase.
+  > **First, check the launch command carries `-p` or `--print`. If it does not, REFUSE to run it**
+  > — report the malformed command and implement here instead. The launchers set `CADDIS_HEADLESS`
+  > *only* on `-p`/`--print`, and that variable is the entire loop guard. A launch command missing
+  > it spawns a session that is not marked headless, which reads this same `Lane:` line and spawns
+  > again — unbounded recursion. Without `-p` the command also opens an interactive session, so the
+  > parent waits forever on a child that is sitting at a prompt.
+- **Headless or docket-runner session → never spawn. Implement here and record the deviation.**
+  You may already *be* the spawned lane, and a session that spawns its own lane on every start is
+  an infinite loop. The env markers above are the guard: if either is set, someone else placed you.
+
+**After the spawn, verify it — do not assume.** Re-read the plan's Tracker row for that phase and
+confirm the status and commit hash the child claims to have written. "Wait for it and report" checks
+nothing: a mistyped plan path in the launch command silently implements a *different plan* while you
+move on. If the row is unchanged, treat the phase as **not done** and say so.
+
+**If your arguments carry a phase restriction — `— Phase N only` — implement exactly that phase and
+stop**, then emit the final JSON block. Every launch command this system generates ends that way, and
+nothing used to honour it: a child spawned for phase 2 of 14 would run phases 2 *through 14*, pulling
+later `claude`-lane and security-sensitive phases onto the cheap model. That is the precise inverse of
+the bug the lane routing exists to fix.
+
+**Record the lane you actually ran on in the Tracker's `Lane` column** — the lane you ran, never the
+lane the plan planned. A deviation then shows up as a diff between the phase block and the tracker
+row, visible to any later reader without an Advisory Hub having to catch it live.
+
+**Advisory-Hub mode (conditional — OFF by default).** Check whether a companion file
+`<plan-dir>/<plan-stem>-advisory-context.md` exists (e.g. plan `.caddis/plans/foo.md` → look for
+`.caddis/plans/foo-advisory-context.md`). **If it does not exist — the normal case, including every
+docket run — Advisory-Hub mode is OFF and nothing else in this command changes.** If it exists, read it
+and set Advisory-Hub mode ON for this run: it names locked decisions you may not change unilaterally,
+this project's declared safety conventions, and how to re-derive the plan's anchor numbers. See the
+`advisory-hub` skill for the full contract.
+
+**In Advisory-Hub mode, the previous phase's VERDICT gates this one.** Before starting phase N, require
+a verdict in `.caddis/advisory-hub-reports/` that satisfies **all three** of:
+
+1. **It covers phase N-1.** Usually `phase-(N-1).verdict.md`, but a **batched** verdict counts: a file
+   whose `phase:` is a range — `phase-10-11.verdict.md`, `phase: 10-11` — satisfies the gate for every
+   phase the range **covers**. Batched pairs are normal, not exotic: one live plan alone carries
+   `phase-05-06`, `08-09`, `10-11` and `13-14`. A literal `phase-(N-1)` lookup sends phase 12 hunting
+   for a `phase-11.verdict.md` that will never exist, and falsely blocks a properly validated plan.
+2. **It belongs to the plan you are implementing.** The report directory is flat and shared, so with two
+   hub-mode plans in one repo, plan A's `phase-02.verdict.md` would otherwise satisfy plan B's phase-3
+   gate. Match the verdict's identity field against the plan. **Accept either `plan:` (a path) or
+   `feature:` (a slug) — both are in live fleet use** and neither is wrong; one project's verdicts carry
+   one, another's carry the other. If a verdict carries neither, treat its identity as unproven: say so
+   and do not let it gate anything.
+3. **It carries `verdict: accept` or `verdict: accept-with-correction`.**
+
+- **Missing** → the Hub has not validated it yet. **STOP.** Mark the Tracker row
+  `blocked-pending-hub` and say which verdict you are waiting on.
+- **`verdict: reject`** → **STOP.** The phase is to be redone, not built upon.
+- **`verdict: accept-degraded`** → the Hub validated it **without an advisory context**, so the
+  locked-decision and safety-rule re-checks never ran. It is a partial check wearing an accept. Proceed
+  only if the phase is low-stakes, and **say in your report that you did so on a degraded verdict**.
+- Phase 1 (or the first phase of the plan) has no predecessor — proceed.
+
+This is the Hub's central power and until now it ran on human discipline alone: the verdict recorded
+whether the next phase could start, and *nothing read it*. Five lines of check make the claim true by
+machine.
+
+**If a `phase-NN.prompt.md` exists for the phase you are about to run, it is the INSTRUCTION OF
+RECORD** — read it, and measure your DEVIATIONS against it, not against the plan alone. The Hub writes
+that file before the phase precisely so a deviation is falsifiable; an executor that never reads it
+undermines the whole argument.
+
 **2. Determine where to resume.** The `## Tracker` table is the resume signal. Start at the first phase whose
 status is not `done`/`✅`. If every phase is already done, verify the tests are green and go straight to the
 report — do not redo completed work.
 
 **3. Implement each remaining phase, TDD-first.** For each phase, in order:
+   - **LANE** — **re-check this phase's `Lane:` and apply Step 1's spawn/record rule to it.** Do this
+     first, every phase, not just the one you resumed at. Step 1's check only ever saw the *resume*
+     phase: on a plan whose phase 1 is `claude` and phase 2 is `glm-headless`, it finds no mismatch and
+     this loop then carries you straight through phase 2 — so the lane silently executes nothing for
+     every phase after the first, which is the original bug wearing a different hat.
    - **RED** — write the failing test(s) the phase names (`<test file>::<case>`). Run them; confirm they
      fail for the right reason (the missing behavior, not an import error). If a phase genuinely has no
      testable surface, say so in the review file and implement the minimal change directly.
@@ -59,19 +163,91 @@ report — do not redo completed work.
    - **COMMIT** — `git add` the phase's files and `git commit` with the phase's conventional-commit message
      (from the plan, or a faithful equivalent). Stay on the current branch.
    - **UPDATE THE TRACKER** — edit the plan's `## Tracker` row for this phase: set Status to `done`, fill
-     the short commit hash (`git rev-parse --short HEAD`) and a one-line note. This is what lets a future
-     session (or the runner) see progress. Commit the Tracker update with the phase (or as a tiny follow-up
-     commit) — it lives in the plan file, which is fine to commit on this branch.
+     the short commit hash (`git rev-parse --short HEAD`), set the `Lane` column to the lane this phase
+     ACTUALLY ran on (not the planned one — see Step 1), and add a one-line note. This is what lets a
+     future session (or the runner) see progress. Commit the Tracker update with the phase (or as a tiny
+     follow-up commit) — it lives in the plan file, which is fine to commit on this branch.
+   - **FILE THE PHASE REPORT — Advisory-Hub mode only.** *Skip this bullet entirely if Step 1 found no
+     `<slug>-advisory-context.md`.* Write `.caddis/advisory-hub-reports/phase-NN.report.md` (zero-padded
+     phase number; create the directory and add a `README.md` index row if absent — and when you
+     create `.caddis/advisory-hub-reports/` for the first time, also write an **`AGENTS.md`** there
+     carrying the naming, frontmatter and role rules from the `advisory-hub` skill, so they bind every
+     agent that writes to that directory including ones that never loaded the skill. The skill claims
+     this file ships; nothing ever created it, so it exists only where a Hub hand-wrote one.
+     **Never overwrite an existing `AGENTS.md`** — the hand-written ones in the fleet are the good
+     copies) using the
+     `advisory-hub` skill's report contract. Verbatim means verbatim — paste real terminal output, never
+     reconstruct it. Report the model/lane you actually ran on. Report every commit, including tooling and
+     config. `git add` the report file with this phase's commit. **If the report's SURPRISES /
+     CONTRADICTIONS section is non-empty, stop after this phase** — mark the Tracker row
+     `blocked-pending-hub`, leave later phases untouched, and let the Hub correct the plan; that is not
+     your call to make here.
+
+> **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-report
+> plan: <path to the plan>
+> phase: 12          # or 10-11 for a batched pair
+> milestone: M4
+> ---
+> ```
+
 
    If a phase cannot be completed (a blocking gap the plan did not resolve, or a rule above would be
    violated), **stop there**: leave later phases untouched, record the blocker in the review file, mark the
    Tracker row `blocked`, and report honestly with `"tests":"failed"` — never fake completion.
 
+**3b. Halt only at a boundary.** Implement phase after phase, committing each. Stop for exactly four
+reasons — a **milestone boundary**, a phase marked `Session: fresh`, **after** a `risk: high` phase,
+or a **failed/blocked** phase. A lane change is not one of them: you spawn the lane yourself (Step 1).
+
+The `risk: high` halt is deliberately *after*, not before. Execute and commit the phase normally; the
+halt exists to stop the **next** phase building on it before a human has looked, so the blast radius
+stays one reviewable, revertable commit.
+
+**At every halt, PERFORM the handoff yourself, now, before you stop.** Write `relay.md` and update
+the Tracker in this session — you are the only party holding the context that makes them worth
+anything, and it evaporates the moment you stop.
+
+**Do NOT emit "run `/caddis:handoff`", "do a handoff", or "update the relay" as a next action.**
+Naming the command instead of doing the work is the single most common way this step is skipped: the
+session ends, the user runs `/clear`, and the durable record that should have been written never is.
+`/caddis:handoff` is the same procedure a human may invoke *between* sessions; **at a halt, you are
+the one performing it.** The only next action you hand back is the resume line in the halt block.
+
+Then print the halt block as your **last output before the JSON**, so the human has one action rather
+than an archaeology job:
+
+```
+=== HALT — <one-line reason> ===
+Done:    phases <a>-<b> (<milestone>) · commits <sha>, <sha>
+Blocked: <what, or "nothing">
+You:     /clear, then paste ↓
+         read <plan path> and implement Phase <next>
+```
+
+**In headless/runner mode, never ask — halt, write the block, and exit.** The block is how a
+non-interactive run tells a human what it needs; asking is still forbidden.
+
 **4. Run the tests yourself.** After the last phase you complete, run the project's full test command once
 more and record the real result. The runner will re-run it independently and that decides success — but
 you run it too so your reported `"tests"` value is truthful, not assumed. Never report `"passed"` on a
 suite you did not see go green.
 
+**4b. If every phase is now done, tidy the plan into `done/`.** Only when the whole plan is
+finished (every `## Tracker` row is `done`, no halt, no blocker) — a mid-plan halt is not this.
+Flip the plan's own frontmatter `status:` to `done` (your judgment call: only if the Tracker
+genuinely backs it up), commit that with the final phase, then run:
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply
+```
+(falls back to `scripts/caddis_tidy.py` from a source checkout; **skip this step if the script is
+missing** — degrades open, same as the gates in Step 1). A **collision**
+(`done/<name>` already exists) is reported by the script, not fatal — note it in the review file,
+do not fail the run over it.
+
 **5. Write a concise review file** to the path in the `DOCKET_REVIEW` env var (falls back to
 `.caddis/reviews/<slug>.md`, where `<slug>` is `DOCKET_SLUG`). Create `.caddis/reviews/` if needed.
 Keep it short and scannable — this is what the human reviewer reads before merging the branch:
@@ -108,6 +284,9 @@ showed; `review` is the review-file path you wrote:
 {"implemented":true,"phases_done":<int>,"tests":"passed|failed","review":".caddis/reviews/<slug>.md"}
 ```
 
+(In Advisory-Hub mode, the phase report from Step 3 is a **file**, written per phase — this JSON block
+remains the one and only final output of the whole run, in every mode, unchanged.)
+
 If you had to stop before implementing anything (e.g. you were on the default branch, or the plan was
 unreadable), still end with the block using `"implemented":false,"phases_done":0,"tests":"failed"` and put
 the reason in the review file. The only acceptable final output is the code + commits + review file + this

package/bundles/antigravity-plugin/skills/mermaid-diagrams/SKILL.md

@@ -199,14 +199,70 @@ flowchart LR
 
 1. **Start simple** - Core elements first, add details incrementally
 2. **One concept per diagram** - Split complex views into focused diagrams
-3. **Use clear labels** - Meaningful names make diagrams self-documenting
+3. **Use clear labels, but SHORT ones** - see *Label length* below. Meaningful names make diagrams
+   self-documenting; long ones get silently clipped, and a clipped label is worse than a terse one
+   because the reader cannot tell text is missing
 4. **Comment extensively** - Use `%%` to explain complex parts
 5. **Validate syntax** - Test at [mermaid.live](https://mermaid.live) before committing
 6. **Version control** - Store `.mmd` files with code
 7. **Keep updated** - Update diagrams when code changes
 
+## Label length — text is CLIPPED, not wrapped, and nothing warns you
+
+**The most common defect in a generated diagram, and it is invisible to the author.** Mermaid does
+not error, the diagram renders, and the text is simply cut off mid-word. Two distinct causes:
+
+**1. A long unbroken token in a node label cannot wrap.** Mermaid wraps node text at *spaces* only.
+`GenesysConversationTranscripts` is 30 characters with no space in it, so there is no break
+opportunity — it overflows the box and is clipped to `GenesysConversationTransc…`. Identifiers,
+table names, class names and file paths are all this shape.
+
+**2. Edge labels never wrap at all.** `A -->|"E2 · no index on ConversationStart"| B` renders on one
+line at any length, clipping or overlapping neighbouring nodes.
+
+**Rules:**
+
+- **Keep any unbroken token to ~20 characters.** Break longer ones explicitly with `<br/>`:
+  `["GenesysConversation<br/>Transcripts"]`.
+- **Keep each `<br/>`-separated line to ~25 characters.**
+- **Never put a sentence on an edge.** Edge labels get a short id or one word — `|"B2"|`, `|"reads"|`.
+  If it needs explaining, explain it in prose or a table beside the diagram.
+- **Prefer a short display name plus a lookup table** over cramming full identifiers into nodes:
+
+  ```mermaid
+  flowchart TD
+      B["Voice<br/>transcripts"] --> APP["dashboard"]
+  ```
+
+  | short name | actual table |
+  |---|---|
+  | Voice transcripts | `dbo.GenesysConversationTranscripts` |
+
+**Check it mechanically before shipping** — cheaper than rendering, and catches both causes:
+
+```bash
+python -c "
+import re,sys
+body=re.search(r'\`\`\`mermaid(.*?)\`\`\`',open(sys.argv[1],encoding='utf-8').read(),re.S).group(1)
+for e in re.findall(r'\|\"?([^\"|]+)\"?\|',body):
+    if len(e)>15: print(f'EDGE LABEL {len(e)} chars (never wraps): {e}')
+for lbl in re.findall(r'\[\"(.*?)\"\]',body):
+    for line in lbl.split('<br/>'):
+        t=max((len(w) for w in line.split()),default=0)
+        if t>20: print(f'LONG TOKEN {t} chars (cannot wrap): {line}')
+print('checked')
+" FILE.md
+```
+
+**Rendering to look at it is better still** — but only if you actually open the image. A diagram that
+renders without error is not a diagram that reads correctly, which is the same trap as a passing
+test that asserts nothing.
+
 ## Common Issues
 
+**Text is cut off mid-word:** see *Label length* above — the label is too long to wrap. This does
+not produce an error.
+
 **Diagram won't render:**
 - Check for typos in diagram type declaration
 - Validate syntax at [mermaid.live](https://mermaid.live)

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

@@ -0,0 +1,126 @@
+---
+name: park
+description: File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open
+---
+
+# /caddis:park — put future work in the ONE place it belongs
+
+Everything we will do later lives in `.caddis/parking-lot/`, one item per file. This command is the
+only sanctioned way to add to it. Use it whenever work is identified but deliberately not done now:
+a defect you are not fixing, a proposal, a plan you are parking, an idea worth keeping.
+
+**Why a command and not just a convention.** Parking-lot item `002` records an agent that hand-wrote
+a hub artifact into the wrong directory while the correct path sat unread on line 188 of the command
+it never invoked. A documented convention that nothing enforces gets bypassed by the next agent in a
+hurry. This command plus the `caddis_gate.py parking-lot` gate is the fix.
+
+The request is **$ARGUMENTS**.
+
+## Mode select
+
+| `$ARGUMENTS` | Do this |
+|---|---|
+| empty or `list` | Go to **List mode** |
+| `done <slug>` or `drop <slug>` | Go to **Close mode** |
+| anything else | Go to **File mode** — the text is what to park |
+
+---
+
+## File mode
+
+### Step 1 — check it belongs here
+
+Park it only if it is work **we** will do later. Redirect these instead, and say which you chose:
+
+| If it is | Send it to |
+|---|---|
+| Being worked on right now | `.caddis/plans/<feature>.md` |
+| An interrupted task you will come back to this session | `/caddis:digress` |
+| Blocked on a person outside this repo | `.caddis/comms/` + its `register.md` |
+| A card on the docket board | the board. **Never hand-edit `.caddis/backlog/`** — docket writes it |
+| A fact about the environment, not a task | the KB (`/caddis:kb`) |
+
+### Step 2 — do not duplicate
+
+List `.caddis/parking-lot/*.md` and read the title line of each. If this item already exists, **update
+that file** — add the new evidence and refresh `Last Updated` — and stop. Say which file you updated.
+
+### Step 3 — write the file
+
+Path: `.caddis/parking-lot/<short-slug>.md`. Slug only, **no number prefix**: two sessions filing at
+the same time would both pick the same number.
+
+```markdown
+---
+type: parking-lot
+status: open
+future: <yes if we have committed to it; omit or `no` if it is a candidate>
+severity: <high | medium | low>
+found: <YYYY-MM-DD>
+found-by: <repo / session / who reported it>
+Creating Model: <your exact model id>
+---
+
+# <One line that states the problem, not the solution>
+
+## What happened
+The evidence. What was observed, where, with the actual output, path, or number.
+
+## What it costs
+Who or what is affected, and what goes wrong if this is never done. An item with no cost
+stated is an item nobody will ever prioritise.
+
+## Suggested fix
+The smallest change that would remove the cause. Say if it is uncertain.
+```
+
+Rules the gate enforces — get them right the first time:
+
+- `type:` is always `parking-lot`, whatever the item started life as.
+- `status:` is one of `open`, `doing`, `done`, `dropped`. Nothing else. Not `wip`, not `todo`.
+- `future:` if present is exactly `yes` or `no`. It is a **separate axis** from `status`: an item can
+  be `status: open` and `future: yes`, meaning agreed but not started.
+- Keep the file under **20 KB**. Over that it is a register, not an item, and the gate fails it.
+- Set `severity` to something an outsider could check, not to how annoying it was.
+
+### Step 4 — verify
+
+Run the gate and show the result:
+
+```bash
+python scripts/caddis_gate.py parking-lot --repo-root .
+```
+
+Exit 0 means it conforms. Exit 1 means fix what it printed, then re-run. Do not report the item as
+filed until this passes.
+
+### Step 5 — report
+
+One line: the path, the severity, and whether `future: yes` was set. Nothing else.
+
+---
+
+## List mode
+
+Read every `.caddis/parking-lot/*.md` (skip `README.md` and `done/`). Print one table, sorted by
+`future: yes` first, then severity high → low:
+
+| Item | Severity | Future | Status | One-line summary |
+|---|---|---|---|---|
+
+Below the table, print the counts: how many open, how many committed (`future: yes`). Then run
+`python scripts/caddis_gate.py parking-lot --repo-root .` and report any violation it prints.
+
+If the directory is empty, say so in one line. Do not invent items.
+
+---
+
+## Close mode
+
+1. Find `.caddis/parking-lot/<slug>.md`. If there is no exact match, list the near matches and stop.
+2. Set `status: done` (finished) or `status: dropped` (deliberately abandoned).
+3. **For `dropped`, append a `## Why dropped` section.** This is not optional. An item deleted with
+   no reason gets re-raised by the next session that has the same idea; an item kept with "no,
+   because ..." does not.
+4. Run `python scripts/caddis_tidy.py --apply`, which moves it into `.caddis/parking-lot/done/`.
+5. Report the file's new path in one line.

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

@@ -21,8 +21,10 @@ Interview the user to fill gaps. Ask only what you can't infer from the codebase
 Ask in small batches; stop interviewing once the spec is testable.
 
 ## 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 Discovery interview above is **suspended and
+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 Discovery interview above is **suspended and
 forbidden**. This mode exists for one-line ideas: the card may be nothing more than a short title with
 **no description**, and there may be **no codebase or `STACK.md`** to draw on. That is expected and still
 fully actionable — a terse title is enough to write a complete draft PRD.

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

@@ -392,6 +392,11 @@ If you revise an existing report file, preserve the original metadata fields and
 | `PASS` | Zero CRITICAL findings AND zero pending decisions |
 | `FAIL` | Any CRITICAL finding exists OR any decision is PENDING |
 
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`PREFLIGHT: PASS` (zero CRITICAL findings and zero pending decisions) or `PREFLIGHT: FAIL` (one or
+more CRITICAL findings, or any decision pending). Automated runners read only this line; it must
+exactly match one of those two forms.
+
 `SIGNIFICANT` and `MINOR` findings do not block a PASS — they are advisory. However, they should be included in the report for the Planner to address.
 
 ---