scip-query 0.19.4 → 0.19.6

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,83 @@
+# 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.6" },
+  "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.
+
+## 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,6 +4,8 @@
 
 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).
+
 ### Indexing
 
 | Command | Description | Options |
@@ -24,11 +26,11 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 |---|---|---|
 | `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>`--json` |
-| `trace <symbol>` | Trace a symbol: definition + all references | `--full`<br>`--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 | `--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` |
@@ -73,7 +75,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 +102,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` |
+| `diff-gate` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--baseline`<br>`--full`<br>`--skip <check>`<br>`--hook`<br>`--json`<br>`--compact` |
 | `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
 | `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>`<br>`--json` |
 
@@ -114,7 +116,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 
 | 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` |
+| `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` |
 
 ### Health
 
@@ -130,14 +132,14 @@ 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` |

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.

package/docs/CONFIGURATION_WRITE_SAFETY.md

@@ -0,0 +1,130 @@
+# Configuration and setup write safety
+
+scip-query updates files that people and other agents may edit at the same
+time: `.scipquery.json`, provider hook JSON, `.git/info/exclude`,
+`AGENTS.md`, `CLAUDE.md`, structured suppression records, and an owned
+pre-commit hook. A conflict-aware writer is a file updater that transforms one
+identified revision and refuses to claim success if an independent revision
+wins before commit. Its defining behavior is preservation: it either applies
+its narrow change to the newest valid input or leaves the newest input
+untouched and reports why.
+
+## Revision and commit protocol
+
+Every participating writer:
+
+1. acquires a short, token-owned process lock beside the target;
+2. reads a stable snapshot and records its SHA-256 hash plus file identity;
+3. computes only the domain change it owns;
+4. rereads the target immediately before commit;
+5. retries the merge when the revision changed and retry is safe, or reports a
+   conflict when it is not;
+6. stages and flushes complete bytes, atomically publishes them, and flushes
+   the parent directory where the platform exposes that operation.
+
+The lock serializes scip-query processes. Editors do not need to participate:
+their byte or identity change is detected by the optimistic revision check.
+The lock record is token-owned and carries process identity, so a live owner
+cannot be displaced and a dead owner can be reclaimed by the shared process
+lock protocol.
+
+First creation uses a flushed staging inode plus an exclusive public hard
+link. This is stronger than `exists` followed by replacement: only one creator
+can publish, and a reader sees no public file until every byte is present.
+
+## JSON merge rules
+
+Project setup rereads the latest valid object and changes only the requested
+field. Unknown current and future fields survive. A three-way check compares
+the caller's observed value, the latest value, and the requested value:
+
+- an unrelated latest edit is preserved and the owned field is updated;
+- the requested value already present is idempotent;
+- a different latest value for the same field is an explicit stale-field
+  conflict.
+
+Hook setup rereads the latest valid provider object on every bounded retry,
+removes only scip-query-owned hook entries, and merges the current owned hook
+groups. Unknown top-level fields and non-scip hook entries survive installation
+and removal.
+
+Malformed latest JSON is never repaired by replacement because doing so could
+erase information the writer cannot classify. The command reports the parse
+failure and leaves the exact bytes in place.
+
+### Project-config format boundary
+
+The project configuration is a durable policy record whose `schemaVersion`
+determines the meaning of its other fields. Current writers publish version 2
+and include a `$schema` URI reference to
+`docs/schemas/project-config.schema.json` in the installed package.
+Unversioned files and explicit `schemaVersion: 1` files have the same readable
+legacy meaning. They are migrated in memory and written as version 2 only when
+`init` creates a file or a setup action enters an authorized mutation path.
+
+The schema migration is part of the no-op decision. If the requested field is
+already correct but the durable record is legacy or lacks its editor-schema
+hint, the writer still publishes a current record and reports `changed: true`.
+Unknown root and nested fields survive because migration begins from the
+latest complete object and removes only the owned legacy discriminator.
+
+A non-integer discriminator, non-object top level, invalid `$schema` hint, or
+unsupported older/future version fails before options are exposed to runtime
+consumers. The loader names the supported legacy/current versions. A setup
+writer applies the same decoder to its latest stable snapshot and leaves
+rejected bytes byte-for-byte unchanged, so upgrading the CLI—not a blind
+rewrite—is the recovery path for a future version.
+
+## Suppression policy rules
+
+A suppression identity is the stable finding ID, or the deterministic hash of
+a check-and-file target when no finding ID exists. It is a policy conflict
+domain: decisions for different identities occupy different files, while two
+decisions for the same identity must be reconciled.
+
+The first decision uses exclusive durable creation. An identical replay
+returns the existing revision without rewriting metadata. A different reason,
+expiry, check, or file requires `--replace <revision>`, where the revision is
+the full SHA-256 hash reported when the existing decision was rejected or
+created. Replacement succeeds only if those exact reviewed bytes still occupy
+the path. A stale token, a malformed record, an unsupported future schema, or
+an edit at the commit boundary leaves the latest bytes untouched.
+
+New records use suppression schema version 1 and include the
+`scip-query-suppression` discriminator, their stable identity, and the
+`scip-query` writer version. Unversioned legacy records and v1 records written
+before the discriminator was added remain readable. They remain byte-for-byte
+unchanged on an idempotent replay and are upgraded only by an explicit
+compare-and-replace policy change. Incompatible files are counted and reported
+by `diff-gate`; they never authorize a suppression. See
+[`COMMITTED_RECORD_COMPATIBILITY.md`](COMMITTED_RECORD_COMPATIBILITY.md).
+
+## Managed text rules
+
+Agent guidance changes only the text between the exact
+`scip-query:agent-setup` markers. Text before and after the block is preserved.
+Missing markers permit first installation, but incomplete, duplicated, or
+reordered markers are a conflict because the intended ownership boundary is
+ambiguous.
+
+Managed Markdown and owned pre-commit operations use a strict final revision
+check rather than silently recomputing across an intervening edit. The command
+reports the expected and latest revision hashes and does not write.
+`.git/info/exclude` can safely retry because its exact owned marker block is
+recomputed from the newest text.
+
+## Recovery
+
+When a command reports a conflict:
+
+1. open the named file and preserve the latest independent edit;
+2. repair malformed JSON or marker structure deliberately, if reported;
+3. for a suppression policy change, review the latest decision and rerun
+   `suppress` with the reported `--replace <revision>`;
+4. for setup/configuration, rerun the command so it reads the new revision.
+
+Do not delete a live `.scip-query-write.lock`. If its owner crashed, the next
+writer reclaims it only after the shared lock protocol proves the recorded
+process identity is no longer live. A crash before publication leaves the
+previous target intact; a failed first publication leaves no partial public
+file.

package/docs/DETECTOR_GUIDE.md

@@ -13,20 +13,20 @@ maps these to the agent behaviors that create the problems.)
 Same disease — structure built for a future that never came — detected at
 four different altitudes:
 
-| Command | Altitude | What it measures | The fix |
-|---|---|---|---|
-| `unused-params` | **parameter** | Trailing parameters no body ever uses. TS/JS only, trailing-run only — removals that are type-safe by construction. `_`-prefixed and externally-published signatures are exempt. | Delete the parameters and their call-site arguments. |
-| `passthrough-candidates` | **function (fan-out view)** | Functions with exactly **one callee** and a small body — they just forward arguments to the real implementation. | Inline it: call the target directly. |
-| `wrapper-candidates` | **function (fan-in view)** | Symbols with exactly **one caller** — indirection that provides no reuse. Strongest when the sole caller is itself widely used. | Fold the body into the caller. |
-| `stale-abstractions` | **type** | Classes, interfaces, and type aliases with 0–1 *real* cross-file consumers (barrel re-exports don't count as consumers). Single-implementation interfaces, misplaced types. | De-abstract: replace the interface with the concrete thing, or move the type to its one consumer. |
+| Command                  | Altitude                    | What it measures                                                                                                                                                                 | The fix                                                                                           |
+| ------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `unused-params`          | **parameter**               | Trailing parameters no body ever uses. TS/JS only, trailing-run only — removals that are type-safe by construction. `_`-prefixed and externally-published signatures are exempt. | Delete the parameters and their call-site arguments.                                              |
+| `passthrough-candidates` | **function (fan-out view)** | Functions with exactly **one callee** and a small body — they just forward arguments to the real implementation.                                                                 | Inline it: call the target directly.                                                              |
+| `wrapper-candidates`     | **function (fan-in view)**  | Symbols with exactly **one caller** — indirection that provides no reuse. Strongest when the sole caller is itself widely used.                                                  | Fold the body into the caller.                                                                    |
+| `stale-abstractions`     | **type**                    | Classes, interfaces, and type aliases with 0–1 _real_ cross-file consumers (barrel re-exports don't count as consumers). Single-implementation interfaces, misplaced types.      | De-abstract: replace the interface with the concrete thing, or move the type to its one consumer. |
 
 How to keep them straight:
 
 - `passthrough` looks **down** (what does this function call? one thing) —
   `wrapper` looks **up** (who calls this function? one caller). A function can
   be both: a one-line forwarder with a single caller is the purest bloat.
-- `unused-params` is *inside* a signature; the other three are *about whole
-  symbols*.
+- `unused-params` is _inside_ a signature; the other three are _about whole
+  symbols_.
 - `stale-abstractions` is the only one about **types**, not behavior. Note its
   confidence ranking: a single-consumer `class` is usually deliberate
   encapsulation (low), a single-consumer `interface` is worth questioning
@@ -35,17 +35,17 @@ How to keep them straight:
 ## Cluster 2 — "This already exists" (the similarity family)
 
 All of these find duplication, but at different granularities and with
-different evidence — and two of them add *direction*:
-
-| Command | Granularity | Evidence | Question it answers |
-|---|---|---|---|
-| `similar <symbol>` | function | callee-fingerprint cosine (TF-IDF), source-token fallback | "What else does roughly what this function does?" |
-| `similar-signatures` | function | normalized parameter + return types | "What has the same *shape*, regardless of body?" |
-| `similar-files` | file | Jaccard on import/dependency profiles | "Which files are copy-paste variants of each other?" |
-| `similar-chains` | pipeline | edit distance on infrastructure-filtered dependency chains | "Which end-to-end flows are parallel re-implementations?" |
-| `recent-duplicates` | callable/frontend unit + **git age** | callable, React, and Vue similarity + file-add history | "Which side is the established original, which is the fresh echo?" (ECHO = new copies old; TWIN = both new) |
-| `incomplete-migration` | function + **git diff** | callee *containment* vs new-in-diff helpers | "I just extracted a helper — which call sites still have the logic inline and were never migrated?" |
-| `convergence <a> <b>` | a known pair | shared/unique callees | "I already know these two overlap — give me the merge prescription." |
+different evidence — and two of them add _direction_:
+
+| Command                | Granularity                          | Evidence                                                   | Question it answers                                                                                         |
+| ---------------------- | ------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `similar <symbol>`     | function                             | callee-fingerprint cosine (TF-IDF), source-token fallback  | "What else does roughly what this function does?"                                                           |
+| `similar-signatures`   | function                             | normalized parameter + return types                        | "What has the same _shape_, regardless of body?"                                                            |
+| `similar-files`        | file                                 | Jaccard on import/dependency profiles                      | "Which files are copy-paste variants of each other?"                                                        |
+| `similar-chains`       | pipeline                             | edit distance on infrastructure-filtered dependency chains | "Which end-to-end flows are parallel re-implementations?"                                                   |
+| `recent-duplicates`    | callable/frontend unit + **git age** | callable, React, and Vue similarity + file-add history     | "Which side is the established original, which is the fresh echo?" (ECHO = new copies old; TWIN = both new) |
+| `incomplete-migration` | function + **git diff**              | callee _containment_ vs new-in-diff helpers                | "I just extracted a helper — which call sites still have the logic inline and were never migrated?"         |
+| `convergence <a> <b>`  | a known pair                         | shared/unique callees                                      | "I already know these two overlap — give me the merge prescription."                                        |
 
 How to keep them straight:
 
@@ -56,13 +56,13 @@ How to keep them straight:
   which copy to delete. Run it after agent sessions. It covers generic callables,
   React component structure, React hook behavior, Vue template structure, and
   Vue composable-like behavior.
-- `incomplete-migration` is the **inverse of an echo**: the *new* code is the
-  canonical one (the helper you just extracted), and the *established* code is
+- `incomplete-migration` is the **inverse of an echo**: the _new_ code is the
+  canonical one (the helper you just extracted), and the _established_ code is
   what should disappear. It also scores by containment, not symmetric
-  similarity, because an un-migrated site holds the helper's logic *plus* its
+  similarity, because an un-migrated site holds the helper's logic _plus_ its
   own — cosine under-scores exactly those.
 - `extract-candidates` is the **before** picture: seams inside one big
-  function that *should* become a helper. `incomplete-migration` is the
+  function that _should_ become a helper. `incomplete-migration` is the
   **after** picture: you made the helper but didn't finish moving everyone
   onto it.
 
@@ -71,11 +71,11 @@ How to keep them straight:
 Three detectors share the word "drift" or the concept; they watch different
 gaps:
 
-| Command | Watches the gap between | Evidence |
-|---|---|---|
-| `drift` | a file and its **siblings/declared architecture** | reference graph: unused imports, project-owned forbidden boundary edges, "no sibling imports this" deviations |
-| `doc-drift` | **docs** and the code they describe | doc file-citations + doc↔code co-change history; flags broken references and staleness scores |
-| `co-change` | two **files** with an invisible contract | git history: pairs that change together with no dependency edge |
+| Command     | Watches the gap between                           | Evidence                                                                                                      |
+| ----------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `drift`     | a file and its **siblings/declared architecture** | reference graph: unused imports, project-owned forbidden boundary edges, "no sibling imports this" deviations |
+| `doc-drift` | **docs** and the code they describe               | doc file-citations + doc↔code co-change history; flags broken references and staleness scores                 |
+| `co-change` | two **files** with an invisible contract          | git history: pairs that change together with no dependency edge                                               |
 
 How to keep them straight: `drift` is structural and intra-code, `doc-drift`
 is prose-vs-code, `co-change` is code-vs-code where the connection exists only
@@ -92,7 +92,7 @@ coverage, reciprocity, and connected-group signals.
 | `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
 | `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
 | `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
-| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, requireAcyclic, requireResolvedBoundaries, requireMinimalPolicy, maxBoundaryFanOut, global maxBoundaryFiles, per-boundary maxFiles, or testPaths are configured and a baseline exists. |
+| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, requireAcyclic, requireResolvedBoundaries, requireMinimalPolicy, maxBoundaryFanOut/maxBoundaryFiles, or testPaths are configured and a baseline exists. |
 | `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
 | `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
 | `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |
@@ -103,11 +103,11 @@ Baseline identities use `detector:file:shortName`. File or symbol renames can le
 
 ## Cluster 4 — "Nothing uses this" (the deadness family)
 
-| Command | Scope | Question |
-|---|---|---|
-| `dead` | symbols | "What has zero consumers?" (evidence-ranked, entrypoint-aware) |
-| `isolated` | callables | "What is fully disconnected — no callers *and* no callees?" |
-| `cleanup-plan` | the cascade | "If I delete the dead stuff, what *becomes* dead next — and will my compiler vouch for the whole batch?" (`--verify`) |
+| Command        | Scope       | Question                                                                                                              |
+| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| `dead`         | symbols     | "What has zero consumers?" (evidence-ranked, entrypoint-aware)                                                        |
+| `isolated`     | callables   | "What is fully disconnected — no callers _and_ no callees?"                                                           |
+| `cleanup-plan` | the cascade | "If I delete the dead stuff, what _becomes_ dead next — and will my compiler vouch for the whole batch?" (`--verify`) |
 
 `dead` finds candidates; `isolated` finds the most extreme subset;
 `cleanup-plan --verify` turns candidates into a compiler-proven deletion plan.
@@ -118,21 +118,21 @@ Don't hand-delete from `dead` output when `cleanup-plan` can prove it.
 ## After-the-change check matrix
 
 The reflex to build (and the one the `scip-query` router skill teaches
-agents): match the check to what the change *did*. `diff-gate` runs the
+agents): match the check to what the change _did_. `diff-gate` runs the
 broad sweep on every diff; these are the targeted follow-ups.
 
-| You just... | Run |
-|---|---|
-| Extracted a helper / created an abstraction | `scip-query incomplete-migration` — did every site migrate? |
-| Wrote a brand-new helper or module | `scip-query similar <it>` and `scip-query recent-duplicates` — did it already exist? |
-| Added parameters, options, or config flags | `scip-query unused-params` — does anything use them yet? |
-| Added a forwarding/wrapper layer | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — does it earn its indirection? |
-| Added an interface, base class, or type alias | `scip-query stale-abstractions` — does it have more than one real consumer? |
-| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — who historically moves with it? |
-| Changed code that docs describe | `scip-query doc-drift` — which docs now lie? |
-| Deleted code | `scip-query cleanup-plan --verify` — what else just became dead, and does the compiler agree? |
-| Anything at all, before saying "done" | `scip-query reindex && scip-query diff-gate` |
+| You just...                                           | Run                                                                                                     |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Extracted a helper / created an abstraction           | `scip-query incomplete-migration` — did every site migrate?                                             |
+| Wrote a brand-new helper or module                    | `scip-query similar <it>` and `scip-query recent-duplicates` — did it already exist?                    |
+| Added parameters, options, or config flags            | `scip-query unused-params` — does anything use them yet?                                                |
+| Added a forwarding/wrapper layer                      | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — does it earn its indirection? |
+| Added an interface, base class, or type alias         | `scip-query stale-abstractions` — does it have more than one real consumer?                             |
+| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — who historically moves with it?                                         |
+| Changed code that docs describe                       | `scip-query doc-drift` — which docs now lie?                                                            |
+| Deleted code                                          | `scip-query cleanup-plan --verify` — what else just became dead, and does the compiler agree?           |
+| Anything at all, before saying "done"                 | `scip-query reindex && scip-query diff-gate`                                                            |
 
 And before any non-trivial change: plan with `scip-query plan-context
-<target>` (or the `scip-concrete-plan` skill, which requires a scip-query citation
+<target>` (or the `scip-plan` skill, which requires a scip-query citation
 for every claim in the plan).