scip-query 0.10.0 → 0.10.2

package/docs/analyzer-validation-ledger.md

@@ -0,0 +1,262 @@
+# Analyzer Validation Ledger
+
+This ledger records the analyzer evaluation work carried out after the analyzer inventory, validation protocol, and locality design. It is the operating document for keeping analyzer accuracy work traceable end to end.
+
+The companion documents are:
+
+- `docs/analyzer-inventory.md`: names the analyzers and their action tiers.
+- `docs/analyzer-validation-protocol.md`: defines the review protocol and per-analyzer TP/FP/FN criteria.
+- `docs/locality-analyzer-design.md`: defines the locality and organization analyzer behavior.
+
+## Source Anchors
+
+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.              |
+| 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.                          |
+
+## Core Concepts
+
+A validation ledger is a maintained record of analyzer evaluation work, including the claim being tested, the repositories used, the evidence captured, the verdict, and the next precision action. Its essential role is to keep validation from dissolving into scattered notes by making every analyzer claim traceable to a reviewed outcome.
+
+A ledger item is one independently completable evaluation obligation. It may cover one analyzer, one analyzer family, one repository run, or one score-model decision; its essential characteristic is that it has a clear done signal and can move from ready to complete without needing the whole validation effort to finish.
+
+A run batch is a bounded execution of analyzer commands against one repository and revision. It is the smallest repeatable field-test unit because it records the project, commit, commands, raw output, sample selection, and reviewer verdicts together.
+
+A calibration decision is a documented change to detector confidence, action tier, score weight, threshold, wording, or evidence fields. It is not just a preference; it is a maintainer decision justified by reviewed true positives, false positives, false negatives, suppressions, or repair outcomes.
+
+A repair outcome is the result of acting on an analyzer finding. It matters because an analyzer can be locally accurate while still causing bad repairs, churn, misplaced abstractions, or broader APIs when an agent follows it.
+
+## Status Values
+
+| Status     | Meaning                                                                            |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `ready`    | The item has a defined scope, command set, corpus, and done signal.                |
+| `running`  | Raw analyzer output or human review is currently being collected.                  |
+| `blocked`  | The item cannot be completed until tooling, indexing, or corpus access improves.   |
+| `complete` | The item has reviewed evidence, verdicts, and any next precision actions recorded. |
+| `deferred` | The item is valid but intentionally lower priority than other ledger work.         |
+
+## Active Ledger
+
+Closeout status: all active ledger rows are complete as of 2026-06-22. Remaining future work is provider- or corpus-gated, not an unfinished validation slice: true co-change issue/PR label ingestion needs a repository metadata provider, and locality score integration needs stronger consumer-coverage plus repair-outcome evidence.
+
+| ID      | Item                                   | Scope                                                                                                                                                                                  | Status     | Next action                                                                               | Done signal                                                                                              |
+| ------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| AVL-001 | Field evaluation baseline              | Run the protocol on `scip-query`, `Stable_Management`, `Vega_2.0`, and `SynthRunnerRust`.                                                                                              | `complete` | Completed in `docs/validation/2026-06-21-second-repo-confirmation.md`.                    | A dated run summary exists for each repo with raw-output locations and sampling notes.                   |
+| AVL-002 | Direct repair analyzer verdicts        | `cleanup-plan`, `dead`, `new-dead`, `isolated`, `unused-params`, `unused-imports`, `redundant-reexports`, `passthrough-candidates`, `cycles`, broken `doc-drift`, and `doc-reference`. | `complete` | Completed in `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`.       | Each direct analyzer has TP/FP/FN counts, accepted-design examples, and precision actions.               |
+| AVL-003 | Contextual signal analyzer verdicts    | Similarity, extraction, locality, wrapper, stale abstraction, frontend duplicate, hook/composable, co-change, bottleneck, coupling, drift, and deep-chain families.                    | `complete` | Completed in `docs/validation/2026-06-21-contextual-signal-closure-result.md`.            | Each contextual family has a reviewed precision note and a score-weight recommendation.                  |
+| AVL-004 | Support analysis accuracy              | `affected`, `change-surface`, `plan-context`, navigation commands, graph metrics, and `self-audit`.                                                                                    | `complete` | Completed in `docs/validation/2026-06-21-support-analysis-accuracy-result.md`.            | Support commands have referential-accuracy notes and known unsupported cases.                            |
+| AVL-005 | Analyzer implementation parity         | Confirm each public analyzer command's documented behavior matches implementation behavior.                                                                                            | `complete` | Completed in `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`.       | The inventory and protocol either match implementation or list required doc/code corrections.            |
+| AVL-006 | Score calibration                      | Evaluate direct findings, contextual signals, suppressions, validation ratio, and signal backlog pressure.                                                                             | `complete` | Completed in `docs/validation/2026-06-21-score-calibration-finalization-result.md`.       | A calibration memo states score-weight changes, accepted current weights, or blocked evidence gaps.      |
+| AVL-007 | Output and schema quality              | Verify each analyzer emits enough structured evidence for users and agents to review the claim.                                                                                        | `complete` | Completed in `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`.   | Each analyzer family has an output-quality verdict and missing-field list.                               |
+| AVL-008 | Performance and budget behavior        | Check large-index behavior, `--full`, scan limits, git-history bounds, and graceful degradation.                                                                                       | `complete` | Completed in `docs/validation/2026-06-21-performance-budget-behavior-result.md`.          | Budget behavior is documented with any timeout, cap, or misleading-empty-output issues.                  |
+| AVL-009 | Suppression lifecycle                  | Evaluate whether suppressions are stale, justified, expired, or useful as detector precision feedback.                                                                                 | `complete` | Completed in `docs/validation/2026-06-21-suppression-lifecycle-result.md`.                | Suppression categories have counts, stale examples, and trust-weight recommendations.                    |
+| AVL-010 | Cross-language capability boundaries   | Establish what works for TypeScript, React, Vue, Rust, and any unsupported language surfaces.                                                                                          | `complete` | Completed in `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`. | Capability notes distinguish "no findings" from "not supported by current evidence."                     |
+| AVL-011 | Agent repair outcomes                  | Test whether acting on analyzer findings produces better code rather than churn or misplaced abstraction.                                                                              | `complete` | Completed in `docs/validation/2026-06-21-agent-repair-outcomes-result.md`.                | Each action tier has at least one reviewed repair outcome or an explicit reason it cannot be tested yet. |
+| AVL-012 | Locality analyzer validation           | Validate the proposed `locality-candidates` report and `scip-locality-review` skill workflow before implementation.                                                                    | `complete` | Completed in `docs/validation/2026-06-21-locality-analyzer-validation-result.md`.         | The locality design has TP/FP/FN-style examples and a go/no-go recommendation for implementation.        |
+| AVL-013 | Config and declared-coupling freshness | Check whether `.scipquery.json` declared couplings and suppressions still point at current paths.                                                                                      | `complete` | Completed in `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`.   | Stale config paths are fixed, removed, or documented as intentionally retained.                          |
+| AVL-014 | Public command surface coverage        | Ensure every public analyzer command is present in the inventory, protocol, and ledger.                                                                                                | `complete` | Completed in `docs/validation/2026-06-21-public-command-surface-coverage-result.md`.      | A coverage checklist shows no missing analyzer or marks non-analyzer support commands separately.        |
+
+## Public Command Coverage Checklist
+
+The canonical source is `src/runtime/commands/query-command-specs.ts:10-73`, where `queryCommandOrder` lists the public query command surface.
+
+- Core and navigation support: `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, `slice`
+- Direct cleanup and deletion analyzers: `dead`, `isolated`, `unused-imports`, `cleanup-plan`, `unused-params`, `passthrough-candidates`, `redundant-reexports`
+- Similarity, reuse, extraction, and locality analyzers: `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `recent-duplicates`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `stale-abstractions`, `doc-drift`, `drift`, `convergence`
+- Frontend analyzers: `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`
+- Graph, risk, and complexity analyzers: `hotspots`, `fan-in`, `fan-out`, `coupling`, `cycles`, `bottlenecks`, `deep-chains`, `complexity-hotspots`, `complexity`
+- Diff, impact, and planning analyzers: `affected`, `change-surface`, `co-change`, `diff-gate`, `incomplete-migration`, `plan-context`
+- Meta and action commands: `self-audit`, `cleanup-apply`
+
+## Completed Run Batches
+
+The completed effort used this order so early runs created useful evidence for later calibration work.
+
+Current pilot:
+
+- Plan: `docs/plans/2026-06-21-analyzer-validation-pilot.md`
+- Summary: `docs/validation/2026-06-21-analyzer-validation-pilot.md`
+- Verdict review: `docs/validation/2026-06-21-analyzer-verdict-review.md`
+- Calibration memo: `docs/validation/2026-06-21-analyzer-calibration-memo.md`
+- Precision implementation plan: `docs/plans/2026-06-21-analyzer-precision-implementation.md`
+- Precision implementation result: `docs/validation/2026-06-21-analyzer-precision-implementation-result.md`
+- Stable_Management second confirmation: `docs/validation/2026-06-21-stable-management-second-confirmation.md`
+- Echo tier refinement result: `docs/validation/2026-06-21-echo-tier-refinement-result.md`
+- Wrapper boundary evidence result: `docs/validation/2026-06-21-wrapper-boundary-evidence-result.md`
+- Passthrough boundary evidence result: `docs/validation/2026-06-22-passthrough-boundary-evidence-result.md`
+- Passthrough public-facade caveats result: `docs/validation/2026-06-22-passthrough-public-facade-caveats-result.md`
+- Public surface caveats result: `docs/validation/2026-06-22-public-surface-caveats-result.md`
+- Doc cited-claim metadata result: `docs/validation/2026-06-22-doc-cited-claim-metadata-result.md`
+- Root-cause grouping result: `docs/validation/2026-06-22-root-cause-grouping-result.md`
+- Co-change partner labels result: `docs/validation/2026-06-22-co-change-partner-labels-result.md`
+- Incomplete migration containment result: `docs/validation/2026-06-22-incomplete-migration-containment-result.md`
+- Co-change recency and broad-sweep context result: `docs/validation/2026-06-22-co-change-recency-sweep-result.md`
+- Doc drift historical intent result: `docs/validation/2026-06-22-doc-drift-historical-intent-result.md`
+- Framework entry caveats result: `docs/validation/2026-06-22-framework-entry-caveats-result.md`
+- Incomplete migration scope hints result: `docs/validation/2026-06-22-incomplete-migration-scope-hints-result.md`
+- Doc reference citation parser result: `docs/validation/2026-06-22-doc-reference-citation-parser-result.md`
+- Co-change subject context result: `docs/validation/2026-06-22-co-change-subject-context-result.md`
+- Second-corpus score-weight confirmation result: `docs/validation/2026-06-22-second-corpus-score-weight-confirmation-result.md`
+- Passthrough exported-facade second-corpus result: `docs/validation/2026-06-22-passthrough-exported-facade-second-corpus-result.md`
+- Incomplete migration second-corpus scope result: `docs/validation/2026-06-22-incomplete-migration-second-corpus-scope-result.md`
+- Doc parser second-corpus validation result: `docs/validation/2026-06-22-doc-parser-second-corpus-validation-result.md`
+- Validation ledger closeout result: `docs/validation/2026-06-22-validation-ledger-closeout-result.md`
+- Global install cross-verification result: `docs/validation/2026-06-22-global-install-cross-verification-result.md`
+- Stable Management locality suggested-home review: `docs/validation/2026-06-22-stable-management-locality-suggested-home-review.md`
+- Locality positive suggested-home result: `docs/validation/2026-06-22-locality-positive-suggested-home-result.md`
+- Stable_Management wrapper confirmation: `docs/validation/2026-06-21-stable-management-wrapper-boundary-confirmation.md`
+- Vue pressure-kind output result: `docs/validation/2026-06-21-vue-pressure-kind-output-result.md`
+- Similarity evidence split result: `docs/validation/2026-06-21-similarity-evidence-split-result.md`
+- Doc citation-kind output result: `docs/validation/2026-06-21-doc-citation-kind-output-result.md`
+- Baseline metadata inheritance result: `docs/validation/2026-06-21-baseline-metadata-inheritance-result.md`
+- Second-repo confirmation: `docs/validation/2026-06-21-second-repo-confirmation.md`
+- Rust wrapper and React pressure review: `docs/validation/2026-06-21-rust-wrapper-react-pressure-review.md`
+- React pressure-kind output result: `docs/validation/2026-06-21-react-pressure-kind-output-result.md`
+- Rust wrapper boundary vocabulary result: `docs/validation/2026-06-21-rust-wrapper-boundary-vocabulary-result.md`
+- Frontend behavior evidence classification result: `docs/validation/2026-06-21-frontend-behavior-evidence-classification-result.md`
+- Extract candidate evidence classification result: `docs/validation/2026-06-21-extract-candidate-evidence-classification-result.md`
+- Stale abstraction action-tier result: `docs/validation/2026-06-21-stale-abstraction-action-tier-result.md`
+- Health score action-tier counts result: `docs/validation/2026-06-21-health-score-action-tier-counts-result.md`
+- Graph-risk family result: `docs/validation/2026-06-21-graph-risk-family-result.md`
+- Config declared-coupling freshness result: `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`
+- Suppression lifecycle result: `docs/validation/2026-06-21-suppression-lifecycle-result.md`
+- Support analysis accuracy result: `docs/validation/2026-06-21-support-analysis-accuracy-result.md`
+- Cross-language capability boundaries result: `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`
+- Public command surface coverage result: `docs/validation/2026-06-21-public-command-surface-coverage-result.md`
+- Analyzer implementation parity result: `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`
+- Performance and budget behavior result: `docs/validation/2026-06-21-performance-budget-behavior-result.md`
+- Agent repair outcomes result: `docs/validation/2026-06-21-agent-repair-outcomes-result.md`
+- Locality analyzer validation result: `docs/validation/2026-06-21-locality-analyzer-validation-result.md`
+- Direct small analyzer verdicts result: `docs/validation/2026-06-21-direct-small-analyzer-verdicts-result.md`
+- Direct remaining verdicts result: `docs/validation/2026-06-21-direct-remaining-verdicts-result.md`
+- Direct deletion-family closure result: `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`
+- Contextual signal closure result: `docs/validation/2026-06-21-contextual-signal-closure-result.md`
+- Score calibration finalization result: `docs/validation/2026-06-21-score-calibration-finalization-result.md`
+- Output/schema quality finalization result: `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`
+- Raw output root: `/tmp/scip-query-validation/2026-06-21-pilot`
+
+### Batch 1: Corpus Baseline
+
+- Repositories: `scip-query`, `Stable_Management`, `Vega_2.0`, `SynthRunnerRust`.
+- Commands:
+  - `git rev-parse HEAD`
+  - `scip-query reindex`
+  - `scip-query health --full --json`
+  - `scip-query diff-gate --json`
+  - `scip-query capability-matrix`
+- Outputs:
+  - Raw JSON outside the repo unless intentionally promoted.
+  - Plain text output when a command does not expose `--json`.
+  - Summary in `docs/validation/YYYY-MM-DD-corpus-baseline.md`.
+
+### Batch 2: Direct Repair Families
+
+- Commands:
+  - `scip-query cleanup-plan --json`
+  - `scip-query dead --only-dead --json`
+  - `scip-query isolated --json`
+  - `scip-query unused-params --json`
+  - `scip-query redundant-reexports`
+  - `scip-query passthrough-candidates --json`
+  - `scip-query cycles --json`
+  - `scip-query doc-drift --json`
+- Review:
+  - Top 10 findings, 5 threshold-edge findings, and 5 false-negative probes where possible.
+  - Classify as `tp`, `fp`, `accepted_design`, `needs_judgment`, or `fn`.
+
+### Batch 3: Contextual Signal Families
+
+- Commands:
+  - `scip-query similar --json`
+  - `scip-query similar-files --json`
+  - `scip-query similar-chains --json`
+  - `scip-query similar-signatures --json`
+  - `scip-query recent-duplicates --json`
+  - `scip-query extract-candidates --json`
+  - `scip-query wrapper-candidates --json`
+  - `scip-query stale-abstractions --json`
+  - `scip-query co-change --json`
+  - `scip-query bottlenecks --json`
+  - `scip-query coupling --json`
+  - `scip-query deep-chains --json`
+  - `scip-query drift --json`
+- Review:
+  - Separate "true signal" from "direct repair."
+  - Record what product or architecture judgment was needed.
+
+### Batch 4: Frontend-Specific Families
+
+- React corpus: `Vega_2.0`.
+- Vue corpus: `Stable_Management`.
+- Commands:
+  - `scip-query react-component-duplicates --full --json`
+  - `scip-query react-hook-candidates --full --json`
+  - `scip-query react-large-component-pressure --full --json`
+  - `scip-query vue-component-duplicates --full --json`
+  - `scip-query vue-composable-candidates --full --json`
+  - `scip-query vue-large-view-pressure --full --json`
+- Review:
+  - Validate whether findings imply component extraction, hook/composable extraction, locality repair, or only investigation.
+
+### Batch 5: Evidence Providers and Agent Outcomes
+
+- Commands:
+  - `scip-query plan-context <target> --full --json`
+  - `scip-query change-surface <file> --json`
+  - `scip-query affected <symbol> --json`
+  - `scip-query refs <symbol> --json`
+  - `scip-query imports <file> --json`
+  - `scip-query rdeps <file>`
+  - `scip-query self-audit --samples 100 --json`
+- Review:
+  - Confirm reference accuracy.
+  - Pick a small number of analyzer findings and record whether an agent could repair them cleanly.
+
+## Verdict Record Template
+
+```json
+{
+  "ledgerId": "AVL-002",
+  "repo": "scip-query",
+  "revision": "COMMIT",
+  "command": "dead --only-dead --json",
+  "findingId": "stable id or pasted summary",
+  "location": "src/path/file.ts:10",
+  "verdict": "tp | fp | accepted_design | needs_judgment | fn",
+  "actionTier": "direct | signal | support",
+  "evidence": ["facts that support the verdict"],
+  "counterevidence": ["facts that weaken the analyzer claim"],
+  "repairOutcome": "not_attempted | improved | churn | bad_abstraction | blocked",
+  "precisionAction": "none | parser | root_detection | threshold | score_weight | output_schema | docs | tests",
+  "notes": "short reviewer note"
+}
+```
+
+## Update Rules
+
+When a run batch completes:
+
+1. Update the relevant `AVL-*` rows from `ready` or `running` to `complete`, `blocked`, or `deferred`.
+2. Add a dated summary under `docs/validation/` when the result is worth retaining.
+3. Keep raw JSON out of the repo unless it is small and useful as a fixture.
+4. Turn precision actions into implementation issues or a concrete implementation plan.
+5. If a finding changes an action tier or score-weight recommendation, update `docs/analyzer-inventory.md` and `docs/analyzer-validation-protocol.md`.
+
+## Initial End-to-End Slice
+
+The first concrete run was intentionally narrow:
+
+1. Run Batch 1 on `scip-query` and `Stable_Management`.
+2. Run Batch 2 only for `dead`, `unused-params`, `passthrough-candidates`, and `doc-drift`.
+3. Run Batch 3 only for `similar`, `wrapper-candidates`, and `co-change`.
+4. Run Batch 4 only for Vue on `Stable_Management`.
+5. Record at least 30 reviewed verdicts.
+6. Produce one calibration memo that says whether the current direct/signal/support split still holds.
+
+That slice tested the ledger, the protocol, the review burden, and the score model before the later completion passes covered the remaining analyzer families.

