scip-query 0.22.0 → 0.24.0

package/docs/locality-analyzer-design.md

@@ -91,15 +91,15 @@ The output should include confidence, reasons, counterevidence, and the exact co
 
 The locality analyzer should not replace existing analyzers. It should complete their story.
 
-| Existing analyzer                                    | What it says today                                    | Locality companion question                                                                           |
-| ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `react-large-component-pressure`                     | This React component is too large.                    | If pieces are extracted, which ones are private, feature-local, or shared?                            |
-| `vue-large-view-pressure`                            | This Vue SFC is too large.                            | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
-| `extract-candidates`                                 | This function contains a possible extraction cluster. | Would the extracted helper have one real owner or a broader consumer set?                             |
-| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.                   | Is the hook/composable local to one feature or reusable across domains?                               |
-| `recent-duplicates`, `echo`                          | New code duplicates older code.                       | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
-| `incomplete-migration`                               | A helper extraction stopped halfway.                  | Is the helper in the right place for all remaining call sites?                                        |
-| `co-change`                                          | Files move together historically.                     | Does history imply a hidden shared owner or only a local synchronization point?                       |
+| Existing analyzer                                    | What it says today                               | Locality companion question                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `react-large-component-pressure`                     | This React component is too large.               | If pieces are extracted, which ones are private, feature-local, or shared?                            |
+| `vue-large-view-pressure`                            | This Vue SFC is too large.                       | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
+| `extract-candidates`                                 | This function has a region of exclusive callees. | Would the extracted helper have one real owner or a broader consumer set?                             |
+| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.              | Is the hook/composable local to one feature or reusable across domains?                               |
+| `recent-duplicates`, `echo`                          | New code duplicates older code.                  | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
+| `incomplete-migration`                               | A helper extraction stopped halfway.             | Is the helper in the right place for all remaining call sites?                                        |
+| `co-change`                                          | Files move together historically.                | Does history imply a hidden shared owner or only a local synchronization point?                       |
 
 ## Algorithm Sketch
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -371,7 +371,7 @@
     "api:report": "node scripts/api-surface-contract.mjs report",
     "api:check": "npm run build && node scripts/api-surface-contract.mjs check && tsc -p tests/fixtures/public-api-consumer/tsconfig.json",
     "api:update": "npm run build && node scripts/api-surface-contract.mjs update",
-    "lint": "npm run format:check && eslint src tests tsup.config.ts scripts/api-surface-contract.mjs scripts/audit-production-dependencies.mjs scripts/benchmark-cold-reindex.ts scripts/benchmark-graph-literal.ts scripts/benchmark-query-service.ts scripts/benchmark-reindex-accounting.ts scripts/benchmark-source-search.ts scripts/build-scip-windows.mjs scripts/cache-lifecycle-soak.ts scripts/codex-exploration-sandbox.mjs scripts/codex-exploration-trial-core.mjs scripts/codex-exploration-trial.mjs scripts/compare-exploration-trials.mjs scripts/exploration-benchmark-core.mjs scripts/exploration-benchmark.mjs scripts/npm-release-state.ts scripts/npm-release.ts scripts/publish-scip-windows.ts scripts/release-npm-guard.ts scripts/release-npm.ts scripts/scip-windows-package-identity.ts scripts/scip-windows-provenance.mjs scripts/scip-windows-release.ts scripts/verify-identity-collision-cli.mjs scripts/verify-scip-windows.mjs scripts/verify-scip-windows-registry.ts skills/scip-explore/scripts/capture-evidence.mjs && npm run api:check && node scripts/check-skill-links.mjs",
+    "lint": "npm run format:check && eslint src tests tsup.config.ts scripts/api-surface-contract.mjs scripts/audit-production-dependencies.mjs scripts/benchmark-cold-reindex.ts scripts/benchmark-graph-literal.ts scripts/benchmark-query-service.ts scripts/benchmark-reindex-accounting.ts scripts/benchmark-source-search.ts scripts/build-scip-windows.mjs scripts/cache-lifecycle-soak.ts scripts/codex-exploration-sandbox.mjs scripts/codex-exploration-trial-core.mjs scripts/codex-exploration-trial.mjs scripts/compare-exploration-trials.mjs scripts/exploration-benchmark-core.mjs scripts/exploration-benchmark.mjs scripts/npm-release-state.ts scripts/npm-release.ts scripts/publish-scip-windows.ts scripts/release-npm-guard.ts scripts/release-npm.ts scripts/scip-windows-package-identity.ts scripts/scip-windows-provenance.mjs scripts/scip-windows-release.ts scripts/score-detector-labels.ts scripts/verify-identity-collision-cli.mjs scripts/verify-scip-windows.mjs scripts/verify-scip-windows-registry.ts skills/scip-explore/scripts/capture-evidence.mjs && npm run api:check && node scripts/check-skill-links.mjs",
     "build:scip-windows": "node scripts/build-scip-windows.mjs",
     "verify:scip-windows": "node scripts/verify-scip-windows.mjs",
     "verify:identity-collision-cli": "node scripts/verify-identity-collision-cli.mjs",

