@caddis/cli 0.2.4 → 0.2.6

package/README.md

@@ -84,6 +84,17 @@ Summary
 `--strict` exits non-zero when something needs fixing (for CI). Detected-but-unsupported agents are
 information, not failures, and never trip `--strict`. `--json` gives machine-readable output.
 
+**`doctor` also checks whether `@caddis/cli` itself is behind npm** (a 5s `npm view` lookup, opt-in to
+`doctor` only — `status`/`init`/`update` stay network-free by default so they never feel hung offline).
+This matters because every per-agent drift check above compares against the pool bundled in *this*
+install — a CLI that is itself stale can under-report drift even though each individual comparison is
+correct. When behind, doctor adds:
+```
+  ▲ @caddis/cli 0.2.3 → 0.2.4 available
+      npm i -g @caddis/cli@latest
+```
+and counts it as a `--strict`-tripping problem, same as an agent gap.
+
 ### `caddis status`
 
 The same facts as a glanceable table. Running bare `caddis` does this.

package/bundles/antigravity-plugin/agents/claude-md-curator.md

@@ -1,6 +1,6 @@
 ---
 name: claude-md-curator
-description: Use this agent periodically (every few weeks, or when any AGENTS.md exceeds ~80 lines) to prune and consolidate the project's AGENTS.md rules files (the canonical rules; CLAUDE.md is a thin @AGENTS.md import shim). Flags staleness, bloat, duplication, misrouted how-to content, and CLAUDE.md shims that have grown rules of their own. Proposes a curated version — never writes without showing the diff to the main thread first.
+description: Use this agent periodically (every few weeks, or when any AGENTS.md exceeds ~200 lines) to prune and consolidate the project's AGENTS.md rules files (the canonical rules; CLAUDE.md is a thin @AGENTS.md import shim). Flags staleness, bloat, duplication, misrouted how-to content, and CLAUDE.md shims that have grown rules of their own. Proposes a curated version — never writes without showing the diff to the main thread first.
 ---
 
 You are the rules-file maintenance agent. **`AGENTS.md` is the canonical rules file** (root + each
@@ -90,14 +90,17 @@ propose deletion — they're copy-paste artifacts and don't affect the live, plu
 
 ## Step 3 — Size budget check
 
-An AGENTS.md over 80 lines almost certainly contains bloat. Flag the file and count:
+An AGENTS.md over 200 lines (`AGENTS_MD_BUDGET` — the one enforced value, in
+`scripts/claudster_doctor.py` and mirrored in `scripts/check_doc_coverage.py`; do not restate a
+different number here) almost certainly contains bloat. Flag the file and count:
 - Lines that pass the "keep" bar
 - Lines that should be deleted
 - Lines that should be moved to a runbook
 
 > The pre-push doc-coverage checker (`scripts/check_doc_coverage.py`) also *warns* on an oversize
-> always-loaded rules file (`AGENTS.md` + its `CLAUDE.md` shim; `agents_md_budget`) — this agent is the
-> deeper consolidation pass that actually fixes it.
+> always-loaded rules file (`AGENTS.md` + its `CLAUDE.md` shim; `agents_md_budget`), and a
+> `PostToolUse` hook (`hooks/rules_budget_nudge.py`) re-warns mid-session on every edit to one that's
+> already over — this agent is the deeper consolidation pass that actually fixes it.
 
 ## Step 4 — Return proposed changes (never write)
 

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.54",
+  "version": "1.3.75",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/skills/_registry.md

@@ -71,20 +71,26 @@
 | Digress | `digress/` | Park the current workstream on the stack and switch to a new task — without losing the original |
 | Excalidraw Db | `excalidraw-db/` | Turn a SQL artifact into an Excalidraw diagram for a design review / ARB pack / slide — higher-level, drag-the-boxes format |
 | Feature Plan | `feature-plan/` | Create a phased, TDD-structured implementation plan that acts as the durable spine for multi-session work |
+| Gate Preflight | `gate-preflight/` | Deterministic headless preflight — validates a plan against the actual codebase, self-contained (never depends on a skill activating) |
+| Gate Review | `gate-review/` | Deterministic headless code review — adversarial diff review, self-contained (never depends on a skill activating) |
 | Handoff | `handoff/` | End-of-session handoff — capture exact state so the next session resumes with zero re-discovery |
 | Implement | `implement/` | Headless plan executor — implement an approved plan phase-by-phase on the current feature branch, TDD-first, committing per phase |
 | Kb | `kb/` | Rebuild the KB index (.caddis/kb/DOC-MAP.md) — create it if missing, index un-indexed notes, report dangling links |
 | Mermaid Db | `mermaid-db/` | Turn a SQL artifact (proc, view, query, .sql file, or table name) into a Mermaid diagram that explains it — git-diffable, saved as .md |
 | Migrate Dir | `migrate-dir/` | Rename this repo's legacy `.claudster/` artifact dir to `.caddis/` — dry-run first, `git mv` to keep history, merges a straggler dir, rewrites live refs. Opt-in, never automatic. |
+| Park | `park/` | File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open |
 | Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
 | Resume | `resume/` | Pop the most recently parked workstream off the stack and resume it at its exact resume point |
 | Ship | `ship/` | Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only) |
 | Ship Merge | `ship-merge/` | Merge an already-green, already-reviewed PR behind an explicit deploy-confirm, monitor the deploy, validate prod, then clean up the branch — only on green. |
 | Ship Pr | `ship-pr/` | Open a reviewed PR for the current feature branch — rebase-safe push, PR create/update, monitor CI, STOP at green. Never merges, never deploys (that's /ship-merge). |
+| Spawn Hub | `spawn-hub/` | Hand the Advisory Hub role to a fresh session — run the mechanical audit, then generate the succession prompt with a context self-check the new Hub must pass |
+| Spawn Session | `spawn-session/` | Hand the WORK to a fresh session — generate the handover from the repo, then validate the successor by re-deriving its answers |
 | Tdd | `tdd/` | Run a strict red-green-refactor TDD cycle for a unit of behavior |
 | Ui Brief | `ui-brief/` | Design-first UI brief — lock the aesthetic before writing any code |
 | Usage Review | `usage-review/` | Review local caddis usage over a window, surface prioritised recommendations, and apply config changes in one step |
 | Use Model | `use-model/` | Explain (or apply) the model lanes — claude / claude-glm / cross-review — key resolution, and how to add a provider |
+| Validate Phase | `validate-phase/` | Advisory Hub phase validation — consume a phase report, RE-DERIVE its claims independently, and return ACCEPT / ACCEPT-WITH-CORRECTION / REJECT |
 | Version | `version/` | Report the installed caddis version |
 
 ### Media
@@ -108,6 +114,7 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
+| Advisory Hub | `advisory-hub/` | Cross-session phase validation for multi-phase implementation plans — a long-lived "Hub" session RE-DERIVES each implementation phase's claims independently instead of trusting its self-assessment. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or when a long, multi-session plan with expensive-to-reverse decisions (a migration, a security change, anything touching production data correctness) needs an independent session that verifies every phase before the next one starts. NOT for a three-phase feature — it costs a full extra session's context per phase, and a skill that doesn't say so gets applied everywhere and resented. Every Hub artefact belongs in `.caddis/advisory-hub-reports/` — a succession prompt is `hub-NN.spawn.md` there, never a generic prompts folder, even when you write it by hand instead of running `/caddis:spawn-hub`. |
 | Best Practices | `best-practices/` | >- |
 | Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
 | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |

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

@@ -0,0 +1,183 @@
+---
+name: advisory-hub
+description: Cross-session phase validation for multi-phase implementation plans — a long-lived "Hub" session RE-DERIVES each implementation phase's claims independently instead of trusting its self-assessment. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or when a long, multi-session plan with expensive-to-reverse decisions (a migration, a security change, anything touching production data correctness) needs an independent session that verifies every phase before the next one starts. NOT for a three-phase feature — it costs a full extra session's context per phase, and a skill that doesn't say so gets applied everywhere and resented. Every Hub artefact belongs in `.caddis/advisory-hub-reports/` — a succession prompt is `hub-NN.spawn.md` there, never a generic prompts folder, even when you write it by hand instead of running `/caddis:spawn-hub`.
+---
+
+# 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.
+
+## 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

@@ -0,0 +1,214 @@
+# 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 | | |