scip-query 0.10.6 → 0.10.8

package/docs/COMMAND_REFERENCE.md

@@ -93,7 +93,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>`<br>`--json` |
 | `change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | `--full`<br>`--json` |
 | `co-change [file]` | Files that change together in git history without a dependency edge — hidden coupling candidates | `--min-together <n>`<br>`-n, --limit <n>`<br>`--all`<br>`--full`<br>`--json` |
-| `diff-gate` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, uncited doc updates, unused params, new dead symbols; exit 1 on findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--skip <check>`<br>`--hook`<br>`--json` |
+| `diff-gate` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, uncited doc updates, unused params, new dead symbols; exit 1 on findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--baseline`<br>`--full`<br>`--skip <check>`<br>`--hook`<br>`--json` |
 | `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
 | `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>`<br>`--json` |
 
@@ -115,7 +115,8 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 
 | Command | Description | Options |
 |---|---|---|
-| `install-skills` | Install skills (scip-query, scip-query-setup, scip-adoption, scip-health-audit, scip-health-improve, scip-api-impact, concrete-plan, scip-ai-cleanup, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-debloat, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook) into Claude Code, Codex, and shared agent roots | - |
+| `bench` | Benchmark indexing and command runtimes for this repository | `--json`<br>`--cold-index`<br>`--include-heavy`<br>`--command <cmd>`<br>`--timeout-ms <n>` |
+| `install-skills` | Install skills (scip-query, scip-query-setup, scip-adoption, scip-health-audit, scip-health-improve, scip-hyper-optimization, scip-api-impact, concrete-plan, scip-ai-cleanup, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-debloat, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook) into Claude Code, Codex, and shared agent roots | - |
 | `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--json` |
 | `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
 | `capabilities` | Report which evidence and verification capabilities are available in this project | `--json` |
@@ -127,7 +128,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `setup` | Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health | `--git-hook`<br>`--json` |
 | `setup-agent` | Seed agent guidance for this project: AGENTS.md/CLAUDE.md block pointing agents at the scip-query skills and diff gate, plus an optional git pre-commit backstop | `--git-hook` |
 | `setup-ci` | Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests | `--force`<br>`--dry-run` |
-| `watch` | Watch for file changes and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>` |
+| `watch` | Watch for file changes and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>` |
 | `status` | Show index status for this project | `--json`<br>`--capabilities` |
 
 <!-- END GENERATED COMMAND REFERENCE -->

package/docs/analyzer-inventory.md

@@ -20,7 +20,7 @@ The action tiers are:
 
 ## Current Surfaces
 
