sidegraph 0.17.1__tar.gz → 0.17.3__tar.gz

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

@@ -201,6 +201,7 @@ jobs:
             tests/test_hot_index_facts.py `
             tests/test_delivery_evidence.py tests/test_delivery_stats.py tests/test_delivery_surfaces.py `
             tests/test_git_output_utf8.py `
+            tests/test_githooks_atomic_lock.py::test_windows_pid_probe_is_never_a_signal_from_python `
             tests/test_health_check_skill.py `
             $privateTests
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

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

@@ -7,6 +7,48 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.17.3] — 2026-10-26
+
+### Fixed
+
+- Graph refresh hooks acquire both the runner lock and stale-breaker gate with exclusive
+  shell PID files. Concurrent hooks remain serialized on systems whose external `mkdir`
+  can report success to two racing callers, while live legacy directory locks are respected.
+- Installer cleanup coordinates with the same breaker gate and preserves a lock whose owner
+  changed during its PID check. Optional native-lock failures no longer prevent publishing
+  an updated helper, and a failed gate PID write no longer leaves a permanent gate.
+- Doctor detects the complete older directory-lock helper; plain `sidegraph-init` repairs
+  it while keeping hook bytes and the recorded choice. Automatic detection conservatively
+  preserves unfamiliar scripts and quoted examples. Run `sidegraph-init` after upgrading
+  in each clone that uses the old helper.
+- Native Windows installer cleanup leaves PID-bearing locks untouched, instead of using
+  Python signal probes on process ids from a potentially different POSIX-shell namespace.
+
+## [0.17.2] — 2026-10-25
+
+### Fixed
+
+- Doctor identifies per-record advisory findings with `record_id` and `record_type` in
+  JSON and prints the subject beside its physical path in text. Decisions sharing one
+  packed shard, source file and capture commit can now be triaged separately. This also
+  covers never-surfaced, orphaned-record, binding and other record findings; global notes
+  remain subjectless. Fixes [#1](https://github.com/SantyagoSeaman/sidegraph/issues/1).
+- MCP domain-listing hints use the local Store API for oversized records, including packed
+  domains, and pending-proposal hints explain the visibility policy instead of promising
+  that an explicit id can bypass it.
+- Drift checks distinguish missing required anchor files, absent checkable anchors and
+  untracked inspected paths with safe fixed diagnostics. Missing-scope errors explain how
+  to inspect the full anchor scope locally without reading SQLite. Unavailable anchor
+  entities and failed Git scope lookups get specific diagnostics before any check is published.
+- Ratification refusals explain that an accepted decision or fact is not proposed. The
+  drift and anchor playbooks no longer recommend dropping accepted decisions, and clarify
+  that drift markers appear in formatted context rather than raw decision-listing JSON.
+- PreToolUse refuses delivery before claiming files if a record-selection read fails.
+  Concurrent zero-wait hooks therefore cannot skip an unreadable early file and consume
+  different three-file sets from the same command.
+- Complete the headless anchor-healing example's write-tool deny list with drift-check
+  writes and domain proposals.
+
 ## [0.17.1] — 2026-10-25
 
 ### Security

{sidegraph-0.17.1 → sidegraph-0.17.3}/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.1) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.17.3) — 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.1 → sidegraph-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.17.1
+Version: 0.17.3
 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.1 → sidegraph-0.17.3}/docs/guides/ci-cd-maintenance.md

@@ -10,9 +10,10 @@ unattended.
 
 1. **CI never ratifies.** Nothing in these recipes calls `ratify`/`sidegraph-ratify --accept`
    (or `--drop`, for that matter). A scheduled job may *propose* a superseding decision
-   (`propose_decisions` with `supersedes`) or *recommend* a drop in its summary, but turning
-   a proposal into an accepted/rejected terminal state stays a human action, every
-   time. See [`heal-anchors`](../../plugin/sidegraph/skills/heal-anchors/SKILL.md#triage-decision-tree-add_anchors-propose_decisions-or-recommend-a-drop)
+   (`propose_decisions` with `supersedes`) or report obsolete subjects in its summary.
+   Recommend drop only for proposed decisions/facts or a supported domain drop; accepted
+   decisions without a meaningful successor retain their history. A proposal verdict
+   stays a human action. See [`heal-anchors`](../../plugin/sidegraph/skills/heal-anchors/SKILL.md#triage-decision-tree-re-anchor-supersede-or-report-an-obsolete-subject)
    for the triage tree these jobs run. An auto-ratification policy would break this rule
    without any `ratify` call — the transition rides `propose_decisions` itself, which the
    deny list below cannot block. Legacy `SIDEGRAPH_AUTO_ACCEPT=on` bypasses the queue too.
@@ -316,9 +317,10 @@ jobs:
           claude -p 'Run the heal-anchors playbook: call sync_anchors(force=True), then for
           every orphaned/ambiguous entity and every stale decision, follow the triage tree —
           add_anchors for code that moved, propose_decisions(supersedes=...) for content
-          that is genuinely outdated, and a plain-text recommendation (never a tool call)
-          for anything to drop. Summarize every action taken and every recommendation at
-          the end.' \
+          that is genuinely outdated, and a status-aware summary for obsolete subjects.
+          Recommend drop only for proposed decisions/facts or a supported domain drop;
+          retain accepted decision history when there is no meaningful successor.
+          Summarize every action taken and recommendation at the end.' \
             --model "$SIDEGRAPH_TRIAGE_MODEL" \
             --mcp-config mcp-config.json --strict-mcp-config \
             --allowedTools "mcp__sidegraph__sync_anchors mcp__sidegraph__find_entity mcp__sidegraph__query_structure mcp__sidegraph__query_decisions mcp__sidegraph__add_anchors mcp__sidegraph__propose_decisions mcp__sidegraph__list_proposed mcp__sidegraph__retrieve_decisions mcp__sidegraph__get_entity_history mcp__sidegraph__list_facts mcp__sidegraph__verify_store" \
@@ -355,7 +357,7 @@ CLI default.
 
 Do not add `--permission-mode bypassPermissions`: it disables both tool lists. The
 `--disallowedTools` list is the ratification guard: it names the tools that ratify or write a
-record directly and the one that records a drift check. The allowlist only narrows normal MCP
+record directly, records a drift check, or proposes a domain. The allowlist only narrows normal MCP
 access and can be widened by ambient host settings. Keep both. Read-only built-in
 tools can still inspect the checkout in a headless run; the troubleshooting note below states
 that boundary explicitly. The matching

{sidegraph-0.17.1 → sidegraph-0.17.3}/docs/guides/troubleshooting.md

@@ -222,8 +222,11 @@ entity file is skipped, an anchor to the same name mints a second entity; once t
 
 ### refresh-helper-outdated
 
-A git hook runs a graph refresh helper that starts Graphify without `GRAPHIFY_NO_AUTO_REFRESH=1`
-(an older Sidegraph wrote it). Graphify 0.9.87 and later refresh the agent skills they installed,
+A git hook runs an older graph refresh helper that uses directory-based locking, or starts
+Graphify without `GRAPHIFY_NO_AUTO_REFRESH=1`.
+The directory lock can admit overlapping rebuilds with uutils `mkdir`; the replacement uses
+exclusive PID files for both the runner lock and the stale-breaker gate.
+Graphify 0.9.87 and later refresh the agent skills they installed,
 such as `~/.claude/skills/graphify/`, on the first run after a Graphify upgrade unless that
 variable is set. One hook that runs the helper is enough for the check to fire, and a recorded "no"
 does not silence it. Run `sidegraph-init` with no flag: it rewrites the helper and keeps your

{sidegraph-0.17.1 → sidegraph-0.17.3}/docs/integrations/graphify.md

@@ -242,13 +242,25 @@ the `/graphify` skill's `--update` form).
   [above](#linked-worktrees-read-the-main-checkouts-graph)), so a commit in one does nothing.
   Rebuilding there as well costs about 18 MB and 43 s for a cold build on one field corpus with
   25 worktrees, and agents commit in worktrees constantly.
-- **In the background, one at a time.** Git never waits for the rebuild. A lock directory keeps
+- **In the background, one at a time.** Git never waits for the rebuild. An exclusively created PID file keeps
   one rebuild running; a hook that fires while it runs makes it go once more when it finishes, so
   the graph never settles on a tree older than the last request. A lock left by a job that died
   is detected and cleared: by its pid, or, when the job died before writing one (a full disk, a
-  quota), by its age, ten minutes. `sidegraph-init --hooks` clears such a lock at once. One risk
+  quota), by its age, ten minutes. Re-running `sidegraph-init --hooks` refreshes the helper and clears a dead lock;
+  a fresh lock without a PID is kept until the ten-minute grace period expires. One risk
   remains: after a reboot a pid can belong to a live, unrelated process, and the hook then waits
   until that process exits.
+  Plain `sidegraph-init` also repairs an outdated helper in use, keeping the recorded choice.
+  Older helpers used lock directories; the new helper respects a live old runner and can
+  recover its stale directory. Both the lock and the stale-breaker gate now use shell
+  exclusive creation, so locking does not depend on external `mkdir`.
+  Installer cleanup takes the same breaker gate before removing a dead runner lock. A small
+  native OS lock on `sidegraph-graph-refresh.repair` serializes installers while they recover
+  a dead gate; the coordination file stays in the common git directory to keep a stable inode.
+  Where native locks are unsupported, helper publication still proceeds and optional installer
+  cleanup is skipped. On Windows, PID-bearing locks are left to the POSIX helper to recover,
+  because its PIDs need not be native Windows PIDs. Installing or repairing a helper does not
+  itself start a rebuild.
 - **Where the output goes.** The last rebuild's output is `sidegraph-graph-refresh.log` in the
   common git directory (`.git/` in a normal clone).
 - **No `sidegraph-sync` in the hook.** The next memory call notices the new graph version and

{sidegraph-0.17.1 → sidegraph-0.17.3}/docs/reference/cli.md

@@ -1562,7 +1562,7 @@ plain-text line):
 | `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 a graph refresh helper whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (an older Sidegraph wrote it), so Graphify 0.9.87 and later can rewrite the agent skills they installed on the first rebuild 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 |
