@caddis/cli 0.2.4 → 0.2.6

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

@@ -0,0 +1,233 @@
+# 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/antigravity-plugin/skills/advisory-hub/reference/report-contract.md

@@ -0,0 +1,94 @@
+# 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/antigravity-plugin/skills/advisory-hub/reference/succession.md

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

package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md

@@ -37,7 +37,7 @@ Start by understanding the current project context, then ask questions one at a
 ## After the Design
 
 **Documentation:**
-- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Write the validated design to `.caddis/plans/YYYY-MM-DD-<topic>-design.md`
 - Apply `.github/instructions/document-frontmatter.instructions.md` when creating or updating the design doc
 - Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git

package/bundles/antigravity-plugin/skills/code-review/SKILL.md

@@ -120,3 +120,10 @@ try {
 - [ ] No obvious performance issues
 - [ ] Code is readable and documented
 - [ ] Breaking changes documented
+
+## Machine Verdict (automated / headless runs)
+
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`REVIEW: CLEAN` (no blocking issues found across the categories above) or `REVIEW: BLOCKING` (one
+or more blocking issues). Automated runners read only this line; it must exactly match one of
+those two forms.

package/bundles/antigravity-plugin/skills/context-curator/SKILL.md

@@ -55,7 +55,7 @@ If the context package is written as a standalone Markdown handoff or context do
 | Intent Document | `agent-docs/intents/<feature>.md` | Goal, Constraints, Success Criteria |
 | Pipeline state | `.github/pipeline-state.json` | Current stage, approved gates |
 | Project config | `project-config.md` | Tech stack, constraints, brand tokens |
-| Current plan step | `.github/plans/<feature>.md` | Current phase/step only |
+| Current plan step | `.caddis/plans/<feature>.md` | Current phase/step only |
 
 ### Tier 2 — Include When Relevant (SHOULD READ)
 | Item | Source | What to extract |

package/bundles/antigravity-plugin/skills/cross-review/SKILL.md

@@ -10,25 +10,78 @@ Run a cross-vendor review of the current changes with a DIFFERENT model family t
 is green and before you commit, or for a second opinion on a risky diff. This is the *cross-vendor*
 complement to `/caddis:code-review`, not a replacement.
 
-## Prerequisite (one-time)
-A provider key must be resolvable. Precedence: `REVIEW_API_KEY` > the provider's own env var
-(`DEEPSEEK_API_KEY` / `GLM_API_KEY`) > `OSS_API_KEY` > the keys file (`~/.caddis/keys.env`,
-overridable via `CADDIS_KEYS_FILE`). If your keys file is populated, no env setup is needed.
-Details: the `coding/cross-review` skill and the **Providers & keys** guide.
+## Step 0 — check the key BEFORE reading the diff
+
+```bash
+python "$TOOL" --check-config      # resolve $TOOL first, see "Run it" below
+```
+
+Exit 0 means ready; it prints which providers have a key. **Exit 3 means nothing is configured —
+STOP and ask the user now.** Do not proceed to the review, and do not silently skip it.
+
+Ask with `AskUserQuestion`: which provider to set up (DeepSeek, GLM, or another OpenAI-compatible
+endpoint), then write the key they give you to `~/.caddis/keys.env` as `DEEPSEEK_API_KEY=<key>` (or
+the matching variable) and re-run the check. **The keys file lives outside every git repo, so it
+cannot be committed by accident. Never put a key in the repo, in a command, or in your reply.**
+
+**Why asking is the fix, and why the script does not do it.** This used to fail at the point of use
+— mid-task, with a commit pending, which is the worst moment to go hunting for a credential. A
+command that fails once at an inconvenient moment does not get retried, so the safety check is
+quietly lost and nothing records that it was lost. But `oss_review.py` also runs headless, from CI
+and from `claude -p` sessions, where a prompt on stdin does not ask a question — it hangs forever.
+So the script answers *"is it configured?"* and **you** do the asking.
+
+If a key exists for a different provider than the one requested, the error names it and gives you
+the exact flag (`--provider glm`). Read the message before concluding anything is missing.
+
+**Key precedence:** `REVIEW_API_KEY` > the provider's own env var (`DEEPSEEK_API_KEY` /
+`GLM_API_KEY`) > `OSS_API_KEY` > the keys file (`~/.caddis/keys.env`, overridable via
+`CADDIS_KEYS_FILE`). Details: the `coding/cross-review` skill and the **Providers & keys** guide.
 
 ## Run it
