sidegraph 0.18.0__tar.gz → 0.19.0__tar.gz

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

@@ -7,6 +7,39 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-10-27
+
+### Changed
+
+- `sidegraph-doctor --check` no longer exits `2` on `maintenance-due` alone. The finding is
+  still printed, listed in `--json` and shown as a session notice; `store-not-migrated` and
+  every other finding still fail `--check`.
+- `sidegraph-export-adr` names store records (the ADR's own record, supporting facts,
+  domains, successors without a document) by id instead of linking into `.sidegraph/`.
+  Migrating or maintaining the store no longer rewrites every exported ADR. The first export
+  with this version rewrites each generated document once. The `$record_link` template
+  placeholder is now a code span with the id, not a link target.
+
+### Fixed
+
+- One record file that cannot be read or decoded no longer fans out into findings at every
+  record that refers to it. `sidegraph-verify` reports the one `parse-error`; a fact that
+  supports it, a successor that supersedes it and a binding to such an entity raise nothing
+  more, and `sidegraph-doctor` adds no `dangling-record` for the supporting fact.
+- `sidegraph-verify --against` no longer reports `illegal-deletion` or `illegal-field-change`
+  for a committed file the store never loads: a stray copy under an unsafe name, or a file
+  whose baseline id is unsafe. Deleting such a file is the fix; the snapshot still reports it
+  as `unsafe-record-id` while it exists.
+- Ratifying, dropping or closing a decision written before the `scope` field existed no longer
+  reads as an illegal `scope` change. `sidegraph-verify`, `sidegraph-compact` and maintenance
+  accept the default `repo` that the writer or the archive line adds, so such a record can be
+  compacted and packed again. A real `scope` edit is still refused. Entities without `kind`
+  get the same treatment for its default, `concrete`.
+- `sidegraph-export-okf` no longer exports a domain's superseded row when its successor's id
+  happens to sort lower, which can happen for two ids minted in the same millisecond, or
+  after a domain is renamed away and back. A row with a later revision under the same slug
+  never becomes that slug's page.
+
 ## [0.18.0] — 2026-10-26
 
 ### Changed

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -326,7 +326,7 @@ legacy `archive/` segment that maintenance would delete, a shard line in the wro
 repeated with an equal body, or a stray shard file. Nothing is broken, and `sidegraph-verify`
 does not report these states. A segment that stays because one of its lines is not safe to
 delete does not count. Run `sidegraph-compact` on the default branch. Doctor lists one finding
-at the store path, and `--check` exits `2` on it. A legacy segment that maintenance would delete counts, whether its records are already in shard
+at the store path; `--check` reports it but does not exit `2` on it. A legacy segment that maintenance would delete counts, whether its records are already in shard
 lines or maintenance would pack them. The check does not consult git, so a record file that
 still has to settle (or is untracked) is not predicted. It reads the shard files once; a store
 with more than 200 per-record files is decided from the directory listing.
@@ -411,7 +411,7 @@ not reported: nothing was switched off.
   `~/.claude/settings.json`.
 - **Where it runs.** The session surface and doctor. Not run outside a git repository, with no
   `git`, or when `git ls-files` takes longer than five seconds. Doctor lists the finding with the
-  code `plugin-off-in-subdirectories`, and `--check` exits `2` on it like any finding.
+  code `plugin-off-in-subdirectories`, and `--check` exits `2` on it.
 - **Why only a root launch tells you.** A session started in a directory where the plugin is off
   runs no SessionStart hook, so nothing speaks there. The line (and the notice, with case (b))
   comes from a session at the root, and the finding from doctor and the setup skill.

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

@@ -1363,11 +1363,11 @@ plain-text line):
 | `snapshot-without-requirement` | snapshot | a `domain-snapshot.json` exists but the `format` marker does not require Sidegraph 0.14.0 or later |
 | `bad-validity-window` | snapshot | `valid_to < valid_from` on a decision or fact |
 | `superseded-without-successor` | snapshot | a `status=superseded` record has no other record's `supersedes` pointing back at it (a successor held by a file skipped for its unsafe name still counts) |
