@caddis/cli 0.4.52 → 0.4.54

package/bundles/codex/.codex/skills/workflow/roadmap/assets/render-check.template.mjs

@@ -0,0 +1,68 @@
+// Render check template. Copy it into the app (for example frontend/render-check.mjs) so CI and prod checks can run it.
+//
+// Usage:
+//   node render-check.mjs --base http://localhost:5173 --path /dashboard --expect kpi-total --expect chart-main
+//   node render-check.mjs --prod https://app.example.com --path /dashboard --expect kpi-total --channel msedge \
+//        --allow-auth app.example.com
+//   node render-check.mjs --base http://localhost:5173 --path /dashboard --expect kpi-total --prove-it-can-fail
+//
+// Options:
+//   --base <url> | --prod <url>   Origin to test (local or prod). One of them is required.
+//   --path <path>                 Page path. Default "/".
+//   --expect <testid>             A data-testid that must be visible. Repeat it.
+//   --channel <name>              Browser channel, for example msedge. Default: bundled chromium.
+//   --allow-auth <host>           Host that may use the current Windows login (NTLM). Repeat it.
+//   --settle <ms>                 Wait after network idle. Default 3000.
+//   --prove-it-can-fail           Add a test id that does not exist. The run must then exit 1.
+// Exit codes: 0 all checks pass, 1 a check failed, 4 bad arguments.
+import { chromium } from 'playwright'; // or: import { chromium } from '@playwright/test';
+
+const args = process.argv.slice(2);
+const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const all = (name) => args.flatMap((a, i) => (a === name ? [args[i + 1]] : []));
+
+const origin = opt('--prod') ?? opt('--base');
+if (!origin) { console.error('give --base <url> or --prod <url>'); process.exit(4); }
+const path = opt('--path') ?? '/';
+const settle = Number(opt('--settle') ?? 3000);
+const expected = all('--expect');
+const allowAuth = all('--allow-auth');
+if (args.includes('--prove-it-can-fail')) expected.push('testid-that-does-not-exist');
+if (expected.length === 0) { console.error('give at least one --expect <testid>'); process.exit(4); }
+
+const launch = { headless: true };
+if (opt('--channel')) launch.channel = opt('--channel');
+if (allowAuth.length) launch.args = [`--auth-server-allowlist=${allowAuth.join(',')}`];
+
+const failures = [];
+const browser = await chromium.launch(launch);
+for (const width of [1440, 400]) {
+  const context = await browser.newContext({ viewport: { width, height: 900 } });
+  // Dark theme seeded before any page script runs. Change the key and value to match the app.
+  await context.addInitScript(() => { try { localStorage.setItem('theme', 'dark'); } catch { /* ignore */ } });
+  const page = await context.newPage();
+  let consoleErrors = 0;
+  page.on('console', (m) => { if (m.type() === 'error') consoleErrors += 1; });
+  page.on('pageerror', () => { consoleErrors += 1; });
+
+  await page.goto(new URL(path, origin).toString());
+  await page.waitForLoadState('networkidle');
+  await page.waitForTimeout(settle);
+
+  if (consoleErrors > 0) failures.push(`${width}px: ${consoleErrors} console error(s)`);
+  const overflow = await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth);
+  if (overflow) failures.push(`${width}px: horizontal scroll`);
+  for (const id of expected) {
+    const visible = await page.getByTestId(id).first().isVisible().catch(() => false);
+    if (!visible) failures.push(`${width}px: data-testid "${id}" is not visible`);
+  }
+  console.log(`${width}px: console errors ${consoleErrors}, horizontal scroll ${overflow ? 'yes' : 'no'}`);
+  await context.close();
+}
+await browser.close();
+
+if (failures.length) {
+  for (const f of failures) console.error(`FAIL ${f}`);
+  process.exit(1);
+}
+console.log('PASS render check');

package/bundles/codex/.codex/skills/workflow/roadmap/assets/review-protocol.md

