@caddis/cli 0.2.6 → 0.4.0

package/bundles/codex/.codex/skills/testing/webapp-testing/examples/element_discovery.py

@@ -0,0 +1,40 @@
+from playwright.sync_api import sync_playwright
+
+# Example: Discovering buttons and other elements on a page
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page()
+
+    # Navigate to page and wait for it to fully load
+    page.goto('http://localhost:5173')
+    page.wait_for_load_state('networkidle')
+
+    # Discover all buttons on the page
+    buttons = page.locator('button').all()
+    print(f"Found {len(buttons)} buttons:")
+    for i, button in enumerate(buttons):
+        text = button.inner_text() if button.is_visible() else "[hidden]"
+        print(f"  [{i}] {text}")
+
+    # Discover links
+    links = page.locator('a[href]').all()
+    print(f"\nFound {len(links)} links:")
+    for link in links[:5]:  # Show first 5
+        text = link.inner_text().strip()
+        href = link.get_attribute('href')
+        print(f"  - {text} -> {href}")
+
+    # Discover input fields
+    inputs = page.locator('input, textarea, select').all()
+    print(f"\nFound {len(inputs)} input fields:")
+    for input_elem in inputs:
+        name = input_elem.get_attribute('name') or input_elem.get_attribute('id') or "[unnamed]"
+        input_type = input_elem.get_attribute('type') or 'text'
+        print(f"  - {name} ({input_type})")
+
+    # Take screenshot for visual reference
+    page.screenshot(path='/tmp/page_discovery.png', full_page=True)
+    print("\nScreenshot saved to /tmp/page_discovery.png")
+
+    browser.close()

package/bundles/codex/.codex/skills/testing/webapp-testing/examples/static_html_automation.py

@@ -0,0 +1,33 @@
+from playwright.sync_api import sync_playwright
+import os
+
+# Example: Automating interaction with static HTML files using file:// URLs
+
+html_file_path = os.path.abspath('path/to/your/file.html')
+file_url = f'file://{html_file_path}'
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page(viewport={'width': 1920, 'height': 1080})
+
+    # Navigate to local HTML file
+    page.goto(file_url)
+
+    # Take screenshot
+    page.screenshot(path='/mnt/user-data/outputs/static_page.png', full_page=True)
+
+    # Interact with elements
+    page.click('text=Click Me')
+    page.fill('#name', 'John Doe')
+    page.fill('#email', 'john@example.com')
+
+    # Submit form
+    page.click('button[type="submit"]')
+    page.wait_for_timeout(500)
+
+    # Take final screenshot
+    page.screenshot(path='/mnt/user-data/outputs/after_submit.png', full_page=True)
+
+    browser.close()
+
+print("Static HTML automation completed!")

package/bundles/codex/.codex/skills/testing/webapp-testing/scripts/with_server.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Start one or more servers, wait for them to be ready, run a command, then clean up.
+
+Usage:
+    # Single server
+    python scripts/with_server.py --server "npm run dev" --port 5173 -- python automation.py
+    python scripts/with_server.py --server "npm start" --port 3000 -- python test.py
+
+    # Multiple servers
+    python scripts/with_server.py \
+      --server "cd backend && python server.py" --port 3000 \
+      --server "cd frontend && npm run dev" --port 5173 \
+      -- python test.py
+"""
+
+import subprocess
+import socket
+import time
+import sys
+import argparse
+
+def is_server_ready(port, timeout=30):
+    """Wait for server to be ready by polling the port."""
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        try:
+            with socket.create_connection(('localhost', port), timeout=1):
+                return True
+        except (socket.error, ConnectionRefusedError):
+            time.sleep(0.5)
+    return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Run command with one or more servers')
+    parser.add_argument('--server', action='append', dest='servers', required=True, help='Server command (can be repeated)')
+    parser.add_argument('--port', action='append', dest='ports', type=int, required=True, help='Port for each server (must match --server count)')
+    parser.add_argument('--timeout', type=int, default=30, help='Timeout in seconds per server (default: 30)')
+    parser.add_argument('command', nargs=argparse.REMAINDER, help='Command to run after server(s) ready')
+
+    args = parser.parse_args()
+
+    # Remove the '--' separator if present
+    if args.command and args.command[0] == '--':
+        args.command = args.command[1:]
+
+    if not args.command:
+        print("Error: No command specified to run")
+        sys.exit(1)
+
+    # Parse server configurations
+    if len(args.servers) != len(args.ports):
+        print("Error: Number of --server and --port arguments must match")
+        sys.exit(1)
+
+    servers = []
+    for cmd, port in zip(args.servers, args.ports):
+        servers.append({'cmd': cmd, 'port': port})
+
+    server_processes = []
+
+    try:
+        # Start all servers
+        for i, server in enumerate(servers):
+            print(f"Starting server {i+1}/{len(servers)}: {server['cmd']}")
+
+            # Use shell=True to support commands with cd and &&
+            process = subprocess.Popen(
+                server['cmd'],
+                shell=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE
+            )
+            server_processes.append(process)
+
+            # Wait for this server to be ready
+            print(f"Waiting for server on port {server['port']}...")
+            if not is_server_ready(server['port'], timeout=args.timeout):
+                raise RuntimeError(f"Server failed to start on port {server['port']} within {args.timeout}s")
+
+            print(f"Server ready on port {server['port']}")
+
+        print(f"\nAll {len(servers)} server(s) ready")
+
+        # Run the command
+        print(f"Running: {' '.join(args.command)}\n")
+        result = subprocess.run(args.command)
+        sys.exit(result.returncode)
+
+    finally:
+        # Clean up all servers
+        print(f"\nStopping {len(server_processes)} server(s)...")
+        for i, process in enumerate(server_processes):
+            try:
+                process.terminate()
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+            print(f"Server {i+1} stopped")
+        print("All servers stopped")
+
+
+if __name__ == '__main__':
+    main()

package/bundles/codex/.codex/skills/workflow/advisory-hub/SKILL.md

@@ -0,0 +1,227 @@
+---
+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.
+
+### 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/codex/.codex/skills/workflow/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 | | |