@caddis/cli 0.4.52 → 0.4.53

package/bundles/codex/.codex/skills/workflow/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/codex/.codex/skills/workflow/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 | | |