scip-query 0.10.12 → 0.11.0

package/docs/AGENT_GUIDE.md

@@ -3,6 +3,7 @@
 Goal-oriented workflows for AI agents and developers. Each section starts with a goal and walks through the exact commands to run, what to expect back, and how to use the results.
 
 For command syntax and options reference, see [Command Reference](COMMAND_REFERENCE.md).
+For analyzer implementation work, follow [Regex Policy](REGEX_POLICY.md): regex is kept for flat machine-generated strings, while structured inputs should use available parsers and disclose fallback paths.
 
 ---
 
@@ -14,25 +15,24 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 1. **Run setup**
    ```bash
-   scip-query setup-hooks --json
    scip-query setup --json
    ```
-   Returns: project-local hook install state, detected languages, indexer readiness, remediation attempts, index result, capability summary, smoke tests, health score, issue list, health dossier paths, and setup verdict.
+   Returns: detected languages, indexer readiness, remediation attempts, index result, capability summary, project-local hook install state, smoke tests, health score, issue list, health dossier paths, and setup verdict. Use `scip-query setup --no-hooks --json` when the repo should not write Codex or Claude Code lifecycle hooks.
 
 2. **Resolve blockers**
    ```bash
-   scip-query check-deps
    scip-query doctor
-   scip-query capability-matrix --json
+   scip-query status --json
+   scip-query capabilities --matrix
    ```
-   Missing indexers or toolchains are blockers, not clean results. Fix what setup can prove, then rerun setup or reindex.
+   `doctor` is the human diagnostic. `status --json` is the machine-readable freshness/config surface. `check-deps` and `capability-matrix` remain compatibility aliases, but new workflows should prefer `doctor`, `status`, and `capabilities --matrix`.
 
 3. **Start health follow-through**
    ```bash
-   scip-query health --json --full
+   scip-query health --json
    scip-query diff-gate --json
    ```
-   Before cleanup, tell the user the health score, confirmed items, unavailable checks, and recommended first cleanup batch. Use `scip-health-audit` for confirmation and `scip-health-improve` when the user wants autonomous score improvement.
+   Before cleanup, tell the user the health score, confirmed items, unavailable checks, and recommended first cleanup batch. Use `scip-cleanup-audit` for confirmation and `scip-cleanup-improve` when the user wants autonomous score improvement.
 
 ### What you should know after this workflow
 
@@ -178,17 +178,19 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 ### Steps
 
+Numeric thresholds below are recommended starting points for review sessions; command defaults may differ.
+
 1. **Get the full health report**
    ```bash
    scip-query health
    ```
    This runs every analysis and produces a prioritized action list. Start here. The actions are sorted by impact/effort ratio — do the top ones first.
 
-2. **Delete dead code (safest, highest impact)**
+2. **Review dead-code candidates**
    ```bash
    scip-query dead --min-loc 10 --skip-barrels
    ```
-   These symbols have zero cross-file references. They can be safely deleted. `--skip-barrels` ignores references from inactive barrel files, which helps surface exports kept alive only by unused re-export layers without hiding live package entry surfaces.
+   These symbols have zero cross-file references. Treat them as deletion candidates and confirm with `cleanup-plan --verify` before deleting. `--skip-barrels` ignores references from inactive barrel files, which helps surface exports kept alive only by unused re-export layers without hiding live package entry surfaces.
 
 3. **Delete isolated symbols**
    ```bash
@@ -233,9 +235,9 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 9. **Fix pattern drift**
    ```bash
-   scip-query drift
+   scip-query drift --patterns
    ```
-   Files that deviate from their directory's typical dependency pattern. Bring them into line with their neighbors.
+   Files that deviate from their directory's typical dependency pattern. Bring them into line with their neighbors. `--patterns` is opt-in (off by default since 21.2 calibration found this channel low-precision at scale) — treat hits as leads to confirm, not findings.
 
 10. **Remove redundant re-exports**
     ```bash
@@ -253,8 +255,8 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 | Priority | What | Why |
 |---|---|---|
-| 1 | Dead code | Zero risk, immediate LOC reduction |
-| 2 | Isolated symbols | Zero risk, zero consumers |
+| 1 | Dead code | High-confidence deletion candidates; verify before deleting |
+| 2 | Isolated symbols | Zero indexed consumers; verify before deleting |
 | 3 | Circular deps | Structural fix, prevents future problems |
 | 4 | Similar functions | Reduces duplication, use `convergence` for prescription |
 | 5 | Extraction candidates | Reduces function complexity |
