scip-query 0.19.6 → 0.19.10

package/docs/CLI_JSON_OUTPUT.md

@@ -1,4 +1,30 @@
-# CLI JSON output contract
+# CLI output modes
+
+Human output is the default for people and agents. It is the command-owned
+presentation: reports retain sections and whitespace, and `code` retains a
+path/range header, source indentation, and one-based line numbers. It omits
+transport metadata that does not help answer the command's question.
+
+Public commands that support structured output share the same three options:
+
+```text
+--json         Emit the stable versioned CLI envelope.
+--result-only  With --json, emit only the command-owned result.
+--compact      With --json, minify the selected JSON form for a program.
+```
+
+Use plain `--json` for an integration that depends on producer, schema,
+coverage, evidence, arguments, or invocation options. Use `--json
+--result-only` for a program that needs just the result. Agents should run the
+ordinary command instead; pretty JSON remains structurally noisier than the
+human renderer. Both modifiers are rejected without `--json`.
+
+For example, `scip-query code <symbol>` prints source directly. Its result-only
+form contains only `file`, resolved `symbol`, `language`, a one-based `range`,
+and ordered `{ line, text }` rows. Resolution alternatives are added only when
+the requested symbol is ambiguous.
+
+## Stable JSON envelope
 
 A CLI JSON envelope is the public transport record printed by a scip-query
 command when a caller selects `--json`. Its real-world units are the JSON
@@ -13,12 +39,12 @@ The current envelope is schema version 1:
 {
   "kind": "scip-query-result",
   "schemaVersion": 1,
-  "producer": { "name": "scip-query", "version": "0.19.6" },
+  "producer": { "name": "scip-query", "version": "0.19.10" },
   "command": "refs",
   "resultSchemaVersion": 1,
   "evidence": "graph-fact",
   "args": ["login"],
-  "options": { "json": true, "compact": true },
+  "options": { "json": true },
   "result": {},
   "coverage": {}
 }
@@ -37,6 +63,130 @@ The public `scip-query/runtime` export provides
 consumers that want the repository's compatibility policy rather than a
 hand-written field check.
 