-| `dangling-supersedes` | snapshot | a `supersedes` id doesn't resolve to any record, hot or archived (a file skipped for its unsafe name still counts as the record it holds, so renaming it back is the only heal) |
-| `dangling-binding-entity` | snapshot | a binding's `entity_id` doesn't resolve to any `entities/<id>.json` (an entity held by a file skipped for its unsafe name still counts) |
-| `dangling-fact-support` | snapshot | a fact's `supports` id doesn't resolve to any decision (a file skipped for its unsafe name still counts, as for `dangling-supersedes`) |
-| `dangling-drift-check` | snapshot | an auxiliary verification references no hot or archived decision; terminal targets remain valid history |
-| `dangling-parent` | snapshot | a domain's `parent_id` doesn't resolve to any domain, hot or archived (a superseded, dropped or archived parent still counts, as the write path only checks that it exists; a file skipped for its unsafe name counts too, as for `dangling-supersedes`) |
+| `dangling-supersedes` | snapshot | a `supersedes` id doesn't resolve to any record, hot or archived (a file skipped for its unsafe name still counts as the record it holds, so renaming it back is the only heal; a regular file with a safe name that does not decode counts as the record its name names, so it gives one `parse-error` and no finding here; a directory or other entry named like a record file does not) |
+| `dangling-binding-entity` | snapshot | a binding's `entity_id` doesn't resolve to any `entities/<id>.json` (an entity held by a file skipped for its unsafe name still counts, and so does an entity file that does not decode) |
+| `dangling-fact-support` | snapshot | a fact's `supports` id doesn't resolve to any decision (a file skipped for its unsafe name, or one that does not decode, still counts, as for `dangling-supersedes`) |
+| `dangling-drift-check` | snapshot | an auxiliary verification references no hot or archived decision; terminal targets remain valid history (a decision file with a safe name that does not decode counts, as for `dangling-supersedes`) |
+| `dangling-parent` | snapshot | a domain's `parent_id` doesn't resolve to any domain, hot or archived (a superseded, dropped or archived parent still counts, as the write path only checks that it exists; a file skipped for its unsafe name, or one that does not decode, counts too, as for `dangling-supersedes`) |
 | `parent-cycle` | snapshot | the `parent_id` chain of some domains loops back on itself (a domain that is its own parent included); reported once per cycle, at the domain with the smallest id on it, and not for a domain that merely hangs off the cycle |
 | `duplicate-ulid` | snapshot | the same internal id appears in more than one canonical location — two hot files, a hot file plus any archive copy, or two archive segments whose payloads for that id actually differ. **Exempt:** two or more archive segments carrying byte-*identical* payloads for the same id — a sanctioned cross-branch `sidegraph-compact` merge (independent compaction on two branches, later merged) — see [`reference/store-format.md#archive-segments-sidegraph-compact`](store-format.md#archive-segments-sidegraph-compact). **On a packed (format 2) store** a hot file beside an archive line is not a duplicate when the file holds the line's state or a legal successor of it, and a shard line beside an archive line is not when it does or when the archive line is a legal successor of the shard line; a per-record file beside a shard line is the normal state before maintenance and is judged by `shadow-divergence` |
 | `bad-archive-segment` | snapshot | an `archive/*.jsonl` entry is not a regular file (`unreadable: not a regular file`), or a line isn't valid UTF-8 or JSON, isn't a JSON object, or holds a decision or domain that fails its model, can't be serialised, or has a nonterminal status. Schema/decode failures match the lines the reload leaves out; the verifier additionally rejects nonterminal archive records (one violation per line, naming the segment and the line number) |
@@ -1385,7 +1385,7 @@ plain-text line):
 | `illegal-status-jump` | transition | `status` changed to something that isn't a real write-path transition for that record kind |
 | `valid-to-unset` | transition | `valid_to` reverted from a value back to `null` |
 | `valid-to-changed` | transition | `valid_to` changed from one value to a *different* value (only `null → value`, once, is legal) |
