sidegraph 0.19.0__tar.gz → 0.20.0__tar.gz

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

@@ -7,6 +7,44 @@ 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-0.19.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.19.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.19.0 → sidegraph-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.19.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.19.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.19.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.19.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.19.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.19.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.19.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

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

@@ -1515,7 +1515,7 @@ 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 |
@@ -1524,7 +1524,8 @@ sidegraph-doctor [--db PATH] [--against GIT_REF] [--check] [--stale-days N] [--j
 | `--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`, 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
@@ -1554,7 +1555,7 @@ plain-text line):
 | `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 |
@@ -1620,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,

{sidegraph-0.19.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.19.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

{sidegraph-0.19.0 → sidegraph-0.20.0}/docs/reference/mcp-tools.md

@@ -30,7 +30,8 @@ Git commands for provenance, initiative, ratification identity and graph checks
 EOF on standard input, keeping subprocesses separate from the MCP protocol stream.
 
 The development lockfile selects FastMCP 3.4.11 and MCP Python SDK 1.30.0. Supported package
-dependencies are `fastmcp>=3.4.10,<4` and `mcp>=1.30,<2`, with runtime security floors
+dependencies are `fastmcp>=3.4.10,<4`, `mcp>=1.30,<2` and `markdown-it-py>=4,<5` (it reads
+markdown structure for [declared-section drift checks](#record_drift_check)), with runtime security floors
 `certifi>=2026.10.19` and `opentelemetry-api>=1.45.1`. The locked stack
 uses the `initialize` / `notifications/initialized` lifecycle and negotiates protocol
 versions through **2025-11-25**. The server reports Sidegraph's package version in
@@ -1816,6 +1817,7 @@ record_drift_check(
     checked_commit: str,   # current full inspected Git HEAD
     files: list[str],     # all required anchor files plus inspected dependencies
     rationale: str,       # nonblank, redacted before validation; at most 4000 characters
+    sections: list[dict] | None = None,  # optional: markdown sections you read
 ) -> dict
 ```
 
@@ -1840,8 +1842,49 @@ An unloadable required entity returns `unavailable_anchor_scope`; a failed initi
 scope lookup returns `git_scope_unavailable`. Both refusals occur before check publication.
 Write errors keep their bounded schema vocabulary and do not echo file names or raw causes.
 
+**Declared sections.** For a markdown file in `files`, `sections` narrows the check to the
+sections you read:
+
+```python
+sections=[{"file": "docs/spec.md",
+           "headings": [["55.2 Rules"]],            # 1-32 declared, read at HEAD
+           "also_watch": [["56. Echo", "56.4 Amendments"]]}]  # 0-32 siblings the claim depends on
+```
+
+Each chain is the trailing part of a heading chain, outermost first, 1-6 segments of 1-200
+characters; a suffix matching two sections is `ambiguous_section`. At most 16 files, 32
+sections per file and 64 per check; every `file` must be in `files` and end in `.md` or
+`.markdown`. The writer resolves each chain against the HEAD blob and stores hashes only: no
+heading text reaches the capsule. A section includes its subsections, up to the next heading
+of the same or a higher level. Never declare a section you did not read. Afterwards the record
+re-arms on that file only when a declared or also-watched section, or the file's link
+reference definitions, change; other checked files compare as before. A file whose structure
+cannot be bounded is compared whole, as are unknown schemes and roles. Section parsing uses
+`markdown-it-py` (CommonMark block structure, no inline pass).
+
+The writer refuses with these fixed codes, before anything is published:
+
+| Code | When |
+|---|---|
+| `section_file_not_in_files` | a `sections` file is not in `files` |
+| `section_file_not_markdown` | the extension is not `.md` or `.markdown` |
+| `section_file_too_large` | one declared blob is over 2 MiB or 20,000 lines |
+| `section_scope_too_large` | the distinct declared blobs together exceed 8 MiB or 20,000 lines |
+| `section_text_unavailable` | the text is not UTF-8, could not be read (including any read in a partial clone on Git older than 2.45, which could fetch), or the 3 s budget ran out |
+| `section_file_unsupported` | a heading sits inside a list item or quote, a footnote reference is in a declared span, or a parser cap was hit |
+| `unknown_section` | no heading chain ends with the given segments |
+| `ambiguous_section` | the suffix matches more than one section |
+| `duplicate_section` | the same section twice, or in both lists |
+| `duplicate_section_file` | a `file` appears twice |
+| `too_many_sections` | over 32 sections in a file or 64 in a check |
+
 The result names `id`, `decision_id`, `checked_commit`, `required_files`, `checked_files`,