-The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`, with doc-reference and baseline policy helpers kept private to the query tree.
+The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet.
 
 `health --json` on this repository currently reports:
 
@@ -67,7 +67,7 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 | `doc-reference`        | Living docs citing changed files, excluding import-only source changes, with citation kind and Markdown-local cited-claim context                                                         | Split by citation evidence | Behavioral/current doc claims are direct doc-review evidence. Configuration examples and intentional records are support-tier checks unless the cited target changed meaning.                                                                                                                                 |
 | `unused-params`        | Trailing unused params in changed files                                                                                                                                                   | Direct repair              | Conservative enough to be a high-confidence local fix.                                                                                                                                                                                                                                                        |
 | `new-dead`             | Changed production symbols with zero consumers, excluding entry/root/test/framework-discovered cases                                                                                      | Direct repair              | Either wire it up, remove it, or mark it as an externally live root before it lands.                                                                                                                                                                                                                          |
-| `baseline`             | New health finding identity versus committed baseline                                                                                                                                     | Direct gate                | It does not explain the smell itself, but correctly blocks regression until fixed or accepted.                                                                                                                                                                                                                |
+| `baseline`             | New health finding identity versus committed baseline, when the caller explicitly asks diff-gate to run the full baseline ratchet                                                         | Direct gate                | It does not explain the smell itself, but correctly blocks regression until fixed or accepted. It is opt-in for diff-gate because the baseline comparison is repo-wide rather than diff-sized.                                                                                                                |
 
 ## Standalone Cleanup and Similarity Analyzers
 

package/docs/analyzer-validation-ledger.md

@@ -15,7 +15,7 @@ The ledger is anchored to the current tool surface, not memory.
 | Surface                   | Source                                                                                                                                                                                                                                                                                                       | Why it anchors the ledger                                                                     |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
 | Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:194`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()`.                                                                                                                                                          | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
-| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:94`, where `diffGate()` runs `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, `new-dead`, and `baseline`.                                                                                  | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
+| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:94`, where `diffGate()` runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide. | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
 | Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:10`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:94`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                  |
 | Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:27`, where the canonical diff-gate check list is exported.                                                                                                                                                              | The ledger must cover every change-time check that can block a diff.                          |
 
@@ -267,4 +267,4 @@ The maintainability-register completion slice rechecked the ledger's command-sur
 
 ## 2026-06-23 Current Sweep Citation Refresh
 
-The current maintainability sweep rechecked the `diff-gate.ts` citation again after doc-reference and baseline policy helpers moved into private query modules. The ledger remains accurate because `diffGate()` and `DIFF_GATE_CHECKS` still live in `src/queries/impact/diff-gate.ts`; only helper policy bodies moved behind the same entry point.
+The current maintainability sweep rechecked the `diff-gate.ts` citation again after doc-reference and baseline policy helpers moved into private query modules. The ledger remains accurate because `diffGate()` and `DIFF_GATE_CHECKS` still live in `src/queries/impact/diff-gate.ts`; the baseline policy body remains behind the same entry point, but the repo-wide baseline ratchet is explicit rather than part of default diff-gate execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",

package/skills/concrete-plan/SKILL.md

@@ -11,7 +11,7 @@ You are writing a production implementation plan as a markdown checklist. Every
 
 ## Hard Rules
 
-1. **Every code reference must come from scip-query.** Run `scip-query reindex` before starting. Re-run if significant code has changed during the session. No reference from memory, grep, or file reads.
+1. **Every code reference must come from scip-query.** Run `scip-query status --capabilities` or `scip-query status --json` before starting. If freshness is `fresh`, keep going; if it is `stale`, `missing`, or `unknown`, run `scip-query reindex` before using graph facts. No reference from memory, grep, or file reads.
 
 2. **Every step must cite its source.** Each step in the plan includes a `Source` field naming the scip-query command that produced the file path, line number, and behavioral claim. A step without a Source is unverified and must not appear in the plan.
 
@@ -289,7 +289,7 @@ Apply the 11 Principles against every step in the design. For each principle, as
 
 After stress-testing is complete:
 
-1. **Reindex**: Run `scip-query reindex`.
+1. **Freshness**: Run `scip-query status --capabilities`; reindex only if freshness is not `fresh`.
 2. **Verify references**: Spawn parallel subagents (one per phase) using the **Subagent Briefing Template**. Each agent confirms that every file path exists, every line number is within +-5 lines, and every described behavior matches reality. Reject output that doesn't cite scip-query commands.
 3. **Fix drift**: Update any stale references.
 4. **Check execution order**: No phase depends on a later phase. No step within a phase depends on a later step.

package/skills/scip-adoption/SKILL.md

@@ -67,7 +67,9 @@ scip-query config-validate
 ### 5. Prove ongoing local usefulness
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query stats
 scip-query files <known-source-term>
 scip-query outline <known-source-file>
@@ -109,7 +111,7 @@ Health:
 - confirmed cleanup queue or audit handoff
 
 Verification:
-- `scip-query reindex`
+- `scip-query status --capabilities`, then `scip-query reindex` only if freshness is `stale`, `missing`, or `unknown`
 - `scip-query diff-gate --json`
 - targeted smoke commands
 

package/skills/scip-ai-cleanup/SKILL.md

@@ -25,7 +25,7 @@ plan and a CI ratchet.
 
 ## Hard Rules
 
-1. **Evidence first.** Run `scip-query status` and `scip-query reindex` before
+1. **Evidence first.** Run `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown` before
    trusting graph facts. All detectors print whether they're heuristic.
 2. **Verify before deleting.** Findings are candidates; only
    `cleanup-plan --verify` output stamped COMPILER-VERIFIED is proof.

package/skills/scip-api-impact/SKILL.md

@@ -21,7 +21,9 @@ Use this skill before changing a public surface. A public surface is a callable,
 
 ```bash
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query surface <module-or-package>
 scip-query outline <file>
 scip-query trace <symbol-or-command>
