scip-query 0.19.8 → 0.20.0

package/docs/COMMAND_REFERENCE.md

@@ -4,15 +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>`. Oversized human output prints an exact continuation command; oversized JSON prints the exact command that opts into versioned output pages.
+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>`--trust-project-tools`<br>`--install-missing`<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>` |
 
@@ -20,136 +20,136 @@ Every command accepts `--output-page-size <characters>` and `--output-cursor <cu
 
 | 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` | 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>`--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>`--install-missing`<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.

package/docs/DURABILITY.md

@@ -15,10 +15,12 @@ directory entry survive power loss.
 
 A **crash-durable replacement** is a visibility-atomic replacement that also
 flushes the complete staging file before rename and flushes the containing
-directory after rename. Those ordered flushes are what make acknowledged file
-contents and the name that reaches them recoverable after an operating-system
-or machine crash, subject to the host filesystem and device honoring their
-flush contract.
+directory after rename. When the writer creates a missing directory path, it
+also creates each component from the nearest existing ancestor outward and
+flushes the directory that names each new component. Those ordered flushes are
+what make acknowledged file contents and the complete path that reaches them
+recoverable after an operating-system or machine crash, subject to the host
+filesystem and device honoring their flush contract.
 
 An **authoritative record** is file-backed state whose loss can change which
 generation, owner, policy, or accepted decision the program treats as current.
@@ -35,16 +37,28 @@ from a filename to its file—after the file itself has been flushed. Flushing
 only file contents is insufficient because a crash can otherwise lose the
 rename that made those contents current.
 
+An **achieved durability result** is the guarantee established by the
+operations that actually completed, not the guarantee the caller requested.
+`visibility` means only old-or-new complete process visibility;
+`file-flushed` means the final file bytes were flushed but at least one
+directory namespace could not be synchronized; and `directory-durable` means
+the file plus every newly created ancestor and final directory entry crossed
+the supported persistence frontier.
+
 ## APIs
 
-| API | Staging identity | File flush | Rename | Parent-directory flush |
-| --- | --- | --- | --- | --- |
-| `writeJsonAtomic` / `replaceFileAtomic(..., { durability: "visibility" })` | Exclusive random token | No | Yes | No |
-| `writeJsonDurable` / `replaceFileAtomic(..., { durability: "durable" })` | Exclusive random token | Yes | Yes | Yes where supported |
+| API                                                                        | Staging identity                                | File flush            | Rename/link                       | New-ancestor flush  | Final-directory flush |
+| -------------------------------------------------------------------------- | ----------------------------------------------- | --------------------- | --------------------------------- | ------------------- | --------------------- |
+| `writeJsonAtomic` / `replaceFileAtomic(..., { durability: "visibility" })` | Exclusive random token                          | No                    | Yes                               | No                  | No                    |
+| `writeJsonDurable` / `replaceFileAtomic(..., { durability: "durable" })`   | Exclusive random token                          | Yes                   | Yes                               | Yes where supported | Yes where supported   |
+| `createFileAtomicExclusive(..., { durability: "durable" })`                | Exclusive random token                          | Yes                   | Exclusive hard link               | Yes where supported | Yes where supported   |
+| `cloneFileDurable`                                                         | Final target inside an unpublished staging tree | Yes, after final mode | Caller publishes the staging tree | Yes where supported | Yes where supported   |
 
 `writeJsonAtomic` retains its original `void` return contract for compatibility.
-`writeJsonDurable` and `replaceFileAtomic` return the achieved directory-sync
-status. Verified binary installation owns an equivalent platform-local
+`writeJsonDurable`, `replaceFileAtomic`, and `createFileAtomicExclusive`
+return `requestedDurability`, `achievedDurability`, and `directorySync`.
+Callers must use the achieved fields when logging or forwarding a durability
+claim. Verified binary installation owns an equivalent platform-local
 flush/rename sequence because the enforced architecture forbids dependencies
 between the sibling `platform` and `storage` boundaries.
 
@@ -53,18 +67,25 @@ Known Windows "directory handles unsupported" errors produce
 `directorySync: "unsupported"` after the staged file itself has been flushed
 and renamed. That result means complete visibility plus flushed file contents,
 not the full POSIX directory-entry durability guarantee. Other directory-sync
-errors remain failures.
+errors remain failures. An API that returns only a path or value makes no
+machine-crash claim; protocol APIs that acknowledge work expose the achieved
+result explicitly.
 
 ## Failure Outcomes
 
-| Failure point | Target visible after return/throw | Owned staging file |
-| --- | --- | --- |
-| Exclusive create | Previous target | No owned file was created |
-| Write or short/invalid progress | Previous target | Closed and removed |
-| File flush | Previous target | Closed and removed |
-| Rename | Previous target | Removed by the writer |
-| POSIX directory flush | New complete target; durability unconfirmed and the call throws | Already renamed; no staging path |
-| Unsupported Windows directory flush | New complete target; result reports the limitation | Already renamed; no staging path |
+| Failure point                       | Target visible after return/throw                               | Owned staging file               |
+| ----------------------------------- | --------------------------------------------------------------- | -------------------------------- |
+| Exclusive create                    | Previous target                                                 | No owned file was created        |
+| Write or short/invalid progress     | Previous target                                                 | Closed and removed               |
+| File flush                          | Previous target                                                 | Closed and removed               |
+| Rename                              | Previous target                                                 | Removed by the writer            |
+| POSIX directory flush               | New complete target; durability unconfirmed and the call throws | Already renamed; no staging path |
+| Unsupported Windows directory flush | New complete target; result reports the limitation              | Already renamed; no staging path |
+
+When a parent chain is new, a failure while creating or flushing any ancestor
+also throws before a durable result is returned. The incomplete path can be
+visible to the running process, but recovery may discard every component that
+has not yet been named by a flushed parent.
 
 The post-rename failure row is deliberately explicit. Once rename succeeds,
 rolling back would be another publication with its own crash window. The
@@ -73,25 +94,28 @@ could not confirm the stronger durability guarantee.
 
 ## Call-Site Classification
 
-| Record | Contract | Reason |
-| --- | --- | --- |
-| Reindex `meta.json` | Durable | Names the accepted index status, fingerprint, and generation metadata |
-| SQLite generation manifest and `state.json` | Durable | Flushes one complete immutable artifact set, then atomically selects it for new readers |
-| Shared-generation manifest | Durable file within staging | Authenticates immutable artifacts; the later generation-directory publication remains a separate generation-store operation |
-| Worktree lease and local cache pointer | Durable | Protect generations from collection and bind a worktree to repository cache identity; generation changes, liveness touches, and cleanup serialize through the repository-cache lock |
-| Watch service state | Durable | Publishes the process instance and index generation accepted as current |
-| Rust semantic session `server.json` | Durable | Publishes the live server process and mailbox identity |
-| Project `.scipquery.json` | Durable | Controls indexing, watch, architecture, and detector policy; versioned reads reject unsupported meaning before use, and authorized writes migrate legacy bytes without dropping unknown fields |
-| Codex/Claude hook JSON | Durable | Controls whether and when agent hooks execute |
-| Structured suppression file | Durable | Records an accepted finding and its reason |
-| Health baseline | Durable | Acts as a committed regression policy |
-| Verified binary cache promotion | Durable | Makes checksum-accepted executable or tool bytes current |
-| TypeScript/Rust request and response mailboxes | Visibility-atomic | A timeout or retry reconstructs the ephemeral message |
-| Watch activity | Visibility-atomic | A newer timestamp supersedes an older idle-lifetime observation; it carries no durable intent |
-| Watch refresh request, claim, and completion records | Durable immutable admission and acknowledgement | Accepted intent survives activity replacement and owner crashes; exclusive claims may be recovered only by the next lock owner |
-| TypeScript fragment/overlay manifests | Visibility-atomic | Content-addressed cache artifacts are validated and rebuildable |
-| Repository GC state | Visibility-atomic | Sweep history can be reconstructed conservatively |
-| Affected-set shadow latest record | Visibility-atomic | Calibration telemetry does not control publication |
+| Record                                               | Contract                                                           | Reason                                                                                                                                                                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Reindex `meta.json`                                  | Durable                                                            | Names the accepted index status, fingerprint, and generation metadata                                                                                                                          |
+| SQLite generation manifest and `state.json`          | Directory-durable where supported                                  | Durably establishes the generation root, flushes final read-only artifact bytes and metadata, publishes the immutable directory, then selects it for new readers                               |
+| Shared generation                                    | Directory-durable where supported                                  | Flushes every read-only artifact and manifest, the staging namespace, the final generation rename, and the shared `generations/` namespace                                                     |
+| Worktree lease and local cache pointer               | Durable                                                            | Protect generations from collection and bind a worktree to repository cache identity; generation changes, liveness touches, and cleanup serialize through the repository-cache lock            |
+| Watch service state                                  | Durable                                                            | Publishes the process instance and index generation accepted as current                                                                                                                        |
+| Rust semantic session `server.json`                  | Durable                                                            | Publishes the live server process and mailbox identity                                                                                                                                         |
+| Project `.scipquery.json`                            | Durable                                                            | Controls indexing, watch, architecture, and detector policy; versioned reads reject unsupported meaning before use, and authorized writes migrate legacy bytes without dropping unknown fields |
+| Codex/Claude hook JSON                               | Durable                                                            | Controls whether and when agent hooks execute                                                                                                                                                  |
+| Structured suppression file                          | Durable                                                            | Records an accepted finding and its reason                                                                                                                                                     |
+| Health baseline                                      | Durable                                                            | Acts as a committed regression policy                                                                                                                                                          |
+| Verified binary cache promotion                      | Durable                                                            | Makes checksum-accepted executable or tool bytes current                                                                                                                                       |
+| TypeScript/Rust request and response mailboxes       | Directory-durable where supported                                  | Admission is acknowledged only after the pending name is flushed; a new owner directory is durably named before a request moves from pending to inflight; responses precede claim release      |
+| Watch activity                                       | Visibility-atomic                                                  | A newer timestamp supersedes an older idle-lifetime observation; it carries no durable intent                                                                                                  |
+| Watch refresh request, claim, and completion records | Durable immutable admission and acknowledgement                    | Accepted intent survives activity replacement and owner crashes; exclusive claims may be recovered only by the next lock owner                                                                 |
+| Cache ownership credential                           | Directory-durable where supported                                  | A complete file is flushed privately, hardening is revalidated, the public credential is linked exclusively, and its directory is flushed before detailed publication success                  |
+| npm release state                                    | Directory-durable where supported; file-flushed on bounded hosts   | The registry is freshly reconciled and remains external authority; the local coordinate-pair recovery record reports its exact achieved guarantee                                              |
+| Outcome event                                        | File publication locally; repository-durable only after Git commit | The event becomes shared history through the committed repository record, not merely because a checkout-local file exists                                                                      |
+| TypeScript fragment/overlay manifests                | Visibility-atomic                                                  | Content-addressed cache artifacts are validated and rebuildable                                                                                                                                |
+| Repository GC state                                  | Visibility-atomic                                                  | Sweep history can be reconstructed conservatively                                                                                                                                              |
+| Affected-set shadow latest record                    | Visibility-atomic                                                  | Calibration telemetry does not control publication                                                                                                                                             |
 
 Process locks use exclusive descriptor creation rather than replacement. Their
 durable token ownership, malformed-creation grace, guarded recovery, and
@@ -101,3 +125,29 @@ stable compatibility mirrors, and their crash ordering are defined in
 [Local Index Generations](INDEX_GENERATIONS.md). Durable watch demand,
 idempotency, claim recovery, and acknowledgement ordering are defined in
 [Watch Refresh Requests](WATCH_REFRESH_REQUESTS.md).
+
+## Executable crash model
+
+`tests/helpers/persistence-frontier.ts` models the two states a normal
+filesystem test otherwise conflates. Writes, links, renames, and removals first
+change process-visible state. File synchronization advances persisted inode
+bytes and mode; directory synchronization advances persisted names. A modeled
+power loss discards everything beyond those frontiers.
+
+`tests/storage/atomic-file-crash.test.ts` replays replacement, exclusive
+publication, new ancestor creation, and durable artifact cloning after every
+relevant phase. Boundary-specific tests then hold the higher-level protocol
+order:
+
+- local generation stage and same-size corruption tests;
+- shared-generation artifact, manifest, staging, rename, and final-directory
+  stage tests;
+- watch admission, claim, completion, and retry tests;
+- mailbox owner-directory, claim-transfer, response, and recovery tests;
+- ownership short-write, unsupported-sync, and failed-sync tests; and
+- release-state synchronized, unsupported, and failed-write tests.
+
+The deterministic model proves the filesystem primitive’s persisted-state
+semantics. The boundary tests prove each protocol invokes those primitives in
+the required order. Neither an exception callback alone nor a successful live
+filesystem read is described as a simulated power loss.