package/docs/analyzer-validation-protocol.md

@@ -0,0 +1,192 @@
+# Analyzer Validation Protocol
+
+This document answers the part of the analyzer review that the inventory does not: how to test whether each analyzer is right across real codebases, how to label false positives and false negatives, and how to turn those labels into programmatic precision work.
+
+The companion inventory is `docs/analyzer-inventory.md`. The running work tracker is `docs/analyzer-validation-ledger.md`. The companion placement design is `docs/locality-analyzer-design.md`.
+
+## Core Concepts
+
+A validation corpus is a deliberately chosen set of real repositories, revisions, and stack shapes used to test analyzer claims against maintained code. It is not just a pile of projects; its essential job is to expose each analyzer to the kinds of source layouts, framework idioms, build boundaries, and historical changes that determine whether the analyzer's claim would matter to a maintainer.
+
+An analyzer verdict is a human-reviewed classification of one analyzer output or one known missed case. It ties the tool's structured claim back to source files, references, git history, and product structure so the claim can be counted as true, false, accepted-by-design, or still undecidable.
+
+A true positive is an analyzer claim where the reported code location really does have the maintenance problem the analyzer names, and the next reasonable maintainer action matches the analyzer's suggested direction.
+
+A false positive is an analyzer claim where the reported evidence exists but the inspected code shows that no repair is warranted. The usual cause is that the analyzer noticed a real structural pattern but missed ownership, framework convention, product meaning, or intentional API design.
+
+A false negative is an existing maintenance problem that the analyzer's stated scope should have reported but did not. It matters more than an empty report because it shows a missing detector feature, missing language support, skipped source unit, or threshold that is too narrow.
+
+An accepted design is a reported pattern that is real but intentionally kept. It should not be counted as a bug in the codebase; it is feedback that the analyzer needs either suppression support, a lower score weight, or a better explanation field.
+
+Programmatic precision work is a code change to the analyzer, its evidence model, or its score model that makes future reports closer to maintainer judgment without hard-coding one repository. It is different from tuning a threshold until one known example disappears.
+
+## Validation Corpus
+
+The first corpus should use local repositories that are already available and large enough to stress the current analyzer families.
+
+| Repository                                              | Stack shape                                                          | Source evidence seen locally         | Analyzer coverage                                                                        |
+| ------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `/Users/aydansalois/Documents/GitHub/scip-query`        | TypeScript CLI and analysis library                                  | 290 `.ts`, 103 `.md`                 | Core graph, cleanup, health, docs, diff gate, score behavior                             |
+| `/Users/aydansalois/Documents/GitHub/Stable_Management` | npm workspaces with Vue frontend, TypeScript backend, shared package | 1,168 `.ts`, 409 `.vue`, 380 `.md`   | Vue analyzers, co-change, cross-workspace coupling, docs, large-index budget             |
+| `/Users/aydansalois/Documents/GitHub/Vega_2.0`          | TypeScript monorepo with React web app, API app, shared packages     | 1,567 `.ts`, 672 `.tsx`, 1,163 `.md` | React analyzers, monorepo locality, diff gate, shared-package coupling                   |
+| `/Users/aydansalois/Documents/GitHub/SynthRunnerRust`   | Rust project                                                         | 27 `.rs`, 36 `.md`                   | SCIP graph smoke coverage, non-TypeScript command behavior, docs and git-history signals |
+
+The current best field-test evidence is Stable_Management. A previous run found 1,167 indexed files, 93k symbols, 491 commits analyzed, useful co-change clusters, a bounded `health` score of 91, and 155 baseline findings. It also reported an honest negative: candidate-style findings did not currently predict fix commits well, with validation ratios of 0.6x on Stable_Management and 0.36x on scip-query.
+
+That negative is part of the protocol. It means candidate analyzers can be useful without being predictive enough to deserve the same score weight as direct repair analyzers.
+
+## Run Protocol
+
+For each repository, record the exact revision first.
+
+```sh
+git -C /path/to/repo rev-parse HEAD
+```
+
+Then index and capture the broad report.
+
+```sh
+cd /path/to/repo
+scip-query reindex
+scip-query health --full --json > /tmp/scip-query-validation/REPO/health.json
+scip-query diff-gate --json > /tmp/scip-query-validation/REPO/diff-gate.json
+```
+
+For each analyzer under review, capture three samples when possible.
+
+| Sample               | What to inspect                                        | Why it exists                                                   |
+| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
+| Top findings         | 10 highest-ranked findings                             | Tests whether ranking puts obvious work first                   |
+| Threshold edge       | 5 findings near the default threshold or last page     | Tests whether cutoffs are calibrated                            |
+| Expected-miss probes | 5 known cases from code search, history, or user notes | Tests false negatives instead of only checking emitted findings |
+
+Every sampled finding should be reviewed with the same evidence bundle:
+
+```sh
+scip-query plan-context <symbol-or-file> --full --json
+scip-query refs <symbol> --json
+scip-query code <symbol> --json
+git log --oneline -- <file>
+```
+
+For file-level or history-level analyzers, substitute the file tools:
+
+```sh
+scip-query change-surface <file> --full --json
+scip-query imports <file> --json
+scip-query deps <file> --json
+scip-query rdeps <file> --json
+scip-query co-change <file> --full --json
+```
+
+The validation record should be small enough to write for every sampled result.
+
+```json
+{
+  "repo": "Stable_Management",
+  "revision": "COMMIT",
+  "command": "vue-composable-candidates",
+  "findingId": "stable identifier or pasted summary",
+  "location": "frontend/src/views/Example.vue",
+  "verdict": "tp | fp | accepted_design | needs_judgment | fn",
+  "actionTier": "direct | signal | support",
+  "evidence": ["source/reference/history facts that make the verdict reproducible"],
+  "counterevidence": ["facts that weaken the analyzer claim"],
+  "precisionWork": "threshold, parser, evidence field, skip rule, score weight, wording, or none"
+}
+```
+
+Do not accept a precision change unless it survives at least one second repository or one focused fixture. That is the guard against fitting the analyzer to whichever repo annoyed us today.
+
+## Analyzer Matrix
+
+| Analyzer or family                                                                | True-positive standard                                                                                                                                                                                                                                                   | Likely false positives                                                                                                                                                                                                                   | False-negative probes                                                                                   | Programmatic precision work                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cleanup-plan`                                                                    | The batch deletes graph-unreferenced production code and `--verify` keeps the checker green.                                                                                                                                                                             | Entry points, reflection, generated exports, CLI/plugin surfaces, unrecognized framework-discovered files.                                                                                                                               | Search for manually deleted dead code in recent history and compare with prior report.                  | Better root-surface detection, package export reading, framework-discovered route/page exports, and verification summaries are implemented; generated/reflection root coverage remains a future caveat.                                                                                        |
+| `dead`, `new-dead`, `isolated`                                                    | The symbol has no real production consumers and is not an entry surface.                                                                                                                                                                                                 | File-private helpers, test-only helpers, exported APIs consumed outside the index, generated or reflection entry points.                                                                                                                 | Known orphan functions found by `rg`, deleted symbols in git history, test fixtures with dynamic usage. | Separate "dead" from "file-internal", package/export metadata, and framework-discovered route/page roots are implemented; generated/reflection roots and external consumer evidence remain future caveats.                                                                                     |
+| `unused-params`                                                                   | A trailing simple parameter is unused in all relevant implementations and can be removed without API breakage.                                                                                                                                                           | Interface conformance, callback arity, overload compatibility, framework signatures, future public API shape.                                                                                                                            | Search for underscore-less trailing params in changed files and compare with command output.            | Type-aware override/interface checks, callback convention allowlists, public API guards.                                                                                                                                                                                                       |
+| `unused-imports`, `drift` unused-import findings                                  | The imported binding is never referenced in the file's executable or type surface.                                                                                                                                                                                       | Type-only imports hidden by parser limits, macro usage, framework compiler usage, generated symbols.                                                                                                                                     | Compare against TypeScript/ESLint unused import diagnostics where available.                            | Compiler-oracle comparison, macro/framework allowlists, unused-import evidence in output.                                                                                                                                                                                                      |
+| `redundant-reexports`                                                             | A private barrel re-export has zero barrel consumers, zero direct consumers, and emits `actionTier: "direct"`.                                                                                                                                                           | Public package API, external consumers outside the repo, documentation examples, generated SDK boundaries.                                                                                                                               | Inspect barrels with no internal imports and compare against package exports/docs.                      | Package `exports`, directory index entrypoints, nested package manifests, action tier, surface evidence, and recommendations are now emitted; generated-surface caveats remain future precision work.                                                                                          |
+| `passthrough-candidates`                                                          | The function only forwards arguments to one callee, adds no stable name, policy, boundary, public-facade role, or adaptation, and the emitted `actionTier` is `direct`.                                                                                                  | Domain vocabulary wrappers, API adapters, test seams, telemetry/auth wrappers, public facade names, package-public exports, service/provider boundaries, capability modules, access-policy forwarding.                                   | Search for tiny wrappers around known callees that command misses.                                      | Action tier, runtime-boundary evidence, separate public-facade evidence, recommendation, and health score discount are now emitted; clean Vega second-corpus confirmation kept signal/direct counts stable.                                                                                    |
+| `wrapper-candidates`                                                              | A small one-consumer wrapper adds no useful concept and can be inlined.                                                                                                                                                                                                  | Boundary naming, dependency inversion, future API shape, test isolation, schema/contract modules.                                                                                                                                        | Inspect one-consumer helpers in high-churn files.                                                       | Consumer-kind evidence, caller fan-in smoothing, naming/domain hints, suppression-informed weight reduction.                                                                                                                                                                                   |
+| `stale-abstractions`                                                              | A type/class/helper has zero consumers or one accidental consumer and no boundary role, and the emitted staleness kind/action tier correctly separates unused cleanup from one-consumer ownership review.                                                                | Contract types, generated schema types, nominal domain names, low-consumer but intentionally public API.                                                                                                                                 | Search for old low-consumer files, compare with command and suppressions.                               | Action tier, staleness kind, and recommendation are now emitted; one-consumer rows stay contextual/support in score calibration unless stronger public-surface evidence changes the claim.                                                                                                     |
+| `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence` | Two units share enough behavior or dependency shape that unification would reduce real duplication.                                                                                                                                                                      | Coincidental same framework plumbing, shared type shape but different concepts, generated code, parallel product flows, or cross-language structural overlap without recognized semantic tokens.                                         | Manually inspect known copy-paste pairs, recent duplicated commits, and repeated command handlers.      | Domain-token reporting, framework-token downweighting, neutral `structural-overlap` evidence, changed-code directionality, grouped evidence rather than scalar similarity alone.                                                                                                               |
+| `recent-duplicates`, diff-gate `echo`                                             | New or recently changed code re-implements older code with the same behavior.                                                                                                                                                                                            | Boilerplate repeated by framework convention, tests, intentionally forked product variants.                                                                                                                                              | Scan recent commits for "copy", "duplicate", "refactor", or similar edits not reported.                 | Root-cause groups now separate review items from pairwise evidence; age windows, test/generated filters, behavior-token evidence, and established-owner links remain future precision candidates.                                                                                              |
+| `extract-candidates`                                                              | A large callable contains a cohesive callee cluster, and the emitted extraction kind/recommendation correctly frames it as workflow orchestration, a broad helper cluster, or a cohesive helper cluster.                                                                 | Incidental call clustering, readable local sequence, algorithm steps that should stay together, or helper groups without a stable concept name.                                                                                          | Inspect large functions with obvious sections and compare with report.                                  | Extraction kind, action tier, reasons, and recommendation are now emitted; locality and score calibration are recorded, while placement decisions remain report-only through the locality workflow.                                                                                            |
+| `incomplete-migration`                                                            | A new helper is used at some matching sites while other equivalent sites still contain the old inline pattern, and the old site passes both helper-containment and site-coverage checks.                                                                                 | Intentional partial rollout, tests documenting old behavior, helper only valid for one subtype, or broad orchestration sites where the helper pattern is only a small fragment.                                                          | Search diffs with new helpers and repeated old call clusters.                                           | Two-sided containment, helper shape, site coverage, broad-site regression coverage, migration-scope hints, and second-corpus same-scope validation are now recorded.                                                                                                                           |
+| `react-component-duplicates`, `vue-component-duplicates`                          | Two components repeat substantial render structure where a component extraction would preserve product meaning.                                                                                                                                                          | Design-system repetition, route-specific layouts, data-table boilerplate, static labels inflating similarity.                                                                                                                            | Inspect similar screenshots/templates not reported, especially after large component splits.            | Framework-token downweighting, static text handling, shared component/import evidence, route/domain context.                                                                                                                                                                                   |
+| `react-hook-candidates`, `vue-composable-candidates`                              | Components repeat state, effects, lifecycle, request, or handler behavior that can live in a hook/composable, and the row's evidence class points to domain or mixed behavior rather than only generic workflow.                                                         | Generic useState/useEffect/useQuery plumbing, unrelated screens using the same framework primitives, or existing shared abstractions that already own the workflow.                                                                      | Search for repeated custom hook/composable calls and copied handler names.                              | Evidence class and action tier are now emitted; field validation and score calibration are recorded, and new non-empty corpora can extend calibration later.                                                                                                                                   |
+| `react-large-component-pressure`, `vue-large-view-pressure`                       | A component/view is large enough that unrelated reasons to change are forced through one file.                                                                                                                                                                           | Generated views, story/demo files, intentionally monolithic route shells, style-heavy one-off pages.                                                                                                                                     | Search largest React/Vue files and compare with command output.                                         | Pressure-kind/context recommendations are validated; future locality recommendations remain report-only until consumer coverage improves.                                                                                                                                                      |
+| `complexity`, `complexity-hotspots`                                               | A symbol or file has enough branching, LOC, fan-in, or fan-out that local reasoning and change risk are objectively high.                                                                                                                                                | Central orchestration code, parsers, reducers, generated code, tables expressed as code.                                                                                                                                                 | Compare against high-branch files from code search and known bug-fix hotspots.                          | Keep cyclomatic and graph-pressure scores separate, report branch evidence, combine with churn/fix density.                                                                                                                                                                                    |
+| `cycles`                                                                          | A real dependency cycle crosses source files in a way that makes layering or change order harder.                                                                                                                                                                        | Barrel cycles, test cycles, module-hierarchy cycles, framework registration loops.                                                                                                                                                       | Compare file dependency SCCs with `deps`/`rdeps`, seed fixture cycles.                                  | Keep existing cycle-kind split, score only real cycles, improve barrel/test classification.                                                                                                                                                                                                    |
+| `co-change`, diff-gate `co-change-partner`                                        | Files repeatedly change together without a dependency edge, showing hidden coordination work; partner class, commit scope, recency, and commit-subject context now distinguish focused current pairs from broad, stale, unlabeled, fix-labeled, or docs-labeled history. | Same feature touched by broad commits, stale coupling that history no longer predicts, local commit subjects that do not reflect true tracker labels, or a partner class that is real but does not imply this diff needs the other side. | Inspect known schema/client, env/config, doc/code pairs and changed partner misses.                     | Partner-class evidence, declared-coupling suggestions, broad-sweep context, recency context, local subject labels, issue refs, external-label-unavailable status, and health score weighting are now emitted; continue only with future metadata-provider validation for true issue/PR labels. |
+| `doc-drift`, diff-gate `doc-reference`                                            | A doc cites code that moved, broke, or kept changing after the doc claim stopped changing, and the cited claim or doc intent indicates whether this is current guidance, support evidence, or a broken reference.                                                        | Exploratory docs, historical notes, configuration examples, docs intentionally describing old behavior.                                                                                                                                  | Search docs with path references and compare broken/stale outputs.                                      | Cited-claim metadata, citation-kind output, co-change-only historical-note intent, Markdown-local citation parsing, and second-corpus parser validation are now recorded.                                                                                                                      |
+| `drift` layer and pattern findings                                                | Imports violate an explicit or strongly inferred local architecture rule, and the row's action tier correctly separates explicit policy from inferred signal.                                                                                                            | Inferred rules from too few siblings, migration states, intentionally exceptional bridge files.                                                                                                                                          | Inspect known layer boundaries and sibling directories with unique imports.                             | Action tier, policy basis, evidence reasons, and recommendation are now emitted; inferred drift stays low-score/support unless stronger sibling support is available.                                                                                                                          |
+| `hotspots`, `fan-in`, `fan-out`, `coupling`, `bottlenecks`, `deep-chains`         | The graph facts correctly identify centrality, dependency breadth, shared symbols, hubs, or long chains, while output frames them as contextual signal or support rather than direct repair.                                                                             | These are not smells by themselves; false positives are mostly product mistakes when score treats them as repair demands.                                                                                                                | Compare with raw SCIP graph and known central modules.                                                  | Bottlenecks, coupling, and deep chains now emit action-tier metadata; deep chains de-duplicate strict suffix rows. Keep graph risk contextual except when combined with churn, cycles, or direct findings.                                                                                     |
+| `affected`, `change-surface`, `plan-context`                                      | The tool names real consumers, blast radius, references, calls, history, and risks for a target.                                                                                                                                                                         | Missing index data, generated code, dynamic imports, language unsupported by current index.                                                                                                                                              | Pick symbols with known callers and compare against `rg` plus compiler refs when available.             | Index capability reporting, language-specific fallbacks, clearer "missing evidence" sections.                                                                                                                                                                                                  |
+| `self-audit`                                                                      | Cheap evidence paths match the TypeScript compiler oracle on sampled symbols.                                                                                                                                                                                            | Sampling bias, non-TypeScript code, compiler config mismatch.                                                                                                                                                                            | Repeat with scopes from different packages and compare disagreement classes.                            | Stratified sampling by package/file kind, persistent disagreement fixtures.                                                                                                                                                                                                                    |
+| `health`, `health-phase`, `diff-gate` composite reports                           | The composite report explains its deductions and gates new direct findings without hiding signal pressure.                                                                                                                                                               | Treating contextual signal as direct debt, score staying perfect while signal backlog grows, baseline churn from history-derived findings.                                                                                               | Compare scalar changes against reviewed finding labels and suppression counts.                          | Action-tier identities, direct/signal score separation, suppression trust adjustments, and hidden-coupling score-count correction are recorded.                                                                                                                                                |
+
+The first TypeScript support-analysis review found accurate source-grounded output for `validateProjectConfig()` and fixed `status`/`doctor` config diagnostic parity. The Rust cross-language review confirmed that graph/source/checker-backed analyzers work on Rust, while TypeScript semantic self-audit is explicitly unavailable and frontend analyzers correctly return stack-specific empty results.
+
+`cleanup-apply` is not an analyzer. It is an action command that should be validated through the `cleanup-plan --verify` path and normal project checks.
+
+Navigation commands such as `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, and `slice` should be tested as evidence providers. Their success standard is referential accuracy, not whether they find a smell.
+
+## False-Negative Search
+
+False negatives need active hunting because normal analyzer output cannot show what it missed.
+
+Use these probes on each corpus:
+
+1. Search for large units:
+
+   ```sh
+   rg --files | rg '\.(ts|tsx|vue|rs)$' | xargs wc -l | sort -nr | head -30
+   ```
+
+2. Search for repeated names and local copy-paste clues:
+
+   ```sh
+   rg -n "TODO|copy|duplicate|refactor|extract|cleanup|unused|dead|stale"
+   ```
+
+3. Search history for repairs that should have been predicted:
+
+   ```sh
+   git log --oneline --grep='fix\\|bug\\|cleanup\\|refactor\\|remove\\|dead'
+   ```
+
+4. Inspect suppressions as precision labels:
+
+   ```sh
+   rg -n "scip-query: ignore-" src tests docs
+   ```
+
+5. For frontend repos, inspect large component split candidates by directory:
+
+   ```sh
+   rg --files | rg '\.(tsx|vue)$' | xargs wc -l | sort -nr | head -50
+   ```
+
+The expected result of this phase is not "all analyzers are accurate." The expected result is a ranked list of detector improvements with evidence: parser gaps first, public-surface mistakes second, framework convention mistakes third, score-weight mistakes fourth.
+
+## Score Implications
+
+The score model should encode reviewed action implication.
+
+Direct findings are code or docs locations where the analyzer normally identifies a local repair. They should carry heavier deductions and should be eligible for diff-gate blocking.
+
+Contextual signals are real patterns whose repair depends on product or architecture judgment. They should accumulate as backlog pressure, but a single signal should not be scored like dead code.
+
+Support analyses are evidence maps. They should inform planning and other detectors, not reduce health by themselves.
+
+Suppression counts and `self-audit` disagreement rates should modify analyzer trust. A detector with many accepted suppressions or poor compiler-oracle disagreement should still report, but its score weight should be lower until the false-positive cause is understood. Structured suppressions must keep a reason, an identity, a live expiration when temporary, and any file scope must still point at a current file.
+
+## Residual Future Work
+
+No active validation ledger slice remains. Future production steps should stay small and falsifiable:
+
+1. Keep true co-change issue/PR labels blocked until a repository metadata provider is available; local commit-subject context is implemented.
+2. Keep locality report-only until exact consumer coverage and repair outcomes justify score integration.
+3. Keep `docs/analyzer-validation-ledger.md` current as each analyzer family receives a new implementation or corpus-confirmation result.

package/docs/assets/scip-query-logo-dark.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">scip-query</title>
+  <desc id="desc">A minimal scip-query wordmark with a bright blue underscore cursor for dark backgrounds.</desc>
+  <style>
+    .wordmark {
+      fill: #F8FAFC;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >scip-query</text>
+  <rect x="430" y="76" width="50" height="8" rx="4" fill="#60A5FA" />
+</svg>

package/docs/assets/scip-query-logo.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">scip-query</title>
+  <desc id="desc">A minimal scip-query wordmark with a blue underscore cursor.</desc>
+  <style>
+    .wordmark {
+      fill: #111827;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+    .cursor {
+      fill: #2563EB;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >scip-query</text>
+  <rect class="cursor" x="430" y="76" width="50" height="8" rx="4" />
+</svg>