+## Complete output for agents
+
+An output page is one consecutive, bounded part of the characters a command
+rendered. Its real-world units are the `scip-query-output-page` objects and
+human page blocks returned after a result exceeds an agent transport's safe
+size. It differs from a query limit because it divides already-produced
+output without discarding any character: following each emitted continuation
+command reconstructs the complete rendered stream.
+
+Every command accepts these global options:
+
+```text
+--output-page-size <characters>
+--output-cursor <cursor>
+```
+
+Run commands normally without choosing a page size. Human output larger than
+12,000 characters is paged automatically as ordinary multiline text, not as a
+JSON object. Each incomplete page prints one exact continuation command after
+its content. Agents must run that command unchanged until the output-complete
+marker. Supplying `--output-page-size` changes the character budget; it does
+not select JSON. The value counts rendered JavaScript string characters, not
+rows, results, model tokens, or bytes. If the complete result fits, scip-query
+returns it unchanged and removes the temporary snapshot; a page wrapper exists
+only when more content remains. Partial human pages end at the last complete
+line within that budget whenever one exists, so the next page begins with its
+own heading or source line number; a single line longer than the budget is the
+only case that requires a character-boundary split. Do not pipe scip-query
+through `head`, `tail`, or a line-range `sed`; those programs discard output
+without creating a resumable position.
+
+Default `--json` output remains the ordinary, additively extensible
+`scip-query-result` envelope. When that envelope exceeds
+12,000 characters, scip-query writes an early stderr warning containing the
+exact command that opts into output pages. The paged command returns:
+
+```json
+{
+  "kind": "scip-query-output-page",
+  "schemaVersion": 1,
+  "producer": { "name": "scip-query", "version": "0.19.10" },
+  "command": "architecture",
+  "contentType": "application/json",
+  "agentInstruction": "INCOMPLETE EVIDENCE: do not draw conclusions or report completion from this partial page. Run page.continuation.command exactly, then repeat until page.complete is true.",
+  "page": {
+    "offset": 0,
+    "returnedCharacters": 12000,
+    "totalCharacters": 48152,
+    "omittedCharacters": 36152,
+    "remainingCharacters": 36152,
+    "complete": false,
+    "outputHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "continuation": {
+      "cursor": "<opaque cursor>",
+      "command": "scip-query architecture --json --output-page-size 12000 --output-cursor <opaque cursor>"
+    }
+  },
+  "content": "{\n  \"kind\": \"scip-query-result\",\n  ..."
+}
+```
+
+The cursor is bound to the executable or package-runner prefix, command,
+working directory, complete non-pagination argument list, immutable page
+number and size, private output snapshot, and SHA-256 of the complete rendered
+output. The initial capture records that invocation identity plus each page's
+UTF-8 byte range and hash. A continuation reads and verifies only that range,
+so retrieving all pages performs linear snapshot I/O and never re-runs the
+command. A changed executable identity, page, page size, missing snapshot, or
+expired snapshot is rejected with the exact page-one restart command using the
+same prefix that created it.
+
+A genuinely partial JSON page must carry `content` as a string because an
+arbitrary character boundary is not necessarily valid nested JSON. Run the
+emitted continuation exactly until completion. Normal agent work should use
+human output, where partial pages remain multiline text rather than a JSON
+string.
+
+One snapshot is bounded to 32 million characters, 64 MiB, and 32,768 pages.
+The per-user pool is bounded to 32 snapshots and 256 MiB under atomic
+reservation. Every incomplete machine-readable page carries a direct
+`agentInstruction`; consumers must follow `page.continuation.command` until
+`page.complete` is `true`.
+
+Output pages and result coverage answer different questions:
+
+- output pagination says whether every rendered character is retrievable;
+- the result envelope's `coverage` says whether the command examined every
+  logical result unit.
+
+A completely retrieved page can therefore still contain a bounded or sampled
+analysis. Use the result envelope's stated `--full` remediation when present,
+then follow output continuation commands until complete.
+
+Invocation coverage counts the semantic result units declared by the command
+descriptor. A list command counts top-level rows; a report counts one report;
+and a command with a named result field counts only that field. Unrelated
+diagnostic arrays do not inflate `returned`. Symbol-selecting commands also
+report a separate `coverage.resolution` state—`exact`, `ambiguous`, or
+`missing` with its candidate count—because resolving one requested identity
+and enumerating that identity's result rows are different completeness
+questions.
+
+`refs --limit <n>` uses a generation-bound keyset cursor: each ordinary page
+continues after the last returned `(relativePath, line)` and stops once it has
+found the requested rows plus one continuation witness. The JSON result reports
+`pagination.producer: "source-keyset"` for that bounded producer. Explicit
+semantic enrichment (`--full`), Ruby supplemental evidence, and the coarse SCIP
+chunk fallback cannot currently resume before complete materialization; those
+pages preserve their evidence but report
+`pagination.producer: "complete-only"` instead of implying that `--limit`
+bounded the analysis work. Version-1 offset cursors remain readable and their
+next continuation is upgraded to the version-2 keyset format. Every result
+cursor is rejected after the index generation changes.
+
+The machine-readable page schema is
+[`schemas/cli-output-page.schema.json`](schemas/cli-output-page.schema.json).
+Page sizes range from 256 through 100,000 characters and cursors are limited
+to 4,096 characters. The first paged invocation streams the complete output
+to a mode-`0600` snapshot beneath a current-user mode-`0700` temporary
+directory while retaining only the requested page in memory. Snapshots expire
+after one hour and are removed after the final page. Pagination imposes no
+arbitrary total-output ceiling and does not silently discard later pages;
+command-level result budgets still apply and report their own completeness.
+
 ## Compatibility policy
 
 The decoder accepts:
@@ -59,6 +209,29 @@ The committed v0 and v1 fixtures in `tests/fixtures/` prove that the newest
 decoder reads both generations. The v1 fixture also contains an unknown
 additive field so tests prove tolerant reads rather than exact-key coupling.
 
