sidegraph 0.14.0__tar.gz → 0.16.0__tar.gz

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

@@ -130,7 +130,7 @@ jobs:
           interpreter="$environment/bin/python"
           constraints=()
           if [ "$SDK_PAIR" = minimum ]; then
-            constraints=(fastmcp==3.4.2 mcp==1.24.0)
+            constraints=(fastmcp==3.4.2 mcp==1.30.0)
           fi
           uv pip install --python "$interpreter" "$wheel" pytest "${constraints[@]}"
           mkdir -p "$RUNNER_TEMP/sdk-check"
@@ -188,13 +188,17 @@ jobs:
           uv run pytest -q --junitxml="$env:RUNNER_TEMP/windows-core.xml" `
             tests/test_store_mutation_guard.py `
             tests/test_store_mutation_immediate.py tests/test_store_cross_process_mutations.py `
+            tests/test_hook_contention.py tests/test_retrieval_seeds.py `
             tests/test_portable_json.py tests/test_bootstrap_descriptor_cleanup.py `
             tests/test_server_result_contract.py tests/test_server_invocation_policy.py `
             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 `
+            tests/test_health_check_skill.py `
             $privateTests `
             tests/test_installed_wheel_smoke.py
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

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

@@ -7,6 +7,81 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-10-20
+
+See [Using Sidegraph 0.16](docs/guides/using-0.16.md) for update, compatibility, and
+limitation notes.
+
+### Security
+
+- Raise the minimum MCP Python SDK to 1.30.0, which includes the upstream fix for
+  [GHSA-84m7-p3x7-pcfv](https://github.com/advisories/GHSA-84m7-p3x7-pcfv). The supported
+  SDK major remains 1.
+
+### Added
+
+- Add `/sidegraph:health-check`, a read-only installation report with six evidence sections
+  and prioritized manual recommendations. It uses an already identified Python interpreter
+  and skips doctor and stats paths when an existing SQLite index is unsafe to open.
+
+### Changed
+
+- Hook-owned SQLite handles now refuse lock contention immediately across session, stop,
+  tool-use and subagent entry paths. SessionStart's dedupe remains best-effort under overlap;
+  its graph, filesystem and Git work is outside this lock-wait bound.
+- Retrieval and file listings reuse a lazy, per-call descriptor lookup, avoiding repeated
+  full entity scans while preserving seed selection and rendered output.
+- `sidegraph-compact` reports distinct hot files retained when their content is not fully
+  represented in the immutable archive, with warnings that distinguish extra fields from
+  shared-value or structure differences.
+
+### Fixed
+
+- `list_domains` now bounds its complete MCP text response and reports matched, returned and
+  omitted counts with whole rows. Its provisional return shape changes from a bare list to a
+  JSON-text envelope; exact domain-id and query filters can retrieve rows left out by the cap.
+- `sidegraph-stats` withholds anchor health counts while a fresh index's binding statuses await
+  `sidegraph-sync`, while keeping the record inventory and reach figures available.
+
+## [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.16.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.16.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.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.14.0
+Version: 0.16.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
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.13
 Requires-Dist: anyio>=4
 Requires-Dist: fastmcp<4,>=3.4.2
-Requires-Dist: mcp<2,>=1.24
+Requires-Dist: mcp<2,>=1.30
 Requires-Dist: pydantic>=2.9
 Requires-Dist: python-ulid>=3.0
 Description-Content-Type: text/markdown
@@ -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.16.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.16.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.16.0}/docs/README.md

@@ -26,6 +26,7 @@ If the repository already has ADRs or specs, use the
 ## Operate and maintain it
 
 - [Migrate an existing store to Sidegraph 0.14](guides/migrating-to-0.14.md).
+- [Check a Sidegraph installation](guides/health-check.md).
 - [Survive refactors and heal anchors](guides/surviving-refactors.md).
 - [Read what Sidegraph tells you when it needs attention](guides/troubleshooting.md).
 - [Run CI and scheduled maintenance](guides/ci-cd-maintenance.md).

{sidegraph-0.14.0 → sidegraph-0.16.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.16.0}/docs/concepts/mind-model.md

@@ -131,9 +131,11 @@ this matters in practice beyond an ordinary rename: freeing a community that a d
 still claims (give the successor no matching `path_prefixes`/`seed_anchors` instead of
 carrying the old rule forward).
 
-**Listing.** `list_domains(status=None)` returns every domain in the store — optionally
-filtered to one status — with membership/lineage counts (`member_count`, `seed_anchor_count`,
-`parent_slug`/`child_slugs`); it's the general "show me all domains" answer `list_proposed`
+**Listing.** `list_domains(status=None)` searches every status and returns whole domain rows
+inside a bounded JSON-text envelope, with counts and a hint when filters or output limits omit
+rows. Narrow by exact domain ids or query terms to reach a row from an omitted listing. Rows
+include membership/lineage fields (`member_count`, `seed_anchor_count`, `parent_slug` and
+`child_slugs`); this is the general "show me all domains" answer `list_proposed`
 (proposed-only) and `list_domain_candidates` (unclaimed-only) don't cover.
 
 ## How domains relate to engine communities

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

@@ -103,6 +103,12 @@ an empty list with an explanatory `"note"` key — everything store-derived (`do
 takes the seeds as `files` and `entities`): given what the agent is about to touch, return a compact slice of structure *and* memory, memory ranked so the things
 most likely to save it from a repeat mistake come first.
 
