codebaseiq 0.1.0

package/docs/accuracy-hardening-goal.md

@@ -0,0 +1,500 @@
+# Accuracy Hardening and Health Certification Roadmap
+
+Date: 2026-07-10
+Status: Complete for private-shadow readiness; public leaderboard remains a separate program
+
+> Historical certification record. It preserves the evidence and command
+> names used during the 2026-07 program. See
+> [Analyzer inventory](analyzer-inventory.md) and
+> [Analyzer validation protocol](analyzer-validation-protocol.md) for the
+> current product and evaluation standard.
+
+Current execution plan:
+[`2026-07-11-remaining-accuracy-verification-program.md`](./plans/2026-07-11-remaining-accuracy-verification-program.md).
+Closure certificate:
+[`2026-07-11-accuracy-program-closure.md`](./validation/2026-07-11-accuracy-program-closure.md).
+
+## Goal
+
+Make codebaseiq's reported health findings trustworthy enough to publish for
+real open-source repositories. Trust is earned per detector, language, and
+evidence capability; it is not inherited from the composite health score or
+from calibration on a different ecosystem.
+
+This program uses existing repositories as its primary evidence. Small
+fixtures remain regression tests, while historical fixes and temporary
+mutations in disposable worktrees provide known-positive cases for measuring
+what a detector misses.
+
+## Accuracy Contract
+
+Precision is the share of reported findings that satisfy the detector's truth
+rule after the cited code is inspected. Recall is the share of known real
+problems that the detector reports. Precision protects users from false
+accusations; recall measures the problems the tool fails to show. Neither can
+substitute for the other.
+
+A truth rule is the repeatable decision procedure that makes two reviewers
+classify the same candidate consistently. Every detector must define its rule
+before its findings are sampled.
+
+### Certification levels
+
+| Level                 | Evidence requirement                                                                                                                                                 | Public treatment                                 |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Certified             | Observed precision at least 95%, conservative 95% confidence lower bound at least 90%, evidence from at least three repositories, and known-positive recall coverage | Actionable finding                               |
+| Qualified             | Observed precision at least 90% but not all certified gates are met                                                                                                  | Investigation signal                             |
+| Experimental          | Observed precision below 90% or a known unresolved noise archetype can produce finding walls                                                                         | Omit from public results; retain for development |
+| Unsupported           | Required parser, semantic provider, checker, framework model, or repository input is unavailable                                                                     | Report `not analyzed`, never zero                |
+| Insufficient evidence | Too few reviewed findings or known-positive cases to estimate performance                                                                                            | Report uncertified status, never imply accuracy  |
+
+The conservative lower bound is the plausible floor after accounting for
+sample size. For orientation, 95 valid rows out of 100 is 95% observed
+precision but does not establish a 90% lower bound; about 97 out of 100 or 190
+out of 200 does.
+
+Certification is recorded independently for each detector-language pair and,
+where framework behavior changes reachability, for the applicable framework
+cohort. An aggregate percentage may summarize certified rows, but it must
+never hide an uncertified combination.
+
+## Publication Contract
+
+Until certification is complete, the composite health score is a local
+prioritization aid and is not eligible for a public cross-repository
+leaderboard.
+
+Public output must:
+
+- separate derived measurements, compiler/graph-backed candidates, and
+  investigation signals;
+- identify language, detector version, indexer or semantic provider, commit,
+  dependency-install state, and capability status;
+- report applicable production files or lines, excluded candidates, and
+  exclusion reasons;
+- distinguish a supported zero from `unsupported`, `degraded`, and `not
+analyzed`;
+- normalize applicable findings by production lines or applicable files, not
+  by every indexer-emitted symbol;
+- keep React, Vue, Rust macro/trait, Python framework, and other stack-specific
+  cohorts out of universal comparisons unless applicability is normalized;
+- disclose Git-history coverage and commit filters for history-derived
+  measurements; and
+- preserve the raw result and analysis version so a published result can be
+  reproduced after detector changes.
+
+Facts and recommendations must remain separate. Identical bodies, dependency
+cycles, branch counts, or Git change counts can be reproducible facts; a claim
+that code should be consolidated, split, or deleted requires additional
+evidence.
+
+## Real-Repository Corpus
+
+The first calibration corpus uses repositories already available locally.
+They remain read-only; any deletion test or planted known-positive case runs
+in an isolated worktree or temporary clone.
+
+| Cohort     | Initial repositories                                                                                  | Coverage purpose                                                                                                    |
+| ---------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| TypeScript | Vega_2.0, openwork, Stable_Management, traceroot; Element Plus and PrimeVue for Vue framework breadth | React, Vue, workspaces, packages, backend code, documentation/showcase families, and mixed-language boundaries      |
+| Rust       | openai/codex, SynthRunnerRust                                                                         | Large workspace plus small crate; traits, derives, macros, generated code, async runtimes, and public APIs          |
+| Python     | scip-python, traceroot, Python files in openai/codex                                                  | Large Python codebase, mixed repositories, decorators, framework registration, and current semantic-capability gaps |
+
+Additional public repositories may be added to cover a missing framework or
+repository shape. Corpus additions must address a named gap rather than merely
+increase volume.
+
+## Detector Truth Rules
+
+Each detector gets a more detailed rule in its calibration manifest. The
+starting rules are:
+
+- **Dead code:** no production, public API, framework, generated, reflective,
+  configured, FFI, macro, or test-required consumer exists, and removal passes
+  every available checker covering the file. A missing checker prevents a
+  certified deletion claim.
+- **Dependency cycle:** the reported files and dependency edges exist in the
+  accepted index. The cycle is factual; architectural harm is a separate
+  signal.
+- **Exact duplicate body:** normalized callable bodies are equal. The equality
+  is factual; consolidation is a recommendation.
+- **Complexity measurement:** source lines, branches, and cyclomatic estimate
+  match the stated AST or fallback basis. The composite hotspot product is a
+  prioritization signal, not cyclomatic or cognitive complexity.
+- **Similarity, twins, wrappers, passthroughs, stale abstractions, extraction,
+  frontend pressure, and hidden coupling:** the emitted evidence must match
+  the code, but actionability is an investigation verdict until the
+  detector-language pair earns certification.
+
+## Roadmap
+
+### Phase 0 — Freeze the calibration and publication schemas
+
+- Define the machine-readable calibration manifest, reviewed-row schema,
+  detector truth rule, verdict vocabulary, and noise-archetype vocabulary.
+- Record repository, commit, tool version, detector version, language,
+  framework cohort, evidence provider, capability state, finding ID, file and
+  line, exclusion reasons, reviewer verdict, checker result, and review notes.
+- Add Wilson confidence intervals and per-detector-language certification
+  status. Do not calculate one global accuracy number as the primary result.
+
+Exit: the same reviewed rows always produce the same precision, confidence,
+and certification decision.
+
+### Phase 1 — Extend the real-repository calibration harness
+
+The current `scripts/accuracy-calibration.mjs` harness proves selected
+navigation answers against known source facts and records timing. Extend it
+without making local repositories a normal test dependency.
+
+- Run health detectors in full, uncapped mode against temporary indexes.
+- Select deterministic random and stratified samples instead of only top
+  findings.
+- Produce a review ledger with `valid`, `invalid`, and `uncertain` verdicts.
+- Preserve candidate evidence and source locations needed for code review.
+- Group invalid findings by named noise archetype.
+- Support a fresh holdout sample that was not used while fixing the detector.
+- Replay selected historical commits and temporary known-positive mutations
+  in isolated worktrees for recall.
+
+Exit: one command can generate a reproducible calibration packet without
+modifying any corpus repository.
+
+### Phase 2 — Certify TypeScript dead-code findings
+
+- Review approximately 25 deterministic candidates each from Vega_2.0,
+  openwork, Stable_Management, and traceroot for a 100-row baseline.
+- Verify public exports, ambient declarations, decorators, framework
+  registration, workspace/barrel consumers, generated entry points, and test
+  boundaries.
+- Fix shared false-positive archetypes rather than suppressing individual
+  examples or raising thresholds until output looks clean.
+- Re-run the original sample and a fresh holdout sample.
+- Exercise known positives from historical deletions or isolated worktree
+  mutations to establish recall coverage.
+
+Exit: TypeScript dead code is certified, qualified, or explicitly retained as
+experimental with every failed criterion recorded.
+
+### Phase 3 — Certify TypeScript measurements and remaining detector families
+
+Work in evidence order:
+
+1. cycles, exact duplicates, raw complexity measurements, unused imports, and
+   unused parameters;
+2. recent duplicates, similarity, co-change, and doc drift;
+3. twins, wrappers, passthroughs, stale abstractions, extraction candidates,
+   React/Vue duplication and pressure, and hidden coupling.
+
+Detectors below 90% remain absent from public output even when useful during
+interactive exploration.
+
+Exit: every TypeScript health family has a current certification state and a
+published list of unresolved noise archetypes.
+
+### Phase 4 — Certify Rust and replace silent bias with visible applicability
+
+Completed 2026-07-11 with qualified, insufficient, or unsupported verdicts;
+no Rust row met the evidence threshold for promotion to certified. The renewal
+used three pinned broad-replay repositories plus the prior six-repository dead
+expansion, corrected seven trait/convention/import/signature advice archetypes,
+and retained ordinary relationships on an untouched Vega holdout. Evidence and
+per-command boundaries are recorded in
+[`2026-07-11-rust-detector-certification.md`](./validation/2026-07-11-rust-detector-certification.md).
+
+- Calibrate on openai/codex and SynthRunnerRust, then add at least one more
+  public Rust repository before awarding certified status.
+- Measure trait, trait-implementation, derive, attribute-macro, test,
+  generated-code, async-runtime, ABI/export, and public-library behavior.
+- Replace silent broad exclusions with reported applicability states and
+  exclusion counts wherever the tool cannot prove runtime reachability.
+- Prefer rust-analyzer or SCIP evidence over framework-name rules. A
+  conservative exclusion may protect precision, but it must not make a
+  macro-heavy repository appear objectively healthier through invisible
+  omissions.
+- Verify candidate deletion with `cargo check` when available and report when
+  build scripts, features, targets, or missing dependencies limit coverage.
+
+Exit: each Rust detector is certified, qualified, experimental, unsupported,
+or insufficiently evidenced, with exclusion coverage visible.
+
+### Phase 5 — Build and certify Python semantic and framework coverage
+
+Status: Complete with explicit withholding. The current implementation has a
+Python indexer and source facts but no Python semantic provider or type-aware
+checker. The three-repository audit corrected dunder, transitive model,
+protocol-hook, and runtime export false positives, then assigned every Python
+row a qualified, insufficient, or unsupported verdict. Evidence:
+[`2026-07-11-python-detector-certification.md`](./validation/2026-07-11-python-detector-certification.md).
+
+- Establish the current indexing, semantic, and checker capability separately
+  for each corpus repository.
+- Add or integrate semantic reference evidence before making strong dead-code
+  claims.
+- Model decorator and registration behavior for Django, FastAPI, Flask,
+  pytest fixtures, Click/Typer, dataclasses, and Pydantic as corpus evidence
+  requires.
+- Treat unsupported semantic or checker paths as `not analyzed`, not clean.
+- Calibrate on scip-python, traceroot, and at least one additional public
+  Python repository with a different framework shape.
+
+Exit: Python findings meet the same thresholds as TypeScript and Rust, or the
+public capability matrix clearly withholds unsupported families.
+
+### Phase 6 — Replace the leaderboard score with certified evidence views
+
+- Publish per-language and per-framework finding families, coverage, and
+  certification status before considering a composite score.
+- Normalize only within comparable cohorts and applicable production code.
+- Version methodology and retain historical results under the detector version
+  that produced them.
+- Ensure health actions use calibrated language: facts, candidates, signals,
+  and unsupported analyses cannot share defect wording.
+
+Exit: two repositories cannot change relative rank merely because one uses a
+framework-specific detector or contains more excluded/test/generated symbols.
+
+### Phase 7 — Run a private cloud shadow leaderboard
+
+- Analyze immutable clean checkouts for new commits with reproducible
+  dependency setup or an explicit degraded-mode disclosure.
+- Reuse parent-commit indexes and semantic evidence through the completed
+  automatic incremental indexing system.
+- Run for several weeks across diverse public repositories, auditing top
+  findings, commit-to-commit stability, coverage changes, and detector-version
+  rank changes.
+- Publish only after certified detector output remains stable and
+  reproducible; keep experimental detectors private.
+
+Exit: the service can reproduce any result from repository commit, analysis
+version, configuration, capability record, and preserved raw output.
+
+## Completed Foundation
+
+The previous accuracy-hardening program established:
+
+- source-backed fixture/oracle checks for navigation commands;
+- an optional real-repository calibration script using temporary caches;
+- fail-closed mixed-language indexing with explicit partial opt-in;
+- Rust path-qualified lookup and call-graph regression coverage;
+- candidate/disclaimer language for heuristic commands; and
+- optional timing and index-size metadata.
+
+Those checks prove that selected commands retrieve expected source and graph
+facts. They do not certify health-finding precision or recall, which is the
+active program above.
+
+## Program Closure
+
+Language detectors, composite workflows, navigation answers, and operational
+state transitions have terminal verdicts under their current capabilities.
+The final full repository verification passed, and certified evidence views are
+ready for a capability-aware private cloud shadow. The aggregate health score
+remains experimental and must not drive a public cross-language leaderboard.
+
+## Progress — 2026-07-10
+
+The first TypeScript dead-code baseline is complete:
+[`2026-07-10-typescript-dead-certification-baseline.md`](./validation/2026-07-10-typescript-dead-certification-baseline.md).
+Across 78 deterministic rows from Vega_2.0, openwork, Stable_Management, and
+traceroot, 25 were valid and 53 invalid: 32.1% observed precision with a 95%
+Wilson interval of 22.7%–43.0%. The detector remains experimental.
+
+Those five causes were fixed, and a second review exposed React lifecycle,
+implemented-protocol, and nested Next.js proxy roots. The final certificate is
+recorded in
+[`2026-07-10-typescript-dead-certification.md`](./validation/2026-07-10-typescript-dead-certification.md).
+The final fixed-seed sample contained 43 valid findings and zero invalid
+findings across four repositories: 100% observed precision with a 91.8% 95%
+Wilson lower bound, plus three positive-recall fixtures. TypeScript `dead` is
+therefore certified under its repository-dead truth rule. This does not certify
+Rust, Python, other TypeScript detectors, or the aggregate health score.
+
+The Rust `dead` baseline and hardening replay are also complete:
+[`2026-07-10-rust-dead-certification-baseline.md`](./validation/2026-07-10-rust-dead-certification-baseline.md)
+and
+[`2026-07-10-rust-dead-certification.md`](./validation/2026-07-10-rust-dead-certification.md).
+The baseline found 1 valid and 51 invalid rows. Cargo library rooting and an
+explicit `implicit-usage` signal tier removed every reviewed false positive;
+the pinned replay produced three valid findings and zero invalid findings.
+That is 100% observed precision, but the 43.8% Wilson lower bound and
+one-repository finding sample are too small for certification. Rust `dead`
+therefore remains insufficiently evidenced and must not be presented as a
+public actionable metric. Three positive fixtures protect private-library and
+binary-only recall while the corpus is expanded.
+
+The TypeScript factual-detector campaign is complete:
+[`2026-07-10-typescript-factual-detectors.md`](./validation/2026-07-10-typescript-factual-detectors.md).
+`unused-imports` (59/59), `duplicate-bodies` (40/40), raw `complexity`
+(40/40), and `redundant-reexports` (40/40) are certified under their narrow
+fact rules. `unused-params`, `cycles`, `isolated`, `not-implemented`,
+`decorative-checkers`, and `test-quality` were audited and hardened but remain
+insufficiently evidenced because their surviving real-repository frames lack
+the required row count or repository breadth. The campaign removed import-use,
+ambient dependency-edge, framework-contract, re-export-attribution,
+delegated-checker, and implicit-test-assertion false-positive archetypes.
+
+The TypeScript general-similarity campaign is also complete:
+[`2026-07-10-typescript-similarity-detectors.md`](./validation/2026-07-10-typescript-similarity-detectors.md).
+The `similar`, `similar-files`, and `similar-signatures` relationship claims are
+certified at 36/36, 40/40, and 40/40 valid rows across four repositories.
+`similar-chains` is qualified because its correct 40/40 sample came from a
+bounded 500-path input frame, and none of its sampled consolidation advice was
+actionable. `twin-drift` is qualified at 37/40 (92.5%) after constant,
+near-name, test-helper, and convention-only filtering. `recent-duplicates` is
+8/8 after generic React-plumbing hardening but remains insufficiently
+evidenced. The campaign now records factual relationship validity separately
+from recommendation utility.
+
+The initial TypeScript architecture/history campaign is complete:
+[`2026-07-10-typescript-architecture-history-detectors.md`](./validation/2026-07-10-typescript-architecture-history-detectors.md).
+The `co-change`, `doc-drift`, and `stale-abstractions` relationship claims are
+certified at 40/40 valid rows across four repositories. `drift` is qualified at
+40/40 because the population was 39 pattern deviations, one inferred layer,
+and a supported zero for unused-import rows; none of the sampled drift advice
+was actionable without ownership evidence. The initial packet qualified
+`wrapper-candidates` at 30/30 and left `passthrough-candidates` insufficient at
+21/21. The 2026-07-11 renewal expanded those samples to 60/60 and 41/41 valid
+relationships across three repositories, certifying both narrow facts. Removal
+utility remains contextual. The campaign removed ambient-declaration,
+generated co-change state, and structural-token feature-label noise.
+
+The initial TypeScript extraction and graph-risk campaign is complete:
+[`2026-07-10-typescript-extraction-graph-risk-detectors.md`](./validation/2026-07-10-typescript-extraction-graph-risk-detectors.md).
+`extract-candidates`, `locality-candidates`, `coupling`, `deep-chains`,
+`complexity-hotspots`, `hotspots`, `fan-in`, and `fan-out` are certified on
+43-48 valid sampled rows across four repositories. `bottlenecks` is qualified
+at 33/33 because its 89.6% confidence floor remained just below the certified
+threshold. The 69,942-row uncapped frame exposed and removed ambiguous
+shortened fan-in identities and cycle-inflated dependency depth. These results
+certify the disclosed measurements, not automatic refactoring actionability.
+
+The bottleneck population renewal is complete:
+[`2026-07-11-typescript-bottlenecks-certification.md`](./validation/2026-07-11-typescript-bottlenecks-certification.md).
+The public result now discloses the deterministic caller-file and
+external-callee sets behind its totals. All 39 reviewed rows passed arithmetic
+and pinned-source checks across four repositories, producing a 91.0% Wilson
+lower bound and certifying the narrow graph fact. Centrality remains a review
+signal rather than evidence that refactoring is beneficial.
+
+The React and Vue framework-detector campaign is complete:
+[`2026-07-11-react-vue-detectors.md`](./validation/2026-07-11-react-vue-detectors.md).
+React component duplication, hook candidates, and component pressure are each
+certified at 48/48 valid rows across three repositories. Vue component
+duplication is certified at 41/41 across four repositories, composable
+candidates at 48/48 across three repositories with findings, and view pressure
+at 64/64 across four repositories. The 54,586-row combined uncapped frame
+removed unqualified dominant-pressure axes, nested-component route-page
+misclassification, and unreproducible similarity-score totals. All sampled
+refactoring advice remained non-actionable without local design context.
+
+The same campaign's initial `augment-vue` runs reported 66,396 SFC mentions in
+Stable_Management and 13,700 in on_main_mvp. Those totals established the
+operational path but were not an accuracy certificate. Missing project files
+no longer abort the whole run, and the reliable single-context resolver is the
+default after parallel worker stalls reproduced at two, four, and eight
+workers. Ordinary `reindex` does not run this optional augmentation.
+
+The completed Vue reference-completeness audit is recorded in
+[`2026-07-11-vue-reference-completeness.md`](./validation/2026-07-11-vue-reference-completeness.md).
+It found that the earlier totals collapsed local SFC bindings onto component
+symbols, attributed properties to nearby callables, and counted module-path
+fragments. After hardening, an exact import/component oracle matched all 841
+reviewed mentions across Stable_Management, on_main_mvp, and agent_chat. The
+command is qualified for cross-file component identity; broader local and
+property identity is withheld and explicitly unsupported.
+
+The `twin-ab` generated-scaffold audit is complete:
+[`2026-07-11-twin-ab-generated-scaffold.md`](./validation/2026-07-11-twin-ab-generated-scaffold.md).
+Three pinned TypeScript repositories produced importable real-callable
+scaffolds with zero scaffold-local compiler diagnostics. The audit found and
+fixed a shared export-classification defect where an adjacent exported
+declaration made a following private callable look exported; the two real
+private pairs now refuse, and focused regression coverage preserves that
+boundary.
+
+The low-population TypeScript factual renewal is also complete:
+[`2026-07-11-typescript-factual-evidence-renewal.md`](./validation/2026-07-11-typescript-factual-evidence-renewal.md).
+All 25 emitted rows were valid across the four-repository replay, including four
+newly reviewed mock-echo facts. `unused-params`, `cycles`, `isolated`,
+`not-implemented`, `decorative-checkers`, and `test-quality` remain
+insufficient because their natural populations still fail sample-size or
+repository-breadth gates; they should be renewed only when a named new corpus
+adds the missing population.
+
+The wrapper/passthrough population renewal is complete:
+[`2026-07-11-typescript-wrapper-passthrough-certification.md`](./validation/2026-07-11-typescript-wrapper-passthrough-certification.md).
+Independent unbounded reference checks validated all 60 wrapper rows, and
+source review validated all 41 passthrough rows. Both relationship claims are
+now certified; automatic removal remains unsupported without local boundary
+evidence.
+
+The recent-duplicates population expansion is complete:
+[`2026-07-11-typescript-recent-duplicates-expansion.md`](./validation/2026-07-11-typescript-recent-duplicates-expansion.md).
+All eight natural findings passed pinned source, shared-evidence, and
+file-addition-history checks across four repositories with findings. Two more
+repositories produced supported zeros, and one repository's indexing failure
+remained explicit rather than becoming a zero. The 67.6% confidence floor is
+still insufficient, so renewal is terminal for this named corpus and should
+resume only when another corpus or historical snapshot adds findings.
+
+The widened Rust dead-code population replay is complete:
+[`2026-07-11-rust-dead-expansion.md`](./validation/2026-07-11-rust-dead-expansion.md).
+Five of six pinned repositories completed with indexing, source, semantic, and
+checker capability; one indexing failure stayed explicit. The only three
+natural findings again came from VegaAssistant and were all valid. Four
+supported zeros cannot raise the 43.9% confidence floor, so Rust `dead` remains
+insufficient and is terminal for this named corpus.
+
+The Python detector campaign is complete under the current capability boundary:
+[`2026-07-11-python-detector-certification.md`](./validation/2026-07-11-python-detector-certification.md).
+`scip-python-plus` and source facts were available, but no Python semantic
+provider or type-aware checker existed. The renewal corrected convention
+dunders, transitive Pydantic model liveness, runtime protocol hooks, and
+literal `__all__` export/import behavior. The Flask holdout retained 29
+file-internal and two signature relationships while reporting zero
+repository-dead rows. Every Python matrix row is now qualified, insufficient,
+or unsupported; none is certified for public actionable scoring.
+
+The composite workflow campaign is complete:
+[`2026-07-11-composite-workflow-certification.md`](./validation/2026-07-11-composite-workflow-certification.md).
+All 166 targeted cleanup, diff-gate, health, effectiveness, and impact probes
+passed. A mixed Python replay exposed that health omitted capability state and
+turned contextual relationships into action language. Health now carries the
+live capability matrix, marks its score experimental and non-comparable across
+languages, distinguishes syntax-only verification, and describes candidates as
+investigations rather than automatic refactorings. Diff-gate and impact
+workflows are qualified under their per-check evidence; only exact configured
+coverage-contract comparison is certified in this slice.
+
+The navigation and graph-answer campaign is complete:
+[`2026-07-11-navigation-graph-certification.md`](./validation/2026-07-11-navigation-graph-certification.md).
+All 107 exact-answer probes passed across 14 fixture files, and a live replay
+kept definition ranges, imports, references, dependencies, calls, slices,
+outlines, and counts mutually consistent. The audit corrected reference-only
+imports, type owners, and module owners appearing as callable callers. It also
+records that hierarchy is lexical, dataflow is reference-level, overload
+selection and inheritance are unsupported, and semantic cross-language edges
+exist only when an upstream indexer emits them.
+
+## Program Acceptance Criteria
+
+- Every health detector-language pair has a visible certification state.
+- Public actionable findings meet the certified threshold; public signals
+  meet the qualified threshold; lower-precision rows remain private.
+- Precision samples span at least three repositories, and recall has
+  known-positive evidence.
+- False positives are tracked as named archetypes with regression coverage,
+  not hidden by unreasoned suppressions.
+- Unsupported and degraded analyses cannot appear as zero findings.
+- Rust exclusions and framework-specific applicability are reported rather
+  than silently improving comparative results.
+- Python does not make strong semantic health claims until the required
+  provider and checker evidence exists.
+- Public comparisons are reproducible, versioned, coverage-aware, and limited
+  to comparable cohorts.
+- `npm test`, `npm run typecheck`, and `npm run build` pass after each
+  implementation slice.
+- Current changes use native tests plus the relevant `context`, `diff-impact`,
+  `architecture`, or detector command. No codebaseiq command declares an
+  arbitrary coding task complete.

