sidegraph 0.7.0__tar.gz → 0.8.0__tar.gz

{sidegraph-0.7.0 → sidegraph-0.8.0}/CHANGELOG.md

@@ -7,6 +7,132 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.8.0] — 2026-10-03
+
+### Added
+
+- **`get_task_context` says where the memory is when your file has none.** A file seed the graph
+  lacks, or one that resolved with no current record anchored to it, now gets a `## Nearest anchored`
+  sentence naming up to three files that do carry records: the graph neighbours first (the two
+  with the most records), then the files under the nearest directory that has any, skipping a
+  directory that holds more than a quarter of all anchored files (and more than four) and never
+  the repository root.
+  When the answer has no decision memory at all, the records of those files follow under `##
+  Nearest anchored records (not anchored to your files)`, labelled as not about your files, with
+  the same supersede line the main answer carries. An empty answer carries the sentence under `##
+  Why this is empty`. At most three seeds get a sentence. The records count as shown in
+  `sidegraph-stats`, and the neighbour files are never recorded as seeds. See
+  [the tool reference](docs/reference/mcp-tools.md#the-nearest-anchored-records).
+
+- **Records that never reach the team are now visible.** A record follows the branch and
+  checkout it was written on, and on one field corpus two supersessions sat uncommitted for five
+  days and 32 proposals lived only on branches that `main`'s session start never saw. Two new
+  checks run at session start. `store-uncommitted` (degraded, with a notice, also in
+  `sidegraph-doctor` and `sidegraph-stats`) reports store files nobody committed for a day, aged
+  by the ULID in a new file's name (a `git stash` cannot rewrite it) and by the modification time
+  otherwise; fully staged files do not count, so `sidegraph-doctor --check` in a pre-commit hook
+  never blocks the fixing commit. `branch-only-records` (advisory) scans every unmerged local branch,
+  oldest first, for open records the default branch lacks (each counted once, for the newest
+  branch that holds it), and sends a notice when such a branch is more than a week old: the fix is
+  to merge it. The write tools (`add_decision`,
+  `supersede_decision`, `add_fact`, `supersede_fact`, `add_anchors`, `add_domain`,
+  `supersede_domain`, and the written elements of `propose_decisions` and `propose_domains`) add a
+  `commit_hint` to their result when the store is inside a git repository, except a store that is a
+  symlink to a directory outside it: git commits the link, not the records behind it. Where records
+  are written does not change. See the
+  [troubleshooting guide](docs/guides/troubleshooting.md#store-uncommitted) and the
+  [MCP tools reference](docs/reference/mcp-tools.md#commit-hint).
+
+- **Sidegraph tells you when it needs attention, not only the model.** One list of integrity
+  checks now runs at every session start and in `sidegraph-doctor` and `sidegraph-stats`. The model
+  still gets a status line per problem, with the five existing lines unchanged and in the same
+  order. Problems that need a person also reach you as a `systemMessage`, which Claude Code shows as
+  a warning: at most once a day for each check, again at once when a problem gets worse, and not
+  again once the check finds nothing. New checks: a store that cannot be opened (a merge conflict
+  left in `.sidegraph/`, a damaged index, a store written by another version) now says so and
+  names the fix instead of switching memory off silently; a missing or unreadable code graph;
+  open records whose every code anchor is orphaned (degraded, with a notice, when three or more were
+  written in the last 14 days; advisory otherwise); and store files the last reload could not
+  index. A proposal that has waited 30 days earns a notice too. `sidegraph-doctor` gains an
+  `orphaned-record` finding and, with no graph, a skipped-checks line (`"graph"` in `--json`'s
+  `skipped`) instead of a finding, so `--check` does not start failing CI jobs that run without
+  one. `sidegraph-stats` opens with a `HEALTH` line (`health` in `--json`). The checks, their
+  severities and fixes are in the new [troubleshooting guide](docs/guides/troubleshooting.md), and
+  the output is in the [hooks reference](docs/reference/hooks.md#notices-for-the-human).
+
+- **`sidegraph-init` asks whether to keep the code graph fresh, and installs the hook that does
+  it.** A graph nobody rebuilds goes stale, and on one field corpus it fell 314 commits behind
+  because the setup hint was printed and skipped. In a terminal, init now asks once (default yes);
+  `--hooks` installs without asking, `--no-hooks` declines and records it
+  (`git config sidegraph.graphRefresh false`), and `--remove-hooks` takes everything out and exits
+  without creating a store (it exits 1, and says the removal was partial, when a hook is a symlink
+  or has damaged markers and so keeps its block). The hook is a marked block in `post-commit`, `post-merge` and
+  `post-checkout`, inserted right after the shebang line so that a foreign hook that ends in `exit`
+  cannot skip it, plus a helper that rebuilds the graph in the background, in the main checkout
+  only (a linked worktree reads its graph), one rebuild at a time. It never replaces a hook: one that
+  is a symlink, not executable, CRLF or not a shell script is left alone and the line to add by hand
+  is printed. With `core.hooksPath` set it writes no hook file and prints the lines instead. Without
+  a terminal nothing is written, and a new advisory check, `refresh-hook-missing`, tells the model
+  to ask you, and tells you once a day, until the hook is installed or declined. A call you add by hand
+  counts only when its hook is executable and the call is not in a comment. The three flags are
+  a Committed surface ([stability](docs/reference/stability.md)); see
+  [keeping the graph fresh](docs/integrations/graphify.md#keeping-the-graph-fresh-git-hooks) and the
+  [troubleshooting guide](docs/guides/troubleshooting.md#refresh-hook-missing).
+
+### Changed
+
+- **`get_task_context` reads a wrong seed the way you meant it, and an empty answer says why.**
+  A seed the graph does not hold as written used to come back as "No context found." Now `./x.py`,
+  `x.py:12`, an absolute path inside the repository, a missing or invented directory prefix, a bare
+  file name, a directory, and a `Type.member` with no file are read through a short ladder, and a
+  `## How your seeds were read` block says what each one became and that a rewrite is a guess. A
+  file that exists on disk but not in the graph is never swapped for a namesake. A directory reads
+  as up to eight files, or is listed when it holds more than 24. A path that differs from a graph
+  file only by letter case reads as that file, even on a case-insensitive filesystem. A path or
+  name that could mean several is reported and read as none. Guessed seeds rank in the related
+  tier below the seeds you got right. The not-in-graph block now names the normalised path, so
+  `./pkg/n.py` gets the stale-or-new advice instead of "check the path". A name with no file that
+  matches several symbols is no longer expanded to all of them: it is reported as ambiguous. A call
+  with no seeds at all names the accepted domains you can drill into. Telemetry records a rewritten
+  path under the path that was read and a directory under its normalised key, and keeps a seed
+  whose name starts with `..` that it used to drop. See
+  [the tool reference](docs/reference/mcp-tools.md#seeds-are-read-tolerantly).
+
+### Fixed
+
+- **A symlinked store's capture commit, code drift and refresh-hook check come from the project
+  that holds the link.** A store can be a symlink (`.sidegraph -> ../shared/store`). Its records
+  are anchored to code in the project that holds the link, but git resolved the link and answered
+  for the repository it points into: `provenance.commit` named that repository's `HEAD`, or was
+  empty when the target sits in no repository, so the code-drift check passed silently or never
+  ran, and the refresh-hook check read the wrong hooks. Capture now stamps the project's `HEAD`
+  (empty while the project has no commits), the code-drift check diffs it in the project's
+  repository, and the refresh-hook check reads the project's hooks and recorded choice, the ones
+  `sidegraph-init` writes. A store that is not a symlink behaves as before, and
+  `--against` (`sidegraph-verify`, `sidegraph-doctor`) still diffs the history of the repository
+  that holds the store's files. Three behaviour changes come with it. A store directory that is itself a repository or
+  submodule inside another repository now stamps the enclosing project's `HEAD` and measures drift
+  there, and its refresh-hook check now runs against the enclosing project; a top-level store
+  repository with no enclosing one is unchanged. A record stamped before the fix with the link
+  target's (or the nested repository's) `HEAD` now gets `sidegraph-doctor`'s existing
+  `code-drift: git unavailable — check skipped` note for that commit, where it used to pass
+  silently. And the records of a symlinked store now match in git-bindings rule (a) and in
+  `sidegraph-blame`, which read `provenance.commit`. See [the store
+  format](docs/reference/store-format.md).
+
+### Security
+
+- **The lockfile moves `PyJWT` from 2.13.0 to 2.15.1 and `virtualenv` from 21.7.0 to
+  21.14.4.** The PyJWT 2.14.0 and 2.15.0 fixes cover one critical advisory (an asymmetric
+  PEM key with mutated whitespace skips the HMAC key-confusion guard), five high ones (key
+  material accepted as HMAC secrets, JWKS redirects, a BOM bypass) and several moderate
+  ones. The virtualenv fixes cover seed wheels that were not integrity-checked and
+  activation scripts that run commands embedded in a path or a prompt. PyJWT reaches Sidegraph only
+  through the MCP SDK's `crypto` extra, and Sidegraph never decodes a token; virtualenv is
+  a development dependency through pre-commit. The published package pins neither, so this
+  changes development and CI environments and installs made from `uv.lock`; a fresh install
+  already resolves fixed versions.
+
 ## [0.7.0] — 2026-10-02
 
 ### Changed

{sidegraph-0.7.0 → sidegraph-0.8.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.7.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.8.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.7.0 → sidegraph-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.7.0
+Version: 0.8.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

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/README.md

@@ -25,6 +25,7 @@ If the repository already has ADRs or specs, use the
 ## Operate and maintain it
 
 - [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).
 - [Import decision-shaped documents](guides/semantic-docs.md).
 - [See runtime cost and operational boundaries](reference/operations.md).

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/concepts/retrieval.md

@@ -95,8 +95,17 @@ most likely to save it from a repeat mistake come first.
 A `Seed` is either:
 - a **file path** — resolves to every anchorable node in that file, or
 - a **name (+ optional file_path)** — an entity ref, resolved the same way capture resolves
-  anchors (see [anchoring](anchoring.md#descriptors-name--file)); an ambiguous ref keeps
-  *all* candidates rather than guessing or dropping the seed.
+  anchors (see [anchoring](anchoring.md#descriptors-name--file)). An ambiguous ref with a file
+  keeps *all* its candidates in that file. For the MCP tool `get_task_context`, an ambiguous ref
+  with *no* file is reported and not read: expanding it would be a silent guess.
+  `query_structure` and `query_decisions` still expand every candidate.
+
+The MCP tool reads a seed that the graph does not hold as written before giving up on it: a
+path with a stray `./`, a wrong prefix or a bare file name, a directory, and a `Type.member`
+with no file. Every rewrite is a guess and is named as one in the reply, the seeds that resolved
+as written come first, and a guess that could mean several things is listed and never read (see
+[`get_task_context`](../reference/mcp-tools.md#seeds-are-read-tolerantly)). The rule is still
+exact matching, never similarity.
 
 A seed reaches the store's entities two ways, and both count: a named seed that matches a
 stored anchor name is that entity directly (whatever the graph calls the node, so a stored
@@ -317,8 +326,9 @@ syncs it too, index-only: the derived state fills its cold index, and no tracked
 version (plus the reader's resolver revision, so an upgrade that changes how names resolve reruns the pass once) against the store's `last_synced_graph_version` meta stamp and skips the full pass if they match (an entity remembered under
 `pending_uncommitted_moves` is still re-verified once `HEAD` has moved).
 This is the self-healing mechanism described in
-[anchoring](anchoring.md#what-happens-on-rename-or-move): a graph that was rebuilt after a
-missed post-commit sync is caught by the next read, and it's what keeps each accepted domain's
+[anchoring](anchoring.md#what-happens-on-rename-or-move): a graph that was rebuilt, by the
+[graph refresh hook](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks) or by hand,
+with no sync after it, is caught by the next read, and it's what keeps each accepted domain's
 `communities` field current too (see
 [mind model](mind-model.md#how-domains-relate-to-engine-communities)). It cannot catch a graph
 that was never rebuilt, because the version it compares is the file's own: that case is

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/guides/retrieval-in-sessions.md

@@ -80,8 +80,16 @@ seeds that resolve to the right part of the graph:
 - An **entity seed** (`entities=[{"name": "Trader", "file_path": "trader/exec.py"}]`) resolves
   through the same name+file matching `add_decision`'s anchors use.
 
+A seed does not have to be spelled the way the graph spells it. `./trader/exec.py`,
+`trader/exec.py:42`, `exec.py` and an absolute path inside the repository all read as the same
+file, a directory (`trader/`) reads as up to eight of its files, and `Trader.place` finds the
+method with no file at all. Each such rewrite is a guess, and the reply says so in a
+`## How your seeds were read` block. When a name could mean several files or symbols, the tool
+lists them and reads none: pass the repo-relative path.
+
 Vague, non-task questions ("what does this project do") don't give the tool anything to seed
-on — be concrete about the file or symbol so the retrieval has something to resolve.
+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.
 
 ## Reading the output blocks
 
@@ -97,11 +105,14 @@ entirely if empty:
 | `## Related` | Accepted decisions reached indirectly, plus one-line superseded history for seed entities. |
 | `## Unratified proposals` | Proposed decisions and facts, always after accepted memory and omitted by the proposal policy when required. |
 
-If nothing resolves at all, the tool returns the literal string `No context found.` If a file
-you passed is not in the code graph, a trailing `## Not in the code graph` block says why: the
-graph is stale and needs `graphify update .`, the file is newer than the build or one the engine
-skips, or the path is not a normalized repo-relative path to a file (an absolute path, `./x` and a
-directory are not; see [`get_task_context`](../reference/mcp-tools.md#get_task_context)). With no
+If nothing resolves at all, the tool returns the literal string `No context found.`, followed
+by a block that says why. A seed that was read some other way than written gets a
+`## How your seeds were read` line (guessed, normalised, a directory, ambiguous, or a name that
+matches no symbol). If a file you passed is not in the code graph, a trailing
+`## Not in the code graph` block says why: the graph is stale and needs `graphify update .`, the
+file is newer than the build or one the engine skips, or the path names no file in the
+repository (see [`get_task_context`](../reference/mcp-tools.md#get_task_context)). A call with no
+seeds gets a `## Why this is empty` block. With no
 code graph at all, a trailing `## No code graph` block names the path that was looked at and says
 to build it: the graph is missing, so memory anchored to code could not be looked up. In a
 linked worktree the graph is the main checkout's, and a file that exists only on the branch is

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/guides/semantic-docs.md

@@ -31,7 +31,8 @@ graphify update .
 graphify extract . --backend claude
 ```
 
-`graphify update .` stays your per-commit default (wire it into the post-commit hook per
+`graphify update .` stays your per-commit default, and it is what the graph refresh hook runs
+after each commit in the main checkout (`sidegraph-init --hooks`; see
 [`integrations/graphify.md`](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks)).
 `graphify extract` is a separate, explicit step — run it after documentation changes
 meaningfully, not on every commit.

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/guides/team-workflow.md

@@ -33,6 +33,28 @@ might Graphify's `graph.json` — that one really is regenerated on every build;
 store is the opposite, deliberately durable, and is the one piece of Sidegraph's state that
 must survive a laptop being wiped.
 
+## Writes that never reach the team
+
+A record follows the branch and the checkout it was written on, because the store is committed
+with the repository. Two things strand one without anyone noticing:
+
+- **It was never committed.** An agent wrote a decision or a supersession into the checkout, a
+  later session took it for a foreign change and kept it out of every pull request, and it sat
+  there for days. Other checkouts and teammates never saw it, and a `git clean` or a re-clone
+  would lose it.
+- **It sits on a branch nobody merges.** A proposal made on a feature branch is invisible to
+  `main`'s session start, which counts the proposals it can see, until the branch merges.
+
+Sidegraph says so instead of changing where records go. A write tool's result carries a
+`commit_hint` when the store is inside a git repository ([MCP tools](../reference/mcp-tools.md#commit-hint)).
+At session start, two checks look: `store-uncommitted` reports store files that stayed
+uncommitted for a day, and `branch-only-records` reports records that exist only on unmerged
+local branches, with a notice when such a branch is more than a week old
+([troubleshooting](troubleshooting.md#store-uncommitted)). The fix is the ordinary one: commit
+`.sidegraph/` in the same pull request as the work that produced the records, and merge the
+branch that holds the rest. A pre-commit hook that runs `sidegraph-doctor --check` is safe, since
+files that are fully staged do not count.
+
 ## Ratification as part of PR review
 
 Because each decision is its own small file, a raw `git diff` on a branch that ratified

sidegraph-0.8.0/docs/guides/troubleshooting.md

@@ -0,0 +1,221 @@
+# Troubleshooting: what Sidegraph tells you, and what to do
+
+Sidegraph used to degrade without a word. The graph fell hundreds of commits behind, records
+were written with every anchor orphaned, a merge conflict in `.sidegraph/` switched memory off,
+and the only place any of it showed was a line in the model's context. Now one list of integrity
+checks runs at every session start and says what needs fixing, to the person as well as to the
+model.
+
+- **The model** gets one status line per problem, at every session start, in the context the hook
+  injects. The model forgets between sessions, so these are not rationed.
+- **You** get a notice, shown by the host as a warning, for the problems that need you. A notice
+  comes at most once a day for each check, comes again at once when a problem gets worse, and
+  stops when the check finds nothing. The text names the fix.
+
+`sidegraph-doctor` lists the same problems record by record, and `sidegraph-stats` leads with a
+`HEALTH` line. Both read the store without writing to it.
+
+## The checks
+
+| Check | Severity | What it means | Shows in | Fix |
+|---|---|---|---|---|
+| `store-unreadable` | broken | The store cannot be opened, so memory is off for the session | session notice and line | `sidegraph-verify`, or remove the damaged index |
+| `pending-ratification` | advisory | Proposals await a human's verdict | session line; a notice once the oldest is 30 days old | `sidegraph-ratify` |
+| `code-drift` | advisory | Records are anchored to code that changed after their capture | session line | `sidegraph-doctor` |
+| `graph-borrowed` | advisory | A linked worktree reads the main checkout's graph | session line | none needed |
+| `graph-stale` | degraded | The graph was built at a commit `HEAD` has moved past | session line and notice, doctor, stats | `graphify update .` |
+| `stray-store` | degraded | A subdirectory launch created a second, empty store | session line and notice | remove the empty store |
+| `graph-missing` | advisory | There is no graph, or it cannot be read | session line | `graphify update .` |
+| `orphaned-records` | degraded or advisory | Open records whose every code anchor is orphaned | session line; notice and stats when degraded; doctor | `sidegraph-doctor` |
+| `store-files-skipped` | degraded | Store files the last reload could not index | session line and notice, stats | `sidegraph-verify` |
+| `refresh-hook-missing` | advisory | No git hook keeps the code graph fresh | session line and notice | `sidegraph-init --hooks`, or `--no-hooks` to stop the reminder |
+| `store-uncommitted` | degraded | Store files nobody committed for a day | session line and notice, doctor, stats | commit `.sidegraph/` in a pull request |
+| `branch-only-records` | advisory | Records that exist only on unmerged branches | session line; a notice when a branch is a week old | merge the branch |
+
+Severity decides who is told. **Broken** means memory does not work now. **Degraded** means it
+works worse than it should, so you get a notice and `sidegraph-stats` shows it. **Advisory**
+means something worth knowing, which the model's line and the commands above report. Three
+advisory checks also send a notice, because the fix is yours to decide: a proposal queue that
+has waited 30 days, a missing refresh hook, and records on a branch that has not moved for a
+week.
+
+### store-unreadable
+
+Sidegraph could not open `.sidegraph/`. The notice names the store path, the exception and a fix
+that depends on the exception:
+
+- A merge conflict left in a record file, or a record that does not validate: run
+  `sidegraph-verify` from the repository root to find the file, then resolve the conflict.
+- A damaged or read-only `index.db`: it is derived and safe to delete. Remove
+  `.sidegraph/index.db` and start a new session; it is rebuilt from the committed files. When
+  there is no `index.db` to remove, or the database could not be opened at all (a read-only store
+  directory, a `.sidegraph` that is a plain file), the advice is the generic one below instead.
+- A store written by a different Sidegraph version: upgrade Sidegraph, or use the version that
+  wrote it. Migration tooling is deferred.
+- Anything else: `sidegraph-verify` gives the details.
+
+A lock that another process holds is not a broken store. The hook stays silent for it, and the
+next session start opens the store.
+
+### pending-ratification
+
+Proposals nobody has ratified. The model's line gives the counts and the age of the oldest. When
+the oldest is 30 days old, you also get a notice. Review the queue with `sidegraph-ratify`, or ask
+the agent to use the ratify tool. `SIDEGRAPH_RATIFY_NUDGE=off` silences both the line and the
+notice.
+
+### code-drift
+
+Records whose anchored files changed after their capture. The line says how many. It is the
+agent's work to supersede the ones that no longer hold, so there is no notice. `sidegraph-doctor`
+lists them as `code-drift` findings, and the `sidegraph:triage-drift` skill walks them.
+`SIDEGRAPH_DRIFT_NUDGE=off` silences the line.
+
+### graph-borrowed
+
+A linked worktree has no graph of its own and reads the main checkout's. Code that exists only on
+the worktree's branch is not in that graph. Nothing is wrong, and nothing needs doing unless you
+want the graph to include the branch: build one in the worktree with `graphify update .`.
+
+### graph-stale
+
+The graph's build commit is behind `HEAD`, and a file the graph should hold has changed or
+appeared since. Memory cannot see or anchor to code added after the build. Run
+`graphify update .` from the repository root. In a worktree that borrows the main checkout's
+graph, rebuild it there. A graph that cannot be compared with `HEAD` (no recorded build commit, a
+graph outside a git repository, git unavailable) is not reported, and a recorded notice survives
+the start where it could not be compared.
+
+### stray-store
+
+An older Sidegraph created an empty store beside the directory a session was started in, and the
+repository's own store, with the records, sits above it. The session uses the empty one. Remove
+the empty store, as the notice names it, to use the repository's.
+
+### graph-missing
+
+No code graph where Sidegraph looked, or one that could not be read. Memory still works from the
+store, but it cannot match files to records or anchor new ones. Build the graph from the
+repository root: `graphify update .`. This is advisory, because a corpus of documents only runs
+without a graph. It is a model line only, and `sidegraph-doctor` reports it as a skipped check,
+never as a finding.
+
+### orphaned-records
+
+Open decisions and facts whose every leaf anchor is orphaned: retrieval reaches them only through
+their file or domain. If the graph is stale, rebuilding it re-anchors them. Otherwise
+`sidegraph-doctor` lists each record as an `orphaned-record` finding, and the
+`sidegraph:heal-anchors` skill repairs them, by re-anchoring with `add_anchors` or by superseding a
+record whose code is gone.
+
+The severity depends on how old the records are. **Three or more written in the last 14 days** is
+degraded: anchoring is failing now, as when a batch of proposals lands with its anchors orphaned
+at once. Anything older is advisory, curation debt that does not need a notice. The thresholds are
+unmeasured beyond two points.
+
+The statuses live in the derived index and are recomputed by a sync. Right after a reload, such as
+a `git pull` that changed a record, every anchor reads live until the next sync, so the check does
+not run then and a recorded notice is kept. `sidegraph-doctor` lists `orphaned-records` among its
+skipped checks until then; `sidegraph-sync` recomputes the statuses.
+
+### store-files-skipped
+
+Files under `.sidegraph/` that the last reload could not index, usually because a record's id does
+not match its file name. They are left out of memory. The notice names the first file and the
+reason. Run `sidegraph-verify` to list them all, then fix or restore them with git.
+
+### refresh-hook-missing
+
+No git hook rebuilds the code graph when it goes stale, so it will fall behind as code changes.
+The helper `sidegraph-graph-refresh` is missing, or one of `post-commit`, `post-merge` and
+`post-checkout` does not call it (in the `core.hooksPath` directory when that is set). The
+model's line tells the agent to ask you and not to install anything unasked. Run
+`sidegraph-init --hooks` to install the hook, or `sidegraph-init --no-hooks` to stop the
+reminder (it records `sidegraph.graphRefresh=false` in the repository's git config; a global
+`false` works too). What the hook does and where it goes:
+[keeping the graph fresh](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks).
+
+If the hook is installed and the graph still goes stale, read `sidegraph-graph-refresh.log` in
+the repository's git directory (the output of the last rebuild), then re-run
+`sidegraph-init --hooks`: it rewrites the helper and clears a lock that a job which died left
+behind (the helper also clears one by itself, by its pid or, when the job never wrote one, after
+ten minutes). One case is not detected: after a reboot a recorded pid can belong to a live,
+unrelated process, and the hook then waits until that process exits.
+
+The check does not run in a repository without a graph, so a corpus of documents is never
+nagged, nor when the graph is somewhere other than `graphify-out/graph.json` at the main
+checkout's root, the only one the hook rebuilds. A linked worktree that borrows the main
+checkout's graph is checked, because the hooks are shared; one with a graph of its own, a store
+in a subdirectory, and a bare repository with worktrees (no main checkout) are not. A call added
+by hand to a hook counts as installed, which
+is how a hooks-manager setup (Husky, lefthook, pre-commit) clears it. A hook counts only when git
+would run it and the call would run: the file is executable and the helper's name is on a line
+that does not start with `#`, so a comment that names it, or a hook without the executable bit,
+leaves the reminder on. It has no doctor finding, because a CI checkout has no hooks.
+
+### store-uncommitted
+
+Files under `.sidegraph/` that nobody committed for 24 hours. A record follows the branch and the
+checkout it was written on, so one that stays uncommitted is invisible to every other checkout and
+teammate, and a `git clean` or a re-clone loses it. The text gives how many files there are, how
+old the oldest is and what kinds they are (decisions, facts, domains, bindings, entities, other),
+and names the path to commit. Commit `.sidegraph/` in a pull request, in the same change as the
+work that produced the records. The write tools remind the agent with a
+[`commit_hint`](../reference/mcp-tools.md#commit-hint).
+
+- **Age.** A new record or entity file is aged by the ULID in its name, which `git stash -u` and
+  `pop` cannot rewrite; a modified file, or anything under `bindings/`, by its modification time;
+  a deleted file by the modification time of its subdirectory, which is a lower bound. A name
+  that is not a plausible ULID (dated before 2020, or more than a day ahead of the clock) is aged
+  by its modification time too. New `archive/` files beside deleted records read as "a
+  compaction" (`sidegraph-compact`).
+- **Fully staged files do not count.** They are being committed now, so a
+  `sidegraph-doctor --check` in a pre-commit hook never blocks the commit that fixes the problem.
+  A file that was staged and then edited again still counts.
+- **Where it runs.** Not run outside a git repository, when `git` is missing or slower than two
+  seconds. Doctor lists one `store-uncommitted` finding at the store path, and `--check` exits `2`
+  on it. A fresh CI checkout has nothing uncommitted.
+
+### branch-only-records
+
+Open records that exist only on local branches that are not merged into the default branch. They
+reach it when the branch merges, which is normal for work in progress. The line names the number
+of records, how many await ratification, and up to three branches by their counts. A notice
+comes only when a branch holding records has a tip older than a week: that is work that may
+never merge. The fix is to merge the branch. Ratifying the records there does not help, because
+an accepted record on an unmerged branch is as stranded as a proposed one.
+
+- **The default branch** is `origin/HEAD` when it resolves (in a pull-request flow the local
+  `main` lags), otherwise the first of `origin/main`, `origin/master`, `main` and `master` that
+  exists. With none of them the check does not run.
+- **What counts.** Every record a branch adds under `decisions/`, `facts/` and `domains/`
+  whose status is not terminal, and which the default branch does not already hold (a branch that
+  was squash- or rebase-merged stays "unmerged" to git while its records are on the default
+  branch). The branch you are on is left out. A record counts once, for the newest branch that
+  holds it (a branch cut from another carries the first one's records too), and that branch's
+  copy decides its status.
+- **Delete branches you have squash-merged.** If the records were compacted away on the default
+  branch afterwards (`sidegraph-compact`), they no longer exist there, and the leftover branch
+  reads as holding records that never arrived.
+- **Cost.** Every unmerged branch is scanned, oldest first, within two seconds. A scan that runs
+  out of time says "at least" before the count and that the scan ran out of time; a partial scan
+  that found nothing is not run, so a recorded notice is kept.
+- It has no doctor finding, because a CI checkout has no local branches, and no stats item.
+
+## How a notice behaves
+
+- It comes **at most once every 24 hours** for each check. A second session start inside the day
+  still carries the model's line, and no notice.
+- It comes **again at once** when the check's severity is higher than the one last reported.
+- It **stops** when the check runs and finds nothing, and a problem that comes back after a fix is
+  reported at once. A check that did not run, because its evidence was missing or a switch is
+  off, changes nothing.
+- Two registrations of the hook for one session do not both notify.
+
+There is no switch for notices. The existing `SIDEGRAPH_RATIFY_NUDGE` and `SIDEGRAPH_DRIFT_NUDGE`
+still silence their own checks. The record of what was reported lives in the derived `index.db`,
+as `integrity_notice:<check>` meta rows, so deleting the index repeats the notices once.
+
+See [`hooks.md`](../reference/hooks.md#notices-for-the-human) for the exact output,
+[`cli.md`](../reference/cli.md#sidegraph-doctor) for the doctor findings and the stats `HEALTH`
+line.

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/integrations/claude-code.md

@@ -158,7 +158,10 @@ or blocks the tool call: any failure (or the store simply having nothing to offe
 ### Silent degradation
 
 All three hooks are written to **never crash the session** and never block a tool call. Any
-exception inside `session_start` prints `{}` (Claude Code proceeds with no injected context);
+exception inside `session_start` prints `{}` (Claude Code proceeds with no injected context),
+except that a store which cannot be opened prints a `systemMessage` naming the cause and the fix
+(and a model line saying memory tools will fail) instead, and a lock another process holds still
+prints `{}`;
 any exception inside `stop` prints `{}` (Claude Code proceeds to stop normally); any exception
 inside `pre_tool_use` — or the nudge conditions simply not holding — also prints `{}` (the
 tool call proceeds through the normal permission flow). A missing store, missing graph, or

{sidegraph-0.7.0 → sidegraph-0.8.0}/docs/integrations/graphify.md

@@ -176,9 +176,9 @@ and Graphify's is the noisier, unbounded one.
 install`** — you already have the graph-orientation and read-nudge behaviour, done more
 conservatively. If you specifically want Graphify's own `graphify query` reflex on top, keep
 its hooks but set `SIDEGRAPH_GREP_NUDGE=off` (see [`claude-code.md`](claude-code.md)) so the
-two don't double-nudge on reads. This is separate from `graphify hook install` (the
-[post-commit git hook](#keeping-the-graph-fresh-git-hooks) that rebuilds `graph.json`) — that
-one is orthogonal and fine to keep.
+two don't double-nudge on reads. This is separate from the git hook that rebuilds `graph.json`: Sidegraph installs its own
+([below](#keeping-the-graph-fresh-git-hooks)), which differs from Graphify's `graphify hook
+install` in rebuilding in the main checkout only.
 
 `graphify update .` prints "Re-extracting code files" / "Code graph updated" even on a
 pure-markdown corpus with no code files at all — expected engine chatter, not a sign the
@@ -190,29 +190,74 @@ by design, it is the only place Graphify specifics may live in Sidegraph.
 
 ## Keeping the graph fresh: git hooks
 
-Install Graphify's own hook once, in the target repo:
+Let `sidegraph-init` install the refresh hook, once, in the target repo. It asks, in a terminal,
+and `--hooks` installs without asking (`--no-hooks` declines, and records that so the
+reminder stops):
 
 ```bash
-graphify hook install    # post-commit (and post-checkout) → rebuilds graph.json
+sidegraph-init --hooks
 ```
 
-This installs a **code-only AST rebuild** (no LLM) into `.git/hooks/post-commit` as a marked
-block. Prose/ADR extraction is a model pass and is not re-run automatically — re-run
-`graphify update .` (or the `/graphify` skill's `--update` form) whenever the docs change.
-
-Chain Sidegraph's sync **after** Graphify's block, in the same hook, so the graph rebuild
-always finishes first:
-
-```bash
-# .git/hooks/post-commit, appended after Graphify's marked block:
-sidegraph-sync
-```
-
-This is a convenience, not a dependency: `sidegraph-sync` re-resolves anchors and skips the
-full pass when the graph version hasn't changed (entities remembered under
-`pending_uncommitted_moves` are still re-verified once `HEAD` has moved). Because the same `graph_version` check also runs
-lazily on every read path (`get_task_context`, `SessionStart`), a graph that was rebuilt while
-the hook missed its sync is caught by the next read, which re-syncs before serving context.
+It writes a small helper, `sidegraph-graph-refresh`, into the repository's `hooks/` directory
+(inside the common git directory, so every worktree shares it), and a marked three-line block
+into `post-commit`, `post-merge` and `post-checkout` that calls it. The helper runs
+`graphify update .`, a **code-only AST rebuild** (no LLM). Prose/ADR extraction is a model pass
+and is not re-run automatically: re-run `graphify update .` (or the `/graphify` skill's
+`--update` form) whenever the docs change.
+
+- **Which events.** After a commit, after a merge (a fast-forward `git pull` fires
+  `post-merge`, which Graphify's own hook does not cover) and after a branch switch. A file
+  checkout (`git checkout -- file`) and a `git switch -c` that stays on the same commit do not
+  rebuild.
+- **One graph.** The helper rebuilds `graphify-out/graph.json` at the main checkout's root, and
+  init installs it only where that is the graph the store reads. A store in a subdirectory, a
+  typed `--graph`, a linked worktree with a graph of its own and a bare repository with worktrees
+  (no main checkout) get `graph refresh hook: skipped`, naming the graph the hook would rebuild.
+- **The main checkout only.** A linked worktree reads the main checkout's graph (see
+  [above](#linked-worktrees-read-the-main-checkouts-graph)), so a commit in one does nothing.
+  Rebuilding there as well costs about 18 MB and 43 s for a cold build on one field corpus with
+  25 worktrees, and agents commit in worktrees constantly.
+- **In the background, one at a time.** Git never waits for the rebuild. A lock directory keeps
+  one rebuild running; a hook that fires while it runs makes it go once more when it finishes, so
+  the graph never settles on a tree older than the last request. A lock left by a job that died
+  is detected and cleared: by its pid, or, when the job died before writing one (a full disk, a
+  quota), by its age, ten minutes. `sidegraph-init --hooks` clears such a lock at once. One risk
+  remains: after a reboot a pid can belong to a live, unrelated process, and the hook then waits
+  until that process exits.
+- **Where the output goes.** The last rebuild's output is `sidegraph-graph-refresh.log` in the
+  common git directory (`.git/` in a normal clone).
+- **No `sidegraph-sync` in the hook.** The next memory call notices the new graph version and
+  re-anchors before it answers, the same lazy check described below. Chaining `sidegraph-sync`
+  into a hook would race the background rebuild.
+- **It never replaces a hook.** The block goes right after the hook's shebang line, so a
+  foreign hook that ends in `exit` or `exec` cannot skip it, and every other byte of the file
+  stays as it was. A second `--hooks` leaves the files byte-identical. A hook that is a
+  symlink, is not executable, has CRLF line endings or is not a shell script (a Python or Node
+  hook) is left untouched, and init prints the one line to add by hand. Damaged markers (a lone
+  marker, reversed markers, two pairs) are reported and left alone.
+- **`core.hooksPath`.** When it is set, a hooks manager such as Husky, lefthook or pre-commit
+  owns that directory and regenerates it, so init writes nothing there. It installs the helper
+  and prints the line to add to each of the three hooks in that directory; a call added by hand
+  counts as installed, provided the hook is executable and the call is not in a comment.
+- **Removal.** `sidegraph-init --remove-hooks` removes exactly the block's bytes (a file that
+  Sidegraph created is deleted, a foreign hook ends as it was before), deletes the helper and its
+  lock files, and clears the recorded choice.
+- **The reminder.** Without the hook, a session start tells the model and, once a day, you
+  (the `refresh-hook-missing` check in the [troubleshooting guide](../guides/troubleshooting.md#refresh-hook-missing)).
+  It stays quiet in a repository with no graph, and after `--no-hooks`.
+
+**Graphify's own hook** (`graphify hook install`) is not needed and is not what Sidegraph
+installs. It rebuilds in every linked worktree that commits, writes no `post-merge` hook, and
+appends its block after any existing content. If both are installed, the main checkout rebuilds
+twice on every commit (Graphify's lock serialises them), and linked worktrees rebuild too. Init
+reports it when it finds one, and never touches it; `graphify hook uninstall` removes it and
+leaves Sidegraph's block as it was.
+
+The lazy check keeps the store honest whichever way the graph was rebuilt: `graph_version` is
+compared on every read path (`get_task_context`, `SessionStart`), so a graph that was rebuilt in
+the background, or by hand, is caught by the next read, which re-syncs before serving context
+(entities remembered under `pending_uncommitted_moves` are still re-verified once `HEAD` has
+moved).
 
 A graph that was **never rebuilt** is a different case, and the lazy check cannot see it: it
 compares `graph.json` with the store's last sync, so a graph that stopped at an old commit