scip-query 0.19.5 → 0.19.8

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.

package/skills/scip-query/SKILL.md

@@ -1,88 +1,59 @@
 ---
 name: scip-query
-description: Use scip-query effectively in an indexed repository. Routes questions like "how does this work?", "what will break?", "why is this broken?", "make a plan", "review this diff", or "clean this up" to the focused scip-* skill and command family.
-commands:
-  - template: 'scip-query status --capabilities'
-    when: 'Before routing: confirm the index is fresh.'
-  - template: 'scip-query plan-context <target>'
-    when: 'Default loop: anchor a plan for the routed skill.'
-  - template: 'scip-query diff-gate --json'
-    when: 'Default loop: the loop is complete only when this passes or is explained.'
+description: Use FIRST for codebase work that should rest on SCIP evidence. Routes understanding to scip-explore, prospective changes to scip-plan, failures to scip-diagnose, read-only problem finding to scip-audit, confirmed fixes to scip-improve, adoption or repair to scip-setup, and finished diffs to scip-verify.
 ---
 
-# scip-query Router
+# SCIP Query Router
 
-Use this skill only to route. A scip-query workflow is a codebase task whose claims should be grounded in the SCIP index: the compiler-derived map of files, symbols, references, calls, dependencies, and consumers.
+## Purpose
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need freshness, lookup, postcheck, or subagent rules.
+Choose one owning workflow before acting. An owning workflow is the bundled
+skill whose completion criterion matches the request: understanding, planning,
+diagnosis, read-only auditing, implementation, setup, or verification. The
+router does not perform that workflow itself.
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query status --capabilities` | Show index status for this project | freshness, generation, language shards, watcher, and optional capabilities | `complete` | Before routing: confirm the index is fresh. |
-| `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` | Default loop: anchor a plan for the routed skill. |
-| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | blocking findings with check id, message, and remediation; advisory findings; root-cause groups; changed file and symbol counts; process exit status (1 when blocking findings exist) | `bounded` | Default loop: the loop is complete only when this passes or is explained. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Default Loop
-
-For non-trivial code changes:
-
-1. Invoke `scip-concrete-plan`, anchored by `scip-query plan-context <target>`. It picks its own mode: ordinary planning by default, high-assurance only for security, money, destructive or irreversible operations, data migration, shared-state concurrency, or broad public API change. Do not demand the high-assurance certificate for routine work.
-2. Implement the plan in the smallest coherent slice.
-3. Invoke `scip-verify`.
-
-The loop is complete only when `scip-verify` passes or each remaining finding has a specific reason.
+Load `../_shared/SKILL.md` only after the owning workflow's shortlist proves
+insufficient. The shared reference contains the complete command vocabulary,
+coverage rules, and evidence contract; loading it before a route is selected
+adds choices without adding direction.
 
 ## Routes
 
-| Work                                                                                                     | Skill                         | Anchor                                            |
-| -------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------- |
-| Understand a system before answering or editing                                                          | `scip-explore`                | `system`, `trace`, `call-graph`, `dataflow`       |
-| Root-cause a bug or regression                                                                           | `scip-debug`                  | `trace`, `dataflow`, `change-surface`             |
-| Diagnose the design flaw behind a family of recurring bugs                                               | `scip-root-cause`             | `co-change`, `similar`, `refs`                    |
-| Turn a report into a fix packet                                                                          | `scip-triage-issue`           | `files`, `trace`, `affected`                      |
-| Create a code flow, dependency, or blast-radius diagram                                                  | `scip-diagram`                | `call-graph`, `dataflow`, `affected`              |
-| Plan a feature, fix, or refactor                                                                         | `scip-concrete-plan`          | `plan-context`                                    |
-| Run a multi-phase program: plan, delegate, verify handoffs, close                                        | `scip-conductor`              | `plan-context`, `diff-gate`, `health`             |
-| Assess public API, route, config, schema, CLI, or export changes                                         | `scip-api-impact`             | `surface`, `affected`, `co-change`                |
-| Pick language-specific high-signal commands                                                              | `scip-language-playbook`      | language row                                      |
-| Benchmark and optimize a command, workflow, or hot path                                                  | `scip-hyper-optimization`     | `bench`, `plan-context`, profiles                 |
-| Adopt or repair scip-query setup in a repo                                                               | `scip-setup`                  | `setup`, `doctor`, `capabilities`                 |
-| Verify any finished change                                                                               | `scip-verify`                 | `status`, `diff-impact`, final gate               |
-| Audit, rank, or confirm cleanup findings                                                                 | `scip-cleanup-audit`          | `health`, `cleanup-plan`, cleanup detectors       |
-| Autonomously fix confirmed cleanup findings                                                              | `scip-cleanup-improve`        | `health`, `cleanup-plan`, verified batches        |
-| Find or resolve same-name twins that have diverged                                                       | `scip-twin-drift`             | `twin-drift`, `duplicate-bodies`, `refs`          |
-| Faked or half-implemented features, checkers that never fail, dead paths behind fallbacks, lying metrics | `scip-integrity-audit`        |
-| Audit whether a status claim is derived, hedged, or merely asserted                                      | `scip-claim-audit`            | `refs`, `code`, `trace`                           |
-| Prove whether a parser/AST branch is actually reachable                                                  | `scip-probe-reachability`     | `outline --signatures`, `code`, scratch probes    |
-| Reconcile living docs with code                                                                          | `scip-doc-reconcile`          | `doc-drift`                                       |
-| Review or migrate folder ownership                                                                       | `scip-directory-architecture` | `locality-candidates`, `similar-files`            |
-| Review deeper maintainability and system compression                                                     | `scip-maintainability`        | `bottlenecks`, `similar-chains`, `change-surface` |
-| Review React reuse and component/hook pressure                                                           | `scip-react-maintainability`  | React duplicate and pressure commands             |
-| Review Vue reuse and SFC/composable pressure                                                             | `scip-vue-maintainability`    | Vue duplicate and pressure commands               |
-| Model a TypeScript system with TLA+                                                                      | `scip-tla-model-system`       | `plan-context`, `tla verify`                      |
-
-Routing is complete only when one owning skill is selected or the task is small enough for the default loop alone.
-
-## Tie-Breaks
-
-- "Is this implementation real / does it actually work" → `scip-integrity-audit`; "is this well-organized" → `scip-maintainability`; same-name drifted twins specifically → `scip-twin-drift`.
-- One change → `scip-concrete-plan`; a program of changes with delegation → `scip-conductor`.
-- One failing behavior → `scip-debug`; a family of similar bugs whose fixes keep recurring, or "what is really wrong with this system" backed by bug history → `scip-root-cause`; structure smells with no bug evidence → `scip-maintainability`.
-
-- Use `scip-cleanup-audit` for reports, ranking, confirmation, or recent AI-residue triage without edits.
-- Use `scip-cleanup-improve` when the user asks to fix, improve, continue cleaning, or raise health autonomously.
-- Use `scip-maintainability`, `scip-directory-architecture`, or `scip-hyper-optimization` only when the target is architecture, file ownership, or measured speed/cost rather than cleanup.
-- Use `scip-twin-drift` for same-name/near-name consolidation questions (a specific concept copied and drifted); use `scip-cleanup-audit`/`scip-cleanup-improve` for general bloat, echoes, and duplication sweeps that are not centered on one drifted twin family.
-
-## Setup
-
-If a repository has not been bootstrapped, invoke `scip-setup`. Use `scip-query setup-agent` only to refresh agent guidance, `scip-query setup-hooks --json` only to repair project-local hooks, and `scip-query setup-ci` only when the user explicitly asks for CI setup.
+| The request starts from… | Owning skill | Completion criterion |
+| --- | --- | --- |
+| Existing code that must be understood, traced, or diagrammed | `scip-explore` | Entry points, flow, dependencies, consumers, and remaining uncertainty are evidenced. |
+| A proposed feature, refactor, migration, API change, performance campaign, TLA+ model, or multi-phase program | `scip-plan` | Current flow, affected consumers, reuse decisions, ordered slices, validation, and risks are explicit. |
+| A failure, regression, recurring bug family, raw issue, or parser/AST reachability question | `scip-diagnose` | The observed failure is connected to a cause, rivals are rejected, and the smallest fix packet is defined. |
+| A question about whether problems exist, without permission to edit | `scip-audit` | The scoped items are classified and ranked with evidence; no code or docs are changed. |
+| Confirmed cleanup, drift, maintainability, frontend, directory, twin, or documentation findings that should be fixed | `scip-improve` | One coherent finding slice is changed and passes its routed postchecks. |
+| First adoption, broken setup, missing capabilities, skill installation, hooks, CI, or uninstall | `scip-setup` | The workspace is ready, or every unavailable capability has an explicit blocker. |
+| A finished diff that must be challenged before commit or release | `scip-verify` | Workspace, impact, applicable postchecks, gate findings, and refutation attempts are all accounted for. |
+
+## Disambiguation
+
+- Existing behavior with no symptom routes to `scip-explore`; a contradiction
+  or failure routes to `scip-diagnose`.
+- Finding and classifying problems without edits routes to `scip-audit`;
+  changing already-confirmed findings routes to `scip-improve`.
+- Prospective work routes to `scip-plan`; a concrete finished diff routes to
+  `scip-verify`.
+- Setup wins whenever the index or a required capability is missing, stale,
+  invalid, or not yet installed.
+- A request may cross workflows in sequence. Keep one owner at a time:
+  diagnose before planning a fix, audit before improving, plan before a
+  non-trivial implementation, and verify after every implemented slice.
+
+## Default non-trivial change loop
+
+1. Invoke `scip-plan`, anchored by
+   `scip-query plan-context <target>`.
+2. Implement the smallest coherent planned slice.
+3. Invoke `scip-verify`; do not declare completion until it passes or every
+   remaining finding has a specific evidence-backed disposition.
+
+Routing is complete only when exactly one owner is selected for the current
+phase, or the request is small enough that no compiler-resolved relationship
+claim is needed.
 
 <!-- BEGIN GENERATED ROUTER COMMAND PREVIEW -->
 ## Command Preview
@@ -91,27 +62,11 @@ Top commands per routed skill, generated from each skill's own `commands:` front
 
 | Skill | Top commands |
 | --- | --- |
-| `scip-api-impact` | `scip-query surface <module-or-package>`, `scip-query refs <symbol>`, `scip-query affected <symbol> --json` |
-| `scip-claim-audit` | `scip-query files <pattern>`, `scip-query refs <symbol>`, `scip-query code <symbol>` |
-| `scip-cleanup-audit` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query duplicate-bodies --json --full` |
-| `scip-cleanup-improve` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query cleanup-apply --verified --batch <n>` |
-| `scip-concrete-plan` | `scip-query status --capabilities`, `scip-query plan-context <target>`, `scip-query refs <symbol>` |
-| `scip-conductor` | `scip-query plan-context <target>`, `scip-query diff-gate --json`, `scip-query health --json` |
-| `scip-debug` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
-| `scip-diagram` | `scip-query system <module>`, `scip-query trace <symbol>`, `scip-query call-graph <symbol>` |
-| `scip-directory-architecture` | `scip-query system <scope>`, `scip-query locality-candidates --json --full`, `scip-query similar-files --full --json` |
-| `scip-doc-reconcile` | `scip-query doc-drift --json --full`, `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` |
-| `scip-explore` | `scip-query stats`, `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>` |
-| `scip-hyper-optimization` | `scip-query bench --json`, `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000`, `scip-query work-audit <profile> --json` |
-| `scip-language-playbook` | `scip-query stats`, `scip-query files <feature-or-module-name>`, `scip-query outline <file>` |
-| `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
-| `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |
-| `scip-react-maintainability` | `scip-query react-component-duplicates --scope <scope> --full --json`, `scip-query react-hook-candidates --scope <scope> --full --json`, `scip-query react-large-component-pressure --scope <scope> --full --json` |
-| `scip-root-cause` | `scip-query trace <mechanism-symbol>`, `scip-query co-change <fix-site-file>`, `scip-query system <system-scope>` |
-| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --json` |
-| `scip-tla-model-system` | `scip-query tla scaffold <file>`, `scip-query tla verify <spec>`, `scip-query tla instrument <spec>` |
-| `scip-triage-issue` | `scip-query files <issue-term>`, `scip-query trace <entry-or-error-symbol>`, `scip-query code <entry-or-error-symbol>` |
-| `scip-twin-drift` | `scip-query twin-drift --json --full`, `scip-query duplicate-bodies --json --full`, `scip-query code <symbol>` |
-| `scip-verify` | `scip-query doctor`, `scip-query status --capabilities`, `scip-query diff-impact --json` |
-| `scip-vue-maintainability` | `scip-query augment-vue --project <path-to-tsconfig>`, `scip-query vue-component-duplicates --scope <scope> --full --json`, `scip-query vue-composable-candidates --scope <scope> --full --json` |
+| `scip-audit` | `scip-query health --json`, `scip-query decorative-checkers --json --full`, `scip-query doc-drift --json --full` |
+| `scip-diagnose` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
+| `scip-explore` | `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>`, `scip-query affected <symbol> --json` |
+| `scip-improve` | `scip-query cleanup-plan --verify --json`, `scip-query cleanup-apply --verified --batch <n>`, `scip-query diff-gate --json --compact` |
+| `scip-plan` | `scip-query plan-context <target>`, `scip-query refs <symbol>`, `scip-query affected <symbol> --json` |
+| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --capabilities` |
+| `scip-verify` | `scip-query doctor`, `scip-query diff-impact --json`, `scip-query diff-gate --json --compact` |
 <!-- END GENERATED ROUTER COMMAND PREVIEW -->

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "SCIP Query Router"
-  short_description: "Route codebase work to SCIP skills"
-  default_prompt: "Use $scip-query to choose the right SCIP-backed workflow for this codebase task."
+  short_description: "Route a codebase task to the right SCIP skill"
+  default_prompt: "Use $scip-query first to pick the right SCIP-backed skill for this task before doing anything else."