scip-query 0.20.0 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,8 @@
     "scripts/scip-windows-provenance.mjs",
     "scripts/verify-scip-windows.mjs",
     "skills/**/*.md",
-    "skills/**/agents/*.yaml"
+    "skills/**/agents/*.yaml",
+    "skills/**/scripts/*.mjs"
   ],
   "sideEffects": false,
   "exports": {
@@ -40,6 +41,10 @@
       "import": "./dist/queries/architecture.js",
       "types": "./dist/queries/architecture.d.ts"
     },
+    "./queries/anchors": {
+      "import": "./dist/queries/anchors.js",
+      "types": "./dist/queries/anchors.d.ts"
+    },
     "./queries/bottlenecks": {
       "import": "./dist/queries/bottlenecks.js",
       "types": "./dist/queries/bottlenecks.d.ts"
@@ -92,6 +97,14 @@
       "import": "./dist/queries/dataflow.js",
       "types": "./dist/queries/dataflow.d.ts"
     },
+    "./queries/dependence-slice": {
+      "import": "./dist/queries/dependence-slice.js",
+      "types": "./dist/queries/dependence-slice.d.ts"
+    },
+    "./queries/dependency-depth": {
+      "import": "./dist/queries/dependency-depth.js",
+      "types": "./dist/queries/dependency-depth.d.ts"
+    },
     "./queries/dead": {
       "import": "./dist/queries/dead.js",
       "types": "./dist/queries/dead.d.ts"
@@ -104,14 +117,18 @@
       "import": "./dist/queries/deep-chains.js",
       "types": "./dist/queries/deep-chains.d.ts"
     },
+    "./queries/entry-map": {
+      "import": "./dist/queries/entry-map.js",
+      "types": "./dist/queries/entry-map.d.ts"
+    },
+    "./queries/system-map": {
+      "import": "./dist/queries/system-map.js",
+      "types": "./dist/queries/system-map.d.ts"
+    },
     "./queries/deps": {
       "import": "./dist/queries/deps.js",
       "types": "./dist/queries/deps.d.ts"
     },
-    "./queries/diff-gate": {
-      "import": "./dist/queries/diff-gate.js",
-      "types": "./dist/queries/diff-gate.d.ts"
-    },
     "./queries/diff-impact": {
       "import": "./dist/queries/diff-impact.js",
       "types": "./dist/queries/diff-impact.d.ts"
@@ -128,6 +145,10 @@
       "import": "./dist/queries/drift.js",
       "types": "./dist/queries/drift.d.ts"
     },
+    "./queries/evidence": {
+      "import": "./dist/queries/evidence.js",
+      "types": "./dist/queries/evidence.d.ts"
+    },
     "./queries/extract-candidates": {
       "import": "./dist/queries/extract-candidates.js",
       "types": "./dist/queries/extract-candidates.d.ts"
@@ -196,6 +217,10 @@
       "import": "./dist/queries/plan-context.js",
       "types": "./dist/queries/plan-context.d.ts"
     },
+    "./queries/context": {
+      "import": "./dist/queries/context.js",
+      "types": "./dist/queries/context.d.ts"
+    },
     "./queries/recent-duplicates": {
       "import": "./dist/queries/recent-duplicates.js",
       "types": "./dist/queries/recent-duplicates.d.ts"
@@ -204,6 +229,14 @@
       "import": "./dist/queries/redundant-reexports.js",
       "types": "./dist/queries/redundant-reexports.d.ts"
     },
+    "./queries/reference-neighborhood": {
+      "import": "./dist/queries/reference-neighborhood.js",
+      "types": "./dist/queries/reference-neighborhood.d.ts"
+    },
+    "./queries/reference-reachability": {
+      "import": "./dist/queries/reference-reachability.js",
+      "types": "./dist/queries/reference-reachability.d.ts"
+    },
     "./queries/refs": {
       "import": "./dist/queries/refs.js",
       "types": "./dist/queries/refs.d.ts"
@@ -256,6 +289,14 @@
       "import": "./dist/queries/slice.js",
       "types": "./dist/queries/slice.d.ts"
     },
+    "./queries/source-inspection": {
+      "import": "./dist/queries/source-inspection.js",
+      "types": "./dist/queries/source-inspection.d.ts"
+    },
+    "./queries/source-search": {
+      "import": "./dist/queries/source-search.js",
+      "types": "./dist/queries/source-search.d.ts"
+    },
     "./queries/stale-abstractions": {
       "import": "./dist/queries/stale-abstractions.js",
       "types": "./dist/queries/stale-abstractions.d.ts"
@@ -296,6 +337,10 @@
       "import": "./dist/queries/unused-params.js",
       "types": "./dist/queries/unused-params.d.ts"
     },
