scip-query 0.20.0 → 0.21.1

package/skills/scip-integrity-audit/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: scip-integrity-audit
+description: Audit whether implementations are real with scip-query. Use for suspected faked or half-implemented features, decorative checkers or verifiers that never fail, dead code paths hidden behind graceful fallbacks, metrics that may be lying, or a "does any of this actually work" interrogation of a system.
+metadata:
+  commands:
+    - template: 'scip-query search <text>'
+      when: 'Locate a status word, checker name, adapter, fallback, or metric producer.'
+    - template: 'scip-query outline <file>'
+      when: 'Inventory the callables in a known file before choosing a drill target.'
+    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
+      when: 'Project callers, callees, or dataflow around a checker, adapter, fallback, or metric.'
+    - template: 'scip-query inspect --at <file:line> --view behavior'
+      when: 'Read connected behavior for a named remaining gap after graph evidence.'
+    - template: 'scip-query code <selector>'
+      when: 'Read exact implementation syntax only when the body itself can change the verdict.'
+    - template: 'scip-query decorative-checkers -s <scope> --json'
+      when: 'Shortlist validate/verify/check/assert/is/has callables with no reachable failure exit.'
+    - template: 'scip-query not-implemented -s <scope> --json'
+      when: 'Shortlist reachable placeholder stubs that a real caller can actually reach.'
+    - template: 'scip-query test-quality -s <scope> --json'
+      when: 'Check regression artifacts and tests for assertion-free bodies, skip rot, and mock-echo.'
+    - template: 'scip-query twin-drift -s <scope> --json'
+      when: 'Find same-name or near-name twins whose bodies have silently diverged.'
+    - template: 'scip-query twin-ab <symbolA> <symbolB>'
+      when: 'Scaffold a table-driven comparison of two same-concept twins on a shared input.'
+---
+
+# scip-integrity-audit
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
+| --- | --- |
+| `scip-query search <text>` | Locate a status word, checker name, adapter, fallback, or metric producer. |
+| `scip-query outline <file>` | Inventory the callables in a known file before choosing a drill target. |
+| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project callers, callees, or dataflow around a checker, adapter, fallback, or metric. |
+| `scip-query inspect --at <file:line> --view behavior` | Read connected behavior for a named remaining gap after graph evidence. |
+| `scip-query code <selector>` | Read exact implementation syntax only when the body itself can change the verdict. |
+| `scip-query decorative-checkers -s <scope> --json` | Shortlist validate/verify/check/assert/is/has callables with no reachable failure exit. |
+| `scip-query not-implemented -s <scope> --json` | Shortlist reachable placeholder stubs that a real caller can actually reach. |
+| `scip-query test-quality -s <scope> --json` | Check regression artifacts and tests for assertion-free bodies, skip rot, and mock-echo. |
+| `scip-query twin-drift -s <scope> --json` | Find same-name or near-name twins whose bodies have silently diverged. |
+| `scip-query twin-ab <symbolA> <symbolB>` | Scaffold a table-driven comparison of two same-concept twins on a shared input. |
+
+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 interrogate whether a system's claims are backed by real
+implementations. Structural review asks "is this well organized?"; this skill
+asks **"is this real?"** — it hunts decorative checkers, adapters written
+against imagined data, features that have silently never run, and numbers
+nobody ever recomputed.
+
+Use `$scip-query` locators and evidence projections to inventory producers.
+`health --full` does not run the integrity detectors; call
+`decorative-checkers`, `not-implemented`, `test-quality`, and `twin-drift`
+directly.
+
+## The Stance
+
+A green result you have never seen fail is unverified. Every status word,
+banner, and metric is testimony from the code, not evidence about the code —
+cross-examine the producer before believing it. The most dangerous code is
+not broken code; it is code that reports success without doing the work.
+
+## Drills
+
+Run all five over the chosen scope. Each has a checkable exit.
+
+### 1. Falsify every checker
+
+Inventory everything in scope that accepts/rejects, passes/fails, or
+validates (checkers, gates, verifiers, validators — find producers with
+`search` on the status words in output, then `evidence` execution incoming
+and outgoing). For each one, construct an input that MUST fail — a wrong
+binding, a corrupt file, an impossible value — and run it. A checker that
+passes its should-fail input is decorative: file it as a defect, not a note.
+Before filing, attempt the defense: an accusation triggers a rewrite, so
+search for the failure exit the drill may have missed — a config-gated
+branch, an async rejection, one-hop delegation (the calibration's known
+noise archetypes). File the defect with the executed should-fail input
+attached and the defense attempt noted; a defense that succeeds clears the
+checker and stays in the record as its witness.
+Complete only when every checker in scope has been witnessed rejecting a
+constructed should-fail input, or is listed with a reason it cannot be.
+
+Mechanized by: `scip-query decorative-checkers` finds `validate*`/`verify*`/
+`check*`/`assert*`/`is*`/`has*` callables with no reachable failure exit
+anywhere in their body (calibrated 2026-07-03 against two external repos —
+standalone-only; noise archetypes past one-hop delegation in
+`docs/validation/2026-07-03-integrity-detector-calibration.md`). Run it first
+to shortlist candidates before hand-constructing should-fail inputs.
+
+### 2. Diff every adapter against captured reality
+
+For each parser/adapter of an external format (tool output, XML/JSON
+schemas, protocol messages): obtain ONE real sample from the actual source
+and diff it against the code's assumptions and the tests' fixtures. Ask of
+every fixture: was this generated from reality, or imagined? A parser and a
+hand-written fixture can validate each other's shared hallucination
+indefinitely.
+Complete only when every adapter has been checked against at least one
+captured-real sample.
+
+### 3. Autopsy every fallback
+
+Graceful degradation is where dead features hide: a primary path that has
+never worked looks identical to a healthy fallback. For every catch block,
+`?? fallback`, and degraded mode in scope: produce an execution witness that
+the PRIMARY path runs (a test, a probe, a log). Use `evidence` execution and
+`inspect --view behavior` for branch reachability. A fallback that always
+fires means the feature above it is dead — date of death: birth.
+Complete only when every fallback's primary path has a witness or a filed
+defect.
+
+Mechanized by: `scip-query not-implemented` finds reachable placeholder
+stubs (`throw new Error('not implemented')`, TODO-comment + return-default,
+empty bodies) that a real caller, entry surface, or package-surface export
+can actually reach — the graph fact that separates "primary path never
+built" from `dead`'s "primary path built but unreferenced." Standalone-only
+(calibrated 2026-07-03; 0 live findings on two external repos post-fix, see
+the calibration report) — treat a clean run as "nothing this shape found,"
+not as "every fallback's primary path is proven live."
+
+### 4. Hand-compute every metric twice
+
+For each number the system reports (scores, counts, estimates): pick two
+concrete instances, compute the expected value by hand from first
+principles, and compare. Off-by-a-factor errors (double counting, inflated
+estimates) survive for years because nobody ever recomputes one sample.
+Complete only when every reported metric has two hand-verified samples.
+
+### 5. Cross-examine same-concept twins
+
+Where one concept is computed in more than one place, feed both the same
+input and require the same answer. `twin-drift` finds the same-name cases
+mechanically; for same-concept-different-name pairs, project consumers with
+`evidence` execution incoming and compare implementations with `code`. Once
+a pair is identified, `scip-query twin-ab <symbolA> <symbolB>` scaffolds a
+table-driven vitest file that imports both and asserts equal output —
+fill in the input table and run it. Disagreement between twins means at
+least one is wrong — determine which before consolidating.
+Complete only when every discovered twin pair has been compared on a shared
+input.
+
+## Severity
+
+Rank findings by what the failure does to a user who trusted the output:
+a decorative checker or false "verified" banner outranks everything; a
+dead-but-fallbacked feature outranks a wrong metric; a wrong metric outranks
+structural mess. Structural findings are real, but they are not lies — do
+not fold them into the integrity verdict.
+
+## Reporting
+
+File each finding with: the claim as displayed, the producer (file:line),
+the drill that exposed it, the should-fail input or real sample used, and
+the fix. The audit is complete only when every drill's exit criterion is
+met for the scope, and every defect found has a regression artifact — a
+test, fixture, or model that fails on the pre-fix behavior.
+
+End with a derived verdict, not an impression:
+
+```markdown
+Integrity: <scope> — <c> checkers witnessed failing, <a> adapters diffed
+against reality, <f> fallback primaries witnessed live, <m> metrics
+recomputed, <t> twins compared; <d> defects filed, <u> unverifiable (reasons)
+```
+
+A suspect scope that produces zero defects is itself a claim: state what
+made the suspicion wrong, or rerun the drill that should have caught it.
+
+A regression artifact that doesn't actually assert anything, or asserts the
+same literal it stubbed into its own mock, is a fake witness — the same
+"reports success without doing the work" failure mode this skill hunts in
+production code, just relocated to the test suite. Run `scip-query
+test-quality -s <scope>` over the audit's own regression artifacts (and,
+periodically, over the suite at large) to catch this: assertion-free test
+bodies, a skipped-test ledger with git-blame age (a skip with no fix date
+attached is a claim nobody is checking), and mock-echo (a test that only
+proves its own stub). Standalone-only, mixed precision by sub-check
+(calibrated 2026-07-03): assertion-free and skipped are high-precision;
+mock-echo is intentionally low-precision (syntactic same-literal matching,
+not dataflow) — treat its output as a reviewed candidate list, not a verdict.