@@ -103,7 +105,9 @@ Verification:
 ### 6. Verify after editing
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query diff-impact --json
 scip-query diff-gate --json
 ```

package/skills/scip-debloat/SKILL.md

@@ -304,7 +304,7 @@ scip-query hotspots -n 10                  # Most-referenced symbols
 ### Phase 1: Health Check (5 minutes)
 
 ```bash
-scip-query reindex                         # Ensure index is fresh
+scip-query status --capabilities           # Ensure freshness; reindex only if stale, missing, or unknown
 scip-query health                          # Get the full report
 ```
 

package/skills/scip-debug/SKILL.md

@@ -32,7 +32,9 @@ If the user provides no reproduction, make the smallest runnable reproduction yo
 
 ```bash
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query files <feature-or-error-term>
 scip-query outline <candidate-file>
 scip-query trace <candidate-symbol>
@@ -88,7 +90,9 @@ Name the smallest symbol or file that should change. If the blast radius is larg
 Apply the minimal code change, then run:
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query diff-gate --json
 ```
 

package/skills/scip-diagram/SKILL.md

@@ -32,7 +32,9 @@ Start with current graph facts:
 
 ```bash
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 ```
 
 Collect only the commands needed for the diagram:

package/skills/scip-directory-architecture/SKILL.md

@@ -24,7 +24,7 @@ A migration slice is the smallest set of file moves and import updates that can
 3. Preserve working conventions. Existing boundaries are not wrong just because they are broad; central folders such as `errors`, `routes`, `workflows`, `schemas`, `contracts`, or `features` may be doing real work.
 4. Do not reward generic `shared`. A shared folder is justified only when the shared concept has a name, owner, and consumers across real boundaries.
 5. Treat messy repos honestly. If ownership concepts are not stable, produce a discovery map and decision list instead of pretending the repo has a clean target structure.
-6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate --json`.
+6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, a fresh scip-query index, and `scip-query diff-gate --json`.
 
 ## Workflow
 
@@ -46,7 +46,9 @@ Run:
 
 ```bash
 scip-query status
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query stats
 find . -maxdepth 3 -type d | sort
 ```
@@ -155,7 +157,9 @@ When the user asks to proceed, pick the smallest high-confidence slice. Before e
 Then move files with normal filesystem tools, update imports with project tooling where available, and run:
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query incomplete-migration
 scip-query recent-duplicates
 scip-query co-change <moved-file-or-config>

package/skills/scip-doc-reconcile/SKILL.md

@@ -30,7 +30,9 @@ descriptive.
 ### 1. Build the evidence-backed worklist
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query doc-drift                      # all living docs, ranked by staleness
 scip-query doc-drift agent-os/standards   # scoped to a standards tree
 ```

package/skills/scip-explore/SKILL.md

@@ -77,10 +77,10 @@ Start by making sure the SCIP facts are current enough to trust:
 
 ```bash
 scip-query status                    # Check index location, freshness, and project root
-scip-query reindex                   # Run when missing, stale, uncertain, or after code changes
+scip-query status --capabilities     # Reindex only when freshness is stale, missing, or unknown
 ```
 
-If `status` is unavailable or inconclusive, run `scip-query stats` and `scip-query reindex` when the repository has changed. Do not explore from an index you know is stale.
+If `status` is unavailable or inconclusive, run `scip-query stats` and then `scip-query reindex` only when the repository has changed or freshness cannot be proven. Do not explore from an index you know is stale.
 
 ### Step 1: Orient — What are we looking at?
 

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

@@ -34,7 +34,9 @@ Then collect the current state:
 ```bash
 scip-query doctor
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query health --json --full
 scip-query diff-gate --json
 scip-query capability-matrix --json
@@ -139,7 +141,9 @@ When the user has asked for cleanup or the current workflow is post-setup cleanu
 After every batch:
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query diff-gate --json
 scip-query health --json --full
 ```

package/skills/scip-health-improve/SKILL.md

@@ -40,7 +40,9 @@ Collect the baseline before ranking:
 ```bash
 scip-query doctor
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query health --json --full
 scip-query diff-gate --json
 scip-query capability-matrix --json