-Locate the tool (stdlib-only, no install), in order:
-- `.github/tools/oss_review.py` — this project vendors its own copy.
-- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every install has this;
-  use it whenever the project has no local copy).
+Resolve the tool path deterministically — check only these two exact locations, in order, and
+**never search the filesystem for it** (see Rules below):
+```bash
+# THE PLUGIN COPY WINS. It is the one `caddis update` refreshes; a vendored copy is a snapshot
+# of whatever caddis shipped the day someone copied it, and it never updates again.
+if [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py" ]; then
+  TOOL="${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py"
+  # A vendored copy that DIFFERS is a live hazard, not a curiosity — say so, do not stay silent.
+  if [ -f ".github/tools/oss_review.py" ]      && ! diff -q ".github/tools/oss_review.py" "$TOOL" >/dev/null 2>&1; then
+    echo "[cross-review] WARNING: .github/tools/oss_review.py differs from the caddis copy and is"
+    echo "               being IGNORED. Delete it, or keep the local change deliberately."
+  fi
+elif [ -f ".github/tools/oss_review.py" ]; then
+  TOOL=".github/tools/oss_review.py"   # no plugin present — the vendored copy is all there is
+else
+  echo "oss_review.py not found at either known location — report this and stop. Do NOT search for it."
+  exit 3
+fi
+```
+
+> **Why the plugin copy is first.** It used to be second. On 2026-08-10 a repo ran a stale vendored
+> `oss_review.py` and got `REVIEW: CLEAN` on a database write path that was never reviewed. The bug
+> had been fixed on 2026-08-01 — the fix just never reached the caller, because a file someone
+> copied weeks earlier silently won. `caddis_gate.py vendor-drift` now fails on the same condition.
 ```
-python <resolved-path>/oss_review.py                     # DeepSeek eyes (default)
-python <resolved-path>/oss_review.py --provider glm      # GLM eyes
-python <resolved-path>/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
+python "$TOOL"                                           # DeepSeek eyes (default)
+python "$TOOL" --provider glm                            # GLM eyes
+python "$TOOL" --range $ARGUMENTS                        # review a git range, e.g. origin/main..HEAD
 ```
 Optional: `--base-url <url>`, `--model <id>` (env always overrides the preset).
-**Alternate the provider between reviews** (DeepSeek one diff, GLM the next) — different model
-families have different blind spots, and alternation maximizes what the pair catches over time.
+
+**A large diff is batched, not refused.** Over `REVIEW_MAX_DIFF_CHARS` (default 60,000) the tool splits
+on whole-file boundaries and reviews each batch, and the verdict is CLEAN only if every batch is. Exit 2
+now means the narrower case — a **single file** too big to split, or more batches than the cap. When you
+see it, the fix is usually to review that one file separately, not to narrow `--range`; don't raise
+`--max-diff-chars` blind.
+
+**Do not alternate providers on a schedule.** DeepSeek is the default because it has actually found real
+bugs that same-vendor passes missed; GLM is the documented fallback, used automatically when DeepSeek is
+unavailable and you did not name a provider. The policy lives in `oss_review.py`'s `FALLBACK_PROVIDERS`
+comment — a rota that sends half your phases to a provider observed timing out three phases running buys
+variety it never actually collects, and a review that silently does not happen is the same failure class
+as a diff that silently is not read. Name a provider explicitly only when you have a reason.
 
 ## Interpret the exit code
 - **0 — REVIEW: CLEAN** → no blocking issues. Proceed.
@@ -41,3 +94,7 @@ families have different blind spots, and alternation maximizes what the pair cat
 - Read-only second opinion — the tool never edits, commits, or pushes. YOU apply fixes in the main thread.
 - Treat exit 2/3 as blocking-unknown, never as approval (the tool is fail-closed by design).
 - A different vendor means a different style; weigh its findings on merit, don't cargo-cult them.