package/skills/conductor/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: conductor
+description: Plan and conduct multi-step engineering programs like a skeptical principal engineer. Use for writing executable multi-phase plans, delegating implementation, reviewing another agent's work, or carrying a large change end to end with verification at every handoff.
+---
+
+# conductor
+
+This skill is how to run a _program_ of work: planning, delegation, review,
+and closure. It is not how to write one change plan; use `$scip-plan` for an
+individual change in a scip-query-indexed repository.
+
+## The Three Laws
+
+1. **A green result you have never seen fail is unverified.** Applies to
+   tests, gates, reports from other agents, and your own checks.
+   `$scip-integrity-audit` is the same law aimed at code.
+2. **A plan is a contract for a less-capable executor, not a note to self.**
+   If a competent-but-uninspired agent could not execute a step without
+   guessing, the step is not finished being written.
+3. **Nothing is silent.** Every finding, deviation, and shortcut is either
+   fixed or written down with a reason someone else would accept. Zero
+   percent silent is the invariant; "fixed everything" is not.
+
+## Writing the Plan
+
+- **Goal states what DONE MEANS falsifiably**: a command someone can run
+  and a result they can check, not an aspiration.
+- **Pre-register acceptance benchmarks.** Before any work: measure the
+  current number (test count, timing, finding count, proof line), write it
+  in the plan, and state the target number. Work that cannot move a
+  pre-registered number is scope to question.
+- **Every step carries five fields**: file anchor with verified current
+  behavior (cite how you know); the exact change; the validation command
+  with expected output; testability design (pure core, injected effects);
+  why this step is safe _in this order_. "Update X" with no current and
+  target behavior is a wish, not a step.
+- **Order phases by information gain and risk**: blockers and
+  evidence-integrity first; cheap discriminating probes before expensive
+  builds; measurement before optimization; anything not yet decided by the
+  human is a GATED phase the executor must not start. Infrastructure the
+  later steps inherit (a labeling choke point, a shared helper layer)
+  lands before the features that need it.
+- **Flag one-way doors** with their migration path, and keep an explicit
+  DEFER list so cut scope is visible instead of forgotten.
+- **Include the working agreement**: ONE COMMIT PER STEP (bisectability is
+  non-negotiable; phase-level commits hide which step broke), the exact
+  gate commands, meaning the FULL gate set the repo defines per phase
+  (tests, typecheck, lint and format, build) and not just focused tests
+  (focused tests hide cross-phase regressions; omitting the linter is how
+  red mains ship), regeneration duties, and the deviation protocol:
+  "if source contradicts an anchor, BLOCKED-note it and continue; never
+  improvise silently."
+
+## Conducting the Work
+
+- **Delegate breadth, keep judgment.** Fan out mechanical, scoped work;
+  personally own anything requiring taste, cross-cutting context, or the
+  final word on "is this real."
+- **Concurrent agents get disjoint write scopes**, named in their briefs.
+  If a collision happens anyway: stop racing, apply-verify-commit
+  atomically in one action, and re-sequence to a single writer.
+- **Never accept a report; reproduce its evidence.** On every handoff,
+  choose the _minimal discriminating probe_: the one command most likely to
+  expose the report being wrong (a mutation input, a hand count, the
+  benchmark number, a `scip-query diff-impact` over the claimed change), and
+  run it yourself. A report verified by reading it is not verified.
+- **Make the commit cadence mechanical, not aspirational.** At every step
+  boundary run the arithmetic check: steps completed equals commits made. If
+  they differ, stop and commit before touching anything new. "I'll commit
+  when it's all done" is the signature decay of a long or low-effort run.
+  A self-check that is a count cannot be rationalized.
+- **Loop until the gate is quiet**: fix, re-run the discriminating probe,
+  re-run the gate, and only then move on. After the program, fold what was
+  learned back into the durable layer (docs, skills, followups). Insight
+  that lives only in the conversation is lost.
+- **Escalate only genuine decision points**: one-way doors, scope changes,
+  taste, spending. Everything else: decide, act, disclose.
+
+## Scar Rules (each bought with a real failure)
+
+- **Verify your verifier.** A gate check that cannot fail is no gate: a
+  lint grep that only matches one linter's output, an impact check run on a
+  clean tree, a test suite that skips the new path. Prove the check catches
+  a planted failure once before trusting its green.
+- **Never `git checkout`, `git restore`, or `git stash` on a tree with
+  uncommitted work**, yours or anyone's. Revert probe edits by targeted
+  deletion. If source is lost, check `dist/*.map` sourcesContent before
+  panicking.
+- **Commit working states early and surgically** with explicit paths, never
+  `add -A` on a shared tree. An unbisectable pile of work is a liability.
+- **Watch for your own gate holes**: after any "all green," ask what that
+  check does NOT cover (eslint versus prettier; unit versus integration;
+  clean-tree vacuity).
+
+## Self-Report (required output)
+
+End every conducted program, and every plan written under this skill,
+with a checklist mapping each section above to concrete evidence:
+the pre-registered benchmarks and their before and after values; each
+handoff's discriminating probe and its OBSERVED result (a probe listed but
+not run counts as not run); the deviation ledger; the DEFER list; which
+learnings were folded back and where. A reviewer must be able to audit the
+_conduct_, not just the artifact.
+
+## Completion
+
+The program is complete only when: every pre-registered benchmark met or
+its miss explained; every handoff probe run and recorded; the gate quiet on
+the final state; nothing silent, meaning every finding fixed or ledgered;
+and the self-report written.