@@ -116,7 +118,9 @@ Then repeat:
 2. Run the project check that proves the touched behavior.
 3. Run:
    ```bash
-   scip-query reindex
+   scip-query status --capabilities
+   # If freshness is stale, missing, or unknown:
+   # scip-query reindex
    scip-query diff-gate --json
    scip-query health --json --full
    ```

package/skills/scip-hyper-optimization/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: scip-hyper-optimization
+description: Run scientific performance optimization campaigns with scip-query evidence, command ledgers, and benchmark corpora. Use when the user asks to hyper optimize, make commands blazing fast, speed up a CLI/tool/app, benchmark regressions, or compare targeted tuning against radically different implementations.
+---
+
+# SCIP Hyper Optimization
+Use this skill to make a command, workflow, service, page, or tool as fast as
+feasibly possible without changing its observable result. Hyper optimization is
+a bounded campaign that improves runtime, memory use, or computational cost
+against objective measurements; every accepted change is proven by a repeatable
+benchmark and unchanged output.
+
+A measurement harness is the repeatable set of commands, fixtures, corpora,
+environment notes, and result documents used to decide whether performance
+changed. A command ledger is the living document for one target: what it
+returns, what code runs, where time is spent, what was tried, and what evidence
+accepted or rejected each idea.
+
+## Rules
+
+1. Do not optimize until a measurement harness exists or has been created.
+2. Use scip-query for code understanding: `status`, `plan-context`, `trace`,
+   `call-graph`, `code`, `dataflow`, `complexity`, `diff-impact`, `diff-gate`.
+3. Capture representative inputs, required output behavior, and correctness
+   checks before editing.
+4. Measure cold and warm paths when both matter; record exact commands, corpus,
+   elapsed time, repetitions, and outliers.
+5. Work both tracks: tune the current pipeline and evaluate radically different
+   algorithms or data models that preserve the same result.
+6. Keep only changes that improve real workloads without reducing accuracy,
+   diagnostics, safety checks, or supported inputs.
+
+## Phase 0: Measurement Harness
+If the target repository is not already a reliable scip-query workspace, invoke
+`scip-query-setup` first. Do not run setup-ci in this workflow.
+
+Create or update a benchmark note before code changes. Prefer the repo's
+existing convention; otherwise use
+`docs/benchmarks/YYYY-MM-DD-<target>-baseline.md`. Include target, machine/date
+context, corpus or fixture list, cold/warm/correctness commands, baseline
+timings, output-contract evidence, and slowest stages.
+
+Choose the measurement mechanism from the target's real workload. For app
+paths, use the app's benchmark, test, route smoke, build, profiler, load test,
+or timing script; if none exists, create the smallest repeatable timing command.
+For scip-query command, detector, or indexer targets, benchmark the relevant
+command matrix:
+
+```bash
+scip-query bench --json
+scip-query bench --json --cold-index --include-heavy --timeout-ms 600000
+```
+
+## Phase 1: Command Ledger
+Create one ledger per target:
+`docs/benchmarks/YYYY-MM-DD-<target>-ledger.md`. Include Output Contract,
+Current Pipeline, Measurements, Current-Pipeline Optimizations, Alternative
+Designs, and Decisions.
+
+## Phase 2: Trace Current Behavior
+Trace the target end to end and write the actual path into the ledger:
+
+```bash
+scip-query status --capabilities
+# If stale, missing, or unknown: scip-query reindex
+scip-query plan-context <entry-symbol-or-file>
+scip-query trace <entry-symbol>
+scip-query call-graph <entry-symbol>
+scip-query code <entry-symbol>
+scip-query dataflow <entry-symbol>
+scip-query complexity <hot-symbol>
+scip-query change-surface <touched-file> --json --full
+```
+
+Record input parsing, lookups, database queries, graph traversal, source scans,
+semantic calls, cache reads/writes, rendering, and verification.
+
+## Phase 3: Find Speedups
+For the current pipeline, look for repeated work, broad scans, N+1 lookups,
+uncached pure work, avoidable source or semantic reads, large arrays, late
+filters, batchable per-file work, and safe parallelism.
+
+For alternative designs, restate the output contract first. Ask whether SQLite
+can answer directly, an index/cache/precomputed table can move work out of the
+hot path, batch queries can replace loops, a cheap pruning stage can precede
+exact work, or workers can run independent phases safely.
+
+## Phase 4: Implement and Verify
+Make the smallest reversible change that tests one performance hypothesis.
+Update the ledger with hypothesis, changed files/symbols, before/after timings,
+output comparison, tests, and gates.
+
+Run the narrow correctness check, benchmark cases, `scip-query diff-impact
+--json`, and `scip-query diff-gate --json`; reindex first if freshness is not
+proven. Also run postchecks matching the change type. End with starting time,
+final time, percentage change, accepted changes, rejected ideas, remaining
+bottlenecks, and the next target.