-| `illegal-deletion` | transition | a record file — or an already-published archive segment — was deleted with no sanctioned reason. The one exception: a decision/domain preserved by same-kind, same-ID archive copies in the new tree, every copy schema-valid, compactable and a legal raw-payload transition from the baseline (a legitimate `sidegraph-compact`). An ID match alone is insufficient |
+| `illegal-deletion` | transition | a record file — or an already-published archive segment — was deleted with no sanctioned reason. The one exception: a decision/domain preserved by same-kind, same-ID archive copies in the new tree, every copy schema-valid, compactable and a legal raw-payload transition from the baseline (a legitimate `sidegraph-compact`). An ID match alone is insufficient. A file the store never loaded (an unsafe file name, or an unsafe id in the baseline) is not a record: deleting or editing it adds no transition finding, and the snapshot's `unsafe-record-id` covers it while it exists |
 | `shard-body-without-source` | transition | on a packed (format 2) store, a shard line added or changed since `GIT_REF` whose body is not the body of any occurrence of the same record in `GIT_REF` (a per-record file, a shard line or an archive line). `sidegraph-compact` only ever writes bodies it read, so a hand-forged line, or an edit folded in the same pull request that made it, is reported: land the edit on the target branch first, then fold |
 | `format-downgrade` | transition | the `format` marker went from major 2 in `GIT_REF` to a lower major. The one legal shape is the full rollback: no `shards/*.shard` file is left and every record is back in its per-record file with all its keys |
 
@@ -1459,8 +1459,9 @@ file — whether its default is `null` (`Provenance.commit` today) or an empty l
 and fills the field back in with that default. That alone is never a change: an absent field
 counts as the same value as an explicit `null` or an empty list/object, inside nested objects
 and inside the items of a list, everywhere this table calls a field immutable. A field whose
-default is a *non-empty* value (`Decision.scope`, `"repo"`) is **not** covered by this — an
-absent key there still reads as changed — but no file in this store lacks `scope` today.
+default is a *non-empty* value (`Decision.scope`, `"repo"`; `Entity.kind`, `"concrete"`) has
+its own narrower rule: an absent key equals exactly that default value on the other side, in
+either direction, and nothing else. A move to or from any other value is still a change.
 
 **Known limit:** `verify_against` compares only the net change across the whole diffed range
 (see "diffs the CURRENT WORKING TREE" below), not each intermediate commit. So a ratifier