+## Effectiveness telemetry authority
+
+`effectiveness --json` reports both handling outcomes and the authority of the
+observer that produced them. Repository-local agents and humans can edit the
+same `.scipquery/events/` and suppression files being summarized, so their
+rows use `authority: "local-writable-telemetry"` and expose
+`resolutionVsSuppressionRate`. The legacy `precision` result field remains
+present but is `null` for writable, mixed, or self-asserted populations. It is
+numeric only when every event in that population is a `protected-ci`
+observation with `protected-external` authority and the caller supplies its
+gate-run ID through a separately controlled attestation set. The built-in
+repository-history command supplies no such set, so writable JSON cannot
+self-promote into an independent grade. External evaluators can call the
+public `computeEffectiveness()` export from `scip-query/queries` with
+`protectedGateRunIds` obtained from their separately controlled corpus.
+
+The result also includes observer counts, distinct and missing gate-run
+identities, and bounded anomaly samples. Those samples identify calibration
+work without requiring a human to approve every ordinary automated
+suppression. `recordCompatibility.outcomeEvents` remains the independent
+statement about whether every event file was readable; neither compatibility
+nor Git can prove that a writable event file was never deleted.
+
 ## Other JSON protocols
 
 The hidden `__health-phase` and `__diff-impact-batch` commands are

package/docs/COMMAND_REFERENCE.md

@@ -4,13 +4,15 @@
 
 This syntax summary is generated from the CLI command descriptors. Keep workflow guidance hand-authored, but keep command syntax, descriptions, and option flags descriptor-owned.
 
-Commands with `--json` emit the versioned public envelope documented in [CLI JSON output contract](CLI_JSON_OUTPUT.md).
+Commands with `--json` share three structured modes: plain `--json` emits the stable public envelope, `--json --result-only` emits only the command payload, and `--json --compact` minifies either form for a program. Agents should prefer ordinary human output. See [CLI output modes](CLI_JSON_OUTPUT.md).
+
+Every command accepts `--output-page-size <characters>` and `--output-cursor <cursor>`. Run normally without choosing a page size: oversized human output stays readable text and prints one exact continuation command; oversized JSON prints the exact command that opts into versioned JSON page envelopes.
 
 ### Indexing
 
 | Command | Description | Options |
 |---|---|---|
-| `reindex` | Index the codebase and convert to SQLite | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--indexer-concurrency <n>`<br>`--json` |
+| `reindex` | Index the codebase and convert to SQLite | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--trust-project-tools`<br>`--install-missing`<br>`--indexer-concurrency <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table | - |
 | `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar | `--project <tsconfig>` |
 