package/skills/scip-hyper-optimization/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Hyper Optimization"
+  short_description: "Scientific benchmark-driven optimization"
+  default_prompt: "Use $scip-hyper-optimization to set up objective benchmarks, trace the target end to end, and optimize it without changing output."

package/skills/scip-maintainability/SKILL.md

@@ -28,7 +28,7 @@ System compression belongs inside this review. A system compression is a maintai
 
 ## Hard Rules
 
-1. **Evidence first.** Use `scip-query` to ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius. If the SCIP index is missing or stale, run `scip-query reindex` before trusting graph facts.
+1. **Evidence first.** Use `scip-query` to ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius. Check `scip-query status --capabilities`; if freshness is `stale`, `missing`, or `unknown`, run `scip-query reindex` before trusting graph facts.
 
 2. **Do not chase health scores.** `scip-query health`, detector counts, and LOC estimates are diagnostic signals. They are not the objective. A change is valuable only when it reduces real maintenance burden while preserving behavior.
 
@@ -83,7 +83,7 @@ Start from current code intelligence:
 
 ```bash
 scip-query status
-scip-query reindex                    # Run when missing, stale, uncertain, or after code changes
+scip-query status --capabilities      # Reindex only when freshness is stale, missing, or unknown
 scip-query stats
 scip-query system <scope>
 scip-query surface <scope>
@@ -264,7 +264,10 @@ Always finish implemented maintainability work with:
 
 ```bash
 scip-query diff-impact --json