@@ -1521,7 +1522,7 @@ sidegraph-doctor [--db PATH] [--against GIT_REF] [--check] [--stale-days N] [--j
 |---|---|---|
 | `--db` | `$SIDEGRAPH_DIR` → existing `.sidegraph/` → `.sidegraph` | store directory; `$SIDEGRAPH_DB` honored for back-compat (deprecated) — same never-auto-create rule as `sidegraph-verify` (see above) |
 | `--against GIT_REF` | none | also run `sidegraph-verify`'s transition layer vs `GIT_REF` (identical semantics — same operational-error rules) |
-| `--check` | off | advisory findings also exit `2` (default: report only; a *skipped* check never fails, even with `--check`) |
+| `--check` | off | advisory findings also exit `2`, except `maintenance-due` (default: report only; a *skipped* check never fails, even with `--check`) |
 | `--stale-days N` | `30` | flag a proposed decision/domain whose id timestamp is strictly older than `N` days; must be `>= 0` |
 | `--json` | off | print `{"clean", "violations", "findings", "skipped"}` as one JSON object to stdout (nothing else) |
 | `--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) |
@@ -1538,14 +1539,16 @@ never constructs a `Store`.
   exit `1` operational error only when `--against` requests the git-backed transition layer;
   the snapshot layer works without git.
 - **Advisory section** — `doctor.curate`: curation findings that never gate the exit code
-  by default; `--check` escalates them to exit `2`, mirroring `sidegraph-sync --check`.
+  by default; `--check` escalates them to exit `2`, mirroring `sidegraph-sync --check`. The
+  one exception is `maintenance-due`, routine upkeep on a healthy packed store: it is still
+  printed and still in `--json`, but never changes the exit code.
 
 **Finding codes** (the `code` field in `--json`'s `findings`, or the first column of a
 plain-text line):
 
 | Code | Meaning |
 |---|---|
-| `dangling-record` | an open decision (`proposed`/`accepted`) has no committed anchor set; an open fact (`valid_to` unset) has no anchor AND no `supports` id resolving to a LIVE (`proposed`/`accepted`) decision — an anchor alone, or a supports id resolving to a live decision, is reachability for a fact |
+| `dangling-record` | an open decision (`proposed`/`accepted`) has no committed anchor set; an open fact (`valid_to` unset) has no anchor AND no `supports` id resolving to a LIVE (`proposed`/`accepted`) decision — an anchor alone, or a supports id resolving to a live decision, is reachability for a fact. A fact that supports a decision whose file does not decode is not reported: that file is `sidegraph-verify`'s one `parse-error` |
 | `degraded-binding` | a binding's last recorded status (from `index.db`) is `degraded` |
 | `orphaned-binding` | a binding's last recorded status (from `index.db`) is `orphaned` |
 | `stale-proposal` | a proposed decision/domain whose ULID timestamp is strictly older than `--stale-days` |
@@ -1561,11 +1564,11 @@ plain-text line):
 | `graph-stale` | the graph was built at a commit HEAD has moved past (graph.json's `built_at_commit`), and a file the graph should reflect changed since: one it holds was edited after the graph was last built (the later of `graph.json`'s and its sibling `manifest.json`'s modification times) or deleted, or a new file of a type it holds now exists (not under a dot-directory, which Graphify skips). Memory cannot see or anchor to code added after the build. The detail gives the build commit, how many commits behind HEAD (or "a commit outside HEAD's history" after a checkout of an older commit), how many files changed, and up to five example paths; the fix is to rebuild from the repository root by running `graphify update .` with the environment variable `GRAPHIFY_NO_AUTO_REFRESH=1` set, then `sidegraph-sync`. Silent when the build commit is HEAD, when only file types the graph does not hold changed (a `.yml` against a `.py`-only graph), and when a graph built from a dirty tree was committed afterwards, or a `graphify update .` found nothing to change and rewrote only `manifest.json` (the file is no newer than the build); also silent when the comparison cannot be made (no `built_at_commit`, one that is not a full commit id, a graph outside a git repository, a build commit the repository lacks, git unavailable or slower than 3 seconds). **`--check` exits `2` on it**, so a CI job that runs doctor should rebuild the graph first; one that does is unaffected. Needs `--graph` to resolve |
 | `orphaned-record` | an open (`proposed`/`accepted`) decision or fact whose every Tier-2 (leaf) anchor is `orphaned`, so retrieval reaches it only through its file or domain; one finding per record, at its canonical file, naming how many leaf anchors it has. Statuses come from `index.db` and read "as of last sync", so the check is skipped while the statuses are not computed for the current graph (see *Skipped checks* below; run `sidegraph-sync`). It is the record-level view of `orphaned-binding` (any record it flags has orphaned bindings, which that code already reports), so it adds no new reason for `--check` to exit `2`. The fix is to rebuild a stale graph, then `sidegraph-sync`; otherwise re-anchor the record with `add_anchors` or the `heal-anchors` skill, or supersede it if the code is gone. Needs a usable `index.db` |
 | `store-uncommitted` | store files nobody committed for at least 24 hours: records, bindings, entities, an archive segment or the root files (`format`, `.gitignore`, `stamping_live_since`) that `git status` shows as new, modified or deleted. One finding, at the store path, naming how many files there are, how old the oldest is and what kinds they are (a new `archive/` segment beside deleted records reads as "a compaction"). A new record or entity file is aged by its ULID name, which a `git stash` cannot rewrite; a modified file, or anything under `bindings/`, by its modification time; a deleted file by its subdirectory's, a lower bound. Entries fully staged in the index are not counted, so a `--check` run in a pre-commit hook does not block the commit that fixes the problem. **`--check` exits `2` on it.** The fix is to commit the store in a pull request. Silent, and not run, outside a git repository, with no `git`, or when git is slower than 2 seconds |
-| `plugin-off-in-subdirectories` | Claude Code sessions started below the repository root run without the Sidegraph plugin. Claude Code reads the project settings (`.claude/settings.json`) of the launch directory only, and the repository root's `.claude/settings.local.json` for every launch inside the repository; `enabledPlugins` merges key by key (user settings, then project, then local). Two problems, reported as up to two findings: (a) the plugin is enabled only in the root's `.claude/settings.json`, so every directory below the root without its own enabling settings runs without it (reported at that file); (b) nested directories with a `.claude/settings.json` or `.claude/settings.local.json` of their own that sets `enabledPlugins` and whose merge leaves the plugin off (reported at the first such directory, naming how many there are; a nested settings file without `enabledPlugins` cannot change the merge, so it is not counted). The walk covers every directory that holds a tracked file (one `git ls-files` over the index, a few tens of milliseconds on a large repository) and looks for the two settings files in each directly, so a repository that ignores `.claude/` is covered. User settings are read from `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set and non-empty, else from `~/.claude/settings.json`. Silent when the plugin is not enabled for a launch at the root at all, and not run outside a git repository, with no `git`, or when `git ls-files` takes longer than 5 seconds. **`--check` exits `2` on it**, like any finding; enabling the plugin at user scope or in the root's `.claude/settings.local.json` clears it |
-| `refresh-helper-outdated` | a git hook runs an older graph refresh helper that uses directory-based locking (unsafe with uutils `mkdir`), or whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (Graphify 0.9.87 and later can rewrite installed agent skills after an upgrade). Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**, like any finding. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
-| `engine-version` | the graph was built by a Graphify release this Sidegraph was not tested with (its `graph.graphify_version` stamp is neither absent nor in the tested set), so anchors and domains may read differently. Advisory; **`--check` exits `2` on it**, like any finding. Pin Graphify to a tested release listed under [Engine version pinning](../integrations/graphify.md#engine-version-pinning), then rebuild the graph. It also fires for a mention-edge graph (Graphify 0.9.62 or later) over a store without a minimum Sidegraph version; follow the [0.14 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.14.md). A malformed marker leaves this second case silent. Silent without a readable graph |
-| `store-not-migrated` | the store uses the pre-0.17 layout (a format marker below major 2) and holds at least one record of any kind (initiatives included). One finding, at the store path, naming `sidegraph-migrate` (run on the default branch, after the team checklist in the [0.17 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.17.md)) and the `sidegraph:compact` skill. Degraded; **`--check` exits `2` on it**, like any finding. Silent on an empty store and on a store that is already format 2 |
-| `maintenance-due` | a format-2 store that `sidegraph-compact` would tidy: more than 200 per-record files, or a legacy `archive/` segment it would delete, or a misplaced or duplicated shard line, or a stray shard file. `sidegraph-verify` does not report these; maintenance heals them. A segment kept because one of its lines is not safe to delete does not count. Advisory; **`--check` exits `2` on it**, like any finding. Run `sidegraph-compact` on the default branch. Silent on a store that is not format 2 |
+| `plugin-off-in-subdirectories` | Claude Code sessions started below the repository root run without the Sidegraph plugin. Claude Code reads the project settings (`.claude/settings.json`) of the launch directory only, and the repository root's `.claude/settings.local.json` for every launch inside the repository; `enabledPlugins` merges key by key (user settings, then project, then local). Two problems, reported as up to two findings: (a) the plugin is enabled only in the root's `.claude/settings.json`, so every directory below the root without its own enabling settings runs without it (reported at that file); (b) nested directories with a `.claude/settings.json` or `.claude/settings.local.json` of their own that sets `enabledPlugins` and whose merge leaves the plugin off (reported at the first such directory, naming how many there are; a nested settings file without `enabledPlugins` cannot change the merge, so it is not counted). The walk covers every directory that holds a tracked file (one `git ls-files` over the index, a few tens of milliseconds on a large repository) and looks for the two settings files in each directly, so a repository that ignores `.claude/` is covered. User settings are read from `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set and non-empty, else from `~/.claude/settings.json`. Silent when the plugin is not enabled for a launch at the root at all, and not run outside a git repository, with no `git`, or when `git ls-files` takes longer than 5 seconds. **`--check` exits `2` on it**; enabling the plugin at user scope or in the root's `.claude/settings.local.json` clears it |
+| `refresh-helper-outdated` | a git hook runs an older graph refresh helper that uses directory-based locking (unsafe with uutils `mkdir`), or whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (Graphify 0.9.87 and later can rewrite installed agent skills after an upgrade). Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
+| `engine-version` | the graph was built by a Graphify release this Sidegraph was not tested with (its `graph.graphify_version` stamp is neither absent nor in the tested set), so anchors and domains may read differently. Advisory; **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. Pin Graphify to a tested release listed under [Engine version pinning](../integrations/graphify.md#engine-version-pinning), then rebuild the graph. It also fires for a mention-edge graph (Graphify 0.9.62 or later) over a store without a minimum Sidegraph version; follow the [0.14 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.14.md). A malformed marker leaves this second case silent. Silent without a readable graph |
+| `store-not-migrated` | the store uses the pre-0.17 layout (a format marker below major 2) and holds at least one record of any kind (initiatives included). One finding, at the store path, naming `sidegraph-migrate` (run on the default branch, after the team checklist in the [0.17 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.17.md)) and the `sidegraph:compact` skill. Degraded; **`--check` exits `2` on it**. `maintenance-due` is the one finding it does not escalate. Silent on an empty store and on a store that is already format 2 |
+| `maintenance-due` | a format-2 store that `sidegraph-compact` would tidy: more than 200 per-record files, or a legacy `archive/` segment it would delete, or a misplaced or duplicated shard line, or a stray shard file. `sidegraph-verify` does not report these; maintenance heals them. A segment kept because one of its lines is not safe to delete does not count. Advisory, and the one finding **`--check` does not escalate**: it is printed and listed in `--json`, but the exit code stays `0`. Run `sidegraph-compact` on the default branch. Silent on a store that is not format 2 |
 
 `degraded-binding`/`orphaned-binding` come from `index.db`, opened strictly read-only — it
 is the only source for binding status (canonical `bindings/*.json` files carry identity,
@@ -1651,13 +1654,15 @@ of the lines above. A store whose format marker refuses this version also skips
 checks: `remaining checks skipped (<the reason>)`, for example
 `remaining checks skipped (This store requires Sidegraph >= 0.15.0; this is 0.14.0.)`.
 A missing graph is deliberately not a finding: `--check` escalates
-every finding, so a CI job that runs doctor without building a graph would start exiting `2`.
+every finding except `maintenance-due`, so a CI job that runs doctor without building a graph
+would start exiting `2`.
 
 **Exit code:** `0` healthy — advisory findings alone stay `0` without `--check`. `1`
 operational error — same paths as `sidegraph-verify` (unreadable store; or, when `--against`
 is used, a bad ref or store outside any git repo), plus a negative `--stale-days`, rejected before the
 store is touched (same hard-usage treatment as `sidegraph-import --limit`). `2` strict
-violations, or — with `--check` — advisory findings too.
+violations, or — with `--check` — advisory findings too, except `maintenance-due`, which never
+changes the exit code.
 
 **Examples:**
 
@@ -1760,8 +1765,10 @@ What lands in the bundle:
   before, abandoned because…" is the product; the export doesn't hide it. The one thing it
   does hide is unratified `proposed` drafts — those have not entered the shared memory yet,
   so they are never published (proposed domains are dropped the same way).
-- `domains/` — one concept per slug (the latest revision row wins), with parent links
-  and an `# Anchored records` backlink section.
+- `domains/` — one concept per slug, with parent links and an `# Anchored records`
+  backlink section. The page shows the slug's current row: a row loses to every row of its
+  slug that has no later revision under that slug, following supersession through any slug,
+  and among the rest the newest id wins.
 - `entities/` — only entities actually referenced by an exported anchor; each page lists
   every decision/fact anchored to it. Bindings to `domain:*` entities link to the domain
   page instead; volatile `community:*` bindings are not exported at all.

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

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

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

@@ -1,7 +1,7 @@
 {
   "name": "sidegraph",
   "displayName": "Sidegraph",
-  "version": "0.18.0",
+  "version": "0.19.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.18.0 → sidegraph-0.19.0}/plugin/sidegraph/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.18.0",
+  "version": "0.19.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.18.0 → sidegraph-0.19.0}/plugin/sidegraph/.muse-plugin/plugin.json

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sidegraph"
-version = "0.18.0"
+version = "0.19.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"

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

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

{sidegraph-0.18.0 → sidegraph-0.19.0}/src/sidegraph/adr.py

@@ -36,7 +36,9 @@ _KINDS = frozenset({DecisionKind.ADR, DecisionKind.CONSTRAINT})
 
 @dataclass(frozen=True)
 class AdrSnapshot:
-    """Owned record values and canonical source locations, not volatile graph mappings."""
+    """Owned record values, not volatile graph mappings. Where a record is stored (a file,
+    a shard line, an archive segment) is not part of it: an exported document names a store
+    record by id, so migration and maintenance never change a generated document."""
 
     root: Path
     decisions: dict[str, Decision]
@@ -44,9 +46,6 @@ class AdrSnapshot:
     domains: dict[str, Domain]
     entities: dict[str, Entity]
     bindings: dict[str, list[AnchorBinding]]
-    record_paths: dict[str, Path]
-    fact_paths: dict[str, Path]
-    domain_paths: dict[str, Path]
 
     @property
     def exported(self) -> dict[str, Decision]:
@@ -87,23 +86,21 @@ def read_snapshot(path: Path) -> AdrSnapshot:
 def _snapshot_of(root: Path, packed: dict[tuple[str, str], EffectiveRecord]) -> AdrSnapshot:
     """The snapshot of a store: every record is its inventory's effective record
     (``store_rules.effective``), whichever file, shard line or archive segment holds it, so an
-    archived body never overwrites a live one. A record's path is where it is stored.
+    archived body never overwrites a live one.
 
     # see design/superpowers/specs/2026-10-20-packed-store-format-design.md (§7.2)"""
 
-    def of[Model: BaseModel](record_type: str, model: type[Model]) -> tuple[dict[str, Model], dict]:
-        values: dict[str, Model] = {}
-        paths: dict[str, Path] = {}
-        for (kind, rid), rec in packed.items():
-            if kind == record_type:
-                values[rid] = model.model_validate(rec.raw)
-                paths[rid] = rec.source_path(root)
-        return values, paths
-
-    decisions, record_paths = of("decision", Decision)
-    facts, fact_paths = of("fact", Fact)
-    domains, domain_paths = of("domain", Domain)
-    entities, _ = of("entity", Entity)
+    def of[Model: BaseModel](record_type: str, model: type[Model]) -> dict[str, Model]:
+        return {
+            rid: model.model_validate(rec.raw)
+            for (kind, rid), rec in packed.items()
+            if kind == record_type
+        }
+
+    decisions = of("decision", Decision)
+    facts = of("fact", Fact)
+    domains = of("domain", Domain)
+    entities = of("entity", Entity)
     bindings: dict[str, list[AnchorBinding]] = {}
     for (kind, rid), rec in packed.items():
         if kind == "bindings":
@@ -112,9 +109,7 @@ def _snapshot_of(root: Path, packed: dict[tuple[str, str], EffectiveRecord]) ->
             bindings[rid] = [
                 AnchorBinding.model_validate({**item, "record_id": rid}) for item in rec.raw
             ]
-    return AdrSnapshot(
-        root, decisions, facts, domains, entities, bindings, record_paths, fact_paths, domain_paths
-    )
+    return AdrSnapshot(root, decisions, facts, domains, entities, bindings)
 
 
 def _label(text: str) -> str:
@@ -122,7 +117,8 @@ def _label(text: str) -> str:
 
 
 def file_link(label: str, target: Path, out: Path) -> str:
-    """Link from a flat ADR directory, retaining archive ID in the label where needed."""
+    """Link from a flat ADR directory to a project file (a code anchor, a document ref).
+    Store records are never linked by path: see :func:`record_ref`."""
     try:
         path = os.path.relpath(target, out).replace(os.sep, "/")
     except ValueError:  # Windows cross-drive output has no relative spelling.
@@ -160,10 +156,19 @@ def record_domains(snapshot: AdrSnapshot, record_id: str) -> list[Domain]:
     return [current[slug] for slug in sorted(slugs) if slug in current]
 
 
-def _ref(snapshot: AdrSnapshot, rid: str, paths: dict[str, str], out: Path) -> str:
+def record_ref(rid: str) -> str:
+    """A store record named by its id. Never a path: the store's layout (a per-record file,
+    a shard line) changes under migration and maintenance, and the generated document and
+    its header hash must not.
+
+    # see design/superpowers/specs/2026-10-27-adr-record-locator-design.md"""
+    return f"`{_label(rid)}`"
+
+
+def _ref(rid: str, paths: dict[str, str]) -> str:
     if rid in paths:
         return f"[{_label(rid)}]({quote(paths[rid], safe='/')})"
-    return file_link(rid, snapshot.record_paths[rid], out)
+    return record_ref(rid)
 
 
 def render_record(
@@ -171,7 +176,7 @@ def render_record(
 ) -> str:
     """Render complete authored prose plus a mandatory source/status/evidence footer."""
     decision = snapshot.exported[record_id]
-    record_link = file_link(record_id, snapshot.record_paths[record_id], out)
+    record_link = record_ref(record_id)
     evidence_lines = []
     for fact in sorted(snapshot.facts.values(), key=lambda f: f.id):
         if (
@@ -180,8 +185,7 @@ def render_record(
             and record_id in fact.supports
         ):
             evidence_lines.append(
-                f"- {file_link(fact.id, snapshot.fact_paths[fact.id], out)}: {fact.statement}\n"
-                f"  Source: {fact.source}"
+                f"- {record_ref(fact.id)}: {fact.statement}\n  Source: {fact.source}"
             )
     anchors = []
     for binding in snapshot.bindings.get(record_id, []):
@@ -202,8 +206,11 @@ def render_record(
         else:
             detail = _label(descriptor_path) if descriptor_path else "no durable file path"
             anchors.append(f"- {_label(entity.canonical_name)} ({detail}; unlinked, not verified)")
+    # A backtick in a title would pair with the id's code span; escape it. The title's own
+    # backslashes are escaped first, before _label adds its bracket escapes, so neither
+    # cancels nor doubles another escape.
     domains = [
-        file_link(d.title, snapshot.domain_paths[d.domain_id], out)
+        f"{_label(d.title.replace('\\', '\\\\')).replace('`', '\\`')} ({record_ref(d.domain_id)})"
         for d in record_domains(snapshot, record_id)
     ]
     source = f"Recorded source: {decision.provenance.source}."
@@ -238,12 +245,8 @@ def render_record(
         "evidence": "\n".join(evidence_lines) or "None recorded.",
         "anchors": "\n".join(sorted(set(anchors))) or "None recorded.",
         "domains": ", ".join(domains) or "Unassigned",
-        "supersedes": _ref(snapshot, previous, paths, out)
-        if previous in snapshot.decisions
-        else "None",
-        "successors": ", ".join(
-            _ref(snapshot, d.id, paths, out) for d in sorted(successors, key=lambda d: d.id)
-        )
+        "supersedes": _ref(previous, paths) if previous in snapshot.decisions else "None",
+        "successors": ", ".join(_ref(d.id, paths) for d in sorted(successors, key=lambda d: d.id))
         or "None",
         "record_link": record_link,
         "source": source,

{sidegraph-0.18.0 → sidegraph-0.19.0}/src/sidegraph/cli.py

@@ -84,6 +84,7 @@ from .doc_import import (
     import_docs,
 )
 from .doctor import (
+    CHECK_EXEMPT_CODES,
     curate,
     open_curation_index,
     ratification_info_lines,
@@ -2749,7 +2750,7 @@ def doctor_main(argv: list[str] | None = None) -> int:
     (advisory findings alone stay 0 without ``--check``), 1 operational error (including
     a negative ``--stale-days``, rejected before the store is touched — same hard-usage
     treatment as ``sidegraph-import --limit``), 2 strict violations or, with ``--check``,
-    advisory findings.
+    advisory findings other than :data:`doctor.CHECK_EXEMPT_CODES` (``maintenance-due``).
     """
     parser = argparse.ArgumentParser(
         prog="sidegraph-doctor",
@@ -2773,7 +2774,8 @@ def doctor_main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "--check",
         action="store_true",
-        help="advisory findings also exit 2 (default: report only; skipped checks never fail)",
+        help="advisory findings also exit 2, except maintenance-due (default: report only; "
+        "skipped checks never fail)",
     )
     parser.add_argument(
         "--stale-days",
@@ -2955,7 +2957,7 @@ def doctor_main(argv: list[str] | None = None) -> int:
 
     if violations:
         return 2
-    if args.check and report.findings:
+    if args.check and any(f.code not in CHECK_EXEMPT_CODES for f in report.findings):
         return 2
     return 0