scip-query 0.23.0 → 0.26.0

package/skills/scip-explore/SKILL.md

@@ -1,78 +1,34 @@
 ---
 name: scip-explore
-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.
+description: Understand existing implementation paths, callers, consumers and dependencies with targeted relationship queries and ordinary source reads.
 ---
 
 # SCIP Explore
 
-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.
+Load `$scip-query` for mechanics when the question crosses code locations or module boundaries. Use ordinary search and file tools for a local lookup or implementation read.
 
-`$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.
+A repository system is cooperating code and resources that turns an initiating input into observable results. Establish only the parts whose behavior could change the requested answer or edit. For substantial work, keep concise notes on established facts and remaining questions; a formal evidence ledger is not required.
 
-## Build the proof target
+## Find the existing path
 
-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.
+Start with locations named by the request or found through ordinary search. Use `system --source` when module structure is unknown, `entrypoints` when the initiating surface is unclear, and `context <target>` when existing reuse or impact candidates matter. Avoid repeating source through another command once its behavior is established.
 
-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.
+When several implementations appear relevant, compare their entry surfaces, incoming execution, runtime connections and consumers. Path, recency and result order do not establish the live implementation. Keep distinct paths separate until routing or behavior resolves which serves the request.
 
-Give each row one status:
+Before planning new behavior, find a comparable working feature and the central path it uses. Identify the existing owners and extension points. Use `$scip-plan` to document this flow and the reuse decisions before implementation.
 
-- `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.
+## Resolve relationships and behavior
 