+| `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 |
@@ -1617,6 +1617,16 @@ neither flagged nor cleared. `drill_down` does record a `domain:<slug>` seed, bu
 consumes it yet; its *shows* count normally, so surfacing only through a domain drill-down
 still protects a decision from a false flag.
 
+Each JSON finding has `code`, `path`, `detail`, `record_id` and `record_type`.
+Per-record findings carry their logical identity (`decision`, `fact`, `entity`, `domain`,
+or `bindings`); global notes have null record fields. A malformed raw record whose id
+cannot be read also has a null subject; use its violation and physical path for repair. `path` retains the physical source,
+including a shared shard or archive segment, so it is not a record locator. Text prints
+`<code>  <record_type>:<record_id>  <path>  <detail>` for identified subjects; global notes
+omit the subject column. `duplicate-entity` identifies the selected lowest-id entity;
+its detail names the other members. A `bindings` subject uses the bound record's id.
+Use `record_id` to retrieve or check a drifted decision; do not parse the shard or detail.
+
 `clean` is `true` only when both `violations` and `findings` are empty.
 
 **Skipped checks.** A check that cannot look says so and is never a finding: it affects neither

{sidegraph-0.17.1 → sidegraph-0.17.3}/docs/reference/hooks.md

@@ -402,6 +402,13 @@ raises costs only its own line.
     > installed on the first rebuild after an upgrade. Ask the user to run `sidegraph-init`,
     > which refreshes the helper and keeps their recorded hook choice; do not run it unasked.
 
+    A helper using the old directory-based lock is also reported: uutils `mkdir` can admit
+    overlapping rebuilds. `sidegraph-init` replaces it with exclusive PID-file locking while
+    preserving hook bytes and the recorded choice. The outdated-helper check recognizes concrete defects in simple shell helpers,
+    rather than comparing the whole template. It conservatively skips unfamiliar scripts with
+    heredocs or multiline quotes. This controls automatic defect repair; an ordinary init
+    that refreshes a fully installed hook still rewrites its managed helper.
+
     It also sends a notice for the person. See
     [`refresh-helper-outdated`](../guides/troubleshooting.md#refresh-helper-outdated).
 15. **Refresh-hook line.** When no git hook keeps the graph fresh, one line tells the model to
@@ -832,6 +839,10 @@ permission flow, untouched:
    session's own agent, so the main agent's keys do not start with any subagent's prefix. The value
    is the claim's ISO timestamp. These keys are deliberately **not** the `Stop` hook's
    `capture_sessions` ledger, so the guards can't consume each other.
+   If any record-selection read fails, the hook refuses this delivery before claiming any
+   file. An unreadable early file is not treated as an empty one: otherwise parallel hooks
+   could choose different triples from the same command. A later clean call may deliver
+   the files because this refusal consumes no per-file claim or showing.
 7. If at least one claim succeeded, the winner emits one non-blocking, `additionalContext`-only
    block for the files it won:
 

{sidegraph-0.17.1 → sidegraph-0.17.3}/docs/reference/mcp-tools.md

@@ -765,8 +765,10 @@ hundreds of records, so the answer fills in this order:
    `omitted_ids_unlisted` counts ids the budget cut as well.
 
 Nothing is dropped silently: a superseded record is at worst a short row or a bare id. Read an
-omitted decision with `retrieve_decisions(ids=[...])` and an omitted fact with
-`list_facts(ids=[...])`, or narrow with `status=[...]` (for example `["superseded"]`).
+omitted decision locally with `Store.get_decision(id)` and an omitted fact with
+`Store.get_fact(id)` on the configured store, or narrow with `status=[...]` (for example
+`["superseded"]`). Explicit-id `retrieve_decisions`/`list_facts` calls still obey the
+proposal-surfacing policy and may omit older or regulated-mode proposals.
 `omitted_records` and `omitted_ids` appear only when something was left out.
 
 ## `get_task_context`
@@ -1228,10 +1230,13 @@ initial prefix of complete rows, sorted by slug. Each row retains the existing f
 "seed_anchor_count", "parent_slug", "child_slugs"}`. `member_count` remains
 `len(domain.communities)`. Parent/child lineage comes from the full store even when filters
 exclude relatives. When the character budget omits rows, `hint` identifies the effective bound,
