scip-query 0.10.11 → 0.11.0

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

@@ -0,0 +1,138 @@
+---
+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: class fields on files with any indexed method are usually invisible to `scaffold`.** The write scanner can find `this.field = ...` writes fine, but the class-field fallback only ever sees candidates that `getDefinitionsForFile` actually returns — and that catalog (`definition-catalog.ts`/`symbol-row-policy.ts`) deliberately drops class-member fallback rows whenever the file has any other primary-indexed (enclosing-range) definition, which any class with a constructor or a named method always has. So a concurrency class like a lock or connection pool — exactly the shape this skill most wants to model — will almost always report "no mutable state discovered", not because the state isn't there but because the shared definition catalog hides it one layer below scaffold. When you hit this: model by hand from `plan-context`/`trace` evidence instead of via `scaffold`, or narrow the target file so the class in question is the only indexed definition in it. Widening the catalog itself is out of scope for this skill's tooling — it's a shared primitive nearly every other command depends on.
+
+## 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.
+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" }
+    },
+    "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.
+
+`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.
+
+`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.
+- **Know the three state backings.** Program variables: normal aliases. Filesystem-backed state (locks, published artifacts): `resource: { "path": ... }` bindings make fs calls provable. Database/SQL-backed state (prepared statements, table rows): `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. Only genuinely dynamic SQL (built by string concatenation, no static text to match) 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.
+
+## 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

@@ -0,0 +1,4 @@
+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,49 +1,71 @@
 ---
 name: scip-triage-issue
-description: Triage bug reports and issues with scip-query evidence. Use when the user shares a GitHub issue, bug report, failing test, support report, TODO, vague defect, or asks to investigate, classify, root-cause, write an issue, or produce a test-first fix plan before implementation.
+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 Issue Triage
+# scip-triage-issue
 
-Use this skill to turn a report into a grounded fix plan. An issue is a described mismatch between expected and observed behavior that needs a tracked decision or code change. Triage is the evidence pass that determines whether the issue is reproducible, where it enters the codebase, what root cause is most likely, and what test should fail before the fix.
+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. Extract concrete observed behavior, expected behavior, scope, and reproduction first.
+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. If no test harness exists, name the smoke command or manual check that will prove the fix.
-4. If the user asks only for triage, stop at the triage packet. If they asked to fix it too, implement after the packet is clear.
+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:
+Record summary, observed behavior, expected behavior, reproduction, affected surface, severity, user impact, and logs/screenshots/tests/links.
 
-- title or short summary;
-- observed behavior;
-- expected behavior;
-- reproduction steps or missing reproduction data;
-- affected surface: CLI command, API route, UI view, job, library export, docs, or config;
-- severity and user impact;
-- known logs, stack traces, screenshots, failing tests, or issue links.
+Ask the user only for product intent, credentials, private data, or external system state the repo cannot answer.
 
-If key facts are missing but the repo can answer them, investigate. Ask the user only when the missing fact is product intent, credentials, private data, or an external system state you cannot inspect.
+This step is complete only when missing facts are either recovered or named.
 
-### 2. Map likely code ownership
+### 2. Map ownership
 
 ```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
 scip-query files <issue-term>
 scip-query outline <candidate-file>
 scip-query system <module-or-scope>
 scip-query surface <module-or-scope>
 ```
 
-Use `scip-query kind-counts --scope <scope>` and `scip-query by-kind function --scope <scope>` when the issue names a broad subsystem and you need an inventory.
+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
 
@@ -55,32 +77,24 @@ scip-query dataflow <state-or-input-symbol>
 scip-query slice <state-or-input-symbol>
 ```
 
-If a stack trace names a file and line, use `scip-query code '<file>:<start>-<end>'` to read the exact region before following symbols.
+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. Look for known-good comparisons
+### 4. Compare and bound
 
 ```bash
 scip-query similar <suspect-symbol> --json --full
-scip-query convergence <suspect-symbol> <comparison-symbol>
+scip-query similar <suspect-symbol> <comparison-symbol> --plan
 scip-query similar-files <suspect-file> --json --full
 scip-query co-change <suspect-file> --json --full
-```
-
-Use comparisons to identify a missing guard, validation step, conversion, docs partner, generated artifact, or test fixture.
-
-### 5. Bound impact and test shape
-
-```bash
 scip-query change-surface <suspect-file> --json --full
 scip-query affected <suspect-symbol> --json
-scip-query diff-impact --json
 ```
 
-Choose the narrowest failing test that proves the bug. If the issue crosses a public API or generated contract, include `scip-query co-change <file> --json --full` in the plan.
-
-## Triage Packet
+This step is complete only when the packet has a narrow test shape and impact bound.
 
-Write the packet before filing or fixing:
+## Packet
 
 ```markdown
 ## Issue
@@ -97,18 +111,16 @@ Write the packet before filing or fixing:
 
 ## Impact
 - users/surfaces affected
-- blast radius from `scip-query affected` or `change-surface`
+- blast radius
 
 ## Fix Plan
 1. Add or update failing test/smoke check.
 2. Make the smallest code change.
 3. Run targeted test.
-4. Run `scip-query status --capabilities`; if freshness is `stale`, `missing`, or `unknown`, run `scip-query reindex`.
-5. Run `scip-query diff-gate --json`.
-6. Invoke `scip-verify`.
+4. Invoke `scip-verify`.
 
 ## Open Questions
 - <product intent or external state only>
 ```
 
-If creating a GitHub issue, use the packet as the issue body and include exact file/symbol references. If no root cause is proven, label the result as `needs reproduction` or `needs product decision`, not as ready to implement.
+If no root cause is proven, label the issue `needs reproduction` or `needs product decision`.

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

@@ -0,0 +1,107 @@
+---
+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: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; 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

@@ -0,0 +1,4 @@
+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."