sidegraph 0.19.0__tar.gz → 0.21.0__tar.gz

{sidegraph-0.19.0 → sidegraph-0.21.0}/.github/workflows/ci.yml

@@ -7,20 +7,33 @@
 #
 # Actions are pinned to commit SHAs (the tag comment records the version): a mutable tag
 # is a supply-chain hole, and this workflow ships to the public repo by snapshot.
+# Draft PRs run lint, store-lint and anchor-health. Ready PRs, main pushes and
+# workflow_call also run test, sdk-compatibility and windows-core. full-ci is the
+# single required check. Ready pushes validate this revision against the full matrix.
+# Draft runs use another name: a skipped job counts as success.
+# A superseded PR run cannot provide a result for a newer revision.
+# Rollback: disable the ruleset first, then revert this workflow through a PR.
 name: ci
 
 on:
   push:
     branches: [main]
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
   workflow_call:   # reused as the pre-publish gate by publish.yml (tag builds)
 
 permissions:
   contents: read
 
+# PR runs only: main, tag and workflow_call runs each get a unique group.
+# This does not apply to session-link-gate.yml. Re-run only the head run.
+concurrency:
+  group: ci-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || format('run-{0}', github.run_id) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     timeout-minutes: 15
     steps:
       # zizmor artipacked: this job never pushes, so the checkout's git credentials should not
@@ -42,7 +55,7 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
         with:
           path: ~/.cache/pre-commit
-          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+          key: pre-commit-ubuntu-slim-${{ hashFiles('.pre-commit-config.yaml') }}
 
       - name: Install dependencies
         run: uv sync --locked
@@ -77,6 +90,7 @@ jobs:
           PY
 
   test:
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
     timeout-minutes: 30
     strategy:
@@ -100,9 +114,10 @@ jobs:
         run: uv sync --locked
 
       - name: Run tests
-        run: uv run pytest -q
+        run: uv run pytest -q --durations=30 --durations-min=1
 
   sdk-compatibility:
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
     timeout-minutes: 15
     strategy:
@@ -149,6 +164,7 @@ jobs:
             -k "not t9 and not t14_every and not t14_the_manual and not console_script_is_the_host_entry"
 
   windows-core:
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
     runs-on: windows-2022
     timeout-minutes: 30
     strategy:
@@ -188,7 +204,7 @@ jobs:
           if (Test-Path "tests/private/test_older_reader_native.py") {
             $privateTests += "tests/private/test_older_reader_native.py"
           }
-          uv run pytest -q --junitxml="$env:RUNNER_TEMP/windows-core.xml" `
+          uv run pytest -q --durations=30 --durations-min=1 --junitxml="$env:RUNNER_TEMP/windows-core.xml" `
             tests/test_store_mutation_guard.py `
             tests/test_store_mutation_immediate.py tests/test_store_cross_process_mutations.py `
             tests/test_hook_contention.py tests/test_retrieval_seeds.py `
@@ -207,6 +223,7 @@ jobs:
             tests/test_git_output_utf8.py `
             tests/test_githooks_atomic_lock.py::test_windows_pid_probe_is_never_a_signal_from_python `
             tests/test_health_check_skill.py `