-suggests filters, and names a bounded relative local-file fallback for the next omitted domain
-(`domains/<id>.json`). That file exists only while the domain is stored as a per-record file;
-once maintenance has packed it into a shard (store format 2), narrow with `status`, `query` or
-`ids` instead of following the path.
+suggests filters, and names a bounded local Python fallback for the next omitted domain:
+`Store.get_domain("<id>")` on the configured store. It returns the full model, including
+`seed_anchors`, for both per-record and packed layouts. Open the configured store with
+`with Store(store_path) as store:` and call `store.get_domain(id)`; a domain may no longer
+have an individual `.json` file. If the id itself cannot fit the hint, use
+`Store.iter_domains()`. This local Store access can rebuild the derived index; it is distinct
+from the read-only MCP listing.
 When `limit` cuts the list, the hint suggests filters and raising `limit` only below 100. Empty
 stores say `No domains in the store.`; empty filtered matches name active filter keys without
 echoing their values. This is the provisional MCP return shape and sends no output schema or
@@ -1494,12 +1499,14 @@ When the queue does not fit, the first line counts it (`Pending: 31 decisions, 4
 domains. Showing 18 decisions, 0 facts, 2 domains.`), the sections fill in order with the
 blocks that fit (a block that does not fit is skipped and the fill goes on), and the end lists
 what is missing, in the order of the blocks, as `<id> <title head>` entries (then `and N more
-ids`). `ratify` accepts an id you have not read, so nothing is out of reach. The end also says how to read
-an item that is not shown (`retrieve_decisions(ids=[...])`, `list_facts(ids=[...])`,
-`list_domains(status="proposed")`). Those reads obey the proposal window
-(`SIDEGRAPH_PROPOSAL_WINDOW_DAYS`), so a proposed decision or fact older than the window is not
-returned by id; read it with `sidegraph-ratify` without flags, which lists every pending
-proposal. Ratify what is shown, then call again, or raise `budget_chars`.
+ids`). Read every item before deciding its verdict. The hint explains that decision
+or fact proposals may be hidden from `retrieve_decisions`/`list_facts` by the proposal
+window or regulated mode;
+explicit ids do not bypass that policy. Inspect omitted decisions locally with
+`Store.get_decision(id)` and omitted facts with `Store.get_fact(id)` on the configured
+store, or use `sidegraph-ratify` without flags for the full pending queue. Domains use
+`list_domains(status="proposed")`. Ratify what is shown, then call again, or raise
+`budget_chars`.
 
 **Returns:** a plain-text string.
 
@@ -1556,6 +1563,12 @@ makes `bootstrap → ratify` turn the TOC on in the same session, without waitin
 two only ever appear for a fact id that rode a decision's cascade rather than being named
 directly.
 
+Decisions and facts can be accepted or dropped only while `proposed`. A refusal names
+the existing status; an accepted decision cannot be retired through `drop`. Propose a
+meaningful supersession when the recorded claim becomes obsolete. If no successor exists,
+report that limitation and retain history rather than editing canonical status fields.
+Domain drop has its separate accepted-domain exception.
+
 ## `ratify_decisions` (deprecated)
 
 ```python
