sidegraph 0.18.0__tar.gz → 0.20.0__tar.gz

{sidegraph-0.18.0 → sidegraph-0.20.0}/CHANGELOG.md

@@ -7,6 +7,77 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-10-28
+
+### Added
+
+- **Contract change:** `record_drift_check` takes an optional `sections` argument for
+  markdown files: the sections you read, plus sections to also watch. The record then
+  re-arms on that file only when one of them, or the file's link reference definitions,
+  changes. The result echoes `declared_sections` (`first_line`, `lines`) and eleven new
+  fixed error codes name each refusal. The capsule gains an optional `declared_sections`
+  field inside `schema_version` 1 (hashes only, no heading text); plain capsules write an
+  empty list. An older release ignores the field, compares whole blobs and warns more,
+  never less. An unknown scheme or role, or a file whose structure cannot be bounded, still
+  compares by whole blob, and so does a partial clone on Git older than 2.45, where reading
+  section text could fetch objects.
+- `sidegraph-doctor` groups per-record `code-drift` by the drifted file. Each record names the
+  blob it was compared against (a capture, check or scope baseline, with its mode) and shares
+  one `git diff <old blob> <new blob>` per distinct change; a mode-only or type change says so.
+  A record whose anchored Python function or Markdown section is identical at both ends carries
+  `anchored region unchanged; sibling sections of the file may still matter`, a reading aid
+  that never clears or reorders anything. `--json` gains a `drift_groups` key; `findings` is
+  unchanged. `--flat` restores one line per record and skips the grouping.
+- `markdown-it-py>=4,<5` is a direct dependency (Markdown heading spans for the hint and for
+  declared sections).
+
+### Changed
+
+- The SessionStart drift line says how many of the records needing review are recent:
+  `Sidegraph: 190 record(s) need content review (12 new in the last 7 days): …`, or
+  `(none new in the last 7 days)`. A record without a recorded first-seen time counts as
+  unknown age, never as new. An index built before this version prints the line without the
+  clause on its first day, `(none new since <date>)` while its stamping is younger than
+  7 days, and `(none new in the last 7 days)` from then on, until a record newly drifts.
+  `SIDEGRAPH_DRIFT_NUDGE=off` silences it with the rest of the line.
+- `sidegraph-doctor --json` findings carry `first_seen`: the ISO time a `code-drift`
+  record was first seen drifted, otherwise `null`.
+- The default `sidegraph-doctor` text for per-record `code-drift` is the grouped block above
+  instead of one line per record. The summary count, `--check` and the exit codes are unchanged.
+
+## [0.19.0] — 2026-10-27
+
+### Changed
+
+- `sidegraph-doctor --check` no longer exits `2` on `maintenance-due` alone. The finding is
+  still printed, listed in `--json` and shown as a session notice; `store-not-migrated` and
+  every other finding still fail `--check`.
+- `sidegraph-export-adr` names store records (the ADR's own record, supporting facts,
+  domains, successors without a document) by id instead of linking into `.sidegraph/`.
+  Migrating or maintaining the store no longer rewrites every exported ADR. The first export
+  with this version rewrites each generated document once. The `$record_link` template
+  placeholder is now a code span with the id, not a link target.
+
+### Fixed
+
+- One record file that cannot be read or decoded no longer fans out into findings at every
+  record that refers to it. `sidegraph-verify` reports the one `parse-error`; a fact that
+  supports it, a successor that supersedes it and a binding to such an entity raise nothing
+  more, and `sidegraph-doctor` adds no `dangling-record` for the supporting fact.
+- `sidegraph-verify --against` no longer reports `illegal-deletion` or `illegal-field-change`
+  for a committed file the store never loads: a stray copy under an unsafe name, or a file
+  whose baseline id is unsafe. Deleting such a file is the fix; the snapshot still reports it
+  as `unsafe-record-id` while it exists.
+- Ratifying, dropping or closing a decision written before the `scope` field existed no longer
+  reads as an illegal `scope` change. `sidegraph-verify`, `sidegraph-compact` and maintenance
+  accept the default `repo` that the writer or the archive line adds, so such a record can be
+  compacted and packed again. A real `scope` edit is still refused. Entities without `kind`
+  get the same treatment for its default, `concrete`.
+- `sidegraph-export-okf` no longer exports a domain's superseded row when its successor's id
+  happens to sort lower, which can happen for two ids minted in the same millisecond, or
+  after a domain is renamed away and back. A row with a later revision under the same slug
+  never becomes that slug's page.
+
 ## [0.18.0] — 2026-10-26
 
 ### Changed

{sidegraph-0.18.0 → sidegraph-0.20.0}/CLAUDE.md

@@ -13,7 +13,7 @@ task-aware retrieval + decision memory riding on the engine's entity graph.
 continuing participant in the project. A core feature must preserve, organize, or deliver
 accumulated project understanding. Document search by itself is not the product.
 
-Sidegraph is pre-1.0 (v0.18.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.20.0) — the full loop (capture, ratification, mistakes-first
 retrieval, refactor-surviving re-anchoring, semantic docs layer, mind-model domains, and the
 facts evidence layer) ships and is exercised end-to-end, but interfaces may still move before
 a stable release. See