package/docs/analyzer-inventory.md

@@ -0,0 +1,78 @@
+# Analyzer inventory
+
+This inventory describes the current analysis product. Historical validation
+records may name commands that no longer exist; use this file and the generated
+[command reference](COMMAND_REFERENCE.md) for the live surface.
+
+An analyzer is a program that derives repository facts or maintenance leads
+from indexed code, source text, configuration, or version history. A direct
+finding identifies a local condition that normally has a concrete repair. A
+signal identifies evidence that needs inspection before a repair can be chosen.
+Support analysis maps code without claiming that the mapped code is defective.
+
+## Support analysis
+
+- `context` gathers one target's definitions, references, callers, callees,
+  dataflow, slices, affected consumers, change risk, dependencies, public
+  surface, complexity, history, suppressions, and possible reuse sites.
+- Navigation commands such as `code`, `refs`, `call-graph`, `dataflow`, `slice`,
+  `deps`, `rdeps`, `system`, and `surface` answer narrower questions.
+- `diff-impact` maps the current change to affected symbols, tests, consumers,
+  and risk. It does not approve or reject the change.
+- `architecture` checks declared boundaries and dependency rules.
+
+## General cleanup analyzers
+
+These commands report direct findings or bounded maintenance leads:
+
+- dead code and unused inputs: `dead`, `unused-imports`, `unused-params`,
+  `stale-abstractions`;
+- duplication and drift: `similar`, `similar-files`, `similar-signatures`,
+  `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`;
+- migration and documentation: `incomplete-migration`, `doc-drift`,
+  `redundant-reexports`;
+- history and coordination: `co-change`, `change-surface`.
+
+## React analyzers
+
+- `react-component-duplicates`
+- `react-hook-candidates`
+- `react-large-component-pressure`
+
+## Vue analyzers
+
+- `vue-component-duplicates`
+- `vue-composable-candidates`
+- `vue-large-view-pressure`
+
+Vue indexing and source augmentation remain first-class parts of the product.
+React and Vue findings are also represented in `health`.
+
+## Repository health
+
+`health` combines general, React, and Vue detector families into one review
+report. It is a maintenance scan, not a completion authority. Its score and
+actions help choose cleanup work; they do not prove that an arbitrary coding
+task is complete.
+
+`health --write-baseline` records the current finding identities.
+`health --baseline` reports findings that are new relative to that baseline.
+This is an optional repository ratchet, not a required agent ceremony.
+
+## Suppressions
+
+Structured suppression files record reviewed findings under
+`.codebaseiq/suppressions/`. They are loaded with project analysis, counted in
+health and context, and validated by `config-validate`. Inline
+`codebaseiq: ignore-*` comments remain visible to the suppression inventory.
+
+## Evidence limits
+
+Each command reports or documents its coverage as complete, bounded, sampled,
+or unknown. A complete transport only means that every rendered character was
+retrieved. It does not turn bounded analysis into an exhaustive repository
+claim.

package/docs/analyzer-validation-protocol.md

@@ -0,0 +1,84 @@
+# Analyzer validation protocol
+
+This protocol tests whether codebaseiq 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.
+
+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.
+
+## Required evidence
+
+For each detector family, use at least:
+
+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.
+
+Do not score a detector by output volume. Count correct findings, incorrect
+findings, missed known cases, time, and output size separately.
+
+## Mapping commands
+
+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:
+
+- 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.
+
+## Cleanup commands
+
+For dead code, duplication, drift, extraction, wrappers, migration residue, and
+documentation findings, record:
+
+- 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.
+
+## React and Vue
+
+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.
+
+## Architecture
+
+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.
+
+## Health
+
+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?
+
+## Agent-effectiveness trials
+
+To test whether the product helps an agent, run matched control and treatment
+tasks in separate disposable copies of the same fixture:
+
+- 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
+  codebaseiq 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.
+
+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.