@@ -296,9 +298,9 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 5. **Structural drift**
    ```bash
-   scip-query drift
+   scip-query drift --patterns
    ```
-   Files with unused imports, layer violations, or dependency profiles that deviate from their neighbors.
+   Files with unused imports, layer violations, or dependency profiles that deviate from their neighbors. `--patterns` opts into the deviation channel (off by default since 21.2 calibration); layer violations and unused imports print either way.
 
 ### Quality report template
 
@@ -346,10 +348,10 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 
 3. **Re-check structural drift around the changed area**
    ```bash
-   scip-query drift
+   scip-query drift --patterns
    scip-query change-surface <changed-file>
    ```
-   Verify the change did not introduce new dependency-pattern outliers and understand the remaining blast radius.
+   Verify the change did not introduce new dependency-pattern outliers and understand the remaining blast radius. `--patterns` opts into the deviation channel (off by default since 21.2 calibration).
 
 ---
 
@@ -387,4 +389,4 @@ For command syntax and options reference, see [Command Reference](COMMAND_REFERE
 - **Run `diff-impact --json` before committing** — catches unexpected blast radius across downstream consumers
 - **Use `convergence` after `similar`** — `similar` finds the problem, `convergence` gives the solution
 - **Start cleanup with `health`** — it prioritizes for you so you don't have to decide what to fix first
-- **Scope commands with `-s`** — most commands accept `--scope <path>` to limit analysis to a specific module. Use this on large codebases to keep results focused.
+- **Scope where supported** — many cleanup and health commands accept `-s, --scope <path>`; navigation commands usually take a file, symbol, or module argument instead. Use the narrowest supported target on large codebases.

package/docs/AI_FAILURE_MODES.md

@@ -21,7 +21,9 @@ contradict each other.
 
 **The detector:** `recent-duplicates` makes similarity *directional* using git
 file ages - which side is the established original, which is the freshly-added
-echo:
+echo.
+
+Illustrative output:
 
 ```
 91%  ECHO  react-component  src/components/ProjectCardVisual.tsx  ProjectCardVisual  (added 62 commits ago)
@@ -135,7 +137,9 @@ is worse than none.
 
 **The detector:** `doc-drift` reads every doc's file citations *and* its
 co-change history, and flags docs whose referenced code kept changing after
-the doc stopped — including broken references to files that no longer exist:
+the doc stopped — including broken references to files that no longer exist.
+
+Illustrative output:
 
 ```
 staleness 94  product/domain-model.md
@@ -183,7 +187,9 @@ safe to remove.
 deleting batch 0 makes batch 1 dead, and the plan shows the cascade. Then
 `--verify` applies each batch in a throwaway git worktree and runs **your own
 compiler** (tsc, cargo, go, python oracles — differentially, so pre-existing
-errors don't drown the signal):
+errors don't drown the signal).
+
+Illustrative output:
 
 ```
 ── Batch 0: deletable now (graph-fact, 67 LOC) ──
@@ -216,7 +222,7 @@ scip-query plan-context <symbol-or-file>   # before the edit
 scip-query diff-impact --json              # after the edit
 ```
 
-The `concrete-plan` skill enforces this end-to-end: every step in a plan must
+The `scip-concrete-plan` skill enforces this end-to-end: every step in a plan must
 cite the scip-query command that verified it.
 
 ## 10. Slow quality decay nobody notices
@@ -248,12 +254,14 @@ The detectors only help if they run. Three layers, in increasing strength:
 bundled skills into `~/.agents/skills/`, `~/.claude/skills/`, and
 `~/.codex/skills/` — they update automatically with the package. Project setup
 writes reviewable repo-local hooks to `.codex/hooks.json` and
-`.claude/settings.json`, unless `SCIP_QUERY_SKIP_HOOK_INSTALL=1` is set. The
-hooks add scip-query context at session start, route prompts toward the right
-specialist, and run a safe Stop hook wrapper around the diff gate only for that
-repository. The Stop hook warns by default instead of blocking the agent; set
-`SCIP_QUERY_STOP_HOOK_MODE=feedback` to ask the agent to continue without a
-hook error, or `SCIP_QUERY_STOP_HOOK_MODE=block` to enforce the gate. Run
+`.claude/settings.local.json` by default; `setup-hooks --shared` opts into the
+tracked `.claude/settings.json`. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run
+`scip-query setup --no-hooks` to skip lifecycle hook setup. The hooks add
+scip-query context at session start, route prompts toward the right specialist,
+and run a safe Stop hook wrapper around the diff gate only for that repository.
+The Stop hook sends feedback to the agent by default; set
+`SCIP_QUERY_STOP_HOOK_MODE=warn` for warning-only output or
+`SCIP_QUERY_STOP_HOOK_MODE=block` to enforce the gate. Run
 `scip-query setup-hooks --json` to repair the current repo's hooks.
 
 **2. Project setup and guidance.** Run once per project:
@@ -268,17 +276,32 @@ commands, writes `docs/scip-query/health-dossier.md` and `.json`, reports the
 health score and items needing attention, and seeds a managed block in
 `AGENTS.md` plus a `CLAUDE.md` import shim.
 
-After setup, use `scip-health-audit` to confirm raw signals and
-`scip-health-improve` when the user wants the agent to fix the worst confirmed
+After setup, use `scip-cleanup-audit` to confirm raw signals and
+`scip-cleanup-improve` when the user wants the agent to fix the worst confirmed
 items until the health score is as high as reasonably possible.
 
 **3. The gate (enforcement).**
 
 ```bash
-scip-query diff-gate --json          # one command, every check above, scoped to the diff, exit 1 on findings
+scip-query diff-gate --json          # default diff-scoped checks, exit 1 on findings
+scip-query diff-gate --json --baseline  # include the health-baseline ratchet
 scip-query setup-agent --git-hook    # pre-commit backstop: fires whoever wrote the diff
 ```
 
+<!-- BEGIN GENERATED DIFF-GATE CHECKS -->
+| Check | What it catches | When it runs |
+| --- | --- | --- |
+| `echo` | Changed symbols that newly echo established code elsewhere. | Default diff gate. |
+| `incomplete-migration` | New helpers or abstractions wired into some sites while older inline sites remain. | Default diff gate. |
+| `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
+| `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
+| `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
+| `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
+| `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
+| `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |
+| `baseline` | New health finding identities compared with the committed health baseline. | Only with `diff-gate --baseline`. |
+<!-- END GENERATED DIFF-GATE CHECKS -->
+
 Every finding ships with a remediation an agent can act on without human
 triage. The installed Codex/Claude Stop hook uses the same diff-gate evidence,
 warns by default, and no-ops outside indexed scip-query workspaces, so global

package/docs/API.md

@@ -1,6 +1,6 @@
 # Programmatic API
 
-Every CLI command is also available as a TypeScript function. The `queries` namespace exports cover the public commands, including the `top*` variants of `fan-in`, `fan-out`, and `coupling`, plus `similarAll` for the cross-codebase mode of `similar`.
+Public query commands are also available as TypeScript functions. The `queries` namespace exports cover the analysis commands, including the `top*` variants of `fan-in`, `fan-out`, and `coupling`, plus `similarAll` for the cross-codebase mode of `similar`. Operational CLI commands such as `setup`, `doctor`, and `setup-hooks` remain runtime commands rather than query-library exports.
 
 ```typescript
 import { ScipDatabase, createGitignoreFilter } from 'scip-query';

package/docs/COMMAND_REFERENCE.md

@@ -48,7 +48,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `dead [scope]` | Find dead code and file-internal symbols (no cross-file consumers) | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json` |
 | `unused-imports <file>` | Find imports not referenced in the same file | `--full`<br>`--json` |
 | `isolated` | Find completely orphaned symbols (no references at all) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json` |
-| `similar [symbol]` | Find heuristic function similarity candidates from callee fingerprints | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--full`<br>`--json` |
+| `similar [symbol] [other]` | Find heuristic function similarity candidates from callee fingerprints | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--plan`<br>`--full`<br>`--json` |
 | `similar-files [file]` | Find heuristic similar-file candidates from dependency profiles | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-deps <n>`<br>`--full`<br>`--json` |
 | `react-component-duplicates [file]` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
 | `react-hook-candidates [file]` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
@@ -64,14 +64,17 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `recent-duplicates` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | `--window <n>`<br>`--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
 | `doc-drift [doc]` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | `-n, --limit <n>`<br>`--min-coupling <n>`<br>`--full`<br>`--json` |
 | `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `drift [module]` | Detect heuristic drift candidates: unused imports, layer violations, and pattern deviations | `--min-deviation <n>`<br>`--full`<br>`--json` |
-| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `drift [module]` | Detect heuristic drift candidates: unused imports and layer violations by default; pass --patterns for pattern deviations too | `--min-deviation <n>`<br>`--patterns`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
 | `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full`<br>`--json` |
+| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full`<br>`--json` |
 | `complexity-hotspots` | Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `convergence <symbol1> <symbol2>` | Show what a consolidated version of two similar functions would look like | `--full`<br>`--json` |
+| `convergence <symbol1> <symbol2>` | Deprecated alias for similar <symbol1> <symbol2> --plan | `--full`<br>`--json` |
 | `redundant-reexports` | Find barrel re-exports that nobody imports through | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `similar-signatures` | Find functions with near-identical type signatures (same shape) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `duplicate-bodies` | Find exact duplicate small-body candidates across files | `-s, --scope <path>`<br>`--max-loc <n>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `twin-drift` | Twin drift candidates: same-name (or near-name) functions across files with diverged bodies | `-s, --scope <path>`<br>`--min-similarity <n>`<br>`--include-homonyms`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `twin-ab <symbolA> <symbolB>` | Generate a behavioral A/B scaffold comparing two same-concept twins (scip-integrity-audit drill 5) — a ready-to-fill vitest file, not an auto-executor | `--out <path>`<br>`--force`<br>`--json` |
+| `similar-signatures` | Find functions with near-identical type signatures (same shape) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-shape-frequency <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
 
 ### Graph
 
@@ -93,10 +96,16 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>`<br>`--json` |
 | `change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | `--full`<br>`--json` |
 | `co-change [file]` | Files that change together in git history without a dependency edge — hidden coupling candidates | `--min-together <n>`<br>`-n, --limit <n>`<br>`--all`<br>`--full`<br>`--json` |
-| `diff-gate` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, uncited doc updates, unused params, new dead symbols; exit 1 on findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--baseline`<br>`--full`<br>`--skip <check>`<br>`--hook`<br>`--json` |
+| `diff-gate` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--baseline`<br>`--full`<br>`--skip <check>`<br>`--hook`<br>`--json` |
 | `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
 | `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>`<br>`--json` |
 
+### Formal Models
+
+| Command | Description | Options |
+|---|---|---|
+| `tla <operation> [spec]` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | `--map <file>`<br>`--config <file>`<br>`--checker <mode>`<br>`--tla-tools <jar>`<br>`--apalache <binary>`<br>`--length <n>`<br>`--timeout-ms <n>`<br>`--trace <file>`<br>`--next <operator>`<br>`--allow-unknown`<br>`--out <path>`<br>`--module-name <name>`<br>`--force`<br>`--full`<br>`--json` |
+
 ### Planning
 
 | Command | Description | Options |
@@ -116,19 +125,53 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | Command | Description | Options |
 |---|---|---|
 | `bench` | Benchmark indexing and command runtimes for this repository | `--json`<br>`--cold-index`<br>`--include-heavy`<br>`--command <cmd>`<br>`--timeout-ms <n>`<br>`--progress`<br>`--profile`<br>`--profile-out <path>` |
-| `install-skills` | Install skills (scip-query, scip-query-setup, scip-adoption, scip-health-audit, scip-health-improve, scip-hyper-optimization, scip-api-impact, concrete-plan, scip-ai-cleanup, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-debloat, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook) into Claude Code, Codex, and shared agent roots | - |
-| `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--json` |
+| `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots | - |
+| `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--shared`<br>`--remove`<br>`--force`<br>`--json` |
 | `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
-| `capabilities` | Report which evidence and verification capabilities are available in this project | `--json` |
-| `capability-matrix` | Report the evidence and verification capability matrix by language | `--json` |
+| `capabilities` | Report which evidence and verification capabilities are available in this project | `--matrix`<br>`--json` |
+| `capability-matrix` | Deprecated alias for capabilities --matrix | `--json` |
 | `init` | Create a .scipquery.json config file for this project | - |
 | `config-validate` | Validate .scipquery.json, including structured suppressions and declared coupling groups | `--json` |
 | `suppress <id>` | Record an accepted finding in .scipquery.json with a required reason | `--reason <text>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--json` |
 | `doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | `--json` |
-| `setup` | Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health | `--git-hook`<br>`--json` |
+| `setup` | Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health | `--git-hook`<br>`--no-hooks`<br>`--dossier-dir <path>`<br>`--json` |
 | `setup-agent` | Seed agent guidance for this project: AGENTS.md/CLAUDE.md block pointing agents at the scip-query skills and diff gate, plus an optional git pre-commit backstop | `--git-hook` |
 | `setup-ci` | Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests | `--force`<br>`--dry-run` |
-| `watch` | Watch for file changes and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>` |
+| `uninstall` | Remove scip-query-owned skill links, project hooks, and managed agent setup blocks | `--global`<br>`--project`<br>`--dry-run`<br>`--json` |
+| `watch` | Watch for file changes in the foreground and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>` |
 | `status` | Show index status for this project | `--json`<br>`--capabilities` |
 
 <!-- END GENERATED COMMAND REFERENCE -->
+
+## `analysisBudget` disclosure contract
+
+On a large index (`stats.symbols >= 25,000` or `stats.documents >= 2,500`), commands built on the
+shared `budgetedDbCommand`/`budgetedListCommand`/`budgetedTableCommand`/`budgetedReportCommand`/
+`budgetedGroupedByFileCommand`/`budgetedSectionedReportCommand` helpers (`src/runtime/commands/
+command-execution.ts`) automatically cap their candidate scan and disable semantic (ts-morph)
+enrichment, and — unless `--full` is passed — disclose the cap two ways: a stderr notice in human
+mode, and an `analysisBudget: { scanLimit, semanticEnrichment, reason }` key at the top level of
+the `--json` envelope (`printJsonEnvelope`, same file). This is a general-purpose seam, not
+diff-gate-specific: as of this writing it already covers `dead`, `unused-imports`, `isolated`,
+`extract-candidates`, `locality-candidates`, `similar`, `similar-signatures`, `drift`,
+`convergence`, `duplicate-bodies`, `twin-drift`, `cleanup-plan`, `cleanup-apply`,
+`recent-duplicates`, `unused-params`, `complexity-hotspots`, `complexity`, `bottlenecks`,
+`imports`, `refs`, `dataflow`, `slice`, `plan-context`, `change-surface`, `incomplete-migration`,
+`co-change`, `diff-gate`, and the React/Vue battery commands.
+
+Commands stay on the plain (unbudgeted) `dbCommand`/`listCommand`/`tableCommand`/`reportCommand`
+family — and so never emit `analysisBudget` — when their cost model has no candidate-count or
+semantic-enrichment knob for the budget to honestly describe: single-symbol/single-file lookups
+(`code`, `outline`, `fan-in`, `fan-out`, `coupling`, `twin-ab`), or whole-graph structural queries
+with their own independent bound (`cycles`, `deep-chains`). Adding the `analysisBudget` key to one of those
+without also making the underlying query respect `scanLimit`/`semantic` would disclose a cap that
+isn't real — forbidden by the same "no silent/false disclosure" rule this contract exists to
+enforce (see `docs/plans/2026-07-02-followups.md` items 6 and 9).
+
+Followup #6 closed the one confirmed gap in an otherwise-wired battery command: `co-change`
+(`src/runtime/query-commands/impact.ts`) used the plain `dbCommand` and never disclosed a budget,
+even though its per-pair classification loop in `queries.coChange`
+(`src/queries/impact/co-change.ts`) does real filesystem/graph work whose cost scales with
+candidate-pair count on a large repository. It now flows through `budgetedDbCommand` and
+`coChange` accepts a `scanLimit` option that truncates the (already priority-sorted) candidate
+pairs before classification, so the disclosed budget is truthful rather than cosmetic.

package/docs/DETECTOR_GUIDE.md

@@ -79,8 +79,25 @@ gaps:
 
 How to keep them straight: `drift` is structural and intra-code, `doc-drift`
 is prose-vs-code, `co-change` is code-vs-code where the connection exists only
-in commit history. The diff-gate runs all three angles scoped to your change
-(`doc-reference` and `co-change-partner` checks).
+in commit history. The diff gate includes doc/code and hidden-coupling coverage
+through the `doc-reference` and `co-change-partner` checks; run `drift`
+directly when you need directory-pattern or layer-policy analysis.
+
+<!-- BEGIN GENERATED DIFF-GATE CHECKS -->
+| Check | What it catches | When it runs |
+| --- | --- | --- |
+| `echo` | Changed symbols that newly echo established code elsewhere. | Default diff gate. |
+| `incomplete-migration` | New helpers or abstractions wired into some sites while older inline sites remain. | Default diff gate. |
+| `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
+| `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
+| `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
+| `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
+| `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
+| `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |
+| `baseline` | New health finding identities compared with the committed health baseline. | Only with `diff-gate --baseline`. |
+<!-- END GENERATED DIFF-GATE CHECKS -->
+
+Baseline identities use `detector:file:shortName`. File or symbol renames can legitimately show as one fixed baseline identity plus one new identity; update the baseline after reviewing intentional renames.
 
 ## Cluster 4 — "Nothing uses this" (the deadness family)
 
@@ -115,5 +132,5 @@ broad sweep on every diff; these are the targeted follow-ups.
 | Anything at all, before saying "done" | `scip-query reindex && scip-query diff-gate` |
 
 And before any non-trivial change: plan with `scip-query plan-context
-<target>` (or the `concrete-plan` skill, which requires a scip-query citation
+<target>` (or the `scip-concrete-plan` skill, which requires a scip-query citation
 for every claim in the plan).

package/docs/REGEX_POLICY.md

@@ -0,0 +1,34 @@
+# Regex Policy
+
+Regular expressions are pattern matchers over text. In this codebase, they are appropriate when the input is a flat machine-generated string whose structure is fully represented by local characters, and inappropriate when an available parser can expose the structure that gives the text its meaning.
+
+Use parsers for structured inputs when the parser is available:
+
+- Source code: use tree-sitter, ts-morph, Vue compiler APIs, or language-specific source readers before scanning syntax with regex.
+- TLA modules: use SANY-derived facts when the tools are available; regex model parsing is a disclosed fallback only.
+- Checker diagnostics: use each checker's structured output or documented diagnostic shape before falling back to generic line matching.
+- Markdown citations: use the existing citation context and citation-kind classifiers rather than broad path regexes alone.
+
+Regex remains the right tool for flat machine-generated strings:
+
+- SCIP symbol encodings in `src/symbols/symbol-parser.ts`.
+- SCIP row and descriptor filters in storage/query SQL when the pattern is static.
+- Path fragments and glob prefilters, followed by segment-aware matching when slash semantics matter.
+- Signature normalization in `src/queries/cleanup/similar-signatures.ts`.
+- Import path and source-text stripping helpers where the input is already a known lexical fragment.
+- Framework and file classifiers that match names, extensions, and conventional path segments.
+
+Retired or downgraded load-bearing regexes in the round-2 remediation:
+
+- Complexity branch counting now uses AST nodes when parsing succeeds; source regex counting is labeled `regex-fallback`.
+- `complexity-hotspots` uses the same branch estimate and no longer relies on size and fan metrics alone.
+- Scope filters in SQL queries now bind parameters instead of interpolating user text into `LIKE`.
+- `files` keeps SQL `LIKE` only as a prefilter and applies segment-aware glob matching in code.
+- Drift policy no longer turns an unlisted `src/*` layer into an explicit layer violation.
+- Cycles output discloses when DFS depth truncates the search.
+
+Future work already identified:
+
+- Health's fix-commit signal intentionally remains a subject-keyword regex until conventional-commit or issue-link evidence replaces it; output must disclose that basis.
+- Checker diagnostic extraction should prefer structured per-oracle parsers and label heuristic fallback.
+- TLA conformance should prefer SANY XML facts and label text parsing as `regex-fallback`.

package/docs/analyzer-inventory.md

@@ -20,15 +20,15 @@ The action tiers are:
 
 ## Current Surfaces
 
-The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet.
+The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet. The `tla` command is also ordered in that command registry as an on-demand formal-model verifier, not as a health-scored analyzer.
 
-`health --json` on this repository currently reports:
+An earlier `health --json` run on this repository reported:
 
 - score 100, riskScore 100, hygieneScore 100
 - zero active findings across all health phases
 - 174 suppression comments: 72 extract, 62 wrapper, 17 stale, 15 similar, 8 passthrough
 
-That suppression shape is evidence that broad candidate analyzers have historically produced enough accepted or false-positive results to need explicit maintainer judgment. The suppression lifecycle review confirmed the current source comments are recent and reasoned, while structured file-scoped suppressions now warn when their file path goes stale.
+That suppression shape was evidence that broad candidate analyzers had historically produced enough accepted or false-positive results to need explicit maintainer judgment. The suppression lifecycle review confirmed the source comments were recent and reasoned, while structured file-scoped suppressions now warn when their file path goes stale.
 
 The declared-coupling config has been refreshed after the inventory surfaced old pre-folder-move paths. `config-validate` now warns when a declared-coupling entry names a file that no longer exists, so known maintenance units stay connected to the current file graph instead of silently becoming stale metadata.
 
@@ -104,6 +104,8 @@ These commands analyze the index, but they are not finding detectors and should
 
 They are essential because other analyzers and agents use them to ground claims. Their defining characteristic is retrieval or explanation, not smell detection.
 
+`tla` is a formal-model verification command: it checks a TLA+ module, an explicit model-to-TypeScript mapping contract, and compiler-indexed code evidence in one on-demand run. Its defining role is to make model/code discrepancies reviewable before a user or agent treats the TLA+ model as an accurate description of the implementation.
+
 The support-analysis accuracy review confirmed that `refs`, `affected`, `change-surface`, `plan-context`, `imports`, `deps`, `rdeps`, `fan-in`, `fan-out`, `hotspots`, `status`, and `self-audit` return useful source-grounded evidence for a TypeScript target. It also fixed diagnostic parity so `status` and `doctor` use the same root-aware config validation as `config-validate`.
 
 The cross-language boundary review confirmed that Rust projects have graph-backed indexing, source fallback, cleanup detector output, git/diff support, and compiler cleanup verification when `rust-analyzer` and `cargo check` are available. It also confirmed that TypeScript semantic self-audit is explicitly unavailable on Rust and that React/Vue analyzers return stack-specific empty results rather than Rust findings.
@@ -201,3 +203,38 @@ citations remain accurate after the Git evidence product migration. Health
 still owns the composite phase inventory, and diff-gate still owns
 `DIFF_GATE_CHECKS`; both now obtain Git history facts through
 `gitEvidenceProduct()` instead of direct helper reads.
+
+## 2026-06-30 Health Cleanup Follow-Up
+
+The `src/queries/public-query-entries.ts` reference remains the public query
+manifest reference. Private query-helper coverage is now asserted as a
+CLI-contract test fixture in `tests/runtime/cli-contract.test.ts`, so the
+production manifest only exports the public entries and source paths used by
+packaging.
+
+2026-07-01 round-2 remediation note: the `src/queries/health/health.ts`
+guide reference remains current after the health output gained explicit
+validation-basis and source-facts disclosure fields. The analyzer inventory
+still points readers at the health command implementation that owns score
+phases, suppressions, and validation reporting.
+
+## 2026-07-01 Remediation Plan 3 Follow-Up
+
+The `src/queries/impact/diff-gate.ts` and `src/queries/health/health.ts`
+citations remain accurate after remediation plan 3 (detection primitives).
+`DIFF_GATE_CHECKS` gained `twin-partner` (advisory — a same-(near-)name twin
+left behind by a one-sided edit) and `coverage-contract` (enumeration-rot:
+a configured `coverageContracts` key set drifted from its ground-truth
+source). `HEALTH_PHASES` gained `coverage-contracts`. Both files still own
+their respective canonical lists; only the list contents grew.
+
+## 2026-07-02 Queued Enhancements Follow-Up
+
+The `src/queries/health/health.ts`, `src/queries/public-query-entries.ts`,
+and `src/runtime/commands/query-command-specs.ts` citations remain accurate
+after the queued-enhancements batch (Q1/Q4). `HEALTH_PHASES` gained
+`twin-drift` (divergent/identical same-name twin groups as a hygiene
+dimension), and the public command surface gained `twin-ab` (behavioral A/B
+scaffold generator for scip-integrity-audit drill 5) in `queryCommandOrder`
+and `PUBLIC_QUERY_ENTRIES`. All three files still own their respective
+canonical lists; only the list contents grew.

package/docs/analyzer-validation-ledger.md

@@ -14,10 +14,10 @@ The ledger is anchored to the current tool surface, not memory.
 
 | Surface                   | Source                                                                                                                                                                                                                                                                                                       | Why it anchors the ledger                                                                     |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:194`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()`.                                                                                                                                                          | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
-| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:94`, where `diffGate()` runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide.    | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
-| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:10`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:94`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                  |
-| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:27`, where the canonical diff-gate check list is exported.                                                                                                                                                              | The ledger must cover every change-time check that can block a diff.                          |
+| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:217`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()`.                                                                                                                                                          | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
+| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:228`, where `diffGate()` runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide.    | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
+| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:11`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:104`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                 |
+| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:64`, where the canonical diff-gate check list is exported.                                                                                                                                                              | The ledger must cover every change-time check that can block a diff.                          |
 
 ## Core Concepts
 
@@ -64,14 +64,15 @@ Closeout status: all active ledger rows are complete as of 2026-06-22. Remaining
 
 ## Public Command Coverage Checklist
 
-The canonical source is `src/runtime/commands/query-command-specs.ts:10-73`, where `queryCommandOrder` lists the public query command surface.
+The canonical source is `src/runtime/commands/query-command-specs.ts:11-78`, where `queryCommandOrder` lists the public query command surface.
 
 - Core and navigation support: `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, `slice`
 - Direct cleanup and deletion analyzers: `dead`, `isolated`, `unused-imports`, `cleanup-plan`, `unused-params`, `passthrough-candidates`, `redundant-reexports`
-- Similarity, reuse, extraction, and locality analyzers: `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `recent-duplicates`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `stale-abstractions`, `doc-drift`, `drift`, `convergence`
+- Similarity, reuse, extraction, and locality analyzers: `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `recent-duplicates`, `duplicate-bodies`, `twin-drift`, `twin-ab`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `stale-abstractions`, `doc-drift`, `drift`, `convergence`
 - Frontend analyzers: `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`
 - Graph, risk, and complexity analyzers: `hotspots`, `fan-in`, `fan-out`, `coupling`, `cycles`, `bottlenecks`, `deep-chains`, `complexity-hotspots`, `complexity`
 - Diff, impact, and planning analyzers: `affected`, `change-surface`, `co-change`, `diff-gate`, `incomplete-migration`, `plan-context`
+- Formal model verification: `tla`
 - Meta and action commands: `self-audit`, `cleanup-apply`
 
 ## Completed Run Batches
@@ -306,3 +307,30 @@ The `diffGate()` and health citations remain accurate after the Git evidence
 product migration. Default diff-gate still runs the same check family, and
 health still reports the same Git evidence summary; both paths now read Git
 history through `gitEvidenceProduct()`.
+
+2026-07-01 round-2 remediation note: the `src/queries/health/health.ts`
+configuration example remains current after the health command added
+validation-basis disclosure and parser-unavailable reporting. The validation
+ledger's health examples still cite the command surface that computes and
+renders those analyzer signals.
+
+## 2026-07-01 Remediation Plan 3 Follow-Up
+
+The `diffGate()` and health citations remain accurate after remediation plan 3
+(detection primitives). Default diff-gate now also runs `twin-partner`
+(advisory) and `coverage-contract`; `src/runtime/commands/query-command-specs.ts`
+still owns the public query order. Health gained a `coverage-contracts` phase
+and a `detectorPrecision` field (per-check finding-outcome stats from the new
+finding-outcome ledger) — both paths still compute and render through the same
+command surfaces cited above.
+
+## 2026-07-02 Doc-Reference Hub-Cascade Follow-Up
+
+The `diffGate()` and `DIFF_GATE_CHECKS` citations were refreshed (line anchors
+`diff-gate.ts:205` -> `:228` and `:62` -> `:64`) after followup #8 added
+hub-file cascade damping to the doc-reference check: when more than 3 docs
+cite the same changed hub file in one gate run, their findings collapse into
+one clustered finding carrying `citationCount`, up to 3 `citationExemplars`,
+and an explicit `suppressedCount`. Default diff-gate still runs the same
+check family through the same entry point; per-doc findings under the
+threshold are unchanged.