-`provenance`, `cache_cleared` and `redactions`. `cache_cleared` only says whether an existing
+`provenance`, `cache_cleared` and `redactions`. With `sections` it also carries
+`declared_sections`: per file `{path, scheme, total_lines, sections: [{heading, role,
+first_line, lines}]}`, the readable chain you declared with its 1-based first line and length.
+Check it: a section spanning most of the file gains nothing, and a `first_line` that is not
+where the heading sits in your viewer means the parser disagrees with your renderer, so make a
+whole-file check. The echo is never stored. `cache_cleared` only says whether an existing
 valid derived cache contained and removed this decision; other cached ids stay intact.
 When additional anchor paths lie outside inspected coverage, pruning is deferred to the
 normal refresh so a check cannot hide their capture warning.
@@ -1851,7 +1894,12 @@ retrying; SQLite rollback does not remove an already published immutable file.
 
 A matching check compares current decision/leaf identity, exact required-file coverage,
 and stored file blob ids plus modes. Changed checked dependencies, deletion, mode or
-subject/scope changes re-arm review even if capture's original files match again.
+subject/scope changes re-arm review even if capture's original files match again. For a
+file with declared sections, only a change to a declared or also-watched section or to the
+file's link reference definitions re-arms it; the reasons are `declared section changed`,
+`declared section not found`, `also-watched section changed` and `referenced link definition
+changed`, and `section scope unavailable; whole file compared` when the sections cannot be
+bounded (the whole file then re-arms on any change, as before).
 Unrelated commits and identical bytes after squash/revert do not re-arm. The original
 checked commit remains provenance and need not exist locally after a squash/clone.
 Git/FS edits outside Sidegraph can race the final cleanliness/HEAD check and publication;

{sidegraph-0.19.0 → sidegraph-0.20.0}/docs/reference/stability.md

@@ -25,8 +25,8 @@ described a mode that had not existed for weeks, because no test looked there.
 
 | Surface | What is fixed | What guards it |
 |---|---|---|