@@ -1815,7 +1828,15 @@ that exact HEAD; unrelated dirty files do not block the check. All current check
 concrete anchor files are required; explicitly inspected dependencies may extend coverage.
 Unknown binding status conservatively includes existing committed anchor paths. Abstract-only,
 unstamped, skipped or terminal subjects, missing Git HEAD, incomplete scope and dirty
-inspected files are refused without a new check. Existing safe write diagnostics apply.
+inspected files are refused without a new check. Missing required anchors return the
+fixed code `missing_required_files`, distinct from `no_checkable_files` and `untracked_files`.
+To inspect the scope locally without querying SQLite, open the configured Store, call
+`store.bindings_for_record(decision_id)`, and resolve each `binding.entity_id` with
+`store.get_entity(...)`; inspect the descriptors' file paths and current Git entries.
+Include every current checkable concrete anchor, not just doctor's changed-file subset.
+An unloadable required entity returns `unavailable_anchor_scope`; a failed initial Git
+scope lookup returns `git_scope_unavailable`. Both refusals occur before check publication.
+Write errors keep their bounded schema vocabulary and do not echo file names or raw causes.
 
 The result names `id`, `decision_id`, `checked_commit`, `required_files`, `checked_files`,
 `provenance`, `cache_cleared` and `redactions`. `cache_cleared` only says whether an existing

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

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

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

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

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

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