-scip-query reindex && scip-query diff-gate --json
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
+scip-query diff-gate --json
 ```
 
 Treat `diff-gate` findings as unfinished work. Fix them or state a concrete acceptance reason; do not silently report success.

package/skills/scip-query/SKILL.md

@@ -10,8 +10,11 @@ Your job here is only to route: identify the phase of work, invoke the right
 specialist skill, and enforce the non-negotiable checks. Do not improvise a
 workflow when a specialist skill exists for it.
 
-If the index might be stale (code changed since the last reindex), run
-`scip-query reindex` before anything else.
+Before trusting graph facts, check freshness with `scip-query status --capabilities`
+or `scip-query status --json`. If the index is `fresh`, continue without
+reindexing. If it is `stale`, `missing`, or `unknown`, run `scip-query reindex`
+before using code-intelligence results. Project hooks auto-refresh stale indexes
+by default unless `.scipquery.json` sets `watch.autoRefresh: false`.
 
 ## The default loop for any implementation request
 
@@ -22,9 +25,9 @@ When the user asks you to build, change, or fix something non-trivial:
 2. **Implement** the plan.
 3. **Verify** — invoke `scip-verify`, then run the post-checks that match what
    you changed (table below).
-4. **Gate before done** — run `scip-query reindex`, then
-   `scip-query diff-gate --json`; fix findings or state explicitly why each is
-   accepted.
+4. **Gate before done** — check freshness; reindex only when the index is not
+   `fresh`, then run `scip-query diff-gate --json`; fix findings or state
+   explicitly why each is accepted.
 
 ## Route by phase of work
 
@@ -37,8 +40,10 @@ When the user asks you to build, change, or fix something non-trivial:
 | Plan a feature, fix, or refactor                                                                                   | `concrete-plan`               | `scip-query plan-context <target>`                                                                          |
 | Assess a public API, route, CLI, config, schema, or boundary change                                                | `scip-api-impact`             | `scip-query surface <module>`, `scip-query affected <symbol>`, `scip-query co-change <file>`                |
 | Pick high-signal commands for an unfamiliar language                                                               | `scip-language-playbook`      | —                                                                                                           |
+| Benchmark indexing, command runtime, or detector performance                                                       | `scip-query`                  | `scip-query bench --json`, `scip-query bench --cold-index --include-heavy`                                  |
+| Hyper-optimize a command, workflow, indexer, detector, or app path with benchmark ledgers and alternative designs  | `scip-hyper-optimization`     | `scip-query bench --json`, `scip-query plan-context <target>`, command-specific correctness checks          |
 | Adopt or bootstrap scip-query in a repository                                                                      | `scip-adoption`               | `scip-query setup --json`, `scip-query check-deps`, `scip-query capability-matrix --json`                   |
-| Verify work you just finished (any implementation, refactor, or extraction)                                        | `scip-verify`                 | `scip-query reindex`, `scip-query diff-gate --json`                                                         |
+| Verify work you just finished (any implementation, refactor, or extraction)                                        | `scip-verify`                 | `scip-query status --capabilities`, `scip-query diff-gate --json`                                           |
 | Confirm post-setup health signals before cleanup                                                                   | `scip-health-audit`           | `scip-query health --json --full`, `scip-query diff-gate --json`                                            |
 | Raise the health score as high as reasonably possible with autonomous verified cleanup                             | `scip-health-improve`         | `scip-query health --json --full`, `scip-query cleanup-plan --verify --json`, `scip-query diff-gate --json` |
 | Audit dead code, duplication, unnecessary abstractions, or structural bloat and produce a prioritized cleanup plan | `scip-debloat`                | `scip-query health`                                                                                         |
@@ -59,6 +64,9 @@ Use these boundaries before loading a specialist skill:
 - `scip-health-improve` is the autonomous campaign. Use it when the user asks
   to raise/maximize the health score, keep working with minimal interaction, or
   get the repo as clean as reasonably possible.
+- `scip-hyper-optimization` is the benchmark-led performance campaign. Use it
+  when the user asks to make a command, detector, indexer, workflow, or app path
+  as fast as possible while preserving output.
 - `scip-debloat` is a bloat audit and cleanup plan. Use it when the user wants
   dead code, duplication, unnecessary abstractions, wrappers, or structural
   waste found and prioritized, but has not asked for a score-maxing campaign.

package/skills/scip-query-setup/SKILL.md

@@ -44,7 +44,7 @@ The setup command also installs skills and configures project-local hooks, but r
 scip-query setup --json
 ```
 
-This pass installs bundled skills, configures project-local hooks, checks indexer readiness, attempts configured indexer remediation, refreshes the index, verifies capabilities, smoke-tests representative command families, writes `docs/scip-query/health-dossier.md` and `docs/scip-query/health-dossier.json`, and seeds agent guidance.
+This pass installs bundled skills, configures project-local hooks, checks indexer readiness, attempts configured indexer remediation, refreshes or reuses the index, verifies capabilities, smoke-tests representative command families, writes `docs/scip-query/health-dossier.md` and `docs/scip-query/health-dossier.json`, and seeds agent guidance.
 
 If setup reports `blocked`, run:
 
@@ -64,11 +64,14 @@ scip-query config-validate
 
 Keep `.scipquery.json` minimal. Add settings only when they are justified by observed repo facts, reviewed false positives, declared coupling, or explicit suppressions.
 
-6. Refresh the index and inspect project status when setup repairs anything.
+For TypeScript monorepos with multiple discovered project shards, prefer persistent `indexer.typescript.projectMode: "workspace"`. Add `indexerConcurrency` only when the repo has enough CPU/memory or measured cold-index timing justifies a project-specific worker cap.
+
+6. Inspect freshness and refresh only when setup repairs anything or the index is not fresh.
 
 ```bash
-scip-query reindex
 scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query capabilities --json
 scip-query stats
 ```
