sidegraph 0.9.0__tar.gz → 0.11.0__tar.gz

{sidegraph-0.9.0 → sidegraph-0.11.0}/.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
         "source": "local",
         "path": "./plugin/sidegraph"
       },
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors."
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors."
     }
   ]
 }

{sidegraph-0.9.0 → sidegraph-0.11.0}/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     {
       "name": "sidegraph",
       "source": "./plugin/sidegraph",
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors.",
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors.",
       "homepage": "https://github.com/SantyagoSeaman/sidegraph"
     }
   ]

{sidegraph-0.9.0 → sidegraph-0.11.0}/AGENTS.md

@@ -31,8 +31,9 @@ Tests/fixtures: `tests/`; plugin skills/configuration in `plugin/sidegraph/`.
 Python 3.13+; `uv`:
 
 - `uv sync --locked`: install dependencies.
-- `uv run pytest tests/test_store.py -q`: focused tests.
-- `uv run pytest -q`: full suite; CI covers 3.13/3.14.
+- `uv run pytest tests/test_store.py -q`: the touched test file while editing (`-x`, `--lf`).
+- `uv run pytest -m "not slow"`: the broader pre-push check; skips the subprocess-heavy tests, but still takes minutes.
+- `uv run pytest -q`: full suite; run it once before a commit or PR, not while editing. CI runs it again (3.13/3.14).
 - `uv run pre-commit run --all-files`: shared lint/format/type/secret-scanning gate (also
   runs `gitleaks`, `detect-private-key`, `zizmor`, `actionlint`, `check-toml`, and a
   `uv.lock`-in-sync check).

{sidegraph-0.9.0 → sidegraph-0.11.0}/CHANGELOG.md

