sidegraph 0.17.3__tar.gz → 0.19.0__tar.gz

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

@@ -180,10 +180,13 @@ jobs:
       - name: Test portable core and MCP contracts
         shell: pwsh
         run: |
-          # The wheel-smoke tests are release-only (tests/private); the public snapshot has no copy.
+          # Private acceptance files are absent from the public snapshot.
           $privateTests = @()
           if (Test-Path "tests/private/test_installed_wheel_smoke.py") {
-            $privateTests = @("tests/private/test_installed_wheel_smoke.py")
+            $privateTests += "tests/private/test_installed_wheel_smoke.py"
+          }
+          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" `
             tests/test_store_mutation_guard.py `
@@ -195,6 +198,7 @@ jobs:
             tests/test_verify_format2_snapshot.py `
             tests/test_store_format.py tests/test_store_rules.py `
             tests/test_maintenance_publish.py tests/test_migrate.py `
+            tests/test_store_junctions.py tests/test_format2_windows.py `
             tests/test_repo_relative_paths_portable.py `
             tests/test_command_windows.py `
             tests/test_hook_payload_encoding.py tests/test_hook_failure_diagnostics.py `

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

@@ -7,6 +7,58 @@ 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
+
+- `get_task_context` and `query_decisions` show at most 5 lines of related memory reached by
+  expansion. Each line has a short choice snippet and the record's id. The rest are counted
+  in one closing `- (+N more related not shown: …)` line. Global-scope rules and a seed's
+  superseded one-liners are not capped.
+
+### Fixed
+
+- Internal Windows directory junctions are refused by the store's link guard, including
+  junctions added before maintenance. Deliberately linked store roots remain supported.
+
+### Tests
+
+- Native Windows CI exercises packed-store migration, edits, compaction, Git checkout under
+  both autocrlf settings, long paths, busy files, case aliases and older-reader refusal.
+
 ## [0.17.3] — 2026-10-26
 
 ### Fixed

{sidegraph-0.17.3 → 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.17.3) — 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.17.3 → sidegraph-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.17.3
+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.17.3 → sidegraph-0.19.0}/docs/concepts/retrieval.md

@@ -250,11 +250,18 @@ unrelated question. The render is tiered instead:
   clipped to ~1200 characters, plus `rejected` and `consequences` (when populated) each
   clipped to ~400 characters, rendered as `"(context: ...)"`/`"(rejected: ...)"`/
   `"(consequences: ...)"` suffixes.
-- **Related tier** (`TaskContext.related` — bucket C/D and superseded one-liners): the
-  original tight one-liner — `choice` clipped to ~240 characters, title + snippet only, no
-  `context`/`rejected`/`consequences` at all, regardless of whether those fields are
-  populated. This is also what stops an off-topic decision's `rejected`/`consequences` from
-  repeating across unrelated questions — a related entry never renders them.
+- **Related tier** (`TaskContext.related` — bucket C/D and superseded one-liners): a
+  short one-liner with no `context`/`rejected`/`consequences` and no inline evidence,
+  regardless of whether those fields are populated. This is also what stops an off-topic
+  decision's `rejected`/`consequences` from repeating across unrelated questions — a
+  related entry never renders them. Records reached through community, domain, peripheral
+  or guessed-seed expansion show at most **5** lines, each with `choice` clipped to ~80
+  characters and the record's `(id: …)` so it can be expanded with
+  `retrieve_decisions(ids=[…])`; any further ones are counted in one closing
+  `- (+N more related not shown: …)` line instead of rendered. Most of these records were
+  measured off-task for the task at hand. Two kinds stay outside that cap and keep the
+  plain one-liner (`choice` clipped to ~240 characters, no id): `scope: global` decisions,
+  which are repo-wide rules, and the seed's own superseded one-liners, which are its history.
 
 Every clip cuts at a word boundary with a trailing ellipsis. The one exception is a single unbroken token longer than the limit (a long identifier or URL), which is cut hard at the limit. The per-field
 clips are applied *before* the `memory_chars` check, not a bypass of it: a single
@@ -291,7 +298,7 @@ already on the line (the `(id: …)` suffix these tiers carry).
 
 Whenever at least one marker renders, one fixed legend line is appended to the context
 (and `drill_down` returns it as a separate `"legend"` key) explaining exactly that. The
-related tight tier never carries the marker — no id, no supersede consumer there. Marker
+related tight tier never carries the marker, even on the capped lines that show an id. Marker
 freshness rides a store-meta cache refreshed by the SessionStart/Stop hooks
 (`sync.refresh_code_drift_cache`, one bounded git scan); records superseded mid-session are
 filtered out at read time, so a marker never outlives its record's liveness. Only

{sidegraph-0.17.3 → 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.17.3 → 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.17.3 → 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.17.3 → sidegraph-0.19.0}/docs/guides/retrieval-in-sessions.md