{sidegraph-0.17.1 → sidegraph-0.17.3}/plugin/sidegraph/skills/explain-why/SKILL.md

@@ -45,8 +45,10 @@ accepted it yet — present it as a proposal, not settled memory.
 
 `get_entity_history` returns superseded records too — that's the point. On a long-lived
 entity the newest records come in full and the rest as short rows (`omitted_records`) or bare
-ids (`omitted_ids`): read one with `retrieve_decisions(ids=[...])` / `list_facts(ids=[...])`, or
-narrow with `status=["superseded"]`. The answer to a
+ids (`omitted_ids`). Explicit-id `retrieve_decisions` / `list_facts` calls obey the
+proposal-surfacing policy and can omit old or regulated-mode proposals. For complete local
+records use `Store.get_decision(id)` / `Store.get_fact(id)` on the configured store, or
+narrow history with `status=["superseded"]`. The answer to a
 why-question has two layers, and the reader deserves both, clearly separated:
 
 1. **Current truth** — the live (`accepted`) records: the standing decision, its

{sidegraph-0.17.1 → sidegraph-0.17.3}/plugin/sidegraph/skills/heal-anchors/SKILL.md

@@ -74,6 +74,9 @@ store write or a source change: confirm before acting.
      with **explicit fresh `anchors` pointing at the successor code**. Do NOT omit
      `anchors` here: omitting inherits the predecessor's bindings verbatim — *including
      their orphaned status* — which reproduces exactly the problem you're healing.
+   If an accepted decision has no meaningful successor, report the obsolete subject to
+   the human and retain its history. `ratify(drop=...)` rejects only proposed decisions
+   and facts; it cannot retire an accepted decision. Do not edit canonical status fields.
 2. **A lone `orphaned: <name> (no match)`** whose decision is NOT in the stale block —
    multi-anchor did its job: another anchor still holds the decision live. No action
    needed unless the orphaned one was the load-bearing anchor.
