scip-query 0.23.0 → 0.26.0

package/docs/PRODUCT_VISION.md

@@ -0,0 +1,135 @@
+# scip-query: exploration, planning, and code maintenance
+
+Status: product vision and removal audit, recorded on 2026-09-05. The workflows and acceptance requirements below are the implementation target, not a claim that the current product already meets them. The earlier simplification and Sol/medium pilot are completed work; this document supersedes their narrower product scope.
+
+## Purpose
+
+Give coding agents reliable evidence about existing code and their changes, so they can choose appropriate owners, reuse suitable implementations, preserve behavior, and remove unnecessary complexity.
+
+A module is a unit of code that implements an assigned responsibility through operations other code can use. Responsibility ownership is the assignment of control over a rule or resource to the code that enforces its valid use. For example, a reservation operation owns cancellation when all channels go through its eligibility checks and recorded writes.
+
+A code pattern is a recurring arrangement of responsibilities and interactions, such as entry points delegating policy and persistence to the same operation. Repeated syntax is evidence of similarity; it does not establish that two implementations express the same policy or should share an owner. A code smell is an observable arrangement suggesting a maintenance problem and requiring contextual review. A finding is a recorded observation identifying the exact code, the evidence, the applicable requirement or concern, and the limits of the conclusion.
+
+The product must work in two situations: first adoption in an unfamiliar repository, including a large repository; and continued use through exploration, a written plan, implementation, and review of the resulting diff. A diff is the set of source changes relative to an explicitly identified Git revision or snapshot.
+
+## First adoption: useful findings without prior setup work
+
+After preparing the supported source analysis, the tool must provide a short, useful set of findings without requiring a historical baseline, owner annotations, suppression records, or prior scip-query use. Initial indexing time and analysis coverage must be visible. Missing history or configuration must disable only the findings that depend on them.
+
+The initial report should identify exact sites and explain concerns such as:
+
+- Duplicated implementations, with both bodies and their material differences available.
+- Complex functions, showing the decisions or nesting that contribute to the measurement.
+- Circular imports, with the actual import path that closes the cycle and whether the edges are type-only or runtime imports where supported.
+- Possible mixed responsibilities, supported by separately used operations, distinct consumers, dependencies, or state effects. File length or a folder name alone cannot establish this.
+- Possible competing owners, supported by multiple live implementations or write paths controlling the same declared rule or resource. An absent owner declaration is missing context, not proof of defective architecture.
+- Dependency violations where rules are declared. Without declarations, show the observed relationships and possible concerns; do not invent an intended layer order.
+
+The first screen must contain actionable examples, not only category totals followed by a list of commands. Group findings about the same underlying code so one duplicated implementation does not appear as several independent problems. Large scans may be bounded, but must identify what was scanned, what was omitted, and how to recover the rest. Missing output is never a clean bill of health.
+
+## Established use: explore, plan, implement, review
+
+### Explore and write the plan
+
+The agent should establish the requested behavior, applicable existing implementations and patterns, the intended owner, affected consumers, dependency constraints, and relevant tests. The tool should expose competing implementations and exceptions rather than choosing an authority by naming, apparent recency, or result order.
+
+The written plan records the intended change, exact affected code, opportunities for reuse, behavior and state effects to preserve, planned removals, required validation, and unresolved assumptions. This is an agent-authored decision backed by evidence, not a plan inferred automatically from similarity scores. Keep plans in the repository's existing planning convention; do not introduce a second persistent planning database.
+
+### Implement and review the actual diff
+
+After implementation, the skill must direct the agent to review the current diff before reporting completion or committing. Review must include newly created functions, new untracked source files, and new functions added to old files, as well as modified and deleted code. It must identify the comparison revision, current source state, index freshness, and unsupported analysis.
+
+The review should report:
+
+1. The changed and newly created code units, including changes the index could not attribute.
+2. Affected callers, consumers, and relevant dependency changes.
+3. Per-function complexity before and after the change, or an explicit reason a comparison is unavailable. Splits, merges, deletions, and ambiguous matches must not be forced into misleading numeric deltas.
+4. New or increased duplication against existing repository code, including another function in the same file. An unrelated duplicate elsewhere must not crowd the changed code out of a bounded search.
+5. Changes in declared architecture violations and observed cycles, with actual edges.
+6. Applicable drift, obsolete wiring, unused-code, and test-quality findings, each with evidence and stated coverage.
+7. What improved, what worsened, what was already present, what was intentionally accepted, and what remains unknown.
+
+The agent then addresses supported problems, checks preserved behavior, and reruns review for the affected change. A lower metric alone does not establish improvement: moving complexity into poorly named helpers, weakening tests, or merging independent policies must not count as success.
+
+### Complexity and coverage
+
+Cyclomatic complexity is a measure of branching within a function; counted decision points determine the result under a stated language rule set. Cognitive complexity is a rule-based estimate of difficulty following execution, including additional cost for nested decisions. These measurements describe different properties and must not be silently substituted for one another. The current branch-based estimate remains labeled as an estimate until its supported syntax is independently validated.
+
+Test coverage records which parts of the implementation were exercised by a particular test run. The Change Risk Anti-Patterns (CRAP) index combines cyclomatic complexity with that coverage. CRAP requires coverage matched to the exact source revision, with the coverage kind and provider disclosed. Missing, stale, or unmappable coverage means CRAP is unavailable; it is neither zero coverage nor a good score. Coverage does not establish the quality of test assertions.
+
+Metric definitions: [Sonar's Cognitive Complexity specification](https://www.sonarsource.com/docs/CognitiveComplexity.pdf), [PHPUnit's CRAP and coverage definitions](https://docs.phpunit.de/en/12.5/code-coverage.html#software-metrics-for-code-coverage).
+
+## One evidence model, a small workflow surface
+
+Retain shared analysis providers and use a common finding record for first-use scans and change review. Each record needs a stable rule identity, exact source subjects, supporting observations, the concern or violated declaration, evidence strength, coverage and freshness, and a concrete inspection or validation step. A change review additionally identifies whether the finding is introduced, worsened, unchanged, resolved, or not comparable to the base. Accepted exceptions retain a reason and the code identity they apply to.
+
+Use existing `health` for repository maintenance, existing `context` plus exact exploration controls for planning, and one `review` surface for the diff. It assembles shared providers rather than grow a parallel detector engine. `diff-impact` already supplies changed-symbol and consumer evidence; it is a component of review, not the entire review.
+
+Keep `search`, `outline`, `evidence`, `inspect`, and `code` for exact investigation. Keep architecture declarations and their checks. Decide specialist command retention from a concrete unique need and a replacement path, not from a command-count target. Do not require agents to memorize a separate command for every smell.
+
+## Removal and consolidation audit
+
+The recommendations below precede implementation. A producer is the code that computes an observation; its public command and report are presentation surfaces. Consolidating a surface does not justify deleting a producer still used by another supported workflow.
+
+| Existing mechanism                                                                         | Recommendation                                                         | Evidence and replacement requirement                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| File-age-based Echo orientation in `recent-duplicates`                                     | Replace as the pre-commit duplication mechanism                        | `recentDuplicateFocusFiles` and `orientRecentDuplicate` classify recency from file-add history. A new function in an old file can be excluded. Use base/current function changes for review; keep historical recency only if it answers a separately justified question. |
+| Cross-file-only callable comparison in Echo                                                | Remove this restriction from diff duplication analysis                 | `callableDuplicateCandidates` sets `crossFileOnly: true`; a copied function in the same file must be detectable. Preserve intentional policy differences and report candidates rather than automatic deletion instructions.                                              |
+| General similarity results presented as instructions to delete the newer code              | Remove the unsupported conclusion                                      | Shared callees or tokens do not establish equivalent behavior or ownership. Show both implementations and the verification needed before reuse or consolidation.                                                                                                         |
+| Category-only health actions with effort/impact and recoverable-line estimates             | Replace as the main first-use report                                   | `HealthAction` carries aggregate descriptions and estimates without exact source subjects. Lead with evidence-backed findings; keep useful totals secondary. Do not infer effort or quality from potential line deletion.                                                |
+| Separate per-detector command discovery during every review                                | Consolidate into the scan/review workflow                              | The query command registry exposes many specialist surfaces. Preserve proven producers and detailed recovery paths while removing redundant public registrations only after their replacement is tested.                                                                 |
+| Generated commands and repeated exploration instructions across installed skills           | Compress; integrate the planning and review obligation                 | The primary skill duplicates command templates in its generated manual and relies on a second skill for investigation. Keep one concise normal workflow; retain specialist explanation material as references where useful.                                              |
+| Watcher startup as the only ordinary freshness procedure                                   | Replace with an explicit freshness contract                            | The pilot ran with background services disabled. Review must either analyze the current source or report exactly why it cannot; the skill must support the configured service mode without repeated failed startup attempts.                                             |
+| Broad source expansion during an exact range read                                          | Candidate for explicit opt-in rather than default                      | A requested `recentDuplicates` range automatically included its same-file helper closure. `inspect` already serves connected behavior; exact `code` reads should have a predictable scope. Audit compatibility and evidence completeness before changing it.             |
+| `twin-ab` generated test scaffolding                                                       | Candidate for retirement from the core product                         | CLI help describes a ready-to-fill Vitest scaffold, not executed behavioral evidence. Keep validation in the project's real test framework; inspect consumers before deletion.                                                                                           |
+| `self-audit`                                                                               | Keep as developer calibration, outside the normal user workflow        | Its purpose is checking the tool's own evidence paths against stronger analysis. Reliable detectors need this validation; it is not a repository cleanup finding.                                                                                                        |
+| `cleanup-plan --verify/--patch`                                                            | Audit separately; do not treat compiler success as cleanup correctness | It proposes deletion batches and runs a compiler in an isolated snapshot. That can support a deletion review but cannot establish preserved runtime behavior. Preserve useful dependency ordering while avoiding a competing general planning workflow.                  |
+| Optional formal-model tooling                                                              | Outside the default workflow; no wholesale deletion established yet    | The vision prioritizes first-use findings and everyday change review. Separate useful verification from its default installation and discoverability; inspect dependencies and actual users before proposing a removal.                                                  |
+| Complexity, duplication, drift, dependency, consumer, source, and supported flow providers | Retain and validate                                                    | These directly serve the stated product. Removing misleading packaging is not a reason to remove accurate underlying observations.                                                                                                                                       |
+
+Implementation anchors: [recent duplicate selection](../src/queries/cleanup/recent-duplicates.ts#L137), [callable comparison](../src/queries/cleanup/recent-duplicates.ts#L248), [file-age orientation](../src/queries/cleanup/recent-duplicates.ts#L410), [health result model](../src/queries/health/health-report.ts#L11), [command registry](../src/runtime/commands/query-command-specs.ts#L11), [primary skill](../skills/scip-query/SKILL.md), [pilot findings](benchmarks/2026-09-05-change-pilot.md).
+
+## Implementation order and completion tests
+
+1. Finish the removal audit and settle the small normal workflow. For each removal, identify its consumers, retained producer, replacement, contract tests, and migration note. Preserve the existing working-tree changes and earlier pilot artifacts.
+2. Repair freshness and missing-selector completeness before using semantic results for review. Test initial use, watcher-disabled operation, newly added source, edits between queries, and incomplete providers. Never label a result complete when a requested subject is unresolved.
+3. Establish the common finding record and concrete first-use report using validated existing detectors. Exercise a repository with no scip-query configuration or history, and a larger repository where bounded scans and duplicate grouping matter. Show actual cycle paths and duplicate sites; keep ownership concerns calibrated.
+4. Implement review of the actual diff by reusing impact analysis and the same finding providers. Test tracked, staged, unstaged, untracked, added, removed, and renamed code. Read the requested base correctly and disclose failures. A staged-only review, if supported, must analyze staged bytes rather than unrelated working-tree edits.
+5. Add validated per-function cognitive and cyclomatic measurements and a coverage adapter for CRAP. Start with explicit TypeScript/JavaScript support and disclose unsupported syntax/languages. Test nested functions, decision syntax, changed signatures, function splits, stale coverage, and source mappings. Extend language support only with verified implementations.
+6. Repair Echo through diff-based comparison. Required cases include copying into an old file, copying within one file, renaming identifiers, reusing common library calls without duplicating a responsibility, and deliberately equal but independently changing policies. Compare changed code against established code outside the changed-file set.
+7. Connect setup and the installed skill to exploration, an evidence-backed written plan, implementation, diff review, and behavior checks. Test generated instructions and execute the loop in disposable checkouts. Do not add a hidden committing or automatic refactoring step.
+8. Evaluate the whole workflow using the approved cheaper model, initially `gpt-5.6-sol` at `medium`. Preserve raw outcomes and failures. Expand beyond the tiny development fixture, then repeat matched runs after requirements are frozen.
+
+Completion requires a demonstrated first-use report, an executed planning/edit/review loop, meaningful detector and integration tests, documented omissions, compatible generated command/API records or explicit migrations, and a review of the resulting tool diff. A written vision or passing implementation tests alone is not completion of this product work.
+
+## Evaluate the actual purpose
+
+Measure three things separately: whether the tool identifies real problems without excessive false alarms; whether it helps an agent find existing implementations and make appropriate plans; and whether its review helps the agent repair defects in its own change while preserving behavior.
+
+Use both known defects and legitimate exceptions. Tasks must include problems that the agent is not explicitly told to look for, and checks independent of the detector's own score. Record correct findings, missed defects, false alarms, unnecessary edits, preserved behavior, maintenance effort on a later change, time, and token use. An import cycle detected correctly and a suggested module split justified poorly are different outcomes.
+
+The [first Sol/medium pilot](benchmarks/2026-09-05-change-pilot.md) remains a small development baseline. Its directed tasks and index-refresh limitation do not establish the value of first-use diagnosis, planning, or continuous diff review. Do not replace it silently, tune against a held-out evaluation set, or use a lower complexity score as the sole success criterion.
+
+## Implementation checkpoint: 2026-09-05
+
+The ordinary workflow now has a shared current-source TS/JS health scan and Git-based review, documented in [REVIEW.md](REVIEW.md). Review includes changed/new/deleted functions, explicit metric contributions, same-file and repository-wide body duplication candidates, relative import cycles, declared architecture edges, removed-file import residue, and measured coverage/CRAP with source-hash validation. It does not depend on watcher freshness. Source and supplied test-coverage omissions are visible and fail the optional completeness gate.
+
+Removed in this implementation: `twin-ab` and its public scaffold API; automatic local-call expansion from ordinary range reads; literal-erasing comparison in the older duplicate-body detector. The default health report now presents exact finding sites; the older specialist report is available through `health --indexed`. Main skill and setup guidance connect exploration, a written plan, implementation, diff review, simplification and behavioral checks. Missing graph roots and partial multi-selector source reads no longer report full resolution.
+
+Still evidence-dependent: conceptual ownership, business-rule equivalence, module cohesion and the best abstraction cannot be inferred from size or token similarity. Existing context/evidence and indexed drift/framework/cleanup producers remain useful specialists. This checkpoint does not certify every language/provider or claim measured agent effectiveness. A Sol medium audit on a real repository snapshot found three reproducible defects in the first implementation; all three now have fixes and regression tests. See the [audit report](benchmarks/2026-09-05-maintenance-sol-audit.md).
+
+Reviewing the implementation also exposed a comparison defect: an increase in one complexity measure could be hidden by an unchanged maximum ranking score. Review now compares both measures independently, with an executable regression for increased cyclomatic complexity and unchanged cognitive complexity. The report renderer separates changed-function records from finding details; the comparison logic makes its precedence explicit. These changes improve the implementation without requiring every parser branch or validation check to disappear below a threshold.
+
+The repository policy gives the isolated change-benchmark fixture its own boundary with no production dependencies. Range-read tests belong to the navigation test suite. The existing source owner continues to own source snapshots, parsing, fingerprints and coverage measurements; its file budget increases from 61 to 65 for the four shared implementations. This is an explicit budget revision for added responsibility, not evidence that file count measures conceptual quality. All dependency-direction and ownership-coverage rules remain enforced.
+
+The implementation's own review remains above the strict complexity gate: examples include `dependenceSlice` (41 cyclomatic / 48 cognitive), the metric syntax visitor (24 / 29), and `functionCoverage` (19 / 18). Their branches include criterion validation, bounded traversal, syntax-specific counting, source-hash validation and nested-function exclusions. These are retained review findings, not waived checks or a claim that the implementations are optimal. Further simplification must preserve those distinctions and the regression cases. No whole-repository coverage receipt was supplied for this review, so it makes no whole-repository CRAP claim.
+
+Final verification on 2026-09-05: all 2,871 tests in 334 files passed in the serial full suite. `npm run lint` passed formatting, ESLint, the build, public API compatibility, consumer type checking and skill-link checks; `npm run typecheck` and `git diff --check` passed separately. After reindexing, architecture mapped all 541 indexed files across 37 declared boundaries, with no unmapped or ambiguous owners, forbidden dependencies, cycles, size-limit violations, test-boundary violations or stale allowances. The current-source review accounted for 563 eligible files and 12,326 functions with no source-coverage problems. Indexed `diff-impact` also ran, but its coverage did not establish an exhaustive consumer set. The Sol audit and the tests support these bounded claims; they do not establish general improvement in agent outcomes.
+
+
+## First-use reliability follow-up
+
+The active follow-up is recorded in [the scanner checklist](plans/2026-09-05-first-use-scanner-reliability.md). Compiler snapshot resolution, configuration-only diff evidence, source-role exclusions, dependency-role separation, bounded planning subjects and a conservative lexical-binding responsibility candidate are implemented. The follow-up is verified in the [first-use validation report](benchmarks/2026-09-05-first-use-validation.md); the earlier checkpoint above describes the preceding implementation. Current user-facing behavior and precise limitations are documented in [REVIEW.md](REVIEW.md).
+
+
+The first-use follow-up passes the 2,900-test full suite, final focused checks, lint/type/API checks and the refreshed architecture policy. Its source scan resolves LaunchPoint's aliases across all 5,306 eligible files with zero unresolved internal imports in that snapshot. It presents shared dependency components and a bounded selection of module subjects with exact evidence. Conceptual ownership and runtime resource identity remain evidence-dependent; no responsibility candidate qualified in LaunchPoint, and no general agent-effectiveness improvement is claimed. See the validation report for retained metrics, source/index coverage differences and the cheaper-model audit.

package/docs/PROPERTY_TESTING.md

@@ -0,0 +1,73 @@
+# Property-based verification
+
+A property-based test checks a stated rule against generated inputs. Each case is one completed predicate invocation, potentially containing several edits, assertions or service events. fast-check reduces failures to simpler inputs and records a seed and replay path. A passing case count measures executions within the documented generators; it is not a count of unique inputs or proof of exhaustive correctness.
+
+The suites use the existing Vitest runner and production TypeScript owners. fast-check is a development dependency. The shared runner is `tests/properties/support.ts`; the eight area suites are `tests/properties/<area>.property.test.ts`. The external compiler comparison is registered through `indexing-compiler.ts`.
+
+## Running and replaying
+
+```sh
+npm run build # Required for the real daemon and worker entrypoints used by indexing histories.
+npm run test:properties
+npm run test:properties:thorough
+npm run test:properties:thorough -- --area indexing --seed 20260907
+npm run test:properties:types
+```
+
+Normal runs execute 200 component cases, five integration cases, two compiler sequences and two system histories per property. Thorough runs execute 200,000 component cases, 200 integration cases, 30 compiler sequences and 30 system histories per property. All area suites also run at normal budgets under `npm test`. A sequence contains multiple operations; those operations are not added to the case totals. The compiler check launches the independently packaged scip-typescript CLI after each generated edit and compares exact retained document bytes, with separately known file membership and definition checks.
+
+The runner prints a unique temporary result directory. `summary.json` includes actual per-area/tier counts and individual receipts containing the fast-check version, seed, duration, skipped inputs, shrinking count, counterexample and failure message. Failed or interrupted properties cannot contribute passing-case credit; the runner also fails if Vitest reports an error or a full area misses its requested component budget. A raw test pass with a runner/worker error is not accepted.
+
+Replay one failed property with its recorded seed and path, selecting its exact Vitest test name:
+
+```sh
+npm run test:properties -- --area scanner --test 'scanner: generated branches' --seed 12345 --path '0:1:2'
+```
+
+The example seed/path above is illustrative. Use the receipt from the failure. To vary local budgets, set `SCIP_PROPERTY_COMPONENT_RUNS`, `SCIP_PROPERTY_INTEGRATION_RUNS`, `SCIP_PROPERTY_COMPILER_RUNS`, or `SCIP_PROPERTY_SYSTEM_RUNS`. Values must be positive integers. A full thorough invocation still requires at least 200,000 passing component cases per area. Targeted `--test` invocations report only their selected work and do not claim full-area completion.
+
+The GitHub workflow runs normal budgets on pushes and pull requests, and thorough budgets weekly or through manual dispatch. Unspecified seeds vary between invocations and are saved. It uploads the actual receipts even on test failure. The workflow becomes active after the commit reaches GitHub; local execution does not verify hosted CI.
+
+## Guarantees and independent expectations
+
+| Area | Generated checks | Independent expectation and bounds |
+| --- | --- | --- |
+| `indexing` | Add/edit/delete manifests; affected consumers; compiler shard membership; SQLite publication and failures at all four patch stages; retained compiler documents versus fresh compiler output | Plain before/after arrays, exhaustive small-graph reachability, explicit relational facts, unchanged accepted database bytes, and the external compiler. Component graphs have up to 10 vertices; SQLite sequences up to eight operations; compiler sequences two to five edits across four modules plus their consumer. |
+| `graphs` | Component membership/order, target-only vertices, resolved module dependencies, isolated modules and cycle membership | Exhaustive reachability, independent of production Tarjan/queue traversal; generated source imports directly specify expected edges. Up to 10 vertices and 100 proposed edges. |
+| `pagination` | Cursor identity; count/completion consistency; exact saved-output recovery across UTF-8 byte boundaries | Input strings and independently calculated counts, with real snapshot files and continuation reads. Includes ASCII, astral characters, combining marks, control characters, quotes and empty strings. This checks transport accounting, not whether a selected graph contains every task-relevant fact. |
+| `scanner` | Exact cyclomatic/cognitive counts, local renaming and significant-literal duplication distinctions, comment invariance, parse failures, first-use health and file-budget failures | Constructed branches have known counts. Up to five branch groups with five nesting levels, else branches and while loops. Integration scans measure one to 20 sequential conditions and subsequent edits. Other syntax forms retain their existing fixed tests. |
+| `cache` | Source equality, database isolation, LRU eviction, computation failure and scoped/global invalidation; actual source reads after edits/deletions | A small list-based cache model and current file contents. Up to 25 operations, two ownership keys and five files; separate real database/file integration. Source readers are invalidated through the documented cache registry, not assumed to poll disk on each cached read. |
+| `suppressions` | Exact comment categories, source location bounds, finding identity, expiry, changed evidence and cached inventory/configuration changes | Constructed categories, explicit wall-clock comparisons and content identities, plus real indexed source comments. These checks do not establish the correctness of a human's suppression rationale. |
+| `boundaries` | All 20 registered query-service request kinds, identity/timing/payload corruption, binary file limits, hashing and descriptor ownership | Shared fixed request fixtures are exhaustive at compile time; generated envelope fields and independent bytes/hash expectations. Real file cases cover up to 2,048 bytes; existing mutation/race regressions remain. |
+| `lifecycle` | Admission, success, rejection, malformed/mismatched response, timeout, worker error, cancellation, duplicate response and delayed termination; watch finalization failures | Observable settlements, timers, admission state, termination calls, signal listeners and finalization order. The production lane/lifecycle runs with controlled worker/timer boundaries. Generated schedules cover the modeled events, not every OS thread/process interleaving. |
+
+## Command coverage map
+
+Direct coverage below means a generated test invokes the production consumer used by that command. Shared coverage means the command benefits from tested indexing, caches, protocols or transport, while its particular analysis still relies on existing fixed tests. Coverage of a dependency is not coverage of the entire command.
+
+| Commands / surfaces | Property coverage | Remaining specificity |
+| --- | --- | --- |
+| `health`, `review`, `system --source` | Direct current-source scanner/module report consumers; current edits, incompleteness, dependency direction and cycle membership | Generated Git-base diff comparisons, every architecture rule and coverage-backed CRAP are not included. |
+| `reindex` | Direct affected-file planning, sharding, SQLite patch publication and compiler document updates; real reindex/daemon histories, generation readers and interrupted publication | Generated repositories use one small TypeScript project; every configuration and non-TypeScript indexer is not covered. |
+| `watch` | Direct worker-lane/lifecycle transitions; real daemon compiler requests, service restarts and an automatic filesystem refresh | Selected process interruptions and completion schedules do not exhaust OS event delivery or locking behavior. |
+| `continue` | Direct immutable saved-output producer/consumer | Output beyond configured caps and every storage failure retain existing regressions. |
+| `search`, `outline`, `entrypoints`, `inspect`, `code`, `files`, `methods`, `refs`, `imports`, `imported-by`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `stats`, `surface` | Shared indexed identities/source freshness; generated protocol checks for registered request kinds; cursors and output transport | Locator relevance, semantic resolution and exact content selection are not established by envelope validation. |
+| `evidence`, `session`, `deps`, `rdeps`, `system`, `cycles`, `architecture`, `dependency-depth`, `entry-map`, `call-graph`, `affected`, `diff-impact`, `change-surface`, `context`, `hotspots`, `fan-in`, `fan-out`, `coupling`, `bottlenecks`, `dependence-slice` | Shared indexing, graph component/ordering foundations, source module evidence and transport | Symbol-level execution/dataflow/provider completeness and task relevance retain dedicated fixed tests; source-module tests do not prove these relations. |
+| `complexity`, `duplicate-bodies`, `similar`, `similar-files`, `similar-signatures`, `recent-duplicates`, `twin-drift`, `dead`, `unused-imports`, `unused-params`, `drift`, `passthrough-candidates`, `slice-cohesion`, `redundant-reexports`, `not-implemented`, `decorative-checkers`, `test-quality`, `cleanup-plan`, `locality-candidates`, `co-change`, `doc-drift`, `incomplete-migration` | Shared source metrics/fingerprints, cache validity, suppression parsing and transport | Indexed detector-specific scoring, history interpretation, cleanup safety and precision are not inferred from shared properties. |
+| `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure` | Shared source/cache/index/transport foundations | Framework-specific structures remain covered by existing examples; no generated React/Vue suite is claimed. |
+| `augment-sources`, `augment-vue`, `install-skills`, `check-deps`, `capabilities`, `init`, `config-validate`, `suppress`, `doctor`, `setup`, `setup-agent`, `uninstall`, `status` | Shared boundaries/suppression foundations where used | Installation effects, migrations, project discovery, provider support, skill prose and configuration semantics retain existing contracts. |
+| `hook-architecture-stop`, `__diff-impact-batch`, `__health-phase`, `__health-semantic-prewarm` | Shared service and analysis foundations | These internal routes retain their existing end-to-end tests. |
+
+## Scope and results
+
+The indexing system suite (`indexing-history.ts`, `indexing-interruptions.ts`, `indexing-mutations.ts`) runs the actual reindex entrypoint, daemon/worker and SQLite publication. It supplies source edits, never an affected-file list. An initial function-to-constant change must publish incrementally with expensive fallback disabled. Every successful checkpoint compares all fixture-file compiler occurrences (symbols, roles, ranges and enclosing ranges) against the independently packaged compiler, checks exact file membership and database integrity, and checks that an already open reader retains its prior snapshot. The source map supplies independent expected membership and an untouched definition. Compiler semantic bugs shared by both paths can still escape this comparison; it is not a comparison of every analysis provider's output.
+
+Generated histories contain 3–12 actions drawn from function/constant changes, deletion, restoration, rename, import rewiring, invalid syntax, configuration edits, no-op, revert and service restart. A separate fixed history exercises every kind. Short-history enumeration checks every sequence of length 1–2 (12 histories, 21 edit checkpoints) normally and length 1–3 (39 histories, 102 edit checkpoints) in thorough mode, over three owner states: function, constant and absent. Enumeration counts are printed separately, not added to generated-case totals.
+
+Five real process-death checks kill a child indexer before/after its authoritative pointer change and during stable mirror replacement, then recover using retained crash files. Two I/O checks inject ENOSPC. Further checks cover cancellation, competing writers serialized by the lifecycle lock, a moving-input build's rejection, and automatic watcher catch-up. Checkpoints are controlled at real filesystem/status boundaries in an isolated test process. They do not simulate machine power loss or every possible OS schedule. Two temporary production-function mutations deliberately omit dependent files or retain old candidate database rows; both must be caught by the same clean-build assertion. These are negative controls, not production defects found by chance.
+
+The state-verification worklist, confirmed production defects and validation receipts are recorded in [the indexer state plan](plans/2026-09-07-indexer-state-verification.md).
+
+This suite increases the combinations exercised through the tool's shared foundations and selected real consumers. It cannot determine whether business module boundaries are well chosen, infer task intent, validate every language provider, or prove no future defects exist. No agent benchmarks are required. Tests do not alter production thresholds or suppressions.
+
+The implementation worklist, execution receipts and discovered issues are recorded in [the property-testing plan](plans/2026-09-07-property-testing.md).

package/docs/REVIEW.md

@@ -0,0 +1,76 @@
+# Explore, plan, review
+
+Use `scip-query health` for an initial scan and `scip-query review --base HEAD` after changing code. Both read current TypeScript/JavaScript files without a compiler index. `context <symbol>`, exact source reads, and explicitly selected relationship evidence support planning around existing implementations. The installed scip-query skill connects these operations to a written plan and behavioral checks.
+
+A finding is a report identifying concrete source and evidence of a possible defect or maintenance problem. Derived findings report a deterministic calculation, such as a circular import component. Candidates identify code requiring judgment, such as similar implementations whose contracts may differ. Neither category establishes that an automatic rewrite is correct.
+
+## Normal use
+
+```sh
+scip-query health
+scip-query context <existing-symbol>
+# Write a plan citing the implementation, consumers, preserved behavior, and checks.
+# Implement and run the relevant tests.
+scip-query review --base HEAD
+```
+
+`review` compares the named commit with current files, including untracked files, unstaged edits and staged changes still present in current bytes. It lists added, modified and removed functions, including callbacks. Changed functions below warning thresholds still appear. Unique path/name pairs receive before/after metrics; ambiguous names receive uncomparable records. Renames and splits are not guessed: they may appear as removal plus addition. This is not a staged-only report.
+
+Findings are classified as introduced, worsened, existing, resolved, or uncomparable. Duplicate comparisons scan repository peers, including same-file peers and functions added to old files; they do not use file creation dates to decide whether a copy is new. `--scope src/module` filters displayed subjects while retaining repository peers for comparison. `--include-tests` includes tests, fixtures and benchmarks. `--full` displays all findings; it does not remove source-analysis bounds. `--max-files` raises the default 10,000-file limit. Files over 1 MiB and snapshots over 128 MiB are disclosed omissions.
+
+`--check` exits 1 for introduced/worsened derived review findings (or any derived health finding), 2 for incomplete source coverage or unavailable explicitly requested test coverage, and 0 otherwise. Similarity candidates do not fail this gate. A zero exit code does not establish behavioral correctness, complete dependency coverage, or good ownership. Coverage limitations apply even when the source scan is accounted for.
+
+`health --indexed` retains specialist framework, drift and cleanup analyses. `health --baseline` and `--write-baseline` retain the indexed finding-identity baseline. Fresh `diff-impact` and `evidence` establish indexed symbol consumers and supported runtime relationships. The current-source report's affected files are transitive importers only.
+
+## Complexity rules
+
+A function is an executable source unit with parameters and an implementation body. Each function, method, accessor, constructor and callback is measured separately; a nested function's decisions are not added to its enclosing function.
+
+Cyclomatic complexity is a control-flow measure counting independent decision paths under a specified counting rule. Rule set `typescript-function-local-v1` starts at 1 and adds 1 for each `if`, loop, non-default `case`, `catch`, ternary, and `&&`, `||`, or `??` operation. It does not attempt interprocedural path feasibility or implicit exception paths.
+
+Cognitive complexity is a structural measure that increases when control-flow interruptions occur inside other control-flow structures. This implementation adds 1 plus nesting for `if`, loops, `catch`, ternaries and `switch`; `else` and `else if` add 1; same-operator logical sequences add 1; labeled jumps add 1. Nullish coalescing adds no cognitive increment. Contributions include exact line/column locations in the machine result. The initial warning thresholds are cyclomatic >10 or cognitive >15; they are review defaults, not universal design laws.
+
+The structural rules are informed by [SonarSource's specification](https://www.sonarsource.com/docs/CognitiveComplexity.pdf). This version does **not** claim exact Sonar parity: it measures nested functions independently and omits recursion because source spelling alone cannot establish recursive binding. Metrics identify branching and nesting; they do not measure whether a business concept has a clear owner.
+
+## Actual coverage and CRAP
+
+Test coverage is a record of which executable source locations were observed during a test run. CRAP is a numerical review measure combining cyclomatic complexity with uncovered execution locations:
+
+`CRAP = complexity² × (1 − coverageFraction)³ + complexity`.
+
+This is the continuous formula used in [php-code-coverage's CRAP implementation](https://github.com/sebastianbergmann/php-code-coverage/blob/main/src/Node/CrapIndex.php), without its ≥95% shortcut. Here the coverage fraction counts distinct Istanbul statement-start lines belonging to the function, excluding nested function statements. It is not branch coverage, path coverage, or proof that assertions checked the behavior. CRAP ≥30 produces a review finding. Base CRAP is unavailable without an independent source-matched base measurement, so current CRAP findings are uncomparable rather than falsely introduced.
+
+Configure your existing test runner to write Istanbul `coverage-final.json`. Then wrap that actual command. For a local package installation:
+
+```sh
+node node_modules/scip-query/scripts/record-review-coverage.mjs \
+  --input coverage/coverage-final.json --output .scipquery/coverage.json \
+  -- npm test -- --coverage
+scip-query review --coverage .scipquery/coverage.json
+```
+
+Use the test arguments appropriate to your project; the recorder does not install a coverage provider. In this repository the script is at `scripts/record-review-coverage.mjs`. It requires Git, a successful test process, a fresh coverage artifact and unchanged source hashes before/after the run. The receipt contains `schemaVersion: 1` and a `files` object keyed by project-relative path; each entry holds `sourceHash` (SHA-256 of file bytes) and its original Istanbul `coverage` entry. Missing hashes, changed bytes, malformed coverage or unmapped executable locations yield **unavailable**, never fabricated zero coverage. Both health and review print available/unavailable measurement counts. Supplying unusable coverage makes the report incomplete; review requires coverage for its changed current functions, while health requires it for functions in its displayed scope. Keep receipts local; regenerate after edits.
+
+## What findings establish
+
+`suppress <id>` records an exception supported by named source, configuration, test or graph evidence. Automatic acceptance requires a content hash for every file named by the finding, even when the reason is supported by a different file. Supply repeated `--evidence source:<target-file>` arguments alongside that other evidence. Changing or deleting a target or cited evidence invalidates the exception; missing target evidence leaves the finding open. Raw findings remain visible in the report. Suppression checks establish that the reviewed referents still match, not that the written justification is correct.
+
+Duplicate findings compare entire function bodies with at least 60 tokens. They preserve literal values and property names, ignore comments and formatting, and disclose local-binding renaming as candidate evidence. A compiler binding lookup distinguishes each local declaration from unrelated globals and shadowed variables; no import resolution or project-wide typecheck is implied. This is neither semantic equivalence nor partial-block clone detection. Compare callers, errors, side effects, state and intended contracts before selecting one implementation to own a rule. Similar code can correctly serve separate responsibilities.
+
+Dependencies use TypeScript compiler resolution over captured repository source and configuration: relative imports, `paths`/`baseUrl`, JSONC inheritance, project references and repository package exports. Each Git revision uses its own configuration. Missing external configuration is disclosed; the compiler host never silently reads current filesystem bytes to resolve the base. External packages and Node built-ins are counted separately from missing or ambiguous internal imports. Existing relative asset targets (for example CSS) are recorded as excluded dependencies, not missing executable modules. Runtime package installation, custom loaders and nonliteral dynamic targets remain outside this source provider.
+
+The production file-cycle report uses static value imports and re-exports. Type-only imports, tests, dynamic imports and CommonJS calls have separate counts and exact import records. Declared architecture checks include type dependencies and exclude test-related edges; the indexed command preserves dedicated opt-in test-policy checks. Boundary cycles explicitly report whether a cycle between files exists or only the grouping creates the cycle. Neither proves a runtime initialization failure. Missing dependency-policy rows remain unknown directions, even when every analyzed file has a boundary. First-use source checks report observed forbidden edges, enforced group cycles, configured bounds and assignment violations; use `architecture` for the full indexed policy, including test policy and unused allowances.
+
+Review lists source changes, configuration changes and import-relationship changes separately. Configuration-only edits can affect unchanged consumers without inventing added or modified functions. Configuration gaps make dependency comparisons uncertain while exact source metrics remain comparable. Removed targets remain visible through both source revisions.
+
+Default exclusions cover tests (including end-to-end test support), fixtures, benchmarks, declarations, managed build output, generated directories, and reference/vendor copies. `--include-tests`, `--include-generated` and `--include-references` opt into those source roles. Exclusion reasons, eligible/analyzed file counts, missing dependencies and parse/resource failures are visible. Project configuration selects the applicable resolution rules; compiler `include`/`exclude` membership does not silently erase repository tooling from the source inventory.
+
+Health presents dependency components separately from five module planning subjects by default. A shared cycle is not assigned to its first member as that module's defect. A subject groups findings by an unambiguous declared boundary, or by directory when none exists; it is not a discovered business responsibility. Each subject includes exact implementations, observed consumer/dependency files and ranked findings. The first display gives the strongest available example of each finding kind a slot before filling remaining slots, so many copies cannot crowd out all complexity evidence. `--limit` changes the displayed subject count; `--scope` focuses a source path; `--full` returns all findings and details. Machine reports preserve all subjects and findings using `--json --json-output <path>`.
+
+A responsibility candidate requires at least two independent groups of substantial exported top-level functions (at least two functions with 60 body tokens per group), separate observed dependencies and separate named importers. Same-file helpers/state and shared imported modules connect groups; orchestration and shared consumers are contrary evidence. The provider follows lexical binding identity, including nested closures, rather than matching identifier spelling. Classes, indirect re-exports, dynamic consumers, external users and runtime resource identity remain unestablished. A common public contract can justify retaining separate operations together; candidates never authorize an automatic split.
+
+Ownership and conceptual cohesion still require combining behavior, consumers and dependency evidence. The tool does not invent owners, declare a large module inherently wrong, or assign an architectural grade. Plans should record established responsibilities, uncertain alternatives, existing patterns to reuse, and the tests that would catch a mistaken consolidation.
+
+## Retirements
+
+`twin-ab` and its public API were removed: the command generated an unfinished test scaffold, not a behavioral comparison. Write and run focused comparison tests in the project's own test suite. `code file:start-end` now reads only that range by default; add `--local-calls` for statically attributed same-file callees. Default `health` now returns concrete current-source findings; existing consumers of the specialist JSON report should use `health --indexed`.

package/docs/SKILLS.md

@@ -0,0 +1,51 @@
+# Agent workflows and module evidence
+
+scip-query is built for coding agents. Its workflows address choosing the wrong implementation, copying an existing rule, overlooking consumers, leaking coordination into callers, and mistaking an incomplete implementation for finished behavior.
+
+Ordinary source search/reads are the default. Use the tool for relationships, reuse, module structure, quality findings and change impact. Saved results can be read selectively; routine exploration needs no formal evidence ledger or mandatory page draining.
+
+## Six skills
+
+Setup and `install-skills` install all six workflows into available Claude, Codex, and shared agent roots. `--all` remains compatible with existing scripts and has the same result. Agents load only the workflow relevant to their task.
+
+| Skill | Responsibility |
+| --- | --- |
+| [scip-query](../skills/scip-query/SKILL.md) | Shared commands, evidence limits, transport, and actual-diff review |
+| [scip-explore](../skills/scip-explore/SKILL.md) | Establish live behavior, relevant owners, consumers, decisions, effects, and recovery |
+| [scip-plan](../skills/scip-plan/SKILL.md) | Concrete implementation order, preserved behavior, consumer migration, retirement, and checks |
+| [scip-architecture-review](../skills/scip-architecture-review/SKILL.md) | Evaluate architecture and maintainability using concrete consequences for future changes |
+| [scip-integrity-audit](../skills/scip-integrity-audit/SKILL.md) | Compare promised behavior with live behavior; exercise distinguishing positive/negative cases |
+| [scip-setup](../skills/scip-setup/SKILL.md) | Diagnose and repair indexing, freshness, watchers, caches, and installation |
+
+Architecture review absorbs principal-maintainability-review, scip-system-compression, and structural investigations from scip-root-cause and scip-twin-drift. Integrity review absorbs scip-claim-audit, scip-probe-reachability, scip-calibrate, and behavioral comparison of competing implementations. Planning absorbs the useful execution/retirement guidance from conductor. The concrete-plan alias is removed.
+
+Upgrade removes links into this package for retired skills. It preserves unrelated links and user-owned files. Existing prompts naming retired workflows must use the canonical names above. Historical audit documents retain their original skill names as records of those runs.
+
+The shared guide and relevant workflows link the appropriate sections of the [shared command decision guide](../skills/scip-query/references/command-guide.md). Every public command has a question, selector/mode, index prerequisite and interpretation limit. The guide separates internal transport/workers and explains which overlapping-looking controls answer different questions. Agents load the needed section, not an all-command checklist.
+
+## One module evidence view
+
+```sh
+scip-query system --source
+scip-query system --source src/payments
+# Or use an exact group ID printed by the inventory:
+scip-query system --source 'directory:src/payments' --full
+```
+
+Source mode reads the current TS/JS snapshot and configuration without creating a compiler index. It uses the same source analysis as health, but includes modules with no findings. Unambiguous configured boundaries take precedence; remaining files are grouped by directory. A path selects whole groups containing matching files, not a guessed business subsystem.
+
+Selecting a group exposes files, grammar-derived export declarations, imports, incoming import sites, production dependency/consumer files, and finding identities. Cross-group edges retain exact import sites and distinguish value/type, production/test, and static/dynamic/CommonJS syntax. Findings retain derived/candidate labels. The report also exposes configured boundary coverage and unknown dependency-policy rows.
+
+In machine output, `imports` stores each parsed import observation once. Group `importIds`, `incomingImportIds`, and edge `importIds` are indexes into that report's table; they are not identities to reuse across runs. Human output resolves these references to source locations.
+
+Export declarations are starting locations for interface investigation. Wildcard exports are not expanded; CommonJS export assignments, class member interfaces, external consumers, runtime registrations, and complete symbol invocation coverage are not established. `system <path>` retains the indexed summary; indexed `surface <path>` and selected `evidence` relationships supply additional facts where supported. A syntax tree, a resolved reference, and observed execution establish different things.
+
+The human view limits displayed groups and examples and prints exact recovery. `--full` shows all captured rows; it does not remove scan bounds. `--max-files` raises the default 10,000-file limit. File and snapshot byte bounds, parsing/configuration failures, missing imports, and exclusions remain disclosed. Use `--include-tests`, `--include-references`, or `--include-generated` for optional source roles. Save exhaustive machine output using `--json --json-output <path>`.
+
+## Design and integrity judgments
+
+The tool reports structure and checks declared rules. The architecture skill requires the agent to connect a concern to a real maintenance mistake, examine consumers and counterevidence, and explain how a proposed change reduces required knowledge or coordination. Deep interfaces are evaluated by caller obligations; no depth or architecture score is produced.
+
+Integrity review starts with a specific promised outcome, traces the live route, and exercises cases that distinguish a real implementation from a shortcut. A parser library being present does not prove it replaced regex extraction. A missed parser probe does not prove a branch unreachable. Literal status values can be justified by preceding checks; computed status can still be misleading.
+
+Skills are agent instructions. They do not enforce their own compliance or establish better agent behavior merely by existing. Workflow effectiveness requires comparing actual agent tasks and resulting changes, alongside deterministic tests for the tool's reported facts. A complete inventory does not establish a complete behavioral review; disclose material limitations when they affect the conclusion.

package/docs/WINDOWS_SIDECAR_RELEASE.md

@@ -137,9 +137,9 @@ and verifying registry truth after each publication:
 2. require a clean Git checkout and record the exact `HEAD` object ID;
 3. resolve one canonical credential-free HTTPS npm registry and retain it for
    the complete run;
-4. run typecheck, the complete test suite, and lint; lint includes formatting,
-   production build, API compatibility, downstream compilation, and skill
-   link checks;
+4. run typecheck, the production dependency audit, and lint (including
+   formatting, production build, API compatibility, downstream compilation,
+   and skill links), then the complete test suite against that fresh build;
 5. verify provenance and pack the sidecar;
 6. pack the main package with lifecycle scripts disabled;
 7. extract both packed `package.json` files, require their coordinates, and
@@ -184,6 +184,15 @@ the two packed artifacts were tested and produced.
    local recovery record, and reads/downloads any existing registry versions.
    It never invokes `npm publish`.
 
+   The complete suite keeps its two-worker limit. CLI contract tests execute
+   the built CLI instead of repeatedly loading TypeScript through a development
+   runner. Test subprocesses share Node's module compilation cache inside the
+   release's temporary directory, which is removed on success or failure.
+   Every test still executes; no previous pass is reused. Explicit
+   `NODE_DISABLE_COMPILE_CACHE=1` and `NODE_COMPILE_CACHE` settings are honored,
+   and `NODE_V8_COVERAGE` disables compilation caching for precise coverage.
+   Node versions without compilation-cache support still run the same checks.
+
 5. Review the reported coordinates, integrities, registry states, and the JSON
    record under `.scipquery/releases/`.
 6. Run:

package/docs/accuracy-audit-checklist.md

@@ -42,6 +42,63 @@ The certification thresholds and publication rules live in
 Program closure and the private-shadow decision live in
 [`2026-07-11-accuracy-program-closure.md`](./validation/2026-07-11-accuracy-program-closure.md).
 
+## 2026-09-03 third and fourth repository label review
+
+SuplierScout (Express + React, solution-style tsconfig, 17.8k symbols) and
+Stable_Management (workspace monorepo, five tsconfigs, 109k symbols). Sample
+seed 11; every row read in source. Precision is over labeled signal-tier rows,
+recall over labeled true rows.
+
+| Detector                         | Repository        | Sample | Precision | Recall | Note                                                                             |
+| -------------------------------- | ----------------- | ------ | --------- | ------ | -------------------------------------------------------------------------------- |
+| `twin-drift`                     | Stable_Management | 15     | 1.0       | 1.0    | writeAuditEntry in 18 copies, hasAnyRole in 4, drifted normalization helpers.    |
+| `duplicate-bodies`               | Stable_Management | 10     | 1.0       | 1.0    | Identical bodies under different names or workspaces.                            |
+| `stale-abstractions`             | Stable_Management | 20     | 1.0       | 1.0    | Verified with `git grep -w`; nine contract types with no consumer anywhere.      |
+| `co-change`                      | Stable_Management | 16     | 1.0       | 1.0    | Was 0.82 recall; view script companions were read as maintenance scripts.        |
+| `similar`                        | Stable_Management | 20     | 1.0       | 0.92   | Was 0.33 recall; same-file workflow siblings were held at signal by vocabulary.  |
+| `wrapper-candidates`             | Stable_Management | 20     | n/a       | n/a    | All 50 rows are signal tier; the sample holds no direct-tier row to score.       |
+| `dead`                           | Stable_Management | 1      | 1.0       | 1.0    | One frontend API export with no frontend reference.                              |
+| `extract-candidates`             | Stable_Management | 20     | 0.25      | 1.0    | Three signal rows are fragments crossing a block boundary; see the known gap.    |
+| `similar`                        | SuplierScout      | 13     | 1.0       | 0.67   | Console panels sharing a boot-and-fetch shell stay at signal.                    |
+| `extract-candidates`             | SuplierScout      | 20     | 1.0       | 0.64   | Was 0.9 precision; misses are wide-interface rows disclosed at support tier.     |
+| `dead`                           | SuplierScout      | 17     | 1.0       | 1.0    |                                                                                  |
+| `twin-drift`                     | SuplierScout      | 12     | 0.83      | 1.0    | Provider-contract implementations and client HTTP wrappers over server services. |
+| `co-change`                      | SuplierScout      | 16     | 0.8       | 1.0    | One global stylesheet paired with a server route.                                |
+| `duplicate-bodies`               | SuplierScout      | 10     | 1.0       | 1.0    |                                                                                  |
+| `stale-abstractions`             | SuplierScout      | 20     | 1.0       | 1.0    |                                                                                  |
+| `passthrough-candidates`         | SuplierScout      | 4      | 1.0       | 1.0    | The defaulted-parameter row is excluded now.                                     |
+| `wrapper-candidates`             | SuplierScout      | 6      | n/a       | n/a    | All signal tier.                                                                 |
+| `react-large-component-pressure` | SuplierScout      | 4      | 1.0       | 1.0    |                                                                                  |
+
+Known gap: `extract-candidates` reports regions built from callee line
+intervals, so a region can begin inside an enclosing branch or end by closing
+one. Demoting every region whose braces do not balance fixes the three
+Stable_Management rows but fires on 50 to 75 percent of all rows and costs
+recall on Vega and SuplierScout, so it is not shipped.
+
+## 2026-09-02 TypeScript label review
+
+The matrix below is the 2026-07-10 snapshot. On 2026-09-02 the TypeScript
+detectors that feed the health report were re-audited against reviewed
+label sets (`docs/validation/labels/<repository>/<detector>.json`, scored by
+`scripts/score-detector-labels.ts`). Each row names the repository, the
+sample, and the result after that day's fixes; the truth rules are in the
+label files' notes.
+
+| Detector                                              | Repository        | Sample                     | Precision / recall of labeled rows                             | Notes                                                                              |
+| ----------------------------------------------------- | ----------------- | -------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `dead`                                                | Launchpoint       | 20 of 65 dead-code rows    | 0.95 / 1.0, then 1.0 after the config-referenced entry surface | word search outside the defining file as the truth rule                            |
+| `similar`                                             | Launchpoint       | 20 pairs                   | 1.0 / 0.43                                                     | four true pairs sit at signal tier by the earlier scaffolding calibration          |
+| `stale-abstractions`                                  | Launchpoint       | 5 direct, 10 signal        | 1.0 / 1.0                                                      | signal rows are counted findings (`countedTiers`)                                  |
+| `complexity-hotspots`                                 | Launchpoint       | 20 of the 192 extreme rows | 1.0 / 1.0                                                      | text recount of branch tokens agrees                                               |
+| `react-large-component-pressure`                      | Launchpoint       | 20 components              | 1.0 / 1.0                                                      | two static templates labeled uncertain                                             |
+| `co-change`                                           | Launchpoint       | 20 non-doc pairs           | 0.53 before the signal tier                                    | sweep-only, stale, and configuration pairs are signal tier and not counted         |
+| `extract-candidates`                                  | Launchpoint, Vega | 20 each                    | 1.0 / 1.0; 0.875 / 0.54                                        | Vega misses are wide-interface support rows; element-boundary snapping added       |
+| `wrapper-candidates`                                  | Launchpoint, Vega | 20 each                    | direct tier 0 false; 1.0 / 1.0                                 | forwarding shape, owner-qualified boundary names, module-private state             |
+| `passthrough-candidates`                              | Launchpoint, Vega | 20 each                    | 1.0 / 1.0; 1.0 / 1.0                                           | shared vocabulary, composed-service facades, curried handlers                      |
+| `twin-drift`                                          | Launchpoint, Vega | 20 groups each             | 0.77 / 1.0; 0.83 / 0.71                                        | layering, stubs, overrides, key-qualified lookups, near-name suffix words          |
+| `react-component-duplicates`, `react-hook-candidates` | Launchpoint       | full-list review (morning) | see the calibration document                                   | policy exclusions for generic mechanics, hook/component pairs, vendored primitives |
+
 ## Certification Matrix
 
 Legend: `certified`, `qualified`, `experimental`, `insufficient`, `unsupported`,
@@ -97,8 +154,8 @@ state. A checked box does not upgrade an `insufficient` state to `certified`.
 
 - [x] `unused-imports` — certified
 - [x] `unused-params` — insufficient population evidence
-- [x] `cycles` — insufficient population evidence
-- [x] `duplicate-bodies` — certified
+- [x] `cycles` — insufficient population evidence (2026-09-02: consistent across generations; the Launchpoint change was the repository removing its cycles)
+- [x] `duplicate-bodies` — certified (2026-09-02: constructors, test bodies, route verb exports, and UI-kit bodies removed before grouping)
 - [x] `complexity` — certified
 - [x] `isolated` — insufficient population evidence
 - [x] `redundant-reexports` — certified
@@ -151,8 +208,8 @@ certificate:
 - [x] `similar-files` — certified relationship
 - [x] `similar-chains` — qualified within a bounded candidate frame
 - [x] `similar-signatures` — certified relationship
-- [x] `twin-drift` — qualified; 37/40 valid
-- [x] `react-component-duplicates` — certified relationship
+- [x] `twin-drift` — qualified; 37/40 valid (2026-09-02: route-convention and CRUD/lifecycle member names excluded; no reviewed precision sample yet)
+- [x] `react-component-duplicates` — certified relationship (2026-09-02: test-file, UI-kit, route-scaffolding, and hook-versus-component policies; Launchpoint label set precision 1.0 / recall 1.0)
 - [x] `vue-component-duplicates` — certified relationship
 - [x] `convergence` alias parity with `similar --plan`
 - [x] `twin-ab` — certified generated-scaffold correctness for importable named
@@ -164,18 +221,18 @@ consolidation would improve the code.
 
 ## Architecture and Refactoring Signals
 
-- [x] `wrapper-candidates` — certified production single-caller relationship
-- [x] `passthrough-candidates` — certified literal-forwarding relationship
+- [x] `wrapper-candidates` — certified production single-caller relationship (2026-09-02: constructors excluded, body shape distinguishes forwarders from helpers; no reviewed precision sample yet)
+- [x] `passthrough-candidates` — certified literal-forwarding relationship (2026-09-02: facade files (three or more forwards to one collaborator) become boundary signals; no reviewed precision sample yet)
 - [x] `stale-abstractions` — certified relationship
-- [x] `extract-candidates` — certified measurement; extraction remains contextual
+- [x] `extract-candidates` — certified measurement; extraction remains contextual. Rebuilt 2026-09-02 around exclusive line regions with compiler-known locals; the Python row above predates the rebuild, and the current reviewed sample is `docs/validation/labels/launchpoint-backend/extract-candidates.json`
 - [x] `locality-candidates` — certified relationship; movement remains contextual
 - [x] `drift` — qualified; subtype breadth incomplete
-- [x] `co-change` — certified relationship
+- [x] `co-change` — certified relationship (2026-09-02: doc-code and generated-artifact partners weight zero)
 - [x] `doc-drift` — certified relationship
 - [x] `coupling` — certified graph fact
 - [x] `bottlenecks` — certified disclosed graph fact; utility remains contextual
 - [x] `deep-chains` — certified condensed-component path
-- [x] `complexity-hotspots` — certified measurement
+- [x] `complexity-hotspots` — certified measurement (2026-09-02: rendered children count as fan-out; extreme requires ten branches; pressure threshold scales with file count)
 - [x] `hotspots` — certified graph fact
 - [x] `fan-in` — certified exact-symbol graph fact
 - [x] `fan-out` — certified graph fact
@@ -185,9 +242,9 @@ action. A real relationship can still be an unhelpful recommendation.
 
 ## React and Vue Signals
 
-- [x] `react-component-duplicates` — 48/48, certified relationship
-- [x] `react-hook-candidates` — 48/48, certified relationship
-- [x] `react-large-component-pressure` — 48/48, certified measurement
+- [x] `react-component-duplicates` — 48/48, certified relationship (2026-09-02: test-file, UI-kit, route-scaffolding, and hook-versus-component policies; Launchpoint label set precision 1.0 / recall 1.0)
+- [x] `react-hook-candidates` — 48/48, certified relationship (2026-09-02: generic-mechanics and shared-hook policies; Launchpoint label set precision 1.0 / recall 1.0)
+- [x] `react-large-component-pressure` — 48/48, certified measurement (2026-09-02: UI-kit directories excluded; token axes gated by size)
 - [x] `vue-component-duplicates` — 41/41, certified relationship
 - [x] `vue-composable-candidates` — 48/48, certified relationship
 - [x] `vue-large-view-pressure` — 64/64, certified measurement
@@ -218,7 +275,7 @@ was not independently actionable without local design context.
   - [x] `new-dead` — qualified candidate with unconfirmed tier
   - [x] `baseline` — qualified exact set difference
 - [x] `health` — experimental composite; private shadow only
-- [x] `self-audit` — qualified; partial oracles withhold precision
+- [x] `self-audit` — qualified; partial oracles withhold precision (2026-09-02: renders question, per-symbol complete oracle, callee precision measured (Vega 1.0 / Launchpoint 0.988))
 - [x] `effectiveness` — qualified ledger-transition facts
 - [x] `affected` — qualified indexed closure
 - [x] `change-surface` — qualified indexed consumer counts

package/docs/analyzer-inventory.md

@@ -31,8 +31,8 @@ These commands report direct findings or bounded maintenance leads:
   `similar-chains`, `duplicate-bodies`, `recent-duplicates`, `twin-drift`;
 - unnecessary indirection: `wrapper-candidates`, `passthrough-candidates`,
   `decorative-checkers`, `not-implemented`;
-- extraction and locality: `extract-candidates`, `locality-candidates`,
-  `complexity-hotspots`;
+- extraction and locality: `extract-candidates`, `slice-cohesion`,
+  `locality-candidates`, `complexity-hotspots`;
 - migration and documentation: `incomplete-migration`, `doc-drift`,
   `redundant-reexports`;
 - history and coordination: `co-change`, `change-surface`.