@@ -0,0 +1,78 @@
+---
+type: reference
+title: Review protocol
+description: The review method one model can rely on - invariants, inputs and writers, shared state, execute what the change promises, tests, docs, then severity (only blocking stops the merge; each finding needs a reproduction), one FINDING line per finding and an END REVIEW line. caddis_review.py sends it to every review run.
+status: current
+---
+
+# Review protocol (generic, any diff)
+
+You review a diff. You do NOT edit, create or delete files, and you do not commit. You may read files and run commands
+(tests, dry runs, the commands that plans, cards and docs name). Work through ALL steps in order. Do not stop at the
+first finding. Include a short section per step, in order.
+
+## Step 1 - Purpose and invariants
+Read the card, the plan or design section it cites, and the diff. Write the list of INVARIANTS this change must keep:
+safety limits, gates, money caps, isolation between runs or users, path containment, "X can never cause Y". Include
+invariants that the surrounding system relies on, not only the ones the card names.
+
+## Step 2 - Inputs and who controls them
+List every input the changed code reads: files, file sections, env vars, CLI args, other processes' output, the clock,
+the home folder. For EACH input write: who or what can write it (the owner, an unattended session, another runner,
+a test, a template), and when. Then, for each invariant from step 1, ask: can any writer of any input break it, by
+accident or on purpose? This includes the agent or session the code is meant to limit.
+
+## Step 3 - Shared state and concurrency
+List state that two runs, two kinds of target, or two processes could share (files, locks, relays, logs, caches).
+Can they collide? Can one read the other's output as its own?
+
+## Step 4 - Execute what the change promises
+Run the tests the card names. Then run every command that the plan, its exit gates, the docs or the skill text say
+should work for this change (dry runs, the documented usage lines), exactly as written. Use the repo's OWN fixtures
+and example files, not ones you build, and run unattended scripts (hooks, runners) as they are really run (as a script,
+with a real payload). Compare risky behaviour with the parent commit when the change claims to fix or tighten
+something. Report any that fail or that cannot work as documented.
+
+## Step 5 - Tests
+For each new or changed test: could it pass for the wrong reason (no assertion that can fail, mocked away the thing
+under test)? Does it depend on the real machine (home folder, real STOP files, network, clock, cwd)? Which new
+behaviour has no test, especially the negative cases (placeholders, malformed input, edge values)?
+
+## Step 6 - Docs and contracts
+Compare every doc, skill, prompt asset and usage line touched by or describing this feature with the code. List each
+mismatch (paths, flags, names, steps that do not exist or no longer apply). Check that every tool the new mode is told
+to use supports the new mode.
+
+## Step 7 - Report
+Severity rule. Only **blocking** stops the merge, so use it with care:
+- **blocking** = a defect that breaks a stated invariant from step 1 (safety, security, isolation, a gate passing when
+  it should fail, a crash of something that runs unattended), or loses or corrupts work or data, or breaks a money cap,
+  or makes a documented command fail. Use it even if other limits make the defect unlikely.
+- **should-fix** = a real defect that does not stop the merge: it goes on a follow-up list. Examples: a missing
+  negative test, a doc that is wrong in a way that does not make a command fail, an error message that misleads.
+- **nit** = style and wording.
+
+Every finding needs a concrete reproduction: a command, an input or a test that shows the failure, written in the
+failure scenario. A finding without a reproduction is a **nit**, whatever its severity would otherwise be. Do not
+write "might", "could in theory" or "a future change may": show it or call it a nit.
+
+The gate exits by the findings. A **blocking** finding fails it. **should-fix** and **nit** findings do not: they are
+listed in the report under "Follow-up (not blocking)". The tool allows 3 completed review rounds for a phase; the 4th completed round
+ends with "stop, the owner decides". Report every real defect once, with its true severity, so that one round is
+enough.
+
+End your answer with the findings, one line per finding, in exactly this form (no bullets, no bold, no code block):
+
+```
+FINDING <n> | <severity> | <file>:<line> | <one-sentence failure scenario>
+```
+
+`<n>` counts from 1, `<severity>` is `blocking`, `should-fix` or `nit`. Put the reproduction in the one sentence
+(for example `... ; reproduce: python x.py --flag with an empty file`). If you have no findings, write the line
+`NO FINDINGS` instead. The very last line of your answer is `END REVIEW <count>`, where `<count>` is the number of
+FINDING lines (`END REVIEW 0` after `NO FINDINGS`). A review whose last line is missing or whose count is wrong is
+treated as not run. Do not write a verdict line: the gate reads the findings only.
+No other line may contain the word FINDING followed by a number, anywhere in the line (in any case, also as
+`finding-1`, `finding #1`, `finding (1)`, after a bullet, a `>`, a table `|` or any other text): such a line that is
+not a complete FINDING line also makes the review count as not run. In your step sections, write "issue 1", not
+"finding 1".