@@ -89,8 +92,9 @@ store write or a source change: confirm before acting.
    domain's frozen membership is, and a re-scope applies only after
    `sidegraph-domains snapshot --refresh --domain <slug>`); read the old rule back first
    (`list_domains(ids=[<domain_id>])` returns the exact complete row, including
-   `path_prefixes`; check its `hint` and use its local-file fallback if the row does not fit;
-   for the actual `seed_anchors` list read `.sidegraph/domains/<domain_id>.json`) and carry what's still
+   `path_prefixes`; check its `hint` and use its local Store fallback if the row does not fit;
+   for the actual `seed_anchors` list use local Python `Store.get_domain(domain_id)`
+   on the configured store, which works for files and packed shards) and carry what's still
    right — then `ratify(accept=[<new_id>])`. Or retire it: `ratify(drop=[<domain_id>])`
    if the area is genuinely gone.
 5. **`path rule too broad — path contribution dropped (...):`** — a `path_prefixes` rule
@@ -127,7 +131,7 @@ store write or a source change: confirm before acting.
    not, `ratify(drop=[<the part that should not exist>])`: the remaining domain takes the
    frozen membership back at once.
 
-## Triage decision tree (add_anchors, propose_decisions, or recommend a drop)
+## Triage decision tree (re-anchor, supersede, or report an obsolete subject)
 
 For every `orphaned`/`ambiguous` entity and every `stale_decisions` entry, walk this tree
 before touching anything — the same tree whether you're triaging interactively or running
@@ -174,16 +178,17 @@ is gated on a human's `ratify`. Never call `supersede_decision`/`supersede_fact`
 immediately-`accepted` MCP tools) from an unattended/CI context — unlike `propose_decisions`,
 they skip the ratify gate entirely.
 
-**(c) The subject is genuinely gone.** The code (or doc section) the decision was about was
-deleted outright, not renamed or moved. There is no tool call for this: recommend a drop in
-your summary (`ratify(drop=[<id>])`, or `sidegraph-ratify --drop <id>`, for a *human* to
-run) and stop there. **Never drop a decision yourself.** Dropping is append-only-safe, but
-it is a ratify-gate action exactly like accepting one — that judgment call belongs to a
-human, same as every other write this skill routes to a human instead of performing.
+**(c) The subject is genuinely gone.** Confirm that it was deleted rather than renamed
+or moved. Check the record's current status. For an accepted decision, propose a meaningful
+supersession when something remains true or successor code exists; otherwise report the
+obsolete subject and retain its history. There is no accepted-decision retirement API.
+`ratify(drop=[<id>])` and `sidegraph-ratify --drop <id>` reject only proposed decisions/facts.
+Recommend those only for proposed records, and leave the verdict to the human. Domain drop
+has its separate accepted-domain exception. Never edit canonical status or valid_to fields.
 
 ## Running this playbook headlessly (CI)
 
-Everything above except the drop in (c) is a tool call, not a judgment a human has to make
+The lookup, binding-repair and proposal steps above can run without a human verdict
 in the moment — `sync_anchors`/`find_entity`/`query_structure`/`add_anchors`/
 `propose_decisions` all run fine unattended, and so do the tools that read records
 (`retrieve_decisions`/`get_entity_history`/`list_facts`/`verify_store`) used to confirm a
@@ -199,12 +204,13 @@ policy would ratify through `propose_decisions` with no `ratify` call at all, wh
 claude -p 'Run the heal-anchors playbook: call sync_anchors(force=True), then for every
 orphaned/ambiguous entity and every stale decision, follow the triage tree — add_anchors
 for code that moved, propose_decisions(supersedes=...) for content that is genuinely
