scip-query 0.19.5 → 0.19.8

package/docs/AI_FAILURE_MODES.md

@@ -1,6 +1,6 @@
 # The Ways AI Coding Rots a Codebase — and the Detector Built for Each
 
-AI-assisted development fails in *specific, repeatable* ways. None of them are
+AI-assisted development fails in _specific, repeatable_ ways. None of them are
 visible in a single file, which is why linters and code review miss them: every
 one lives in the relationships between files — the reference graph, the git
 change graph, or the gap between docs and code. Each failure mode below names
@@ -19,7 +19,7 @@ hook, composable, or frontend component that already exists - a date formatter,
 a retry wrapper, a validation guard, a table toolbar. Now there are two implementations that drift independently until they
 contradict each other.
 
-**The detector:** `recent-duplicates` makes similarity *directional* using git
+**The detector:** `recent-duplicates` makes similarity _directional_ using git
 file ages - which side is the established original, which is the freshly-added
 echo.
 
@@ -61,11 +61,11 @@ inside the recency window) and tells you to pick one before they drift:
 **What the agent does:** creates an abstraction, rewires one or two call
 sites into it, and abandons the rest — the extracted logic survives inline at
 every site it missed. The codebase ends up with the worst of both worlds: an
-abstraction *and* the duplication it was meant to remove.
+abstraction _and_ the duplication it was meant to remove.
 
 **The detector:** `incomplete-migration` finds symbols that are new at the
 base ref, confirms they were wired into at least one site, then reports
-established untouched functions whose callee sets *contain* the helper's
+established untouched functions whose callee sets _contain_ the helper's
 (containment scoring, because a missed site holds the helper's logic plus its
 own — symmetric similarity under-scores exactly these):
 
@@ -88,11 +88,11 @@ scip-query incomplete-migration --base origin/main    # gate a whole branch
 ## 4. Writing code that never gets wired up
 
 **What the agent does:** builds the function, the type, the handler — and
-never connects it. Or it *was* connected, then a later session rewired the
+never connects it. Or it _was_ connected, then a later session rewired the
 flow and left the original dangling. Dead code that looks intentional.
 
 **The detectors:** `dead` (evidence-ranked, entrypoint-aware), and the
-`new-dead` check in `diff-gate` that catches it *at the moment of creation*:
+`new-dead` check in `diff-gate` that catches it _at the moment of creation_:
 
 ```
 [new-dead] resolveTheme (src/theme.ts) was changed but has zero indexed consumers
@@ -114,7 +114,7 @@ every future reader has to understand.
 
 **The detectors:** `unused-params` (trailing parameters no body uses, scoped
 to removals that are type-safe by construction), plus the abstraction-level
-versions: `wrapper-candidates` (functions that only forward), 
+versions: `wrapper-candidates` (functions that only forward),
 `passthrough-candidates` (layers that add nothing), and `stale-abstractions`
 (interfaces/bases with a single implementation).
 
@@ -131,11 +131,11 @@ scip-query stale-abstractions
 ## 6. Letting the standards docs lie
 
 **What the agent does:** nothing — that's the problem. You write in-repo
-standards *for* agents; the code moves on; the doc doesn't. The next agent
+standards _for_ agents; the code moves on; the doc doesn't. The next agent
 reads the doc and faithfully implements against a dead spec. A stale standard
 is worse than none.
 
-**The detector:** `doc-drift` reads every doc's file citations *and* its
+**The detector:** `doc-drift` reads every doc's file citations _and_ its
 co-change history, and flags docs whose referenced code kept changing after
 the doc stopped — including broken references to files that no longer exist.
 
@@ -147,8 +147,8 @@ staleness 94  product/domain-model.md
   22 change(s) since doc update  src/workflows/serviceTasks.ts
 ```
 