package/bundles/codex/.codex/skills/workflow/roadmap/assets/roadmap.template.md

@@ -0,0 +1,32 @@
+# <slug> roadmap
+
+Runner host: HOSTNAME
+
+The roadmap file on `origin/main` is the only truth. Change it with `scripts/caddis_roadmap.py` (each change is a small
+docs PR), never by a direct push. Only `rollup` sets a milestone `done`.
+
+## Milestones
+| ID | Milestone | Phases | Depends on | Exit check | Status | Owner | Target |
+|---|---|---|---|---|---|---|---|
+| S1 | <what is true when it is done> | <plan>#1, <plan>#2 | - | `<command that exits 0 when S1 holds>` | todo | runner | <date> |
+
+## Blockers
+| Milestone | Type | Reason | Check |
+|---|---|---|---|
+
+## Notes
+
+- Status: todo, in-progress, code-done/data-pending, done or not-needed (blocked = has a Blockers row).
+- Blocker types: owner-gate, external, shared, calendar or data-condition (Check: a command, added by the owner
+  only; recheck runs it in a worktree of origin/main and clears that row on exit 0). A calendar blocker's Check is
+  an ISO date YYYY-MM-DD; recheck clears the row once that date has passed.
+- Status not-needed needs --reason "dropped: why" or --reason .caddis/parking-lot/file.md; the reason is added
+  below as "- id not-needed: reason (date)".
+- status lists each blocker row older than 14 days as "old blockers: id type (N days)"; the age comes from git.
+- A malformed section (wrong cell count, a row without a leading pipe, a line right after the table, a pipe in
+  prose, a second table, a renamed heading) stops every command: fix it by a PR. Escape a pipe in prose as \|.
+- This file allows only headings, plain paragraphs, lists and pipe tables: no code fences, no HTML, no setext
+  headings, no control or non-ASCII whitespace characters. GitHub would hide or move lines the parser reads, so
+  each one is a parse error.
+- Owner: runner (or empty) = the runner may take it; a session name = that session does it by hand.
+- A Depends on change cites a decision id from decisions.md in the Milestone cell: `S9 (dep waived: D4)`.

