scip-query 0.19.4 → 0.19.6

package/skills/scip-improve/references/twin-drift.md

@@ -0,0 +1,35 @@
+# Twin drift
+
+Use when the same concept exists in more than one place under the same or a near-name and the bodies have silently diverged — same-name or near-name functions across files with diverged bodies, drifted policy thresholds, one-sided fixes, or consolidating a duplicated concept into one canonical helper.
+
+A twin drift group is a same-leaf-name family of callables spanning at least two files whose normalized-token bodies are neither identical (that's `duplicate-bodies`' job) nor unrelated (a homonym like `render` or `parse`), but partially overlapping — a concept copied once and edited independently in only some copies. "Near-name" means case-insensitive match, or edit-distance ≤ 2 for names of 8+ characters.
+
+## Detect
+
+Run `scip-query twin-drift --json --full` to surface every DIVERGENT and near-name group in scope; scope it with `-s/--scope <path>` when the review should be bounded. Cross-check against `scip-query duplicate-bodies --json --full` — IDENTICAL groups belong there, not here; don't re-report them. Homonyms (similarity below `--min-similarity`, default 0.3) are noise — skip them unless `--include-homonyms` was explicitly requested. Record group count, member count, and `maxDivergence` per group. Done only when every group in scope is enumerated with its relationship (divergent vs. suppressed homonym).
+
+## Classify
+
+For every DIVERGENT group, read each member's body with `scip-query code <symbol>`, starting from the group's `firstDivergentTokens` field to locate where the bodies diverge. Assign exactly one label with a one-line reason:
+
+- **Intentional variation** — the domains genuinely differ (e.g., a React-specific vs. Vue-specific structural comparator branching on framework-specific checks). Essential variation stays; record the reason.
+- **Drifted policy** — one policy (a threshold, a normalization rule, an edge-case guard) only some copies received when it last changed. This is a bug: pick the correct value and propagate it, or extract the policy into one named function/constant.
+- **One-sided fix** — one copy was bugfixed or hardened and its twin(s) weren't. This is a bug: apply the same fix to every member, or consolidate.
+
+Done only when every DIVERGENT group has one of the three labels with its reason.
+
+## Consolidate
+
+Pick the canonical member by comparing consumer counts via `scip-query refs <symbol-in-file-A>` and `scip-query refs <symbol-in-file-B>` — prefer the member with more consumers, or the one in the more general/shared location on a tie. Extract or move the canonical body to one exported helper and update the other members to call it, or delete them outright if they were pure duplication under a different name for caller convenience. Preserve classified-essential variation as a parameter or a thin caller-side branch, not a second copy of the whole body. For intentional-variation groups, don't force consolidation — record the reason in a comment near one of the members so the next `twin-drift` run and the next reader both see it was considered.
+
+Done only when every DIVERGENT group is either consolidated (old copies gone or forwarding) or has a recorded reason it stays separate.
+
+## Verify
+
+Rerun `scip-query twin-drift --json --full` to confirm consolidated groups no longer appear as DIVERGENT, then run the routed postchecks from `scip-verify`. The twin-partner check inside `diff-gate` is advisory and never blocks the gate by itself — but a finding there on your own diff means you've reproduced the exact defect class this skill exists to catch; treat it as a signal to run this workflow, not just to suppress the finding. Fix it or explicitly accept it before finishing.
+
+Done only when `twin-drift` shows no unclassified DIVERGENT groups in scope and any `diff-gate` findings are resolved or explained.
+
+## Report
+
+Scope, groups found (total / divergent / suppressed homonyms), each divergent group with its classification and action taken, and the verification results of `twin-drift --json --full` and `diff-gate --json`.