+- **Never use `find`, `Get-ChildItem -Recurse`, or any other filesystem-wide search to locate
+  `oss_review.py`.** Check only the two paths above. On Git Bash under Windows, `find /` (or any
+  search rooted at `/`) walks every mounted drive, not just the repo — it can hang or take minutes.
+  If neither path exists, stop and report it; don't go hunting for the file.

package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/SKILL.md

@@ -7,9 +7,9 @@ description: Re-measure an app's dashboard/API endpoints for load-time regressio
 # dashboard-perf-sweep — re-measure, then judge the shape, not just the time
 
 Today an app "earns" the rs-kit refresher pattern only when someone happens to be doing unrelated
-work on it, hits a slow page, and measures it properly. That worked for rev-sight and serve-sight,
-but a snapshot measurement goes stale — a page added last month, or a table that crossed a growth
-threshold since, has no mechanism to surface itself. This skill re-measures on demand.
+work on it, hits a slow page, and measures it properly. That worked for a couple of apps in the
+fleet, but a snapshot measurement goes stale — a page added last month, or a table that crossed a
+growth threshold since, has no mechanism to surface itself. This skill re-measures on demand.
 
 **What already exists and must NOT be rebuilt:** every app in the fleet has its own
 `.caddis/kb/dashboard-performance-tracker.md` with real baseline measurements. The gap this closes
@@ -40,14 +40,14 @@ growing. Time alone is not sufficient evidence — the fleet's own history prove
 
 | App | Cold time | Root cause | rs-kit? |
 |---|---|---|---|
-| serve-sight | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
-| rev-sight (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
-| appointment-assist | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
-| nps-lens | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
-| app-sight | 202ms | n/a — never crossed gate 1 | **NO** |
+| App A | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
+| App B (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
+| App C | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
+| App D | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
+| App E | 202ms | n/a — never crossed gate 1 | **NO** |
 
-A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged appointment-assist and nps-lens.
-That already happened once before the shape distinction was made explicit — don't repeat it.
+A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged App C and App D. That already
+happened once before the shape distinction was made explicit — don't repeat it.
 
 ## Step 1 — build the endpoint list for this app
 
@@ -103,12 +103,12 @@ Force these questions, in order, for each slow endpoint — don't skip to a verd
 1. **Does response size explain most of the time** (large payload, not a slow query)? → not rs-kit;
    recommend trimming fields / gzip / virtualization.
 2. **Is the slow part parsing/serialization, not the DB round-trip?** → not rs-kit; recommend
-   caching/warming the parsed form (nps-lens precedent).
+   caching/warming the parsed form (App D precedent).
 3. **Does the query scale with total stored rows rather than the response size** — read the actual
    SQL/query plan, not just the timing — **and is the same aggregation recomputed per request on data
    that keeps growing?** → candidate for rs-kit.
 4. **Is it slow only at deep pagination (OFFSET)?** → not rs-kit; recommend keyset paging
-   (`exception_id`-style cursor, rev-sight R6/P3 precedent).
+   (`exception_id`-style cursor, App B precedent).
 5. **Is a specific WHERE clause unseekable** (function-wrapped column, NVARCHAR/VARCHAR param
    mismatch)? → not rs-kit; recommend an index or a param-type fix.
 
@@ -124,9 +124,9 @@ being able to see a before/after. Print a summary alongside the file edit.
 
 ## Validating this skill against known ground truth
 
-Before trusting a new app's output, or after changing the checklist, run the sweep against an
-already-known app and confirm it reproduces the **already-established, human-verified** conclusion:
-**app-sight** (202ms, should conclude "not a candidate") and **serve-sight** (known breach, should
-conclude "aggregation-shaped, rs-kit candidate" for the pages already identified). If the output
-disagrees with the known-good conclusion for either, that's a checklist bug — fix the checklist, don't
-rationalize the disagreement away.
+Before trusting a new app's output, or after changing the checklist, run the sweep against two
+already-known apps in your fleet and confirm it reproduces the **already-established, human-verified**
+conclusion for each: one that's genuinely fast (should conclude "not a candidate") and one with a
+known aggregation breach (should conclude "aggregation-shaped, rs-kit candidate" for the pages
+already identified). If the output disagrees with the known-good conclusion for either, that's a
+checklist bug — fix the checklist, don't rationalize the disagreement away.