sidegraph 0.17.1__tar.gz → 0.17.2__tar.gz

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

@@ -7,6 +7,31 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [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.2}/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.2) — 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.17.1
+Version: 0.17.2
 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.2}/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.2}/docs/reference/cli.md

@@ -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.2}/docs/reference/hooks.md

@@ -832,6 +832,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.2}/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.2}/package.json

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

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

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

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

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

{sidegraph-0.17.1 → sidegraph-0.17.2}/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.2}/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.2}/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.2}/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.2}/pyproject.toml

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

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

{sidegraph-0.17.1 → sidegraph-0.17.2}/src/sidegraph/cli.py

@@ -2894,7 +2894,13 @@ def doctor_main(argv: list[str] | None = None) -> int:
                         {"code": v.code, "path": v.path, "detail": v.detail} for v in violations
                     ],
                     "findings": [
-                        {"code": f.code, "path": f.path, "detail": f.detail}
+                        {
+                            "code": f.code,
+                            "path": f.path,
+                            "detail": f.detail,
+                            "record_id": f.record_id,
+                            "record_type": f.record_type,
+                        }
                         for f in report.findings
                     ],
                     "skipped": skipped + (["graph"] if reader is None else []),
@@ -2906,7 +2912,8 @@ def doctor_main(argv: list[str] | None = None) -> int:
         for v in violations:
             print(f"{v.code}  {v.path}  {v.detail}")
         for f in report.findings:
-            print(f"{f.code}  {f.path}  {f.detail}")
+            subject = f"  {f.record_type}:{f.record_id}" if f.record_id is not None else ""
+            print(f"{f.code}{subject}  {f.path}  {f.detail}")
         stamp_note = None if index_usable else index_stamp_note(args.db)
         if stamp_note is not None:
             print(f"index checks withheld: {stamp_note}")