package/skills/conductor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Conductor'
+  short_description: 'Plan and conduct multi-phase engineering programs with verified handoffs'
+  default_prompt: 'Use $conductor to plan and conduct this multi-phase program end to end: pre-register benchmarks, write executor-ready steps, reproduce the evidence at every handoff, and close with the self-report.'

package/skills/principal-maintainability-review/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: principal-maintainability-review
+description: Review maintainability like a principal engineer. Use when the user asks what a senior, staff, principal, or highly opinionated maintainer would notice, whether code looks vibe-coded, what is gross, what should be fundamentally different, or which architecture smells matter beyond ordinary deduplication. Finds scattered concepts, hidden policies, accidental variation, and compression opportunities, then proposes or executes maintainability-improving refactors.
+metadata:
+  commands:
+    - template: 'scip-query search <text>'
+      when: 'Locate a policy word, threshold, helper name, or repeated literal across the review scope.'
+    - template: 'scip-query system <scope>'
+      when: 'Map a module: files, exported symbols, dependencies in and out.'
+    - template: 'scip-query surface <scope>'
+      when: 'See which symbols consumers actually use from a module.'
+    - template: 'scip-query outline <file>'
+      when: 'Inventory one file before claiming it has unrelated reasons to change.'
+    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
+      when: 'Project callers, callees, dataflow, or ownership around a suspected scattered concept.'
+    - template: 'scip-query code <selector>'
+      when: 'Read exact source when the body itself decides whether variation is essential.'
+    - template: 'scip-query similar --cross-file-only'
+      when: 'Probe for functions with overlapping callee sets across files.'
+    - template: 'scip-query similar-files'
+      when: 'Probe for files with overlapping dependency profiles.'
+    - template: 'scip-query stale-abstractions --include-low-confidence'
+      when: 'Probe for types, interfaces, and classes with zero or one consumer.'
+    - template: 'scip-query wrapper-candidates'
+      when: 'Probe for single-consumer indirection.'
+    - template: 'scip-query passthrough-candidates'
+      when: 'Probe for functions that only forward to one callee.'
+    - template: 'scip-query drift --architecture'
+      when: 'Probe for files that deviate from sibling conventions and for declared boundary violations.'
+    - template: 'scip-query health --full'
+      when: 'Run every configured detector once as a sampling frame, never as a target.'
+    - template: 'scip-query diff-impact'
+      when: 'After an implemented slice, map changed symbols and downstream consumers.'
+    - template: 'scip-query architecture'
+      when: 'After an implemented slice, confirm declared boundaries still hold.'
+---
+
+# Principal Maintainability Review
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
+| --- | --- |
+| `scip-query search <text>` | Locate a policy word, threshold, helper name, or repeated literal across the review scope. |
+| `scip-query system <scope>` | Map a module: files, exported symbols, dependencies in and out. |
+| `scip-query surface <scope>` | See which symbols consumers actually use from a module. |
+| `scip-query outline <file>` | Inventory one file before claiming it has unrelated reasons to change. |
+| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project callers, callees, dataflow, or ownership around a suspected scattered concept. |
+| `scip-query code <selector>` | Read exact source when the body itself decides whether variation is essential. |
+| `scip-query similar --cross-file-only` | Probe for functions with overlapping callee sets across files. |
+| `scip-query similar-files` | Probe for files with overlapping dependency profiles. |
+| `scip-query stale-abstractions --include-low-confidence` | Probe for types, interfaces, and classes with zero or one consumer. |
+| `scip-query wrapper-candidates` | Probe for single-consumer indirection. |
+| `scip-query passthrough-candidates` | Probe for functions that only forward to one callee. |
+| `scip-query drift --architecture` | Probe for files that deviate from sibling conventions and for declared boundary violations. |
+| `scip-query health --full` | Run every configured detector once as a sampling frame, never as a target. |
+| `scip-query diff-impact` | After an implemented slice, map changed symbols and downstream consumers. |
+| `scip-query architecture` | After an implemented slice, confirm declared boundaries still hold. |
+
+These commands are controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct question. There is no required sequence or query limit. Run a command's `--help` when you need a flag not shown in its template.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Purpose
+
+Use this skill to review a codebase from the standpoint of an expert maintainer who is optimizing for future comprehension and change safety, not just correctness, test count, or line count.
+
+A principal maintainability review is an architecture review over real code units such as files, symbols, tests, commands, adapters, caches, public exports, and docs; it identifies where one human concept is scattered across many local implementations and replaces that scatter, when justified, with a smaller named mechanism that preserves behavior.
+
+This differs from a normal refactor because the target is maintainer memory load. The question is not only "is there duplication?" The question is "what hidden concept, policy, lifecycle, or pipeline must a future maintainer rediscover to change this safely?"
+
+Keep a review read-only unless the user separately authorizes edits.
+
+## Trigger Posture
+
+When this skill triggers, adopt an evaluative but evidence-grounded stance. The user is asking for taste and judgment, not a neutral file tour.
+
+Translate persona prompts into technical review prompts:
+
+- "What would a principal engineer notice?" means "Which concepts are scattered, undernamed, or locally reimplemented?"
+- "Would this look vibe-coded?" means "Where does the structure fail to communicate the domain model or maintenance contract?"
+- "What is gross here?" means "Which code shapes create avoidable future mistakes?"
+- "What would be fundamentally better?" means "Which smaller mechanism would preserve behavior while reducing concept count?"
+
+Do not mock the code. Be direct about smells, but keep claims tied to concrete evidence. Taste is allowed only when it is tied to concrete files, symbols, tests, public surfaces, callers, or maintenance failure modes.
+
+## Core Concepts
+
+A code smell is an observable codebase fact that predicts avoidable future mistakes because the same knowledge must be rediscovered, synchronized, or defended in several places.
+
+A concept boundary is the line around code units that exist for one reason to change. A weak boundary mixes unrelated reasons to change, such as parsing syntax, choosing fallback policy, caching data, and rendering output in one module.
+
+A hidden policy is a rule for choosing behavior when several plausible behaviors exist, but the rule is implemented through local branches, repeated comments, or caller folklore instead of a named mechanism.
+
+A lifecycle is a repeatable sequence of states or steps that makes a result valid, such as parse -> fallback -> emit, candidate -> evidence -> score -> report, or load -> augment -> write -> invalidate.
+
+Concept count is the number of distinct ideas a maintainer must hold active to make a safe change. Lowering concept count is valuable only when the new structure still explains all real variation.
+
+Accidental variation is difference in code shape that does not correspond to a difference in behavior, domain facts, or external constraints.
+
+Essential variation is difference that must remain because the real-world referents differ, such as different language grammars, API contracts, runtime environments, or public compatibility boundaries.
+
+A unifying definition is the single essential trait that makes several code sites one concept. It is a test, not a label: if no single trait covers every cited site, the sites are not one concept, and consolidating them anyway would package essential variation into a false abstraction.
+
+## Workflow
+
+### 1. State the Review Question
+
+Restate the task in concrete terms:
+
+```text
+What future-maintenance mistakes does this structure invite, and what smaller named mechanisms would prevent them without hiding real variation?
+```
+
+Name the scope: repo, module, command family, query family, runtime surface, fixture set, or feature path. If the user asks to execute changes, proceed after building enough evidence. If they ask only "what else is there?", return the next ranked smell set and its evidence.
+
+### 2. Build an Evidence Map
+
+Start from real units:
+
+```bash
+scip-query search <policy-word-or-helper-name>
+scip-query system <scope>
+scip-query surface <scope>
+scip-query outline <file>
+scip-query evidence --symbol <symbol> --edge execution --direction incoming --depth 1 --max-edges 60
+scip-query evidence --symbol <symbol> --edge ownership --direction both --depth 1 --max-edges 40
+```
+
+Use smell probes as signals, not verdicts:
+
+```bash
+scip-query similar --cross-file-only
+scip-query similar-files
+scip-query extract-candidates
+scip-query wrapper-candidates
+scip-query passthrough-candidates
+scip-query stale-abstractions --include-low-confidence
+scip-query drift --architecture
+scip-query health --full
+```
+
+If no SCIP index exists, run `scip-query setup` first, or fall back to tests, build config, and manual code reading and say so in the report.
+
+### 3. Name the Referents
+
+For each suspicious area, identify the concrete referents before judging it:
+
+- files and exported symbols
+- callers and downstream public surfaces
+- tests and fixtures that define behavior
+- data structures and result records
+- fallback paths, caches, registries, adapters, and command handlers
+- generated artifacts or compatibility constraints
+
+Do not call something a smell until you can point to the code units that make the future-maintenance risk real.
+
+### 4. Ask the Principal Questions
+
+For each cluster, answer:
+
+- What one concept is being implemented in several places, and what single essential trait makes them one concept?
+- What policy is hidden in branches, comments, argument conventions, or test fixtures?
+- What lifecycle is present but unnamed?
+- Which differences are essential, and which are accidental?
+- What must a new maintainer know that the local interface does not admit?
+- Would a small named mechanism remove a reason to change, or only move code around?
+- What behavior or public API constrains the refactor?
+
+Prefer severe smells in this order:
+
+1. Hidden correctness or evidence policy spread across modules.
+2. Repeated lifecycle or pipeline with no named owner.
+3. Public surface that exposes accidental internals.
+4. Large module with multiple unrelated reasons to change.
+5. Tests that encode incident history without a contract vocabulary.
+6. Adapter families with repeated capability or fallback shapes.
+7. Suppression comments that document architecture decisions instead of exceptions.
+8. Thin wrappers, pass-throughs, and helper layers that do not buy clarity.
+
+### 5. Rank by Compression Value
+
+A good target should satisfy most of these:
+
+- It removes a hidden policy or names a lifecycle.
+- It reduces the amount of context needed to make future changes.
+- It makes tests easier to state as contracts.
+- It prevents drift among sibling modules.
+- It lowers public API accident risk.
+- It deletes, merges, or enforces a real mechanism instead of merely relocating code.
+
+Reject false compression when:
+
+- similar code reflects essential variation
+- a helper would hide grammar, protocol, or domain differences
+- the new abstraction needs more concepts than it removes
+- a compatibility boundary must stay explicit
+- the smell is only aesthetic
+
+Every scattered-concept or consolidation claim ships its unifying definition and its strongest dissenter: the cited site most likely to differ essentially, with the evidence that it does not. A dissenter that survives moves the entry to `skip` with reason `essential variation`. The dissenter stays in the register either way.
+
+### 6. Produce a Register or Atlas
+
+For broad review, create or update a Markdown register under `docs/plans/` unless the user asks not to edit files.
+
+Use this shape:
+
+```markdown
+# Principal Maintainability Register
+
+## Executive Read
+
+## Current Status
+
+## Smell Ledger
+
+| Priority | Smell | Evidence | Why it hurts | Better shape | Disposition |
+| --- | --- | --- | --- | --- | --- |
+
+## Next Slice
+
+## Deferred Boundaries
+
+## Verification Plan
+```
+
+Use dispositions: `merge`, `delete`, `inline`, `extract`, `generate`, `enforce`, `supersede`, `defer`, `skip`.
+
+For implementation work, write an atlas for the chosen slice before editing. `$scip-system-compression` owns the full atlas template; use it when the scope is a subsystem rather than one slice.
+
+### 7. Implement Conservatively
+
+When asked to fix the smells:
+
+- Introduce the smallest named mechanism that matches the real concept.
+- Keep essential variation close to the adapter or domain code that knows it.
+- Move hidden policies behind interfaces that make the choice visible.
+- Preserve behavior before broadening scope.
+- Update docs and registers to record deferred boundaries and why.
+- Commit coherent slices after verification when the user asked for commits.
+
+Avoid "frameworking." A new abstraction is justified only if it removes real concept count or enforces a policy that callers were already hand-maintaining.
+
+### 8. Verify the Review Did Real Work
+
+After changes, run the narrow tests for the touched subsystem and the repository's standard checks, then:
+
+```bash
+scip-query diff-impact
+scip-query architecture
+scip-query stale-abstractions --include-low-confidence
+scip-query wrapper-candidates
+scip-query passthrough-candidates
+```
+
+The final answer states:
+
+- the named smell addressed
+- the mechanism introduced or simplified
+- what was deliberately not compressed, and which dissenter kept it separate
+- verification results
+- commit hash, when committed
+
+## Output Style
+
+Be candid and specific. Use plain engineering language:
+
+- "This module has three reasons to change."
+- "This helper names a policy that was previously caller folklore."
+- "This similarity is false; the syntax differences are essential."
+- "This is a good next slice because it removes a lifecycle repeated across sibling adapters."
+
+Do not rely on persona language in the final artifact. The persona is a prompt for judgment; the deliverable is an evidence-backed maintainability review.