+Within one retrieval or file-list call, descriptor resolution shares a lazy, operation-scoped
+lookup of parsed entities. It preserves the existing exact-path, pathless adoption, ambiguity,
+and winner rules while avoiding a full entity-table parse for each graph node. The lookup is
+discarded after the call; a later call sees entity changes. This is a performance-only change:
+seed selection, record ranking, budgets, and rendered output are unchanged.
+
 ### Seeds
 
 A `Seed` is either:
@@ -353,6 +359,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.16.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.16.0}/docs/getting-started/installation.md

@@ -24,18 +24,18 @@ installs a non-editable wheel outside the checkout, checks its package bytes aga
 artifact, runs a CLI, and exchanges real MCP stdio messages in a Unicode/spaced directory.
 The exact selection is in [the CI workflow](../../.github/workflows/ci.yml).
 
-Separately, each release candidate runs real Claude Code and Codex sessions with the
+For the 0.14.0 release-candidate campaign, real Claude Code and Codex sessions ran with the
 installed plugin, in fresh host profiles, on Windows Server 2022 x64 and macOS 15 arm64,
-each with Python 3.13 and 3.14. Each run is the full plugin session for both hosts: the
+each with Python 3.13 and 3.14. Each run was the full plugin session for both hosts: the
 plugin's MCP server, `SessionStart` context, records before a Read, a bundled skill, a
 subagent brief, the `Stop` capture prompt, capture and ratification, and recall in a fresh
-session. The project folder and host profile paths contain a non-ASCII character.
+session. The project folder and host profile paths contained a non-ASCII character.
 
 **0.14.0 publication gate:** Claude Code 2.1.296 and Codex CLI 0.162.1 on all four cells
 above, including a Windows 3.14 cell with PowerShell 7 unavailable for preflight and both
 real host sessions. Windows 3.13 retains PowerShell 7; its launcher checks also cover 5.1.
-Stable publication requires the full gate to pass without a known-issue exception. The
-README's blue badges summarize release acceptance, rather than live workflow status or
+Stable publication of 0.14.0 required the full gate to pass without a known-issue exception.
+The README's blue badges summarize release acceptance, rather than live workflow status or
 support for every published version. Muse and OpenCode have the narrower coverage in
 their installation guides and are outside this native matrix.
 