-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:
+Choose the relationship that answers the next concrete question: incoming execution for callers; outgoing execution for callees; runtime for producer/consumer handoffs; dataflow for value transfer; dependencies for module reliance. Batch related roots. Use another family only when its meaning matches the missing fact. The [command guide](../scip-query/references/command-guide.md#exploration) covers specialist choices.
 
-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.
+Read implementations and relevant invocations with ordinary tools to verify predicates, arguments and effects. Preserve the decisions that matter: authorization, precedence, bounds, transformations, state writes, returned defaults, notifications, owner lifetime, concurrency, errors and recovery. Follow queued work to its consumer when completion depends on it.
 
-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.
+Read saved results selectively. Expand a graph or recover omitted details only when they could change the conclusion. A bounded call list cannot establish what every caller passes, and a local slice cannot establish whole-program value history. Do not treat missing or unsupported relationships as proof of absence.
 
-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.
+Stop when the relevant behavior and consequences are established or the remaining limitation is explicit. Do not collect unrelated symbols, read every file in a result or run every available analysis.
 
-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.
+## Explain what matters
 
-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.
+Connect the initiating surface, existing owners, decisions, effects and observed result in the order needed to understand them. Cite exact files/lines or symbols. Preserve material alternative outcomes and uncertainty without adding a routine coverage footer or a transcript of the exploration.
 
-## Establish the causal spine
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-After each packet:
-
-- 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.
-
-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.
-
-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.
-
-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.
-
-## 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.
+Read [the information model](references/information-model.md) only for uncertain relationship support. The [external evidence protocol](references/external-evidence.md) applies only when an explicit runner supplies `SCIP_EXPLORE_EVIDENCE_DIR` and `SCIP_EXPLORE_LEDGER`; its checkpoint machinery is not the ordinary workflow. Use [delegated exploration](references/delegated-exploration.md) only when delegation and that checkpoint protocol are explicitly requested.

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

@@ -1,4 +1,4 @@
 interface:
-  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.'
+  display_name: "SCIP Explore"
+  short_description: "Trace live code behavior and consumers."
+  default_prompt: "Use $scip-explore to establish the live implementation and the facts needed for this task."

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

@@ -24,7 +24,7 @@ node <loaded-scip-explore-skill-directory>/scripts/capture-evidence.mjs --id loc
 
 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 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 specialized runner, use the ordinary workflow and selectively read saved results. An optional continuation reads another saved page; it is needed only when omitted evidence could change the decision. Do not infer completeness from a partial 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.
 
@@ -38,7 +38,7 @@ An `inspect --view behavior` receipt keeps every exact source slice once, plus c
 
 ## 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.
+For this explicitly requested checkpoint protocol, keep the 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:
 

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

@@ -1,42 +1,39 @@
 # 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.
+Use this map to decide what kind of repository fact the question requires. It inventories information classes rather than prescribing a route. For command selection and current index prerequisites, use the shared [command decision guide](../../scip-query/references/command-guide.md). `scip-query --help-all` remains the runtime inventory; `scip-query capabilities --matrix` reports current provider support when that is a named uncertainty.
 
 ## 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 |
+| Information kind | What its real referents are | What it can establish | What it cannot establish alone |
+|---|---|---|---|
+| Current text | Exact current project bytes, occurrences, paths, and aligned compiler owners | Cardinality and location within reported text coverage | Task relevance or executable reachability |
+| Source structure | Compiler-owned files, symbols, members, methods, nesting, and ranges | 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 | 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 | 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 | 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 | 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 | 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 | 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 | The identified constraint relationship | Runtime invocation or unchecked behavioral conformance |
+| Identity | Compiler- or source-owned observations that refer to the same entity | 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 | 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 | 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 | 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.
+Select the required information first, then consult the relevant command-guide section:
 
-| 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 |
+- [Planning and actual change review](../../scip-query/references/command-guide.md#orientation-and-change-review): reuse candidates, changed metrics and downstream consumers.
+- [Architecture and dependencies](../../scip-query/references/command-guide.md#architecture-and-dependencies): policy, structural connections, historical coordination and placement.
+- [Simplification and cleanup](../../scip-query/references/command-guide.md#simplification-and-cleanup): complexity, slices, duplication and possible removal.
+- [Framework investigations](../../scip-query/references/command-guide.md#framework-investigations): React and Vue behavior patterns.
+- [Implementation integrity](../../scip-query/references/command-guide.md#implementation-integrity): promises, live routing, placeholders, checks and migrations.
+- [Tool operations](../../scip-query/references/command-guide.md#tool-operations): index freshness, capability, installation and repair.
+
+These analyses are optional answers to specific questions, not ordinary stages in every exploration. Their measurements and candidates do not establish design quality or runtime behavior by themselves.
 
 ## Calibration limits
 
@@ -48,4 +45,4 @@ Evidence strength controls the strongest claim available:
 - `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.
+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 `dependence-slice`, `inspect`, `code`, or an exact text search as the reported recovery permits.

package/skills/scip-explore/scripts/capture-evidence.mjs

@@ -30,15 +30,27 @@ function main() {
   const receiptPath = join(evidenceRoot, `${id}.receipt.json`);
   if (existsSync(rawPath) || existsSync(receiptPath)) fail(`Evidence id already exists: ${id}`);
 
+  validateCaptureOutputArguments(queryArgs);
+
+  const priorReceipts = readPriorReceipts(evidenceRoot);
+  const reusableReceipts = receiptsForLatestObservation(priorReceipts);
+  const request = requestIdentity(queryArgs);
+  if (emitReusableCapture(id, request, reusableReceipts)) return;
+
+  const exportReceipt = executeCaptureQuery(queryArgs, rawPath);
+  const envelope = JSON.parse(readFileSync(rawPath, 'utf8'));
+  persistCaptureProjection({ id, request, rawPath, receiptPath, exportReceipt, envelope, priorReceipts });
+}
+
+function validateCaptureOutputArguments(queryArgs) {
   for (const argument of queryArgs) {
     if (FORBIDDEN_OUTPUT_ARGUMENTS.some((flag) => argument === flag || argument.startsWith(`${flag}=`))) {
       fail(`The capture wrapper owns ${argument.split('=', 1)[0]}; remove it from the scip-query arguments.`);
     }
   }
+}
 
-  const priorReceipts = readPriorReceipts(evidenceRoot);
-  const reusableReceipts = receiptsForLatestObservation(priorReceipts);
-  const request = requestIdentity(queryArgs);
+function emitReusableCapture(id, request, reusableReceipts) {
   const reuse = findReusableObservation(request, reusableReceipts);
   if (reuse) {
     process.stdout.write(
@@ -53,7 +65,7 @@ function main() {
         recovery: 'Reuse the named receipt ids in the ledger; do not rerun this observation.',
       })}\n`,
     );
-    return;
+    return true;
   }
 
   const overlap = findOverlappingCodeRanges(request, reusableReceipts);
@@ -72,9 +84,13 @@ function main() {
       })}\n`,
     );
     process.exitCode = 2;
-    return;
+    return true;
   }
 
+  return false;
+}
+
+function executeCaptureQuery(queryArgs, rawPath) {
   const execution = spawnSync('scip-query', [...queryArgs, '--json', '--json-output', rawPath], {
     cwd: process.cwd(),
     env: process.env,
@@ -90,7 +106,10 @@ function main() {
   if (!isAbsolute(exportReceipt.path) || resolve(exportReceipt.path) !== rawPath) {
     fail('scip-query wrote the evidence packet to an unexpected path.');
   }
-  const envelope = JSON.parse(readFileSync(rawPath, 'utf8'));
+  return exportReceipt;
+}
+
+function persistCaptureProjection({ id, request, rawPath, receiptPath, exportReceipt, envelope, priorReceipts }) {
   const projection = projectCommandResult(envelope);
   if (projection.status !== 'complete') {
     const refusal = {
@@ -165,17 +184,8 @@ function projectCommandResult(envelope) {
   const identityCoverage = result?.identityCoverage;
   const identities = result?.identities;
   const scopeHints = result?.scopeHints;
-  const commandProjectionComplete =
-    Array.isArray(identities) &&
-    identityCoverage?.mode === 'complete' &&
-    identityCoverage.omitted === 0 &&
-    identityCoverage.returned === identities.length &&
-    identityCoverage.total === identities.length;
-  const exhaustivePacketComplete =
-    Array.isArray(identities) &&
-    Number.isSafeInteger(identityCoverage?.total) &&
-    identities.length === identityCoverage.total &&
-    result.matchingLines === identityCoverage.total;
+  const commandProjectionComplete = completeCommandSearchIdentities(identities, identityCoverage);
+  const exhaustivePacketComplete = completeExhaustiveSearchIdentities(result, identities, identityCoverage);
   const identitiesComplete = commandProjectionComplete || exhaustivePacketComplete;
   const scopeHintsComplete = Array.isArray(scopeHints) && result.omittedScopeHints === 0;
   if (!identitiesComplete || !scopeHintsComplete) {
@@ -221,6 +231,25 @@ function projectCommandResult(envelope) {
   };
 }
 
+function completeCommandSearchIdentities(identities, coverage) {
+  return (
+    Array.isArray(identities) &&
+    coverage?.mode === 'complete' &&
+    coverage.omitted === 0 &&
+    coverage.returned === identities.length &&
+    coverage.total === identities.length
+  );
+}
+
+function completeExhaustiveSearchIdentities(result, identities, coverage) {
+  return (
+    Array.isArray(identities) &&
+    Number.isSafeInteger(coverage?.total) &&
+    identities.length === coverage.total &&
+    result.matchingLines === coverage.total
+  );
+}
+
 function groupSearchIdentities(identities) {
   const files = new Map();
   for (const identity of identities) {
@@ -569,23 +598,7 @@ function priorSourceCoverage(priorReceipts) {
   const coverage = new Map();
   for (const receipt of priorReceipts) {
     if (receipt.observation === undefined) continue;
-    const ranges = [];
-    if (receipt.request?.args?.[0] === 'code') {
-      const codeRanges = parseCodeRanges(receipt.request.args.slice(1));
-      if (codeRanges !== null) ranges.push(...codeRanges);
-    }
-    if (receipt.observation.result?.kind === 'bounded-inspect-behavior-projection') {
-      for (const slice of receipt.observation.result.slices ?? []) {
-        if (
-          typeof slice.relativePath === 'string' &&
-          Number.isSafeInteger(slice.startLine) &&
-          Number.isSafeInteger(slice.endLine) &&
-          slice.startLine <= slice.endLine
-        ) {
-          ranges.push({ path: slice.relativePath, start: slice.startLine, end: slice.endLine });
-        }
-      }
-    }
+    const ranges = receiptSourceRanges(receipt);
     for (const range of ranges) {
       const intervals = coverage.get(range.path) ?? [];
       intervals.push({ ...range, receipt });
@@ -595,6 +608,27 @@ function priorSourceCoverage(priorReceipts) {
   return coverage;
 }
 
+function receiptSourceRanges(receipt) {
+  const ranges = [];
+  if (receipt.request?.args?.[0] === 'code') {
+    const codeRanges = parseCodeRanges(receipt.request.args.slice(1));
+    if (codeRanges !== null) ranges.push(...codeRanges);
+  }
+  if (receipt.observation.result?.kind === 'bounded-inspect-behavior-projection') {
+    for (const slice of receipt.observation.result.slices ?? []) {
+      if (
+        typeof slice.relativePath === 'string' &&
+        Number.isSafeInteger(slice.startLine) &&
+        Number.isSafeInteger(slice.endLine) &&
+        slice.startLine <= slice.endLine
+      ) {
+        ranges.push({ path: slice.relativePath, start: slice.startLine, end: slice.endLine });
+      }
+    }
+  }
+  return ranges;
+}
+
 function subtractIntervals(range, intervals) {
   let remaining = [{ start: range.start, end: range.end }];
   for (const interval of intervals.sort((left, right) => left.start - right.start || left.end - right.end)) {