{sidegraph-0.18.0 → sidegraph-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.18.0
+Version: 0.20.0
 Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
 Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
 Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph
@@ -24,6 +24,7 @@ Requires-Python: >=3.13
 Requires-Dist: anyio>=4
 Requires-Dist: certifi>=2026.10.19
 Requires-Dist: fastmcp<4,>=3.4.10
+Requires-Dist: markdown-it-py<5,>=4
 Requires-Dist: mcp<2,>=1.30
 Requires-Dist: opentelemetry-api>=1.45.1
 Requires-Dist: pydantic>=2.9

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/concepts/anchoring.md

@@ -133,6 +133,9 @@ Anchoring and sync collapse the stubs; what agents read keeps the ambiguous answ
 
 ## Why multi-anchor matters for doc corpora
 
+Anchoring decides where a record surfaces. Which sections of a long document a later
+`record_drift_check` must watch is declared when the record is checked, not anchored.
+
 On a docs corpus (ADRs/SAD), both a heading and its containing file are anchorable nodes
 (`file_type` in `{code, document, concept, rationale}` — an allowlist that also keeps
 unanchorable types like `image` out, per the same never-guess principle; `concept` and

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/concepts/data-model.md

@@ -314,8 +314,9 @@ the shared canonical digest/index record tables. See
 | `required_files` | list[str] | Exact current required anchor-file set, separate from optional inspected dependencies. |
 | `checked_files` | list[`CheckedCodeFile`] | Explicit inspected regular-file snapshots, covering every required file; 1–256 unique safe paths. |
 | `subject_digest` | str | SHA-256 of fixed immutable decision/provenance fields and durable leaf descriptors; excludes lifecycle and volatile mapping/status fields. |
+| `declared_sections` | list[`DeclaredSectionFile`] | Optional per-file section scope for markdown files, `[]` for a plain whole-file check; at most 64 entries, each path one of `checked_files`. |
 
-Changed inspected files/modes or required scope re-arm review. A matching snapshot after
+Changed inspected files/modes or required scope re-arm review; for a file with declared sections, a change to a declared or also-watched section, or to the file's link definitions, re-arms instead of any change to the file. A matching snapshot after
 an unrelated commit remains covered. A mistaken semantic assertion cannot be detected
 from these hashes; a genuine successor corrects the decision and preserves the check as
 history. Optional comparison failure has the bounded behavior described in store-format.
@@ -330,3 +331,25 @@ mappings. The total checked-path budget is 16384 UTF-8 bytes.
 | `path` | str | Safe repository-relative forward-slash path, at most 1024 UTF-8 bytes. |
 | `blob_id` | str | Full Git content address of the inspected file. |
 | `mode` | `100644` \| `100755` | Regular-file Git mode; mode changes participate in applicability. |
+
+## `DeclaredSectionFile` — declared sections of one checked file
+
+Nested in `DriftCheck`; this stores locators and digests, never heading text or source
+bodies. A scheme or role this release does not know is accepted and compared by whole blob.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | str | One of the check's `checked_files`; unique across entries. |
+| `scheme` | token | How sections are located; `md1` (markdown block structure) is the one scheme this release resolves. |
+| `refs_hash` | hex \| `null` | `md1`: digest of the file's link reference definitions. |
+| `sections` | list[`DeclaredSection`] | 1–256 sections; at most 1024 across the check. |
+
+## `DeclaredSection` — one declared or also-watched section
+
+Nested in `DeclaredSectionFile`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `heading_hash` | hex | `md1`: digest of the heading chain that locates the section. |
+| `role` | token | `declared` (the checker read it) or `watch` (a sibling the claim depends on). |
+| `text_hash` | hex | `md1`: digest of the section's text, subsections included. |

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/getting-started/installation.md

@@ -45,7 +45,8 @@ with Git for Windows installed; they do not establish support for Windows hosts
 remains outside these checks.
 See [Windows](#windows) before installing a host plugin.
 
-Package dependencies support `fastmcp>=3.4.10,<4` and `mcp>=1.30,<2`. Runtime security
+Package dependencies support `fastmcp>=3.4.10,<4`, `mcp>=1.30,<2` and `markdown-it-py>=4,<5`
+(markdown section scope for drift checks). Runtime security
 floors also require `certifi>=2026.10.19` and
 `opentelemetry-api>=1.45.1`, including standalone wheel installations. Major SDK upgrades
 require a separate compatibility review; an unlocked package install may resolve newer

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/adr-export.md

@@ -24,8 +24,10 @@ consequences come from the record. Missing optional reasoning says `Not recorded
 
 A fixed footer retains status, validity, history, source pointers, durable code descriptors
 and complete accepted, unclosed supporting facts. Even a future `valid_to` closes a fact;
-the exporter never infers a sample size or runtime qualifier. A successor of another kind
-links to its source record rather than a nonexistent ADR. `index.md` groups documents by
+the exporter never infers a sample size or runtime qualifier. Store records (the ADR's own
+record, supporting facts, domains, a successor of another kind) are named by id, never by a
+path into `.sidegraph/`, so migrating or maintaining the store changes no generated
+document. `index.md` groups documents by
 explicit accepted domain bindings, otherwise under Unassigned. These are membership
 intent and durable descriptors, not claims of current graph resolution.
 
@@ -68,7 +70,10 @@ A custom template is a regular UTF-8 file up to 64 KiB, using literal text and
 `string.Template` placeholders. It must include `$title`, `$context`, `$choice`, `$rejected`
 and `$consequences`; `$$` prints a dollar sign. Optional fields are `$kind`, `$status`,
 `$valid_from`, `$valid_to`, `$evidence`, `$anchors`, `$domains`, `$supersedes`, `$successors`,
-`$record_link` and `$source`. The fixed footer remains even if the template omits these.
+`$record_link` and `$source`. `$record_link` is the record's id as a code span, not a link
+target (store records are never linked by path, so migrating the store changes no document);
+a template that used it as the target of a markdown link must drop the link syntax. The fixed
+footer remains even if the template omits these.
 Default templates avoid duplicating it. Unknown placeholders or reserved marker lines are
 errors. The generated ownership marker precedes the template, so template YAML frontmatter
 is not at the first byte of the generated file.

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/capturing-decisions.md

@@ -42,6 +42,9 @@ named, is a separate decision-level Tier-0 binding made by the write path, not p
 `name` is a **heading text** or the **file name itself**; for code, a **function/class name**
 or the file — all valid entity names in a Graphify graph.
 
+For a long document, section scope is declared when the record is checked (see
+[`record_drift_check`](../reference/mcp-tools.md#record_drift_check)), not when it is anchored.
+
 **Always add the containing file as a second anchor — for code symbols and doc headings
 alike.** A heading rename or symbol move orphans the precise anchor on the next sync; the
 file anchor survives and keeps the decision retrievable (and its community fallback intact).

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/ci-cd-maintenance.md

@@ -228,8 +228,8 @@ the branch. (That holds on that checkout; on your own machine the merge base is
 target's tip only after you merged the target into your branch.) Run `sidegraph-verify` against that value: a local run against the fork point can
 differ, and CI's answer is the one that gates the merge. Findings and their remedies:
 [migrating to 0.17](migrating-to-0.17.md). A job that runs `sidegraph-doctor --check` exits `2`
-on the `store-not-migrated` and `maintenance-due` notices until the store is migrated or
-maintained.
+on the `store-not-migrated` notice until the store is migrated. The `maintenance-due` notice is
+reported but never fails `--check`.
 
 ## Recipe 3: scheduled triage
 

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/migrating-to-0.17.md

@@ -154,12 +154,12 @@ needs no other change. Three things to know:
   the target branch's tip, as CI computes it: `git merge-base origin/<target> HEAD` on GitHub's
   pull-request checkout gives that tip. A local `sidegraph-verify --against` run against the
   fork point can differ; CI's answer is the one that gates the merge.
-- **`sidegraph-doctor --check` exits 2 on the new notices.** While a store is unmigrated,
-  doctor reports `store-not-migrated`, and on a packed store with work pending it reports
-  `maintenance-due`; `--check` fails on any finding. A CI job that runs `doctor --check` turns
-  red until you migrate (or run maintenance). Migrate in the same window you upgrade the job,
-  or, since doctor has no flag to exclude a finding, run it with `--json` and filter the two
-  finding names out (for example with `jq`) before deciding.
+- **`sidegraph-doctor --check` exits 2 on an unmigrated store.** While a store is
+  unmigrated, doctor reports `store-not-migrated`, and `--check` fails on it. A CI job that
+  runs `doctor --check` turns red until you migrate. Migrate in the same window you upgrade the
+  job, or, since doctor has no flag to exclude a finding, run it with `--json` and filter that
+  finding name out (for example with `jq`) before deciding. On a packed store with work
+  pending doctor reports `maintenance-due`; since 0.19.0 `--check` does not fail on it.
 - **`sidegraph-verify` has new findings**, all errors: `bad-shard-line`, `shard-conflict`,
   `duplicate-packed-record`, `shadow-divergence`, `binding-entry-dropped`, `shard-name-case`
   and `shards-without-format2` (these on the tree itself), and `shard-body-without-source` and
@@ -168,9 +168,9 @@ needs no other change. Three things to know:
 
 A tool that reads the store files directly, not through Sidegraph, now has to read shard lines
 too: [store format](../reference/store-format.md#format-2-packed-shards) says how. ADR export
-works as before, but each ADR's `Record:` link then points at the shard file (not the
-per-record file), so the first export after the migration rewrites every ADR document, and
-again after maintenance folds a file.
+works as before. Before 0.19.0, each ADR's `Record:` link pointed at the record's file or
+shard, so an export after migration or maintenance rewrote every ADR document; since 0.19.0
+generated documents name store records by id and stay byte-identical.
 
 ## Open branches
 

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/retrieval-in-sessions.md

@@ -297,5 +297,8 @@ Use `sidegraph:triage-drift` to read the claim and current code. If the claim st
 `record_drift_check` can append a justified inspection of the current clean committed
 files without changing the decision. If it no longer holds, propose a real successor.
 The [tool reference](../reference/mcp-tools.md#record_drift_check) describes refusal cases
-and coverage. Changed inspected files or scope re-arm the warning; unrelated commits do
-not. The check is an attributed assertion and can be wrong.
+and coverage. Changed inspected files or scope re-arm the warning, and for a markdown file
+checked with declared sections only a change to a declared or also-watched section or to the
+file's link definitions does; unrelated commits do not. The check is an attributed assertion and can be wrong. `sidegraph-doctor` groups the
+records by drifted file and may note `anchored region unchanged; sibling sections of the file
+may still matter`: that shortens the reading, it does not replace it.

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/team-workflow.md

@@ -54,7 +54,7 @@ local branches, with a notice when such a branch is more than a week old
 `.sidegraph/` in the same pull request as the work that produced the records, and merge the
 branch that holds the rest. Fully staged store files do not count toward `store-uncommitted`,
 so that one check never blocks the commit that fixes it. A pre-commit hook that runs
-`sidegraph-doctor --check` still fails often. `--check` makes every advisory finding exit `2`,
+`sidegraph-doctor --check` still fails often. `--check` makes every advisory finding except `maintenance-due` exit `2`,
 and `code-drift` is one of them: it fires after any commit that touches a file an accepted
 record is anchored to. For a gate on the store itself, use `sidegraph-verify`. It exits `2`
 only for a violation of the store's own write rules, and `0` for a clean store whatever the

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/guides/troubleshooting.md

@@ -134,7 +134,8 @@ notice.
 Records needing content review after code changed or a prior scoped check stopped applying.
 The line says how many. Inspect current code: record an explicit `record_drift_check` if the
 claim still holds, or propose a real successor if it does not. There is no user notice.
-`sidegraph-doctor` lists them as `code-drift` findings, and the `sidegraph:triage-drift` skill walks them.
+`sidegraph-doctor` lists them as `code-drift` findings, grouped by the drifted file with one `git diff` per distinct
+change (`sidegraph-doctor --flat` prints one line per record instead), and the `sidegraph:triage-drift` skill walks them.
 `SIDEGRAPH_DRIFT_NUDGE=off` silences the line.
 
 ### graph-borrowed
@@ -326,7 +327,7 @@ legacy `archive/` segment that maintenance would delete, a shard line in the wro
 repeated with an equal body, or a stray shard file. Nothing is broken, and `sidegraph-verify`
 does not report these states. A segment that stays because one of its lines is not safe to
 delete does not count. Run `sidegraph-compact` on the default branch. Doctor lists one finding
-at the store path, and `--check` exits `2` on it. A legacy segment that maintenance would delete counts, whether its records are already in shard
+at the store path; `--check` reports it but does not exit `2` on it. A legacy segment that maintenance would delete counts, whether its records are already in shard
 lines or maintenance would pack them. The check does not consult git, so a record file that
 still has to settle (or is untracked) is not predicted. It reads the shard files once; a store
 with more than 200 per-record files is decided from the directory listing.
@@ -411,7 +412,7 @@ not reported: nothing was switched off.
   `~/.claude/settings.json`.
 - **Where it runs.** The session surface and doctor. Not run outside a git repository, with no
   `git`, or when `git ls-files` takes longer than five seconds. Doctor lists the finding with the
-  code `plugin-off-in-subdirectories`, and `--check` exits `2` on it like any finding.
+  code `plugin-off-in-subdirectories`, and `--check` exits `2` on it.
 - **Why only a root launch tells you.** A session started in a directory where the plugin is off
   runs no SessionStart hook, so nothing speaks there. The line (and the notice, with case (b))
   comes from a session at the root, and the finding from doctor and the setup skill.

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/reference/cli.md

@@ -1363,11 +1363,11 @@ plain-text line):
 | `snapshot-without-requirement` | snapshot | a `domain-snapshot.json` exists but the `format` marker does not require Sidegraph 0.14.0 or later |
 | `bad-validity-window` | snapshot | `valid_to < valid_from` on a decision or fact |
 | `superseded-without-successor` | snapshot | a `status=superseded` record has no other record's `supersedes` pointing back at it (a successor held by a file skipped for its unsafe name still counts) |
-| `dangling-supersedes` | snapshot | a `supersedes` id doesn't resolve to any record, hot or archived (a file skipped for its unsafe name still counts as the record it holds, so renaming it back is the only heal) |
-| `dangling-binding-entity` | snapshot | a binding's `entity_id` doesn't resolve to any `entities/<id>.json` (an entity held by a file skipped for its unsafe name still counts) |
-| `dangling-fact-support` | snapshot | a fact's `supports` id doesn't resolve to any decision (a file skipped for its unsafe name still counts, as for `dangling-supersedes`) |
-| `dangling-drift-check` | snapshot | an auxiliary verification references no hot or archived decision; terminal targets remain valid history |
-| `dangling-parent` | snapshot | a domain's `parent_id` doesn't resolve to any domain, hot or archived (a superseded, dropped or archived parent still counts, as the write path only checks that it exists; a file skipped for its unsafe name counts too, as for `dangling-supersedes`) |
+| `dangling-supersedes` | snapshot | a `supersedes` id doesn't resolve to any record, hot or archived (a file skipped for its unsafe name still counts as the record it holds, so renaming it back is the only heal; a regular file with a safe name that does not decode counts as the record its name names, so it gives one `parse-error` and no finding here; a directory or other entry named like a record file does not) |
+| `dangling-binding-entity` | snapshot | a binding's `entity_id` doesn't resolve to any `entities/<id>.json` (an entity held by a file skipped for its unsafe name still counts, and so does an entity file that does not decode) |
+| `dangling-fact-support` | snapshot | a fact's `supports` id doesn't resolve to any decision (a file skipped for its unsafe name, or one that does not decode, still counts, as for `dangling-supersedes`) |
+| `dangling-drift-check` | snapshot | an auxiliary verification references no hot or archived decision; terminal targets remain valid history (a decision file with a safe name that does not decode counts, as for `dangling-supersedes`) |
+| `dangling-parent` | snapshot | a domain's `parent_id` doesn't resolve to any domain, hot or archived (a superseded, dropped or archived parent still counts, as the write path only checks that it exists; a file skipped for its unsafe name, or one that does not decode, counts too, as for `dangling-supersedes`) |
 | `parent-cycle` | snapshot | the `parent_id` chain of some domains loops back on itself (a domain that is its own parent included); reported once per cycle, at the domain with the smallest id on it, and not for a domain that merely hangs off the cycle |
 | `duplicate-ulid` | snapshot | the same internal id appears in more than one canonical location — two hot files, a hot file plus any archive copy, or two archive segments whose payloads for that id actually differ. **Exempt:** two or more archive segments carrying byte-*identical* payloads for the same id — a sanctioned cross-branch `sidegraph-compact` merge (independent compaction on two branches, later merged) — see [`reference/store-format.md#archive-segments-sidegraph-compact`](store-format.md#archive-segments-sidegraph-compact). **On a packed (format 2) store** a hot file beside an archive line is not a duplicate when the file holds the line's state or a legal successor of it, and a shard line beside an archive line is not when it does or when the archive line is a legal successor of the shard line; a per-record file beside a shard line is the normal state before maintenance and is judged by `shadow-divergence` |
 | `bad-archive-segment` | snapshot | an `archive/*.jsonl` entry is not a regular file (`unreadable: not a regular file`), or a line isn't valid UTF-8 or JSON, isn't a JSON object, or holds a decision or domain that fails its model, can't be serialised, or has a nonterminal status. Schema/decode failures match the lines the reload leaves out; the verifier additionally rejects nonterminal archive records (one violation per line, naming the segment and the line number) |
@@ -1385,7 +1385,7 @@ plain-text line):
 | `illegal-status-jump` | transition | `status` changed to something that isn't a real write-path transition for that record kind |
 | `valid-to-unset` | transition | `valid_to` reverted from a value back to `null` |
 | `valid-to-changed` | transition | `valid_to` changed from one value to a *different* value (only `null → value`, once, is legal) |
-| `illegal-deletion` | transition | a record file — or an already-published archive segment — was deleted with no sanctioned reason. The one exception: a decision/domain preserved by same-kind, same-ID archive copies in the new tree, every copy schema-valid, compactable and a legal raw-payload transition from the baseline (a legitimate `sidegraph-compact`). An ID match alone is insufficient |
+| `illegal-deletion` | transition | a record file — or an already-published archive segment — was deleted with no sanctioned reason. The one exception: a decision/domain preserved by same-kind, same-ID archive copies in the new tree, every copy schema-valid, compactable and a legal raw-payload transition from the baseline (a legitimate `sidegraph-compact`). An ID match alone is insufficient. A file the store never loaded (an unsafe file name, or an unsafe id in the baseline) is not a record: deleting or editing it adds no transition finding, and the snapshot's `unsafe-record-id` covers it while it exists |
 | `shard-body-without-source` | transition | on a packed (format 2) store, a shard line added or changed since `GIT_REF` whose body is not the body of any occurrence of the same record in `GIT_REF` (a per-record file, a shard line or an archive line). `sidegraph-compact` only ever writes bodies it read, so a hand-forged line, or an edit folded in the same pull request that made it, is reported: land the edit on the target branch first, then fold |
 | `format-downgrade` | transition | the `format` marker went from major 2 in `GIT_REF` to a lower major. The one legal shape is the full rollback: no `shards/*.shard` file is left and every record is back in its per-record file with all its keys |
 
@@ -1459,8 +1459,9 @@ file — whether its default is `null` (`Provenance.commit` today) or an empty l
 and fills the field back in with that default. That alone is never a change: an absent field
 counts as the same value as an explicit `null` or an empty list/object, inside nested objects
 and inside the items of a list, everywhere this table calls a field immutable. A field whose
-default is a *non-empty* value (`Decision.scope`, `"repo"`) is **not** covered by this — an
-absent key there still reads as changed — but no file in this store lacks `scope` today.
+default is a *non-empty* value (`Decision.scope`, `"repo"`; `Entity.kind`, `"concrete"`) has
+its own narrower rule: an absent key equals exactly that default value on the other side, in
+either direction, and nothing else. A move to or from any other value is still a change.
 
 **Known limit:** `verify_against` compares only the net change across the whole diffed range
 (see "diffs the CURRENT WORKING TREE" below), not each intermediate commit. So a ratifier
@@ -1514,16 +1515,17 @@ Once any record, hot or archived, carries an `auto:` stamp, two more information
 When an entity is named by a path, full or partial, of its file (`src/sidegraph/store.py`, `sidegraph/store.py`) beside one named by that file's basename (`store.py`), a `spelling twins: N …` line follows, then one line per such entity: `<id> '<path name>' (K binding(s)) → <id> '<basename>' (M binding(s))`. Lookups and new anchors use the basename entity, and retrieval reaches both, so there is nothing to fix. Like the lines above, these are never findings, never change the exit code, and never appear in `--json`.
 
 ```
-sidegraph-doctor [--db PATH] [--against GIT_REF] [--check] [--stale-days N] [--json] [--graph PATH]
+sidegraph-doctor [--db PATH] [--against GIT_REF] [--check] [--stale-days N] [--json] [--flat] [--graph PATH]
 ```
 
 | Flag | Default | Meaning |
 |---|---|---|
 | `--db` | `$SIDEGRAPH_DIR` → existing `.sidegraph/` → `.sidegraph` | store directory; `$SIDEGRAPH_DB` honored for back-compat (deprecated) — same never-auto-create rule as `sidegraph-verify` (see above) |
 | `--against GIT_REF` | none | also run `sidegraph-verify`'s transition layer vs `GIT_REF` (identical semantics — same operational-error rules) |
-| `--check` | off | advisory findings also exit `2` (default: report only; a *skipped* check never fails, even with `--check`) |
+| `--check` | off | advisory findings also exit `2`, except `maintenance-due` (default: report only; a *skipped* check never fails, even with `--check`) |
 | `--stale-days N` | `30` | flag a proposed decision/domain whose id timestamp is strictly older than `N` days; must be `>= 0` |
-| `--json` | off | print `{"clean", "violations", "findings", "skipped"}` as one JSON object to stdout (nothing else) |
+| `--json` | off | print `{"clean", "violations", "findings", "skipped"}`, plus `drift_groups` when per-record `code-drift` is grouped, as one JSON object to stdout (nothing else) |
+| `--flat` | off | one `code-drift` line per record, as before: restores the flat listing and skips the grouping by file |
 | `--graph` | `$SIDEGRAPH_GRAPH` or `graphify-out/graph.json`, in the store's project | read-only input used for the `graph-root-mismatch` and `graph-stale` checks below; missing or unreadable skips both and says so (see *Skipped checks* below) |
 
 One-stop store health: composes `sidegraph-verify`'s strict snapshot (+ optional
@@ -1538,20 +1540,22 @@ never constructs a `Store`.
   exit `1` operational error only when `--against` requests the git-backed transition layer;
   the snapshot layer works without git.
 - **Advisory section** — `doctor.curate`: curation findings that never gate the exit code
-  by default; `--check` escalates them to exit `2`, mirroring `sidegraph-sync --check`.
+  by default; `--check` escalates them to exit `2`, mirroring `sidegraph-sync --check`. The
+  one exception is `maintenance-due`, routine upkeep on a healthy packed store: it is still
+  printed and still in `--json`, but never changes the exit code.
 
 **Finding codes** (the `code` field in `--json`'s `findings`, or the first column of a
 plain-text line):
 
 | Code | Meaning |
 |---|---|
-| `dangling-record` | an open decision (`proposed`/`accepted`) has no committed anchor set; an open fact (`valid_to` unset) has no anchor AND no `supports` id resolving to a LIVE (`proposed`/`accepted`) decision — an anchor alone, or a supports id resolving to a live decision, is reachability for a fact |
+| `dangling-record` | an open decision (`proposed`/`accepted`) has no committed anchor set; an open fact (`valid_to` unset) has no anchor AND no `supports` id resolving to a LIVE (`proposed`/`accepted`) decision — an anchor alone, or a supports id resolving to a live decision, is reachability for a fact. A fact that supports a decision whose file does not decode is not reported: that file is `sidegraph-verify`'s one `parse-error` |
 | `degraded-binding` | a binding's last recorded status (from `index.db`) is `degraded` |
 | `orphaned-binding` | a binding's last recorded status (from `index.db`) is `orphaned` |
 | `stale-proposal` | a proposed decision/domain whose ULID timestamp is strictly older than `--stale-days` |
 | `unreferenced-entity` | a hot entity no committed anchor set references (structural `domain:*`/`community:*` entities are exempt) |
 | `expired-open-validity` | a decision's `valid_to` is strictly past but its status is still open (`proposed`/`accepted`) |
-| `code-drift` | an open (`proposed`/`accepted`) decision's anchored file(s) changed since capture, or an earlier scoped check no longer applies; `record_drift_check` can record an explicit current inspection without rewriting the decision (MCP only); when binding statuses are uncomputed or unavailable, excludes committed deletions and says "binding status unknown"; also carries the "N record(s) predate commit stamping — not checkable" and git-unavailable notes, in place, when either applies |
+| `code-drift` | an open (`proposed`/`accepted`) decision's anchored file(s) changed since capture, or an earlier scoped check (including its declared sections) no longer applies; `record_drift_check` can record an explicit current inspection without rewriting the decision (MCP only); when binding statuses are uncomputed or unavailable, excludes committed deletions and says "binding status unknown"; also carries the "N record(s) predate commit stamping — not checkable" and git-unavailable notes, in place, when either applies. The default text groups the per-record lines by drifted file (`code-drift: N record(s) in M file group(s)`), numbers each distinct `git diff <old blob> <new blob>` once, and may add `anchored region unchanged; sibling sections of the file may still matter` to a record whose anchored Python function or Markdown section is textually identical at both ends; `--flat` restores one line per record. The hint is a reading aid, never a verdict: it changes no count and no exit code. `--json` adds a sibling `drift_groups` key (`partial`, `notes`, `groups[].records[]` with `basis`, `reason`, `diff` and `hint`); `findings` is unchanged |
 | `never-surfaced` | an accepted decision has `0` shows against `N > 0` queries on its anchored file(s) — anchored where people repeatedly work, never once rendered or injected by a hook |
 | `stale-instructions` | an auto-injected agent-instructions file beside the store (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`) still carries the distinctive wording of a **superseded** decision — that file reaches the agent at turn zero, before retrieval, so an abandoned rule surviving there outranks the store's correction by default. Verbatim-ish match on normalized text with length/word floors; superseded records only; no git call. Advisory: it reports a quotation, not a proven contradiction — the file may be narrating history |
 | `unratified-accept` | an **accepted** record whose provenance says `agent` and which carries no ratifier stamp — the signature `SIDEGRAPH_AUTO_ACCEPT=on` leaves in a shared store (one environment's setting bypassing the ratification gate for everyone). Scoped to records created at/after the EARLIER of the store's earliest ratifier stamp and its creation marker (`.sidegraph/stamping_live_since`, written once when a store is genuinely new — never backfilled onto an existing one), so a store predating both reports nothing rather than everything; a store that has never ratified anything but was created by a marker-writing version is still in scope from its own creation, closing the blind window an unratified store would otherwise sit in forever. A stamped record — including one stamped `auto:<policy>` by an auto-ratification policy — and a human-sourced one are never flagged. A **supersession successor** (`supersedes` set — `supersede_decision`/`supersede_fact`) is never flagged either: reversal has no ratification queue to bypass and lands accepted immediately by design, so it reproduces the signature with no relation to the env var this check hunts. Narrowed exception: a `supersedes`-bearing record IS still flagged if it carries a `layer`, a `provenance.ref`, or a tier-0 `tag:`/`initiative:` binding absent from its predecessor — neither `supersede_decision` nor `supersede_fact` can produce any of the three, so one present proves the `propose_decisions`/auto-accept path wrote it. (The fact half is defensive only: `supersede_fact` always stamps `source="human"`, so a fact successor never reaches this agent-sourced check, and no draft shape carries `supersedes` on a fact.) Only a MINIMAL superseding draft (none of the three) is indistinguishable from a legitimate successor by the record's own fields, and stays excluded — a known, accepted, narrower trade-off than treating every supersession alike. Advisory: the signature is not proof — verify before concluding |
@@ -1561,11 +1565,11 @@ plain-text line):
 | `graph-stale` | the graph was built at a commit HEAD has moved past (graph.json's `built_at_commit`), and a file the graph should reflect changed since: one it holds was edited after the graph was last built (the later of `graph.json`'s and its sibling `manifest.json`'s modification times) or deleted, or a new file of a type it holds now exists (not under a dot-directory, which Graphify skips). Memory cannot see or anchor to code added after the build. The detail gives the build commit, how many commits behind HEAD (or "a commit outside HEAD's history" after a checkout of an older commit), how many files changed, and up to five example paths; the fix is to rebuild from the repository root by running `graphify update .` with the environment variable `GRAPHIFY_NO_AUTO_REFRESH=1` set, then `sidegraph-sync`. Silent when the build commit is HEAD, when only file types the graph does not hold changed (a `.yml` against a `.py`-only graph), and when a graph built from a dirty tree was committed afterwards, or a `graphify update .` found nothing to change and rewrote only `manifest.json` (the file is no newer than the build); also silent when the comparison cannot be made (no `built_at_commit`, one that is not a full commit id, a graph outside a git repository, a build commit the repository lacks, git unavailable or slower than 3 seconds). **`--check` exits `2` on it**, so a CI job that runs doctor should rebuild the graph first; one that does is unaffected. Needs `--graph` to resolve |
 | `orphaned-record` | an open (`proposed`/`accepted`) decision or fact whose every Tier-2 (leaf) anchor is `orphaned`, so retrieval reaches it only through its file or domain; one finding per record, at its canonical file, naming how many leaf anchors it has. Statuses come from `index.db` and read "as of last sync", so the check is skipped while the statuses are not computed for the current graph (see *Skipped checks* below; run `sidegraph-sync`). It is the record-level view of `orphaned-binding` (any record it flags has orphaned bindings, which that code already reports), so it adds no new reason for `--check` to exit `2`. The fix is to rebuild a stale graph, then `sidegraph-sync`; otherwise re-anchor the record with `add_anchors` or the `heal-anchors` skill, or supersede it if the code is gone. Needs a usable `index.db` |
 | `store-uncommitted` | store files nobody committed for at least 24 hours: records, bindings, entities, an archive segment or the root files (`format`, `.gitignore`, `stamping_live_since`) that `git status` shows as new, modified or deleted. One finding, at the store path, naming how many files there are, how old the oldest is and what kinds they are (a new `archive/` segment beside deleted records reads as "a compaction"). A new record or entity file is aged by its ULID name, which a `git stash` cannot rewrite; a modified file, or anything under `bindings/`, by its modification time; a deleted file by its subdirectory's, a lower bound. Entries fully staged in the index are not counted, so a `--check` run in a pre-commit hook does not block the commit that fixes the problem. **`--check` exits `2` on it.** The fix is to commit the store in a pull request. Silent, and not run, outside a git repository, with no `git`, or when git is slower than 2 seconds |
-| `plugin-off-in-subdirectories` | Claude Code sessions started below the repository root run without the Sidegraph plugin. Claude Code reads the project settings (`.claude/settings.json`) of the launch directory only, and the repository root's `.claude/settings.local.json` for every launch inside the repository; `enabledPlugins` merges key by key (user settings, then project, then local). Two problems, reported as up to two findings: (a) the plugin is enabled only in the root's `.claude/settings.json`, so every directory below the root without its own enabling settings runs without it (reported at that file); (b) nested directories with a `.claude/settings.json` or `.claude/settings.local.json` of their own that sets `enabledPlugins` and whose merge leaves the plugin off (reported at the first such directory, naming how many there are; a nested settings file without `enabledPlugins` cannot change the merge, so it is not counted). The walk covers every directory that holds a tracked file (one `git ls-files` over the index, a few tens of milliseconds on a large repository) and looks for the two settings files in each directly, so a repository that ignores `.claude/` is covered. User settings are read from `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set and non-empty, else from `~/.claude/settings.json`. Silent when the plugin is not enabled for a launch at the root at all, and not run outside a git repository, with no `git`, or when `git ls-files` takes longer than 5 seconds. **`--check` exits `2` on it**, like any finding; enabling the plugin at user scope or in the root's `.claude/settings.local.json` clears it |
-| `refresh-helper-outdated` | a git hook runs an older graph refresh helper that uses directory-based locking (unsafe with uutils `mkdir`), or whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (Graphify 0.9.87 and later can rewrite installed agent skills after an upgrade). Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**, like any finding. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
-| `engine-version` | the graph was built by a Graphify release this Sidegraph was not tested with (its `graph.graphify_version` stamp is neither absent nor in the tested set), so anchors and domains may read differently. Advisory; **`--check` exits `2` on it**, like any finding. Pin Graphify to a tested release listed under [Engine version pinning](../integrations/graphify.md#engine-version-pinning), then rebuild the graph. It also fires for a mention-edge graph (Graphify 0.9.62 or later) over a store without a minimum Sidegraph version; follow the [0.14 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.14.md). A malformed marker leaves this second case silent. Silent without a readable graph |
-| `store-not-migrated` | the store uses the pre-0.17 layout (a format marker below major 2) and holds at least one record of any kind (initiatives included). One finding, at the store path, naming `sidegraph-migrate` (run on the default branch, after the team checklist in the [0.17 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.17.md)) and the `sidegraph:compact` skill. Degraded; **`--check` exits `2` on it**, like any finding. Silent on an empty store and on a store that is already format 2 |
-| `maintenance-due` | a format-2 store that `sidegraph-compact` would tidy: more than 200 per-record files, or a legacy `archive/` segment it would delete, or a misplaced or duplicated shard line, or a stray shard file. `sidegraph-verify` does not report these; maintenance heals them. A segment kept because one of its lines is not safe to delete does not count. Advisory; **`--check` exits `2` on it**, like any finding. Run `sidegraph-compact` on the default branch. Silent on a store that is not format 2 |
+| `plugin-off-in-subdirectories` | Claude Code sessions started below the repository root run without the Sidegraph plugin. Claude Code reads the project settings (`.claude/settings.json`) of the launch directory only, and the repository root's `.claude/settings.local.json` for every launch inside the repository; `enabledPlugins` merges key by key (user settings, then project, then local). Two problems, reported as up to two findings: (a) the plugin is enabled only in the root's `.claude/settings.json`, so every directory below the root without its own enabling settings runs without it (reported at that file); (b) nested directories with a `.claude/settings.json` or `.claude/settings.local.json` of their own that sets `enabledPlugins` and whose merge leaves the plugin off (reported at the first such directory, naming how many there are; a nested settings file without `enabledPlugins` cannot change the merge, so it is not counted). The walk covers every directory that holds a tracked file (one `git ls-files` over the index, a few tens of milliseconds on a large repository) and looks for the two settings files in each directly, so a repository that ignores `.claude/` is covered. User settings are read from `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set and non-empty, else from `~/.claude/settings.json`. Silent when the plugin is not enabled for a launch at the root at all, and not run outside a git repository, with no `git`, or when `git ls-files` takes longer than 5 seconds. **`--check` exits `2` on it**; enabling the plugin at user scope or in the root's `.claude/settings.local.json` clears it |
+| `refresh-helper-outdated` | a git hook runs an older graph refresh helper that uses directory-based locking (unsafe with uutils `mkdir`), or whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (Graphify 0.9.87 and later can rewrite installed agent skills after an upgrade). Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
+| `engine-version` | the graph was built by a Graphify release this Sidegraph was not tested with (its `graph.graphify_version` stamp is neither absent nor in the tested set), so anchors and domains may read differently. Advisory; **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. Pin Graphify to a tested release listed under [Engine version pinning](../integrations/graphify.md#engine-version-pinning), then rebuild the graph. It also fires for a mention-edge graph (Graphify 0.9.62 or later) over a store without a minimum Sidegraph version; follow the [0.14 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.14.md). A malformed marker leaves this second case silent. Silent without a readable graph |
+| `store-not-migrated` | the store uses the pre-0.17 layout (a format marker below major 2) and holds at least one record of any kind (initiatives included). One finding, at the store path, naming `sidegraph-migrate` (run on the default branch, after the team checklist in the [0.17 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.17.md)) and the `sidegraph:compact` skill. Degraded; **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. Silent on an empty store and on a store that is already format 2 |
+| `maintenance-due` | a format-2 store that `sidegraph-compact` would tidy: more than 200 per-record files, or a legacy `archive/` segment it would delete, or a misplaced or duplicated shard line, or a stray shard file. `sidegraph-verify` does not report these; maintenance heals them. A segment kept because one of its lines is not safe to delete does not count. Advisory, and the one finding **`--check` does not escalate**: it is printed and listed in `--json`, but the exit code stays `0`. Run `sidegraph-compact` on the default branch. Silent on a store that is not format 2 |
 
 `degraded-binding`/`orphaned-binding` come from `index.db`, opened strictly read-only — it
 is the only source for binding status (canonical `bindings/*.json` files carry identity,
@@ -1617,7 +1621,8 @@ neither flagged nor cleared. `drill_down` does record a `domain:<slug>` seed, bu
 consumes it yet; its *shows* count normally, so surfacing only through a domain drill-down
 still protects a decision from a false flag.
 
-Each JSON finding has `code`, `path`, `detail`, `record_id` and `record_type`.
+Each JSON finding has `code`, `path`, `detail`, `record_id`, `record_type` and `first_seen`
+(the ISO time Sidegraph first saw a `code-drift` finding's record drifted, otherwise `null`).
 Per-record findings carry their logical identity (`decision`, `fact`, `entity`, `domain`,
 or `bindings`); global notes have null record fields. A malformed raw record whose id
 cannot be read also has a null subject; use its violation and physical path for repair. `path` retains the physical source,
@@ -1651,13 +1656,15 @@ of the lines above. A store whose format marker refuses this version also skips
 checks: `remaining checks skipped (<the reason>)`, for example
 `remaining checks skipped (This store requires Sidegraph >= 0.15.0; this is 0.14.0.)`.
 A missing graph is deliberately not a finding: `--check` escalates
-every finding, so a CI job that runs doctor without building a graph would start exiting `2`.
+every finding except `maintenance-due`, so a CI job that runs doctor without building a graph
+would start exiting `2`.
 
 **Exit code:** `0` healthy — advisory findings alone stay `0` without `--check`. `1`
 operational error — same paths as `sidegraph-verify` (unreadable store; or, when `--against`
 is used, a bad ref or store outside any git repo), plus a negative `--stale-days`, rejected before the
 store is touched (same hard-usage treatment as `sidegraph-import --limit`). `2` strict
-violations, or — with `--check` — advisory findings too.
+violations, or — with `--check` — advisory findings too, except `maintenance-due`, which never
+changes the exit code.
 
 **Examples:**
 
@@ -1760,8 +1767,10 @@ What lands in the bundle:
   before, abandoned because…" is the product; the export doesn't hide it. The one thing it
   does hide is unratified `proposed` drafts — those have not entered the shared memory yet,
   so they are never published (proposed domains are dropped the same way).
-- `domains/` — one concept per slug (the latest revision row wins), with parent links
-  and an `# Anchored records` backlink section.
+- `domains/` — one concept per slug, with parent links and an `# Anchored records`
+  backlink section. The page shows the slug's current row: a row loses to every row of its
+  slug that has no later revision under that slug, following supersession through any slug,
+  and among the rest the newest id wins.
 - `entities/` — only entities actually referenced by an exported anchor; each page lists
   every decision/fact anchored to it. Bindings to `domain:*` entities link to the domain
   page instead; volatile `community:*` bindings are not exported at all.

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/reference/configuration.md

@@ -15,7 +15,7 @@ a per-call parameter, not an environment/config setting.
 | `SIDEGRAPH_CAPTURE_NUDGE` | unset | `host/hooks.py` (`stop` only). Set to `off` to disable the `Stop` block-to-distill nudge entirely — no other value has any effect. See [`reference/hooks.md`](hooks.md#sidegraph-stop). |
 | `SIDEGRAPH_RATIFY_NUDGE` | unset | `host/hooks.py` (`session_start` only). Set to `off` to disable the pending-ratification line entirely — no other value has any effect. See [`reference/hooks.md`](hooks.md#sidegraph-session-start). |
 | `SIDEGRAPH_SUBAGENT_BRIEF` | unset | `host/subagent.py` (`subagent_start` only). Set to `off` to stop the `SubagentStart` hook from giving each subagent the memory brief — no other value has any effect. See [`reference/hooks.md`](hooks.md#sidegraph-subagent-start). |
-| `SIDEGRAPH_DRIFT_NUDGE` | unset | `host/hooks.py` (`session_start` and `stop`). Set to `off` to suppress the two drift PROSE surfaces — the SessionStart "N record(s) need content review" line and the Stop-nudge drift clause. **The code-drift cache refresh still runs either way** (it is what keeps the `[drifted]` retrieval markers fresh — gating it would freeze markers at their last pre-`off` state), and the `[drifted]` tags in `get_task_context`/`query_decisions`/`drill_down` output are retrieval content, not gated by this switch. No other value has any effect. See [`reference/hooks.md`](hooks.md#sidegraph-session-start). |
+| `SIDEGRAPH_DRIFT_NUDGE` | unset | `host/hooks.py` (`session_start` and `stop`). Set to `off` to suppress the two drift PROSE surfaces — the SessionStart "N record(s) need content review" line (its recency clause included) and the Stop-nudge drift clause. **The code-drift cache refresh still runs either way** (it is what keeps the `[drifted]` retrieval markers fresh — gating it would freeze markers at their last pre-`off` state), and the `[drifted]` tags in `get_task_context`/`query_decisions`/`drill_down` output are retrieval content, not gated by this switch. No other value has any effect. See [`reference/hooks.md`](hooks.md#sidegraph-session-start). |
 | `SIDEGRAPH_AUTO_ACCEPT` | unset | `server.py` (`propose_decisions`'s tool shell, read at point of use via `_auto_accept()`). Set to `on` to land agent-proposed decisions and facts as `status="accepted"` directly, bypassing the ratification queue — no other value has any effect, and `propose_domains` is never affected by this flag (domains always land `proposed` under it; only `SIDEGRAPH_RATIFY_POLICY=auto-all` can ratify an eligible domain, with a stamp). Detectable after the fact: `sidegraph-doctor`'s `unratified-accept` finding reports accepted agent-sourced records carrying no ratifier stamp, so a shared store can assert the gate in CI rather than trust it. See [`guides/capturing-decisions.md#4-auto-accept-opt-in`](../guides/capturing-decisions.md#4-auto-accept-opt-in). |
 | `SIDEGRAPH_RATIFY_POLICY` | unset (`"manual"`) | `server.py` (`_ratify_policy()`, read at point of use inside the `propose_decisions` and `propose_domains` tool shells) and `cli.py` (each of the doc-import, rationale-import, and domain-bootstrap commands, read once immediately before its batch call). Parsed by the pure `capture.parse_ratify_policy`, which never reads the environment itself — every reader above resolves the raw value and threads the parsed policy down as a keyword, so one batch samples a single value throughout. `manual` (default) introduces no new transition and leaves every existing write path's semantics exactly as they are — it does not mean every write lands `proposed`; some paths already land `accepted` under their own pre-existing flags (e.g. `importer.py`'s `propose=False`), unaffected by this knob. `auto-low-risk` lets eligible `lesson`/`gotcha` decisions and standalone facts self-ratify at write time (never `adr`/`constraint` decisions or domains). `auto-all` additionally admits `adr`/`constraint` decisions and domains. Eligibility is deterministic and conjunctive: the policy admits the shape (under `auto-low-risk` a draft that `supersedes` another is never eligible); the record has at least one live Tier-1/Tier-2 anchor binding (a domain instead needs a graph reader, a clean `path_prefixes` lint, and a resolving seed anchor or non-empty prefixes); the write was clean and not a dry run; provenance is present. An attached fact never ratifies itself — it rides its decision's cascade, and one ineligible attached fact keeps the decision proposed. Scope: `propose_decisions` (decisions and standalone facts), `propose_domains` (`auto-all` only), `sidegraph-import` rationale mode only with `--propose`, `sidegraph-import --docs` only for `--propose` writes that land as a new `proposed` record (status-derived drafts, `superseded` re-imports and `status: rejected` documents never auto-ratify), and `sidegraph-domains bootstrap` (`auto-all` only; a candidate whose derived `path_prefixes` is empty stays proposed); `--dry-run` never transitions, and `add_domain`, `sidegraph-domains add`, `supersede_domain` successors and `sidegraph-bootstrap` are never affected. Under either auto policy a superseding proposal's predecessor stays open until the successor is ratified — automatically, or later by a human. Outcomes are always reported: `ratified_by`/`auto_ratify_error` on each propose result; under a non-`manual` policy the three CLI batch summaries append `, auto-ratified N` and print each failure on stderr as `auto-ratify failure: <id>: <reason>`; `sidegraph-doctor` adds two informational lines (see [`cli.md`](cli.md#sidegraph-doctor)). Matching is exact after trimming surrounding whitespace — `AUTO-ALL` falls back to `manual`. `sidegraph-init` never writes this value silently: in an interactive terminal it asks one question, defaulting to `auto-low-risk` on a bare Enter, and writes whichever answer the person gave (`auto-low-risk` or `manual`) into the project's `.claude/settings.json` `env` block explicitly; outside a terminal (CI, a script, an agent-driven session) it asks nothing and writes nothing, printing the line to add by hand instead; either way it never overwrites an existing value there. `--ratify-policy VALUE` sets it with no prompt, and `--no-settings` skips the whole step (see [`cli.md`](cli.md#sidegraph-init)). `manual` remains the library's own default when the variable is unset with no committed override, and is also what a freshly initialized project gets unless a person answers yes to the prompt (or passes `--ratify-policy auto-low-risk`/`auto-all`); `adr`/`constraint` decisions and domains still wait for a human under both `manual` and `auto-low-risk`. For a committed, CI-checkable setting, pin it in the repository's `.claude/settings.json` `env` block. Claude Code applies that block to the MCP server; under any other host the `sidegraph-mcp` entry point reads the committed value from the selected store's project when its environment sets none (an explicit environment value wins), so the policy also applies under Codex. Any unknown or empty value falls back to `manual` — fail-safe, never fail-open, the `SIDEGRAPH_PROPOSAL_WINDOW_DAYS` precedent. Auto-ratified records are stamped `ratified_by="auto:<policy>"`, distinguishing them from human review. When both knobs are set, legacy `SIDEGRAPH_AUTO_ACCEPT=on` wins over this policy — its direct-`ACCEPTED`, stamp-less write lands before any auto-ratify block runs, and `sidegraph-doctor`'s `unratified-accept` finding keeps flagging it regardless. |
 | `SIDEGRAPH_UNRATIFIED` | unset (`"on"`) | `store_layout.py` (`proposal_surfaces`, read at point of use — the single proposal-surfacing policy every render surface funnels through: `retrieval.py` delegates to it, and so does the PreToolUse hook's index reader). Set to `off` for **regulated mode**: `proposed` records never surface as content — not in `get_task_context`, drill-down, the SessionStart TOC's unratified block, the PreToolUse records block, or the records appended to a subagent's brief on an `Agent` call — regardless of age. The `SubagentStart` brief's counts then include accepted decisions only. The SessionStart pending-ratification **counter stays** (it is queue metadata, not record content). No other value has any effect. For a committed, CI-checkable setting, pin it in the repository's `.claude/settings.json` `env` block. See [`hooks.md`](hooks.md#sidegraph-session-start). |

{sidegraph-0.18.0 → sidegraph-0.20.0}/docs/reference/hooks.md

@@ -256,10 +256,18 @@ raises costs only its own line.
    `$SIDEGRAPH_DRIFT_NUDGE != "off"`, one more line is appended (own `try/except`, same
    never-cost-the-map guard as step 6). Verbatim, with `N` substituted:
 
-   > Sidegraph: N record(s) need content review: code changed or a prior check no longer applies —
+   > Sidegraph: N record(s) need content review (M new in the last 7 days): code changed or a prior check no longer applies —
    > task-relevant ones carry a [drifted] tag in retrieval; full list: sidegraph-doctor;
    > record_drift_check if still true, supersede if no longer true.
 
+   The parenthesised clause counts the records first seen drifted within the last 7 days; it
+   reads `(none new in the last 7 days)` when there are none and `(M new since YYYY-MM-DD)`
+   while the index is younger than 7 days. A record the store has not stamped counts as unknown
+   age, never as new, and the clause is left out whenever it cannot be certified. An index
+   built before this version prints no clause on its first day (a zero count that early says
+   nothing), `(none new since <date>)` while its stamping is younger than 7 days, and
+   `(none new in the last 7 days)` from then on, until a record newly drifts.
+
    `N` counts the whole store; the `[drifted]` tags (see
    [`concepts/retrieval.md`](../concepts/retrieval.md)) mark only the records a given
    retrieval call actually surfaces — the line says where each lives. A duplicate