@@ -45,14 +45,15 @@ with Git for Windows installed; they do not establish support for Windows hosts
 remains outside these checks.
 See [Windows](#windows) before installing a host plugin.
 
-Package dependencies support `fastmcp>=3.4.2,<4` and `mcp>=1.24,<2`. Major SDK upgrades
+Package dependencies support `fastmcp>=3.4.2,<4` and `mcp>=1.30,<2`. Major SDK upgrades
 require a separate compatibility review; an unlocked package install may resolve newer
 versions within those bounds than the development lockfile.
 
 ### Windows
 
-The native checks above cover the tested release, not every published version. On
-Windows they cover the full plugin session; WSL is not a separate CI target.
+Current native CI covers selected core/MCP checks, wheel installation, CLI execution, and
+MCP stdio paths; WSL is not a separate CI target. Full Windows plugin sessions were exercised
+in the historical 0.14.0 release-candidate campaign described above.
 
 **Version requirement:** releases before 0.12.0 can stall a native Windows write: a Git
 child inherits the MCP stdin pipe and holds the write until the request times out (see
@@ -274,7 +275,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 +286,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.16.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.16.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.16.0/docs/guides/health-check.md

@@ -0,0 +1,66 @@
+# Check a Sidegraph installation
+
+Use `/sidegraph:health-check` to collect one read-only report for the current repository.
+It covers plugin wiring, runtime versions, Graphify, store integrity, anchor advisories, and
+inventory and usage. `UNKNOWN` means the evidence could not be established; it remains a
+warning and never becomes a clean result.
+
+## Runtime requirement
+
+The skill runs its local `scripts/collect.py` helper with `-B` under an already identified
+Python interpreter. In a development checkout, the supported paths are:
+
+```bash
+"<project>/.venv/bin/python" -B "<skill-directory>/scripts/collect.py" --project "<launch-directory>" --host claude
+```
+
+For Codex, pass `--host codex`; use `unknown` when the attached host is not known. On Windows,
+use the existing `<project>/.venv/Scripts/python.exe`. Installed use requires a
+known interpreter from attached host launch metadata or metadata for an identified Sidegraph
+environment. The collector does not guess a Python on `PATH`, run an unknown Sidegraph
+executable, or use `uv`/`uvx` as its launcher. If no suitable interpreter is known, the skill
+shows all six sections as limited, includes safe static evidence already available, lists
+manual recommendations, and stops. The same fallback applies when the helper exits nonzero,
+prints error JSON, or cannot import required inspection helpers; show only the error class and
+do not echo exception text. Cached package files alone do not authorize provisioning.
+
+The skill resolves the Git root to select the interpreter, then passes the original launch
+directory as `--project` so Claude plugin-scope checks retain the launch context. The optional
+`--store`, `--graph`, and `--plugin-root` arguments are for
+paths already known to the host or user; the collector does not search unrelated profiles.
+
+## Evidence and limits
+
+The report separates the collector package, plugin manifest, optional PATH installation,
+Graphify-recorded engine version, and any already observed active MCP evidence. Static
+registration is not proof that a running server answered. The workflow never starts a server
+or calls retrieval tools to test connectivity.
+
+The collector fingerprints the canonical store, index and sidecars, settings, plugin
+manifests, graph inputs, and actual Git index around its process. This is a stable-source
+check, not an atomic snapshot; concurrent writes make preservation evidence unstable without
+identifying which process changed it. Host hooks surrounding tool invocation are outside the
+collector's preservation boundary.
+
+If the index is absent, canonical-only doctor curation still runs, and index-dependent
+findings and stats are marked skipped. If an existing index has WAL/SHM sidecars, an
+unrecognized header, an unreadable header, or a nonempty rollback journal, all doctor
+advisory and stats paths that could open it are skipped. A regular rollback-mode index allows
+the existing doctor and stats checks to run. Cold or stale index qualifications are retained.
+
+The six report sections distinguish contract violations from advisory findings and missing
+coverage. Inventory counts come from canonical readers. Pending age is unknown for malformed
+record identifiers. Usage reports summarize recorded activity only; delivery counts do not
+show usefulness, prevented errors, or saved time. Records on unmerged or remote-only branches
+are not exhaustively checked.
+
+## Manual follow-up
+
+Recommendations are prioritized and deduplicated, with a reason, explicit scope, argv, working
+directory, and environment for a manual command or skill to run after the report. Render argv
+with the attached shell's native quoting; paths are never embedded into shell snippets. The
+health check never executes recommendations. Ordinary doctor and stats reads
+outside this collector can create SQLite sidecars for a WAL database, so inspect such an
+index separately after the writing session. Ending a session does not guarantee a persistent
+journal-mode change. Do not recommend an upgrade from an unknown version or install the
+optional PATH CLI solely because it is absent.

{sidegraph-0.14.0 → sidegraph-0.16.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.