package/skills/scip-integrity-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'scip integrity audit'
+  short_description: 'Interrogate whether implementations are real: falsify checkers, diff adapters against reality, autopsy fallbacks.'
+  default_prompt: 'Run the scip-integrity-audit drills over this codebase and report every decorative checker, dead-behind-fallback feature, and lying metric.'

package/skills/scip-plan/SKILL.md

@@ -1,68 +1,86 @@
 ---
 name: scip-plan
-description: Use before, during, AND after non-trivial work: plan a change, migration, or refactor; assess what breaks when changing a public export, module boundary, schema, route, CLI command, config field, generated artifact, signature, or documented behaviour; conduct a multi-phase program and review a delegated agent's work mid-flight; plan a performance campaign; scaffold a TLA+ model before implementing, and trace-check it against the real system afterward. Distinct from the `review` skill, which reviews a finished branch or PR against coding standards and the originating spec — this one oversees a program you are conducting.
-commands:
-  - template: "scip-query plan-context <target>"
-    when: "Anchor the current flow, consumers, reuse options, and change risks."
-  - template: "scip-query refs <symbol>"
-    when: "Complete or narrow the direct consumer set for a planned symbol change."
-  - template: "scip-query affected <symbol>"
-    when: "Measure transitive impact when the change is not consumer-local."
+description: Write a concise, code-grounded implementation plan for a non-trivial feature, fix, refactor, migration, or retirement. Use scip-query as the primary repository exploration surface and cite exact owners, relationships, behavior, and consumers.
+metadata:
+  commands:
+    - template: 'scip-query search <text>'
+      when: 'Locate exact repository text, a runtime key, or a compiler symbol; use `scip-query search -- <text>` when the literal starts with a dash.'
+    - template: 'scip-query outline <file>'
+      when: 'Locate compiler-owned constructs in a known file.'
+    - template: 'scip-query entrypoints <text>'
+      when: 'Locate an external callable root when its entry surface is known.'
+    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
+      when: 'Project explicitly selected typed relationships from one exact root.'
+    - template: 'scip-query inspect --at <file:line> --view behavior'
+      when: 'Read connected behavior for a named implementation gap.'
+    - template: 'scip-query code <selector>'
+      when: 'Read exact source only when syntax itself can change the decision.'
+    - template: 'scip-query diff-impact'
+      when: 'Map changed symbols and downstream consumers after an edit.'
+    - template: 'scip-query architecture'
+      when: 'Validate declared structural boundaries.'
+    - template: 'scip-query health --full'
+      when: 'Run configured cleanup and quality detectors.'
 ---
 