-outdated, and a plain-text recommendation (never a tool call) for anything to drop. Do not
-call ratify. Summarize every action taken and every recommendation at the end.' \
+outdated, and a status-aware summary for obsolete subjects. Recommend drop only for
+proposed decisions/facts or a supported domain drop; retain accepted decision history when
+there is no meaningful successor. Do not call ratify. Summarize every action taken and every recommendation at the end.' \
   --model claude-sonnet-5 \
   --mcp-config mcp-config.json --strict-mcp-config \
   --allowedTools "mcp__sidegraph__*" \
-  --disallowedTools "mcp__sidegraph__ratify,mcp__sidegraph__ratify_decisions,mcp__sidegraph__add_decision,mcp__sidegraph__supersede_decision,mcp__sidegraph__supersede_fact,mcp__sidegraph__supersede_domain,mcp__sidegraph__add_domain,mcp__sidegraph__add_fact" \
+  --disallowedTools "mcp__sidegraph__ratify,mcp__sidegraph__ratify_decisions,mcp__sidegraph__add_decision,mcp__sidegraph__supersede_decision,mcp__sidegraph__supersede_fact,mcp__sidegraph__supersede_domain,mcp__sidegraph__add_domain,mcp__sidegraph__add_fact,mcp__sidegraph__record_drift_check,mcp__sidegraph__propose_domains" \
   --output-format stream-json --verbose
 ```
 
@@ -214,7 +220,8 @@ system itself consults, so under bypass they'd bind nothing at all, and the run
 able to call every tool including `ratify`. **The `--disallowedTools` deny list is the
 load-bearing guard**: it names the exact write-gate tools this playbook must never call
 unattended — `ratify`/`ratify_decisions`, `add_decision`/`supersede_decision`,
-`add_fact`/`supersede_fact`, `add_domain`/`supersede_domain` — and blocks them regardless
+`add_fact`/`supersede_fact`, `add_domain`/`supersede_domain`, `record_drift_check`,
+`propose_domains` — and blocks them regardless
 of the machine's ambient permission configuration. The `--allowedTools` wildcard is scoping,
 not enforcement: on a pristine machine a headless `-p` run auto-denies *MCP* tool calls
 outside it (no terminal to prompt), but a permissive user- or project-level `settings.json`

{sidegraph-0.17.1 → sidegraph-0.17.3}/plugin/sidegraph/skills/manage-domains/SKILL.md

@@ -28,8 +28,8 @@ path_prefixes, seed_anchor_count, parent_slug, child_slugs}`. `member_count` is
 `len(communities)` (0 for a domain not yet ratified/synced), and lineage reflects the full store.
 Read `hint` before assuming the listing is complete. Narrow with `status`, `query` (AND terms
 across slug/title/summary), or `ids` (exact domain ids). `limit` is clamped to 1..100 and
-`budget_chars` to 4,000..40,000. A budget cut includes the relative domain-file fallback for
-the next omitted row; a count cut suggests filters and raising `limit` only while it is below
+`budget_chars` to 4,000..40,000. A budget cut includes a local `Store.get_domain(id)` fallback for
+the next omitted row in either storage layout; a count cut suggests filters and raising `limit` only while it is below
 100. This is the tool for "show me all domains" — prefer it over the narrower views below:
 
 - **`list_proposed()`** — domains awaiting ratification only (`status=proposed`), rendered
@@ -97,10 +97,9 @@ need git-history archaeology either:
   the row still does not fit.
 - **`seed_anchors`** has no structured tool-read for the descriptors themselves —
   `list_domains()` gives you only `seed_anchor_count` (how many, not what). For the actual
-  `{"name", "file_path"}` list, read the committed domain file directly:
-  `.sidegraph/domains/<domain_id>.json` (the full row minus the volatile `communities` field —
-  see [store format](../../../../docs/reference/store-format.md)) — still structured JSON, just
-  not exposed through an MCP tool yet.
+  `{"name", "file_path"}` list, use local Python `Store.get_domain(domain_id)` on the configured store and read
+  its `seed_anchors`. This works for per-record files and packed shards; a domain may no
+  longer have its own `.json` file (see [store format](../../../../docs/reference/store-format.md)).
 
 `supersede_domain` is also the mechanism behind the naming guide's [recovering from a
 mass-drop](../../../../docs/guides/naming-your-domains.md#recovering-from-a-mass-drop): give

{sidegraph-0.17.1 → sidegraph-0.17.3}/plugin/sidegraph/skills/triage-drift/SKILL.md

@@ -28,10 +28,18 @@ The CLI runs through uvx at the session's version, never the copy on `PATH` ([wh
 uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-doctor --json    # findings[] entries with "code": "code-drift"
 ```
 
-Each finding names the record and changed files or why its prior check no longer
-applies (including subject/anchor-scope changes). Original `provenance.commit` stays history. `sidegraph-doctor` is a pure read — safe to run any time. From
-inside a session, the drifted set also announces itself: the SessionStart line and
-`[drifted]` tags in retrieval output are the same population, surfaced lazily.
+For a per-decision `code-drift` finding, use `record_id` and `record_type` ("decision")
+to identify the subject. `path` is its physical source: several records may share one shard.
+Never infer identity from the shard, capture commit or human-readable `detail`. Global notes
+(commit stamping unavailable, Git unavailable, check skipped) have null record fields; they
+are not records to triage. `detail` names changed files or why a prior check no longer applies.
+Original `provenance.commit` stays history. Doctor is a pure read.
+
+The SessionStart count and `[drifted]` tags in detailed formatted `get_task_context`,
+`query_decisions` and `drill_down` output use the lazily refreshed drift cache. Budgets can
+omit records, and compact related-record lines do not all show the marker. Raw
+`retrieve_decisions` JSON has no drift field or tag in either storage layout; use doctor
+for the explicit current list.
 
 Triage in batches — a 35-record queue does not need 35 interrupts. Group verdicts and
 **put every question to the human into one message** (same discipline as
@@ -60,7 +68,10 @@ Triage in batches — a 35-record queue does not need 35 interrupts. Group verdi
      ```
 
      Include every current checkable concrete anchor file and each additional dependency
-     actually inspected. The files must be tracked regular files and clean relative to
+     actually inspected. If `missing_required_files` is returned, inspect the local configured
+     Store: `bindings_for_record(decision_id)`, then `get_entity(binding.entity_id).descriptor`
+     for each binding. Include every current checkable concrete file, not just the files
+     named as changed by doctor. The files must be tracked regular files and clean relative to
      that HEAD; unrelated dirt is allowed. The target must be open, commit-stamped and
      concretely anchored. With no Git HEAD, dirty inspected files, incomplete scope or an
      ineligible target, report the judgment and why no check was recorded; retain the
@@ -88,10 +99,14 @@ Triage in batches — a 35-record queue does not need 35 interrupts. Group verdi
      The direct `supersede_decision` path is legitimate only when the human has dictated
      or approved the successor text in this conversation. For an invalidated *fact*,
      the same split applies with `supersede_fact`.
-   - **(c) The anchored code is gone entirely** — deleted, not changed. That's binding
-     damage, not content drift: run `sidegraph:heal-anchors` (its stale-decisions tree
-     already covers restore-the-name vs. supersede vs. recommend-a-drop). Never drop a
-     record yourself — a drop is a ratify-gate action for a human.
+   - **(c) The anchored code is gone entirely** — deleted, not changed. Run
+     `sidegraph:heal-anchors` to distinguish a rename from a lost subject. For accepted
+     decisions, propose a meaningful supersession that explains the obsolete scope and
+     anchors what remains true. `ratify(drop=...)` only rejects proposed decisions/facts;
+     it cannot retire an accepted decision. If there is no meaningful successor, report
+     that limitation to the human and retain history; do not invent an empty successor
+     or edit status/valid_to in canonical files. Accepted domains have their own supported
+     drop path; do not generalize that exception to decisions.
 
 ## Calibrate the effort
 
@@ -115,8 +130,9 @@ of the wave's own definition of done, not a later triage's discovery.
 
 End with one summary the human can act on in a single pass: checked (decision id, returned check id, revision, inspected scope and cache-clear outcome), still true but
 check unavailable (id and reason), proposed supersessions (old id → new draft title, awaiting
-`sidegraph:ratify-decisions`), handed to heal-anchors (ids), and recommended drops
-(ids + reason — recommendation only, the human runs `ratify(drop=[...])`).
+`sidegraph:ratify-decisions`), handed to heal-anchors (ids), and unresolved obsolete subjects
+(ids + current status + reason). Recommend `ratify(drop=[...])` only for proposed
+decisions/facts, or domains whose drop path explicitly permits it.
 
 ## See also
 

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

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

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