@@ -200,8 +200,9 @@ Proposed records use the final quarantine block instead of the accepted sections
 A `Fact` you attached to a decision (its own `facts` list — see
 [`guides/capturing-decisions.md#facts-the-evidence-layer`](capturing-decisions.md#facts-the-evidence-layer))
 rides that decision's line after both records are accepted: the moment an accepted decision is
-rendered in `## ⚠ Known mistakes & gotchas`, `## Decisions`, or `## Related`, its accepted
-supporting facts render right under it, one indented line each. A proposed fact is collected
+rendered in `## ⚠ Known mistakes & gotchas`, `## Decisions`, or as a `scope: global` line in
+`## Related`, its accepted supporting facts render right under it, one indented line each. The
+other `## Related` lines are short capped one-liners and carry no evidence. A proposed fact is collected
 for `## Unratified proposals` instead. The one exception:
 the `~ tried, reverted 2026-01: ...` superseded one-liners also shown under `## Related` never
 get evidence — a reverted decision's evidence isn't useful at that tight, unbudgeted-for-detail

{sidegraph-0.17.3 → 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.17.3 → 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.17.3 → 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.17.3 → sidegraph-0.19.0}/docs/reference/mcp-tools.md

@@ -788,7 +788,9 @@ degrades to un-synced retrieval, never an error), resolves `files`/`entities` in
 and returns a rendered Markdown string with up to six sections — accepted mistakes (with
 accepted inline evidence facts), accepted decisions (with accepted inline evidence), accepted
 known facts (standalone), structural map, related accepted memory, and unratified proposals —
-under the given character budgets. See
+under the given character budgets. Related memory reached by expansion shows at most 5 short
+lines with ids, plus a count of the rest; see
+[retrieval: two-tier rendering](../concepts/retrieval.md). See
 [retrieval: facts](../concepts/retrieval.md#facts-inline-evidence-and-the-known-facts-bucket)
 for the inline-vs-standalone split and the guarantee that facts never displace a mistake. The
 structural map omits

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

@@ -46,11 +46,12 @@ characters long. Every ULID qualifies. The store refuses to write a record whose
 different from its filename is not a record at all: see
 [Freshness](#freshness-absorbing-a-git-pull) for how a reload treats it.
 
-**Symlinks inside the store are refused.** A `Store` will not open a directory any of whose
+**Symlinks and Windows junctions inside the store are refused.** A `Store` will not open a directory any of whose
 subdirectories (`decisions/`, `facts/`, `domains/`, `entities/`, `bindings/`, `initiatives/`,
 `archive/`, `verifications/`, `shards/`), store files (`format`, `stamping_live_since`,
 `domain-snapshot.json`, `.gitignore`, `.gitattributes`, `index.db`, and
-SQLite's `index.db-journal`, `-wal` and `-shm`) or shard files (`shards/*.shard`) is a symlink, live or dangling: a linked
+SQLite's `index.db-journal`, `-wal` and `-shm`) or shard entries (`shards/*.shard`) is a symlink
+(live or dangling) or Windows directory junction: a linked
 `decisions/` would send every record write to the link's target, and a linked `index.db` would
 make SQLite write there. The error names the entry (`… inside the store is a symlink`);
 replace it with a real directory or file. `sidegraph-verify` reports each such entry as
@@ -58,10 +59,29 @@ replace it with a real directory or file. `sidegraph-verify` reports each such e
 `--against` comparison until the links are removed, and its text output says so in one line.
 An `--against` ref that does not resolve, or a store outside git, is checked before the stop and
 exits `1` without reporting the links.
-`sidegraph-doctor` does the same and skips its advisory checks. A symlinked store **root**
+`sidegraph-doctor` does the same and skips its advisory checks. Junctions use the same
+`symlinked-store-entry` code and existing symlink error wording. A deliberately linked store **root**
 (`.sidegraph -> ../shared/store`) is fine: a deliberately shared store is a real use. Record
 files inside a real subdirectory are still read as they are.
 
+On Windows, format-2 maintenance writes shard bytes in binary mode, avoiding Python's
+newline conversion. The store's `*.shard -text` Git attribute preserves those LF bytes
+across checkout under either `core.autocrlf` setting. If another application holds a shard open
+without delete sharing, replacement can fail with `PermissionError`. The error propagates;
+maintenance does not delete the source files it has not finished publishing. Close the other
+application and rerun the operation. Filesystem path/component limits likewise remain
+operational errors; use a shorter store path if the host or Git cannot handle long paths
+(`core.longpaths=true` enables Git for Windows' long-path support).
+That option does not guarantee every Git operation can start from a directory longer than
+260 characters. If Git refuses the store directory during migration's entry checks, the
+marker and records remain unchanged; use a shorter checkout/store path and retry.
+
+Verify each committed operation against its input commit: migration against the format-1
+commit, a record edit against the migrated commit, and compaction against the commit containing
+the edited hot file. A compaction comparison checks that each published body existed in its
+baseline; comparing an edited, compacted body directly to a ref before the edit does not meet
+that requirement.
+
 **A symlinked store belongs to the project that holds the link.** The code a record is anchored
 to lives in that project, so the repository Sidegraph asks about the store is the project's, not
 the one the link points into: the `provenance.commit` stamped at capture is the project's `HEAD`

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sidegraph"
-version = "0.17.3"
+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.17.3 → sidegraph-0.19.0}/src/sidegraph/__init__.py

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