@@ -7,6 +7,282 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-10-09
+
+### Changed
+
+- **`index.db` no longer creates and deletes its journal in every write transaction.** SQLite's
+  default rollback mode (`DELETE`) created `index.db-journal` at the start of each write and
+  removed it at the end, and the hooks write on every tool call, so one store produced
+  hundreds of thousands of file-system events an hour. Every connection that writes now runs
+  `journal_mode=TRUNCATE`: the same rollback journal, locking and crash safety, but the journal
+  is emptied rather than deleted, so a 0-byte `index.db-journal` stays beside `index.db`
+  (gitignored by `index.db*`, as before). Each transaction still writes, truncates and syncs
+  that file, so the events do not vanish: they fall most for back-to-back writes (tests, bulk
+  imports: about nine times fewer on the journal) and by about a third for hook traffic.
+  Read-only connections still write nothing, and there is normally no `-wal`/`-shm`; an index
+  that another connection has pinned in WAL stays in WAL, which Sidegraph tolerates. A crash
+  mid-transaction still leaves a non-empty journal that the next writer rolls back.
+
+### Fixed
+
+- **The `UNANCHORED` line of `sidegraph-bootstrap` now names the graph in use.** It always said
+  to run `graphify update .`, which rebuilds only the default graph, so with `--graph` or
+  `$SIDEGRAPH_GRAPH` elsewhere the advice could not make the next run write the document. It now
+  uses the same step as the `ANCHORS` line: `rebuild the graph at <path> and rerun` for a custom
+  graph, `run `graphify update .` and rerun` for the default one.
+- **A fresh `sidegraph-bootstrap` run now lists the store's creation marker as changed.** The
+  `CHANGED` lines and `--report` named `format` and `.gitignore` but not the committed
+  `stamping_live_since` file the same run created.
+- **`sidegraph-bootstrap` now says what is wrong when a ratified or revived record is out of the
+  graph's reach.** For an accepted candidate with no anchor in the current graph whose content
+  is already stored (ratified in place, or revived from a rejected record), every rerun used to
+  print `ANCHORS incomplete: accepted candidate has unresolved or ambiguous anchors`,
+  `PROOF incomplete: selected decision did not surface` and a `RESUME` line that could never
+  succeed, and exit 2. The anchors are now judged by whether the
+  record still surfaces through production retrieval, the same test as `PROOF`: when it does
+  not, the run still exits 2 but prints ``ANCHORS      incomplete: stored record <id> for
+  <source> has no anchor in the current graph; run `graphify update .` and rerun``, a matching
+  `PROOF` reason and a `NEXT` line with that command instead of `RESUME`; once the graph has the
+  node, the rerun exits 0. The exact `RESUME` stays when something a resume can fix (a failed
+  write, missing host wiring) is also wrong, and with `--graph` the line names the graph to
+  rebuild instead. The `--report` file carries the same remedy. A written record with an
+  unresolved backticked mention keeps its old message.
+- **A directory named like a record no longer makes the whole store unopenable.** A directory
+  (or a dangling or looping symlink) called `.x.json`, or `01ABC.json`, in `decisions/`,
+  `facts/`, `domains/`, `entities/` or `initiatives/` (or in `bindings/` under a safe name, or
+  `archive/` as `*.jsonl`) crashed every open of the store, so every hook and MCP call failed
+  (`IsADirectoryError` for a directory, `Too many levels of symbolic links` for a looping
+  link), and a FIFO there blocked the open for ever. The reload now skips any entry that is not
+  a regular file before reading it, lists it in the skipped files with the reason `not a
+  regular file`, and the startup warning names it; the other records load and the next open
+  takes the fast path. `sidegraph-verify` reports such an entry once, as `unsafe-record-id`
+  for an unsafe record name and as `parse-error` (`bad-archive-segment` in `archive/`,
+  whatever the segment's name) otherwise, and no longer blocks on a FIFO, including
+  `--against` when a tracked file was replaced by one. A stale directory or looping symlink
+  named `*.tmp` no longer fails the open either. `sidegraph-stats` no longer ends in a
+  traceback on a looping link, and no longer reports the index as behind for ever because of a
+  dangling symlink. The skip reason for a file with an unsafe name now says `unsafe filename`
+  instead of "id 'A' does not match the filename".
+- **`sidegraph-prepare-commit-msg` no longer leaves its candidate block in `git commit -m`
+  messages under the `pre-commit` framework.** The framework passes the hook only the message
+  file and hands git's source in `PRE_COMMIT_COMMIT_MSG_SOURCE`, so the hook always saw "source
+  absent" and wrote its `# Sidegraph: uncomment the trailers…` and `# Sidegraph-Decision: …`
+  lines, which `-m` commits keep. With exactly one argument the hook now reads the source from
+  that variable (unset or empty means a plain commit); with two or three arguments, as raw git
+  passes them, the arguments still win.
+- **The hook entry points answer `--help` instead of running.** `sidegraph-session-start --help`
+  ran the SessionStart hook in the current directory and wrote into its `index.db`, and the other
+  three hook scripts (`sidegraph-stop`, `sidegraph-pre-tool-use`, `sidegraph-subagent-start`)
+  ignored their arguments the same way, while `sidegraph-prepare-commit-msg --help` printed
+  nothing and `sidegraph-mcp --help` started the server. Each now prints a short usage text for
+  `-h` or `--help` and exits 0 before it reads stdin, opens the store or writes anything. Any
+  other argument to a hook script is a usage error on stderr with exit 2. The git hook
+  `sidegraph-prepare-commit-msg` stays fail-open: it prints the same error for an unknown option
+  or a fourth argument but exits 0 and leaves the message untouched, so `git commit` never fails
+  because of a stray `args:` entry; git's one to three positional arguments are unchanged. Hosts call the hook scripts without
+  arguments, so nothing a host runs changes.
+- **`sidegraph-bootstrap` now converges when an accepted candidate has no anchor.** A document
+  with no backticked symbol and no node in the graph (typically one newer than the last graph
+  build) was never written, yet stayed pending: every run, `--resume` included, ended
+  `partial-recoverable` or `incomplete` with exit 2 and a `FAILED REF <none>` the operator
+  could not act on. Review now flags it with a `no-anchor` warning, and apply skips it by name
+  on an `UNANCHORED` line with its source path (`skipped_unanchorable_keys` in the report object)
+  and counts it as neither durable nor pending, so it no longer keeps the run partial. A run
+  where every approved candidate is skipped this way writes no record and ends as a diagnostic
+  that exits 0. It keeps the checks a run with records has, except the anchor and proof ones:
+  the store reopens and verifies clean, the host integration is verified, and `--report` is
+  written. A missing host integration or a store violation exits 2 instead (`STORE
+  incomplete`, with `RESUME`, or `sidegraph-verify` for a violation), as does an anchored
+  candidate kept proposed. Run `graphify update .` (or rebuild the `--graph` file) and the next
+  run writes it.
+  `sidegraph-import` is unchanged.
+- **`sidegraph-verify` now reports a domain whose `parent_id` is not a domain, or whose parent
+  chain loops.** The store refuses to write either, but a hand-edited domain with
+  `parent_id: "not-a-domain"` passed `sidegraph-verify` and `sidegraph-doctor` with exit 0. A
+  `parent_id` that names no domain, hot or archived, is now a `dangling-parent`, and a parent
+  chain that comes back to itself (a domain that is its own parent included) is one
+  `parent-cycle` per cycle, at the domain with the smallest id on it. A superseded, dropped or
+  compacted parent still counts as existing, so a history written through the tools stays
+  clean, and a parent held by a file skipped for its name is not reported twice. A non-string
+  `parent_id` stays a `parse-error` (a `bad-archive-segment` in an archive segment).
+- **A record directory the process cannot list or search is reported as unreadable, not as
+  missing records.** With `decisions/` at mode 000, `sidegraph-verify` printed a
+  `dangling-fact-support` for every fact and `--against` an `illegal-deletion` for every
+  record, as if the store had been tampered with. `sidegraph-verify` and `sidegraph-doctor` now
+  stop with one `store not readable` line naming the directory and exit 1, before any
+  cross-reference or deletion check runs. `sidegraph-stats` likewise says `cannot read the
+  store index` instead of `no store index` when the store directory cannot be searched, and no
+  longer ends in a traceback when a record directory cannot be listed. An empty record
+  directory without the search bit is reported the same way.
+- **`sidegraph-verify` reports only `unsafe-record-id` for a record file the store skips for
+  its name or id.** A copy such as `decisions/.x.json` was also reported as
+  `filename-id-mismatch` and `duplicate-ulid`, and a file with a safe name but an unsafe id as
+  `filename-id-mismatch` too, though the store never indexes either. A file with an unsafe
+  name that was not valid JSON, not UTF-8 or not an object showed only `parse-error`, and the
+  same went for a `bindings/` file that was not a JSON list, so the real problem, the name,
+  went unreported. The name is now checked before the content, in every record directory. A
+  file skipped for its name no longer counts as a second copy of a record, but a record that
+  points at its id is not reported either: renaming the file back is the only fix.
+- **`sidegraph-compact` no longer warns "DIFFERENT content" for a hot file that only lacks
+  newer keys.** A decision or domain written before `ratified_at`, `ratified_by` or
+  `provenance.commit` existed has no such keys, while its archive line, dumped from the model,
+  carries them as `null`. The raw comparison read that as a difference, kept the hot file and
+  repeated the warning on every index rebuild and every later compact. The visible damage was
+  that `sidegraph-verify` then exited 2 with a `duplicate-ulid` for each kept hot file, so the
+  store-lint gate failed after a compact. A key the hot file lacks now matches an explicit
+  `null` or an empty list or object in the archive, recursively, as `sidegraph-verify
+  --against` already treats it. The match is one-directional: a key only the hot file holds, at
+  any depth and whatever its value, still warns and keeps the file, so a field written by a
+  newer version is never lost to a compact by an older one.
+- **`sidegraph-doctor` keeps its `auto share` and `auto supersede rate` lines on a hand-edited
+  archived record.** An archived decision, a fact or a domain whose `status` was a list or a
+  dict made the auto-share tally raise, and doctor swallowed the error and dropped both lines
+  without a word. The bad value now counts as not retired and the lines print. Any other error
+  in the ratification lines is no longer swallowed.
+- **`sidegraph-verify` no longer crashes on a non-string `supersedes`.** A hand-edited record
+  whose `supersedes` was a list or a dict ended the run with a `TypeError` and lost every
+  other violation. The bad value is now reported as the violation it is and the run goes on.
+- **`sidegraph-verify` no longer crashes on an unhashable `supports` item, a status in
+  `--against`, or the malformed id of a deleted record.** Each used a raw hand-edited value as a
+  set member or lookup key; the run died with exit 1 where it should find the violation and exit
+  2. A malformed old status in `--against` is now reported as an illegal status jump.
+- **A symlinked store directory now stops `sidegraph-verify` and `sidegraph-doctor` at the
+  link.** Verify reported the link but still read through it: `facts -> decisions` linted every
+  decision as a fact, a link out of the store linted foreign files, and a linked-out `entities`,
+  `decisions` or `archive` made references into it look dangling. Both commands now report the
+  `symlinked-store-entry` findings, skip every other check (doctor's advisory checks and
+  `--against` included) and print one line saying so in text output; the exit code stays 2. An
+  `--against` ref that does not resolve, or a store outside git, is still checked first and exits
+  1 without reporting the links. A
+  symlinked `format` marker is no longer read, so its target's text cannot reach a CI log. A bindings file with
+  an unsafe name no longer also reports its entities as dangling, since the store skips that
+  file whole.
+- **`sidegraph-verify` and `sidegraph-doctor` report a store directory they cannot search as
+  `store not readable` on every Python.** With the store directory (or a parent) lacking the
+  search bit, for example `chmod 000` or `chmod 600 .sidegraph`, Python 3.14 reported
+  `unknown-schema-version … format marker missing` or `store directory not found` with exit 2
+  or 1, which read as a bad schema version or a missing store; Python 3.13 already printed
+  `store not readable (…)` with exit 1. Both commands now look the directory and its `format`
+  marker up with `os.stat`/`os.lstat`, which raise on every Python, and take the exit-1 path.
+  A directory that is searchable but not listable (`chmod 300`) is still checked normally.
+  The MCP `verify_store` tool now raises on 3.14 as it did on 3.13 instead of reporting
+  `unknown-schema-version`, and a store path that is a symlink loop reports the OS error
+  (`Too many levels of symbolic links`) instead of `store directory not found`, still with
+  exit 1.
+- **`sidegraph-doctor` no longer crashes on a list or dict `status` or `entity_id`.** A
+  hand-edited decision whose `status` was a list or a dict, or an anchor-set entry whose
+  `entity_id` was one, made the dangling-record, unreferenced-entity, expired-open-validity,
+  never-surfaced and code-drift checks raise a `TypeError`. The run exited 1 and lost the whole
+  report, including the `parse-error` that `sidegraph-verify` found for the same file, and the
+  hooks that swallow the error silently switched the code-drift line off for every record. The
+  bad value is now skipped by those checks and reported once, by the model check, so the run
+  exits 2 with the rest of its findings.
+
+## [0.10.0] — 2026-10-04
+
+### Added
+
+- **Every MCP tool now carries annotations, so a host's auto-reviewer stops rejecting memory
+  reads.** In the field, Codex's auto-reviewer rejected 20 `get_task_context` calls, and each
+  one lost memory for that step: an unannotated tool takes the MCP defaults (destructive,
+  open-world), and the review's verdict then depends on the prompt. The seven tools that never
+  change a tracked file are read-only; the other 17 are non-destructive, closed-world local
+  writes. No tool sends anything off the machine and none deletes a record. A test runs the
+  read-only tools on a store where a lazy sync would adopt a moved symbol, and fails if one of
+  them changes a tracked file, so the annotation cannot drift from what the tool does. See the
+  [reference](docs/reference/mcp-tools.md#annotations) and the
+  [Codex page](docs/integrations/codex.md#the-auto-reviewer-and-memory-reads).
+- **The seed tools accept the argument names agents try, and every tool names its parameters in
+  an error.** `get_task_context`, `query_structure` and `query_decisions` accept `paths` (as
+  `files`) and `seeds`; each seed goes to `files` when it looks like a path and to `entities`
+  otherwise. `task` is refused with a line saying there is no free-text query. Any other
+  unknown argument, on any tool, is an error that names it and lists the tool's real parameters;
+  FastMCP's own error named the argument but not the parameters.
+
+### Changed
+
+- **`retrieve_decisions` no longer returns the whole store.** One call returned a full dump of
+  every visible decision: about 143,000 tokens on a store of 260 records, more than a host would
+  show, and in a field report most agents passed `include_superseded: true` and then either
+  printed the dump or filtered it by hand. The call now has two answers.
+  - With no narrowing filter it returns an **overview**: the total, counts by status and kind
+    (superseded and rejected records included, so the counts say that history exists), and the
+    newest records as compact rows (`id`, `kind`, `status`, `title`, `valid_from`).
+  - With a narrowing filter it returns **full records**, gotchas and lessons first and newest
+    first, cut at `limit` (default 25, at most 100) or `budget_chars` (default 24,000, at most
+    60,000), whichever comes first. A `hint` says what cut the list, or why it is empty.
+  - The filters are new arguments, and they combine with AND: `status` and `kind` (a string or a
+    list), `files`, `query` (every word must occur in the record's text) and `ids` (exact record
+    ids, superseded ones too). `include_superseded` keeps its meaning: it widens the overview's
+    `newest` and a filtered call that has no `status`.
+  - `files` are read the way `get_task_context` reads them: a basename, a suffix, a directory or
+    a letter-case slip works. `unresolved_files` lists, for each path nothing could read (at most
+    ten, with `unresolved_omitted` counting the rest), why (`ambiguous`, `directory-too-large`,
+    `not-in-graph` or `no-graph`) and the candidates to pass instead.
+  - **The return type changed from a list to a JSON object, sent once as a single text block
+    with no structured copy**, so `budget_chars` is the real cost on every host. A client that
+    read the list now reads `decisions` of a filtered answer. The proposal policy is unchanged
+    and applies to every shape.
+  - The `check-plan`, `explain-why`, `triage-drift` and `heal-anchors` skills now call it with a
+    filter, and a test fails if a skill calls it without one. See the
+    [reference](docs/reference/mcp-tools.md#retrieve_decisions).
+
+### Fixed
+
+- **A fault converting a reviewed item in `sidegraph-bootstrap` now prints the RESUME line.** The
+  conversion of each reviewed item, and the check that its ref still matches the candidate,
+  ran outside the per-item error handling. A fault there, after an earlier item had been
+  written, left `apply_review` without a report: an `AssertionError` ended the run as a
+  traceback, a `ValueError` was reported as a failure before anything was written, and neither
+  printed `RESUME`, though canonical files were already on disk. The fault now takes the path a
+  write error takes: the run stops, reports `partial-recoverable` with the durable candidates and
+  the failing ref, and prints the resume command. A fault on the first item, before anything is
+  written, now exits 2 with `STORE incomplete`, the failing ref and the resume command, where a
+  `ValueError` used to exit 1 with an `ERROR` line; the terminal shows the failing ref and not the
+  reason.
+- **`sidegraph-import --dry-run` now says what auto-ratification would do.** Both import paths
+  decided auto-ratification only after a real write, so under a non-`manual`
+  `SIDEGRAPH_RATIFY_POLICY` a dry run could not show which records a real run would land
+  accepted without a human: on one fixture it reported 0 where the real run auto-ratified 2. The
+  dry run now runs the same eligibility gate on the record the write would produce and reports
+  the result in a new `would_auto_ratify` field on `ImportReport` and `DocImportReport`, and as
+  `auto_ratify_eligible` on each dry-run item. `auto_ratified` keeps its meaning, transitions
+  that actually happened, so it stays 0 in a dry run.
+  - **Behaviour change:** under a non-`manual` policy the summary line gains `would
+    auto-ratify M` before `(skipped:` and an eligible item line ends with ` [auto]`. Under
+    `manual` both are unchanged. A dry run still never carries the real run's `auto-ratified K`.
+  - The count is eligibility, not a guarantee: a real run's transition can still fail, for
+    example on a race or a refused cascade.
+  - A key repeated within one run no longer counts twice in the dry run. Two rationales with the
+    same title in one file count once. A document ref met more than once (one file named twice, a
+    directory plus a file inside it, or a live and an archived copy that a profile maps to one
+    ref) is classified against the records the earlier copies would have left there, as the real
+    run sees them: an identical repeat is skipped, a differing one supersedes, and a copy after a
+    `rejected` first copy is a fresh write. Two rare shapes can still differ in the
+    `superseded`/`skipped` split, not in the eligibility count where checked: a ref met three
+    times with the first content returning, under an auto policy, and a repeat with no anchor of
+    its own.
+- **`find_entity` no longer calls a dangling record a decision.** Each binding was labelled
+  `fact` if a fact lookup found it and `decision` otherwise, so a binding whose record exists in
+  neither table (a record file removed by hand, or lost in a merge) came back as a decision that
+  `get_decision` could not fetch, and each binding cost a query of its own. The types of all of an
+  entity's bindings now come from one read of the index, and a binding with no record reports
+  `record_type: "unknown"`. The value is additive: a client that handles `decision` and `fact`
+  is unaffected. `get_entity_history` uses the same read and still skips such a binding. See the
+  [reference](docs/reference/mcp-tools.md#find_entity).
+- **A document status like `should not be rejected` no longer lands `rejected`.** The check for
+  a turned-down status saw a negation only as `not` and one space directly before the word, so
+  `should not be rejected`, `not  rejected` (two spaces), `never rejected` and `isn't rejected`
+  all read as rejections, and a false `rejected` lands closed and invisible to retrieval. A
+  negation is now `not`, `never` or a word ending `n't` within the three words before the word in
+  the same clause. A clause ends at `,` `;` `.` `:`, a pipe, a slash, an em or en dash, or a spaced
+  hyphen or `->`, so `not reviewed, rejected`, `Not accepted — rejected` and `Won't do / rejected`
+  still read as rejections, as does `not rejected, rejected`. A conjunction does not end a
+  clause: `Not adopted and rejected` reads as negated, and lands accepted unless `--propose` or
+  a draft marker sends it to the ratification queue. See the
+  [reference](docs/reference/cli.md#sidegraph-import).
+
 ## [0.9.0] — 2026-10-04
 
 ### Added

{sidegraph-0.9.0 → sidegraph-0.11.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.9.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.11.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
@@ -98,8 +98,9 @@ See [`docs/concepts/data-model.md`](docs/concepts/data-model.md) for the record
 ```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                      # run tests
-uv run pytest tests/test_store.py -q
+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)
 ```

{sidegraph-0.9.0 → sidegraph-0.11.0}/CONTRIBUTING.md

@@ -20,10 +20,16 @@ consequence for you:
 git clone https://github.com/SantyagoSeaman/sidegraph.git && cd sidegraph
 uv sync                        # runtime + dev dependencies (Python 3.13+)
 uv run pre-commit install      # once per clone — the lint gate runs before each commit
-uv run pytest -q               # full suite must be green
+uv run pytest tests/test_store.py -q -x --lf   # while editing: the touched file
+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, exactly what CI runs
 ```
 
+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
+`-o tmp_path_retention_policy=all` to keep every test's tree.
+
 The suite is hermetic to `SIDEGRAPH_*` environment variables: `tests/conftest.py` strips every
 one of them before each test runs, so a variable already set in your shell can never change what
 the suite asserts. A test that needs one set must set it explicitly with `monkeypatch` rather

{sidegraph-0.9.0 → sidegraph-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.9.0
+Version: 0.11.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
@@ -82,7 +82,9 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -172,6 +174,10 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -215,7 +221,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -247,16 +253,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -269,7 +281,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.9.0 → sidegraph-0.11.0}/README.md

@@ -52,7 +52,9 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -142,6 +144,10 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -185,7 +191,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -217,16 +223,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -239,7 +251,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.9.0 → sidegraph-0.11.0}/SECURITY.md

@@ -25,10 +25,21 @@ Sidegraph is a local-only tool. Its entire data surface:
   the visualization, OKF export and bootstrap-report commands write to the output paths you
   give them; and the optional `sidegraph-prepare-commit-msg` git hook, once you install it,
   adds commented decision trailers to the commit message file git hands it
-  (normally `.git/COMMIT_EDITMSG`). Beyond those, the only filesystem writes are the standard config
-  snippets you install yourself (`.mcp.json`, hook entries) — Sidegraph touches nothing
-  else. See [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full
-  layout.
+  (normally `.git/COMMIT_EDITMSG`). Three more writes sit outside the repository's own
+  files. `sidegraph-init --hooks` (or a yes to its refresh question) writes a helper script
+  and a marked block in three git hooks (`post-commit`, `post-merge`, `post-checkout`) under
+  `.git/hooks/`. When `core.hooksPath` is set, `sidegraph-init` writes only the helper (to
+  `.git/hooks/`) and prints the lines to add to your hooks by hand. While it runs, the helper
+  also keeps a lock, a flag file and a log in the git directory. `sidegraph-init --no-hooks`
+  writes the git config key `sidegraph.graphRefresh` to the repository's own config, and
+  `sidegraph-init --remove-hooks` takes the blocks, the helper and that key out again. The
+  SessionStart hook writes one 40-character commit id to
+  `${XDG_CACHE_HOME:-~/.cache}/sidegraph/launch-commit`, and only when the running package was
+  installed from the canonical `git+https://github.com/SantyagoSeaman/sidegraph.git@main`. That
+  covers the plugin and the manual `uvx --from …@main` recipe. A PyPI, tag, SHA or editable
+  install never writes it. Beyond those, the only filesystem writes are the standard config
+  snippets you install yourself (`.mcp.json`, hook entries). See
+  [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full layout.
 - **Network:** none. No remote telemetry, no phone-home, nothing leaves your machine. Local
   retrieval telemetry is recorded in the gitignored `index.db` by default (which records
   were shown and which files were touched, never uploaded); set `SIDEGRAPH_TELEMETRY=off` to

{sidegraph-0.9.0 → sidegraph-0.11.0}/docs/concepts/mind-model.md

@@ -105,7 +105,7 @@ write below — the three raw authoring paths underneath it are:
    asked to) names a domain directly, optionally nesting it under a `parent_slug`.
 
 All three land `status=proposed`. **Every path passes through the same ratification gate** —
-the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, kept for one release)
+the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, still kept)
 and the `sidegraph-ratify` CLI, which list and accept/drop decisions *and* domains side by
 side. By default no path bypasses human review, including bootstrap: a fresh repo can
 propose dozens of domains from its community structure in one command, but nothing is named