@@ -18,136 +20,136 @@ Commands with `--json` emit the versioned public envelope documented in [CLI JSO
 
 | Command | Description | Options |
 |---|---|---|
-| `stats` | Show index statistics | `--json` |
+| `stats` | Show index statistics | `--json`<br>`--result-only`<br>`--compact` |
 
 ### Navigation
 
 | Command | Description | Options |
 |---|---|---|
-| `files <pattern>` | Find files matching a pattern | `--json` |
-| `methods <className>` | List methods of a class (with line ranges) | `--json` |
-| `refs <symbol>` | Find all files referencing a symbol | `--full`<br>`-n, --limit <n>`<br>`--cursor <cursor>`<br>`--json`<br>`--compact` |
-| `trace <symbol>` | Trace a symbol: definition + all references | `--full`<br>`--compact`<br>`--json` |
-| `deps <file>` | Files this file depends on (internal) | `--json` |
-| `rdeps <file>` | Files that depend on this file/module | `--json` |
-| `system <module>` | Full module map: files, symbols, deps in/out | `--compact`<br>`--json` |
-| `surface <module>` | What symbols consumers actually use from this module | `--json` |
-| `imports <file>` | What symbols does this file import? | `--full`<br>`--json` |
-| `imported-by <symbol>` | Which files import this symbol? | `--json` |
-| `outline <file>` | Tree view of symbols in a file, with line ranges | `--signatures`<br>`--json` |
-| `members <symbol>` | All children of a symbol (methods, fields, nested types) | `--json` |
-| `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `kind-counts` | Histogram of symbol kinds in the codebase | `-s, --scope <path>`<br>`--json` |
-| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | `--json` |
-| `code <symbol>` | Read the source code for a symbol (bounded to its definition range) | `-C, --context <n>`<br>`--json` |
-| `dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | `--full`<br>`--json` |
-| `slice <symbol>` | Reference-level program slice: what affects this (backward) or what this affects (forward) | `--forward`<br>`--depth <n>`<br>`--full`<br>`--json` |
+| `files <pattern>` | Find files matching a pattern | `--json`<br>`--result-only`<br>`--compact` |
+| `methods <className>` | List methods of one exactly resolved class; ambiguity and missing targets fail explicitly | `--json`<br>`--result-only`<br>`--compact` |
+| `refs <symbol>` | Find all files referencing a symbol | `--full`<br>`-n, --limit <n>`<br>`--cursor <cursor>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `trace <symbol>` | Trace a symbol: definition + all references | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `deps <file>` | Files this file depends on (internal) | `--json`<br>`--result-only`<br>`--compact` |
+| `rdeps <file>` | Files that depend on this file/module | `--json`<br>`--result-only`<br>`--compact` |
+| `system <module>` | Full module map: files, symbols, deps in/out | `--json`<br>`--result-only`<br>`--compact` |
+| `surface <module>` | What symbols consumers actually use from this module | `--json`<br>`--result-only`<br>`--compact` |
+| `imports <file>` | What symbols does this file import? | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `imported-by <symbol>` | Which files import this symbol? | `--json`<br>`--result-only`<br>`--compact` |
+| `outline <file>` | Tree view of symbols in a file, with line ranges | `--signatures`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `members <symbol>` | All children of a symbol (methods, fields, nested types) | `--json`<br>`--result-only`<br>`--compact` |
+| `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `kind-counts` | Histogram of symbol kinds in the codebase | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | `--json`<br>`--result-only`<br>`--compact` |
+| `code <symbol>` | Read the source code for a symbol (bounded to its definition range) | `-C, --context <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `slice <symbol>` | Reference-level program slice: what affects this (backward) or what this affects (forward) | `--forward`<br>`--depth <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Cleanup
 
 | Command | Description | Options |
 |---|---|---|
-| `dead [scope]` | Find repository-dead code, file-internal symbols, and implicit-usage signals | `--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] [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` |
-| `react-large-component-pressure [file]` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | `--min-component-lines <n>`<br>`--min-file-lines <n>`<br>`--min-jsx-tokens <n>`<br>`--min-behavior-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `vue-component-duplicates [file]` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `vue-composable-candidates [file]` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `vue-large-view-pressure [file]` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts | `--min-total-lines <n>`<br>`--min-template-lines <n>`<br>`--min-script-lines <n>`<br>`--min-style-lines <n>`<br>`--review-thresholds`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>`<br>`--full`<br>`--json` |
-| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `locality-candidates [symbol-or-file]` | Find directory-locality and ancestry candidates from consumer ownership | `-s, --scope <path>`<br>`--min-consumers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verify`<br>`--patch`<br>`--json`<br>`--full` |
-| `cleanup-apply` | Apply a compiler-verified cleanup-plan batch to the working tree | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verified`<br>`--batch <n>`<br>`--all`<br>`--force-dirty`<br>`--full` |
-| `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 drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | `--min-deviation <n>`<br>`--patterns`<br>`--architecture`<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 (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>` | 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` |
-| `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-audit integrity scenario) — a ready-to-fill vitest file, not an auto-executor | `--out <path>`<br>`--force`<br>`--json` |
-| `not-implemented` | Reachable placeholder stub candidates (throw-stub, TODO+return-default, empty body) — production callers can actually reach these; an unreachable stub is dead's job, not this one's | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `decorative-checkers` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
-| `test-quality` | Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--rot-days <n>`<br>`--full`<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` |
+| `dead [scope]` | Find repository-dead code, file-internal symbols, and implicit-usage signals | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `unused-imports <file>` | Find imports not referenced in the same file | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `isolated` | Find completely orphaned symbols (no references at all) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `react-large-component-pressure [file]` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | `--min-component-lines <n>`<br>`--min-file-lines <n>`<br>`--min-jsx-tokens <n>`<br>`--min-behavior-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-component-duplicates [file]` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-composable-candidates [file]` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-large-view-pressure [file]` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts | `--min-total-lines <n>`<br>`--min-template-lines <n>`<br>`--min-script-lines <n>`<br>`--min-style-lines <n>`<br>`--review-thresholds`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `locality-candidates [symbol-or-file]` | Find directory-locality and ancestry candidates from consumer ownership | `-s, --scope <path>`<br>`--min-consumers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verify`<br>`--patch`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `cleanup-apply` | Apply a compiler-verified cleanup-plan batch to the working tree | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verified`<br>`--batch <n>`<br>`--all`<br>`--dry-run`<br>`--force-dirty`<br>`--full` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `drift [module]` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | `--min-deviation <n>`<br>`--patterns`<br>`--architecture`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `convergence <symbol1> <symbol2>` | Deprecated alias for similar <symbol1> <symbol2> --plan | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `redundant-reexports` | Find barrel re-exports that nobody imports through | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `twin-ab <symbolA> <symbolB>` | Generate a behavioral A/B scaffold comparing two same-concept twins (scip-audit integrity scenario) — a ready-to-fill vitest file, not an auto-executor | `--out <path>`<br>`--force`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `not-implemented` | Reachable placeholder stub candidates (throw-stub, TODO+return-default, empty body) — production callers can actually reach these; an unreachable stub is dead's job, not this one's | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `decorative-checkers` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `test-quality` | Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--rot-days <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
 
 ### Graph
 
 | Command | Description | Options |
 |---|---|---|
-| `hotspots` | Most-referenced symbols in the codebase (choke points) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `fan-in [symbol]` | Count files referencing an exact symbol; top JSON rows include exact symbol identity | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `coupling [file1] [file2]` | Coupling between two files, or top coupled pairs in codebase | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `cycles` | Detect circular dependency chains between files | `-s, --scope <path>`<br>`--max-depth <n>`<br>`--json` |
-| `architecture` | Evaluate project-owned architectural boundaries and dependency rules | `-s, --scope <path>`<br>`--json` |
-| `bottlenecks` | Find coupling hubs: high fan-in AND high fan-out | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full`<br>`--json` |
-| `deep-chains` | Find the longest condensed dependency-component chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--full`<br>`--json` |
-| `call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | `--full`<br>`--json` |
+| `hotspots` | Most-referenced symbols in the codebase (choke points) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `fan-in [symbol]` | Count files referencing an exact symbol; top JSON rows include exact symbol identity | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `coupling [file1] [file2]` | Coupling between two files, or top coupled pairs in codebase | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `cycles` | Detect circular dependency chains between files | `-s, --scope <path>`<br>`--max-depth <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `architecture` | Evaluate project-owned architectural boundaries and dependency rules | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `bottlenecks` | Find coupling hubs: high fan-in AND high fan-out | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `deep-chains` | Find the longest condensed dependency-component chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Impact
 
 | Command | Description | Options |
 |---|---|---|
-| `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: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; 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`<br>`--compact` |
-| `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` |
+| `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `change-surface <file>` | Pre-change briefing: consumers, published API, operational roots, and explained change risk | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `diff-gate` | Runtime-bounded, single-flight gate for the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; 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`<br>`--result-only`<br>`--compact` |
+| `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`<br>`--result-only`<br>`--compact` |
+| `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### 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>`--coverage`<br>`--allow-unknown`<br>`--out <path>`<br>`--module-name <name>`<br>`--force`<br>`--full`<br>`--json` |
+| `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>`--coverage`<br>`--allow-unknown`<br>`--out <path>`<br>`--module-name <name>`<br>`--force`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Planning
 
 | Command | Description | Options |
 |---|---|---|
-| `plan-context <target>` | Pre-edit planning context for a symbol, file, or module | `--impact-depth <n>`<br>`--slice-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--compact` |
+| `plan-context <target>` | Pre-edit planning context for a symbol, file, or module | `--impact-depth <n>`<br>`--slice-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Health
 
 | Command | Description | Options |
 |---|---|---|
-| `self-audit` | Score cheap evidence paths against the best available semantic/source oracle on sampled symbols | `--samples <n>`<br>`-s, --scope <path>`<br>`--json` |
-| `health` | Composite codebase health report with prioritized action list | `-s, --scope <path>`<br>`--full`<br>`--json`<br>`--baseline`<br>`--write-baseline` |
-| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | `--full`<br>`--json` |
+| `self-audit` | Score cheap evidence paths against the best available semantic/source oracle on sampled symbols | `--samples <n>`<br>`-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `health` | Composite codebase health report with prioritized action list | `-s, --scope <path>`<br>`--full`<br>`--baseline`<br>`--write-baseline`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Maintenance
 
 | 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>` |
-| `work-audit <profile>` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | `--top <n>`<br>`--json` |
+| `bench` | Benchmark indexing and command runtimes for this repository | `--cold-index`<br>`--include-heavy`<br>`--command <cmd>`<br>`--timeout-ms <n>`<br>`--progress`<br>`--profile`<br>`--profile-out <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `work-audit <profile>` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | `--top <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-explore, scip-plan, scip-diagnose, scip-audit, scip-improve, scip-verify) 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` |
+| `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--shared`<br>`--remove`<br>`--force`<br>`--dry-run`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `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 | `--matrix`<br>`--json` |
-| `capability-matrix` | Deprecated alias for capabilities --matrix | `--json` |
+| `capabilities` | Report which evidence and verification capabilities are available in this project | `--matrix`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `capability-matrix` | Deprecated alias for capabilities --matrix | `--json`<br>`--result-only`<br>`--compact` |
 | `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 as a file under .scipquery/suppressions/ with a required reason | `--reason <text>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--replace <revision>`<br>`--json` |
-| `effectiveness` | Per-check effectiveness from the committed outcome ledger: caught, comparison-verified fixes, suppressed, unverified disappearances, and precision | `--since <window>`<br>`--check <check>`<br>`--json` |
-| `doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | `--json` |
-| `setup` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | `--guided`<br>`--yes`<br>`--git-hook`<br>`--no-hooks`<br>`--no-skills`<br>`--no-parsers`<br>`--no-health`<br>`--dossier-dir <path>`<br>`--json` |
+| `config-validate` | Validate .scipquery.json, including structured suppressions and declared coupling groups | `--json`<br>`--result-only`<br>`--compact` |
+| `suppress <id>` | Record an accepted finding as a file under .scipquery/suppressions/ with a required reason | `--reason <text>`<br>`--reason-code <code>`<br>`--evidence <kind:referent>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--replace <revision>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `effectiveness` | Per-check repository telemetry from the committed outcome ledger: verified fixes, suppressions, unresolved findings, observer authority, and anomalies | `--since <window>`<br>`--check <check>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | `--json`<br>`--result-only`<br>`--compact` |
+| `setup` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | `--guided`<br>`--yes`<br>`--git-hook`<br>`--no-hooks`<br>`--no-skills`<br>`--no-parsers`<br>`--install-missing`<br>`--no-health`<br>`--dossier-dir <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `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` |
-| `uninstall` | Remove scip-query-owned skill links, project hooks, and managed agent setup blocks | `--global`<br>`--project`<br>`--dry-run`<br>`--json` |
-| `watch` | Watch in the foreground or manage the per-project background refresh service | `--daemon`<br>`--status`<br>`--stop`<br>`--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>`<br>`--idle-timeout <ms>`<br>`--json` |
-| `status` | Show index status for this project | `--json`<br>`--capabilities` |
+| `uninstall` | Remove selected scip-query-owned integrations; real removal requires exactly one of --global or --project | `--global`<br>`--project`<br>`--dry-run`<br>`--verbose`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `watch` | Watch in the foreground or manage the per-project background refresh service | `--daemon`<br>`--status`<br>`--stop`<br>`--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>`<br>`--idle-timeout <ms>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `status` | Show index status for this project | `--capabilities`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 <!-- END GENERATED COMMAND REFERENCE -->
 

package/docs/COMMITTED_RECORD_COMPATIBILITY.md

@@ -35,21 +35,31 @@ New records conform to
 They carry:
 
 - `kind: "scip-query-suppression"`;
-- `schemaVersion: 1`;
+- `schemaVersion: 2`;
 - the stable `suppressionIdentity`;
 - producer name/version and creation/update timestamps;
-- the existing suppression target and reason fields.
-
-The discriminator is additive within suppression v1. Older v1 readers permit
-unknown properties, so they continue to read newly written records. Current
-readers also accept v1 records written before the discriminator was added and
-unversioned legacy records. The filename remains the conflict domain:
-different suppression identities merge as different paths, while policy
-changes to one identity require revision-aware replacement.
-
-If a future or malformed suppression is omitted, it cannot waive a finding.
-`diff-gate` keeps the matching finding unsuppressed and reports incomplete
-suppression coverage in JSON, human output, and Stop-hook feedback.
+- the exact suppression target and explanatory reason;
+- a controlled adjudication reason code;
+- inspectable counterevidence, including content hashes for file referents;
+- the policy version, decision provenance, and invalidation conditions.
+
+Current readers accept v1 and unversioned records as legacy policy so history
+is not lost. Legacy records do not have enough mechanically checkable evidence
+to authorize automatic acceptance: matching findings remain visible as policy
+escalations until the record is explicitly replaced with a v2 decision.
+Earlier readers classify v2 as unsupported-future and therefore fail closed
+instead of silently treating the new evidence fields as optional. The filename
+remains the conflict domain: different suppression identities merge as
+different paths, while policy changes to one identity require revision-aware
+replacement.
+
+If a legacy, future, malformed, expired, or content-invalidated suppression
+cannot pass current policy, it cannot waive a finding. `diff-gate` keeps the
+matching finding unsuppressed and reports incomplete coverage or the exact
+policy-escalation reason in JSON, human output, and Stop-hook feedback. A
+successful gate that did accept one or more v2 decisions reports
+`pass-with-suppressions`, preserving the difference between an ordinary clean
+pass and an adjudicated exception.
 
 ## Current outcome-event records
 
@@ -61,7 +71,12 @@ They retain all semantic event fields at the root and add:
 - `schemaVersion: 1`;
 - `eventIdentity`, the JSON tuple of check, finding ID, transition, and
   observed commit;
-- producer name/version.
+- producer name/version;
+- `gateRunId`, the logical diff-gate observation shared by retries;
+- observer kind and whether its authority is repository-writable or protected
+  externally;
+- the index/worktree observation receipt;
+- the adjudication policy version on suppressed transitions.
 
 Keeping semantic fields at the root lets the immediately prior permissive
 reader consume new records. Current readers accept both these v1 records and
@@ -70,8 +85,17 @@ the existing unversioned event files.
 The immutable filename is still a timestamp plus a hash of the complete
 record bytes. Deduplication does not use that path or producer metadata; it
 uses the semantic `eventIdentity`. If legacy and current records describe the
-same fact, stronger comparison evidence wins and then the earliest timestamp
-wins, as before.
+same fact, comparable-base proof wins first, then protected/provenance-bearing
+evidence, and then the earliest timestamp.
+
+Observer kind says who originated the record: `local-agent`, `local-human`,
+or `protected-ci`. Observer authority says what conclusion the record can
+support. Both local kinds remain `repository-writable`, because the observer
+can edit the same event and suppression files being measured.
+`protected-external` is accepted only with `protected-ci` records produced by
+a separately controlled evaluator and a gate-run attestation delivered
+outside the writable event directory; a record field cannot attest itself
+and ordinary CLI environment settings cannot mint that authority.
 
 ## Partial history is conservative
 
@@ -80,6 +104,18 @@ wins, as before.
 coverage counts before any metrics. Metrics use only accepted records and are
 therefore explicitly partial when `complete` is false.
 
+`effectiveness` calls the ordinary local ratio
+`resolutionVsSuppressionRate`. It publishes `precision` only when every event
+in the evaluated population claims protected external authority and its
+gate-run ID appears in a separately supplied attestation set. Mixed,
+unattested, repository-writable, and legacy populations remain telemetry and
+carry a null precision field. Provenance gaps, unattested authority claims,
+mixed authority, missing gate-run identity, and anomalous suppression rates
+produce bounded sample reports, not a mandatory per-suppression human queue.
+Git preserves history that is present; deleting an event file cannot be
+detected from the remaining directory, so the command never describes
+repository-local totals as an independent grade.
+
 Cross-HEAD repair verification needs complete committed history to establish
 the prior lifecycle anchor. If any event candidate is incompatible, scip-query
 retains every missing local-ledger finding and defers resolution. An omitted
@@ -113,5 +149,6 @@ removing the legacy ledger.
 - Independent event files should normally keep both sides of a merge.
 - Do not delete an unsupported record to make a warning disappear. Use a
   reader that supports it, or deliberately migrate it with verified tooling.
-- Rolling back to the immediately prior release remains safe because new
-  metadata is additive and prior readers ignore unknown fields.
+- Rolling back remains fail-closed: older readers reject v2 suppressions as
+  unsupported-future, so they cannot accidentally waive a finding using a
+  policy they do not understand.