-**Use it:** `scip-query doc-drift`, then run the `scip-doc-reconcile` skill to
-drive staleness to zero (it updates descriptive claims and *escalates*
+**Use it:** `scip-query doc-drift`, then run the `scip-improve` documentation-reconciliation scenario to
+drive staleness to zero (it updates descriptive claims and _escalates_
 normative violations instead of silently blessing them).
 
 **Caught automatically by:** the `doc-reference` check in `diff-gate` — a doc
@@ -162,7 +162,7 @@ store. The reference graph can't see these pairs — no import connects them —
 but git history can: they've changed together in 12 of the last 14 commits.
 
 **The detector:** `co-change` finds file pairs that repeatedly change in the
-same commits with *no* dependency edge.
+same commits with _no_ dependency edge.
 
 **Use it:**
 
@@ -183,7 +183,7 @@ scip-query co-change src/db/schema.prisma  # partners of one file
 path still references, or it hoards code because it can't prove anything is
 safe to remove.
 
-**The detector:** `cleanup-plan` runs dead-code analysis to a *fixpoint* —
+**The detector:** `cleanup-plan` runs dead-code analysis to a _fixpoint_ —
 deleting batch 0 makes batch 1 dead, and the plan shows the cascade. Then
 `--verify` applies each batch in a throwaway git worktree and runs **your own
 compiler** (tsc, cargo, go, python oracles — differentially, so pre-existing
@@ -222,7 +222,7 @@ scip-query plan-context <symbol-or-file>   # before the edit
 scip-query diff-impact --json              # after the edit
 ```
 
-The `scip-concrete-plan` skill enforces this end-to-end: every step in a plan must
+The `scip-plan` skill enforces this end-to-end: every step in a plan must
 cite the scip-query command that verified it.
 
 ## 10. Slow quality decay nobody notices
@@ -231,7 +231,7 @@ cite the scip-query command that verified it.
 alarming; six weeks later the repo is unrecognizable.
 
 **The detector:** the ratchet. `health --write-baseline` snapshots finding
-identities into a committable file; `health --baseline` exits 1 on any *new*
+identities into a committable file; `health --baseline` exits 1 on any _new_
 finding. "Don't get worse" becomes an objective gate no score arithmetic can
 game.
 
@@ -281,8 +281,8 @@ The generated guidance distinguishes shared repository records from local
 preferences. Commit suppression files and `.scipquery/ledger/` outcome events
 with the change that produced them. Never commit the checkout hook files.
 
-After setup, use `scip-cleanup-audit` to confirm raw signals and
-`scip-cleanup-improve` when the user wants the agent to fix the worst confirmed
+After setup, use `scip-audit` to confirm raw signals and
+`scip-improve` when the user wants the agent to fix the worst confirmed
 items until the health score is as high as reasonably possible.
 
 **3. The gate (enforcement).**

package/docs/API_EVOLUTION.md

@@ -0,0 +1,71 @@
+# Public TypeScript API evolution
+
+The public TypeScript API is the compiler-visible declaration surface
+reachable through `scip-query` package export paths. Its essential property is
+that downstream programs can depend on it without importing this repository's
+internal files.
+
+Every built declaration path is recorded in
+`docs/api/scip-query.api.json`. The report includes exported names, declaration
+kinds and signatures, generic and parameter syntax, return types, and the
+shared declaration chunks that carry referenced public types. Generation
+normalizes formatting, comments, named import/export order, path separators,
+and tsup chunk hashes so the review shows semantic declaration changes rather
+than build noise.
+
+## Contributor workflow
+
+Build and compare the current declarations:
+
+```bash
+npm run api:check
+```
+
+The check fails closed when a declaration target is absent, the committed
+manifest is malformed, its acceptance record is missing, or any declaration
+changes. Review every reported path and downstream use. Then accept the change
+with one classification:
+
+```bash
+npm run api:update -- \
+  --classification additive \
+  --reason "Add an optional result field for evidence provenance."
+```
+
+The classifications are:
+
+- `additive`: an old consumer remains valid, such as a new export or an
+  optional result field;
+- `compatible-correction`: the declaration report changes to correct a
+  contract that did not describe usable runtime behavior, with the reasoning
+  recorded for review;
+- `breaking`: an old consumer may stop compiling or acquire a different
+  meaning.
+
+The checker automatically identifies additions and removals. It treats changed
+signatures and referenced shared declarations conservatively. A human may
+classify uncertain drift as a compatible correction or breaking change, but
+cannot accept a known or uncertain change as additive without resolving the
+evidence.
+
+`api:update` writes a content-addressed record under
+`docs/api/changes/`. The record binds the old and new manifest digests, package
+version, automatic result, chosen classification, reason, and exact change
+list. Do not edit the generated manifest or an acceptance record by hand.
+
+## Compatibility policy
+
+- Keep a deprecated export or adapter for at least one minor release before
+  removal when a feasible compatibility path exists.
+- Add optional fields instead of making old consumers construct new required
+  state.
+- Treat parameter optionality, union membership, generic constraints, and
+  discriminated-union members as contract changes even when runtime tests pass.
+- Preserve the compile fixture in
+  `tests/fixtures/public-api-consumer/`. It represents a previously written
+  downstream program and must compile against the newly built package.
+- The two-package release coordinator runs lint, whose gate includes
+  `api:check`, before packing either artifact or reading registry state. Direct
+  `npm publish` is refused by `prepublishOnly`; it is not an alternate API
+  compatibility path. A declaration change is not accepted merely because
+  its implementation tests pass.

package/docs/CLI_JSON_OUTPUT.md

@@ -0,0 +1,168 @@
+# CLI JSON output contract
+
+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
+objects read by agents, shell scripts, CI jobs, and other programs. It is a
+versioned message format distinguished by one stable outer shape that names
+its producer, command, and result contract while leaving the command-specific
+payload under `result`.
+
+The current envelope is schema version 1:
+
+```json
+{
+  "kind": "scip-query-result",
+  "schemaVersion": 1,
+  "producer": { "name": "scip-query", "version": "0.19.8" },
+  "command": "refs",
+  "resultSchemaVersion": 1,
+  "evidence": "graph-fact",
+  "args": ["login"],
+  "options": { "json": true, "compact": true },
+  "result": {},
+  "coverage": {}
+}
+```
+
+`schemaVersion` governs the outer transport record. `resultSchemaVersion`
+governs the payload selected by `command`; it can advance without changing
+the transport version. `producer.version` is the installed package version
+that emitted the record. `kind` prevents a consumer from mistaking another
+JSON protocol for a CLI result.
+
+The machine-readable schema is
+[`schemas/cli-json-envelope.schema.json`](schemas/cli-json-envelope.schema.json).
+The public `scip-query/runtime` export provides
+`decodeCliJsonEnvelope()` and `requireCompatibleCliJsonEnvelope()` for
+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>
+```
+
+Human output larger than 12,000 characters is paged automatically. The page
+prints its exact continuation command both before and after its content.
+Agents must run that command unchanged and continue until the page reports
+completion. 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 `scip-query-result` envelope
+byte-for-byte so existing scripts are not broken. 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.8" },
+  "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 command, working directory, complete
+non-pagination argument list, next character offset, private output snapshot,
+and SHA-256 of the complete rendered output. SHA-256 is a fixed-size content
+fingerprint: the same bytes produce the same identity with overwhelming
+reliability. A continuation reads the immutable snapshot rather than re-running
+the command, so timestamps, durations, edits, or reindexes cannot mix
+different result generations between pages. Missing, expired, or changed
+snapshot data is rejected with the exact command that restarts at page one.
+Every incomplete machine-readable page also carries a direct
+`agentInstruction`. A partial page is not sufficient evidence for a conclusion
+or completion claim; 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.
+
+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:
+
+| Input                                                               | Meaning                                       | Consumer action                                                |
+| ------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------- |
+| Unversioned legacy envelope                                         | The public shape emitted before schema v1     | Read as supported legacy v0; plan migration                    |
+| `kind: "scip-query-result"`, `schemaVersion: 1`                     | Current transport contract                    | Read the named result schema                                   |
+| A supported envelope with an unknown command `resultSchemaVersion`  | A command payload this consumer does not know | Reject that payload without changing unrelated command schemas |
+| A higher or otherwise unsupported positive envelope `schemaVersion` | An outer contract this consumer does not know | Reject with producer/version context                           |
+| Missing required identity or transport fields                       | A malformed or different message              | Reject with the failed boundary                                |
+
+Consumers must ignore unknown fields. Additive fields can therefore ship in a
+minor release. A field removal, type change, meaning change, or previously
+optional field becoming required needs a new relevant schema version.
+Deprecated aliases remain available for a documented compatibility window;
+removing one requires a major contract transition.
+
+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.
+
+## Other JSON protocols
+
+The hidden `__health-phase` and `__diff-impact-batch` commands are
+same-package child-process messages, not public `--json` responses. They use
+the independently versioned `scip-query-isolated-analysis` protocol and are
+validated for protocol name, schema version, producer, command, and result
+before the parent accepts them.
+
+The `hook-context`, `hook-pretool`, and `hook-stop` outputs implement the
+Codex or Claude host's hook schema. Those hosts are the protocol owners, so
+scip-query must not add its CLI envelope fields to their messages. The hook
+event discriminator supplied by the host contract identifies those records.
+
+## Evolution checklist
+
+1. Keep existing fields and meanings when making an additive change.
+2. Bump `resultSchemaVersion` when one command's payload breaks compatibility.
+3. Bump `schemaVersion` when the shared outer record breaks compatibility.
+4. Keep a fixture for the previous supported generation and teach the decoder
+   whether to migrate or reject it.
+5. Update the JSON Schema, this guide, the command reference, and compatibility
+   tests in the same change.

package/docs/COMMAND_REFERENCE.md

@@ -4,11 +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).
+
+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.
+
 ### 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` |
 | `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>` |
 
@@ -73,7 +77,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `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-integrity-audit drill 5) — a ready-to-fill vitest file, not an auto-executor | `--out <path>`<br>`--force`<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` |
@@ -100,7 +104,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>`<br>`--json` |
 | `change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | `--full`<br>`--json` |
 | `co-change [file]` | Files that change together in git history without a dependency edge — hidden coupling candidates | `--min-together <n>`<br>`-n, --limit <n>`<br>`--all`<br>`--full`<br>`--json` |
-| `diff-gate` | Gate the current diff: 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` |
+| `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` |
 
@@ -130,17 +134,17 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 |---|---|---|
 | `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` |
-| `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-root-cause, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots | - |
+| `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` |
 | `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` |
 | `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>`--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` |
+| `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` |
 | `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` |

package/docs/COMMITTED_RECORD_COMPATIBILITY.md

@@ -0,0 +1,117 @@
+# Committed record compatibility
+
+scip-query stores two kinds of team-shared records in Git:
+
+- `.scipquery/suppressions/*.json` contains accepted detector-policy
+  decisions.
+- `.scipquery/events/*.json` contains immutable finding-transition
+  observations used by `effectiveness` and cross-HEAD repair verification.
+
+A committed record is a repository-owned JSON fact or policy whose value
+comes from surviving clones and branches. Unlike a local cache row, it cannot
+be silently dropped and rebuilt when a reader does not understand it.
+
+## Compatibility states
+
+Every JSON candidate is classified exactly once:
+
+| State                | Meaning                                                           | Included in conclusions? |
+| -------------------- | ----------------------------------------------------------------- | ------------------------ |
+| `legacy`             | A supported unversioned record from an earlier scip-query release | Yes                      |
+| `current`            | A record matching the current discriminator and schema            | Yes                      |
+| `unsupported-older`  | A versioned record older than the supported overlap window        | No                       |
+| `unsupported-future` | A record written by a newer incompatible schema                   | No                       |
+| `malformed`          | Invalid JSON, fields, discriminator, metadata, or stable identity | No                       |
+
+`complete` is true only when every candidate is `legacy` or `current`.
+Readers return accepted records together with `total`, `accepted`, `omitted`,
+the per-state counts, and path-specific issues. A subset may still support a
+conservative result, but it must not be represented as complete.
+
+## Current suppression records
+
+New records conform to
+[`schemas/suppression-record.schema.json`](schemas/suppression-record.schema.json).
+They carry:
+
+- `kind: "scip-query-suppression"`;
+- `schemaVersion: 1`;
+- 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.
+
+## Current outcome-event records
+
+New records conform to
+[`schemas/outcome-event-record.schema.json`](schemas/outcome-event-record.schema.json).
+They retain all semantic event fields at the root and add:
+
+- `kind: "scip-query-outcome-event"`;
+- `schemaVersion: 1`;
+- `eventIdentity`, the JSON tuple of check, finding ID, transition, and
+  observed commit;
+- producer name/version.
+
+Keeping semantic fields at the root lets the immediately prior permissive
+reader consume new records. Current readers accept both these v1 records and
+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.
+
+## Partial history is conservative
+
+`effectiveness --json` includes
+`recordCompatibility.outcomeEvents`. Human output prints the same incomplete
+coverage counts before any metrics. Metrics use only accepted records and are
+therefore explicitly partial when `complete` is false.
+
+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
+record can therefore delay a verified fix, but it cannot manufacture one.
+
+## Legacy JSONL migration
+
+`.scipquery/ledger/events.jsonl` remains readable during the overlap window.
+On the next event append:
+
+1. every non-empty line is classified;
+2. compatible lines are copied to independent current event files;
+3. new observations are appended normally;
+4. the legacy ledger and its `merge=union` attribute are removed only if
+   every line was compatible.
+
+If even one line is unsupported or malformed, the original ledger stays
+byte-for-byte present and the append reports a warning. Repeating the append
+is safe: exclusive content-addressed event creation makes already-copied rows
+idempotent. Upgrade scip-query or repair the named malformed line before
+removing the legacy ledger.
+
+## Merge and rollback rules
+
+- Commit suppression and event files with the code or documentation change
+  that produced them.
+- Do not rewrite all legacy files just to make compatibility counters
+  “current.” Read overlap is the migration mechanism.
+- Resolve a same-suppression-path conflict by reviewing both policy decisions;
+  never choose a side mechanically.
+- 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.