-| **The store on disk** — `.sidegraph/` layout (one JSON file per record, and from 0.17 optionally packed `shards/`), the `format` marker, `schema_version` | The current version is **0.6.0** (a format-2 store's index is stamped `0.7.0+format2`). `0.2.0`/`0.3.0` stores migrate automatically on first open (original kept as `*.migrated-backup`, never deleted). `0.4.0`/`0.5.0` reload in place. A future bump does one of those two or, as format 2 did, an explicit migration command (`sidegraph-migrate`) while the old format stays served — it never orphans a store. A store can require a minimum Sidegraph version (`sidegraph-require`): its marker becomes `sidegraph-store 1.0.0` plus `requires-sidegraph >= X.Y.Z`, and older versions refuse it. A packed store's marker is `sidegraph-store 2.0.0` plus a `requires-sidegraph` line and a `shards N` line; 0.14–0.16 refuse it, and the [0.17 migration guide](../guides/migrating-to-0.17.md) covers the switch. | `sidegraph-verify` lints every canonical file against the write-path invariants; `--against <ref>` classifies every changed file against the store's own transition rules |
-| **CLI commands, flags, exit codes** | 22 entry points, 99 flags. A flag is not removed without a deprecation window; documented exit codes keep their meaning | every parser option must appear in its `cli.md` section (`tests/test_docs_claims.py`) |
+| **The store on disk** — `.sidegraph/` layout (one JSON file per record, and from 0.17 optionally packed `shards/`), the `format` marker, `schema_version` | The current version is **0.6.0** (a format-2 store's index is stamped `0.7.0+format2`). `0.2.0`/`0.3.0` stores migrate automatically on first open (original kept as `*.migrated-backup`, never deleted). `0.4.0`/`0.5.0` reload in place. A future bump does one of those two or, as format 2 did, an explicit migration command (`sidegraph-migrate`) while the old format stays served — it never orphans a store. A store can require a minimum Sidegraph version (`sidegraph-require`): its marker becomes `sidegraph-store 1.0.0` plus `requires-sidegraph >= X.Y.Z`, and older versions refuse it. A packed store's marker is `sidegraph-store 2.0.0` plus a `requires-sidegraph` line and a `shards N` line; 0.14–0.16 refuse it, and the [0.17 migration guide](../guides/migrating-to-0.17.md) covers the switch. | `sidegraph-verify` lints every canonical file against the write-path invariants; a drift-check capsule may carry an optional `declared_sections` field inside `schema_version` 1, which readers that do not know it ignore; `--against <ref>` classifies every changed file against the store's own transition rules |
+| **CLI commands, flags, exit codes** | 22 entry points, 100 flags. A flag is not removed without a deprecation window; documented exit codes keep their meaning | every parser option must appear in its `cli.md` section (`tests/test_docs_claims.py`) |
 | **Environment variables** | The 16 in [`configuration.md`](configuration.md), and the store-path precedence between them. `SIDEGRAPH_DB` stays honoured as the documented deprecated form. `SIDEGRAPH_RATIFY_POLICY`'s name and its `manual` default are committed; its auto values and their gates are Provisional (below). | bidirectional test: the documented set must equal what `src/` actually reads |
 | **Hook process contract** | Read one JSON payload on stdin, write one JSON object on stdout, never block the host, never crash it — any internal failure exits normally, printing `{}`, or for SessionStart a store that cannot be opened prints a `systemMessage` naming the cause. Hosts call the hooks without arguments: `-h`/`--help` prints usage on stdout and exits `0`, and any other argument is a usage error on stderr that exits `2` (keep the `\|\| printf` guard on hand-written wiring) | the hook tests, and a live host run per release |
 
@@ -39,7 +39,7 @@ changes it, we follow the host; that is the point of keeping the host seam thin.
 |---|---|
 | **The MCP tool set and return shapes** (25 tools) | Fields and tools may still be added or deprecated; `ratify_decisions` is already a deprecated alias. Pin a version if a client depends on an exact shape. |
 | **Flow profiles** — the seven names and their ingest globs, ADR output settings and templates | `spec-kit`'s glob reads `specs/*/plan.md`, while that flow writes its rejected alternatives to `research.md`, which nothing reads. Fixing that changes a glob. |
-| **`doctor` finding codes** | Advisory lint; the set grows as checks are added. Guarded against the docs, not frozen. |
+| **`doctor` finding codes** and the `drift_groups` key of `sidegraph-doctor --json` | Advisory lint; the set grows as checks are added. Guarded against the docs, not frozen. The `drift_groups` shape (and the grouped default text) may still change. |
 | **Integrity check ids and severities** — `store-unreadable`, `graph-stale`, `orphaned-records` and the rest of the [troubleshooting](../guides/troubleshooting.md) table, as they appear in `sidegraph-stats --json`'s `health[].check` and in the `integrity_notice:` meta rows | Beside the doctor codes, for the same reason: the set grows as checks are added (the host-wiring checks `version-skew`, `path-skew` and `plugin-off-in-subdirectories` came before `refresh-helper-outdated` and `engine-version`), and a severity or a threshold (such as the age that makes orphaned records degraded) may move once it is measured. |
 | **Auto-ratification policy** — `SIDEGRAPH_RATIFY_POLICY`'s `auto-low-risk`/`auto-all` values and eligibility gates, the `, auto-ratified N` CLI summary segment (and the dry run's `, would auto-ratify M` and `[auto]` marker), and `sidegraph-doctor`'s `auto share`/`auto supersede rate` lines | Eligibility and reporting may tighten. `manual` remains the committed default. |
 

{sidegraph-0.19.0 → sidegraph-0.20.0}/docs/reference/store-format.md

@@ -108,7 +108,7 @@ an ordinary, human-readable git conflict in one small JSON file — not a corrup
 | `Fact` — full row, incl. `status`/`valid_to` (non-derivable knowledge; falsification is supersession, same as a `Decision`) | — |
 | `Domain` — everything except `communities` | `AnchorBinding.status` (`live`/`degraded`/`orphaned`) |
 | `Entity` — `entity_id`/`canonical_name`/`kind`/`descriptor`, for every entity EXCEPT a `community:*` abstract entity (index-only — see below) | `Domain.communities` |
-| `AnchorBinding` set per decision or fact — `entity_id`/`tier`/`relation`/`weight`, no `status`, EXCLUDING any binding whose entity is a `community:*` abstract entity | `toc_cache` (the `SessionStart` table-of-contents render) |
+| `AnchorBinding` set per decision or fact — `entity_id`/`tier`/`relation`/`weight`, no `status`, EXCLUDING any binding whose entity is a `community:*` abstract entity | `toc_cache` (the `SessionStart` table-of-contents render), `code_drift_cache` (the drifted record ids per capture commit, with the `first_seen_since`, `first_seen` and `first_seen_absent` stamps and the `first_seen_checked` marks behind the SessionStart recency clause) |
 | `Initiative` — full row | the per-session capture ledger (`capture_sessions`, dedup markers) |
 | `archive/*.jsonl` segments (once compaction has run) | `last_synced_graph_version` (the graph version plus the resolver revision, `<graph version>:r<N>`; raising the revision reruns the first sync after an upgrade), `pending_uncommitted_moves` (the entities a sync left as `moved_uncommitted`, with the git `HEAD` it saw, so the next sync after `HEAD` moves re-verifies them), `pending_tier1_reconcile` (the `(record, vacated community)` pairs whose Tier-1 reconcile failed, as JSON; every sync retries them first; a pair is cleared once its reconcile completes, and kept, silently, while a live or degraded Tier-2 anchor of the record has no recorded community), `schema_version`, the canonical-digest freshness stamp, `skipped_canonical_files` (the files the last reload left out; see [Digest integrity](#digest-integrity)) |
 | `domain-snapshot.json` (once `sidegraph-domains snapshot` has run) | `domain_members` (each accepted domain's effective membership: node id, file, community), with `domain_membership_stamp`, `domain_membership_failed`, `domain_membership_populated` and `domain_snapshot_signature` in `meta` |
@@ -1010,7 +1010,26 @@ revision, agent provenance, redacted rationale, exact `required_files`, inspecte
 `checked_files` (path, Git blob id and regular-file mode), and a SHA-256 `subject_digest`.
 No source text, engine mapping or binding status is stored. The versioned digest enumerates
 immutable Decision/Provenance fields and durable leaf descriptors (`name`, `file_path`);
-ratification/lifecycle fields and volatile mappings are excluded.
+ratification/lifecycle fields and volatile mappings are excluded. Locators and section
+digests are hashes.
+
+A capsule may also carry `declared_sections` (inside `schema_version` 1; plain capsules
+write `"declared_sections": []`). Each entry names one checked markdown file and the sections
+the checker read: `{path, scheme, refs_hash, sections: [{heading_hash, role, text_hash}]}`.
+Scheme `md1` is the block structure markdown-it-py reports in CommonMark mode (`>=4,<5`,
+inline pass off): `heading_hash` is a chained SHA-256 of the heading chain, `text_hash` the
+SHA-256 of the section's lines (CRLF and CR read as LF, nothing else normalised) and
+`refs_hash` the SHA-256 of the file's link reference definitions. Roles are `declared` and
+`watch`. No heading text is stored. A file with an entry is unchanged when its blob and mode
+match, or when its mode matches and every stored heading still resolves to exactly one
+heading with an equal `text_hash` and the `refs_hash` is equal. Everything else re-arms, with
+`checked files changed` for a mode or absence change, an unknown scheme or an unknown role;
+`section scope unavailable; whole file compared` when the file cannot be bounded (over 2 MiB
+or 20,000 lines, over 5,000 headings or 200,000 parser tokens, not UTF-8, a heading inside a
+list item or quote, nesting too deep, a read failure or an exhausted scan budget);
+`declared section not found`; `declared section changed`;
+`referenced link definition changed`; and `also-watched section changed`. A release that does not know the field ignores it, compares whole blobs and warns
+more, never less; an unknown future scheme or role is accepted and compared by whole blob.
 
 Select the highest generated check id for each decision before validation. This is a
 simple deterministic cross-branch ordering rule, not causal ordering or truth authority.

{sidegraph-0.19.0 → sidegraph-0.20.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "exports": "./index.js"
 }

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sidegraph",
   "displayName": "Sidegraph",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "author": { "name": "SantyagoSeaman", "url": "https://github.com/SantyagoSeaman" },
   "homepage": "https://github.com/SantyagoSeaman/sidegraph",

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "license": "Apache-2.0",
   "skills": "./skills/",

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/.muse-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "sidegraph",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Durable decisions, facts and lessons over your code graph.",
   "compat": {
     "source": "native",

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/skills/record-decision/SKILL.md

@@ -81,6 +81,8 @@ anchors resurface as noise in someone else's task context later.
   {"name": "ADR-001.md", "file_path": "adr/ADR-001.md"}]`. In the first store maintenance
   pass (2026-08-09), this one rule would have kept 7 of 10 fully-invisible records
   reachable.
+- For a long document, section scope is declared when the record is checked
+  (`record_drift_check` with `sections`), not when it is anchored.
 - **Two name shapes need care.** A bare module-level constant
   (`MEMORY_GUARD_LINE`) never resolves — the engine indexes functions/classes/files, not
   constants; anchor the containing file or function and name the constant in prose. A

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/skills/record-fact/SKILL.md

@@ -46,7 +46,8 @@ north star this razor guards.
   existing `Decision` (any status) or the write is rejected before anything is committed —
   never guessed, never left dangling.
 - **Always pair the precise anchor with its containing file** — code symbol or doc heading
-  alike: a rename/move orphans one anchor, the file anchor keeps the fact retrievable.
+  alike: a rename/move orphans one anchor, the file anchor keeps the fact retrievable. For a
+  long document, section scope is declared when the record is checked, not when it is anchored.
   Never anchor to a bare module-level constant (the engine indexes functions/classes/
   files, not constants — anchor the file and name the constant in the statement), and
   keep `name` bare (`store.py`, `_touch_digest`) — `file_path`, not the name, carries

{sidegraph-0.19.0 → sidegraph-0.20.0}/plugin/sidegraph/skills/triage-drift/SKILL.md

@@ -25,16 +25,46 @@ the question is whether what the record says survived what the code became.
 The CLI runs through uvx at the session's version, never the copy on `PATH` ([why](../../../../docs/reference/cli.md#running-the-clis-beside-the-plugin)).
 
 ```bash
-uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-doctor --json    # findings[] entries with "code": "code-drift"
+uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-doctor --json    # drift_groups.groups[] and findings[] with "code": "code-drift"
 ```
 
+Read `drift_groups.groups` first: one group per drifted file, each listing the records whose
+anchored files changed. Build one record list keyed by `record_id` across all groups. A record
+anchored in several files appears in each of their groups with the same `files`; judge it
+**once**, after every one of its `files` has been read. When the `drift_groups` key is absent
+(an older doctor, `--flat`, or no per-record drift) fall back to the `findings[]` entries
+with `"code": "code-drift"` and triage per record as before.
+
+Per record entry:
+
+- `diff.command` is `git diff <old blob> <new blob>`: read it once per file, not once per
+  record. A null `command` means read the file at HEAD and nothing more. `diff.unavailable`
+  says why no diff exists (for example the baseline object is not in this clone).
+- `diff.change` says what kind of change it is. `mode` means the executable bit moved and the
+  content is identical. `type` means the entry kind changed (file, symlink, submodule or
+  directory) and the content may well differ: read the file at HEAD, do not assume nothing
+  changed. `submodule` means a submodule pointer moved (`<old8>→<new8>` in the text): read the
+  submodule's own log, there is no `git diff` here. `content` is a real blob diff; if
+  `old_mode` and `new_mode` differ it also changed the mode.
+- `basis: "scope"` reads "scope changed; the file may also have changed". If a `command` is
+  present, read that diff; otherwise judge the record against the current anchored code.
+- `hint: "region-unchanged"` (text: `anchored region unchanged; sibling sections of the file
+  may still matter`) shortens the reading, never the judging: still read the current
+  implementation and any sibling the claim leans on.
+
 For a per-decision `code-drift` finding, use `record_id` and `record_type` ("decision")
 to identify the subject. `path` is its physical source: several records may share one shard.
 Never infer identity from the shard, capture commit or human-readable `detail`. Global notes
-(commit stamping unavailable, Git unavailable, check skipped) have null record fields; they
-are not records to triage. `detail` names changed files or why a prior check no longer applies.
+(commit stamping unavailable, Git unavailable, check skipped) have null record fields and
+sit in `drift_groups.notes`; they are not records to triage. `detail` names changed files or
+why a prior check no longer applies.
 Original `provenance.commit` stays history. Doctor is a pure read.
 
+Each `code-drift` entry in `findings[]` has `first_seen`: the time Sidegraph first saw the
+record drifted, or `null` when its age is unknown. Group records carry no `first_seen`: look
+each one up in `findings[]` by `record_id`. Triage the records whose `first_seen` is within
+the last 7 days first, newest first, then the `null` ones in doctor order.
+
 The SessionStart count and `[drifted]` tags in detailed formatted `get_task_context`,
 `query_decisions` and `drill_down` output use the lazily refreshed drift cache. Budgets can
 omit records, and compact related-record lines do not all show the marker. Raw
@@ -43,7 +73,9 @@ for the explicit current list.
 
 Triage in batches — a 35-record queue does not need 35 interrupts. Group verdicts and
 **put every question to the human into one message** (same discipline as
-`sidegraph:heal-anchors`).
+`sidegraph:heal-anchors`). Make exactly one `record_drift_check` or one supersession per
+record, each with its own rationale and `files` scope: two records never share a rationale or
+a call, even when one file change re-armed both.
 
 ## Per record: read both sides, then route
 
@@ -79,9 +111,30 @@ Triage in batches — a 35-record queue does not need 35 interrupts. Group verdi
 
      This immutable agent assertion preserves the decision and its capture provenance.
      It does not certify semantic truth, ratify a proposal, or permanently mute warnings.
-     Changed checked files or required scope re-arm review; unchanged file bytes after
-     unrelated commits remain covered. A known wrong claim belongs in route (b).
+     Changed checked files or required scope re-arm review (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); unchanged file bytes after unrelated commits remain covered. A known wrong claim belongs in route (b).
      Never create a content-free successor just to refresh a stamp.
+     **Scoping a check on a document.** Pass `sections` to `record_drift_check` when:
+
+     - the file is markdown, the claim rests on identifiable sections, and you read those
+       sections in this session at the recorded HEAD. When unsure, make a plain whole-file check.
+     - Declare the narrowest sections that carry the claim (`[["55.2 Rules"]]`, not the
+       chapter). The result echoes each section's `first_line` and `lines` (and the file's
+       `total_lines`): a section spanning most of the file gains nothing, and a `first_line`
+       that is not where the heading sits in your viewer means the parser disagrees with your
+       renderer, so make a whole-file check.
+     - Add `also_watch` when the claim depends on content elsewhere in the same file, such as
+       a rule restated in another chapter, a table that must stay consistent or a "the only X"
+       statement. Read the watched section too.
+     - Never declare a section you did not read: the declaration is an attributed assertion,
+       and a wrong narrow scope hides a real change.
+     - Do not declare sections that transclude other files (include directives, snippets).
+     - Refusals are normal. `section_file_unsupported` means a heading sits inside a list
+       item or quote, or a footnote reference is in a declared span; a file over 20,000 lines
+       is `section_file_too_large`. Make a plain whole-file check.
+     - Not for code files. Declared sections are for markdown only.
+     - Report the declared sections per file in your summary line.
    - **(b) Content now wrong or too broad.** The code change genuinely invalidated or
      narrowed the record. Propose the successor — never write it directly on your own
      initiative:

{sidegraph-0.19.0 → sidegraph-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sidegraph"
-version = "0.19.0"
+version = "0.20.0"
 description = "Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -43,6 +43,9 @@ dependencies = [
     # GHSA-84m7-p3x7-pcfv / CVE-2026-59951: MCP 1.30.0 fixes stateful StreamableHTTP.
     "anyio>=4",
     "mcp>=1.30,<2",
+    # Imported directly by drift_groups.py (heading spans for the drift hint)
+    # and lazily by md_sections (declared-section drift scope).
+    "markdown-it-py>=4,<5",
 ]
 
 [project.urls]

{sidegraph-0.19.0 → sidegraph-0.20.0}/src/sidegraph/__init__.py

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
     )
     from .store import Store
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 # name -> the submodule that defines it
 _LAZY = {