-# scip-plan
+# SCIP Plan
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` | Anchor the current flow, consumers, reuse options, and change risks. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | referencing file paths; reference line numbers grouped by file | `bounded` | Complete or narrow the direct consumer set for a planned symbol change. |
-| `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Measure transitive impact when the change is not consumer-local. |
+Write a plan that another coding agent can execute without rediscovering the relevant system.
 
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
+| --- | --- |
+| `scip-query search <text>` | Locate exact repository text, a runtime key, or a compiler symbol; use \`scip-query search -- <text>\` when the literal starts with a dash. |
+| `scip-query outline <file>` | Locate compiler-owned constructs in a known file. |
+| `scip-query entrypoints <text>` | Locate an external callable root when its entry surface is known. |
+| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project explicitly selected typed relationships from one exact root. |
+| `scip-query inspect --at <file:line> --view behavior` | Read connected behavior for a named implementation gap. |
+| `scip-query code <selector>` | Read exact source only when syntax itself can change the decision. |
+| `scip-query diff-impact` | Map changed symbols and downstream consumers after an edit. |
+| `scip-query architecture` | Validate declared structural boundaries. |
+| `scip-query health --full` | Run configured cleanup and quality detectors. |
+
+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
+<!-- BEGIN GENERATED EXPLORATION MANUAL -->
+### Choose a relationship deliberately
 
-Plan and conduct work: a single non-trivial change, public-surface impact, a multi-phase program carried end to end with verification at each handoff (including reviewing a delegated agent's work in flight), a benchmark-driven optimization campaign, and TLA+ modelling both before implementation and as post-implementation trace-conformance.
+| Question | Evidence family | Direction |
+|---|---|---|
+| Who can call or reach this? | `execution` | `incoming` |
+| What can this call or reach? | `execution` | `outgoing` |
+| Where can this value come from? | `dataflow` | `incoming` |
+| Where can this value go? | `dataflow` | `outgoing` |
+| Which producer and consumer rendezvous? | `runtime` | `both` |
+| What resource is observed or changed? | `state` | `both` |
+| What occurs before or after this? | `temporal` | `both` |
+| What interface constrains this? | `contract` | `both` |
+| Are these observations the same entity? | `identity` | `both` |
+| What contains or owns this? | `ownership` | `both` |
+| What does this statically rely on? | `dependencies` | `outgoing` |
 
-Shared mechanics (lookup tips, command families, postchecks, subagent-briefing text, general command catalogue) live in `../_shared/SKILL.md` — load it only when this skill's own shortlist is insufficient.
+Use exact evidence as an observed fact only within its coverage. Derived evidence is deterministically computed; candidate evidence is a lead; mixed evidence must retain its constituent strengths; unknown evidence cannot support a stronger claim. Missing output is not evidence of absence.
 
-## Pick the mode first
+The controls above are complete for ordinary exploration. Run `scip-query capabilities --matrix` only when a named claim depends on uncertain provider support; do not run it for routine orientation.
+<!-- END GENERATED EXPLORATION MANUAL -->
 
-| Situation | Do this |
-|---|---|
-| One non-trivial change, refactor, migration, or bug fix | Ordinary-mode scenario below |
-| The change touches a security boundary, money, a destructive/irreversible op, a persistent-data migration, shared-state concurrency, a broad public API, or an unrollback-able rollout — or the user asks for the rigorous version | `references/high-assurance.md` |
-| You're about to edit a public export, route, schema, CLI command, config field, generated artifact, or documented behavior, and need to know what breaks | `references/api-impact.md` |
-| You're running a multi-phase program: writing an executable plan, delegating steps, reviewing a subagent's work mid-flight, or carrying a change end to end | `references/conductor.md` |
-| You need something faster and must prove the speedup with measurements | `references/hyper-optimization.md` |
-| You need a TLA+ model of a risky protocol, before or after implementation | `references/tla-model.md` |
+scip-query is a repository exploration surface: an indexed code reader that joins exact current text to compiler-owned identities and typed relationships. Use it as the primary exploration surface for tracked repository text. Treat its commands as controls, not a checklist. Use every capability needed by the change, but make each query answer a distinct repository question. There is no mandatory sequence, required anchor phase, or query-count limit.
 
-Picking the mode matters: running the high-assurance certificate on routine work is how planning becomes a tax people route around. When genuinely unsure whether a change needs a heavier mode, ask rather than defaulting up.
+Before planning, understand the relevant initiating surfaces, behavior owners, decisions, data transformations, effects, consumers, existing reuse opportunities, and structural constraints. Use one discriminating locator and reuse its results as graph roots; do not repeat generic synonym searches after usable candidates exist. When several implementations match, compare their entry surfaces, incoming execution, ownership, callers, or runtime connections before selecting one. Locator results are graph roots, not relevance rankings. Read coverage and recovery before making complete-set or absence claims. Use native tools only for edits, checks, binary content, or a specific unsupported gap reported by scip-query.
 
-## Scenario: plan a single non-trivial change (ordinary mode, the default)
+Do not write a plan for one obvious local edit. Write one when correctness depends on several owners or files, downstream consumers, a migration or retirement, reuse of existing behavior, architecture rules, or several coherent implementation slices. Put it in `docs/plans/YYYY-MM-DD-<name>.md` only when it must survive a context reset.
 
-Apply `_shared`'s freshness gate once before citing the first graph fact; let an active watcher handle refreshes and use manual reindex only as the documented fallback. Then run `scip-query plan-context <target>` — the single anchoring call for planning. Its composite return already includes definitions, references, callers, callees, dataflow producers/consumers, forward and backward slices, affected symbols, change-surface risk, dependencies and reverse dependencies, module exports, external surface use, complexity, churn, co-change partners, and active suppressions, so the job is to interpret this composite rather than rebuild a proof system on top of it.
+## Plan shape
 
-Reach for a second command only when a section `plan-context` returned came back bounded (not complete) or the target wasn't indexed: `scip-query refs <symbol>` to enumerate consumers in full, `scip-query affected <symbol>` for the transitive blast radius when the change isn't consumer-local, `scip-query code <symbol>` to read the source behind a behavior claim before writing it into the plan.
+State the observable outcome in one or two sentences. Explain the current behavior with exact symbol and file/line references. Then use this table:
 
-Write the plan to `docs/plans/YYYY-MM-DD-<short-name>.md` with these sections:
-
-- **Goal** — what the user is trying to accomplish, and what done looks like for them.
-- **Current Flow** — the affected path from entry point to observable effect, in prose, with evidence behind each claim; if current behavior can't be described end to end, the change isn't ready to make.
-- **Affected Consumers** — who calls/imports/reads the changed code and what breaks if the contract shifts; state explicitly whether the list is complete or bounded — a capped list presented as complete is worse than one flagged as bounded.
-- **Reuse Decision** — for every new helper/wrapper/type/parameter/flag/component/hook/module, name what it could have extended instead and why extension loses. New parallel code with no reuse decision is the single most common defect this skill exists to prevent.
-- **Slices** — ordered implementation steps, each naming its files/symbols, the behavior change, and the validation (a test, command, or specific manual check) that proves it. A slice with no validation is a wish.
-- **Risks and Unknowns** — what could go wrong, what couldn't be established, and any rollout constraint; keep unknowns explicit rather than rounding them to assumptions.
-
-The plan is done only when: the entry-to-effect path is described and evidenced, every affected consumer is assigned to a slice or explicitly out of scope, every new unit has a reuse decision, every slice has validation, and unknowns are written down rather than resolved by guessing. Then implement in the smallest coherent slice and run `scip-verify` when the change lands.
-
-## Owned command quick-reference
+| Step | Code reference | Change | Preserve or retire | Verify |
+| --- | --- | --- | --- | --- |
+| Coherent implementation slice | Exact symbol and file/line | Concrete edit and why it belongs here | Existing behavior to keep or residue to remove | Check that fails when the outcome is absent |
 
-`bench`, `work-audit` → performance campaigns, see `references/hyper-optimization.md`.
-`tla`, `tla scaffold`, `tla verify`, `tla instrument`, `tla trace-check`, `tla fetch-tools` → model scaffolding and conformance, see `references/tla-model.md`.
+Order the rows so each leaves the repository in a valid state. Include the relevant entry point, behavior owner, downstream consumers, reuse candidates, architecture constraints, migration or cleanup, and validation. Label design choices as choices. Include an open-uncertainty section only when an unresolved repository fact can change the implementation, and name the exact scip-query command that would answer it.
 
-Everything else used above (`plan-context`, `refs`, `affected`, `code`, `surface`, `co-change`, `doc-drift`, `diff-gate`, `health`, `call-graph`, `complexity`, `change-surface`, ...) is general catalogue — see `../_shared/SKILL.md` for the full vocabulary.
+The plan is ready when another agent can implement it without a broad repository rediscovery pass.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "SCIP Plan & Conduct"
-  short_description: "Plan and conduct work with SCIP evidence"
-  default_prompt: "Use $scip-plan to plan this change, assess what it breaks, and conduct it through to verified completion."
+  display_name: 'SCIP Plan'
+  short_description: 'Write concise repository-grounded implementation plans'
+  default_prompt: 'Use $scip-plan to explore the relevant system with scip-query and write a concise implementation plan grounded in exact symbol and file/line references.'

package/skills/scip-query/SKILL.md

@@ -1,82 +1,103 @@
 ---
 name: scip-query
-description: Use FIRST for codebase work that should rest on SCIP evidence. Routes understanding to scip-explore, prospective changes to scip-plan, failures to scip-diagnose, read-only problem finding to scip-audit, confirmed fixes to scip-improve, adoption or repair to scip-setup, and finished diffs to scip-verify.
+description: Use FIRST for codebase work when compiler-resolved identity, runtime boundaries, callers, dependencies, consumers, architecture, change impact, or cleanup relationships can affect the answer. It exposes exact referents, explicit typed-graph projections, and source evidence; it does not infer task relevance. Pair it with scip-explore when the task is to understand a repository system end to end.
+metadata:
+  commands:
+    - template: 'scip-query watch --daemon'
+      when: 'When the user explicitly asks to use scip-query, make sure the background watcher for the exact target worktree is running before the first exploration command.'
+    - template: 'scip-query watch --status'
+      when: 'Check whether the watcher for the current worktree is running, refreshing, idle, or failed.'
+    - template: 'scip-query watch --stop'
+      when: 'Stop the watcher owned by the current worktree when the user asks to turn it off.'
+    - template: 'scip-query search <text>'
+      when: 'Locate exact repository text, a runtime key, or a compiler symbol; use `scip-query search -- <text>` when the literal starts with a dash.'
+    - template: 'scip-query outline <file>'
+      when: 'Locate compiler-owned constructs in a known file.'
+    - template: 'scip-query entrypoints <text>'
+      when: 'Locate an external callable root when its entry surface is known.'
+    - template: 'scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
+      when: 'Project explicitly selected typed relationships from one exact root.'
+    - template: 'scip-query inspect --at <file:line> --view behavior'
+      when: 'Read connected behavior for a named implementation gap.'
+    - template: 'scip-query code <selector>'
+      when: 'Read exact source only when syntax itself can change the decision.'
+    - template: 'scip-query diff-impact'
+      when: 'Map changed symbols and downstream consumers after an edit.'
+    - template: 'scip-query architecture'
+      when: 'Validate declared structural boundaries.'
+    - template: 'scip-query health --full'
+      when: 'Run configured cleanup and quality detectors.'
 ---
 
-# SCIP Query Router
-
-## Purpose
-
-Choose one owning workflow before acting. An owning workflow is the bundled
-skill whose completion criterion matches the request: understanding, planning,
-diagnosis, read-only auditing, implementation, setup, or verification. The
-router does not perform that workflow itself.
-
-Load `../_shared/SKILL.md` only after the owning workflow's shortlist proves
-insufficient. The shared reference contains the complete command vocabulary,
-coverage rules, and evidence contract; loading it before a route is selected
-adds choices without adding direction.
-
-Run commands normally for agent reading: the human renderer preserves
-hierarchy, whitespace, and line numbers without transport metadata. Select
-`--json` only when a program will parse the response; add `--result-only` when
-that program needs only the command result rather than the stable public
-envelope. Do not select `--compact` or `--output-page-size` for readability.
-Follow an emitted continuation command only when the command itself says the
-output is incomplete. The final transport-complete footer means every rendered
-character was retrieved; inspect command coverage separately before claiming
-the logical result is exhaustive.
-
-## Routes
-
-| The request starts from… | Owning skill | Completion criterion |
-| --- | --- | --- |
-| Existing code that must be understood, traced, or diagrammed | `scip-explore` | Entry points, flow, dependencies, consumers, and remaining uncertainty are evidenced. |
-| A proposed feature, refactor, migration, API change, performance campaign, TLA+ model, or multi-phase program | `scip-plan` | Current flow, affected consumers, reuse decisions, ordered slices, validation, and risks are explicit. |
-| A failure, regression, recurring bug family, raw issue, or parser/AST reachability question | `scip-diagnose` | The observed failure is connected to a cause, rivals are rejected, and the smallest fix packet is defined. |
-| A question about whether problems exist, without permission to edit | `scip-audit` | The scoped items are classified and ranked with evidence; no code or docs are changed. |
-| Confirmed cleanup, drift, maintainability, frontend, directory, twin, or documentation findings that should be fixed | `scip-improve` | One coherent finding slice is changed and passes its routed postchecks. |
-| First adoption, broken setup, missing capabilities, skill installation, hooks, CI, or uninstall | `scip-setup` | The workspace is ready, or every unavailable capability has an explicit blocker. |
-| A finished diff that must be challenged before commit or release | `scip-verify` | Workspace, impact, applicable postchecks, gate findings, and refutation attempts are all accounted for. |
-
-## Disambiguation
-
-- Existing behavior with no symptom routes to `scip-explore`; a contradiction
-  or failure routes to `scip-diagnose`.
-- Finding and classifying problems without edits routes to `scip-audit`;
-  changing already-confirmed findings routes to `scip-improve`.
-- Prospective work routes to `scip-plan`; a concrete finished diff routes to
-  `scip-verify`.
-- Setup wins whenever the index or a required capability is missing, stale,
-  invalid, or not yet installed.
-- A request may cross workflows in sequence. Keep one owner at a time:
-  diagnose before planning a fix, audit before improving, plan before a
-  non-trivial implementation, and verify after every implemented slice.
-
-## Default non-trivial change loop
-
-1. Invoke `scip-plan`, anchored by
-   `scip-query plan-context <target>`.
-2. Implement the smallest coherent planned slice.
-3. Invoke `scip-verify`; do not declare completion until it passes or every
-   remaining finding has a specific evidence-backed disposition.
-
-Routing is complete only when exactly one owner is selected for the current
-phase, or the request is small enough that no compiler-resolved relationship
-claim is needed.
-
-<!-- BEGIN GENERATED ROUTER COMMAND PREVIEW -->
-## Command Preview
-
-Top commands per routed skill, generated from each skill's own `commands:` frontmatter.
-
-| Skill | Top commands |
+# scip-query
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Command and question manual
+
+| Command syntax | Question it answers |
 | --- | --- |
-| `scip-audit` | `scip-query health`, `scip-query decorative-checkers --full`, `scip-query doc-drift --full` |
-| `scip-diagnose` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
-| `scip-explore` | `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>`, `scip-query affected <symbol>` |
-| `scip-improve` | `scip-query cleanup-plan --verify`, `scip-query cleanup-apply --verified --batch <n> --dry-run`, `scip-query diff-gate` |
-| `scip-plan` | `scip-query plan-context <target>`, `scip-query refs <symbol>`, `scip-query affected <symbol>` |
-| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --capabilities` |
-| `scip-verify` | `scip-query doctor`, `scip-query diff-impact`, `scip-query diff-gate` |
-<!-- END GENERATED ROUTER COMMAND PREVIEW -->
+| `scip-query watch --daemon` | When the user explicitly asks to use scip-query, make sure the background watcher for the exact target worktree is running before the first exploration command. |
+| `scip-query watch --status` | Check whether the watcher for the current worktree is running, refreshing, idle, or failed. |
+| `scip-query watch --stop` | Stop the watcher owned by the current worktree when the user asks to turn it off. |
+| `scip-query search <text>` | Locate exact repository text, a runtime key, or a compiler symbol; use \`scip-query search -- <text>\` when the literal starts with a dash. |
+| `scip-query outline <file>` | Locate compiler-owned constructs in a known file. |
+| `scip-query entrypoints <text>` | Locate an external callable root when its entry surface is known. |
+| `scip-query evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project explicitly selected typed relationships from one exact root. |
+| `scip-query inspect --at <file:line> --view behavior` | Read connected behavior for a named implementation gap. |
+| `scip-query code <selector>` | Read exact source only when syntax itself can change the decision. |
+| `scip-query diff-impact` | Map changed symbols and downstream consumers after an edit. |
+| `scip-query architecture` | Validate declared structural boundaries. |
+| `scip-query health --full` | Run configured cleanup and quality detectors. |
+
+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 -->
+
+## Watcher lifecycle
+
+The scip-query watcher is a project-scoped background refresh service: one process owned by one worktree that observes that worktree's configured compiler inputs and keeps its index current after relevant changes. It is not a global service, and starting it in one worktree must not start watchers for sibling worktrees.
+
+When the user explicitly names scip-query, invokes `$scip-query`, or asks the agent to use it, run `scip-query watch --daemon` from the exact target project root before the first exploration command. Treat both a newly started watcher and an already-running watcher as success; reuse the existing process instead of starting another. This automatic start applies only to an explicit request to use scip-query. Merely opening a repository or shell must not start it.
+
+Use the normal command without `CHOKIDAR_USEPOLLING` or another forced polling override. If startup fails, report the exact failure; do not silently start a watcher in another worktree, force polling, or substitute an unbounded full rebuild.
+
+Run `scip-query watch --status` from the same project root to inspect the watcher. Run `scip-query watch --stop` from that root when the user asks to stop it. The stop command targets only that worktree's watcher; do not stop watchers owned by other worktrees unless the user names them.
+
+<!-- BEGIN GENERATED EXPLORATION MANUAL -->
+### Choose a relationship deliberately
+
+| Question | Evidence family | Direction |
+|---|---|---|
+| Who can call or reach this? | `execution` | `incoming` |
+| What can this call or reach? | `execution` | `outgoing` |
+| Where can this value come from? | `dataflow` | `incoming` |
+| Where can this value go? | `dataflow` | `outgoing` |
+| Which producer and consumer rendezvous? | `runtime` | `both` |
+| What resource is observed or changed? | `state` | `both` |
+| What occurs before or after this? | `temporal` | `both` |
+| What interface constrains this? | `contract` | `both` |
+| Are these observations the same entity? | `identity` | `both` |
+| What contains or owns this? | `ownership` | `both` |
+| What does this statically rely on? | `dependencies` | `outgoing` |
+
+Use exact evidence as an observed fact only within its coverage. Derived evidence is deterministically computed; candidate evidence is a lead; mixed evidence must retain its constituent strengths; unknown evidence cannot support a stronger claim. Missing output is not evidence of absence.
+
+The controls above are complete for ordinary exploration. Run `scip-query capabilities --matrix` only when a named claim depends on uncertain provider support; do not run it for routine orientation.
+<!-- END GENERATED EXPLORATION MANUAL -->
+
+scip-query is a repository exploration surface: an indexed code reader that joins exact current text to compiler-owned identities and typed relationships. Native text and file tools expose matches and slices; scip-query additionally exposes how code units call, carry data, cross runtime boundaries, observe or change state, occur in order, satisfy contracts, share identity, contain one another, and depend on one another. It performs the control you select; it does not infer task relevance or decide what the user meant.
+
+For end-to-end system understanding, load `$scip-explore` alongside this skill. `scip-explore` owns the material-fact model, evidence integration, answer audit, and stopping judgment; this skill remains the calibrated sensing and source-reading surface.
+
+Use scip-query as the primary exploration surface for tracked repository text. Treat its commands as controls, not a checklist. Use every capability needed by the task, but make each query answer a distinct repository question. There is no mandatory sequence, required anchor phase, or query-count limit. Thoroughness means understanding the relevant system end to end, not exhausting the repository.
+
+Use one discriminating exact `search`, `outline`, or `entrypoints` locator, then reuse every returned symbol or `file:line` as an `evidence` root. Do not repeat generic synonym searches after usable candidates exist. Locator ordering does not establish relevance. When several implementations match the same vocabulary, do not select one by path, naming, apparent recency, or result order. Compare their entry surfaces, incoming execution, ownership, callers, or runtime connections; if the repository does not establish one as authoritative, explain the alternatives and their scopes.
+
+An evidence projection accepts repeated `--symbol`, `--at`, or `--search` roots and repeated `--edge <family>` flags; always choose `--direction incoming|outgoing|both`, `--depth <n>`, and `--max-edges <n>` explicitly. Use `--subtype <subtype>` to narrow a family, `--connecting` when the selected roots themselves must be connected, and `--inventory-only` when counts alone can choose the next bounded projection.
+
+Read each command's request, observed facts, evidence calibration, coverage, and recovery together. Exact observations are facts only within their reported coverage. Derived observations are deterministic computations. Candidate observations require confirmation. Missing or bounded output is not evidence of absence.
+
+An emitted `Continue exactly:` command is a cursor: a next-page read from one immutable rendered result. It is required transport, not optional evidence expansion. Run the emitted command unchanged and repeat until no continuation remains before interpreting that command's complete result. Do not rerun the original query or alter cursor flags. Continuation reads saved output without repository preparation, reindexing, or watcher startup. Printed recovery and expansion commands are different: run those only when their omitted evidence matters.
+
+Prefer human output for agent reading. If a model-facing consumer genuinely needs JSON, add `--json --agent-output`; add `--result-only` only when the common envelope is unnecessary, and drain every emitted cursor before interpreting the result. Never send raw `--json` output through a model-facing terminal or tool. When a program needs the exhaustive machine payload, use `--json --json-output <path>` and inspect that file programmatically instead of injecting its complete contents into model context.
+
+`inspect --view behavior` returns connected behavior for named units; `code` returns exact source. Treat source rendered by either command as already read. Batch independent roots and source gaps when practical. Use native tools only for edits, checks, binary content, or a specific unsupported gap reported by scip-query. After edits, use `diff-impact` when downstream consumers matter, `architecture` for declared boundaries, and `health` for configured quality or cleanup detectors.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "SCIP Query Router"
-  short_description: "Route a codebase task to the right SCIP skill"
-  default_prompt: "Use $scip-query first to pick the right SCIP-backed skill for this task before doing anything else."
+  display_name: "SCIP Query"
+  short_description: "Explore code through exact identities and relationships"
+  default_prompt: "Use $scip-query as the primary repository exploration surface. Treat commands as controls rather than a checklist, reuse locator results as graph roots, distinguish competing implementations by their entry surfaces and callers, and use exact identities, relationships, behavior, source, coverage, and recovery to understand the requested system accurately."