+    "./queries/value-flow": {
+      "import": "./dist/queries/value-flow.js",
+      "types": "./dist/queries/value-flow.d.ts"
+    },
     "./queries/unused-imports": {
       "import": "./dist/queries/unused-imports.js",
       "types": "./dist/queries/unused-imports.d.ts"
@@ -314,23 +359,35 @@
     }
   },
   "scripts": {
-    "build": "node --max-old-space-size=8192 ./node_modules/tsup/dist/cli-default.js",
+    "build": "node --max-old-space-size=16384 ./node_modules/tsup/dist/cli-default.js",
     "dev": "tsup --watch",
-    "format": "prettier --write \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"*.{ts,js,json}\"",
-    "format:check": "prettier --check \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"*.{ts,js,json}\"",
-    "test": "vitest run",
+    "format": "prettier --write \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"skills/**/scripts/*.{js,mjs}\" \"*.{ts,js,json}\"",
+    "format:check": "prettier --check \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"skills/**/scripts/*.{js,mjs}\" \"*.{ts,js,json}\"",
+    "test": "vitest run --maxWorkers=2",
+    "soak:cache-lifecycle": "npm run build && vite-node scripts/cache-lifecycle-soak.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit && tsc -p tests/fixtures/invocation-coverage-contract/tsconfig.json && tsc -p tests/fixtures/protocol-state-contract/tsconfig.json",
     "audit:prod": "node scripts/audit-production-dependencies.mjs",
     "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/build-scip-windows.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-scip-windows.mjs scripts/verify-scip-windows-registry.ts && 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/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",
     "verify:scip-windows-registry": "vite-node scripts/verify-scip-windows-registry.ts",
     "bench:evidence-products": "node scripts/evidence-product-contract.mjs",
+    "bench:exploration": "node scripts/exploration-benchmark.mjs",
+    "bench:exploration:codex": "node scripts/codex-exploration-trial.mjs",
+    "bench:exploration:compare": "node scripts/compare-exploration-trials.mjs",
+    "bench:cold-reindex": "vite-node scripts/benchmark-cold-reindex.ts",
+    "bench:edit-latency": "vite-node scripts/benchmark-edit-latency.ts",
+    "bench:graph-literal": "vite-node scripts/benchmark-graph-literal.ts",
+    "bench:query-service": "npm run build && vite-node scripts/benchmark-query-service.ts",
+    "bench:reindex-accounting": "vite-node scripts/benchmark-reindex-accounting.ts",
+    "bench:source-search": "vite-node scripts/benchmark-source-search.ts",
     "bench:native-symbol-leaf": "node scripts/bench-native-symbol-leaf.mjs",
+    "bench:agent-output": "npm run build -- --silent && vite-node scripts/benchmark-agent-output.ts",
     "calibrate": "node scripts/accuracy-calibration.mjs",
     "docs:commands": "vite-node scripts/render-command-reference.ts --write",
     "prepublishOnly": "vite-node scripts/release-npm-guard.ts",
@@ -363,6 +420,7 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
     "@c4312/scip": "^0.1.0",
+    "@ts-morph/common": "^0.29.0",
     "@vue/compiler-dom": "^3.5.40",
     "@vue/compiler-sfc": "^3.5.40",
     "better-sqlite3": "^13.0.2",

package/skills/concrete-plan/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: concrete-plan
+description: Compatibility alias for the canonical scip-plan skill. Use only when an existing prompt explicitly requests concrete-plan.
+---
+
+# Concrete Plan compatibility alias
+
+This name remains for a transition period so existing agent prompts do not fail. Apply `$scip-plan`; it contains the canonical command/question manual and code-grounded planning format. Do not combine the two skills.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Concrete Plan (compatibility)'
+  short_description: 'Forward old planning prompts to SCIP Plan'
+  default_prompt: 'Use $scip-plan for this repository plan. $concrete-plan is only a compatibility alias.'

package/skills/scip-explore/SKILL.md

@@ -1,90 +1,78 @@
 ---
 name: scip-explore
-description: Use to understand a system before editing it: what calls what, how data flows, what depends on it, what a change would reach, and what historically changed together. Includes choosing high-signal commands for an unfamiliar language and rendering the result as a flow, dependency, or blast-radius diagram. For understanding a failure mode class rather than this codebase, use `engineering-lenses`.
-commands:
-  - template: "scip-query system <module-or-scope>"
-    when: "Orient to a module's files, symbols, dependencies, and consumers."
-  - template: "scip-query trace <entry-symbol>"
-    when: "Connect an entry symbol to its definition and references."
-  - template: "scip-query affected <symbol>"
-    when: "Measure the transitive downstream blast radius of a change."
+description: Understand a repository system end to end before explaining, planning, changing, or reviewing it. Use when the task depends on how behavior enters the system, branches, transforms data, crosses runtimes, changes state, reaches consumers, or recovers from failure across multiple symbols or files. Apply scip-query as the evidence instrument; this skill owns the system model, evidence ledger, synthesis, and stopping test. Skip it for a single exact source lookup whose answer is already local.
 ---
 
-## Purpose
+# SCIP Explore
 
-Build verified understanding of how a system works end to end — entry points, call flow, data flow, dependencies, consumers, and risk — before answering or editing. Exploration means tracing code from entry points to effects against the SCIP index, not against memory or folder guesses. Load shared mechanics from `../_shared/SKILL.md`; use this skill's own shortlist first and open `_shared` only when it is insufficient.
+A repository system is the set of cooperating code, runtime mechanisms, and state resources whose coordinated behavior turns an initiating input into observable consequences. To understand one end to end is to reconstruct that behavior from its initiating boundary through every material decision, transformation, handoff, state change, result, and recovery path within the user's scope.
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
+`$scip-query` is the sensing skill: it locates exact referents, projects typed relationships, reads implementation, and reports evidence strength and coverage. Load it before querying. This skill is the investigation skill: it decides which facts the answer must establish, integrates the observations, and decides when the system is understood well enough to answer. Do not duplicate the command manual here or treat either skill as a fixed command sequence.
 
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query system <module-or-scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Orient to a module's files, symbols, dependencies, and consumers. |
-| `scip-query trace <entry-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Connect an entry symbol to its definition and references. |
-| `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Measure the transitive downstream blast radius of a change. |
+## Build the proof target
 
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
+Before querying, restate the user's question as a checkable capability or decision. Then create a small private evidence ledger. An evidence ledger is a working record whose rows bind each material claim to the evidence needed to settle it. A material claim is a repository fact whose truth could change the requested explanation, decision, plan, or edit.
 
-## Evidence rules (apply to every step below)
+Start with three to seven rows, normally one for each distinct clause in the user's question. A row must be atomic enough that one status applies to every part of it. Split a row when different predicates, outcomes, fields, bounds, or failure paths require different evidence. Do not add rows merely because an unrelated implementation exposes more behavior.
 
-- Use a current index before trusting graph facts: apply `_shared`'s freshness gate once before the first graph claim. After source changes, let an active watcher refresh and use manual reindex only as the documented fallback.
-- Relationship, consumer, and completeness claims must cite a `scip-query` command. Literal local-source claims may cite a native file read instead.
-- Resolve ambiguous symbols before describing behavior — `scip-query code` is the usual tool, but it isn't mandatory when you already have an exact native range.
-- Follow the graph before trusting folder structure. Start wide, then narrow.
-- Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — must state one rival explanation and the trace evidence that ruled it out.
+Give each row one status:
 
-Each `scip-query` command below carries a coverage rating: **complete** (exhaustive) or **bounded** (capped — a follow-up command may be needed to fill in the picture).
+- `unresolved`: no sufficient evidence yet;
+- `established`: exact or adequately calibrated evidence supports the claim within stated coverage;
+- `unsupported`: a named provider or source limitation prevents the claim;
+- `excluded`: the claim cannot change the requested answer, with the reason recorded.
 
-## The core workflow
+Derive rows from the question, not from a generic checklist. For an end-to-end behavior, test whether the answer depends on these five parts of the causal spine:
 
-Run these five steps in order. Skip a step only when its evidence is already in hand from an earlier step.
+1. origin and ownership — what initiates the behavior, which entry surface receives it, and which long-lived or per-invocation owner controls it;
+2. decisions and transformations — which predicates, authorization checks, precedence rules, bounds, defaults, sibling outcomes, extension hooks, and data reshaping alter what happens;
+3. crossings and effects — which runtime mechanisms carry the work, which state or external resources are observed or changed, and in what order;
+4. observation — which return value, emitted event, notification, durable record, or downstream consumer makes the result visible;
+5. failure and recovery — which retry, rejection, rollback, cleanup, interruption rule, later repair, or post-loop maintenance follows an incomplete or completed path.
 
-**1. Orient.** Run `stats` (repo-wide size/shape, complete), `kind-counts`, `system <module-or-scope>` (file paths, exported symbols with line ranges, internal/reverse deps, complete), `outline <entry-file>`, and `by-kind function --scope <scope>`.
-Done when: module files, key symbols, dependencies, and reverse dependencies are mapped.
+These are possible fact classes, not assumptions that every system contains all five. Mark an absent class `excluded` only when evidence shows it cannot alter the answer. For comparisons, keep separate rows for both paths and for each discriminator between them.
 
-**2. Trace entry points.** Run `trace <entry-symbol>` (definition + every reference, bounded), `call-graph <entry-symbol>` (incoming callers, outgoing callees, bounded), `code <entry-symbol>`, `dataflow <entry-symbol>` — repeat for important callees until the path reaches a side effect, a returned value, or a terminal output.
-Done when: the traced path connects entry point to observable effect.
+Read [references/information-model.md](references/information-model.md) only when the user asks for the capability inventory, a ledger row needs a specialized analysis beyond the ordinary relationship families, or provider support is uncertain. It maps the complete kinds of information scip-query can expose to the system claims they can and cannot establish. Do not load it for routine end-to-end exploration.
 
-**3. Map dependencies and consumers.** Run `deps <file>`, `rdeps <file>`, `fan-out <file>`, `surface <module>`, `affected <symbol>` (transitive closure of symbols that could break if this symbol changes: identities, files, traversal depths, bounded).
-Done when: direct dependencies, public surface, and downstream blast radius are named.
+When collaboration tools are available and authorized, and the main agent will continue from the investigation into planning, editing, or review, prefer a fresh delegated explorer for a multi-symbol causal spine. Read [references/delegated-exploration.md](references/delegated-exploration.md) before the main context performs repository exploration. The explorer owns read-only acquisition; the main agent receives only a claim-complete ledger, retains all mutation and user-facing authority, and revalidates affected claims after edits. Do not delegate a single exact lookup whose result is already local.
 
-**4. Follow data and state.** Run `dataflow <symbol-or-variable>` (definition sites, usage sites, producers, consumers, bounded), `slice <symbol-or-variable>`, `slice <symbol-or-variable> --forward`.
-Done when: producers, transformations, storage, and consumers are identified — or explicitly marked unavailable.
+When `SCIP_EXPLORE_EVIDENCE_DIR` and `SCIP_EXPLORE_LEDGER` are set, read [references/external-evidence.md](references/external-evidence.md) before querying. That runner has requested external evidence mode: complete packets stay outside model context, bounded receipts support the investigation, and a claim-complete ledger becomes the only input to a fresh synthesis phase.
 
-**5. Assess risk.** Run `complexity <symbol>`, `complexity-hotspots`, `bottlenecks`, `change-surface <file>` (pre-change briefing: exports, consumers, blast-radius risk), `cycles`, `deep-chains --min-depth 5` (longest condensed dependency-component chains — flags fragile long call paths).
-Done when: the explanation names the risky symbols, or states that no relevant risks appeared.
+## Establish the causal spine
 
-## Route by question type
+Start from the most discriminating exact referent already present in the request. Locate one only when needed. Reuse returned symbols and `file:line` identities as graph roots; do not rediscover the same unit through synonyms.
 
-| Question | Commands |
-|---|---|
-| Function behavior | `code`, `hierarchy`, `call-graph`, `dataflow`, `complexity` |
-| User-action flow | `files` or `outline` to find the handler, then `code` and `call-graph` down the path |
-| Safe to change? | `change-surface`, `affected`, `similar` |
-| Module architecture | `system`, `surface`, `deep-chains`, `bottlenecks`, `cycles`, `hotspots` (`hotspots` lists the most-referenced symbols — choke points where any change ripples widely) |
-| Relationship between two units | `coupling`, `similar --plan`, `similar-chains` |
+Treat all exact text already visible in a locator, inspect slice, or code receipt as located. Do not search for a function, call expression, constant, or message that is already present in delivered source. Do not run `outline` after exact source has already exposed the relevant unit boundaries. If a root has produced two failed or non-settling locator/outline attempts, use the best exact `file:line` already known with one bounded `inspect` and reassess the claim; do not alternate among more locators. A claim is not unsupported or excludable while a delivered exact identity or recovery command can settle a material clause.
 
-## Other owned commands
+When a locator returns competing implementations, make authoritative scope the first ledger row. Before reading either implementation body, compare only the evidence that can identify which path answers the question: external entry surfaces, incoming execution, ownership, consumers, or runtime handoffs. A core type, newer package, first search result, or public export is not ingress. Treat one path as authoritative only when exact evidence connects it to the scope named by the question. If one bounded comparison plus its exact relevant recovery cannot do that, preserve every plausibly live implementation as a separate scope; an ambiguous general question requires each live scope to be explained to the requested depth or explicitly left unresolved. Do not silently choose one, and do not exclude another without evidence that it cannot answer the question.
 
-These four don't have a dedicated workflow step above but come up constantly once you're inside a module — use them as needed, not in sequence:
+For a lifecycle, distinguish scheduling from execution and completion from later maintenance. If work is queued, establish both the event that creates the pending work and the later owner that observes and processes it, including their ordering. If plugins or other extension points can inject, replace, or transform material input, treat those operations as behavior rather than incidental calls. Include later filtering, reconstruction, pruning, or cleanup when it changes what a future consumer observes.
 
-- **`imported-by <symbol>`** — which files import this symbol. Run before changing or removing a shared export, to know exactly which files to check. If the list is empty, confirm with `dead` before deleting rather than trusting the empty result alone.
-- **`unused-imports <file>`** — imports not referenced in that same file. Run on a file you're about to touch, or one a de-bloat pass flagged; remove only entries you've confirmed are safe.
-- **`similar-signatures`** — functions with near-identical type signatures. Run when hunting duplicate-shaped functions to consolidate. This is a *good-with-review* signal — check each match with `code` before merging, don't act on the list alone.
-- **`co-change [file]`** — files that change together in git history with no dependency edge between them: hidden coupling. Run when `change-surface` or `affected` reports a small blast radius but you suspect the graph is missing something. This is also *good-with-review* — a paired file is a prompt to check manually, not proof the current change must touch it too. (`diff-gate`'s `co-change-partner` check is the automated version of this same signal.)
+Select relationships because they can settle named ledger rows. Include the initiating owner as a root or request incoming execution when an end-to-end account needs ingress. Batch independent roots and related families when their evidence belongs to the same open question. When the interface supports concurrent tool calls, issue independent observations in one wave while preserving one complete result and cursor chain per command. Never combine results through a shortening pipe or abandon a printed `Continue exactly:` cursor; transport completion is required before coverage can be evaluated. Do not request every family to see what appears. Use graph evidence for relationships between units and behavior/source evidence for predicates inside a selected unit; neither substitutes for the other.
 
-## Report the exploration
+After each packet:
 
-Cover: overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citation that proves each claim. For every conclusion-bearing claim, name the rival explanation you considered and the evidence that ruled it out. Exploration is complete only when the reader can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.
+- record its normalized request and every delivered exact source interval; before another query, reject an exact duplicate and subtract already covered ranges locally;
+- update only the ledger rows that its evidence actually establishes;
+- preserve evidence strength, coverage, exact bounds, defaults, branch predicates, separately handled fields, ownership scope, state identity, ordering, and cleanup effects;
+- mark a row `established` only when the selected behavior supports every clause in that row; an accurate high-level sentence does not settle omitted guards, markers, fields, stop conditions, or sibling outcomes;
+- treat the exact formula of any configurable threshold, budget, or bound that changes selection as material; treat a durable reduction marker as unresolved until its later consumer and exact model-facing substitution are established or the provider reports that frontier unsupported;
+- name the remaining gap before another query;
+- follow a printed fold, recovery command, or adjacent identity only when it can close that gap;
+- use `inspect --view behavior` for a named behavioral gap and `code` only when exact syntax can change the conclusion.
 
-## Deeper references
+If two consecutive packets neither establish a row nor split one using a newly discovered behavior-changing fact, stop expanding that root and reassess the selected authority, relationship family, or ledger. Do not compensate for a weak root with more source.
 
-| Need | Reference |
-|---|---|
-| Entering an unfamiliar language (TypeScript, Python, Java, Scala, Kotlin, Rust, Go, C, C++, Ruby, C#, Visual Basic, Dart, PHP, Clojure/ClojureScript, Vue) and picking the highest-signal commands, including de-bloat sets | `references/language-playbook.md` |
-| Turning exploration evidence into an HTML flow, dependency, data-flow, or blast-radius diagram | `references/diagrams.md` |
+At an input boundary, keep decoding or parsing separate from validation even when source nests them in one expression. Establish both failure paths before assigning a response: a validator that returns a failure result does not catch an exception or rejected promise raised while its argument is being produced. Preserve which enclosing handler catches that earlier failure.
 
-## Constraint
+Calls and exact runtime handoffs establish executable reachability within their stated coverage. Dataflow, state, temporal, contract, identity, ownership, reference, and dependency evidence establish only the relationship they name. A candidate is a lead requiring confirmation. A bounded or unsupported result cannot establish absence. If scip-query reports a specific unsupported frontier, use a native read only for that frontier and record why the exception was necessary.
 
-scip-explore's OpenAI-agent interface binds to display name "SCIP Explore" with default prompt "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."
+## Synthesize the system
+
+Condense observations into one causal account: when the initiating condition holds, the identified owner evaluates the material decisions, transforms or transfers the identified data, changes the identified state in the established order, and exposes the established result; on the relevant failure path, the established recovery behavior follows.
+
+This causal account is not a chronology of files read. Organize it by what makes the behavior occur. Keep structurally different operations separate: a returned default is not a thrown rejection; a cache invalidation is not a generic state update; an enqueue is not successful consumption; local source order is not cross-process completion.
+
+Before answering or editing, audit the draft against the ledger and every selected statement-complete behavior packet. Repair answer-side omissions from evidence already delivered instead of querying again. Preserve every material predicate, hard bound, default, separately merged field, durable effect, externally visible ordering, and cleanup action. If an unsupported row limits the conclusion, state that limit in the answer.
+
+Stop when every material row is `established`, `unsupported`, or `excluded`, no contradiction remains among the rows, and no exact in-scope recovery command could change the answer. Packet completion, a plausible narrative, elapsed time, query count, and token cost are not stopping conditions.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "SCIP Explore"
-  short_description: "Understand a system with SCIP evidence"
-  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence before editing it."
+  display_name: 'SCIP Explore'
+  short_description: 'Understand repository systems end to end'
+  default_prompt: 'Use $scip-explore to understand this repository system end to end before explaining or changing it.'

package/skills/scip-explore/references/delegated-exploration.md

@@ -0,0 +1,51 @@
+# Delegated live exploration
+
+A delegated explorer is a read-only subagent that turns one fixed repository question into a claim-complete evidence ledger for a separate coding agent. Its defining boundary is that it may observe and record the system but cannot change the repository, choose the implementation, grade its own work, or answer the user. The separation keeps acquisition transcripts outside the main coding context while leaving decisions and effects with the agent responsible for them.
+
+Use this mode only when the active environment permits subagents and the investigation spans enough owners, branches, crossings, or effects that direct exploration would materially enlarge the main context. The main agent remains responsible for the user's objective, permissions, edits, checks, commits, and final answer.
+
+## Create the checkpoint
+
+Before spawning, the main agent:
+
+1. states the exact question and initial material claims without exploring their answers;
+2. creates one private temporary root outside the repository, containing an evidence directory and ledger path;
+3. records the current repository root, commit, dirty paths, and intended scope;
+4. refrains from tracked-source edits until acquisition returns.
+
+Start one fresh explorer with no inherited conversation turns. When the collaboration surface supports explicit profiles, request `gpt-5.6-terra` with `xhigh` reasoning for a terminal ledger unless the user selected another profile or broader fixed evaluation has established a better one. Do not silently substitute a different model or reasoning level.
+
+Treat `gpt-5.6-sol` with `low` reasoning as an experimental balanced profile, not yet the default. On one frozen OpenCode external-ledger run it recovered 6/7 strict compound facts in 338 seconds for about 43.10 Codex credits, versus Terra-xhigh's 5/7 in 630 seconds for 33.20 credits. It has not been repeated across seeds or task shapes. Use it when the user accepts the measured credit premium for faster turnaround and stronger observed clause retention; disclose that the evidence is one run.
+
+Use `gpt-5.6-sol` with `medium` reasoning as an accuracy escalation when a decision-critical compound claim remains unresolved after Terra, or when the user explicitly prioritizes accuracy over credits. On one frozen OpenCode external-ledger run it recovered 7/7 strict compound facts versus Terra-xhigh's 5/7, but cost about 2.5 times as many Codex credits, used 60 semantic queries instead of 23, and has not been repeated across task shapes or seeds. Give Sol the unresolved claim ids and accepted ledger for an audit or targeted delta; do not repeat a complete acquisition unless the earlier ledger is unusable.
+
+Treat `gpt-5.6-luna` with `max` reasoning as an experimental economy pre-pass, not as a terminal-ledger replacement. Use it only when the user explicitly prioritizes cost or the result is a preliminary map. Before relying on its ledger for an implementation or compound system claim, give the question and ledger—not its receipts or transcript—to a fresh Terra-xhigh auditor; turn every missing or weakened material clause into a targeted Terra delta. Do not claim that this hybrid saves cost until its complete acquisition, audit, and delta path has been measured.
+
+Give the explorer only the question, material-claim seed, repository and temporary paths, observed baseline, and these instructions. Require it to load `$scip-explore` and `$scip-query`, read [external-evidence.md](external-evidence.md), and run each scip-query observation through the capture wrapper with the assigned evidence directory. The explorer may prepare or refresh scip-query's private index when required; it may not edit, stage, commit, run tests, mutate external systems, inspect an evaluation rubric, or broaden the user's scope.
+
+The explorer writes either a complete base ledger or a blocked ledger. Its visible response is exactly `LEDGER_READY <absolute-ledger-path>` or `LEDGER_BLOCKED <absolute-ledger-path>`; it does not paste the ledger, receipts, raw packets, or a user-facing explanation into the subagent response.
+
+## Accept the handoff
+
+The main agent reads only the ledger. Accept `LEDGER_READY` only when:
+
+- the path is the assigned path and the file is nonempty and bounded;
+- the header names the exact task, scope, baseline, receipts, and observation identities;
+- the scope manifest accounts for every plausibly live production scope from complete locator evidence; a named but unexplored live scope rejects the handoff unless exact routing evidence excludes it;
+- the ledger state is `complete` and no material row remains `unresolved`;
+- every established row has exact citations, evidence strength, and coverage;
+- receipts combined within a claim describe compatible, adequately stable observations.
+
+If the explorer returns `LEDGER_BLOCKED`, the signal is malformed, the snapshot changed, or a required identity is unknown, do not silently explore in the main context or downgrade the explorer. Retry a fresh explorer only when a named recoverable gap can be corrected; otherwise tell the user which evidence boundary prevented the handoff.
+
+A Sol-low base ledger that fails the scope-manifest or clause-transfer check is not accepted because it is cheaper. Give only the missing scope or claim ids to the configured accuracy escalation as a targeted delta; do not repeat already accepted acquisition.
+
+After acceptance, the main agent synthesizes the system and may read only the exact implementation surfaces needed to edit. It never reads raw packets merely to gain confidence. Keep the temporary evidence until the task's verification is complete, then remove only the exact temporary root created for this handoff.
+
+## Revalidate after edits
+
+An edit changes the repository snapshot and therefore ends the original ledger's authority over current state. Run `scip-query diff-impact` after a nontrivial change and identify which relied-on claim ids intersect changed or affected symbols and files.
+
+A ledger delta is a new read-only handoff that binds an earlier ledger to a later repository snapshot while replacing only claims whose truth or evidence may have changed. Spawn a fresh explorer with the original question, base-ledger checksum, affected claim ids, diff-impact result, and new temporary paths. The delta explorer first ensures scip-query's index reflects the changed tracked sources; an unchanged index-generation identity after an indexed source change cannot authorize the new snapshot. The delta must name the new observation identities, invalidated or superseded ids, replacement terminal rows, and any unchanged rows whose continued applicability it establishes. Do not make the main agent carry the earlier exploration transcript into this pass.
+
+The main agent may retain an old claim only when the delta establishes that the change cannot affect it. A moved commit, changed content or index identity, invalidated stability proof, incompatible receipt, or unknown relationship blocks reuse rather than producing a warning.

package/skills/scip-explore/references/external-evidence.md

@@ -0,0 +1,72 @@
+# External evidence mode
+
+External evidence mode separates complete repository observations from the smaller claim evidence kept in the model's active context. A raw evidence packet is the exhaustive JSON result written by scip-query. An evidence receipt is the bounded, model-facing projection of that same result together with its coverage, observation identity, file path, byte count, and checksum.
+
+Use this mode only when `SCIP_EXPLORE_EVIDENCE_DIR` and `SCIP_EXPLORE_LEDGER` are set. The surrounding runner owns those paths and the later context checkpoint; their presence in the task is sufficient, so do not query `env` to reconfirm them. One evidence directory belongs to one read-only acquisition snapshot. Do not reuse it after a tracked-source edit or known index-generation change; start a new directory and ledger or delta. Receipt reuse is limited to the latest compatible observation identity already present in the directory, but the read-only snapshot boundary is what prevents the first request after an unseen external change from reusing stale evidence.
+
+The supported checkpoint uses two model contexts. The acquisition context receives bounded receipts and writes the ledger; a fresh synthesis context receives only the question and that ledger. Writing evidence to Markdown inside one continuing context does not remove earlier tool results or receipts from that context. A one-context runner may still use capture to reduce each tool result, but it must not describe that as context eviction or expect the ledger to lower already accumulated input.
+
+## Capture evidence
+
+Run every scip-query exploration command through the installed capture script:
+
+```bash
+node <loaded-scip-explore-skill-directory>/scripts/capture-evidence.mjs --id <unique-id> -- <command> <arguments...>
+```
+
+Replace the directory placeholder with the absolute directory containing the `scip-explore` `SKILL.md` you actually loaded. Do not guess that the skill is repository-local; Codex, Claude, and shared-agent installations may expose different absolute roots.
+
+Use a distinctive literal already present in the task or a prior receipt, not a broad topic word:
+
+```bash
+node <loaded-scip-explore-skill-directory>/scripts/capture-evidence.mjs --id locate-root -- search '<exact identifier or message>'
+```
+
+Arguments after `--` are ordinary scip-query arguments without the `scip-query` executable. Do not add `--json`, `--agent-output`, `--json-output`, or pagination flags; the script owns transport. It writes the complete JSON envelope under `SCIP_EXPLORE_EVIDENCE_DIR` before it returns a receipt. It never pipes the result through `head`, `tail`, `jq`, or another shortening stage. A search receipt groups every identity present in the exhaustive packet into a complete file-owner-line manifest and keeps only the freshness states needed to calibrate those identities; verbose per-file proofs and binary-path inventories remain in the checksum-addressed raw packet. A command-rendering identity budget may report omissions even when the exhaustive packet contains the known total; the receipt promotes coverage only when raw identity count, known total, and matching-line count agree exactly. Otherwise an incomplete identity manifest, an overlarge model projection, or any other inability to represent the requested observation safely produces a refusal and keeps the complete raw packet for audit. Narrow or follow the stated recovery under a new evidence id; never treat the refusal as evidence.
+
+The file export is the pagination-safe transport for external evidence mode: the command completes its exhaustive machine payload outside the model-facing terminal, then the wrapper reads that complete file. Outside this wrapper, every printed `Continue exactly:` command remains mandatory. Run each cursor unchanged until none remains before interpreting that command. Do not substitute a fresh query, alter cursor flags, or infer completeness from one page.
+
+The wrapper compares each request with successful receipts in the same evidence directory. An exact duplicate returns `already-captured` with the receipt ids to cite and does not run scip-query again. A `code file:start-end` range already covered by either a code receipt or an exact inspect slice does the same. A partially covered range returns `overlap-requires-uncovered-query` and the exact uncovered selectors; capture only those selectors under a new id. These responses reuse already delivered bytes without deleting or approximating evidence. Prevent the response in the first place: after every receipt, record its normalized request and delivered source intervals in the private ledger; before every capture, check exact-request reuse and subtract covered intervals. Do not ask the wrapper to rediscover that a request is redundant.
+
+Batch independent facts as one acquisition wave when the tool interface supports concurrent calls, but keep one complete raw packet and one receipt per command. Give each command its own id. Batching means issuing independent lossless transports together; it never means concatenating their terminal output, sharing a cursor, or clipping any result to fit a combined budget.
+
+Do not read a raw packet merely because it exists. The receipt is the delivered evidence. A raw packet is for deterministic audit or a specifically named field that the receipt reports as omitted; audit only a count, identity, digest, or other non-source fact programmatically. Never print raw source, result arrays, or a raw field through `jq`, Python, `head`, `tail`, or another native command. If omitted source can change a ledger row, issue the receipt's bounded recovery query. A receipt may refer to an earlier receipt for an identical observation checkpoint while preserving its own observation time and identity hash; resolve that reference when checking snapshot compatibility instead of requesting the checkpoint again.
+
+An `inspect --view behavior` receipt keeps every exact source slice once, plus compact unit, binding, coverage, visible-frontier, and recovery metadata. Duplicate behavior-line encodings and withheld frontier lead objects stay in the raw packet; their counts and exact `remainingInspectCommands` stay visible. Read the delivered slices as source evidence and follow a remaining command only when a named claim depends on its withheld frontier. Do not request the same source again with `code`.
+
+`code` has no smaller safe projection: its exact source is the evidence. Prefer `inspect --view behavior` for predicates and use `code` only for a named, narrow range whose syntax can change a ledger row and is not already covered by an inspect slice or code receipt. A rejected overlarge projection is a signal to narrow the source question, not to print the raw packet.
+
+## Write the checkpoint ledger
+
+Keep the ordinary private evidence ledger while exploring. At the end of the evidence phase, write one self-contained Markdown ledger to the exact `SCIP_EXPLORE_LEDGER` path. This is the only repository understanding carried into the fresh synthesis phase, so preserve claim-sized evidence rather than a narrative summary.
+
+Begin the ledger with:
+
+- schema `scip-explore-ledger/v1`;
+- handoff kind `base` or `delta`;
+- the exact task and scope;
+- a scope manifest listing every plausibly live production scope exposed by complete locator identities, with status `established`, `unsupported`, or `excluded` and exact authority evidence for any exclusion;
+- state `complete` or `blocked`;
+- every receipt id and raw-evidence checksum used;
+- the observation identities and stability proofs reported by those receipts;
+- for a delta, the base-ledger checksum plus every invalidated or superseded claim id.
+
+`complete` means every material row is `established`, `unsupported`, or `excluded` and all receipts used for one claim are compatible with the declared snapshot. Use `blocked` when acquisition cannot produce a trustworthy terminal ledger. Do not silently omit an oversized projection, incompatible observation identity, changed snapshot, or unresolved material clause.
+
+For an unqualified product question, a production scope cannot be excluded merely because another scope has a direct caller or a more complete causal spine. Either explain every plausibly live scope to the requested depth, establish exact product routing that makes one irrelevant, or return `blocked` so a targeted delta can settle it. Naming an unexplored live scope in a limitation does not make a ledger complete.
+
+Do not classify a reachable selection formula, bound, or downstream representation consumer as non-material when it changes the user's requested behavior. In particular, a named budget helper requires its exact arithmetic, and a persisted reduction marker requires the later consumer's exact model-facing result. A delivered identity or recovery command capable of establishing either keeps the row unresolved until it is read.
+
+For every material row include:
+
+- an atomic claim identifier and status;
+- the complete established claim, including every material guard, default, bound, field operation, ordering rule, sibling outcome, cleanup, and failure behavior;
+- a `Must transfer` list with one bullet for every independently material clause that fresh synthesis must state; preserve distinct operations such as inject, replace, and transform as distinct bullets;
+- for an input boundary, separate decoding or parsing failure from validation failure and cite the handler for each; a validator does not catch a failure raised while its argument is being produced;
+- exact `file:line` or compiler-symbol citations present in delivered receipts;
+- evidence strength and coverage limitations;
+- unresolved, unsupported, or excluded clauses stated separately.
+
+For deferred work, state the creation event, the later processing event, and whether processing occurs before ordinary work. For filtering, summarization, or pruning, distinguish durable storage from the model-facing view and state explicitly whether original history or output is deleted.
+
+Do not cite the temporary raw-packet path as repository evidence. Do not answer the user's question in the evidence phase. After writing the ledger, return only the control signal required by the runner so it can decide whether a fresh synthesis context is permitted. Benchmark runners use exactly `LEDGER_READY` for a complete ledger or `LEDGER_BLOCKED` for a blocked ledger; delegated live exploration uses the path-bearing form in [delegated-exploration.md](delegated-exploration.md). Never append an explanation to either signal.

package/skills/scip-explore/references/information-model.md

@@ -0,0 +1,51 @@
+# scip-query information model
+
+Use this map to decide what kind of repository fact a ledger row requires. It inventories information classes rather than prescribing a route. `scip-query --help-all` remains the complete runtime command inventory, and `scip-query capabilities --matrix` remains the authority on which providers and evidence ceilings are available in the current project.
+
+## Direct system evidence
+
+| Information kind | What its real referents are | Primary controls | What it can establish | What it cannot establish alone |
+|---|---|---|---|---|
+| Current text | Exact tracked bytes, occurrences, paths, and aligned compiler owners | `search`, `files` | Cardinality and location within reported text coverage | Task relevance or executable reachability |
+| Source structure | Compiler-owned files, symbols, members, methods, nesting, and ranges | `outline`, `methods`, `members`, `hierarchy`, `by-kind`, `kind-counts` | What constructs exist and contain one another | That a construct runs or is externally active |
+| Entry and consumer surfaces | Callables where control may enter and symbols outside consumers actually use | `entrypoints`, `entry-map`, `surface`, `fan-in` | Candidate ingress, static downstream reach, and published use | Runtime invocation from visibility or zero callers alone |
+| Execution and control | Calls, callbacks, returns, throws, branches, loops, handlers, and local control dependence | `evidence --edge execution`, `call-graph`, `dependence-slice` | Static may-call and supported control reachability | That an invocation occurred, completed, or selected a candidate target at runtime |
+| Data movement | Arguments, parameters, definitions, uses, returns, captures, field uses, serialized discriminators, and values written to state | `evidence --edge dataflow`, `value-flow`, `dependence-slice` | Supported local and bounded cross-call value transfers | General interprocedural definition-use flow, heap aliasing, or every eventual consumer |
+| Runtime handoff | Source-grounded producers and consumers joined by queues, events, commands, discriminators, or registered adapters | `evidence --edge runtime` | Supported producer/consumer rendezvous and dispatch identity | Successful delivery, retry, or an unregistered framework crossing |
+| State interaction | Identified resources read, written, deleted, enqueued, or consumed | `evidence --edge state` | Which construct performs which observed state operation | Transactionality, durability, alias identity, or exclusive ownership unless separately evidenced |
+| Temporal order | Local successors, await completion, lock scope, and supported enqueue-before-consume order | `evidence --edge temporal` | Reported local or adapter-backed before/after relations | Cross-process happens-before, durable completion, or exceptional completion |
+| Contracts | Interfaces, types, and other compiler/source contracts used by a construct | `evidence --edge contract` | The identified constraint relationship | Runtime invocation or unchecked behavioral conformance |
+| Identity | Compiler- or source-owned observations that refer to the same entity | `evidence --edge identity`, `refs`, `trace`, `reference-neighborhood` | Same-entity references within coverage | Execution, value transfer, or active product selection |
+| Ownership | Structural containment or observation ownership between code, runtime observations, and state resources | `evidence --edge ownership`, `hierarchy`, `members` | What contains or owns an observed unit | Lifetime, singleton scope, or per-session sharing unless source behavior establishes it |
+| Dependencies and topology | Imports, reverse imports, file dependencies, cycles, depth, coupling, and cross-file coordination hubs | `evidence --edge dependencies`, `deps`, `rdeps`, `imports`, `imported-by`, `system`, `cycles`, `dependency-depth`, `coupling`, `fan-out`, `bottlenecks`, `hotspots` | Static reliance and structural shape | Execution, runtime contention, or architectural intent by itself |
+| Implementation behavior | Exact statements and connected source units selected for a named gap | `inspect`, `code` | Current source behavior for materialized units | Callers, runtime reachability, or relevance without surrounding evidence |
+
+The eleven `evidence` controls are incoming and outgoing `execution`, incoming and outgoing `dataflow`, plus `runtime`, `state`, `temporal`, `contract`, `identity`, `ownership`, and `dependencies`. They cover nine top-level relationship classes.
+
+## Task-specific analyses
+
+These controls expose additional information, but they are not ordinary stages in every exploration.
+
+| Information kind | Controls | Use when |
+|---|---|---|
+| Change impact | `diff-impact`, `affected`, `change-surface` | A current or proposed edit must preserve downstream consumers, public surface, or operational roots |
+| Declared architecture | `architecture` | Project-owned boundary and dependency rules constrain the answer or edit |
+| Historical coupling and migration state | `co-change`, `incomplete-migration`, `doc-drift` | Git history or partial rollout can expose hidden coordination, residual sites, or stale documentation |
+| Complexity and structural pressure | `complexity`, `complexity-hotspots`, `fan-in`, `fan-out`, `coupling`, `dependency-depth`, `bottlenecks` | Maintainability or structural concentration is the question; reference counts are not runtime load |
+| Duplication, reuse, and cleanup candidates | `similar`, `similar-files`, `similar-chains`, `extract-candidates`, `locality-candidates`, `recent-duplicates`, `duplicate-bodies`, `twin-drift`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `redundant-reexports` | The task asks whether code can be consolidated, reused, moved, or removed; heuristic results remain candidates |
+| Framework health and implementation integrity | `health`, `dead`, `isolated`, `unused-imports`, `unused-params`, `not-implemented`, `decorative-checkers`, `test-quality`, and the React/Vue detectors | The task asks for cleanup, incomplete behavior, or configured framework findings; detector evidence contracts govern each claim |
+| Explicit state-machine models | `tla` | The task asks to scaffold, verify, record, or check an explicit transition model; a verified model is only as sound as its mapping to code |
+| Index and provider capability | `status`, `capabilities`, `doctor`, `stats` | A claim depends on freshness, language support, provider availability, or an analytical ceiling; these describe the instrument, not the repository system's behavior |
+| Delivered evidence state | `session`, transport continuations, coverage and recovery sections | You must determine what evidence has already been delivered, what was withheld recoverably, and what remains unavailable |
+
+## Calibration limits
+
+Evidence strength controls the strongest claim available:
+
+- `exact` is directly established by compiler or source evidence within reported coverage;
+- `derived` is deterministically computed from disclosed input facts;
+- `candidate` is ambiguous or heuristic and requires confirmation;
+- `mixed` preserves constituents of different strengths;
+- `unknown` has no calibrated strength and cannot support a stronger claim than the raw observation.
+
+The current general blind spots are whole-program interprocedural value flow, heap and cross-instance aliasing, interprocedural exceptional flow, reflection, generated dispatch, and framework crossings without a registered adapter. Missing edges across one of these frontiers are unknown, not proof that the behavior is absent. Close only the named material gap with `value-flow`, `dependence-slice`, `inspect`, `code`, or an exact text search as the reported recovery permits.