+            tests/test_checkout_window.py tests/test_store_marker_checkout_race.py `
             $privateTests
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
@@ -289,7 +306,7 @@ jobs:
   # this workflow ships to the public repo.
   store-lint:
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     timeout-minutes: 10
     steps:
       # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
@@ -352,3 +369,47 @@ jobs:
           uvx --from graphifyy==0.9.90 graphify update .
           uv sync --locked
           uv run sidegraph-sync --json --check
+
+  full-ci:
+    name: "${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && 'full-ci' || 'full-ci (draft: full matrix not run)' }}"
+    if: ${{ always() }}
+    needs: [lint, test, sdk-compatibility, windows-core, store-lint, anchor-health]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Every required job passed on this revision
+        env:
+          FULL: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
+          EVENT: ${{ github.event_name }}
+          LINT: ${{ needs.lint.result }}
+          TEST: ${{ needs.test.result }}
+          SDK: ${{ needs.sdk-compatibility.result }}
+          WINDOWS: ${{ needs.windows-core.result }}
+          STORE_LINT: ${{ needs.store-lint.result }}
+          ANCHOR_HEALTH: ${{ needs.anchor-health.result }}
+        run: |
+          status=0
+          need() {  # need <job> <result> <allowed...>
+            job="$1"; result="$2"; shift 2
+            for ok in "$@"; do [ "$result" = "$ok" ] && return 0; done
+            echo "::error::$job: '${result:-none}' (needs: $*)"; status=1
+          }
+          if [ "$FULL" != true ]; then
+            echo "::notice::Draft pull request: the full matrix did not run. Mark it Ready; the required check is full-ci."
+            need lint "$LINT" success
+            need store-lint "$STORE_LINT" success
+            need anchor-health "$ANCHOR_HEALTH" success
+            exit "$status"
+          fi
+          need lint "$LINT" success
+          need test "$TEST" success
+          need sdk-compatibility "$SDK" success
+          need windows-core "$WINDOWS" success
+          if [ "$EVENT" = pull_request ]; then
+            need store-lint "$STORE_LINT" success
+            need anchor-health "$ANCHOR_HEALTH" success
+          else
+            need store-lint "$STORE_LINT" success skipped
+            need anchor-health "$ANCHOR_HEALTH" success skipped
+          fi
+          exit "$status"

{sidegraph-0.19.0 → sidegraph-0.21.0}/.github/workflows/session-link-gate.yml

@@ -26,7 +26,7 @@ permissions:
 
 jobs:
   pr-description-link-gate:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     timeout-minutes: 5
     steps:
       # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.

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

@@ -7,6 +7,77 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.21.0] — 2026-10-28
+
+### Changed
+
+- Draft pull requests run only the quick CI checks. The full test matrix runs when a pull
+  request is marked ready for review, on `main` and before release, behind one aggregate
+  `full-ci` gate.
+
+### Fixed
+
+- `sidegraph-bootstrap` recognises a plugin install. When the manual registration files are
+  not complete, an enabled Sidegraph plugin satisfies the host check: Claude Code prints
+  `INTEGRATION  Claude Code plugin sidegraph@sidegraph enabled (MCP + hooks)`, Codex prints
+  `INTEGRATION  Codex best-effort` with `plugin sidegraph@sidegraph enabled; its hooks run
+  once trusted in Codex (/hooks)`, and a run that is otherwise complete exits `0` instead of
+  `2`. The `--report` integration section gains `- via: plugin` or `- via: manual`, and
+  `--report` refuses the user-level Claude Code settings and Codex config the check now reads.
+
+- `sidegraph-viz` (with or without `--json`) and `sidegraph-export-okf` report a store that
+  cannot be opened, such as a damaged `index.db`, a format marker from another version or a
+  minimum-version requirement this release does not meet, as one
+  `store not readable (<path>): <error>` line on stderr and exit `2`, the documented
+  operational-error code. Before, they ended with a traceback and exit `1`. With `--json`,
+  nothing is printed on stdout in that case.
+
+- Opening a store while git checks out a commit that changes `.sidegraph/format` (a pull of
+  a raised requirement or a migration, a branch switch, a clone) no longer writes a default
+  marker in its place. Git removes the old file before writing the new one. An open in that
+  moment could publish `sidegraph-store 0.6.0`, and git could not create its own file,
+  leaving the default without its `requires-sidegraph` line. The open now waits up to 2 seconds
+  for git's marker and refuses without writing if git stays busy or `HEAD` records a missing
+  marker. The message names the recovery step.
+
+## [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.21.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.21.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.21.0}/CONTRIBUTING.md

@@ -59,7 +59,9 @@ issue when there is one, keep the patch focused, and update affected documentati
 Use an area-prefixed imperative commit subject, for example `store: preserve history`,
 and sign off each commit as described below.
 
-CI runs the full suite on Linux/Python 3.13 and 3.14 and a selected native Windows
+CI runs lint on every PR push. On a pull request that is ready for review (not a draft),
+on `main` and before publishing, it also runs the full suite on Linux/Python 3.13 and 3.14
+and a selected native Windows
 core/MCP suite on both versions; see [platform coverage](docs/getting-started/installation.md#platform-coverage).
 If your change touches paths, permissions,
 subprocesses, or shell commands, describe any additional platform checks you performed.

{sidegraph-0.19.0 → sidegraph-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.19.0
+Version: 0.21.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.21.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.21.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.21.0}/docs/getting-started/bootstrap.md

@@ -124,20 +124,28 @@ current-graph anchor proof. Optional domain suggestions do not block that proof.
 | Claude Code | verified | verified | verified | verified | complete v1 flow |
 | Codex | verified when configured | verified when configured | verified when configured | unsupported | best-effort only |
 
-The host check reads the manual registration files only: `.mcp.json` and the `hooks` of
+The host check reads the manual registration files first: `.mcp.json` and the `hooks` of
 `.claude/settings.json` for Claude Code, `.codex/config.toml` and `.codex/hooks.json` for Codex.
-It does not recognise a plugin install, whose MCP server and hooks live in the plugin
-manifest. On a project that uses the plugin, `INTEGRATION` is therefore reported `incomplete`
-and the command exits `2` even though the plugin works. Ignore that result if the plugin is
-installed, or register the entry points by hand as described in the
-[Claude Code](../integrations/claude-code.md) or [Codex](../integrations/codex.md) setup guide.
+When they are not complete, an enabled Sidegraph plugin satisfies the check.
+
+For Claude Code, the `enabledPlugins` merge must enable `sidegraph@<marketplace>` for a session
+launched at the bootstrap root: user settings, that directory's `.claude/settings.json` and
+`.claude/settings.local.json`, then the repository root's `.claude/settings.local.json` when
+launching below it. `$CLAUDE_CONFIG_DIR` replaces `~/.claude` for user settings when set.
+The terminal prints `INTEGRATION  Claude Code plugin sidegraph@sidegraph enabled (MCP + hooks)`.
+For Codex, `[plugins."sidegraph@<marketplace>"]` with `enabled = true` in
+`$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) satisfies its supported checks.
+Under `INTEGRATION  Codex best-effort`, it prints
+`plugin sidegraph@sidegraph enabled; its hooks run once trusted in Codex (/hooks)`.
+Bootstrap cannot see Codex hook trust.
 
 Claude Code has the complete v1 flow. Codex has MCP, SessionStart, and Stop support, but no
 Read/Grep PreToolUse equivalent. When store, anchors, all three supported Codex checks, and
 production proof are complete, the command reports `best-effort`. In that state, best-effort completion exits 0
 with an explicit warning. The terminal never prints `fully supported` for Codex (the optional
 `--report` markdown does write `- fully supported: false` for Codex). A missing or invalid