package/skills/scip-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: scip-plan
+description: Use before, during, AND after non-trivial work: plan a change, migration, or refactor; assess what breaks when changing a public export, module boundary, schema, route, CLI command, config field, generated artifact, signature, or documented behaviour; conduct a multi-phase program and review a delegated agent's work mid-flight; plan a performance campaign; scaffold a TLA+ model before implementing, and trace-check it against the real system afterward. Distinct from the `review` skill, which reviews a finished branch or PR against coding standards and the originating spec — this one oversees a program you are conducting.
+commands:
+  - template: "scip-query plan-context <target>"
+    when: "Anchor the current flow, consumers, reuse options, and change risks."
+  - template: "scip-query refs <symbol>"
+    when: "Complete or narrow the direct consumer set for a planned symbol change."
+  - template: "scip-query affected <symbol> --json"
+    when: "Measure transitive impact when the change is not consumer-local."
+---
+
+# scip-plan
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` | Anchor the current flow, consumers, reuse options, and change risks. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | referencing file paths; reference line numbers grouped by file | `bounded` | Complete or narrow the direct consumer set for a planned symbol change. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Measure transitive impact when the change is not consumer-local. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Purpose
+
+Plan and conduct work: a single non-trivial change, public-surface impact, a multi-phase program carried end to end with verification at each handoff (including reviewing a delegated agent's work in flight), a benchmark-driven optimization campaign, and TLA+ modelling both before implementation and as post-implementation trace-conformance.
+
+Shared mechanics (lookup tips, command families, postchecks, subagent-briefing text, general command catalogue) live in `../_shared/SKILL.md` — load it only when this skill's own shortlist is insufficient.
+
+## Pick the mode first
+
+| Situation | Do this |
+|---|---|
+| One non-trivial change, refactor, migration, or bug fix | Ordinary-mode scenario below |
+| The change touches a security boundary, money, a destructive/irreversible op, a persistent-data migration, shared-state concurrency, a broad public API, or an unrollback-able rollout — or the user asks for the rigorous version | `references/high-assurance.md` |
+| You're about to edit a public export, route, schema, CLI command, config field, generated artifact, or documented behavior, and need to know what breaks | `references/api-impact.md` |
+| You're running a multi-phase program: writing an executable plan, delegating steps, reviewing a subagent's work mid-flight, or carrying a change end to end | `references/conductor.md` |
+| You need something faster and must prove the speedup with measurements | `references/hyper-optimization.md` |
+| You need a TLA+ model of a risky protocol, before or after implementation | `references/tla-model.md` |
+
+Picking the mode matters: running the high-assurance certificate on routine work is how planning becomes a tax people route around. When genuinely unsure whether a change needs a heavier mode, ask rather than defaulting up.
+
+## Scenario: plan a single non-trivial change (ordinary mode, the default)
+
+Start with `scip-query status --capabilities` to confirm the index is fresh before citing graph facts — reindex only if the index is stale, missing, or unknown. Then run `scip-query plan-context <target>` — the single anchoring call for planning. Its composite return already includes definitions, references, callers, callees, dataflow producers/consumers, forward and backward slices, affected symbols, change-surface risk, dependencies and reverse dependencies, module exports, external surface use, complexity, churn, co-change partners, and active suppressions, so the job is to interpret this composite rather than rebuild a proof system on top of it.
+
+Reach for a second command only when a section `plan-context` returned came back bounded (not complete) or the target wasn't indexed: `scip-query refs <symbol>` to enumerate consumers in full, `scip-query affected <symbol>` for the transitive blast radius when the change isn't consumer-local, `scip-query code <symbol>` to read the source behind a behavior claim before writing it into the plan.
+
+Write the plan to `docs/plans/YYYY-MM-DD-<short-name>.md` with these sections:
+
+- **Goal** — what the user is trying to accomplish, and what done looks like for them.
+- **Current Flow** — the affected path from entry point to observable effect, in prose, with evidence behind each claim; if current behavior can't be described end to end, the change isn't ready to make.
+- **Affected Consumers** — who calls/imports/reads the changed code and what breaks if the contract shifts; state explicitly whether the list is complete or bounded — a capped list presented as complete is worse than one flagged as bounded.
+- **Reuse Decision** — for every new helper/wrapper/type/parameter/flag/component/hook/module, name what it could have extended instead and why extension loses. New parallel code with no reuse decision is the single most common defect this skill exists to prevent.
+- **Slices** — ordered implementation steps, each naming its files/symbols, the behavior change, and the validation (a test, command, or specific manual check) that proves it. A slice with no validation is a wish.
+- **Risks and Unknowns** — what could go wrong, what couldn't be established, and any rollout constraint; keep unknowns explicit rather than rounding them to assumptions.
+
+The plan is done only when: the entry-to-effect path is described and evidenced, every affected consumer is assigned to a slice or explicitly out of scope, every new unit has a reuse decision, every slice has validation, and unknowns are written down rather than resolved by guessing. Then implement in the smallest coherent slice and run `scip-verify` when the change lands.
+
+## Owned command quick-reference
+
+`bench`, `work-audit` → performance campaigns, see `references/hyper-optimization.md`.
+`tla`, `tla scaffold`, `tla verify`, `tla instrument`, `tla trace-check`, `tla fetch-tools` → model scaffolding and conformance, see `references/tla-model.md`.
+
+Everything else used above (`plan-context`, `refs`, `affected`, `code`, `surface`, `co-change`, `doc-drift`, `diff-gate`, `health`, `call-graph`, `complexity`, `change-surface`, ...) is general catalogue — see `../_shared/SKILL.md` for the full vocabulary.

package/skills/scip-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Plan & Conduct"
+  short_description: "Plan and conduct work with SCIP evidence"
+  default_prompt: "Use $scip-plan to plan this change, assess what it breaks, and conduct it through to verified completion."

package/skills/scip-plan/references/api-impact.md

@@ -0,0 +1,19 @@
+# Public-surface impact
+
+Use before changing anything another process or person depends on: a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior. Its defining trait: a local edit can force coordinated consumer, docs, tests, or migration changes outside the implementation file.
+
+## Scenario: assess what breaks before editing a public surface
+
+**Step 1 — identify the actual surface.** Run `scip-query surface <module-or-package>`, `scip-query outline <file>`, `scip-query trace <symbol-or-command>`, `scip-query code <symbol-or-command>`, and `scip-query hierarchy <symbol> --json`. Done only when the real surface is named as one of: member, class, module, package, route, schema, command, or config field.
+
+**Step 2 — find consumers.** Run `scip-query refs <symbol>`, `scip-query fan-in <symbol>`, `scip-query rdeps <file>`, `scip-query affected <symbol> --json`, and `scip-query change-surface <file> --json --full`. Record direct consumers separately from transitive consumers. Done only when direct breakage and regression blast radius are both known.
+
+**Step 3 — find hidden partners.** Run `scip-query co-change <file> --json --full` (files historically coupled without a dependency edge), `scip-query doc-drift --json --full` (docs describing the surface), `scip-query similar <symbol> --json --full`, and `scip-query similar-files <file> --json --full`. Docs, generated files, tests, and config count as part of the API when they describe or enforce the surface. Done only when docs, generated files, fixtures, sibling APIs, and hand-synchronized partners are accounted for or ruled out.
+
+**Step 4 — choose the migration shape.** Pick one of: compatible extension, two-step migration, breaking coordinated change, or an adapter shim for external consumers/compatibility windows. Prefer backward-compatible migrations when consumers are broad or external. Reject speculative new parameters or empty wrappers using `scip-query unused-params --json --full`, `scip-query wrapper-candidates --json --full`, and `scip-query passthrough-candidates --json --full`. Done only when the migration shape explains deploy order, rollback, and compatibility risk.
+
+**Step 5 — write the plan and verify.** Plan template: Surface; a Consumer dispositions table (Consumer | Kind: direct/transitive/doc/config/test | Disposition: unchanged-safe/update/shim/defer); Required co-changes; Migration; Verification (targeted tests, `scip-query diff-impact --json`, `scip-verify`, `scip-query doc-drift --json --full` if docs changed, `scip-query config-validate` if config changed). Every consumer returned by refs/affected must appear as a row — a blank disposition means the analysis is unfinished. Non-indexed consumers (SQL, fixtures, dynamic strings, external callers) must be checked with `rg` and rowed the same way as indexed consumers.
+
+After editing, run the routed checks from `_shared` and invoke `scip-verify`. The workflow is complete only when direct consumers, docs/config partners, and scip-verify have all been checked.
+
+Final report shape: API impact (low/medium/high); Surface changed; Consumers; Migration plan; Co-changes; Verification; Remaining risk.

package/skills/scip-plan/references/conductor.md

@@ -0,0 +1,41 @@
+# Conducting a multi-phase program
+
+This governs running a program of work — planning, delegation, review, closure — across multiple steps, not how to write a single change plan (use the main SKILL.md's ordinary-mode scenario, or `references/high-assurance.md`, for that). Act like a skeptical principal engineer.
+
+Key commands: `scip-query plan-context <target>` anchors each phase's step before delegating it; `scip-query diff-gate --json` verifies a handoff before accepting it and before closing the program; `scip-query health --json` pre-registers or checks a program-level health benchmark.
+
+## The three laws
+
+1. **A green result you have never seen fail is unverified.** This applies to tests, gates, reports from other agents, and your own checks (the integrity scenario in `scip-audit` applies the same law to code, where available).
+2. **A plan is a contract for a less-capable executor, not a note to self.** If a competent-but-uninspired agent could not execute a step without guessing, the step is not finished being written.
+3. **Nothing is silent.** Every finding, deviation, and shortcut must be either fixed or written down with a reason someone else would accept. 0% silent is the invariant — "fixed everything" is not.
+
+## Scenario: write the program plan
+
+State DONE MEANS falsifiably in the Goal — a command someone can run and a result they can check, not an aspiration. Pre-register acceptance benchmarks before any work: measure the current number (test count, timing, finding count, proof line), write it in the plan, and state the target number; work that cannot move a pre-registered number is scope to question.
+
+Every plan step carries five fields: a file anchor with verified current behavior (cite how you know), the exact change, the validation command with expected output, a testability design (pure core, injected effects), and why this step is safe in this order. "Update X" with no current/target behavior is a wish, not a step.
+
+Order phases by information gain and risk: blockers and evidence-integrity first, cheap discriminating probes before expensive builds, measurement before optimization, and anything not yet decided by the human becomes a GATED phase the executor must not start. Infrastructure that later steps inherit (a labeling choke point, a shared helper layer) must land before the features that need it. Flag one-way doors with their migration path, and keep an explicit DEFER list so cut scope is visible instead of forgotten.
+
+Working agreement to include in the plan: ONE COMMIT PER STEP — bisectability is non-negotiable, and phase-level commits hide which step broke. Gate commands must be the FULL gate set the repo defines per phase — tests, typecheck, lint/format, and build — not just focused tests, because focused tests hide cross-phase regressions and omitting the linter is how red mains ship. Include regeneration duties and a deviation protocol: if source contradicts an anchor, BLOCKED-note it and continue; never improvise silently.
+
+## Scenario: delegate and review a handoff
+
+Delegate breadth, keep judgment: fan out mechanical/scoped work to subagents, but personally own anything requiring taste, cross-cutting context, or the final word on "is this real." Concurrent agents must get disjoint write scopes, named in their briefs; if a collision happens anyway, stop racing, apply-verify-commit atomically in one action, and re-sequence to a single writer.
+
+Never accept a report at face value — reproduce its evidence. On every handoff, choose the minimal discriminating probe (the one command most likely to expose the report being wrong: a mutation input, a hand count, the benchmark number) and run it yourself; a report verified only by reading it is not verified. Loop until `scip-query diff-gate --json` is quiet: fix, re-run the discriminating probe, re-run the gate, and only then move on.
+
+Verify your verifier: a gate check that cannot fail is no gate (e.g. a lint grep that only matches one linter's output, a diff-gate run on a clean tree, a test suite that skips the new path) — prove the check catches a planted failure once before trusting its green. After any "all green," ask what that check does NOT cover (eslint vs prettier; unit vs integration; clean-tree vacuity).
+
+## Git and commit discipline
+
+Never run `git checkout`/`restore`/`stash` on a tree with uncommitted work, yours or anyone's; revert probe edits by targeted deletion instead, and if source is lost, check `dist/*.map` sourcesContent before panicking. Commit working states early and surgically using explicit paths, never `add -A` on a shared tree; an unbisectable pile of work is a liability. Make commit cadence mechanical: at every step boundary run the arithmetic check "steps completed == commits made"; if they differ, stop and commit before touching anything new. "I'll commit when it's all done" is the signature decay pattern of a long or low-effort run — in two real executions this rationalized delay led to finishing an entire plan with zero or one commit, with the deviation rationalized mid-run rather than decided; a self-check that is a count (not a feeling) prevents this rationalization.
+
+## Closing the program
+
+After the program, fold what was learned back into the durable layer (docs, skills, followups) — insight that lives only in the conversation is lost. Escalate only genuine decision points — one-way doors, scope changes, taste, spending; for everything else, decide, act, and disclose.
+
+Every conducted program and every plan written under this skill must end with a self-report checklist mapping each section above to concrete evidence: pre-registered benchmarks and their before/after values, each handoff's discriminating probe and its OBSERVED result (a probe listed but not run counts as not run), the deviation ledger, the DEFER list, and which learnings were folded back and where — so a reviewer can audit the conduct, not just the artifact.
+
+The program is complete only when: every pre-registered benchmark is met or its miss explained; every handoff probe is run and recorded; the gate is quiet on the final state; nothing is silent (every finding fixed or ledgered); and the self-report is written.

package/skills/scip-plan/references/high-assurance.md

@@ -0,0 +1,43 @@
+# High-assurance planning (the certificate)
+
+Load this only when the change meets a documented trigger: a security boundary or authorization decision, money/billing/external financial effect, a destructive or irreversible operation, a persistent-data migration, shared-state concurrency, a broad public API change, a rollout that cannot be rolled back, or the user explicitly requests the rigorous version. For ordinary work this protocol costs more than it protects — its cost lands on every future change routed through it. When genuinely unsure, ask rather than defaulting up.
+
+A high-assurance plan is a **certificate**: a dated Markdown document whose "ready to implement" conclusion is derived from numbered, source-cited premises, defended against constructed counterexamples, and shaped so intended behavior is easy to test before it is easy to ship.
+
+## Definitions (state these with referents, not by assertion)
+
+- **Premise** — a numbered, source-cited statement of fact about the current code (P1, P2, ...); steps and defenses cite it by ID so a false premise is traceable to everything built on it. Literal source facts cite a native file read; compiler-resolved identity and complete writer/reader/caller/dependency/consumer/impact sets cite scip-query.
+- **State-authority premise** — a premise enumerating the complete writer and reader sets of one shared state surface, made falsifiable by `refs` and `dataflow`, turning a forgotten write path from unknowable into a checkable omission.
+- **Invariant** — a property of the changed system that must hold at every observable moment, stated in "iff" or "must always" form; the final verdict is derived from whether it survives every attack.
+- **Contract** — the stable promise one code unit exposes to another: accepted inputs, returned outputs, errors, timing expectations, and side effects callers may rely on.
+- **Reuse audit** — the part of a plan that proves a proposed new symbol/file/option/wrapper/contract is needed, by tying the new shape to existing definitions, consumers, and rejected extension points. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until this proves reuse or extension is not the better move.
+- **Test seam** — the entry point a test can call to prove a behavior without replaying the whole product path; must name the exact unit or boundary where correctness will be observed.
+- **Side-effect boundary** — the edge where deterministic program decisions meet files, processes, clocks, networks, databases, or other external capabilities, so failures and fakes can be isolated there while core decisions stay easy to test.
+- **Counterexample attack** — a concrete actor, starting state, and action sequence constructed to violate an invariant, whose defense cites premises and steps so "we considered failure" becomes "this specific failure is blocked here."
+- **Enforcement window** — the interval between the step that installs an invariant enforcer and the step that brings the last existing writer into compliance; during it, every unupdated writer fails the new check in production, so the plan that adds safety can itself be the outage.
+
+Every load-bearing concept gets a `Source:` line with referents — a definition without referents is a guess. Place each concept in its wider class, then name the one trait that causally explains its other traits in this codebase, written as prose (not labeled genus/differentia). Circular and synonym definitions are banned (e.g. "the refresh coordinator coordinates refreshes" defines nothing). Good definitions condense: they imply the concept's other traits instead of listing them, so derived requirements fall out automatically — e.g. if "restore" is defined as the inverse of "cancel," the privilege to restore must not be weaker than the privilege to cancel, and a plan gating them asymmetrically must defend that asymmetry. A claim with no supporting premise is either new evidence to gather or must be marked an explicit ASSUMPTION — never left silent.
+
+## The six-step procedure
+
+**Step 1 — Discover.** Run `scip-query status --capabilities` then `scip-query plan-context <target>` before filling in Goal, Definitions & Invariants, Current State, and Reuse Audit. Done only when concepts are defined with referents, invariants are stated formally, and every proposed new unit has a reuse decision with citations.
+
+**Step 2 — Establish Premises.** For every state surface the plan touches (database column, store field, event topic, endpoint, cache entry), write one state-authority premise enumerating its complete writer and reader sets, established via `refs` and `dataflow` rather than memory. Case study: a sprint-restore plan hardened `restore()` and the cancellation path but never enumerated the writers of sprint status; review later found `PATCH /sprints/:id` could set `status:'active'` around every restore invariant, and transition automations wrote `sprintId` straight past the new membership guard — two of that review's five ship-blockers, both sitting in the writer list a single `refs` call would have produced. Done only when every state surface named in any phase has a state-authority premise and every remaining unknown is an explicit ASSUMPTION.
+
+**Step 3 — Shape for Tests.** Shape plans so tests can call the pure core directly and exercise the side-effect shell with injected replacements. Preferred code shape: (1) parse and validate at the boundary, (2) pass domain data and injected dependencies into a small orchestrator, (3) put calculations/filtering/selection/formatting/state-transition decisions in pure functions, (4) keep database/network/filesystem/clock/randomness/logging/email/payment calls in thin side-effect shells, (5) depend on small contracts at boundaries and avoid broad option objects, booleans that hide behavior, and forwarding-only wrappers. Done only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
+
+**Step 4 — Design the Checklist.** Write phases in execution order; keep each phase deployable or explicitly mark why it is not. Each checklist step needs: file anchor with line range; cited premises; a Deployable yes/no declaration (with reason or single-deploy group name); current behavior verified from source (What); the exact edit (Change); a full testability breakdown (test seam, injected dependencies, pure core, side-effect shell, contract); and a Validation entry (test, smoke command, or manual check). If a step installs an enforcer, check its enforcement window: every existing writer in the relevant state-authority premise is brought into compliance in the same or an earlier step, or the window is carried into the attack record as a hole to accept or repair. Done only when no checklist item says "update this file" without exact current behavior, target behavior, cited premises, a deployability declaration, and validation.
+
+**Step 5 — Attack the Plan.** This pass is falsification, not defense — it should find holes against a draft. Prefer delegating it to a fresh subagent: give the adversary only the Definitions & Invariants, Premises, state-authority maps, and checklist (not the design rationale), and brief it that it wins by producing holes; fold findings back as HOLE entries and repair steps. Solo fallback: enumerate the full attack list from the coverage-matrix rows before writing any Outcome line, so attacks are not shaped around defenses already in hand. Use these lenses as attack prompts: purpose, blast radius, valid intermediate state, reversibility, failure, concurrency, boundaries, data integrity, observability, human experience, efficiency, reuse, testability.
+
+Each attack record states an invariant and lens, an Attack (actor + starting state + action sequence), and an Outcome: HELD (defended by step N.M citing premises), HOLE — repaired by new step N.M, or HOLE — accepted with reason. A HELD outcome that cannot name its defending step and premises is not HELD — it is "a hole wearing confidence." An assertion of absence (e.g. "no new shared mutable state is introduced") is never a valid defense, because it cannot fail and therefore cannot catch anything. Invalid example that preceded three post-review remediation rounds on a real plan: "Concurrency: Validation happens before database writes; no new shared mutable state or retry behavior is introduced." — no actor, no interleaving, cites nothing. Valid contrast: "A3. Every stored value is a member of its field's option set via concurrency — Attack: admin removes option O in transaction A while a user writes value O in transaction B; interleaving B-validates → A-commits → B-commits persists an orphaned value. Outcome: HOLE — repaired by new step 2.2: validation reads the option definition outside B's lock (P4), so serialize definition changes with every value writer via FOR UPDATE on the definition row; regression proves both interleavings against PostgreSQL."
+
+A repaired hole keeps its "HOLE — repaired by step N.M" label permanently and must never be rewritten to HELD, because the repair history is the evidence the pass falsified; the verdict's repaired count must equal the number of HOLE — repaired entries. Close the record with a coverage matrix — one row per writer in every state-authority premise and per applicable lens (valid intermediate state is always applicable when any step installs an enforcer or migration); a blank row is an unattacked writer, and the record is incomplete until every row names an attack or carries an accepted reason. Spread attacks across coverage-matrix rows before deepening any single one — depth on an axis already anticipated does not protect axes that were not; leaks come from blank rows, not from the tenth variation of an already-modeled race. An attack record where nothing ever broke is a red flag — rerun the pass as falsification, preferably in a fresh subagent context. Done only when the coverage matrix has no blank rows and every attack entry ends in a cited HELD or a recorded HOLE.
+
+**Step 6 — Verify and Derive the Verdict.** Phase-by-phase reference verification (run or delegated) confirms: every path exists, every line range is still within about five lines, every premise reproduces when its Source command is rerun (a premise that no longer reproduces is false and everything citing it is suspect until fixed), every behavior claim matches source, every new unit has reuse evidence, and every behavior-changing step has cited premises, a validation command, and a testability design. After reference verification, rerun `scip-query plan-context <target>` for the cited targets to reconfirm the source-producing context.
+
+Verdict template: "A plan is PLANNED-COMPLETE iff the coverage matrix has no blank rows, every attack ends in HELD with cited steps and premises or an accepted hole with a written reason, and no premise failed reverification," followed by a Result line stating PLANNED-COMPLETE or INCOMPLETE plus attack/hole counts and unresolved items. The attack/hole counts are part of the verdict itself — e.g. "16 attacks, 0 holes repaired" against a fresh draft signals an attack pass that defended instead of falsified, and should be rerun before shipping. Done only when stale references are fixed, every premise is reverified, and the verdict line is derived from the attack record.
+
+## Document section order
+
+Title and date; Goal; Definitions & Invariants; Premises (incl. state-authority premises and explicit assumptions); Current State (narrative citing premise IDs); Reuse Audit; Testability Design; Design Phases (steps citing premises, each with deployability declaration); Attack Record (attacks with outcomes, holes repaired or accepted, coverage matrix); Execution Order and deployable phase notes; Ship Order with one-way doors flagged; Verdict with attack and hole counts; Summary of files to create, edit, delete, and verify.

package/skills/scip-plan/references/hyper-optimization.md

@@ -0,0 +1,50 @@
+# Performance optimization campaigns
+
+For making a command, workflow, service, page, or tool faster without changing its observable result. Hyper optimization is a bounded campaign that improves runtime, memory, or computational cost against repeatable measurements. Campaign-level conduct (delegation, handoff verification, benchmark pre-registration across multiple phases) belongs to `references/conductor.md`; this file is the performance-domain method that runs inside it or standalone for a single target.
+
+If the repo is not a reliable scip-query workspace, invoke the `scip-setup` skill first, before starting an optimization target.
+
+## Choose QUICK or CAMPAIGN
+
+- **QUICK** — a single command/function target with an obvious hot path: capture one `docs/benchmarks/runs/YYYY-MM-DD-<target>.jsonl` baseline, skip the ledger and the rest of the campaign artifact set, fix the hypothesis, measure after, done.
+- **CAMPAIGN** — multiple targets, an unclear bottleneck, or a decision between competing designs: requires the full machinery — baseline doc, ledger, profiling, and an alternative-design track.
+
+Decide with one test: if you can already name the one function you expect to fix and a single before/after number will settle it, use QUICK; if naming that function requires investigation or the fix might be architectural, use CAMPAIGN.
+
+## Definitions
+
+- **Measurement harness** — the repeatable set of commands, fixtures, corpora, environment notes, and result documents used to decide whether performance changed.
+- **Run history** — the durable time series of measurements, one record per run, command, subprocess, or profiled stage.
+- **Profile span** — one named timed piece of work inside the target process (input loading, cache reads, database queries, graph traversal, rendering, a child process, ...).
+- **Hierarchical profiling** — measuring coarse spans first, then recursively splitting only the dominant span until the expensive operation is concrete enough to fix.
+- **Command ledger** — the living document for one optimization target: output contract, current pipeline, timings, tried ideas, and decisions.
+
+## Scenario: target-and-harness (both modes)
+
+For a scip-query command target, start with `scip-query bench --json` (baseline timings, command outcomes, environment, optional sampled profiles), then `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000` for cold-path and heavy-detector timings. Do not optimize until a measurement harness exists or is created. Capture representative inputs, the output contract, and correctness checks before editing anything for performance. Record every benchmark in machine-readable run history; measure cold and warm paths separately when they can diverge. Choose the target from user pain, telemetry, benchmark ranking, regression data, cost, frequency, or risk.
+
+Artifacts: CAMPAIGN mode creates/updates `docs/benchmarks/YYYY-MM-DD-<target>-baseline.md` (QUICK mode skips this file); both modes create/update `docs/benchmarks/runs/YYYY-MM-DD-<target>.jsonl` — the one required run-history artifact in every mode.
+
+Done only when baseline timings, output identity evidence, corpus, environment, and run-history location all exist.
+
+## Scenario: the ledger (CAMPAIGN only)
+
+QUICK mode skips this and goes straight to tracing behavior, using the single run-history file as its record. Write `docs/benchmarks/YYYY-MM-DD-<target>-ledger.md` with sections: Output Contract, Target Selection, Current Pipeline, Run History Location, Profile Spans, Bottleneck Candidates, Measurements, Current-Pipeline Optimizations, Alternative Designs, Decisions. Done only when the ledger can explain what must not change.
+
+## Scenario: trace behavior
+
+Run `scip-query plan-context`, `trace`, `call-graph`, `code`, `dataflow`, and `complexity` on the entry/hot symbol — `call-graph <entry-symbol>` returns callers/callees, `complexity <hot-symbol>` returns LOC, branch, complexity, callee, fan-in/out counts — then `scip-query change-surface <touched-file> --json --full` to verify blast radius. Record input parsing, option resolution, subprocesses, lookups, database queries, graph traversal, source scans, semantic calls, cache reads/writes, rendering, serialization, and verification. Done only when each major pipeline step can be timed as a profile span.
+
+Before adding profiling spans, check whether the target app already has an instrumentation layer — a bespoke profiling harness competes with the one the codebase already trusts. When the optimization target is scip-query itself, its instrumentation is `src/instrumentation/profile.ts` (`profileSpan`/`profileAsyncSpan`), env-gated by `SCIP_QUERY_PROFILE` and `SCIP_QUERY_PROFILE_OUT`, with `SCIP_QUERY_PROFILE_CACHE_STATE` for cache-state labels and inherited workload/subsystem identities — use it instead of adding a parallel harness.
+
+## Scenario: profile the chain
+
+Measure the target unprofiled, then measure profiled once and compare overhead. Measure distinct states: cold index, cold evidence/cache fill, warm cache hit, repeated focused run, production-like mixed state. Add coarse spans covering the whole chain, then split the largest workload-weighted span, repeating until the slow operation is a repeated lookup, initialization, scan, traversal, subprocess, serialization step, or wait. Attach cardinality to spans: files, rows, symbols, candidates, cache hits/misses, bytes, edges, nodes, retries, or output rows — write span records with cardinality to run history. When spans carry work identities, run `scip-query work-audit <profile> --json` on the profiling JSONL to separate exact repeats from same-name work on different inputs, ranking repeated-work groups by measured avoidable time (bounded coverage). Done only when the dominant cost is concrete enough to form a falsifiable hypothesis.
+
+## Scenario: diagnose and fix
+
+Classify the dominant performance shape as one of: cold-only setup, warm slow path, repeated setup, N+1 work, broad scan, database time, subprocess startup, serialization, or cache invalidation. Prefer fixes in this order: remove accidental repetition; batch scalar work; move stable derived work to an index/cache with invalidation; replace broad scans with indexed lookups; replace wrapper APIs only after output identity proves equivalence; add pruning only when mathematically equivalent or corpus-proven. Make the smallest reversible change that tests one hypothesis at a time. Work both tracks in parallel — tune the current pipeline and evaluate alternative algorithms or data models — and keep only changes that improve real workloads without reducing accuracy, diagnostics, safety, or supported inputs. Reject faster changes that alter the output contract unless the user explicitly approved a behavior change. Done only when before/after timings, profile deltas, and output identity are recorded.
+
+## Scenario: verify, report, and close
+
+Run the narrow correctness check, benchmark cases, and routed postchecks, then invoke `scip-verify`. End the campaign with a scoreboard from run history containing: starting value, current value, delta, scenario, corpus, commit/version, output identity, accepted changes, rejected ideas, remaining bottlenecks, and next target.

package/skills/scip-plan/references/tla-model.md

@@ -0,0 +1,88 @@
+# TLA+ modeling with code evidence
+
+Use when a TypeScript system needs a TLA+ model tied to code evidence — before implementing a risky protocol, or as post-implementation trace-conformance against the real system. A **modeled slice** is the bounded part of the real system represented by the model: state, transitions, inputs, outputs, and failure modes.
+
+Model the part of the system with the most dangerous interleavings — retries, concurrency, partial failure, money, state machines with guards. Never model a linear happy path: a model that cannot meaningfully fail verifies nothing. If the state space would exceed roughly a million states, the model is too concrete; collapse data you never branch on and replace unbounded values with small symbolic sets.
+
+## Commands
+
+- `scip-query tla scaffold <file>` — starts a new model: derives a draft spec, config, and mapping from indexed code.
+- `scip-query tla verify <spec>` — mechanical conformance: checks referents, reads/writes, calls, and runs the model checker.
+- `scip-query tla instrument <spec>` — generates a trace recorder plus wiring sites for each mapped action.
+- `scip-query tla trace-check <spec> --trace <file>` — semantic conformance: checks a recorded execution against the model's Next relation.
+- `scip-query tla fetch-tools` — downloads the pinned tla2tools.jar into the cache when the model checker is unavailable.
+
+## Scenario: scaffold a model from code
+
+`scip-query tla scaffold <file>` requires the target file to own mutable module-level state (a `let`/`const` plus a writer function) or, failing that, a class whose instance fields a method of that same class writes; a file of pure functions or constants is rejected — pick the file that holds the state, not the file that only computes over it. `--out` must stay inside the project root.
+
+Scaffold calls `getDefinitionsForFile(db, file, { includeClassMemberFallbacks: true })`, which surfaces class-member fallback rows (`ClassName#field.` symbols with a real definition mention) alongside primary rows even when the file has other primary-indexed definitions — verified live with the `Watcher` class in `src/runtime/watch.ts`, so concurrency classes like locks, connection pools, or watchers now scaffold correctly. What remains genuinely invisible to scaffold is narrower: a file where the indexer emitted no member row for a class at all (neither a primary `defn_enclosing_ranges` row nor a `role=1` definition mention) — scaffold reports "no mutable state discovered" because there is nothing in the index to find. When that happens, model by hand from `plan-context`/`trace` evidence instead of via scaffold.
+
+TRIAGE the scaffold output first: if discovered variables are mostly constants and the system's real state lives in files or a database (locks, caches, published artifacts), keep the mapping referents but discard the scaffolded variable set — hand-model the protocol's conceptual state and bind it with resource aliases instead.
+
+## Scenario: the modeling loop
+
+1. **Explore.** `scip-query plan-context <target>`, `system`, `trace`, `call-graph`, `dataflow` until state and transitions are concrete.
+2. **Scaffold.** `scip-query tla scaffold <file>` to generate the draft spec, config, and mapping.
+3. **Resolve every TODO the scaffold emits** — guards, domains, initial values. The scaffold derives what changes; you must supply when it may change. `tla verify` does not detect unfilled TODOs and will report PASS on a placeholder model — grep the spec for TODO before trusting a green run.
+4. **Verify.** `scip-query tla verify <spec> --map <map> --config <cfg>` and read the Proof line; every waiver must carry a reason you would defend in review. `--map` is usually unnecessary: if no `Spec.scip-tla.json` sits next to `Spec.tla`, `tla verify` scans sibling `*.scip-tla.json` files for one whose `module` field names this spec (project-relative `.tla` path, bare filename, or TLA MODULE identifier all accepted) and uses it automatically, printing "(matched by module field)". Two or more mappings naming the same module is a hard error listing every candidate; pass `--map` explicitly to disambiguate. Use `--checker none` only when intentionally checking the mapping without SANY, TLC, or Apalache. If the model checker fails, fix the TLA+ model before relying on conformance output.
+5. **Instrument and trace-check.** Wire the recorder from `scip-query tla instrument`, run the existing tests with `SCIP_TLA_TRACE=<path>` set, then run `scip-query tla trace-check <spec> --trace <path>`. Acceptance means the code's observed behavior is a behavior of the model; divergence names the step to investigate. When modeling a fix-vs-regression pair as two named Next relations in one spec (e.g. `NextCurrent`/`NextVulnerable`), pass `--next <operator>` to pick which one the trace must satisfy — the harness defaults to a bare `Next`, which such specs deliberately don't define.
+6. **Classify every finding** as code bug, model bug, mapping bug, insufficient trace/alias evidence, or accepted non-modeled behavior.
+7. **Patch code, model, or mapping and rerun** until only explicitly waived uncertainty remains.
+
+Done only when `tla verify` passes with reasoned waivers, at least one recorded trace passes `tla trace-check`, and unexercised actions are listed as accepted gaps.
+
+## Model quality rules
+
+- **TypeOK first** — write the type invariant before any property; it catches most modeling mistakes at the lowest checking cost.
+- **Every invariant needs a failure story** — before running TLC, write down the concrete scenario that would violate it; if no scenario exists, the invariant is decorative and should be deleted or replaced.
+- **Falsify every invariant individually** — for each invariant there must be a documented variant or mutation under which TLC refutes it (the CurrentSpec/VulnerableSpec pattern makes this permanent instead of a throwaway edit); an invariant no variant can violate is decorative and should be deleted or redesigned.
+- **Break the model on purpose** — after the first green run, remove one guard or widen one domain and confirm TLC catches it, then restore it; a spec that cannot fail proves nothing.
+- **Safety before liveness** — add fairness only when a liveness property demands it; check deadlock unless termination is intended.
+- **Bound the space deliberately** — use small symbolic constant sets, symmetry where sound, and short sequences; nondeterministic `\in` transitions from the scaffold are permissive placeholders that should be tightened to concrete transitions as you learn the code.
+
+## Trace divergence and regression models
+
+Divergence taxonomy: a missing model transition means the model is too strict; an impossible recorded state means instrumentation projects the wrong slice; a genuinely illegal code transition is a bug and requires writing the regression model before fixing it.
+
+A **regression model** is a small TLA+ module or checker config derived from a counterexample, production bug, or suspected transition. Fast workflow: preserve the full model as source of truth, create a companion regression spec/config named for the failure and seeded from the exact counterexample trace (a diverging trace-check output is already that trace), prefer bounded constants and narrowed action sets over weakening the main model, run the regression first after each patch then run the full model after it passes, and keep the regression if it protects future behavior.
+
+If code changed but the model did not, inspect whether the mapped transition changed meaning; `diff-gate` flags the changed referents.
+
+## The mapping contract
+
+Top-level fields: `module`, `config`, `scope`, `variables`, `actions`, `invariants`, `traces` (see the example mapping for `specs/Queue.tla`). Mapping code entries must resolve through `scip-query trace`; variables must map to value-like symbols (a const, let, field, or property holding runtime state — never a type).
+
+**Four state backings:** program variables use normal aliases, filesystem-backed state uses resource bindings, SQL-backed state uses statements bindings, and ORM-backed state with no literal SQL uses ormCalls bindings — only genuinely dynamic SQL or an unmatched ORM shape still needs a waiver naming the residual class; never fake attribution.
+
+- **Resource mapping** binds a variable to filesystem state — a lock file, a published artifact — anything the model treats as owned state but code only touches through path-taking calls, never a plain assignment. The conformance scanner classifies `writeFileSync`/`rmSync`/`renameSync`/`mkdirSync`/`unlinkSync` calls whose first argument's text contains the declared resource path as writes, and `readFileSync`/`existsSync`/`statSync` calls the same way as reads. Matching is textual containment, not a resolved value — evidence tier stays static-action, and a resource-bound variable still needs a value-like code referent for the kind check.
+- **Statements mapping** (feature Q2) binds a variable to SQL-backed state — prepared statements, table rows behind `db.prepare(...)`/`.exec(...)`/tagged templates — via entries shaped `{ "pattern": "<substring or regex>" }` compiled as a RegExp. Any call expression argument whose static string text (a string literal, or the static fragments of a template literal with `${...}` interpolations excluded) matches the pattern is classified by its leading SQL verb: INSERT/UPDATE/DELETE/REPLACE is a write, SELECT is a read. Dynamic SQL built by string concatenation has no static text to match and still falls through to needing a waiver. Two variables sharing a statements pattern is a mapping-load error, the same as a shared resource path.
+- **ormCalls mapping** (feature C1) binds a variable to ORM-backed state when there is no literal SQL text to match — Drizzle-style query builders such as `db.update(t).set(...)`, `db.insert(t).values(...)`, `db.select().from(t)`, `db.delete(t)` — via entries shaped `{ "table": "<identifier>", "methods"?: [...] }`. A match requires a call chain whose own method name is in the write set (update/insert/delete by default) or read set (select/query/findFirst/findMany by default) AND whose own table argument (or, for select, the `.from(t)` chain segment) names the mapped table — matching never looks at the receiver (`db`, `tx`, ...), only the method + table-arg shape. `methods` narrows the effective set to a subset of the seven-name vocabulary; an unrecognized method name fails to load. Two variables binding the same (table, method) pair is a mapping-load error — but a write-only binding and a read-only binding on the same table do not collide.
+
+**Waivers are per-fact and require a reason** — the blanket `allowUnknown` waiver is legacy and should not be used. Write/read waiver symmetry: `actions.<name>.waive.writes` exempts model-code-write, undeclared-write, and missing-write-evidence findings, the same way `waive.reads` exempts the read-side equivalents. A variable-level waive on `actions.<name>.writes` also exempts the corresponding model-mapping-write mismatch against the SANY-derived model text. A waived write still shows up in the Proof line's waiver ledger with its reason — it never silently vanishes.
+
+**Line windows** (feature C3): an action code entry can narrow itself to `file#function@L<start>-L<end>` — when several guard/branch actions share one function, a whole-function code reference forces every sibling to claim every write in it, whereas a window scopes fact collection to a sub-range so each branch action attributes only its own write. A mapping line window must fall entirely inside the referent's actual resolved span or `tla verify` reports a hard invalid-line-window error naming the file, function, and actual span — it never silently clamps back to the whole function. (Line windows are line-number-brittle by design: a later refactor that shifts lines is caught loudly by the containment check plus referent resolution, not silently mis-scanned.)
+
+**Variable-level controls.** `variables.<v>.selfAlias: false` opts out of the automatic self-name alias (default true); normally a variable's own TLA+ name is always added to its alias list, which can make an object-literal key or identifier that merely echoes the variable's name — but means something unrelated elsewhere in scope — become an unavoidable false write/read attribution. A `selfAlias: false` variable with no other alias, no resource, no statements, and no waive is a mapping load error, since it would otherwise be silently unattributable. `variables.<v>.waive: {reason}` exempts that one variable's missing-referent/invalid-referent-kind findings, for state that genuinely has no code twin (a pure control-flow position, a derived decision, a value observable only through `process.exitCode`) — but a variable-level waive does not exempt read/write facts; those stay on the action's own waive.
+
+**Scope enforcement.** Top-level `unmappedWriteScope: 'actions' | 'scope-files'` (default `scope-files`) controls strictness: the default requires every function anywhere in scope that touches a modeled variable to be mapped as an action, or its write is a hard unmapped-write error. Set it to `'actions'` to opt out of the whole-file sweep when scope legitimately contains code the mapping was never meant to cover in full — only the per-action write/read checks still run.
+
+**Init binding** (feature Q3): top-level `init: { codeRefs: ["file#function", ...], waive?: {reason} }` binds the model's Init to the code referent(s) that materialize initial state — most often a lazy-init factory. `init.codeRefs` resolves and kind-checks like an action's code field (function-like, missing-referent/invalid-referent-kind findings apply, and waive exempts both). Writes statically found inside an Init referent's own range are Init-attributed and excluded from unmapped-write findings without needing `unmappedWriteScope: 'actions'`. `init.codeRefs` must not overlap any action's code referents — overlap is a mapping-load error, the same category as a variable-alias collision. Lazy initialization is Init, not an action: a factory that lazily builds state corresponds to the model's Init and must be mapped to `init`, never to an action.
+
+## Alias discipline
+
+Alias selection is the sharpest knife: never alias a variable to a ubiquitous local identifier (`connection`, `result`, `data`), because every function touching that local gets misattributed across actions. For state with no code twin, use a deliberately unmatchable alias (e.g. `evidenceRowsModelOnly`) so the static layer neither proves nor pollutes, and let the reasoned waiver carry the fact. Turn off the forced self-alias when the variable's own name is a common word (`status`, `phase`, `state`) since object literals elsewhere in scope will otherwise match it and cause misattribution; set `selfAlias: false` and give a precise alias naming the actual stored field. Prefer an honest variable waive over citing an unrelated real symbol just to satisfy the value-like-kind check — name a referent that plainly does not resolve (or resolves to the wrong kind) and waive it, so a reader never has to guess that a `code[]` entry is a decoy.
+
+## Traces and coverage
+
+Design for traces early: the trace encoder pins scalar (and scalar-array) variables only, so a model whose state is all functions and tuple-sets cannot be trace-validated; add scalar projection variables (counts, last outcomes, a phase) alongside the structured state if trace-check matters for the slice.
+
+Trace until covered: one accepted trace proves one path, not the whole mapping — record traces until every Current action with a code twin is exercised by at least one accepted trace, or is explicitly classified with why it cannot be (unreachable without fault injection, environment-gated, model-only). An action no trace ever exercises is a conformance claim resting on static mapping alone.
+
+`tla trace-check ... --coverage` (feature C2) mechanizes coverage checking: it reports steps-exercised-per-action counted from accepted steps only (a step that never proved a legal transition — checker unavailable, or past the divergence point of a rejected trace — does not count), and names every action still unexercised. `--trace` is repeatable and merged/deduped with the mapping's own `traces` list, so recording another trace to cover a gap is additive, not a rewrite. Coverage is informational and does not change trace-check's exit code, so it never substitutes for actually closing the gap.
+
+## Accuracy and evidence tiers
+
+`tla verify` is the mechanical checker and `tla trace-check` is the semantic one — only the pair together justifies the word "conforms." A PASS with waivers is a conditional claim — the Proof line says exactly what was and was not proven, and must never be summarized as unconditional. A PASS on a scaffold with unresolved TODOs is meaningless, not conditional, since the checker has no TODO detector and will pass a placeholder model — never report a PASS without confirming the scaffold's TODOs were actually resolved.
+
+The write/read scanner follows one call hop from a mapped action's referent (no recursion) — a callee's effect on a declared fact counts as evidence and is marked "(via `<callee>`, one call hop...)" in findings. The one-call-hop scanner never asserts a new, undeclared fact: a callee shared by several actions cannot make one action silently inherit another's write. If a variable's waiver becomes provable via the one-call-hop scanner, update the waiver reason to name the real call chain instead of deleting the explanation — the evidence is still approximate since which specific runtime call path executes is not proven, only that the code family does.