scip-query 0.19.5 → 0.19.6

package/skills/scip-react-maintainability/SKILL.md

@@ -1,101 +0,0 @@
----
-name: scip-react-maintainability
-description: Review React maintainability with scip-query. Use for React, TSX, JSX, Next.js, duplicated components, hook candidates, large components, frontend health pressure, or verifying reuse after refactors.
-commands:
-  - template: 'scip-query react-component-duplicates --scope <scope> --full --json'
-    when: 'Bound and scan: duplicated JSX structure candidates.'
-  - template: 'scip-query react-hook-candidates --scope <scope> --full --json'
-    when: 'Bound and scan: shared state/effect/request extraction candidates.'
-  - template: 'scip-query react-large-component-pressure --scope <scope> --full --json'
-    when: 'Bound and scan: components carrying several reasons to change.'
-  - template: 'scip-query recent-duplicates --scope <scope> --full --json'
-    when: 'Bound and scan: recent code re-implementing established components.'
-  - template: 'scip-query similar <closest-existing-component-or-hook>'
-    when: 'Cross-check candidates: existing component or hook to reuse instead.'
-  - template: 'scip-query health --scope <scope> --json'
-    when: 'Bound and scan: frontend health pressure for the scope.'
----
-
-# scip-react-maintainability
-
-Use this skill to review React frontends as maintainable systems of components, hooks, JSX structure, and behavior lifecycles.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query react-component-duplicates --scope <scope> --full --json` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | component pairs with structural similarity evidence | `bounded` | Bound and scan: duplicated JSX structure candidates. |
-| `scip-query react-hook-candidates --scope <scope> --full --json` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers | component groups and shared hook-shaped behavior | `bounded` | Bound and scan: shared state/effect/request extraction candidates. |
-| `scip-query react-large-component-pressure --scope <scope> --full --json` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | component identities with size and responsibility pressure | `bounded` | Bound and scan: components carrying several reasons to change. |
-| `scip-query recent-duplicates --scope <scope> --full --json` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | recent and established symbol pairs with similarity evidence | `bounded` | Bound and scan: recent code re-implementing established components. |
-| `scip-query similar <closest-existing-component-or-hook>` | Find heuristic function similarity candidates from callee fingerprints | symbol pairs, similarity scores, and shared evidence | `bounded` | Cross-check candidates: existing component or hook to reuse instead. |
-| `scip-query health --scope <scope> --json` | Composite codebase health report with prioritized action list | health score, findings, priorities, baselines, and coverage notes | `bounded` | Bound and scan: frontend health pressure for the scope. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Terms
-
-A React component duplicate candidate is a pair or group of rendered structures that repeat the same user-facing arrangement, controls, states, props, or data-presentation shape enough that a shared component may reduce drift.
-
-A React hook candidate is a pair or group of component behaviors that repeat the same state lifecycle, effects, requests, validation, persistence, callback policy, or derived-data rule enough that a shared hook may preserve behavior better.
-
-Large component pressure means one component or file contains several kinds of knowledge that change for different reasons.
-
-## Workflow
-
-### 1. Bound and scan
-
-Pick the narrowest React source root, feature area, or changed-file scope that still includes likely reuse partners. Run uncapped commands:
-
-```bash
-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-query recent-duplicates --scope <scope> --full --json
-scip-query health --scope <scope> --json
-```
-
-This step is complete only when command scope, counts, and uncapped/full status are recorded.
-
-### 2. Cross-check candidates
-
-- Component duplicate only: inspect for shared presentational component or existing component reuse.
-- Hook candidate only: inspect for shared behavior, lifecycle, request, validation, persistence, or derived-state policy.
-- Both: inspect for a feature-level concept needing both component and hook boundaries.
-- Large component only: split by reason to change, not by line count.
-
-Use:
-
-```bash
-scip-query outline <file>
-scip-query deps <file>
-scip-query rdeps <file>
-scip-query similar-files --scope <scope>
-scip-query similar <closest-existing-component-or-hook>
-```
-
-This step is complete only when each top candidate is reuse, extract, split, skip, or blocked.
-
-### 3. Act on findings
-
-Prefer reuse before extraction. Extract components for repeated UI structure, states, props, slots/children, or design-system composition. Extract hooks for repeated state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence. Keep domain-specific variation at call sites when essential.
-
-This step is complete only when the chosen action reduces future drift without creating boolean-soup APIs or wrapper components with no policy.
-
-### 4. Verify
-
-Invoke `scip-verify` and use its authoritative postcheck table, including the applicable React, extraction, duplicate, parameter, wrapper, passthrough, and stale-abstraction checks.
-
-The work is complete only when acted-on candidate pairs disappear, weaken materially, or are explicitly accepted as essential variation.
-
-## False Positive Checks
-
-Shared design-system primitives, icons, labels, route names, or test IDs are not enough. Similar JSX with different domain lifecycles may justify a presentational component but not a hook. A large file is review pressure, not proof of duplication.
-
-## Report
-
-Report executive read, command evidence, candidate groups, recommended action, post-change proof, and remaining accepted variation.

package/skills/scip-react-maintainability/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP React Maintainability"
-  short_description: "Review React reuse and component pressure"
-  default_prompt: "Use $scip-react-maintainability to review React reuse, hooks, components, and frontend health pressure."

package/skills/scip-root-cause/SKILL.md

@@ -1,151 +0,0 @@
----
-name: scip-root-cause
-description: Diagnose the design flaw behind a family of related bugs with scip-query evidence. Use when similar bugs keep recurring, the same subsystem keeps needing patches, or the user lists fixed/observed bugs and asks what is really wrong; produces a falsifiable flaw diagnosis, a latent-instance hunt, and the least invasive remedy that kills the class.
-commands:
-  - template: 'scip-query trace <mechanism-symbol>'
-    when: 'Assemble the family: mechanism and violated invariant for each bug.'
-  - template: 'scip-query co-change <fix-site-file>'
-    when: 'Assemble the family: files that historically changed with each fix site.'
-  - template: 'scip-query system <system-scope>'
-    when: 'Define the system: real responsibilities, files, dependencies in and out.'
-  - template: 'scip-query similar <fixed-symbol> --json --full'
-    when: 'Predict: hunt latent instances among sibling implementations of the fixed code.'
-  - template: 'scip-query refs <invariant-carrier>'
-    when: "Predict: every site that touches the violated invariant's state."
-  - template: 'scip-query affected <remedy-symbol> --json'
-    when: 'Choose the rung: blast radius of the candidate remedy.'
----
-
-# scip-root-cause
-
-Use this skill to move from a family of related bugs to the design flaw that produces them, and to the least invasive remedy that eliminates the class. `scip-debug` takes one failure to one minimal fix; `scip-maintainability` finds structural smells without bug evidence; this skill starts from the evidence that patching has not worked — the same kind of bug keeps coming back — and asks what the system's design gets wrong.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query trace <mechanism-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Assemble the family: mechanism and violated invariant for each bug. |
-| `scip-query co-change <fix-site-file>` | Files that change together in git history without a dependency edge — hidden coupling candidates | file pairs, co-change counts, confidence, and history context | `bounded` | Assemble the family: files that historically changed with each fix site. |
-| `scip-query system <system-scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Define the system: real responsibilities, files, dependencies in and out. |
-| `scip-query similar <fixed-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | symbol pairs, similarity scores, and shared evidence | `bounded` | Predict: hunt latent instances among sibling implementations of the fixed code. |
-| `scip-query refs <invariant-carrier>` | Find all files referencing a symbol | referencing file paths; reference line numbers grouped by file | `bounded` | Predict: every site that touches the violated invariant's state. |
-| `scip-query affected <remedy-symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Choose the rung: blast radius of the candidate remedy. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Terms
-
-A bug family is a set of failures whose mechanisms violate the same invariant; what makes it a family rather than a coincidence is that one stated flaw derives every member, so fixing members one at a time treats symptoms of a shared cause.
-
-A design flaw is a mismatch between what a system's design assumes and what its real responsibilities require; what makes it the root cause is that it is the earliest fact from which every family member's mechanism follows, so removing it removes the class.
-
-Retrodiction is deriving each already-known bug from the hypothesized flaw; what makes it a test is that a family member the flaw cannot derive either shrinks the family or kills the hypothesis.
-
-A latent instance is a not-yet-reported bug the flaw predicts must exist in unfixed code; what makes it decisive is that it is checkable now — finding one confirms the diagnosis and becomes a fix target, while an honest hunt that finds none weakens the diagnosis and must be reported as weakening it.
-
-The remedy ladder is the ordered set of interventions from least to most invasive; what makes the order binding is that each rung is only justified when a constructed family member survives the rung below it.
-
-## Rules
-
-1. Every bug in the family gets a mechanism traced to source, not a symptom description: which invariant broke, where, and what the fix did. Sources: fix commits (`git log`, `git show`) plus `trace`/`code`/`dataflow`.
-2. The flaw hypothesis must be falsifiable and stated as a design claim — "the design assumes X, but the system's responsibilities include Y" — never as a narrative about unlucky bugs.
-3. State at least two rivals and kill them with evidence: unrelated coincidences, caller misuse rather than design, one missed edge case rather than a structural flaw.
-4. The hypothesis must retrodict every family member and predict at least one latent instance, and the latent-instance hunt must be executed (`similar`, `refs` over the invariant's carriers, or a constructed probe), not argued.
-5. Choose the lowest remedy rung that kills the whole class — retrodicted and latent members both. Climb a rung only when a constructed family member survives the rung below, and keep that counterexample in the record.
-6. Root-cause stories are the most rationalization-prone artifact in software: prefer delegating the attack on the diagnosis and the remedy to a fresh subagent given only the family table, system definition, and hypothesis — briefed to win by refuting. Solo fallback: write the rival hypotheses and the latent-instance predictions before reading any more code.
-7. The verdict is derived with counts, and the diagnosis hands off to `scip-concrete-plan` for implementation — this skill does not edit application code.
-
-## Workflow
-
-### 1. Assemble the bug family
-
-For each reported or fixed bug, fill one row:
-
-```markdown
-| Bug | Symptom | Mechanism (file:symbol) | Invariant violated | Fix applied | Source |
-| --- | ------- | ----------------------- | ------------------ | ----------- | ------ |
-```
-
-Evidence: the user's description, fix commits (`git log --follow`, `git show`), `scip-query trace`/`code` on the mechanism symbols, `scip-query co-change` on fix sites to find members the user forgot.
-
-This step is complete only when every row has a source-traced mechanism and a named invariant — a bug whose mechanism cannot be traced is listed as `unconfirmed member`, not silently included.
-
-### 2. Define the system
-
-Define the system that owns the family, contextually: its wider class, then the essential responsibility that explains its other traits in this codebase — with referents from `scip-query system <scope>` and `surface <scope>`. Then list the design's load-bearing assumptions as the code actually embodies them (not as the README states them), each with a `Source:` citation.
-
-This step is complete only when the system's real responsibilities and embodied assumptions are stated with citations.
-
-### 3. Hypothesize the flaw — and its rivals
-
-State the flaw as a falsifiable design claim:
-
-```markdown
-Flaw hypothesis: the design assumes <X> (Source: <citation>), but the system's
-responsibilities include <Y> (Source: <citation>); every family member is an
-instance of the X∧Y collision.
-
-Rivals:
-
-- R1. Coincidence — the members have unrelated causes. Killed by: <evidence> | ALIVE
-- R2. Misuse — callers hold the bug, the design is sound. Killed by: <evidence> | ALIVE
-- R3. <next-most-plausible> — Killed by: <evidence> | ALIVE
-```
-
-A rival still marked `ALIVE` at the end of the workflow caps the diagnosis at `CANDIDATE`, not `CONFIRMED`.
-
-### 4. Retrodict and predict
-
-Retrodiction: derive each family-table row from the flaw in one sentence each. A member that cannot be derived is removed from the family (say so) or refutes the hypothesis (start over).
-
-Prediction: the flaw implies unfixed instances exist. Name where they must be, then hunt:
-
-```bash
-scip-query similar <fixed-symbol> --json --full
-scip-query refs <invariant-carrier>
-```
-
-plus a constructed probe when the claim is cheaply executable. Record each prediction with an executed result:
-
-```markdown
-- L1. <predicted latent instance> → FOUND at <file:line> (new fix target) | NOT FOUND after <hunt executed>
-```
-
-This step is complete only when every family member is retrodicted and every prediction has an executed hunt result. Zero latent instances found is a reportable weakness of the diagnosis, not a detail to omit.
-
-### 5. Choose the lowest rung
-
-The remedy ladder, in order:
-
-1. **Enforce the invariant at a boundary** — type, guard, constraint, lint, trigger — without moving code.
-2. **Consolidate the responsibility into one owner** — the scattered decision gets one named mechanism.
-3. **Redesign the core behind its existing interface** — consumers untouched.
-4. **Redesign the interfaces** — last resort; consumers migrate.
-
-For the chosen rung, run the attack: construct a family member — retrodicted or latent — that survives the rung. If one survives, keep the counterexample in the record and climb one rung. Check blast radius with `scip-query affected` before proposing any rung above 1. For protocol- or lifecycle-shaped flaws whose remedy must hold across interleavings, note the escalation path to `scip-tla-model-system`.
-
-This step is complete only when the chosen rung has an attack record showing no family member survives it, and every rejected lower rung keeps its surviving counterexample.
-
-### 6. Report and hand off
-
-```markdown
-## Root-cause diagnosis
-
-System: <definition with referents>
-Bug family: <n> members traced, <u> unconfirmed
-Flaw: <the design claim> — CONFIRMED | CANDIDATE (rival <id> alive)
-Rivals: <r> stated, <k> killed with evidence
-Retrodiction: <n>/<n> members derived
-Latent instances: <p> predicted, <f> found (each a fix target), hunts executed
-Remedy: rung <1-4> — <the intervention>; lower rungs rejected by <counterexamples>
-Blast radius: <affected summary>
-Escalation: <none | scip-tla-model-system for <property>>
-```
-
-Hand the diagnosis to `scip-concrete-plan`: the flaw and invariants become its Definitions & Invariants, the family table and hunt results become premises, and the surviving-counterexample record seeds its attack pass.
-
-The diagnosis is complete only when the verdict line carries the counts and every count is backed by an entry in the record above it.

package/skills/scip-root-cause/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP Root Cause"
-  short_description: "Diagnose the design flaw behind a family of recurring bugs"
-  default_prompt: "Use scip-query to trace a family of related bugs to the design flaw that produces them: retrodict every member, hunt the latent instances the flaw predicts, and propose the least invasive remedy that eliminates the class."

package/skills/scip-tla-model-system/SKILL.md

@@ -1,148 +0,0 @@
----
-name: scip-tla-model-system
-description: Model TypeScript systems with TLA+ and scip-query evidence. Use to scaffold, verify, instrument, or trace-check TLA+ specs, mapping files, configs, regression models, counterexample loops, or code/model conformance for an existing system.
-commands:
-  - template: 'scip-query tla scaffold <file>'
-    when: 'Start here for a new model: derive a draft spec, config, and mapping from indexed code.'
-  - template: 'scip-query tla verify <spec>'
-    when: 'Mechanical conformance: referents, reads/writes, calls, and the model checker.'
-  - template: 'scip-query tla instrument <spec>'
-    when: 'Generate a trace recorder plus wiring sites for each mapped action.'
-  - template: 'scip-query tla trace-check <spec> --trace <file>'
-    when: "Semantic conformance: check a recorded execution against the model's Next relation."
-  - template: 'scip-query tla fetch-tools'
-    when: 'Download the pinned tla2tools.jar into the cache when the checker is unavailable.'
----
-
-# scip-tla-model-system
-
-Use this skill when a TypeScript system needs a TLA+ model tied to code evidence. A modeled slice is the bounded part of the real system represented by the model: state, transitions, inputs, outputs, and failure modes.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query tla scaffold <file>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` | Start here for a new model: derive a draft spec, config, and mapping from indexed code. |
-| `scip-query tla verify <spec>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` | Mechanical conformance: referents, reads/writes, calls, and the model checker. |
-| `scip-query tla instrument <spec>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` | Generate a trace recorder plus wiring sites for each mapped action. |
-| `scip-query tla trace-check <spec> --trace <file>` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` | Semantic conformance: check a recorded execution against the model's Next relation. |
-| `scip-query tla fetch-tools` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` | Download the pinned tla2tools.jar into the cache when the checker is unavailable. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Choose the Slice
-
-Model the part 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. `scaffold` 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.
-
-**Known boundary: files where the indexer emitted no member rows at all are invisible to `scaffold`.** `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 — a concurrency class like a lock, connection pool, or watcher (verified live: `Watcher` in `src/runtime/watch.ts` — 26 instance fields and 12 state-writing actions discovered, previously 0) now scaffolds correctly. What remains genuinely invisible 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 — has nothing for either query to return, and `scaffold` reports "no mutable state discovered" because there is nothing in the index to find. When you hit that: model by hand from `plan-context`/`trace` evidence instead of via `scaffold`. See `docs/plans/2026-07-02-catalog-class-members.md` for the K3 survey of whether other commands (`members`, `refs`, `trace`, `health`, `dead`) should opt in too — no decision has been made there yet, so this remains scaffold-only.
-
-## Loop
-
-1. Explore the target with `scip-query plan-context <target>`, `system`, `trace`, `call-graph`, and `dataflow` until state and transitions are concrete.
-2. Run `scip-query tla scaffold <file>` to generate the draft spec, config, and mapping (`--out` must stay inside the project root). Resolve every `TODO` it emits: guards, domains, initial values. The scaffold derives _what_ changes; you supply _when_ it may. TRIAGE the output first: if the 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. `tla verify` does not detect unfilled `TODO`s and will report PASS on a placeholder model — grep the spec for `TODO` before trusting a green run.
-3. Strengthen the model per the quality rules below.
-4. Run `scip-query tla verify <spec> --map <map> --config <cfg>`. 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 (the project-relative `.tla` path, bare filename, or the TLA `MODULE` identifier are all accepted) and uses it automatically, printing `(matched by module field)` — this is what makes bare `tla verify Foo.tla` work even when the only mapping on disk is named `FooHardened.scip-tla.json`. Two or more mappings naming the same module is a hard error listing every candidate; pass `--map` explicitly to disambiguate.
-5. Wire the recorder from `scip-query tla instrument`, run the existing tests with `SCIP_TLA_TRACE=<path>`, 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. 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.
-
-The loop is complete 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 — delete or replace it.
-- **Falsify every invariant individually.** One break-test is not enough: 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 — delete or redesign it.
-- **Break the model on purpose.** After the first green run, remove one guard or widen one domain and confirm TLC catches it. A spec that cannot fail proves nothing. Restore it afterward.
-- **Safety before liveness.** Add fairness only when a liveness property demands it; check deadlock unless termination is intended.
-- **Bound the space deliberately.** Small symbolic constant sets, symmetry where sound, sequences kept short. Nondeterministic `\in` transitions from the scaffold are permissive placeholders — tighten them to concrete transitions as you learn the code.
-- **Trace divergence taxonomy.** When `trace-check` diverges: 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 — write the regression model before fixing it.
-
-## Fast Regression Models
-
-A regression model is a small TLA+ module or checker config derived from a counterexample, production bug, or suspected transition.
-
-1. Preserve the full model as source of truth.
-2. Create a companion regression spec/config named for the failure, seeded from the exact counterexample trace (a diverging `trace-check` output is already that trace).
-3. Prefer bounded constants and narrowed action sets over weakening the main model.
-4. Run the regression first after each patch; run the full model after it passes.
-5. Keep the regression if it protects future behavior.
-
-## Mapping Contract
-
-```json
-{
-  "module": "specs/Queue.tla",
-  "config": "specs/Queue.cfg",
-  "scope": ["src/queue"],
-  "variables": {
-    "queue": { "code": ["src/queue/store.ts/queue"], "aliases": ["queue"] },
-    "lockOwner": {
-      "code": ["src/queue/lock.ts/LockMetadata#pid"],
-      "aliases": ["pid"],
-      "resource": { "path": "lockPath" }
-    },
-    "status": {
-      "code": ["src/queue/lock.ts/LockMetadata#lifecycleStage"],
-      "aliases": ["lifecycleStage"],
-      "selfAlias": false
-    },
-    "phase": {
-      "code": ["src/queue/lock.ts/__phase_no_stored_field__"],
-      "aliases": ["__phase_unmatchable__"],
-      "waive": { "reason": "phase is a pure control-flow position; no code field stores it" }
-    }
-  },
-  "actions": {
-    "Enqueue": {
-      "code": ["src/queue/commands.ts/enqueue"],
-      "reads": ["queue"],
-      "writes": ["queue"],
-      "waive": { "reason": "required only when a declared fact cannot be statically proven" }
-    }
-  },
-  "invariants": ["TypeOK"],
-  "traces": ["specs/queue-run.trace.json"]
-}
-```
-
-`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). Waivers are per-fact and require a reason; blanket `allowUnknown` is legacy. Waivers cover write facts symmetrically with reads: `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, and 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.
-
-An action `code` entry can narrow itself to a line window, `"file#function@L<start>-L<end>"` (C3) — when several guard/branch actions share one function, whole-function `code` forces every sibling to claim every write in it; a window scopes fact collection to that sub-range instead, so each branch action attributes only its own write. The 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 — never a silent clamp back to the whole function. Windows are line-number-brittle by design: a later refactor that shifts lines is caught loudly (the containment check plus `tla verify`'s referent resolution), not silently mis-scanned.
-
-`resource` binds a variable to filesystem state — a lock file, a published artifact — anything the model treats as owned state but that 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 `path` as writes of the variable, and `readFileSync`/`existsSync`/`statSync` calls the same way as reads. The match 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` (Q2) binds a variable to SQL-backed state — prepared statements, table rows behind `db.prepare(...)`/`.exec(...)`/tagged templates. Each entry is `{ "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 — `${...}` interpolations excluded) matches `pattern` is classified by its leading SQL verb: `INSERT`/`UPDATE`/`DELETE`/`REPLACE` is a write, `SELECT` is a read. Matching is not restricted to a callee allowlist (SQL APIs vary too much) — classification comes entirely from the matched text's leading verb. Two variables sharing a `statements` pattern is a mapping-load error, same as a shared `resource` path. Evidence tier stays `static-action`. Dynamic SQL built by string concatenation has no static text to match and still falls through to a waiver.
-
-`ormCalls` (C1) binds a variable to ORM-backed state when there is no literal SQL text to match at all — Drizzle-style query builders (`db.update(t).set(...)`, `db.insert(t).values(...)`, `db.select().from(t)`, `db.delete(t)`). Each entry is `{ "table": "<identifier>", "methods"?: [...] }`. 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 `table` attributes to the variable — matching never looks at the receiver (`db`, `tx`, ...), only the method + table-arg shape. `methods` narrows the effective set to a subset of that seven-name vocabulary; an unrecognized name fails to load. Two variables binding the same `(table, method)` pair is a mapping-load error, same category as a shared `statements` pattern — but a write-only binding and a read-only binding on the same table do not collide. Evidence tier stays `static-action`.
-
-`variables.<v>.selfAlias: false` opts out of the automatic self-name alias (default `true`, fully backward compatible): normally a variable's own TLA+ name is always added to its alias list, which means an object-literal key or identifier that merely echoes the variable's name — but means something unrelated elsewhere in scope — becomes an unavoidable false write/read attribution. Set it `false` and give a precise, unambiguous alias instead (as `status` does above, aliased only to `lifecycleStage`); a `selfAlias: false` variable with no other alias, no `resource`, no `statements`, and no `waive` is a 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`). It does not exempt read/write facts; those stay on the action's own `waive`. Prefer this over the old workaround of citing an unrelated real symbol just to satisfy the value-like-kind check — name a referent that plainly does not resolve (or does resolve but to the wrong kind) and waive it honestly; a reader should never have to guess that a `code[]` entry is a decoy.
-
-Top-level `"unmappedWriteScope": "actions" | "scope-files"` (default `"scope-files"`) controls how strictly `scope` is enforced: 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 `"actions"` to opt out of that 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.
-
-Top-level `"init": { "codeRefs": ["file#function", ...], "waive"?: {"reason": ...} }` (Q3) binds the model's `Init` to the code referent(s) that materialize initial state — most often a lazy-init factory. `codeRefs` resolves and kind-checks like an action's `code` (function-like, `missing-referent`/`invalid-referent-kind` findings apply, `waive` exempts both). Writes statically found inside an Init referent's own range are Init-attributed: they are excluded from `unmapped-write` findings without needing `unmappedWriteScope: "actions"`. `init.codeRefs` must not overlap any action's `code` referents — that is a mapping-load error, same category as a variable-alias collision.
-
-## Mapping Discipline
-
-- **Alias selection is the sharpest knife.** Never alias a variable to a ubiquitous local identifier (`connection`, `result`, `data`) — 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.** A TLA+ variable named `status`, `phase`, or `state` gets its own name auto-included as an alias by default — and object literals elsewhere in scope (`{ status: 'ok' }` in an unrelated response shape) will match it. If the variable's own name is common enough to collide, set `selfAlias: false` and give a precise alias that names the actual stored field instead.
-- **Know the four state backings.** Program variables: normal aliases. Filesystem-backed state (locks, published artifacts): `resource: { "path": ... }` bindings make fs calls provable. SQL-backed state (prepared statements, table rows behind literal SQL text): `statements: [{ "pattern": ... }]` bindings make it provable too (Q2) — a call argument's static SQL text matching `pattern` is classified as a write or read by its leading verb. ORM-backed state with no literal SQL to match (Drizzle-style query builders): `ormCalls: [{ "table": ... }]` bindings (C1) classify by the call chain's own method + table-arg shape instead. Only genuinely dynamic SQL (built by string concatenation, no static text to match) or an ORM shape the method/table matcher cannot see still needs a waiver naming the residual class; never fake attribution.
-- **Lazy initialization is Init, not an action.** A factory that lazily builds state corresponds to the model's `Init`. Top-level `"init": { "codeRefs": ["file#function", ...] }` (Q3) binds it: writes statically found inside an Init referent are Init-attributed and excluded from `unmapped-write` findings without needing `unmappedWriteScope: "actions"` as a whole-file workaround. `init.codeRefs` must not overlap any action's `code` referents — map the factory to `init`, never to an action.
-- **Design for traces early.** The trace encoder pins scalar (and scalar-array) variables only; a model whose state is all functions and tuple-sets cannot be trace-validated. If trace-check matters for the slice, add scalar projection variables (counts, last outcomes, a phase) alongside the structured state.
-- **Trace until covered.** One accepted trace proves one path, not the 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` (C2) mechanizes the check: 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 (merged and deduped with the mapping's own `traces` list) so recording another trace to cover a gap is additive, not a rewrite. Coverage is informational — it does not change `trace-check`'s exit code — so it never substitutes for actually closing the gap.
-
-## Accuracy Rules
-
-- `tla verify` is the mechanical checker; `tla trace-check` is the semantic one. Only the pair justifies the word "conforms".
-- A PASS with waivers is a conditional claim — the Proof line says exactly what was and was not proven. Never summarize it as unconditional.
-- A PASS on a scaffold with unresolved `TODO`s is meaningless, not conditional: the checker has no TODO detector and will pass a placeholder model. Never report a PASS without confirming step 2 of the Loop is actually done.
-- If code changed but the model did not, inspect whether the mapped transition changed meaning; `diff-gate` flags the changed referents.
-- If the model checker fails, fix the TLA+ model before relying on conformance output.
-- Use `--checker none` only when intentionally checking the mapping without SANY, TLC, or Apalache.
-- 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, marked `(via <callee>, one call hop...)` in findings. It 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 this way, update the waiver reason to name the real call chain instead of deleting the explanation — the evidence is still approximate (which specific runtime call path executes is not proven, only that the code family does).

package/skills/scip-tla-model-system/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "TLA Model System"
-  short_description: "Model TypeScript systems with TLA+"
-  default_prompt: "Use $scip-tla-model-system to model or verify a TypeScript system with TLA+ and scip-query evidence."

package/skills/scip-triage-issue/SKILL.md

@@ -1,133 +0,0 @@
----
-name: scip-triage-issue
-description: Triage issues with scip-query evidence. Use for bug reports, GitHub issues, failing tests, support reports, TODOs, vague defects, root-cause packets, issue bodies, or test-first fix plans.
-commands:
-  - template: 'scip-query files <issue-term>'
-    when: 'Map ownership: locate files for the reported term.'
-  - template: 'scip-query trace <entry-or-error-symbol>'
-    when: 'Trace the failing path: definition plus every reference.'
-  - template: 'scip-query code <entry-or-error-symbol>'
-    when: 'Trace the failing path: read the exact source.'
-  - template: 'scip-query call-graph <entry-symbol>'
-    when: 'Trace the failing path: callers and callees.'
-  - template: 'scip-query similar <suspect-symbol> --json --full'
-    when: 'Compare and bound: nearby implementations for missing handling.'
-  - template: 'scip-query affected <symbol> --json'
-    when: 'Compare and bound: transitive impact bound for the fix plan.'
----
-
-# scip-triage-issue
-
-Use this skill to turn a report into a grounded fix packet. Triage is the evidence pass that determines whether the issue is reproducible, where it enters the codebase, what root cause is likely, and what test should fail before the fix.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query files <issue-term>` | Find files matching a pattern | matching file paths | `complete` | Map ownership: locate files for the reported term. |
-| `scip-query trace <entry-or-error-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Trace the failing path: definition plus every reference. |
-| `scip-query code <entry-or-error-symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Trace the failing path: read the exact source. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Trace the failing path: callers and callees. |
-| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | symbol pairs, similarity scores, and shared evidence | `bounded` | Compare and bound: nearby implementations for missing handling. |
-| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Compare and bound: transitive impact bound for the fix plan. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Rules
-
-1. Do not file or implement from the title alone.
-2. Use scip-query for code evidence: entry points, references, call flow, data flow, blast radius, and similar implementations.
-3. Prefer a failing test plan before a code plan.
-4. If the user asks only for triage, stop at the packet. If they asked to fix it too, implement after the packet is clear.
-
-## Workflow
-
-### 1. Normalize the report
-
-Record summary, observed behavior, expected behavior, reproduction, affected surface, severity, user impact, and logs/screenshots/tests/links.
-
-Ask the user only for product intent, credentials, private data, or external system state the repo cannot answer.
-
-This step is complete only when missing facts are either recovered or named.
-
-### 2. Map ownership
-
-```bash
-scip-query files <issue-term>
-scip-query outline <candidate-file>
-scip-query system <module-or-scope>
-scip-query surface <module-or-scope>
-```
-
-Use `kind-counts` and `by-kind` for broad subsystems.
-
-This step is complete only when likely owner files and surfaces are named.
-
-### 3. Trace the failing path
-
-```bash
-scip-query trace <entry-or-error-symbol>
-scip-query code <entry-or-error-symbol>
-scip-query call-graph <entry-symbol>
-scip-query dataflow <state-or-input-symbol>
-scip-query slice <state-or-input-symbol>
-```
-
-For stack traces, read the exact range with `scip-query code 'file:start-end'`.
-
-This step is complete only when a suspected root cause is tied to source evidence or labeled unproven.
-
-### 4. Compare and bound
-
-```bash
-scip-query similar <suspect-symbol> --json --full
-scip-query similar <suspect-symbol> <comparison-symbol> --plan
-scip-query similar-files <suspect-file> --json --full
-scip-query co-change <suspect-file> --json --full
-scip-query change-surface <suspect-file> --json --full
-scip-query affected <suspect-symbol> --json
-```
-
-This step is complete only when the packet has a narrow test shape and impact bound.
-
-## Packet
-
-```markdown
-## Issue
-
-<one-sentence mismatch>
-
-## Reproduction
-
-<steps, command, failing test, or missing data>
-
-## Evidence
-
-- <scip-query command>: <fact>
-
-## Suspected Root Cause
-
-<earliest code fact that explains the symptom>
-
-## Impact
-
-- users/surfaces affected
-- blast radius
-
-## Fix Plan
-
-1. Add or update failing test/smoke check.
-2. Make the smallest code change.
-3. Run targeted test.
-4. Invoke `scip-verify`.
-
-## Open Questions
-
-- <product intent or external state only>
-```
-
-If no root cause is proven, label the issue `needs reproduction` or `needs product decision`.

package/skills/scip-triage-issue/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP Triage Issue"
-  short_description: "Turn bug reports into evidence-backed fix plans"
-  default_prompt: "Triage this issue with scip-query evidence, identify the root cause, and write a test-first fix plan."