-supported check is actionable incomplete and exits `2`.
+supported check is actionable incomplete and exits `2`, unless an enabled Sidegraph plugin
+provides MCP and hooks for this host.
 
 Exit `0` also covers full Claude Code activation and safe diagnostics with no required write.
 A run whose approved candidates were all skipped as unanchored (see below) is such a

{sidegraph-0.19.0 → sidegraph-0.21.0}/docs/getting-started/installation.md

@@ -16,7 +16,8 @@ file- and domain-linked records without a graph; the complete workflow below ins
 
 ### Platform coverage
 
-The automated matrix runs the full suite on Linux with Python 3.13 and 3.14. Native
+On every pull request that is ready for review (not a draft), on `main` and before every
+publish, the automated matrix runs the full suite on Linux with Python 3.13 and 3.14. Native
 Windows x64 (`windows-2022`) runs a selected portable core/MCP suite on both versions:
 Store mutation/rollback and cross-process conflicts, UTF-8 and descriptor cleanup,
 MCP result contracts, invocation admission, and wheel-probe guards. It also builds and
@@ -45,7 +46,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.21.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.21.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.21.0}/docs/guides/troubleshooting.md

@@ -113,14 +113,21 @@ that depends on the exception:
 - A store that requires a newer Sidegraph (`This store requires Sidegraph >= X.Y.Z; this is
   A.B.C.`): upgrade to at least that version and start a new session. A teammate raised it
   with `sidegraph-require`.
+- A missing format marker (`the store format marker … is missing`, or
+  `store format marker is missing and git did not answer in time`): if a git command is
+  running (a pull or checkout), start a new session when it finishes. Otherwise restore a
+  committed marker with `git -C .sidegraph checkout HEAD -- format`. If the message names an
+  index lock and no git command is running, remove that named lock and open again. For a
+  repeated timeout with no git command running, check `git -C .sidegraph status`.
 - A store written by a different Sidegraph version, for example a packed (format 2) store opened
   by 0.14 to 0.16, whose message ends `migration tooling is deferred — use a fresh store`:
   upgrade Sidegraph, or use the version that wrote it. The message predates `sidegraph-migrate`
   and does not mean you need a fresh store.
 - Anything else: `sidegraph-verify` gives the details.
 
