scip-query 0.19.4 → 0.19.6

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

@@ -1,150 +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 | When |
-| --- | --- | --- |
-| `scip-query trace <mechanism-symbol>` | Trace a symbol: definition + all references | 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 | Assemble the family: files that historically changed with each fix site. |
-| `scip-query system <system-scope>` | Full module map: files, symbols, deps in/out | 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 | Predict: hunt latent instances among sibling implementations of the fixed code. |
-| `scip-query refs <invariant-carrier>` | Find all files referencing a symbol | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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,126 +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 | When |
-| --- | --- | --- |
-| `scip-query files <issue-term>` | Find files matching a pattern | Map ownership: locate files for the reported term. |
-| `scip-query trace <entry-or-error-symbol>` | Trace a symbol: definition + all references | 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) | Trace the failing path: read the exact source. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Trace the failing path: callers and callees. |
-| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | Compare and bound: nearby implementations for missing handling. |
-| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | 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."

package/skills/scip-twin-drift/SKILL.md

@@ -1,107 +0,0 @@
----
-name: scip-twin-drift
-description: Find and resolve twin drift with scip-query. Use for same-name or near-name functions across files with diverged bodies, drifted policy thresholds, one-sided fixes, or consolidating a duplicated concept into one canonical helper.
-commands:
-  - template: "scip-query twin-drift --json --full"
-    when: "Run the detector: every DIVERGENT and near-name group in scope."
-  - template: "scip-query duplicate-bodies --json --full"
-    when: "Cross-check: IDENTICAL groups are duplicate-bodies' job, not this skill's."
-  - template: "scip-query code <symbol>"
-    when: "Classify a divergent group: read every member's body."
-  - template: "scip-query refs <symbol>"
-    when: "Pick the canonical twin: consumer count per member."
-  - template: "scip-query diff-gate --json"
-    when: "Verify: the twin-partner check must not flag a one-sided fix."
----
-
-# scip-twin-drift
-
-Use this skill when the same concept exists in more than one place under the same or a near-name (case-insensitive, or edit-distance ≤ 2 for names ≥ 8 characters) and the bodies have silently diverged. A twin drift group is a same-leaf-name family of callables spanning at least two files whose normalized-token bodies are neither identical (that is `duplicate-bodies`' job) nor unrelated (a homonym like `render` or `parse`) but partially overlapping — the signature of a concept that was copied once and then edited independently in only some of its copies.
-
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query twin-drift --json --full` | Twin drift candidates: same-name (or near-name) functions across files with diverged bodies | Run the detector: every DIVERGENT and near-name group in scope. |
-| `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Cross-check: IDENTICAL groups are duplicate-bodies' job, not this skill's. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Classify a divergent group: read every member's body. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | Pick the canonical twin: consumer count per member. |
-| `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 | Verify: the twin-partner check must not flag a one-sided fix. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Rules
-
-1. `IDENTICAL` groups defer to `duplicate-bodies`; do not re-report them here.
-2. Homonyms (similarity below `--min-similarity`, default 0.3) are noise unless `--include-homonyms` was requested; do not chase them.
-3. Every `DIVERGENT` group in scope gets a classification before this skill reports done.
-4. Prefer consolidation to one exported helper over leaving parallel copies; when consolidation is unsafe or premature, record the intent gap explicitly (comment or waiver) rather than silently accepting drift.
-5. A twin-partner `diff-gate` finding on a change you are making is the live version of this same defect class — treat it as a signal to run this skill, not just to suppress.
-
-## Workflow
-
-### 1. Run the detector
-
-```bash
-scip-query twin-drift --json --full
-```
-
-Scope with `-s/--scope <path>` when the review is bounded to a module. Record group count, member count, and `maxDivergence` per group.
-
-This step is complete only when every group in scope is enumerated with its relationship (`divergent` vs suppressed homonym).
-
-### 2. Classify each DIVERGENT group
-
-For each group, read every member with `scip-query code <symbol-or-file:range>` and use the group's `firstDivergentTokens` as a starting point for where the bodies diverge. Classify the group as one of:
-
-- **Intentional variation**: the copies differ because the domains genuinely differ (for example a React-specific vs Vue-specific structural comparator that must branch on framework-specific overlap checks). Essential variation stays; record why.
-- **Drifted policy**: the copies encode what should be one policy (a threshold, a normalization rule, an edge-case guard) that only some copies received when it last changed. This is a bug: pick the correct value and propagate it, or extract the policy into one named function/constant.
-- **One-sided fix**: one copy was bugfixed or hardened and its twin(s) were not. This is also a bug: apply the same fix to every member, or consolidate.
-
-This step is complete only when every DIVERGENT group in scope has one of these three labels with a one-line reason.
-
-### 3. Pick the canonical twin and act
-
-For groups getting consolidated, pick the canonical member by consumer count:
-
-```bash
-scip-query refs <symbol-in-file-A>
-scip-query refs <symbol-in-file-B>
-```
-
-Prefer the member with the most consumers, or the one in the more general/shared location when counts tie. Extract or move the canonical body to one exported helper; update the other member(s) to call it, or delete them if they were pure duplication with different names for the caller's convenience. Preserve any classified-essential variation as a parameter or a thin caller-side branch, not as a second copy of the whole body.
-
-For groups marked intentional variation, do not force consolidation; record the reason in a comment near one of the members so the next `twin-drift` run and the next reader both see it was considered.
-
-This step is complete only when every DIVERGENT group is either consolidated (with the old copies gone or forwarding) or has a recorded reason it stays separate.
-
-### 4. Verify
-
-Rerun the detector to confirm consolidated groups no longer appear as DIVERGENT, then run the routed postchecks from the shared reference and:
-
-```bash
-scip-query diff-gate --json
-```
-
-The `twin-partner` check is advisory (it never blocks the gate by itself) but a finding here on your own diff means you just reproduced the exact defect class this skill exists to catch — fix or explicitly accept it before finishing.
-
-This step is complete only when `twin-drift` shows no unclassified `DIVERGENT` groups in scope and `diff-gate` findings are resolved or explained.
-
-## Report
-
-```markdown
-Scope:
-Groups found: N (M divergent, K suppressed homonyms)
-
-Divergent groups:
-- <leaf name> (<files>) — classification: intentional variation / drifted policy / one-sided fix
-  - action: consolidated into <canonical file:symbol> / reason kept separate
-
-Verification:
-- `scip-query twin-drift --json --full`: <result>
-- `scip-query diff-gate --json`: <result>
-```

package/skills/scip-twin-drift/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP Twin Drift"
-  short_description: "Find and resolve same-name twins that have silently diverged"
-  default_prompt: "Use scip-query twin-drift to find same-name or near-name functions that have diverged across files, classify each divergence, and consolidate or record the intent gap."