@caddis/cli 0.4.52 → 0.4.53

package/bundles/codex/.codex/skills/workflow/advisory-hub/reference/hub-handbook.md

@@ -1,233 +0,0 @@
-# Advisory Hub — how the Hub actually validates — verdict template, checklist, techniques, plan drift
-
-> **Loaded by:** `/caddis:validate-phase` Step 2
->
-> 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.
-
----
-
-## §C — the Hub verdict
-
-```
-=== HUB VERDICT — PHASE <n> ===
-REPORT:        .caddis/advisory-hub-reports/phase-NN.report.md
-VALIDATED BY:  <hub session model/lane> on <ISO 8601 UTC>
-VERDICT:       ACCEPT | ACCEPT-WITH-CORRECTION | REJECT
-
---- RE-DERIVATION (what the HUB ran itself, not what the report said) ---
-CLAIM:     <…>
-HUB RAN:   <the literal command the Hub executed>
-HUB GOT:   <…>
-AGREES:    YES | NO | UNVERIFIABLE — <why>          (repeat per claim)
-
---- GATES RE-RUN ---
-$ <command>
-<output>
-RESULT: PASS | FAIL | NOT RE-RUN — <why>
-
---- COMMITS AUDITED ---
-$ git show --stat <sha>
-MATCHES THE PHASE'S CLAIMED TOUCHES: YES | NO — <what was unexpected>
-
---- SAFETY-RULE RE-CHECK ---
-<per rule in advisory-context §5, or N/A — none declared>
-
---- DEVIATIONS ADJUDICATED ---
-<deviation> → touches locked decision <#>? YES | NO
-           → Hub ruling: allowed | reverted | plan amended — <reason>
-
---- PLAN CORRECTIONS LANDED ---
-<what was edited in the plan file itself, section by section — or NONE>
-
---- CORRECTIONS REQUIRED BEFORE THE NEXT PHASE ---
-1. <exact fix, not a direction>
-
---- WHAT IS NOW STRUCTURAL ---            (MANDATORY — a verdict without this is incomplete)
-| Correction | Where it now lives (file + section) | The failure that earned it |
-|---|---|---|
-
-NEXT PHASE MAY START: YES | NO
-=== END VERDICT ===
-```
-
-**Where does a correction live so it cannot recur?**
-- **Telling the implementing session** — worthless. That session ends and the lesson dies with it.
-- **Putting it in the next phase's prompt** — barely better. It works once, and the Hub must remember to
-  repeat it every phase. It won't, eventually.
-- **Putting it in the durable artifact** (`advisory-context.md`) — correct. It binds every future phase
-  whether or not anyone remembers it, and it carries the failure that earned it so a later reader knows
-  why it exists rather than deleting it as noise.
-
-**A verdict that does not end in "what is now structural" is half a verdict.** And **the Hub is not
-exempt from its own contract**: if a correction traces back to advice the Hub itself gave earlier, the
-verdict says so plainly rather than attributing it to the implementer.
-
----
-
-## §D — Hub validation checklist
-
-1. **Re-derive every VALUE CHECK.** Run the re-derivation yourself. Do not read the reported result.
-2. **Re-run the exit gates**, at minimum the fast ones (unit tests, lint, type-check). Reported output can
-   be stale even when it was honestly captured.
-   **And re-run them in a DIFFERENT ENVIRONMENT from the implementer's** — see §E's
-   "re-running a gate identically is not independent verification". Re-running the same way
-   reproduces the blind spot instead of testing it. This is the sharpest known limit on the
-   Hub's one rule, and it cost a failed production deploy to learn.
-3. **`git log` / `git show --stat` the commits** — do the changes match the phase's claimed touches?
-   Anything unexpected, especially tooling/config/CI files that never appeared in DEVIATIONS?
-4. **Re-check every rule in advisory-context §5** — or record `N/A — none declared`.
-5. **Any deviation** → is it a §4 locked decision? If so it is the Hub's call, not the implementer's.
-6. **Any surprise** → does the plan's `## Current state` need correcting? Correct it **now, in the plan
-   file** (§F).
-7. **Deployed-environment smoke test at milestone boundaries** — against the environment the change
-   actually ships to, not dev. Skip cleanly when the project has no deployed environment.
-
----
-
-## §E — Hub techniques that actually catch things
-
-### Re-running a gate *identically* is not independent verification
-
-The Hub's rule is "re-derive, don't trust". Its sharpest limit: **re-deriving the same way
-reproduces the implementer's blind spot instead of testing it.**
-
-Worked example. A Hub accepted a milestone partly on *"gates genuinely ran — I re-ran the test
-suite myself, 310 passed."* The very next deploy failed on that same suite. A dependency-injected
-service built a database client **before request validation ran**, so an invalid query parameter
-returned 500 instead of 422 — but *only on the CI runner*, because the local env file is
-gitignored and every developer machine supplied it. Implementer green. Hub green. CI red.
-
-> **The rule:** for any phase touching config, a data-store seam, or a dependency-injection
-> boundary, re-run the gate under the *deprived* environment, not just again.
-> `mv <env file> aside && <test command> && mv back` is a one-step runner reproduction.
-
-Two corollaries, both earned:
-- **A regression test for this class must not depend on ambient environment.** The test that broke
-  CI was structurally incapable of catching its own bug locally. Its replacement monkeypatches the
-  dependency to raise, so it bites everywhere.
-- **Construct nothing expensive in a dependency provider or a service `__init__`.** A validation
-  error must never need a database.
-
-### Mutate the phase's riskiest DECISION, not just its named tests
-
-A phase ran three mutations; one — swapping two deliberately-different windows for each other —
-**broke nothing**, because every fixture was single-day so the two windows coincided. The suite
-looked thorough and had a hole exactly where the phase's most consequential choice lived.
-
-> When a phase's headline claim is *"these two things are deliberately different"*, mutate them
-> into being the same and check that something fails.
-
-### Mutate the GUARDRAIL, with evasion variants — not just the obvious violation
-
-A security phase shipped a guard asserting a visibility-only permission could never become a real
-gate. The Hub mutated it three ways:
-
-| Variant | Caught? |
-|---|---|
-| `require("nav.x")` — the obvious one | yes |
-| `require(SOME_CONST)` — indirection | yes, by a *different* test |
-| `require("""nav.x""")` — **triple-quoted** | **no — full evasion** |
-
-The third planted a live gate on an all-roles key and the entire suite plus both lint gates stayed
-green. Root cause: the guard was a regex plus a substring scan, kept "two ways on purpose" — but
-**both read the source as text, so they shared a blind spot rather than covering for each other.**
-
-> **Two checks that can be fooled by the same trick are one check.** Parse the language, don't
-> pattern-match its surface syntax — the parser hands back the *resolved* value, so every quoting
-> style, including ones nobody has thought of, collapses into a single comparison.
-
-Test a guardrail the way an adversary would, not the way its author imagined. On a phase whose
-whole risk is "a gate that looks real and isn't", the guard against fake gates being itself fake is
-the failure that matters most.
-
-### A test asserting the OUTCOME does not pin the INVARIANT
-
-Same phase. A documented invariant read *"break-glass admin resolves **before any database
-lookup**"*. Two tests covered it — and both created the tables first, then asserted the returned
-value. Moving the short-circuit *below* the query left every test green while destroying the
-invariant outright.
-
-> If the invariant is *"X happens without Y"*, the test must **withhold Y**. Asserting the result
-> in a world where Y is present proves only that the result is reachable, not that it is
-> independent. Here the fix was one test that never creates the tables — the omission *is* the test.
-
-### A render/build check proves it mounted, not that it is right
-
-A headless render returned `OK, 0 console errors` for a bar chart drawn upside down. Read the
-screenshot, not the exit code.
-
-### Mutation testing — the highest-value check the Hub does
-
-**A test that passes but would not fail on the bug is worthless.** Reading a test tells you almost
-nothing; breaking the code and watching the test fail tells you everything.
-
-```
-1. Back up the file the test claims to prove something about.
-2. Remove exactly the behaviour under test — the smallest possible break
-   (delete the branch, drop the argument, invert the condition).
-3. Run the project's test command for that test file.  IT MUST FAIL.
-4. Restore the file.
-5. Re-run.  IT MUST PASS AGAIN.
-```
-
-Do this for **every** phase that adds a test claiming to prove a behaviour. It takes about a minute, and
-it is the difference between "6 passed" and "6 tests that mean something." **Always restore and re-run —
-never leave a mutation in the tree.** The specific trap worth naming: dropping an argument that has a
-default silently changes behaviour *without erroring* — exactly what a mutation test catches and a code
-read does not.
-
-### A reproduction harness can DOWNGRADE a finding — build it anyway
-
-A filed finding (GLM executing an injected relay's leftover task before its own prompt) had three
-live observations behind it on one docket, and read as confirmed. Building the harness the note itself
-demanded — replay the real hook's captured stdout into a clean arena via a `--settings` SessionStart
-hook, so the installed plugin can't contaminate the arm — ran it **six** times, three as baselines
-matched to the reported conditions. **Not one reproduced.** The finding was downgraded to "not
-established," not closed: the fixes were kept anyway (cheap, and one is structural), but the writeup
-now says so plainly instead of letting three anecdotes read as a measurement.
-
-> **Three observations on one project is a pattern, not a measurement.** A harness that fails to
-> reproduce is not a wasted harness — it is the finding doing its job. Build the falsifiable test even
-> when the finding already feels certain; "confirmed by re-reading the report" and "confirmed by trying
-> to break it and failing" are different claims, and only the second is durable.
-
-**The reusable A/B method, for testing a hook whose fix is already installed:** capture the real hook's
-actual stdout (pre-fix and post-fix, run for real against a repo holding the test condition), then
-replay each capture into a **clean arena** via a `--settings` SessionStart hook. Keep the arena's own
-plugin relay-free, so the only relay text in play is the one under test — otherwise the installed
-(possibly still-unpatched) plugin injects its own and contaminates the result. Each arena is its own
-git repo, so the evidence is files and commits, not a transcript read.
-
-### Re-run the cross-review yourself
-
-A report's own internal contradiction (CLEAN in one section, "pending" in another) is settled in one
-command by just running it directly. **If a cross-review provider times out, try the other configured
-provider before recording "inconclusive."** A single provider's outage is not grounds for skipping
-independent review — on the reference run, the second provider found the real bug the first had missed.
-
-### Read the copy, don't trust "verbatim copy"
-
-When a phase claims to have copied a function/config/pattern verbatim, read it line by line against the
-original. The easiest thing to drop silently is an argument with a default — dropping it changes
-behaviour without erroring.
-
-### Check the report against itself
-
-Read the report once as a *document* before validating a single claim. Internal contradictions — a
-verdict field disagreeing with a details field, a model name that doesn't match the claimed lane — have
-found real problems as often as checking the code has.
-
----
-
-## §F — Plan drift is the Hub's job
-
-Nothing else in caddis owns *"the plan turned out to be wrong, correct it mid-flight."* The Hub is the
-natural owner, and it is the step most likely to be skipped. Any SURPRISE that contradicts the plan's own
-`## Current state` gets corrected **in the plan file, now** — not noted in the verdict for later, not
-left for the next reader to reconcile.
-
----
-

package/bundles/codex/.codex/skills/workflow/advisory-hub/reference/report-contract.md

@@ -1,94 +0,0 @@
-# Advisory Hub — the phase report contract — what an implementing session must file, verbatim
-
-> **Loaded by:** `/caddis:implement`, in Advisory-Hub mode, at report-filing time
->
-> 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.
-
----
-
-## §B — the phase report contract
-
-Every implementation phase, in Advisory-Hub mode, ends by writing this block **to a file**
-(`.caddis/advisory-hub-reports/phase-NN.report.md` — §H), never just to chat. **A report without re-derivable
-evidence is not a report.**
-
-```
-=== PHASE REPORT FOR ADVISORY HUB ===
-PLAN:          <path to the plan file>
-ADVISORY CTX:  <path to <slug>-advisory-context.md>
-PHASE:         <n> — <title>
-MILESTONE:     <M<n>, or N/A>
-MODEL/LANE:    <tier> / <lane>              (the model you ACTUALLY ran on)
-DATE:          <ISO 8601 UTC>
-STATUS:        COMPLETE | BLOCKED | PARTIAL
-
---- COMMITS ---
-<sha> <subject>                             (one line per commit — including tooling,
-                                              config, and non-source files)
-FILES CHANGED: <n> (+<added>/-<removed>)
-
---- EXIT GATE: verbatim command + verbatim output ---
-$ <the literal command the plan names>
-<paste the real terminal output — do not summarise, retype, or tidy it>
-RESULT: PASS | FAIL                          (repeat this triple per gate)
-
---- VALUE CHECK ---
-CLAIM:                   <the number or behaviour this phase asserts>
-RE-DERIVED BY:            <the exact independent query/command/script — copy-pasteable,
-                          not a description of one>
-RE-DERIVATION RETURNED:  <what it actually returned>
-MATCH:                   YES | NO
-
---- PROJECT SAFETY RULES ---
-RULES IN SCOPE: <rule ids from advisory-context §5, or NONE DECLARED>
-RULE <id>:  APPLIES THIS PHASE: YES | NO — <why>
-            EVIDENCE: <the check that was run + its output, or N/A>
-            RESULT: PASS | FAIL | N/A          (repeat per rule)
-
---- CROSS-REVIEW ---
-PROVIDER: <deepseek | glm | …>   VERDICT: CLEAN | ISSUES | NOT RUN (+ why)
-ISSUES ADDRESSED: <list, or NONE>
-
---- DEVIATIONS FROM PLAN ---
-<each deviation + why, or NONE>
-
---- SURPRISES / CONTRADICTIONS ---
-<anything the real data or code contradicted in the plan's `## Current state`, or NONE>
-<<< STOP CONDITION: if this section is non-empty, STOP after this phase.
-    The Hub owns the plan correction — you do not. >>>
-
---- NOT DONE ---
-<anything in the phase left undone + why, or NONE>
-
---- NEXT PHASE READY: YES | NO ---
-=== END REPORT ===
-```
-
-### Non-negotiables for the report itself — each earned by a real failure
-
-- **Verbatim means verbatim.** A phase once filed a fabricated framework stack-trace line — one that
-  wasn't even valid syntax in that language — in the one section whose entire value is being trustworthy.
-  Once output is reconstructed, the Hub has to re-run everything, which defeats the section's whole
-  point. If output genuinely cannot be captured, **say so** — that is fine. Inventing it is not.
-- **Reconcile the report against itself before filing.** One report's CROSS-REVIEW said `CLEAN` while its
-  DEVIATIONS said "verdict pending" — both cannot be true. Read your own report once as a document before
-  submitting it.
-- **Report the model/lane you actually ran on.** One report named a first-party model for a session
-  actually running on a third-party lane. The Hub uses this field to judge whether a lane is trustworthy
-  for later phases; get it wrong here and the whole lane experiment is uninterpretable.
-- **Report every commit**, including tooling, config, CI, and non-source files. A phase once shipped a
-  deploy-pipeline change that never appeared in its own DEVIATIONS section.
-- **Never edit the plan to make your own gate pass.** Run it, report the failure and why, and let the Hub
-  fix the plan.
-- **A re-derivation crib's numbers must match the final committed diff, not an earlier point in
-  implementation.** One crib was true when written against a 6-test file, then stale by filing time
-  because a late fix added 2 more tests — the same mutation against the final 8-test file gave a
-  different result. The crib wasn't fabricated or self-contradictory (none of the other five rules would
-  have caught it) — it was just stale. **If a late change touches what a crib measured, re-run the crib's
-  own commands before filing.**
-
----
-

package/bundles/codex/.codex/skills/workflow/advisory-hub/reference/succession.md

@@ -1,118 +0,0 @@
-# Advisory Hub — handing the role over — the mechanical audit, the self-check trap, the carried-open ledger
-
-> **Loaded by:** `/caddis:spawn-hub` · `/caddis:handoff` Step 2b
->
-> 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.
-
----
-
-## §G — The mechanical handoff audit
-
-**A context doc is written BEFORE the work happens, so it is ALWAYS stale by the time it is needed.** The
-outgoing Hub's honest first instinct, asked "can we hand off," is always *"yes, the context doc is
-designed for exactly this"* — and that instinct has been measured and found wrong: a real audit found
-seven gaps in a context file the outgoing Hub believed was current, including the single highest-value
-technique the Hub had developed by then.
-
-**Do not ask "are there gaps?" Assume there are, and find them mechanically:**
-
-1. **List every technique, decision, and correction you actually used this session** — from your own
-   actions in this transcript, not from re-reading the context doc. Candidates: did you re-run something
-   with a second provider after a timeout? mutation-test a seam? apply a fix instead of only flagging it?
-   adjudicate a deviation against a locked decision? correct the plan? fix an index/README in passing?
-2. **For each, check whether the context doc's *instruction itself* already covers it** — not whether the
-   word merely appears somewhere. Would a fresh Hub, reading only that file, be told to do the same
-   thing?
-3. **The caveat that will burn you:** a literal-string grep over prose produces **false MISSINGs**. A
-   `0 matches` result means "this exact string isn't here," **not** "this isn't covered" — real content is
-   often phrased differently than the search term. **Read the section before trusting a grep's absence.**
-   Search by concept, read the surrounding paragraph, don't stop at the first non-match.
-4. **Land every real gap as a durable rule** in the right section of the advisory-context, carrying the
-   specific failure that earned it. A note left "for later" is not a fix.
-
-`/caddis:handoff` runs this audit as its Step 2b, whenever the active plan has a companion
-`advisory-context.md` — see that command for the wiring.
-
----
-
-## §I — Hub succession: the Hub is a ROLE, not a conversation
-
-A long plan outlives any one session. The Hub runs as a **numbered series**, each handing to the
-next through *files* — never chat history. **Write this convention down at the start, not when
-someone asks.** On the reference project three Hubs had already run on hand-written prompts before
-anyone noticed there was no convention; it was written only when the user asked "what were the
-rules for spawning a new Hub?" and the answer was *there aren't any*.
-
-Keep a table in `advisory-context.md`:
-
-| Hub | Covered | Ended because |
-|---|---|---|
-| 1 | pre-Phase-0 setup | context |
-| 2 | Phases 0–1 | context |
-| 3 | Phases 2–6, two deploys | context |
-| 4 | Phases 7+ | — |
-
-### What a new Hub does before validating anything
-
-1. **Read, in order:** `advisory-context.md` (all of it) → the plan's milestones, execution protocol
-   and tracker → the project's rate/measurement rules → the most recent 2–3 verdicts.
-2. **Prove the context landed** by answering a self-check *before* touching a phase (§J).
-3. **Verify the tree independently.** `git fetch`, then count divergence yourself — never trust a
-   relay file's number. Also **`git status` and diff any dirty file before treating it as
-   authority**: a plan's working copy was once found carrying an *uncommitted revert* that deleted
-   the rules a Hub was about to read, behind a clean-looking `git log`. A committed rule is only as
-   durable as the working copy the next session opens.
-4. **Run the mechanical handoff audit (§G) early**, while context is still thick — not at the end.
-
-### A Hub may amend its predecessor's verdict — that is the mechanism working
-
-Amend **in place, in the verdict file, with an attributed block**, so the record shows both the
-original judgement and why it moved. On the reference project a fresh Hub — working only from files,
-with no shared history — downgraded its predecessor's ACCEPT to ACCEPT-WITH-CORRECTION *and* caught
-a deploy-blocking bug that the implementer, two cross-review passes and the prior Hub had all
-missed. **That is the single strongest argument for this pattern.**
-
----
-
-## §J — The context self-check, with a deliberate trap
-
-The handoff prompt must force an incoming Hub to *prove* the context landed. Ask it to:
-
-- **re-derive one anchor number live** (not quote it);
-- name the decisions that are **accepted but reversible**, and what would reverse them;
-- state where the next deploy gate is **and how it determined that**;
-- say what it must do before its own handoff;
-- name one thing a green automated check does **not** prove.
-
-**Include at least one question whose naive answer is wrong.** The reference project's is *"what is
-the funnel's `offered` count, and why is it NOT `SUM(OfferedInd)`?"* — the naive read gives 3,814,
-the correct one 4,783, because the raw flags do not nest. A Hub that only skimmed **fails visibly
-instead of silently**, which is the entire point.
-
-### Four rules that make the self-check mean something
-
-Shared with `/caddis:spawn-session`, which transfers the WORK where this transfers the ROLE. Both
-run on `scripts/caddis_spawn.py`, so a fix lands in both.
-
-1. **DERIVE the questions from what CHANGED. Do not choose them.** An agent picking its own exam
-   picks what it remembers, which is the thing under test. Spread them: oldest settled decisions
-   catch a successor that read only the recent sections; the newest changes catch one that read only
-   the summary.
-2. **A SUPERSEDED fact is the highest-signal question there is**, because the obvious answer is the
-   stale one. The measured discriminator was *"which model serves chat?"* — the answer had changed
-   **twice**, and naming only the most recent replacement proved the history had not been read.
-3. **Every question must be answerable from a committed file**, verified with
-   `caddis_spawn.py verify-question`, not assumed. A question whose answer is not written down tests
-   memory — the thing this mechanism replaces.
-4. **Store NO answer key. Re-derive at validation time.** A stored key freezes the outgoing agent's
-   belief: if it was wrong, the key is wrong and the check certifies the error. Re-deriving validates
-   the DOCUMENT as well as the reader — and validating only the reader is precisely what failed, when
-   a Hub passed a thirteen-question check on a handover containing four factual errors.
-
-**Six questions maximum.** Past six the successor writes an essay and the outgoing agent skims it.
-
----
-