package/bundles/codex/.codex/skills/workflow/roadmap/assets/value-check.template.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Value check template: compare figures from an endpoint with an independent source over a fixed past window.
+
+Copy it into the app (for example scripts/check_values.py) so CI and prod checks can run it again.
+
+    python value-check.template.py --base http://localhost:8000 --expected expected.json
+    python value-check.template.py --base http://localhost:8000 --expected expected.json --prove-it-can-fail
+
+Expected file:
+    {"window": {"start": "2026-09-01", "end": "2026-09-30"},
+     "figures": [{"name": "...", "endpoint": "/api/x", "path": "a.b", "expected": 1200,
+                  "source": "where the expected value came from", "population": "who is counted",
+                  "denominator": "what the rate divides by, or none", "tolerance": 0.001, "series": "day"}]}
+
+Rules:
+  - The window must end before today. A moving window ("today") gives a number that changes while you check it.
+  - Every figure names its source, population and denominator.
+  - A "series": "day" figure has ISO date keys that all fall on one weekday. A weekday gap is not a data gap.
+  - --prove-it-can-fail changes the expected values on purpose. The run must then exit 1.
+
+Exit codes: 0 all figures pass, 1 a figure fails, 4 bad input or an HTTP error that is not a figure failure.
+"""
+from __future__ import annotations
+
+import argparse
+import copy
+import datetime as dt
+import json
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+_MISSING = object()
+
+
+class BadInput(Exception):
+    """The expected file or the request is wrong. Exit 4."""
+
+
+def _parse_date(text: str, what: str) -> dt.date:
+    try:
+        return dt.date.fromisoformat(str(text))
+    except ValueError as exc:
+        raise BadInput(f"{what} is not an ISO date: {text!r}") from exc
+
+
+def validate(spec: dict) -> None:
+    window = spec.get("window") or {}
+    start, end = _parse_date(window.get("start"), "window.start"), _parse_date(window.get("end"), "window.end")
+    if end >= dt.date.today():
+        raise BadInput(f"window.end {end} is not before today ({dt.date.today()}): use a fixed past window")
+    if start > end:
+        raise BadInput("window.start is after window.end")
+    figures = spec.get("figures") or []
+    if not figures:
+        raise BadInput("no figures in the expected file")
+    for fig in figures:
+        name = fig.get("name") or "<unnamed>"
+        for key in ("name", "endpoint", "path", "expected"):
+            if key not in fig or fig[key] in ("", None):
+                raise BadInput(f"figure {name!r} has no {key}")
+        for key in ("source", "population", "denominator"):
+            if not str(fig.get(key, "")).strip():
+                raise BadInput(f"figure {name!r} has an empty {key}: name it")
+        if fig.get("series") == "day":
+            if not isinstance(fig["expected"], dict) or not fig["expected"]:
+                raise BadInput(f"figure {name!r}: a day series needs a non-empty object of date keys")
+            weekdays = {_parse_date(k, f"figure {name!r} key").weekday() for k in fig["expected"]}
+            if len(weekdays) > 1:
+                raise BadInput(f"figure {name!r}: day series keys fall on more than one weekday")
+
+
+def prove_it_can_fail(spec: dict) -> dict:
+    """Return a copy with a wrong expected value, so a correct endpoint must fail."""
+    spec = copy.deepcopy(spec)
+    scalars = [f for f in spec["figures"] if not isinstance(f["expected"], dict)]
+    if scalars:
+        scalars[0]["expected"] = scalars[0]["expected"] + 1
+    series = [f for f in spec["figures"] if isinstance(f["expected"], dict)]
+    if series:
+        series[0]["expected"].pop(next(iter(series[0]["expected"])))  # a missing date must fail the compare
+        series[0]["expected"]["1999-01-04"] = 0  # 1999-01-04 is a Monday; the endpoint has no such key
+    if not scalars and not series:
+        spec["figures"][0]["path"] += ".missing"
+    return spec
+
+
+def fetch(base: str, endpoint: str, window: dict, headers: dict) -> tuple[int, object]:
+    query = urllib.parse.urlencode({"start": window["start"], "end": window["end"]})
+    req = urllib.request.Request(f"{base.rstrip('/')}{endpoint}?{query}", headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.status, json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        return exc.code, None
+    except (urllib.error.URLError, TimeoutError, ValueError) as exc:
+        raise BadInput(f"cannot read {endpoint}: {exc}") from exc
+
+
+def dig(data: object, path: str) -> object:
+    for part in path.split("."):
+        if isinstance(data, dict) and part in data:
+            data = data[part]
+        else:
+            return _MISSING
+    return data
+
+
+def same(actual: object, expected: object, tolerance: float) -> bool:
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            return False
+        return all(k in actual and same(actual[k], v, tolerance) for k, v in expected.items())
+    if isinstance(expected, bool) or isinstance(actual, bool) or not isinstance(expected, (int, float)):
+        return actual == expected
+    return isinstance(actual, (int, float)) and abs(actual - expected) <= tolerance
+
+
+def check(spec: dict, base: str, headers: dict) -> bool:
+    ok = True
+    for fig in spec["figures"]:
+        status, body = fetch(base, fig["endpoint"], spec["window"], headers)
+        actual = dig(body, fig["path"]) if status == 200 else _MISSING
+        passed = actual is not _MISSING and same(actual, fig["expected"], float(fig.get("tolerance", 0)))
+        shown = "missing" if actual is _MISSING else actual
+        if status != 200:
+            shown = f"HTTP {status}"
+        print(f"{'PASS' if passed else 'FAIL'} {fig['name']}: endpoint {shown} vs {fig['source']} {fig['expected']}; "
+              f"population {fig['population']}; denominator {fig['denominator']}")
+        ok = ok and passed
+    return ok
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--base", required=True, help="origin of the app, for example http://localhost:8000")
+    ap.add_argument("--expected", required=True, help="expected figures JSON file")
+    ap.add_argument("--prove-it-can-fail", action="store_true", help="change the expected values; the run must exit 1")
+    ap.add_argument("--header", action="append", default=[], metavar="K:V", help="extra request header (repeatable)")
+    args = ap.parse_args(argv)
+    try:
+        with open(args.expected, encoding="utf-8") as fh:
+            spec = json.load(fh)
+        validate(spec)
+        headers = {}
+        for h in args.header:
+            key, sep, value = h.partition(":")
+            if not sep:
+                raise BadInput(f"--header needs K:V, got {h!r}")
+            headers[key.strip()] = value.strip()
+        if args.prove_it_can_fail:
+            spec = prove_it_can_fail(spec)
+        return 0 if check(spec, args.base, headers) else 1
+    except (BadInput, OSError, ValueError) as exc:
+        print(f"bad input: {exc}", file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/codex/AGENTS.md

@@ -61,7 +61,7 @@ these files are the truth.
   runbook, analysis, handoff) must open with a YAML frontmatter block:
   ```yaml
   ---
-  type: plan|prd|adr|design|runbook|handoff|analysis|review|prompt|parking-lot|rca|todo|relay|comms|reference|note|phase-report|implement-review|phase-verdict|hub-spawn|advisory-context|phase-prompt
+  type: plan|prd|adr|design|runbook|handoff|analysis|review|prompt|parking-lot|rca|todo|relay|comms|reference|note|phase-report|implement-review|phase-verdict|hub-spawn|advisory-context|phase-prompt|open-work
   status: draft|current|done|superseded
   feature: <feature-slug>
   creation-agent: caddis
@@ -114,9 +114,10 @@ future: yes              # OPTIONAL. yes = committed. Absent or `no` = a candida
 `status` and `future` answer different questions and must stay separate: where the item is in its
 life, and whether we have agreed to do it. `python scripts/caddis_tidy.py --check` and the
 `caddis_gate.py parking-lot` gate both fail on a non-conforming item, so this is enforced, not
-advised. Two neighbours that are NOT the backlog: `/caddis:digress` parks an interrupted task on a
-stack (`/caddis:catchup` pops it), and `.caddis/backlog/` is written by **docket** as a projection of
-its board — never hand-edit that one.
+advised. `--check` also fails on a plan whose Tracker is all done while its `status:` is still
+active, and with `--commit-range BASE..HEAD` it reports violations only in the files that range
+changed. One neighbour that is NOT the backlog: `/caddis:digress` parks an interrupted task on a
+stack (`/caddis:catchup` pops it).
 
 ### Write environment facts down in the same turn
 **If you learn a fact about the environment, write it to `.caddis/kb/environment-map.md` before you

package/bundles/manifest.json

@@ -1,8 +1,8 @@
 {
-  "poolVersion": "1.3.138",
+  "poolVersion": "1.3.140",
   "bundles": {
-    "antigravity-plugin": "1.3.138",
-    "antigravity-plugin-extras": "1.3.42",
+    "antigravity-plugin": "1.3.140",
+    "antigravity-plugin-extras": "1.3.43",
     "codex": "unknown"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.52",
+  "version": "0.4.54",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",

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

@@ -1,233 +0,0 @@
----
-name: advisory-hub
-description: >-
-  A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its
-  self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub
-  verdict", "who checks the implementing session", "re-derive don't trust", "hand off the hub", or a
-  long plan with expensive-to-reverse work (migration, security change, production data correctness)
-  needs independent checks; not for short features. Hub artefacts go in
-  `.caddis/advisory-hub-reports/`.
----
-
-# Advisory Hub — cross-session phase validation
-
-## The whole model, in four statements
-
-> **1. Re-derive, don't trust — and re-derive DIFFERENTLY than the implementer did.**
-> **2. Two roles, four files.** The implementer writes only the report. The Hub writes everything else.
-> **3. The memory IS the switch.** `<plan-stem>-advisory-context.md` turns the mode on *and* is the
->    Hub's brain. An empty file buys a rubber stamp.
-> **4. Nothing is fixed until it lands in the context doc.** A correction living in a verdict or a
->    chat dies with the session that wrote it.
-
-### 1. The rule, and the correction to it
-
-A phase report is a **self-assessment**. When it says *"VALUE CHECK passed: endpoint 11,126 = SQL
-11,126,"* the Hub **runs the query itself**. A Hub that reads reports and nods is *worse than no Hub*
-— it manufactures false confidence.
-
-**But re-running a gate *identically* is not independent verification** — it reproduces the
-implementer's blind spot. That cost a failed production deploy: implementer and Hub both ran the same
-suite, both green, and CI then failed on a dependency-injection bug the gitignored local env file had
-been masking. **For anything touching config, a data seam, or dependency injection, deprive the
-environment:** `mv <env-file> aside && <test command> && mv back`.
-
-### 2. Two roles, four files
-
-| File | Written by | When | What is lost without it |
-|---|---|---|---|
-| `<plan-stem>-advisory-context.md` | scaffolded at planning; **owned and maintained by the Hub** | before | The Hub's memory — re-derivation access, locked decisions *and their non-obvious reasons*, the disproved-claims list. Nothing else survives a Hub crash or compaction |
-| `.caddis/advisory-hub-reports/phase-NN.prompt.md` | **the Hub** | **BEFORE the phase runs** | What the implementer was *told*. Without it, "the implementer deviated" and "the plan was wrong" are both unfalsifiable |
-| `.caddis/advisory-hub-reports/phase-NN.report.md` | the implementing session | after | The only evidence a phase's claims were ever checkable rather than merely asserted |
-| `.caddis/advisory-hub-reports/phase-NN.verdict.md` | **the Hub** | after | A later reader sees a self-assessment and no evidence anyone checked it |
-
-**Role separation is not decoration.** An implementer that writes its own verdict has produced a
-self-assessment wearing a verdict's name — worse than no verdict, because it *looks* like a check
-happened. Diligence is no substitute: an implementer can re-derive its own claims honestly and still
-produce a worthless verdict.
-
-Where a `phase-NN.prompt.md` exists it is **the instruction of record** — `/caddis:implement` reads it,
-and deviations are measured against it, not against the plan alone.
-
-**The launch command does not belong in `phase-NN.prompt.md`.** That file is read by the implementer,
-i.e. *after* launch — a file instructing you to spawn GLM is one GLM only reads once it has already
-been spawned. Observed on a real plan, and the skill said nothing either way, so it will recur.
-Surface the launch command to whoever is **orchestrating** (the human, or the session that will spawn
-the phase). What the phase prompt SHOULD carry is a one-line **lane declaration** — *"This phase must
-run on `<lane>`"* — so a mis-launched session can self-detect and act on it.
-
-The lane a phase gets is also **provisional until this file is written.** Writing the phase prompt is
-the first time anyone but the spec's author reads the spec; if the phase turns out to need judgment a
-no-escalation lane cannot supply, downgrade it here.
-
-### 3. The switch
-
-`<plan-stem>-advisory-context.md`, beside the plan. `/caddis:implement`, `/caddis:handoff` and
-`/caddis:validate-phase` all check for it. **No file → zero behaviour change, in every command, ever.**
-
-Do not `touch` an empty one to "turn it on". The switch and the memory are deliberately the same file:
-it should be structurally impossible to enable the Hub without giving it a brain.
-
-**The verdict gates the next phase, by machine.** In Advisory-Hub mode, before starting phase N,
-`/caddis:implement` requires `phase-(N-1).verdict.md` carrying `verdict: accept` or
-`accept-with-correction`. Missing, or `reject` → stop and report `blocked-pending-hub`.
-
-### 4. Corrections land structurally
-
-Every correction the Hub issues must be asked: *where does this live so it cannot recur?* Telling the
-implementing session is worthless — that session is closing. Putting it in the next phase's prompt
-works exactly once. **Put it in the context doc**, where it binds every future phase whether or not
-anyone remembers it. Each verdict therefore ends with *"what is now structural."*
-
-Corollary: **feed the generic form back to this skill's parking lot.** Project facts stay in the
-project; role mechanics come back here, or the skill never improves.
-
----
-
-## When it earns its keep
-
-**The cost is a full extra session's context, per phase.** Do not reach for this because it sounds
-rigorous — reach for it when a mistake is expensive enough that the cost is cheap by comparison.
-
-> **REQUIRED: the work is expensive to reverse** — a migration, a security change, production data
-> correctness, or numbers published to stakeholders. **No stakes → no Hub, whatever else is true.**
->
-> **PLUS at least one of:** the plan has **≥8 phases** · it is implemented across **sessions that will
-> not share context**.
-
-A three-phase feature hits none of this. `/caddis:feature-plan` Step 3b runs this test and **offers**;
-it never creates the file silently. This is the test's only home — do not restate the thresholds
-elsewhere, or the copies drift.
-
-### Failing this test correctly does not mean "no discipline"
-
-A plan can fail the test above — properly, no Hub needed — and still be multi-phase, multi-session,
-and worth structuring. The trap is what happens next.
-
-The Hub's file conventions are *attractive*. Once one plan in a repo runs in Hub mode, its
-`phase-NN.prompt.md` / `phase-NN.report.md` / CONTINUE GATE artefacts are sitting right there as the
-most recent example of "how we structure a multi-session plan here." A second, smaller plan copies
-them by analogy. It gets the readability. It gets **none** of the safety, because the safety was
-never in the file names — it was in the role split and the verdict gate.
-
-That has happened. A six-phase UI plan borrowed the naming, and an implementing session filed its own
-batch report **and then wrote the next batch's prompt in the same session**, with nobody having
-looked at the work in between. Nothing was wrong that time. Nothing *checked*, either — and the good
-outcome is not evidence the mechanism worked, it is evidence nothing tested it.
-
-This skill already says why role separation is not decoration:
-
-> *An implementer that writes its own verdict has produced a self-assessment wearing a verdict's
-> name — worse than no verdict, because it looks like a check happened.*
-
-The same sentence holds with two words changed: **an implementer that writes the next phase's
-instructions** has produced a plan wearing an independently-authored prompt's name.
-
-### The one lightweight rule — cheap enough to always afford
-
-> **The session that files a phase's report must not also write the next phase's prompt without an
-> independent re-check in between.**
-
-That is the whole rule. It costs minutes, not a session:
-
-- re-run the test suite rather than trusting the report's claim that it passed
-- grep the source for the report's two or three load-bearing claims
-- open one or two of the screenshots it describes, rather than reading its description of them
-
-No switch file. No dedicated Hub session. No advisory-context doc. If the re-check finds nothing, you
-have lost ten minutes; if it finds something, it found it *before* the wrong instruction went into a
-fresh session that cannot know any better.
-
-**State which one you are doing, in the plan.** A plan that borrows Hub file conventions should say
-either "full Advisory Hub mode" or "Hub file conventions, lightweight re-check rule, no Hub" —
-because a reader six phases later cannot tell the two apart from the artefacts alone. That is the
-entire problem this section exists to prevent.
-
-## Succession is not the same as a standing validator
-
-Two things look alike from outside and are not:
-
-- **`/caddis:spawn-hub` is SUCCESSION.** The outgoing Hub **ends**. It hands the role to a fresh
-  session and stops. There is one Hub afterwards, not two.
-- **`/caddis:validate-phase` assumes a Hub that PERSISTS** across phases, checking each one.
-
-Conflating them builds a review loop that has to be unwound. One session kept Hub-1 alive to check
-Hub-2, then dismantled the arrangement when the user said they were closing Hub-1. Both models are
-reasonable; running both at once is not.
-
-## Every Hub artefact has one home
-
-`.caddis/advisory-hub-reports/`. A succession prompt is `hub-NN.spawn.md` there, with frontmatter
-`type: hub-spawn`. **This holds even when you write one by hand** rather than running
-`/caddis:spawn-hub` — and by hand is exactly when it gets missed, because the instruction lives
-inside the command you skipped.
-
-The knock-on is the part that bites. `spawn-hub` rotates its comprehension trap by reading the last
-spawn prompt from that directory. A prompt filed anywhere else is invisible to it, so rotation
-silently runs against an empty set — the failure the artefact file was introduced to prevent,
-returning through a different door. `check_doc_coverage.py` now warns on a `type: hub-spawn` file
-found outside that directory.
-
-## The Hub is a ROLE, not a conversation
-
-It outlives any one session and hands over through **files**, never chat history. Hand over with
-`/caddis:spawn-hub` — at a milestone boundary, or sooner if context is filling.
-
-**Your instinct that the context doc is current is measured-wrong.** Asked *"can we hand off?"*, an
-outgoing Hub's honest first answer was yes; a mechanical audit then found **seven gaps** — including
-that the single highest-value technique then in use was written down nowhere a fresh Hub would find it.
-
-## While you hold the role — maintain `relay.md`, not just the succession table
-
-**The succession table records WHO HELD THE ROLE. `.caddis/relay.md` records WHERE THE WORK IS. A
-Hub maintains both; they are not substitutes.**
-
-The succession table is written when a Hub **ends**. Nothing else covers the hours while a Hub is
-**working** — and that is the whole period this mechanism exists to protect, because its entire
-purpose is surviving session death.
-
-> **Mirror your working list into `.caddis/relay.md` as you go.** Your in-session task list does not
-> survive this session. `relay.md` does. Anything not written there is lost when the window closes.
-
-This gap was real. A 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. The user noticed before the agent did: *"I don't see it creating any todo list
-yet."* The work was only recoverable because the OUTGOING Hub had written a tracker into `relay.md`
-an hour earlier, on its own initiative.
-
-**`relay.md` is gitignored and machine-local.** That is deliberate — it is per-machine session state,
-not a shared artefact — but it has two consequences a Hub must plan around. It never reaches another
-machine, so anything a *successor on a different box* needs belongs in the advisory context or the
-spawn prompt instead. And no gate can check it through git, so keeping it current is a discipline,
-not something a build will catch for you.
-
-## Where the detail lives
-
-Each file below is loaded by a **named command step**, at the moment it is needed. This is not optional
-reading — it is deferred reading.
-
-| Load this | For | Loaded by |
-|---|---|---|
-| `reference/context-template.md` | scaffolding or maintaining the context doc | `feature-plan` 3b · `validate-phase` 0 · `spawn-hub` 3 |
-| `reference/report-contract.md` | filing a phase report | `implement`, at report time |
-| `reference/hub-handbook.md` | validating a phase — verdict template, checklist, techniques, plan drift | `validate-phase` 2 |
-| `reference/succession.md` | handing the role over — audit, self-check trap, carried-open ledger | `spawn-hub` · `handoff` 2b |
-
-Naming, frontmatter and directory rules ship as an `AGENTS.md` **inside**
-`.caddis/advisory-hub-reports/`, so they bind every agent that writes there — including agents that
-never loaded this skill.
-
-## Not to be confused with
-
-`.github/prompts/advisory-hub.prompt.md` and `.github/instructions/advisory-mode.instructions.md` use
-the same name for an older, unrelated Copilot chat-mode pipeline. It never ships to the Claude Code
-plugin.
-
-## Anti-patterns
-
-- **Rubber-stamping.** A verdict with no re-derivation is not a verdict.
-- **Re-running a gate the same way and calling it independent verification.** Change the environment.
-- **An implementer writing its own verdict.** The roles exist for exactly this.
-- **An empty context doc.** The switch *is* the memory.
-- **Applying this to a short feature.** State the cost, every time, before adopting it.
-- **A correction that lives only in a verdict file.** It dies with the session that wrote it.