@caddis/cli 0.4.52 → 0.4.53

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.139",
   "bundles": {
-    "antigravity-plugin": "1.3.138",
-    "antigravity-plugin-extras": "1.3.42",
+    "antigravity-plugin": "1.3.139",
+    "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.53",
   "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.

package/bundles/antigravity-plugin/skills/advisory-hub/reference/context-template.md

@@ -1,214 +0,0 @@
-# Advisory Hub — the `advisory-context.md` template — the Hub's memory AND its on/off switch
-
-> **Loaded by:** `/caddis:feature-plan` Step 3b (scaffold) · `/caddis:validate-phase` Step 0 (bootstrap) · `/caddis:spawn-hub` Step 3
->
-> Reference for `.github/skills/workflow/advisory-hub/SKILL.md`. The core card carries the
-> model; this carries the detail for one moment of use. Every rule here was earned by a
-> specific failure — the failure is stated alongside it, so a later reader can tell a hard-won
-> rule from an opinion.
-
----
-
-## §A — the `advisory-context.md` template
-
-Copy this in full when you (the Hub) start guarding a new plan. It is a **committed** peer of the plan,
-not of `relay.md`.
-
-````markdown
----
-type: advisory-context
-status: active
-feature: <slug>
-Original Author: <human or agent>
-Creation Date: <ISO 8601 UTC>
-Creating Model: <model/lane>
----
-
-# Advisory Context — <Feature Name>
-
-**Companion to `<path to the plan>`.** The plan says *what to build*. This says *why it is shaped that
-way, what was measured, and what has already been disproved* — the things a reader of the plan alone
-would re-litigate.
-
-**Who this is for:** the **Advisory Hub** — the long-lived session that validates each implementation
-phase. If the Hub session dies or compacts, a new one is reconstituted from: this file → the plan → the
-project's own rules file (`AGENTS.md`). Nothing else is required.
-
----
-
-## 1. The Hub's job, and its one rule
-
-Implementation sessions run phases and report. The Hub **validates**.
-
-> **THE RULE: re-derive, do not trust.** A phase report is a self-assessment; accepting it at face value
-> makes the Hub a rubber stamp.
-
-The Hub's verdict is one of:
-- **ACCEPT** — re-derived numbers match; gates genuinely ran; move to the next phase.
-- **ACCEPT WITH CORRECTION** — work is sound but something is wrong or missing; the Hub states the exact
-  fix and it lands before the next phase.
-- **REJECT** — a gate was skipped, a number does not reproduce, or a locked decision was violated. The
-  phase is redone.
-
-The Hub also protects the plan from drift (§6 below) — a deviation from a locked decision (§4) is a
-*Hub* decision, never the implementer's.
-
----
-
-## 2. Baseline state as of <date>
-
-The state every validation starts from — anything that changed out-of-band, before Phase 0/1 ran, that a
-fresh Hub needs to know about (environment changes, migrations already applied, services restarted).
-
----
-
-## 3. The measured facts (re-derivable — do not accept a contradiction without re-measuring)
-
-### 3a. RE-DERIVATION ACCESS
-
-The literal, copy-pasteable command (or script, query, API call, test invocation) that reproduces this
-plan's anchor numbers from this repo, and roughly how long it takes. **The Hub's one rule is unaffordable
-without this** — if reproducing a number takes twenty minutes of setup, the Hub will quietly stop doing
-it. Include every environment prerequisite; nothing here should require reconstruction.
-
-### 3b. The anchor numbers
-
-| Fact | Value |
-|---|---|
-| <the numbers the plan's claims will be checked against> | |
-
-### 3c. The findings that shaped the plan most
-
-<the 1-3 measured findings that most determined the plan's shape, and why no simpler approach works>
-
----
-
-## 4. Locked decisions — an implementer may not change these unilaterally
-
-| # | Decision | The reason that is NOT obvious from the plan |
-|---|---|---|
-| D1 | | |
-
----
-
-## 5. Project safety conventions this Hub enforces
-
-If this project's rules file (`AGENTS.md`/`CLAUDE.md`) or its docs declare standing correctness
-conventions that a phase could silently violate, list them here with an id, a one-line statement, and
-**the check that proves compliance**. The phase report carries a slot per rule; the Hub re-checks each.
-**If this project declares none, write `NONE DECLARED`** — both the report section and the Hub's
-re-check become `N/A`, and this costs nothing.
-
-| Rule id | What it requires | The check that proves it | Scope (docs only, or `src/` too) |
-|---|---|---|---|
-
-*Worked example — a project that computes rates or percentages typically declares something like: every
-rate-bearing field must name its population, must carry its coverage denominator, and must have a
-nested-subset test that would actually fail if the denominator drifted. Other common shapes: a
-date-window boundary convention; a required migration-reversibility check; a mandatory secret-scan on any
-config change.* This section exists because the Hub's core distrust — re-derive, don't trust — applies to
-process as much as to arithmetic; where a project has already codified that distrust as a rule, the Hub
-enforces it every phase rather than hoping the implementer remembered.
-
----
-
-## 6. Already disproved — do not re-raise
-
-| Claim | Status |
-|---|---|
-| <a claim two reviewers independently raised, that a live check settled as false> | **FALSE** — <the evidence> |
-
-A Hub without this memory reopens the same false blocker every phase a new reviewer raises it.
-
----
-
-## 7. The phase report contract
-
-Canonical definition: the `advisory-hub` skill's §B. This project's local additions (if any) and the
-specific failures that earned them:
-
-<none yet, or list them here as they're discovered>
-
----
-
-## 8. Standing gotchas that bite every phase
-
-<durable, non-obvious rules a fresh implementing session needs and would not discover from the code>
-
----
-
-## 9. Hub techniques that actually caught something here
-
-<which of §E's techniques (mutation testing, re-running cross-review, reading the copy) found a real
-problem on this plan, and what it found>
-
----
-
-## 10. Environment facts a fresh Hub will not otherwise know
-
-| Fact | Why it matters |
-|---|---|
-
----
-
-## 11. Gotchas discovered while implementing (not in the plan)
-
-<implementation-time surprises worth a durable rule, even though the plan didn't anticipate them>
-
----
-
-## 12. Hub self-handoff — the mechanical audit is mandatory, not optional
-
-This file exists so a fresh Hub session can take over without the conversation. That only works if it
-stays current — and the outgoing Hub's instinct is always "yes, this is ready," because it's judging
-against its own memory of the session, not against this document. **That instinct is wrong by default.**
-Run the audit in §G before every handoff; do not skip it because the file "looks current."
-
----
-
-## Changelog
-- **<date>** — created.
-````
-
-**Why this file, not the plan:** a fresh session has the plan but not the *why* — and will re-litigate
-settled questions. §4's *reason* column is the load-bearing part; the decision alone invites a second
-reviewer to reopen it. §6 exists because on the reference implementation of this pattern, two independent
-cross-review models both raised the same blocker — only a live probe closed it, and a Hub without that
-memory would have reopened it every subsequent phase. §3a is kept separate from §3b because the numbers
-are worthless if a future Hub can't cheaply reproduce them.
-
----
-
-## Succession — the Hub is a role, not a conversation
-
-| Hub | Covered | Ended because |
-|---|---|---|
-| 1 | <phases> | <context / milestone / handover> |
-
-## Carried open — APPEND AND CLOSE, never rewrite
-
-Every item keeps a stable id and is **never deleted**. Closing one 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 is still open, and both are visible. It also lets a later Hub see something was closed
-*wrongly*, which a deletion hides forever.
-
-`/caddis:spawn-hub` runs a **conservation check** against this table at every handover: an id present
-in the predecessor's ledger and absent here fails the spawn.
-
-| id | raised by | item | status |
-|---|---|---|---|
-| C1 | Hub 1 | <enough detail to act on without archaeology> | open |
-| C2 | Hub 1 | <…> | **closed by Hub 3** — <why> |
-
-A verdict may *raise* an item, but it is not raised until it has an id here, in the same commit.
-Closed rows compress to one line; they leave for the changelog only when the plan ships.
-
-## Lane trust — what each execution lane has actually earned
-
-Phase reports carry `MODEL/LANE` so the Hub can judge whether a lane is trustworthy for later phases.
-Nothing accumulated that judgement, so each Hub re-formed it from scratch or lost it.
-
-| lane | phases run | notable |
-|---|---|---|
-| claude | | |
-| glm-headless | | |