@@ -79,7 +82,7 @@ If an upstream indexer skipped source files that should still be searchable or v
 scip-query augment-sources
 ```
 
-Use `scip-query watch` only for an active local session where repeated source edits need automatic reindexing. It is not part of the default setup proof.
+Project hooks auto-refresh stale indexes for agent sessions unless `.scipquery.json` sets `watch.autoRefresh: false`. Use `scip-query watch` only when a human explicitly wants a long-running live watcher in a terminal.
 
 7. Confirm health signals before cleanup.
 
@@ -132,7 +135,9 @@ If the repo has no mature boundaries, the correct setup result is a note, not a
 10. Finish with the standard gate.
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query diff-gate --json
 ```
 

package/skills/scip-react-maintainability/SKILL.md

@@ -21,7 +21,9 @@ Refresh the code intelligence before trusting graph facts:
 
 ```bash
 scip-query status
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 ```
 
 Run the React review commands uncapped when doing a serious frontend pass. Do not combine `--full` with `--limit`.
@@ -83,7 +85,10 @@ scip-query unused-params
 scip-query wrapper-candidates --scope <react-source-scope> --full --json
 scip-query passthrough-candidates --scope <react-source-scope> --full --json
 scip-query stale-abstractions --scope <react-source-scope> --include-low-confidence --full --json
-scip-query reindex && scip-query diff-gate --json
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
+scip-query diff-gate --json
 ```
 
 Use the results this way:

package/skills/scip-triage-issue/SKILL.md

@@ -34,7 +34,9 @@ If key facts are missing but the repo can answer them, investigate. Ask the user
 
 ```bash
 scip-query status --capabilities
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query files <issue-term>
 scip-query outline <candidate-file>
 scip-query system <module-or-scope>
@@ -101,7 +103,7 @@ Write the packet before filing or fixing:
 1. Add or update failing test/smoke check.
 2. Make the smallest code change.
 3. Run targeted test.
-4. Run `scip-query reindex`.
+4. Run `scip-query status --capabilities`; if freshness is `stale`, `missing`, or `unknown`, run `scip-query reindex`.
 5. Run `scip-query diff-gate --json`.
 6. Invoke `scip-verify`.
 

package/skills/scip-verify/SKILL.md

@@ -10,7 +10,7 @@ Verify the actual diff, not your intention. A verification pass proves that the
 ## Hard Rules
 
 1. Run environment checks before trusting graph facts.
-2. Reindex before final verification unless a just-finished command already did so and no files changed afterward.
+2. Check index freshness before final verification. Reindex only when freshness is `stale`, `missing`, or `unknown`, unless a just-finished command already refreshed the index and no files changed afterward.
 3. Treat `scip-query diff-gate --json` as the primary blocker for diff-specific risk. Manual checks are drill-down evidence, not a replacement.
 4. Run the postchecks that match the actual change type.
 5. Prefer fixing findings. Use `scip-query suppress <id> --reason "<specific reason>"` only for intentional design, compatibility shims, framework entry points, or accepted false positives with durable evidence.
@@ -30,7 +30,9 @@ If either command reports missing indexers, stale indexes, invalid config, or un
 ### 2. Refresh and assess the diff
 
 ```bash
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 scip-query diff-impact --json
 ```
 
@@ -155,4 +157,4 @@ Remaining risk:
 - accepted suppressions, blocked capabilities, or checks not run
 ```
 
-Do not claim "safe to commit" unless `scip-query reindex` and `scip-query diff-gate --json` passed after the final file edit.
+Do not claim "safe to commit" unless freshness is `fresh` after the final file edit and `scip-query diff-gate --json` passed.

package/skills/scip-vue-maintainability/SKILL.md

@@ -21,7 +21,9 @@ Refresh the code intelligence before trusting graph facts:
 
 ```bash
 scip-query status
-scip-query reindex
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
 ```
 
 If Vue files need rich internals, find the relevant TypeScript project and augment the index:
@@ -89,7 +91,10 @@ scip-query unused-params
 scip-query wrapper-candidates --scope <vue-source-scope> --full --json
 scip-query passthrough-candidates --scope <vue-source-scope> --full --json
 scip-query stale-abstractions --scope <vue-source-scope> --include-low-confidence --full --json
-scip-query reindex && scip-query diff-gate --json
+scip-query status --capabilities
+# If freshness is stale, missing, or unknown:
+# scip-query reindex
+scip-query diff-gate --json
 ```
 
 Use the results this way: