sidegraph 0.14.0__tar.gz → 0.15.0__tar.gz

{sidegraph-0.14.0 → sidegraph-0.15.0}/.github/workflows/ci.yml

@@ -193,7 +193,9 @@ jobs:
             tests/test_verify_git_stdin.py tests/test_seed_paths_portable.py `
             tests/test_repo_relative_paths_portable.py `
             tests/test_command_windows.py `
-            tests/test_hook_payload_encoding.py `
+            tests/test_hook_payload_encoding.py tests/test_hook_failure_diagnostics.py `
+            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 `
             $privateTests `
             tests/test_installed_wheel_smoke.py

{sidegraph-0.14.0 → sidegraph-0.15.0}/CHANGELOG.md

@@ -7,6 +7,45 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.15.0] — 2026-10-18
+
+### Added
+
+- `sidegraph-export-adr` previews and explicitly writes profile-driven ADR sets with stable
+  identity, status/history links, full supporting evidence and preserved human notes.
+  Import and bootstrap withhold generated projections instead of duplicating memory.
+
+- Explicit `record_drift_check` inspections preserve decision capture history and clear
+  only the checked advisory. Changed inspected files or anchor scope re-arm review;
+  immutable auxiliary evidence is linted without changing the shared store digest.
+
+- Local delivery evidence distinguishes prepared answers, rendered record placements and
+  anchor relations, with record status at emission and explicit unknown/empty/error outcomes.
+  Stats keeps MCP and automatic hooks separate. Optional bounded index-only writes cannot
+  block delivery and retain no task/response text or hashes.
+- Automatic point-of-read context and appended task briefs can include eligible facts with
+  their complete statement, source and id, using existing record caps and trust rules.
+  Fact lines over 512 characters are withheld whole; full facts remain available through
+  `list_facts`. SubagentStart's awareness counts still cover decisions only.
+
+### Fixed
+
+- Automatic file-read context and appended agent briefs replace later identical record bodies
+  within one answer with explicit references. First copies, per-file applicability, trust,
+  selection limits and journal placements stay intact; no state crosses calls or agents.
+- Explicit file lookups return eligible decisions and facts by their exact durable file
+  binding when an available graph lacks the file, marked as file applicability with
+  unverified symbol anchors. Remaining-record pointers name both decision and fact listings.
+- Failed lifecycle hooks emit at most one content-free diagnostic line on stderr while
+  preserving their existing fail-open output. Missing indexes and deliberate format
+  refusals remain quiet; diagnostics do not depend on the index or create a log file.
+
+### Known limitations
+
+- Selection still uses file/entity/domain context and can include off-task records.
+  Task-query ranking remains future work; this release makes no measured relevance or
+  time-saving claim. See the [0.15 update and case guide](https://github.com/SantyagoSeaman/sidegraph/blob/v0.15.0/docs/guides/using-0.15.md).
+
 ## [0.14.0] — 2026-10-16
 
 ### Graphify 0.9.90

{sidegraph-0.14.0 → sidegraph-0.15.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.14.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.15.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.14.0 → sidegraph-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.14.0
+Version: 0.15.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
@@ -397,6 +397,9 @@ Contributions are reviewed here and carried over, with attribution, before the n
 
 ## Documentation
 
+[Export and maintain ADRs](docs/guides/adr-export.md) from the available decision store,
+with a preview by default and explicit writes.
+
 [Getting started](docs/getting-started/installation.md) ·
 [Concepts](docs/concepts/decision-memory.md) ·
 [Guides](docs/guides/capturing-decisions.md) ·

{sidegraph-0.14.0 → sidegraph-0.15.0}/README.md

@@ -367,6 +367,9 @@ Contributions are reviewed here and carried over, with attribution, before the n
 
 ## Documentation
 
+[Export and maintain ADRs](docs/guides/adr-export.md) from the available decision store,
+with a preview by default and explicit writes.
+
 [Getting started](docs/getting-started/installation.md) ·
 [Concepts](docs/concepts/decision-memory.md) ·
 [Guides](docs/guides/capturing-decisions.md) ·

{sidegraph-0.14.0 → sidegraph-0.15.0}/SECURITY.md

@@ -51,6 +51,17 @@ provider according to your repository's data policy. The runtime data boundary i
   separate Graphify CLI against the LLM provider you configure. Review that provider's
   data policy before using the pass on private documents.
 
+## Scoped inspection history
+
+`record_drift_check` writes immutable `.sidegraph/verifications/<id>.json` files intended
+for source control. They contain a redacted rationale, decision id, UTC time, inspected
+revision, repository-relative paths, Git blob ids and modes, a subject digest and agent
+provenance. Author/session are currently unknown. There is no source body or transcript
+in these files. Paths and Git content addresses are durable repository metadata; review
+the rationale and paths before sharing a store. Redaction is best-effort and cannot
+remove sensitive semantics from ordinary prose. These assertions can be wrong; they are
+neither truth certificates nor ratification. Older runtimes ignore and preserve them.
+
 ## Secret hygiene
 
 Text captured into decisions passes a redaction step before it is stored (API keys,

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/concepts/data-model.md

@@ -286,3 +286,41 @@ The `Initiative` model below is a separate low-level persisted record supported
 | `name` | str | The label as written at capture — a branch name or a short phrase. |
 | `description` | str \| `null` | Optional one-liner; usually absent for branch-derived initiatives. |
 | `tags` | list[str] | Stored strings on the low-level record; `upsert_initiative` does not slugify them or create `tag:*` entities. |
+
+## `DriftCheck` — attributed auxiliary inspection
+
+An optional immutable file under `.sidegraph/verifications/` records an explicit agent
+judgment that an existing decision still holds. It preserves the decision and original
+capture provenance; it never ratifies a proposal or proves semantic truth. It is outside
+the shared canonical digest/index record tables. See
+[scoped checks](../reference/store-format.md#scoped-drift-checks) and
+[`record_drift_check`](../reference/mcp-tools.md#record_drift_check).
+
+| Field | Type | Meaning |
+|---|---|---|
+| `schema_version` | literal `1` | Version of the auxiliary assertion and fixed subject-digest definition; independent of the store format version. |
+| `id` | ULID | Generated check identity, also its immutable filename. Highest generated id is the deterministic per-decision selection rule, not causal ordering. |
+| `decision_id` | str | Existing decision id; terminal or archived decisions remain valid history references. |
+| `checked_at` | aware datetime | UTC time at which the assertion was recorded. |
+| `checked_commit` | str | Full inspected Git HEAD object id, retained as provenance even after squash/clone removes the object locally. |
+| `provenance` | `Provenance` | Source `agent`, commit equals checked revision; author/session currently unknown. |
+| `rationale` | str | Nonblank explanation, redacted before validation; at most 4000 characters. |
+| `required_files` | list[str] | Exact current required anchor-file set, separate from optional inspected dependencies. |
+| `checked_files` | list[`CheckedCodeFile`] | Explicit inspected regular-file snapshots, covering every required file; 1–256 unique safe paths. |
+| `subject_digest` | str | SHA-256 of fixed immutable decision/provenance fields and durable leaf descriptors; excludes lifecycle and volatile mapping/status fields. |
+
+Changed inspected files/modes or required scope re-arm review. A matching snapshot after
+an unrelated commit remains covered. A mistaken semantic assertion cannot be detected
+from these hashes; a genuine successor corrects the decision and preserves the check as
+history. Optional comparison failure has the bounded behavior described in store-format.
+
+## `CheckedCodeFile` — inspected Git tree entry
+
+Nested in `DriftCheck`; this stores repository metadata, never source bodies or engine
+mappings. The total checked-path budget is 16384 UTF-8 bytes.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | str | Safe repository-relative forward-slash path, at most 1024 UTF-8 bytes. |
+| `blob_id` | str | Full Git content address of the inspected file. |
+| `mode` | `100644` \| `100755` | Regular-file Git mode; mode changes participate in applicability. |

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/concepts/retrieval.md

@@ -353,6 +353,17 @@ reported separately, by comparing the graph's build commit with `HEAD` (see
 [the Graphify integration](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks)), and
 only a rebuild fixes it.
 
+### File applicability outside the graph
+
+When an available graph does not contain an explicitly requested file, the memory read
+also checks exact durable descriptor paths. Eligible decisions and facts can then arrive as
+`[file-bound]`: declared applicability to that file, with symbol anchors the graph cannot
+verify. This reads no neighboring path as an exact match and changes no anchor or binding.
+Ordinary verified seed routes take precedence over the marker. Named-entity requests,
+ambiguous/directory guesses and graph-present orphan handling keep their existing rules;
+with no graph reader at all, this fallback is unavailable. The file still appears in the
+not-in-graph diagnostic, and proposal policy, history, mistakes-first and budgets still apply.
+
 ### Rendering
 
 `TaskContext.render()` emits, in order: **Known mistakes & gotchas**, **Decisions** (with any

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/getting-started/bootstrap.md

@@ -82,6 +82,7 @@ warning code is rendered beside the consequence of accepting it anyway:
 
 | Warning code | Consequence of accepting |
 | --- | --- |
+| `generated-projection` | generated ADRs are projections of existing memory, not new capture evidence |
 | `missing-choice` | the document states no decision; the record would carry only context |
 | `missing-rejected-alternatives` | no rejected alternatives were found; the most valuable field stays empty |
 | `unresolved-anchor` | the anchor does not resolve; the record would not surface for that code |
@@ -112,7 +113,8 @@ stored. There is no default accept-all action.
 Bootstrap reports four outcomes independently: store, anchors, host integration, and
 production-path proof. Proof selects an accepted, currently valid decision with a resolved
 tier-2 anchor and calls the same `get_task_context` production retrieval path used by agent
-sessions. Optional domain suggestions do not block that proof.
+sessions. File-bound applicability remains useful retrieval, but does not satisfy this
+current-graph anchor proof. Optional domain suggestions do not block that proof.
 
 | Host | MCP | SessionStart | Stop | Read/Grep PreToolUse | Completion label |
 | --- | --- | --- | --- | --- | --- |

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/getting-started/installation.md

@@ -274,7 +274,7 @@ setup, scripted/CI use, and the two deliberately human-run jobs (`sidegraph-impo
 | `sidegraph-stop` | `Stop` hook — nudges the agent to distill decisions. |
 | `sidegraph-pre-tool-use` | `PreToolUse` hook — hands the agent the records anchored to a file when it reads or edits it (`Read`, `Grep`, `Edit`, `Write`, and `sed`/`grep`/`rg`/`cat` in Bash). |
 | `sidegraph-subagent-start` | `SubagentStart` hook — tells a starting subagent that decision memory exists and how to ask it. |
-| `sidegraph-bootstrap` | Guided CLI — scan one of six supported ADR/spec profiles, preview and review candidates, write only after confirmation, verify anchors/host integration, and prove production retrieval. |
+| `sidegraph-bootstrap` | Guided CLI — scan one of seven supported ADR/spec profiles, preview and review candidates, write only after confirmation, verify anchors/host integration, and prove production retrieval. |
 | `sidegraph-init` | CLI — bootstrap `.sidegraph/` in a repo: create the store, check for the graph, ask (in a terminal) whether to install the git hook that keeps the graph fresh (`--hooks`, `--no-hooks`, `--remove-hooks`), print the plugin install path (and the no-plugin `claude mcp add` alternative). |
 | `sidegraph-ratify` | CLI — review/accept/drop proposed decisions, facts, and domains. |
 | `sidegraph-sync` | CLI — re-anchor the store after a Graphify rebuild. |
@@ -285,6 +285,7 @@ setup, scripted/CI use, and the two deliberately human-run jobs (`sidegraph-impo
 | `sidegraph-verify` | CLI — lint the store's canonical files against its write-path invariants (schema, validity windows, referential integrity, ULID uniqueness); `--against <git-ref>` additionally checks that every store file changed vs that ref was mutated legally (CI mode). |
 | `sidegraph-doctor` | CLI — one-stop store health: composes `sidegraph-verify`'s strict lint with an advisory curation pass (stale proposals, dangling/degraded/orphaned records, never-surfaced decisions); `--check` also fails on advisory findings. |
 | `sidegraph-viz` | CLI — render an interactive HTML/JSON view of decisions, facts, entities, anchor status, supersession, and evidence links. |
+| `sidegraph-export-adr` | CLI — preview ADR projections and diffs from canonical memory; explicitly write managed documents with preserved human notes. See [ADR export](../guides/adr-export.md). |
 | `sidegraph-export-okf` | CLI — project the store into a deterministic [Open Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle any OKF-aware tool can read; strictly one-way, the store stays the source of truth. |
 | `sidegraph-stats` | CLI — one screen of local usage statistics from the gitignored index (how often memory was asked for, how much of the code worked on has memory anchored to it, what the store holds, anchor health); read-only, never creates the index, `--json` for the same report as data. Reachable in a session as `/sidegraph:stats`. |
 | `sidegraph-prepare-commit-msg` | `prepare-commit-msg` git hook — comments candidate `Sidegraph-Decision:` trailers into the commit message template; fail-open with bounded git/SQLite stages. See [`reference/git-bindings.md`](../reference/git-bindings.md). |

sidegraph-0.15.0/docs/guides/adr-export.md

@@ -0,0 +1,134 @@
+# Export and maintain ADRs
+
+`sidegraph-export-adr` makes stored architectural decisions readable as Markdown ADRs.
+It projects the memory you have; it does not infer a complete architecture from the code.
+Preview first, then run the same command with `--write` after reviewing its diff:
+
+```bash
+uv run sidegraph-export-adr --db .sidegraph --out docs/adr
+uv run sidegraph-export-adr --db .sidegraph --out docs/adr --write
+```
+
+The default is a read-only preview. It creates no directories or files. Neither preview
+nor write opens a `Store`, migrates it, updates its index, or writes `graph.json`. The source
+must already be a valid canonical store; migrate legacy databases explicitly with
+`sidegraph-init` first. Exported text can contain private reasoning: review the diff before
+putting it in tracked or shared documentation.
+
+## What is exported
+
+Each accepted, superseded or deprecated `adr` or `constraint` becomes a document. Proposed
+and rejected records stay out. Acceptance status is the trust boundary; legacy accepted
+records need not have a ratifier-name stamp. Context, choice, rejected alternatives and
+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
+explicit accepted domain bindings, otherwise under Unassigned. These are membership
+intent and durable descriptors, not claims of current graph resolution.
+
+Document-derived records identify their original source and remain orientation to check
+against the artifact and current code. Lessons and gotchas are not turned into ADRs or
+inferred pitfalls just because they share an anchor.
+
+## Format and filenames
+
+The flow profile supplies output data; `generic-adr` uses Nygard-style sections and `madr`
+uses MADR-style headings. Existing flow readers retain their dialects and ingest globs.
+
+| Profile | Default output below the store's parent |
+|---|---|
+| `generic-adr`, `madr` | `docs/adr` |
+| `superpowers` | `docs/superpowers/adr` |
+| `genkovich-sdd` | `docs/features/sidegraph/adr` |
+| `spec-kit` | `specs/sidegraph/adr` |
+| `bmad` | `_bmad-output/sidegraph-adr` |
+| `openspec` | `openspec/adr` |
+
+These are separate ADR projections, not replacements for live flow artifacts. Creating a
+profile's directory can affect structural bootstrap detection (`docs/adr`,
+`docs/superpowers` or `docs/features`). Detection does not mean import candidates exist.
+MADR has no detection marker. Use `--out` to choose a different directory.
+
+```bash
+uv run sidegraph-export-adr --profile madr --out docs/adr
+uv run sidegraph-export-adr --filename '{number:04d}-{id}.md'
+uv run sidegraph-export-adr --template adr-template.txt --out docs/adr
+```
+
+Default filenames contain the stable record ID. Numbered patterns append new numbers;
+existing generated records keep their number and filename when older IDs arrive or the
+pattern changes. Patterns permit only `{id}` and `{number}` with an optional decimal width
+of one to eight digits, must contain the ID, and produce a flat portable `.md` basename.
+They cannot target `index.md`, a device name, or a path outside the output directory.
+
+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.
+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.
+
+## Keep human edits
+
+A generated file has a checksummed region followed by `Local notes`. Add human commentary
+after that region; updates preserve those trailing bytes. If an update writes a file whose
+last line lacks a newline, it appends the repository-required final newline.
+
+Changing generated prose, its ID or its number produces a conflict. The complete edited
+file survives; the command does not replace it even with `--write`. Move additions to
+Local notes, review the source record and the diff, then resolve the generated region
+explicitly. There is no force-overwrite or fuzzy title-matching mode.
+
+Checksums bind protocol version, ID, number and LF-normalized body. CRLF/BOM checkouts are
+accepted, and equivalent generated content remains a no-op. This detects accidental edits;
+it is not authentication against someone deliberately recomputing the checksum. Authored
+opening/closing marker lines are escaped to prevent nested ownership regions. In a code
+fence that escaping is visible as `<`; the canonical source keeps the original text.
+
+An unmanaged destination, duplicate generated ID/number, or case-insensitive filename
+collision is a conflict. A human filename prefix of one to eight digits followed by `-`
+or `_` reserves a sequence number; longer timestamps and unseparated digits do not.
+Numbers stop at 99999999 with an explicit error. A later human/generated number overlap
+warns and keeps both files and existing numbers unchanged. Exact destination collisions
+still refuse the complete plan.
+An imported human ADR already in the chosen directory is linked rather than copied.
+Generated files outside the current export population remain for manual review; they are
+never deleted or listed as current. Symlinked output components and nonregular targets are
+refused, as is output inside the source store.
+
+A plan containing a conflict applies no files. Writes recheck exact before bytes, create
+new files exclusively and replace existing files atomically while retaining their mode.
+The batch is not a transaction: an I/O failure or later concurrent edit can leave earlier
+files applied, or a partial new file. The report marks an incomplete attempted write;
+review the remaining diff before retrying. No protection against an adversarial ancestor
+replacement or a simultaneous source/index-mode change is claimed.
+
+## Drift and round trips
+
+Code drift is advisory output, not rewritten ADR prose. A completed capture-to-HEAD check
+can report a changed anchored file; it does not prove semantic invalidity. Missing stamps,
+uncomputed binding statuses or failed checks remain unknown. Closed/archived decisions are
+not applicable. Uncommitted source edits are outside this existing drift check.
+
+The command reuses the doctor's bounded scan for an available rollback index. A WAL index
+is left unopened because even SQLite read-only connections can create auxiliary WAL/SHM
+files; drift is then unknown. The format check follows SQLite's
+[file-header contract](https://www.sqlite.org/fileformat2.html#file_format_version_numbers).
+This preserves source files rather than claiming a clean result from an unavailable check.
+
+Generated ADRs are **projections, not new capture evidence**. Both document import and
+bootstrap recognize reserved projection claims and skip them, including changed content,
+foreign IDs and unknown marker versions. Fenced, indented and inline examples are ordinary
+human documents. Import reports `skipped_generated_adr`; bootstrap shows
+`generated-projection`. To transfer memory between repositories, use the canonical store,
+not generated ADRs. This command is separate from the one-way OKF bundle export.
+
+`--json` gives planned changes/diffs, advisories, warnings, counts and write-completion
+flags. Exit 0 means successful preview/write, including a valid empty store's empty index;
+2 means invalid input/store, a conflict or operational failure. Review partial-write flags
+before assuming a failed write applied nothing.

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/guides/ci-cd-maintenance.md

@@ -403,3 +403,8 @@ drafts. Proposed content stays below accepted memory and may be hidden by regula
   `add_anchors`'s MCP shapes.
 - [`guides/team-workflow.md`](team-workflow.md) — committing `.sidegraph/` as an ordinary
   part of the repo, outside of CI.
+
+Scoped drift checks are committed auxiliary history under `.sidegraph/verifications/`.
+Use the current `sidegraph-verify` for their schema/reference checks and write-once
+`--against` enforcement; older verifiers ignore them. CI should not create semantic
+inspection assertions automatically merely to obtain fewer drift warnings.

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/guides/retrieval-in-sessions.md

@@ -109,8 +109,14 @@ no query. All three read the store's index directly, so each costs a few tens of
   carries no records: the subagent asks `get_task_context` for the files it works on.
   `SIDEGRAPH_SUBAGENT_BRIEF=off` stops it.
 
-The first two channels deliver decisions only (facts reach the agent through `get_task_context`)
-and exist on Claude Code only. `SubagentStart` runs on Claude Code and on
+The first two channels can deliver eligible facts as well as decisions, within the same record
+caps. Facts keep their whole statement and source; fact lines longer than 512 characters are
+withheld whole and remain available through `list_facts`. Within one answer or appended brief,
+a later identical record may say `See above` with its kind, trust marker and ID under each
+applicable file. The first copy remains complete for that surface. No state crosses calls or
+agents, and saved characters do not buy extra records. Existing once-per-file claims remain;
+use `get_task_context` for fuller decision context and `list_facts` for whole facts.
+These two channels exist on Claude Code only. `SubagentStart` runs on Claude Code and on
 Codex. The wiring is in the [hooks reference](../reference/hooks.md#sidegraph-pre-tool-use).
 
 ## Asking task-scoped questions so `get_task_context` fires with the right seeds
@@ -139,6 +145,15 @@ Vague, non-task questions ("what does this project do") don't give the tool anyt
 on — be concrete about the file or symbol so the retrieval has something to resolve. A call with
 no seeds at all says so, and names the domains you can drill into.
 
+When an available graph does not contain an explicitly requested file, the memory read
+also checks exact durable descriptor paths. Eligible decisions and facts can then arrive as
+`[file-bound]`: declared applicability to that file, with symbol anchors the graph cannot
+verify. This reads no neighboring path as an exact match and changes no anchor or binding.
+Ordinary verified seed routes take precedence over the marker. Named-entity requests,
+ambiguous/directory guesses and graph-present orphan handling keep their existing rules;
+with no graph reader at all, this fallback is unavailable. The file still appears in the
+not-in-graph diagnostic, and proposal policy, history, mistakes-first and budgets still apply.
+
 ## Reading the output blocks
 
 `get_task_context` renders up to six Markdown sections, in this order, each one skipped
@@ -271,3 +286,13 @@ The SessionStart pending-ratification counter is exempt from both: it reports th
 size **and the oldest item's age** even when nothing in it renders, because a queue you
 cannot see is exactly the one that rots. `sidegraph-doctor` adds the latency counterpart
 (`time-to-ratify`) once records carry the ratifier stamp.
+
+## When a drift warning remains after inspection
+
+`[drifted]` requests a content review; a moved file alone does not invalidate a decision.
+Use `sidegraph:triage-drift` to read the claim and current code. If the claim still holds,
+`record_drift_check` can append a justified inspection of the current clean committed
+files without changing the decision. If it no longer holds, propose a real successor.
+The [tool reference](../reference/mcp-tools.md#record_drift_check) describes refusal cases
+and coverage. Changed inspected files or scope re-arm the warning; unrelated commits do
+not. The check is an attributed assertion and can be wrong.

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/guides/troubleshooting.md

@@ -70,7 +70,7 @@ established by core/installed-wheel CI; the native Windows route is verified wit
 |---|---|---|---|---|
 | `store-unreadable` | broken | The store cannot be opened, so memory is off for the session | session notice and line | `sidegraph-verify`, or remove the damaged index |
 | `pending-ratification` | advisory | Proposals await a human's verdict | session line; a notice once the oldest is 30 days old | `sidegraph-ratify` |
-| `code-drift` | advisory | Records are anchored to code that changed after their capture | session line | `sidegraph-doctor` |
+| `code-drift` | advisory | Records need content review after code or check-scope changes | session line | `sidegraph-doctor` |
 | `graph-borrowed` | advisory | A linked worktree reads the main checkout's graph | session line | none needed |
 | `graph-stale` | degraded | The graph was built at a commit `HEAD` has moved past | session line and notice, doctor, stats | `graphify update .` |
 | `stray-store` | degraded | A subdirectory launch created a second, empty store | session line and notice | remove the empty store |
@@ -127,9 +127,10 @@ notice.
 
 ### code-drift
 
-Records whose anchored files changed after their capture. The line says how many. It is the
-agent's work to supersede the ones that no longer hold, so there is no notice. `sidegraph-doctor`
-lists them as `code-drift` findings, and the `sidegraph:triage-drift` skill walks them.
+Records needing content review after code changed or a prior scoped check stopped applying.
+The line says how many. Inspect current code: record an explicit `record_drift_check` if the
+claim still holds, or propose a real successor if it does not. There is no user notice.
+`sidegraph-doctor` lists them as `code-drift` findings, and the `sidegraph:triage-drift` skill walks them.
 `SIDEGRAPH_DRIFT_NUDGE=off` silences the line.
 
 ### graph-borrowed

sidegraph-0.15.0/docs/guides/using-0.15.md

@@ -0,0 +1,42 @@
+# Using Sidegraph 0.15
+
+0.15 adds ADR export and maintenance, auditable delivery statistics, explicit drift
+inspections, eligible fact delivery, and fixes for repeated automatic context and exact-file
+memory outside the graph. File/entity/domain selection still applies; task-query ranking
+is future work. Release changes are listed in the [changelog](../../CHANGELOG.md#0150--2026-10-18).
+
+## Update
+
+Keep a backup or commit of your authored `.sidegraph/` files. For a CLI installation:
+
+```bash
+uv tool install --upgrade sidegraph==0.15.0
+```
+
+For plugins, update the marketplace/package and installed plugin using your
+[host's installation instructions](../getting-started/installation.md), then start a new
+session so the MCP server and hooks use the new release. Public plugins intentionally
+follow `main`; an explicit RC pin stays pinned until you change it.
+
+## Collect cases during the first week
+
+Use ordinary working tasks. Before a task-specific Sidegraph lookup, save the task brief,
+expected files/entities and any constraints or facts you already expect to help. Unknown
+expectations are valid. After lookup, retain the exact tool arguments and full response
+locally, then note what the agent actually did with the memory.
+
+```text
+Date, project, host, Sidegraph version:
+Task and intended result (before lookup):
+Files/entities and known constraints (before lookup):
+Tool arguments and response (saved locally):
+Useful / off-task / missing records, with IDs if known:
+Observed action influenced by memory, or UNKNOWN:
+```
+
+A few ordinary cases across the week are enough for an initial diagnosis. Include cases
+where memory did not help. Keep real records and responses private; redact credentials
+before sharing a report and exclude whole dialogue exports. Record an observed action
+rather than estimating time saved. Inspected cases can inform private or synthetic regression examples; real records and
+responses stay out of repositories. An inspected case cannot serve as an unseen test for
+a later ranking change.

{sidegraph-0.14.0 → sidegraph-0.15.0}/docs/reference/cli.md

@@ -1,11 +1,12 @@
 # CLI reference
 
-20 console scripts are registered in `pyproject.toml` (`[project.scripts]`): fifteen
+21 console scripts are registered in `pyproject.toml` (`[project.scripts]`): sixteen
 commands documented on this page — fourteen in [`src/sidegraph/cli.py`](../../src/sidegraph/cli.py)
 (including `sidegraph-prepare-commit-msg`, which doubles as a git hook — see
 [`reference/git-bindings.md`](git-bindings.md) for its installation and mechanism) and the
 guided `sidegraph-bootstrap` in
-[`src/sidegraph/bootstrap/cli.py`](../../src/sidegraph/bootstrap/cli.py) — plus the MCP server
+[`src/sidegraph/bootstrap/cli.py`](../../src/sidegraph/bootstrap/cli.py) and ADR export in
+[`src/sidegraph/adr_cli.py`](../../src/sidegraph/adr_cli.py) — plus the MCP server
 (`sidegraph-mcp`) and the four hook entry points (`sidegraph-session-start`,
 `sidegraph-stop`, `sidegraph-pre-tool-use`, `sidegraph-subagent-start`; see
 [`reference/hooks.md`](hooks.md)).
@@ -1226,6 +1227,7 @@ plain-text line):
 | `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`) |
 | `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) |
@@ -1233,7 +1235,7 @@ plain-text line):
 | `filename-id-mismatch` | snapshot | a hot record file's name doesn't match its own internal id |
 | `unsafe-record-id` | snapshot | a record's id is not a safe filename (a single path segment, at most 128 characters, starting with a letter or digit), or is not a string; also a `bindings/` file or hot record file whose name is unsafe, and an `archive/*.jsonl` line whose id is missing, not a string or unsafe. The store's reload skips such a file, and its startup warning points here. A file with an unsafe name gets this code whether or not its content parses; a file with an unsafe name or an unsafe id gets no other snapshot finding (no `filename-id-mismatch`, `duplicate-ulid` or `parse-error`) |
 | `symlinked-store-entry` | snapshot | a store-owned directory or file inside the store is a symlink, live or dangling (one violation per entry); `Store()` refuses to open such a store, so `sidegraph-verify` and `sidegraph-doctor` report the links and stop: no record is linted, no reference checked, no `--against` diff run and no advisory check made until the links are removed (an `--against` ref that does not resolve, or a store outside git, is checked first and still exits `1` without reporting the links) (the text output says so in one line; `--json` carries no marker), see [`reference/store-format.md`](store-format.md#layout-file-per-record-json-plus-a-derived-local-index) |
-| `illegal-field-change` | transition | an immutable field changed between `GIT_REF` and the working tree (the detail names the field); also covers immutable raw keys lost during hot-to-archive transfer, or a modified already-published archive segment (write-once) |
+| `illegal-field-change` | transition | an immutable field changed between `GIT_REF` and the working tree (the detail names the field); also covers immutable raw keys lost during hot-to-archive transfer, or a modified already-published archive segment or auxiliary verification (write-once) |
 | `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) |
@@ -1281,6 +1283,9 @@ which methods):
 - **Initiatives:** no append-only guard in `store.py` at all (`Store.upsert_initiative` is a
   bare, unconditional upsert) — only a *deletion* is flagged (`illegal-deletion`); no
   field-level check runs for initiatives.
+- **Auxiliary verifications** (`verifications/*.json`): write-once, including formatting;
+  additions are schema/reference-checked by the snapshot layer, every later modification
+  or deletion is illegal. Older verifier versions ignore this directory.
 - **Archive segments** (`archive/*.jsonl`): write-once — a brand-new segment (git status
   `A`) is legal; any modification or deletion of an already-published one is always
   illegal.
@@ -1383,7 +1388,7 @@ plain-text line):
 | `stale-proposal` | a proposed decision/domain whose ULID timestamp is strictly older than `--stale-days` |
 | `unreferenced-entity` | a hot entity no committed anchor set references (structural `domain:*`/`community:*` entities are exempt) |
 | `expired-open-validity` | a decision's `valid_to` is strictly past but its status is still open (`proposed`/`accepted`) |
-| `code-drift` | an open (`proposed`/`accepted`) decision's anchored file(s) changed since the commit its `provenance.commit` was captured at; when binding statuses are uncomputed or unavailable, excludes committed deletions and says "binding status unknown"; also carries the "N record(s) predate commit stamping — not checkable" and git-unavailable notes, in place, when either applies |
+| `code-drift` | an open (`proposed`/`accepted`) decision's anchored file(s) changed since capture, or an earlier scoped check no longer applies; `record_drift_check` can record an explicit current inspection without rewriting the decision (MCP only); when binding statuses are uncomputed or unavailable, excludes committed deletions and says "binding status unknown"; also carries the "N record(s) predate commit stamping — not checkable" and git-unavailable notes, in place, when either applies |
 | `never-surfaced` | an accepted decision has `0` shows against `N > 0` queries on its anchored file(s) — anchored where people repeatedly work, never once rendered or injected by a hook |
 | `stale-instructions` | an auto-injected agent-instructions file beside the store (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`) still carries the distinctive wording of a **superseded** decision — that file reaches the agent at turn zero, before retrieval, so an abandoned rule surviving there outranks the store's correction by default. Verbatim-ish match on normalized text with length/word floors; superseded records only; no git call. Advisory: it reports a quotation, not a proven contradiction — the file may be narrating history |
 | `unratified-accept` | an **accepted** record whose provenance says `agent` and which carries no ratifier stamp — the signature `SIDEGRAPH_AUTO_ACCEPT=on` leaves in a shared store (one environment's setting bypassing the ratification gate for everyone). Scoped to records created at/after the EARLIER of the store's earliest ratifier stamp and its creation marker (`.sidegraph/stamping_live_since`, written once when a store is genuinely new — never backfilled onto an existing one), so a store predating both reports nothing rather than everything; a store that has never ratified anything but was created by a marker-writing version is still in scope from its own creation, closing the blind window an unratified store would otherwise sit in forever. A stamped record — including one stamped `auto:<policy>` by an auto-ratification policy — and a human-sourced one are never flagged. A **supersession successor** (`supersedes` set — `supersede_decision`/`supersede_fact`) is never flagged either: reversal has no ratification queue to bypass and lands accepted immediately by design, so it reproduces the signature with no relation to the env var this check hunts. Narrowed exception: a `supersedes`-bearing record IS still flagged if it carries a `layer`, a `provenance.ref`, or a tier-0 `tag:`/`initiative:` binding absent from its predecessor — neither `supersede_decision` nor `supersede_fact` can produce any of the three, so one present proves the `propose_decisions`/auto-accept path wrote it. (The fact half is defensive only: `supersede_fact` always stamps `source="human"`, so a fact successor never reaches this agent-sourced check, and no draft shape carries `supersedes` on a fact.) Only a MINIMAL superseding draft (none of the three) is indistinguishable from a legitimate successor by the record's own fields, and stays excluded — a known, accepted, narrower trade-off than treating every supersession alike. Advisory: the signature is not proof — verify before concluding |
@@ -1517,6 +1522,45 @@ so startup may migrate supported legacy data or rebuild `index.db`. Binding stat
 Exit code 0 on success (a store with problems still exits 0 — the problems are the output), 2
 on an operational error (uninitialized store or unwritable output path).
 
+## `sidegraph-export-adr`
+
+```bash
+uv run sidegraph-export-adr --db .sidegraph --out docs/adr          # preview only
+uv run sidegraph-export-adr --db .sidegraph --out docs/adr --write  # explicit application
+uv run sidegraph-export-adr --profile madr --json
+```
+
+Generate and maintain record-derived ADRs with a unified diff by default. Accepted,
+superseded and deprecated ADR/constraint decisions become documents; proposed/rejected
+records stay out. A fixed footer retains complete accepted, unclosed explicit evidence,
+source pointers, status, history, anchors and domain intent. No inferred architectural
+coverage, automatic prose synthesis or retrieval policy change.
+
+| Flag | Behavior |
+|---|---|
+| `--db` | store path; `SIDEGRAPH_DIR` preferred, deprecated `SIDEGRAPH_DB` retained |
+| `--profile` | export settings from a flow profile; default `generic-adr` |
+| `--out` | override the profile directory, otherwise below the store's parent |
+| `--template` | UTF-8 body template, regular file up to 64 KiB |
+| `--filename` | safe flat pattern containing `{id}`, optionally `{number:04d}` |
+| `--write` | explicitly apply a conflict-free plan; absent means no output writes |
+| `--json` | changes/diffs, advisory states, warnings and write-completion flags |
+
+Manual additions after the managed region survive. Editing generated prose/ownership
+causes a conflict, preserving the file; any planned conflict prevents all writes.
+Existing filenames/numbers are stable; no generated history is deleted. Symlinks,
+nonregular targets and source-store overlap are refused. Existing files are replaced
+atomically, but an I/O/race failure can leave earlier writes or a partial newly created
+file: inspect `applied` and `partial_write_possible` before retrying.
+
+Export never opens Store, migrates it, or updates source/index/graph files. Drift is
+report-only and can be unknown, including for unopened WAL indexes. Both import and
+bootstrap skip generated projections; importing exported ADRs does not create fresh
+memory. Exit 0 for successful preview/write (including an admitted empty population), 2
+for invalid input/store, conflicts or operational errors. See the
+[ADR export guide](../guides/adr-export.md) for formats, custom templates, source tracing,
+conflict recovery, drift limits and round-trip semantics.
+
 ## `sidegraph-export-okf`
 
 ```bash
@@ -1573,6 +1617,16 @@ sidegraph-stats [--db PATH] [--window DAYS] [--graph PATH] [--json]
 
 One screen of usage statistics, read-only: how often memory was asked for, how much of the
 code being worked on has memory anchored to it, what the store holds, and how the anchors are doing.
+An additional **DELIVERY** section (`delivery_evidence` in JSON) reports observed MCP
+outcomes and prepared hook blocks separately: occurrences, actual record placements, anchor relations,
+retained unique records, status/kind at emission, comparable ranker populations and bounded
+retention metadata. It is not added to legacy activation or `showings`. Missing optional
+tables mean unavailable evidence, not zero; with telemetry off the JSON field is `null`.
+Capacity-eviction counts cover this index's recording lifetime, not just the requested
+window. Older writers, failed writes and host receipt remain unknown, and hooks have no
+all-attempt denominator. See [delivery evidence](store-format.md#delivery-evidence-derived-index-only)
+for exact surfaces, units, privacy and caps. This read-only command never migrates the ledger.
+
 It states what was **shown, asked and touched** — never what was improved, prevented, saved
 or caused. A journal cannot separate "memory sent the agent there" from "the agent was going
 there anyway", so no line of the report claims an effect.