-A lock that another process holds is not a broken store. The hook stays silent for it, and the
-next session start opens the store.
+An ordinary store write lock held by another process is transient. The hook stays silent for
+it, and the next session start opens the store. The marker-specific git refusal above instead
+names its recovery step.
 
 ### pending-ratification
 
@@ -134,7 +141,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.21.0}/docs/reference/cli.md

@@ -89,14 +89,16 @@ exclusions, review/state table, host matrix, and recovery semantics.
 | `--codex-config` | `.codex/config.toml` | alternate Codex MCP config path |
 | `--candidate` | all candidates | review only the displayed candidate key |
 | `--task` | deterministic proof selection | additional repository path for production retrieval proof |
-| `--report` | none | after a confirmed apply (including the all-unanchored diagnostic), write an aggregate, source-content-free Markdown report; never uploaded. The pre-apply diagnostics (no candidates, every candidate skipped in review, a changed plan with no writes) write none. The destination must not be, or be hard-linked to, the graph, any host's config file (both hosts', whichever `--host` is set) or a scanned source, and must not lie inside the store; the report replaces the file rather than truncating it in place |
+| `--report` | none | after a confirmed apply (including the all-unanchored diagnostic), write an aggregate, source-content-free Markdown report; never uploaded. The pre-apply diagnostics (no candidates, every candidate skipped in review, a changed plan with no writes) write none. The destination must not be, or be hard-linked to, the graph, any host config file the check reads (both hosts', whichever `--host` is set, including the user-level Claude Code settings and Codex config) or a scanned source, and must not lie inside the store; the report replaces the file rather than truncating it in place |
 | `--resume` | off | marker only, for the resume command a failed run prints — it changes no behavior. The scan/review/reconcile flow is idempotent, so reissuing the same command without it behaves identically |
 
 Output keeps `STORE`, `ANCHORS`, `INTEGRATION`, and `PROOF` independent. Claude Code can
 complete the full v1 flow. Codex verifies MCP, SessionStart, and Stop but reports Read/Grep
 PreToolUse as unsupported; a green supported subset plus store, anchor, and proof completion
 is `best-effort` and exits `0`, but is never labeled fully supported. A missing supported
-check exits `2`.
+check exits `2`. An enabled Sidegraph plugin satisfies the host check when the manual
+registration files are not complete; see
+[Completion, recovery, and hosts](../getting-started/bootstrap.md#completion-recovery-and-hosts).
 
 **Exit codes:** `0` for complete activation, Codex best-effort completion, or a safe
 no-write diagnostic; `1` for usage or operational failure, unreachable once anything has been
@@ -1515,7 +1517,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 +1526,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 +1557,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 +1623,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,
@@ -1700,9 +1704,10 @@ Rendering does not mutate canonical records or `graph.json`. It opens the ordina
 so startup may migrate supported legacy data or rebuild `index.db`. Binding status
 (live/degraded/orphaned) reflects the last `sidegraph-sync`; run sync first for a fresh view.
 Exit code 0 on success (a store with problems still exits 0 — the problems are the output), 2
-on an operational error (uninitialized store or unwritable output path). A store that cannot be
-opened at all (for example a corrupt `index.db`) is not caught: the command exits 1 with a
-traceback.
+on an operational error: an uninitialized store, a store that cannot be opened (for example
+a corrupt `index.db` or a format marker this version does not read; one
+`store not readable (<path>): <error>` line on stderr, and with `--json` nothing on stdout),
+or an unwritable output path.
 
 ## `sidegraph-export-adr`
 
@@ -1785,9 +1790,9 @@ write failure there can leave a partial export. A killed export can leave `.<out
 or `.<out>.okf-old-*` beside `--out` (the repo root for the default `--out`). The `-old-`
 one holds the previous export: if `--out` is missing, rename it back; if `--out` already holds
 the new bundle, delete it. Exit `0` on success, `2` on an operational error
-(uninitialized store — never auto-created — or a refused/unwritable out dir or its
-parent). A store that cannot be opened at all (for example a corrupt `index.db`) is not
-caught: the command exits 1 with a traceback.
+(uninitialized store — never auto-created — a store that cannot be opened, printed as
+`store not readable (<path>): <error>` on stderr, or a refused/unwritable out dir or its
+parent).
 
 ## `sidegraph-stats`
 

{sidegraph-0.19.0 → sidegraph-0.21.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.21.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