package/skills/principal-maintainability-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Principal Maintainability Review'
+  short_description: 'Find the maintainability smells a principal engineer would flag, with evidence'
+  default_prompt: 'Use $principal-maintainability-review to find the highest-value maintainability smells in this codebase: scattered concepts, hidden policies, unnamed lifecycles, and false compression, each tied to files and symbols.'

package/skills/scip-calibrate/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: scip-calibrate
+description: Calibrate scip-query's detectors against a repository before trusting them. Use when adopting scip-query in a new or foreign codebase, after major detector changes, or when a health score or detector output seems too noisy or too clean.
+metadata:
+  commands:
+    - template: 'scip-query capabilities --matrix'
+      when: 'Inventory: which languages got which evidence tier before judging any detector.'
+    - template: 'scip-query health --json'
+      when: 'Battery sweep: every detector finding count as a sampling frame, not a verdict.'
+    - template: 'scip-query dead --json'
+      when: 'Sample: the detector historically most exposed to monorepo and cross-package false positives.'
+    - template: 'scip-query twin-drift -s <scope> --json'
+      when: 'Sample: same-name divergence groups to classify from the code.'
+    - template: 'scip-query similar <symbol>'
+      when: 'Sample: callee-overlap pairs to classify from the code.'
+    - template: 'scip-query code <selector>'
+      when: 'Classify: read the cited site; the finding text is never the evidence.'
+    - template: 'scip-query suppress <id> --reason <text>'
+      when: 'Tune: record one accepted finding with a concrete reason.'
+    - template: 'scip-query config-validate'
+      when: 'Tune: validate .scipquery.json and suppressions after every knob change.'
+---
+
+# scip-calibrate
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
+| --- | --- |
+| `scip-query capabilities --matrix` | Inventory: which languages got which evidence tier before judging any detector. |
+| `scip-query health --json` | Battery sweep: every detector finding count as a sampling frame, not a verdict. |
+| `scip-query dead --json` | Sample: the detector historically most exposed to monorepo and cross-package false positives. |
+| `scip-query twin-drift -s <scope> --json` | Sample: same-name divergence groups to classify from the code. |
+| `scip-query similar <symbol>` | Sample: callee-overlap pairs to classify from the code. |
+| `scip-query code <selector>` | Classify: read the cited site; the finding text is never the evidence. |
+| `scip-query suppress <id> --reason <text>` | Tune: record one accepted finding with a concrete reason. |
+| `scip-query config-validate` | Tune: validate .scipquery.json and suppressions after every knob change. |
+
+These commands are controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct question. There is no required sequence or query limit. Run a command's `--help` when you need a flag not shown in its template.
+<!-- END GENERATED SKILL COMMANDS -->
+
+Use this skill to measure whether scip-query's detectors tell the truth about a specific repository before believing anything they say about it. A detector tuned on one codebase's conventions can be precise there and noisy elsewhere. Calibration is how you find out which you have, and it converts every noise archetype you find into either a repo-side knob or an upstream detector bug.
+
+## The Stance
+
+A health score you have not calibrated is a number, not a fact. Never present detector output from an uncalibrated repo as findings; present it as candidate findings pending classification. The score must EARN trust the same way a checker earns it in `$scip-integrity-audit`: by being witnessed telling the truth on samples you verified yourself.
+
+## Protocol
+
+Run all four stages. Each has a checkable exit.
+
+### 1. Index and inventory
+
+Run `scip-query status` and, if the index is stale or missing, `scip-query reindex`. Then `scip-query capabilities --matrix`. Record which languages got which evidence tier (SCIP-indexed versus source-fallback versus regex). A detector's expected precision differs per tier, and a repo that is mostly fallback-tier must be judged against fallback expectations. Note monorepo shape (workspaces, cross-package imports): historically the single largest false-positive source, with `dead` flagging cross-package consumers.
+
+Complete when: languages, tiers, and workspace shape are written down.
+
+### 2. Battery sweep
+
+Run `scip-query health --json` and the standalone detectors it does not include (`twin-drift`, `decorative-checkers`, `not-implemented`, `test-quality`). Do not react to anything yet. Big numbers are not findings; they are sampling frames.
+
+Watch for finding WALLS: one hub file or one convention mismatch generating dozens of near-identical findings. A wall is always either a missing repo knob or a detector bug. It is never "the repo is just bad."
+
+Complete when: every detector's finding count and every wall are recorded.
+
+### 3. Sample and classify (the actual calibration)
+
+For each detector with findings: sample about 10 (all of them if fewer), READ THE CODE at each site with `scip-query code`, and classify actionable versus noise. Two rules make this real calibration instead of theater:
+
+- Classify from the code, never from the finding text. A finding that sounds plausible and a finding that is true are different things; the difference is only visible at the cited file and line.
+- For every noise finding, name the ARCHETYPE (for example "type-only import invisible to indexer", "delegation chain flagged as twin", "generic shared helpers saturating similarity"). Archetypes are the deliverable: a noise rate without archetypes cannot be fixed.
+
+Then give each detector a verdict: **keep** (precision acceptable), **retune** (name the threshold and the value), or **demote to advisory** for this repo.
+
+Complete when: every detector has sampled precision, named archetypes, and a verdict.
+
+### 4. Tune the knobs, file the bugs
+
+Apply repo-side fixes for what belongs to the repo, and file upstream for what belongs to the detector:
+
+- `scip-query suppress <id> --reason <text>`: one per accepted finding, WITH a concrete reason. A reasonless suppression is hiding, not tuning.
+- `docs.snapshotPaths` in `.scipquery.json`: dated or archival docs that must never generate doc-drift findings.
+- Coverage contracts: enumerations the detectors should police.
+- `commandAnalysisBudget`: cap analysis honestly on very large indexes.
+- Detector bugs (noise archetypes no knob can express) go upstream with the archetype, a concrete example, and the sampled rate. Never tune a threshold to hide an archetype; that trades visible noise for invisible blindness.
+
+Run `scip-query config-validate` after every knob change.
+
+Complete when: the battery from stage 2 re-runs materially quieter, and every remaining finding class is either actionable, suppressed with a reason, or filed upstream.
+
+## Failure Modes (each observed in a real calibration)
+
+- **Sampling too few.** One good finding does not make a detector precise; one bad finding does not make it noise. Ten per detector is the floor.
+- **Classifying from the finding text.** The finding always sounds right; it was generated to. Only the code knows.
+- **Tuning to green.** Raising a threshold until the noise disappears also disappears the real findings. If the archetype is a detector bug, file it and live with the noise until it is fixed.
+- **Trusting a clean run.** Zero findings on a detector can mean precision or can mean the detector cannot see this repo's conventions at all (wrong import style, unindexed language). Verify at least one known-true positive per major detector; plant one if none exists.
+- **Calibrating the wrong tree.** Use clones or worktrees for anything that mutates; the target repo is read-only unless its owner said otherwise.
+
+## After Calibration
+
+Write the calibration report to `docs/validation/YYYY-MM-DD-external-calibration-<repo>.md`: battery table, walls, per-detector verdicts, noise archetypes, caps and deviations. Re-run this protocol only after major detector upgrades or when detector behavior visibly drifts from what you measured.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'SCIP Calibrate'
+  short_description: "Measure scip-query's detector precision on a repository before trusting its scores"
+  default_prompt: 'Run the $scip-calibrate protocol against this repository: inventory evidence tiers, sweep the detector battery, sample and classify each detector from the code, then tune repo knobs and file detector bugs.'