scip-query 0.20.0 → 0.21.1

package/docs/analyzer-validation-protocol.md

@@ -1,192 +1,84 @@
-# Analyzer Validation Protocol
+# 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.
+This protocol tests whether scip-query reports useful repository evidence on
+arbitrary projects. It does not use a hidden exact implementation as the only
+oracle, and it does not treat a command firing as proof that the product helped.
 
-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`.
+An oracle is an independent way to determine what is true in the fixture. A
+fixture is a disposable repository state with known relationships or defects.
+A true positive is a reported item whose claimed relationship or defect exists
+at its cited source. A false positive is a reported item whose claim does not
+hold when the source and relevant consumers are inspected.
 
-## Core Concepts
+## Required evidence
 
-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.
+For each detector family, use at least:
 
-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.
+1. a small synthetic fixture that isolates the claimed behavior;
+2. a real repository example with normal framework and build conventions;
+3. one negative example that looks similar but should not be reported;
+4. direct source, compiler, test, or version-history evidence for the verdict.
 
-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.
+Do not score a detector by output volume. Count correct findings, incorrect
+findings, missed known cases, time, and output size separately.
 
-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.
+## Mapping commands
 
-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.
+Validate `context`, graph queries, and `diff-impact` against relationships that
+can be independently checked through compiler references, source imports,
+tests, or a second language-aware tool. Judge:
 
-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.
+- whether the named entry-to-effect path is real;
+- whether material consumers are present;
+- whether bounded coverage is disclosed;
+- whether the output helps form a correct plan without unnecessary commands.
 
-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.
+## Cleanup commands
 
-## Validation Corpus
+For dead code, duplication, drift, extraction, wrappers, migration residue, and
+documentation findings, record:
 
-The first corpus should use local repositories that are already available and large enough to stress the current analyzer families.
+- the exact claim the command made;
+- the source location and evidence class;
+- the repair that would follow if the claim is correct;
+- intentional variation or framework behavior that defeats the claim;
+- whether rerunning after the repair removes the finding.
 
-| 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 |
+## React and Vue
 
-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.
+Test both frameworks. Each corpus must include components, hooks or composables,
+large views, intentional variants, framework entrypoints, and generated or test
+files. Vue source augmentation must be enabled before judging Vue recall.
 
-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.
+## Architecture
 
-## Run Protocol
+Define boundary rules before creating the violating edge. Confirm that
+`architecture` reports the forbidden dependency with both endpoints and does
+not invent violations outside the declared rules. Then remove the edge and
+confirm the finding disappears.
 
-For each repository, record the exact revision first.
+## Health
 
-```sh
-git -C /path/to/repo rev-parse HEAD
-```
+Judge each underlying finding before judging the aggregate report. A health
+score is a summary of detector output, not an independent oracle. Baseline mode
+is valid only for the narrower question: did a new stable finding identity
+appear relative to the recorded baseline?
 
-Then index and capture the broad report.
+## Agent-effectiveness trials
 
-```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
-```
+To test whether the product helps an agent, run matched control and treatment
+tasks in separate disposable copies of the same fixture:
 
-For each analyzer under review, capture three samples when possible.
+- use the same provider, model, reasoning level, task prompt, starting commit,
+  dependency state, and hidden time limit;
+- prepare and index the treatment before measured work begins;
+- give the control ordinary repository tools and the treatment the reduced
+  scip-query exploration surface;
+- do not reveal hidden scoring facts or the time limit;
+- keep full transcripts;
+- score plan accuracy, implementation correctness, completeness, architecture,
+  residue, elapsed time, and tokens separately.
 
-| 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.
+The treatment succeeds only when it improves task outcomes or reaches the same
+outcome with a meaningful efficiency gain. A detector warning counts as value
+only if it identifies a real issue and changes the agent's work for the better.

package/docs/architecture-coherence-vision.md

@@ -87,7 +87,12 @@ row for a boundary that may depend on nothing. `requireAcyclic` independently
 forbids multi-boundary strongly connected components. A project should enable
 both only after the observed graph has been classified and repaired.
 
-`requireResolvedBoundaries` closes the gap those two leave open. Same-boundary
+`requireCompleteCoverage` gives boundary ownership normative force: every
+indexed, non-ignored file must match exactly one declared boundary. Without the
+flag, unmapped and ambiguous files remain visible coverage facts but cannot
+block work.
+
+`requireResolvedBoundaries` closes the gap the dependency rules leave open. Same-boundary
 dependencies are always allowed, so every edge inside a boundary is discarded
 before `requireAcyclic` runs — which means a boundary coarse enough to contain
 both sides of a cycle passes the check while saying nothing about the code
@@ -173,20 +178,21 @@ For each mature boundary, state which other boundaries it is allowed to depend o
 
 Run the report again. A forbidden edge is now a testable disagreement between implementation and policy, not the tool's opinion about directory distance.
 
-### 6. Baseline and ratchet
+### 6. Review and ratchet
 
-Record reviewed existing violations with `scip-query health
---write-baseline`. Architecture identities name a forbidden boundary pair or
-an explicitly forbidden boundary cycle, so moving a representative file does
-not churn the ratchet. The default `scip-query diff-gate` architecture check
-then rejects new identities while preserving visibility into recorded debt.
-This turns architecture from a one-time diagram into a maintained contract.
+Run `scip-query architecture` after changing a declared boundary or one of its
+consumers. The report applies configured dependency rules exactly and cites the
+files that create each forbidden edge. Repositories that want a broader
+maintenance ratchet can record reviewed health findings with `scip-query health
+--write-baseline` and compare later scans with `scip-query health --baseline`.
+Neither command decides whether an arbitrary coding task is complete.
 
 ### 7. Migrate narrow seams
 
 Start with a narrow edge whose few file dependencies cross a mature rule. Determine whether the right repair is to move code, invert a dependency, extract a genuinely shared contract, combine falsely separated boundaries, or revise the policy.
 
-Verify each slice with tests, typechecking, incomplete-migration checks, architecture analysis, and diff-gate before taking the next one.
+Verify each slice with tests, typechecking, incomplete-migration checks,
+architecture analysis, and `diff-impact` before taking the next one.
 
 ## Example: Vega 2.0
 
@@ -199,7 +205,7 @@ For a codebase the size of Vega 2.0, the first pass should not invent a universa
 5. configure the mature boundaries descriptively;
 6. inspect reciprocal pairs and large connected components with their file-edge breadth;
 7. close dependency rows only where the intended direction is supported;
-8. baseline existing violations and prevent new ones;
+8. record reviewed violations and check each relevant change against the declared rules;
 9. migrate one narrow, high-confidence seam at a time.
 
 The initial result may be a mixture of layers and subsystems. That is preferable to forcing a neat diagram that contradicts the software. The model becomes stronger as verified migrations and maintenance history provide new facts.
@@ -212,7 +218,7 @@ The initial result may be a mixture of layers and subsystems. That is preferable
 - Extract the reusable strongly-connected-component algorithm already embedded in `deep-chains`.
 - Add a pure architecture graph analyzer and `scip-query architecture`.
 - Extend the directory-architecture skill with the discover, declare, measure, and ratchet workflow.
-- Keep architecture outside health scoring and diff-gate blocking.
+- Keep architecture findings distinct from ordinary code-smell scoring.
 
 ### Slice 2: replace implicit drift policy — implemented
 
@@ -225,7 +231,7 @@ The initial result may be a mixture of layers and subsystems. That is preferable
 
 - Give architecture findings stable identities.
 - Add report-only health visibility.
-- Add a narrow default diff-gate ratchet for newly introduced declared violations, backed by the shared health baseline.
+- Support an optional repository health baseline for teams that want a ratchet.
 - Calibrate on scip-query, Vega 2.0, Stable Management, and structurally different external repositories before any score deduction.
 
 ### Slice 4: discovery assistance

package/docs/locality-analyzer-design.md

@@ -147,7 +147,7 @@ scip-locality-review
 The skill would tell agents to run:
 
 ```sh
-scip-query plan-context <target> --full
+scip-query context <target> --full
 scip-query imported-by <symbol>
 scip-query rdeps <file>
 scip-query co-change <file> --full