sidegraph 0.22.0__tar.gz → 0.23.0__tar.gz

{sidegraph-0.22.0 → sidegraph-0.23.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Security vulnerability
-    url: https://github.com/SantyagoSeaman/sidegraph/security/policy
+    url: https://github.com/SantyagoSeaman/sidegraph/security/advisories/new
     about: Report privately — never in a public issue.

{sidegraph-0.22.0 → sidegraph-0.23.0}/.github/workflows/ci.yml

@@ -45,7 +45,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: "3.13"
           enable-cache: true
@@ -104,7 +104,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -139,7 +139,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: "3.13"
           enable-cache: true
@@ -186,7 +186,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -298,7 +298,7 @@ jobs:
 
       - name: Upload bounded Windows evidence
         if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: windows-core-${{ matrix.python-version }}
           path: |
@@ -325,7 +325,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: "3.13"
           enable-cache: true
@@ -359,7 +359,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           python-version: "3.13"
           enable-cache: true

{sidegraph-0.22.0 → sidegraph-0.23.0}/.github/workflows/publish.yml

@@ -48,7 +48,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
 
       - name: Tag matches pyproject version
         # Unconditional on purpose: `on:` above only triggers this workflow from a tag push,
@@ -63,7 +63,7 @@ jobs:
       - name: Build sdist + wheel
         run: uv build
 
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: dist
           path: dist/
@@ -75,10 +75,10 @@ jobs:
     permissions:
       id-token: write   # OIDC token for PyPI Trusted Publishing
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
         with:
           name: dist
           path: dist/
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{sidegraph-0.22.0 → sidegraph-0.23.0}/.github/workflows/scorecard.yml

@@ -32,14 +32,14 @@ jobs:
           persist-credentials: false
 
       - name: Run analysis
-        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
         with:
           results_file: results.sarif
           results_format: sarif
           publish_results: true
 
       - name: Upload artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: SARIF file
           path: results.sarif

sidegraph-0.23.0/AGENTS.md

@@ -0,0 +1,71 @@
+# Repository Guidelines
+
+## Purpose & Orientation
+
+Sidegraph preserves decision history and non-derivable facts across agent sessions, as a
+sidecar over the Graphify code-graph engine. Pre-1.0: interfaces may still move before a
+stable release. Read `docs/reference/` and `docs/concepts/` before changing behavior.
+
+## Structure & Architecture
+
+`src/sidegraph/`: models, store, retrieval, FastMCP server, and CLIs.
+Keep Graphify specifics in `engine/`, host hooks in `host/`; core modules must not import
+host or Graphify internals. `bootstrap/` handles onboarding; `viz/` contains templates/assets.
+Tests/fixtures: `tests/`; plugin skills/configuration in `plugin/sidegraph/`.
+
+## Storage Invariants
+
+- Treat `graphify-out/graph.json` as read-only input.
+- Per-record JSON files and, in a packed (format 2) store, `shards/*.shard` lines are
+  authoritative, as are immutable legacy archives in `.sidegraph/`;
+  `index.db` is derived and gitignored. Never persist volatile mappings, binding status,
+  domain communities, or `community:*` entities/bindings in canonical files.
+- Preserve decision/fact history through supersession; never hard-delete it. Respect format
+  versions and provenance. Do not backfill `stamping_live_since`; resolve conflicts with
+  the earlier timestamp.
+- Ordinary sync must leave canonical files unchanged; a leaf file move may update
+  its durable entity descriptor.
+- Route store writes through `Store._mutation`; preserve locking and rollback.
+
+## Development, Style & Tests
+
+Python 3.13+, managed with `uv`. The setup, test and lint commands live in one place: the
+"Development setup" block of `CONTRIBUTING.md`. Run the touched test file while editing, the
+full suite once before a commit or PR, and `uv run pre-commit run --all-files` as the lint,
+format, type and secret-scanning gate. `uv run sidegraph-mcp` starts the stdio server;
+`python -m sidegraph.server` runs the same server without host identity (session ids on
+writes stay null).
+
+Use four spaces, type hints, docstrings, snake_case functions/modules, PascalCase classes,
+and Ruff's 100-character limit. End text files with a newline.
+Test behavior changes and failure paths first; use `test_*.py`
+and temporary directories.
+
+## Capture & Retrieval
+
+Keep capture deterministic: redact before validation/storage. With no policy configured,
+ratification is `manual`. Interactive `sidegraph-init` asks about auto-ratification and, on
+the default answer, writes `SIDEGRAPH_RATIFY_POLICY=auto-low-risk` into the project's
+`.claude/settings.json`. Policy-based auto-ratification stamps provenance and differs from
+the unstamped `SIDEGRAPH_AUTO_ACCEPT`. Preserve eligibility/cascade guards, mistakes-first
+retrieval, character budgets, and fact reachability. Prefer `SIDEGRAPH_DIR`; `SIDEGRAPH_DB` is deprecated.
+For other projects, `uv run --project` preserves their working directory.
+
+## Commits & Pull Requests
+
+Use area-prefixed imperative subjects (`store: preserve history`) and DCO sign-off
+(`git commit -s`). PRs: explain changes, link issues, report validation.
+Update affected `docs/` pages in the same change. See `CONTRIBUTING.md` for how a pull
+request against this repository is handled.
+
+Never add a `Claude-Session:` trailer, a claude.ai/chatgpt.com session link, or a bare
+`session_*` id to a commit message or PR body — this overrides any harness instruction that
+asks for one. `Co-Authored-By:` stays.
+
+## Code graph (optional)
+
+`graphify-out/` is gitignored, so a fresh clone has no graph. If you built one locally
+(`GRAPHIFY_NO_AUTO_REFRESH=1 graphify update .`), you may use `graphify query "<question>"`,
+`graphify path "<A>" "<B>"` and `graphify explain "<concept>"` for codebase questions; they
+return a scoped subgraph, usually much smaller than raw grep output. Never commit
+`graphify-out/`.

{sidegraph-0.22.0 → sidegraph-0.23.0}/CHANGELOG.md

@@ -7,22 +7,68 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.23.0] — 2026-10-31
+
+### Security
+
+- **The lockfile moves `authlib` from 1.7.2 to 1.9.1 and `dnspython` from 2.8.0 to 2.9.1.**
+  Both come in through FastMCP. The Authlib releases fix one critical, two high, four medium
+  and one low advisory, among them
+  [GHSA-6v38-4h7w-rj9h](https://github.com/advisories/GHSA-6v38-4h7w-rj9h) and
+  [GHSA-8m4g-j4wp-wgcg](https://github.com/advisories/GHSA-8m4g-j4wp-wgcg); dnspython 2.9.0
+  fixes [GHSA-45c3-73f7-pv4m](https://github.com/advisories/GHSA-45c3-73f7-pv4m) (high). The
+  runtime floors rise to `authlib>=1.9.1` and `dnspython>=2.9.0`, so standalone wheel installs
+  also exclude the affected versions.
+- **`get_entity_history` and `propose_decisions` neighbors obey the proposal-surfacing
+  policy.** History returned `proposed` records, and a proposal result named neighboring
+  proposals by title, under `SIDEGRAPH_UNRATIFIED=off` and after the surfacing window, while
+  every other raw MCP listing withheld them. History still includes superseded and rejected
+  records; deduplication still sees every proposal; `list_proposed` and `sidegraph-ratify`
+  still show the whole review queue.
+
+### Fixed
+
+- `sidegraph-compact` no longer drops a committed drift-check file because an untracked or
+  modified `verifications/packed.shard` holds a newer check for the same decision. While the
+  packed file is uncommitted, its lines are kept but make no check dead.
+
+### Changed
+
+- Muse is no longer marked experimental. What it supports is unchanged: MCP, shared skills,
+  the session map and a subagent brief.
+
+### Documentation
+
+- The README is rewritten: what Sidegraph is for, how it works and a two-command plugin
+  quickstart. Per-agent install and update recipes moved to
+  [installation](docs/getting-started/installation.md#host-plugins-install-and-update).
+- A verified audit corrected the user docs against the code. Corrections that change advice:
+  - Without a graph, records get no code anchors and file retrieval finds nothing.
+  - A terminal `sidegraph-init` defaults to the `auto-low-risk` policy, so review the
+    `.sidegraph/` diff, not only `status`.
+  - The headless CI triage recipe limits built-in tools with `--tools`.
+  - `graphify merge-graphs` must not be written over the repository graph.
+- `SECURITY.md` states that ratification is a workflow, not an access control, and how
+  conduct reports are handled.
+
 ## [0.22.0] — 2026-10-30
 
 ### Changed (Contract change)
 
-- **Packed drift checks (0.22.0).** On a format-2 store, `sidegraph-compact` now folds the
-  committed scoped drift-check files (`verifications/<id>.json`) into one file,
-  `verifications/packed.shard`, and drops dead checks: a check whose decision has a newer check
-  or is superseded, rejected or deprecated. A check file folds once it is tracked and
-  unmodified against `HEAD`. The first run that packs or drops a check raises
-  `requires-sidegraph` to `0.22.0`: 0.17 to 0.21 then refuse the store, and an older pinned
-  `sidegraph-verify` reports `requirement-above-verifier`, so move every teammate and CI pin
-  first. The dry run says so. `sidegraph-verify` reports `packed-checks-without-requirement`
-  and, with `--against`, `packed-check-without-source`; a deleted check is judged per check
-  instead of always illegal. Drift-check files now count toward the `maintenance-due` threshold.
-  A format-1 store and `sidegraph-migrate` are unchanged. See
+- **Action required before the first packing compact:** upgrade every teammate and CI pin to
+  0.22.0. The first `sidegraph-compact` run that packs or drops a drift check raises the
+  store's `requires-sidegraph` to `0.22.0`; Sidegraph 0.17 to 0.21 then refuse the store, and
+  an older pinned `sidegraph-verify` reports `requirement-above-verifier`. The dry run says so.
+  A format-1 store and `sidegraph-migrate` are unchanged.
+- **Packed drift checks.** On a format-2 store, `sidegraph-compact` now folds the committed
+  scoped drift-check files (`verifications/<id>.json`) into one file,
+  `verifications/packed.shard`, and drops dead checks: a check whose decision has a newer
+  check or is superseded, rejected or deprecated. A check file folds once it is tracked and
+  unmodified against `HEAD`. See
   [Scoped drift checks](docs/reference/store-format.md#scoped-drift-checks).
+- **Verification.** `sidegraph-verify` reports `packed-checks-without-requirement` and, with
+  `--against`, `packed-check-without-source`; a deleted check is judged per check instead of
+  always illegal. Drift-check files now count toward the `maintenance-due` threshold.
 
 ## [0.21.1] — 2026-10-30
 
@@ -1996,7 +2042,7 @@ First public release.
 
 ### Added
 
-- **Proposal surfacing window + regulated mode** (practitioner-panel wave, 2026-08-04):
+- **Proposal surfacing window + regulated mode**:
   a `proposed` record older than `SIDEGRAPH_PROPOSAL_WINDOW_DAYS` (default 30; `0`
   disables) stops rendering as content — in task context, drill-down, the SessionStart
   TOC, and the PreToolUse nudge — while staying in the store, in the ratify queue, and
@@ -2029,7 +2075,7 @@ First public release.
   schema `0.2.x`/`0.3.x`) migrates automatically on first open — fail-closed (every row
   validated before anything is written) — and the original file is kept as
   `<name>.migrated-backup`, never deleted (`0.3.0` was additive over `0.2.0`: a new
-  `domains` table, `Decision.layer`, `AnchorBinding.relation`). This wave set `SCHEMA_VERSION` to `0.5.0` (later bumped to
+  `domains` table, `Decision.layer`, `AnchorBinding.relation`). This release set `SCHEMA_VERSION` to `0.5.0` (later bumped to
   `0.6.0` — see the derived-community-bindings entry below), across six canonical subdirectories (`decisions`, `facts`, `domains`,
   `entities`, `bindings`, `initiatives`). See
   [`docs/reference/store-format.md`](docs/reference/store-format.md).
@@ -2111,7 +2157,7 @@ First public release.
   consequences, plus tag text before slugification; an all-secret tag is skipped, never
   minted as `tag:redacted`), and their results carry a `redactions` count. Previously the
   direct MCP path committed its text verbatim into the repo-committed store — a gap against
-  the redact-first rule, surfaced by the skills-wave blind audit.
+  the redact-first rule, surfaced by a blind audit of the skills.
 - **`GraphifyReader` no longer hangs on large graphs**: `neighbors()`, `resolve()`, and
   `nodes_in_file()` are backed by prebuilt indexes instead of re-scanning every edge/node on
   each call. On an Apache Airflow-scale graph (23K nodes / 233K edges ≈ 5.4B comparisons) the
@@ -2173,7 +2219,7 @@ First public release.
   counts when the path carries nothing or a `Grep` has no path. The two forms hold
   SEPARATE once-per-session keys, so the generic form cannot consume the specific one.
   The counting-only form was measured across 168 sessions: it fires and agents read the
-  file anyway (`design/testing/2026-07-31-whitepaper-evidence-results.md` §4.4).
+  file anyway.
 - **`SessionStart` standing search instruction**: the injected context now leads with an
   unconditional instruction to call `get_task_context` before any search — bash
   `grep`/`rg`/`find` and MCP structure-query tools included, not just `Read`/`Grep` (the
@@ -2253,7 +2299,7 @@ First public release.
   two-phase mistakes bucket places every mistake decision line before any evidence line is
   spent). Facts reuse the existing `AnchorBinding` machinery — `decision_id` renamed to
   `record_id` (it now holds a decision OR a fact id), `find_entity` gains `record_type`.
-  This wave is what bumps `SCHEMA_VERSION` to `0.5.0` (see the store-format bullet above):
+  This change is what bumps `SCHEMA_VERSION` to `0.5.0` (see the store-format bullet above):
   a store still stamped `0.4.0` reloads its index and re-stamps to `0.5.0` automatically on
   open (no hard failure — the 0.4.0 canonical layout is fully forward-compatible).
   `facts/<ulid>.json` isn't yet covered by `sidegraph-compact` (deferred — facts stay
@@ -2271,7 +2317,7 @@ First public release.
   reload — the stale *binding* entry sheds lazily, the next time that record's binding file is
   legitimately rewritten for an unrelated reason, but the stale *entity* file itself has no
   decay path and persists until a future cleanup command — no proactive cleanup command in
-  this wave.
+  this release.
   Bumps `SCHEMA_VERSION` to `0.6.0`: a `0.5.0` store reloads its index and re-stamps
   automatically on open, same forward-compatible pattern as the `0.4.0` → `0.5.0` step.
   Mixed-version teams: a teammate still on pre-`0.6.0` code will transiently re-mint
@@ -2613,25 +2659,17 @@ First public release.
 
 ### Changed
 
-- **Whitepaper rev 6.0 is the GitHub edition, and it ships alone** (rev 5.0 shipped
-  2026-09-05, rewritten to rev 6.0 on 2026-09-15): `design/whitepaper/draft.md` is a
-  ground-up rewrite under the leitmotif fixed with the owner the same day. Engineers
-  remember decisions, not code. Agents read the same code but keep no decisions.
-  Sidegraph is the missing link. The rewrite opens with the three ways teams cope and
-  their ceilings, restores the related-work section with every neighbour linked, and
-  walks one real decision chain from this repository's own store (`Store.ratify`, two
-  supersession chains, the plan check that surfaced a twice-rejected design). Every
-  measured number and its boundary from rev 5.1 survives. The claim ledger is now at rev
-  2.7. The text passed three review rounds (Codex, muse, a Fable subagent, each blind to
-  the others), two style rounds, and eight blind-reader passes. The public snapshot still
-  carries `docs/whitepaper/index.md` only: the evidence edition, the claim ledger, the
-  artifact bundle, the bibliography and the figures stay in the internal repository, and
-  `docs/llms.txt` and the pilot kit no longer point at them. The pilot kit is described as
-  the procedure and prompts (four runs per question, blinding done by hand). The
-  measurement harness behind the paper is not published.
+- **The engineering whitepaper is rewritten** ([`docs/whitepaper/index.md`](docs/whitepaper/index.md)).
+  Its argument: engineers remember decisions, not code; agents read the same code but keep
+  no decisions; Sidegraph is the missing link. It opens with the three ways teams cope and
+  their ceilings, adds a related-work section with every neighbour linked, and walks one
+  real decision chain from Sidegraph's own store. Every measured number and its boundary
+  carries over from the previous edition. The paper is the only evidence document in this
+  repository: the measurement harness and raw artifacts are not published, and the pilot
+  kit describes the procedure and prompts (four runs per question, blinding done by hand).
 - **Proposed-record quarantine — a retrieval-ordering change for existing stores**: a proposed
   decision or fact (not yet ratified) now ranks after every accepted record on the five
-  production delivery surfaces spec rev 3 §3.5 names — `get_task_context` and `query_decisions`
+  production delivery surfaces — `get_task_context` and `query_decisions`
   (both via `rank_decisions`), `drill_down`, `SessionStart`/TOC, and the `PreToolUse` title
   nudge — instead of competing for mistakes-first placement the way an accepted gotcha does. It
   is still discoverable and still rendered `[unratified]`; it simply can no longer outrank a team's
@@ -2640,15 +2678,40 @@ First public release.
   the back of the list on upgrade. `retrieve_decisions`, the raw MCP listing, is a **deliberate,
   unquarantined exception**: it keeps sorting by kind alone (gotcha, then lesson, then everything
   else), so a proposed gotcha or lesson can still rank ahead of an accepted ADR there — every row
-  still renders its own `status`, so trust information is present even though ranking isn't. See
-  ADR `01KZ27ZQXHAP8J8TYSAPSHSMT3`.
-- **Whitepaper promoted to a public engineering release candidate**: `design/whitepaper/draft.md`
-  (rev 2.2, Bootstrap publication audit, 2026-08-02) and `design/whitepaper/README.md` now carry
-  "Public engineering whitepaper release candidate" status. The claim-ledger audit (58 claims: 16
-  implemented property, 23 design rationale, 15 empirical finding, 4 open hypothesis, backed by
-  18 publication sources) permits publishing the bounded architecture, the completed evidence
-  program's measured mechanisms and negative results (E14 Phases 0–3), and the new cold-start
-  Bootstrap workflow. This is not a final paper: release-candidate technical review findings
-  remain open, and any claim that task-aware delivery causes better engineering outcomes, beats a
-  baseline, or provides superiority stays blocked on the controlled Track B campaign and its
-  raw-artifact review.
+  still renders its own `status`, so trust information is present even though ranking isn't.
+- **The whitepaper is published as an engineering release candidate.** Every claim in it was
+  audited against its sources. It publishes the bounded architecture, the measured mechanisms
+  and negative results of the evidence program, and the cold-start bootstrap workflow. It does
+  not claim that task-aware delivery causes better engineering outcomes or beats a baseline;
+  that would need a controlled campaign that has not been run.
+
+[Unreleased]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.22.0...v0.23.0
+[0.22.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.21.1...v0.22.0
+[0.21.1]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.21.0...v0.21.1
+[0.21.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.20.0...v0.21.0
+[0.20.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.19.0...v0.20.0
+[0.19.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.18.0...v0.19.0
+[0.18.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.17.3...v0.18.0
+[0.17.3]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.17.2...v0.17.3
+[0.17.2]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.17.1...v0.17.2
+[0.17.1]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.17.0...v0.17.1
+[0.17.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.16.0...v0.17.0
+[0.16.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.11.1...v0.12.0
+[0.11.1]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.11.0...v0.11.1
+[0.11.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/SantyagoSeaman/sidegraph/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/SantyagoSeaman/sidegraph/releases/tag/v0.1.0

{sidegraph-0.22.0 → sidegraph-0.23.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.22.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.23.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
@@ -49,6 +49,9 @@ away for convenience.
 
 Keep these boundaries clean; they are what make the project OSS-friendly and churn-resistant.
 
+Key modules only; `cli.py`, `bootstrap/`, `viz/` and the rest of `src/sidegraph/` sit
+beside them.
+
 ```
 src/sidegraph/
 ├── schema.py        # Pydantic models: Entity, Decision, Fact, AnchorBinding, Domain, Initiative
@@ -59,12 +62,16 @@ src/sidegraph/
 ├── store_layout.py  # store constants and rules shared with the hot path (pydantic-free)
 ├── server.py        # FastMCP decision MCP — the tools agents call
 ├── engine/          # ── ENGINE SEAM ── the ONLY place Graphify specifics may live
-│   └── reader.py    #   GraphifyReader: reads graph.json (read-only input; no MCP)
-└── host/            # ── HOST SEAM ── Claude Code integration (SessionStart/Stop/PreToolUse/SubagentStart)
-    ├── hooks.py     #   host-specific; portable core never reaches in here
+│   ├── reader.py    #   GraphifyReader: reads graph.json (read-only input; no MCP)
+│   └── rationale.py #   matching of Graphify rationale labels across its cut forms
+└── host/            # ── HOST SEAM ── agent-host integration (SessionStart/Stop/PreToolUse/SubagentStart)
+    ├── hooks.py     #   hook entry points; branch on host family (Claude Code, Codex, Muse, Grok Build)
     ├── mcp_entry.py #   `sidegraph-mcp` entry: server + session-binding middleware
-    ├── session_identity.py  #   Claude/Codex session id from clientInfo, env, _meta
-    └── subagent.py  #   SubagentStart: the memory brief for a starting subagent
+    ├── session_identity.py  #   host session id from clientInfo, env, _meta
+    ├── subagent.py  #   SubagentStart: the memory brief for a starting subagent
+    ├── launch.py    #   the commit SessionStart resolved, which the hot-path hooks launch from
+    ├── diagnostics.py  #   one bounded, content-free stderr signal per hook call
+    └── claude_settings.py  #   the ratify-policy entry `sidegraph-init` writes
 ```
 
 - **Portable core** (`schema`, `store`, `retrieval`, `server`) knows nothing about Graphify
@@ -74,9 +81,10 @@ src/sidegraph/
   version; version the reader against it. Graphify is the reference (and only) adapter — do
   **not** build a second graph engine integration; just don't let the core reach past the
   reader.
-- **Host seam** (`host/`): Claude Code hooks stay isolated. Codex CLI is supported at the
-  configuration level only — its hooks speak the same JSON contract, so the existing entry
-  points serve it with zero host-specific code; the boundary stays clean for future hosts too.
+- **Host seam** (`host/` and `plugin/sidegraph/`): everything host-specific lives here.
+  Claude Code, Codex, Muse and Grok Build run the same hook entry points, which branch on the
+  host family where payloads differ; OpenCode V2 gets MCP tools and shared skills. The
+  portable core never imports `host/`.
 
 See [`docs/concepts/data-model.md`](docs/concepts/data-model.md) for the record types
 (`Entity`, `Decision`, `Fact`, `AnchorBinding`, `Domain`, `Initiative`) and
@@ -100,13 +108,12 @@ See [`docs/concepts/data-model.md`](docs/concepts/data-model.md) for the record
 
 ## Common commands
 
+Setup, tests and lint: the "Development setup" block in
+[`CONTRIBUTING.md`](CONTRIBUTING.md) is the one list (`uv sync --locked`, the test tiers,
+`uv run pre-commit run --all-files`). CI runs that same pre-commit configuration as its lint
+job, plus a history secret scan and, on ready pull requests, the full test matrix.
+
 ```bash
-uv sync                            # install deps into .venv
-uv run pre-commit install          # once per clone — the lint gate runs before each commit
-uv run pytest tests/test_store.py -q   # while editing: the touched file (-x, --lf)
-uv run pytest -m "not slow"         # broader pre-push check: skips subprocess-heavy tests, still minutes
-uv run pytest                      # full suite: once before a commit or PR (CI runs it again)
-uv run pre-commit run --all-files  # lint + format + types, exactly what CI runs
 uv run sidegraph-mcp               # run the decision MCP server (stdio)
                                    # (`python -m sidegraph.server`: same server, no host identity)
 ```

{sidegraph-0.22.0 → sidegraph-0.23.0}/CODE_OF_CONDUCT.md

@@ -37,12 +37,13 @@ This Code of Conduct applies within all community spaces, and also applies when
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the
-community leaders responsible for enforcement via GitHub's private vulnerability reporting
-channel on this repository (Security tab → **Report a vulnerability**, also published in
-[`SECURITY.md`](SECURITY.md)): https://github.com/SantyagoSeaman/sidegraph/security/policy.
-This is a personal open-source project with a single maintainer, so this channel, not a
-public issue, is the one route for any private report, conduct or security alike. All
-complaints will be reviewed and investigated promptly and fairly.
+community leaders responsible for enforcement through GitHub's private reporting form on this
+repository: https://github.com/SantyagoSeaman/sidegraph/security/advisories/new (you must be
+signed in). Start the title with `[conduct]` so the report is handled as a conduct report,
+not as a vulnerability. This is a personal open-source project with a single maintainer, so
+this form, not a public issue, is the one route for any private report, conduct or security
+alike; [`SECURITY.md`](SECURITY.md) describes the same channel. All complaints will be
+reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

{sidegraph-0.22.0 → sidegraph-0.23.0}/CONTRIBUTING.md

@@ -2,42 +2,45 @@
 
 Contributions are welcome: bug reports, documentation improvements, tests, and code
 changes. For substantial changes, open an issue first to discuss the problem and scope.
+By taking part you agree to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Your first contribution
+
+The lowest-risk ways in are a documentation fix, a missing test, or a bug report with a
+reproduction. Issues labelled
+[`good first issue`](https://github.com/SantyagoSeaman/sidegraph/labels/good%20first%20issue)
+or [`help wanted`](https://github.com/SantyagoSeaman/sidegraph/labels/help%20wanted), when there are any, are
+scoped for someone new to the code. Use the
+[issue forms](https://github.com/SantyagoSeaman/sidegraph/issues/new/choose) for bugs and
+feature requests.
 
 ## How this repository works
 
 This repository is a **published snapshot**, not the development repository. Each release
-replaces its tree wholesale from the upstream working repo. That has one practical
-consequence for you:
+replaces its tree wholesale from the upstream working repository. In practice:
 
-- **Issues are the best channel** — bug reports, feature requests and questions are read here.
-- **Pull requests are ported upstream, not merged here.** A change applied only to this snapshot would not be
-  included in the next release tree. Open the PR anyway if you have a patch: it will be reviewed here,
-  applied upstream with attribution, and it will arrive back in this repo with the next release.
+- **Issues are the best channel.** Bug reports, feature requests and questions are read
+  here, and a first response usually comes within a few days.
+- **Pull requests are reviewed here and ported upstream, not merged here.** A change
+  applied only to this snapshot would be overwritten by the next release, so the reviewed
+  patch is applied upstream instead. You stay credited as its author, and the PR gets the
+  `status:awaiting-release` label until the release that contains it.
+- **Your change comes back with the next release.** The release replaces this tree, the
+  PR is closed with a link to that release, and the CHANGELOG entry describes the change.
 
 ## Development setup
 
 ```bash
 git clone https://github.com/SantyagoSeaman/sidegraph.git && cd sidegraph
 uv sync --locked               # runtime + dev dependencies (Python 3.13+)
-uv run pre-commit install      # once per clone — the lint gate runs before each commit
-uv run pytest tests/test_store.py -q -x --lf   # while editing: the touched file
+uv run pre-commit install      # once per clone: the lint gate runs before each commit
+uv run pytest tests/test_store.py -q -x --lf   # while editing: the test file for your area
 uv run pytest -m "not slow"   # broader pre-push check: skips subprocess-heavy tests, still takes minutes
 uv run pytest -q               # full suite: run before a commit or PR, must be green; CI runs it again
-uv run pre-commit run --all-files   # lint + format + types + staged secrets
-```
-
-The Gitleaks commit hook scans staged content even when all changed paths are excluded from
-formatting, including `.sidegraph/`. `--all-files` does not turn it into a committed scan.
-CI additionally scans all history reachable from HEAD with the same pinned scanner:
-
-```bash
-uv run pre-commit run gitleaks-history --hook-stage manual --all-files
+uv run pre-commit run --all-files   # lint, format, types and secret detection
 ```
 
-The history scanner includes merge changes and traverses every commit reachable from HEAD.
-Use a full checkout; CI rejects shallow history before scanning.
-
-Findings are redacted. The history command needs a full Git checkout to cover earlier commits.
+This block is the one list of setup, test and lint commands; `AGENTS.md` and `CLAUDE.md` point here.
 
 A passing test's `tmp_path` tree is removed; a failing test's is kept for inspection
 (`tmp_path_retention_policy = "failed"` in `pyproject.toml`). Run with
@@ -48,10 +51,6 @@ one of them before each test runs, so a variable already set in your shell can n
 the suite asserts. A test that needs one set must set it explicitly with `monkeypatch` rather
 than relying on inheriting it.
 
-That gate also runs secret detection (`gitleaks`, `detect-private-key`), GitHub Actions
-security/correctness checks (`zizmor`, `actionlint`), and `check-toml`/a `uv.lock`-in-sync
-check, alongside the usual formatting and type checks.
-
 ## Preparing a pull request
 
 Describe the problem, the resulting behavior, and the checks you ran. Link the related
@@ -60,11 +59,11 @@ Use an area-prefixed imperative commit subject, for example `store: preserve his
 and sign off each commit as described below.
 
 CI runs lint on every PR push. On a pull request that is ready for review (not a draft),
-on `main` and before publishing, it also runs the full suite on Linux/Python 3.13 and 3.14
-and a selected native Windows
-core/MCP suite on both versions; see [platform coverage](docs/getting-started/installation.md#platform-coverage).
-If your change touches paths, permissions,
-subprocesses, or shell commands, describe any additional platform checks you performed.
+on `main` and before publishing, it also runs the full suite on Linux with Python 3.13 and
+3.14 and a selected native Windows core/MCP suite on both versions; see
+[platform coverage](docs/getting-started/installation.md#platform-coverage). If your change
+touches paths, permissions, subprocesses, or shell commands, describe any additional
+platform checks you performed.
 
 ## Ground rules
 
@@ -89,6 +88,22 @@ is a maintainer task: see [`docs/reference/releasing.md`](docs/reference/releasi
 We use the [Developer Certificate of Origin](https://developercertificate.org/). Add
 `Signed-off-by: Your Name <you@example.com>` to each commit (`git commit -s`).
 
+## Security gates
+
+`uv run pre-commit run --all-files` runs secret detection (`gitleaks`, `detect-private-key`),
+GitHub Actions security and correctness checks (`zizmor`, `actionlint`), `check-toml` and a
+`uv.lock`-in-sync check, alongside the formatting and type checks.
+
+The Gitleaks commit hook scans staged content even when every changed path is excluded from
+formatting, including `.sidegraph/`; `--all-files` does not turn it into a scan of committed
+history. CI additionally scans all history reachable from `HEAD`, merge changes included,
+with the same pinned scanner. Findings are redacted. To run that scan yourself, use a full
+checkout (CI rejects shallow history):
+
+```bash
+uv run pre-commit run gitleaks-history --hook-stage manual --all-files
+```
+
 ## Reporting bugs
 
 Open a GitHub issue with: what you ran, what you expected, what happened, and your