sidegraph 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -7,6 +7,201 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-10-02
+
+### Changed
+
+- **The hooks and the MCP server look a missing relative store up inside the repository.** The
+  precedence between `--db`, `SIDEGRAPH_DIR`, `SIDEGRAPH_DB` and the default is unchanged, and a
+  store that exists where its relative path is anchored still wins. What is new: when a relative
+  `SIDEGRAPH_DIR` (or the default `.sidegraph`) does not exist there, the three hooks and the MCP
+  server visit the parent directories, nearest first, up to and including the repository root (the
+  nearest directory holding a `.git` entry, a directory or a file), and use the first store found.
+  The lookup never leaves the repository (a `.git` entry at your home directory or above it is not
+  a repository root, so a dotfiles repository does not turn `~/.sidegraph` into every project's
+  store) and does not run for `--db`, an absolute `SIDEGRAPH_DIR`, `SIDEGRAPH_DB`, a value with a
+  `..` part, or an anchor that is a symlink. The CLI, `sidegraph-init`
+  and `sidegraph-bootstrap` are unchanged: from a subdirectory they still need `--db`. To keep the
+  old outcome on a host surface, pass an absolute `SIDEGRAPH_DIR`.
+
+### Fixed
+
+- **A SessionStart hook registered twice on one host no longer injects the map twice.** Two
+  copies firing for one session at once both read the old duplicate-check ledger and both emitted;
+  the check now decides and stamps inside one write transaction, and a duplicate still answers
+  without waiting for a lock. The ledger keeps one row, so a repeat is still let through when
+  another session starts in between, or when two sessions with doubled hooks start together.
+- **Sync's moved rung adopts only a real move.** When an anchor's file is gone, sync looks the
+  name up across the whole graph and follows a unique hit to its new file. That lookup ignores
+  case and decoration, and the check behind it (the old path is out of `HEAD`, the new one is in
+  it) did not ask whether the new path was there before. A type deleted together with its file
+  could therefore be re-anchored onto an unrelated file that held an old member of the same name:
+  a deleted `Priority` followed `.priority` into another file, silently rewriting the entity's
+  committed `descriptor.file_path`. Two rules now close it. The hit must be the same name once
+  the call decoration (`()`, a leading `.`) is stripped from both sides, with case kept. And git
+  must show the new path arriving in the change that removed the old one: the mainline commit that
+  deleted the old path (a branch merged with `--no-ff` counts as one change) must have a first
+  parent without the new path and must hold it itself. With `SIDEGRAPH_TRUST_DIRTY_TREE=on` and the
+  old path still in `HEAD`, the new path must be absent from `HEAD`. Every git failure refuses, as
+  does a history with no deletion in it, so a move out of a path git never held (a gitignored
+  directory) and a move that a shallow clone cannot prove now end `orphaned`, which
+  `sidegraph:heal-anchors` repairs, instead of being adopted. An uncommitted delete onto a path
+  that is already in `HEAD` is `orphaned` too, not remembered as a move waiting for a commit: no
+  commit can make it one. The search matches the old path literally (a path such as
+  `app/[id]/view.tsx` is not a glob) and ignores `log.showSignature`.
+
+  Some real moves are refused as well, because git's history alone does not show them as one
+  change. Each ends `orphaned` and `sidegraph:heal-anchors` re-anchors it:
+  - the new file added in one commit and the old one deleted in another on the first-parent line,
+    including a branch merged fast-forward or rebase-merged;
+  - a second move before any sync ran (`A` to `B` to `C` while the descriptor still names `A`);
+  - an old path that was re-added and then deleted again.
+
+  To check what an earlier release adopted, list the descriptor rewrites:
+  `git log -p --diff-filter=M -- .sidegraph/entities/ | grep -E '^(commit |[-+]\s+"file_path")'`.
+  A rewrite is a real move only if the new path was added by the commit that deleted the old one
+  (`git log --first-parent -m -1 --diff-filter=D -- <old path>` finds that commit; the new path
+  must be missing from its first parent and present in it). Re-anchor a wrong one by superseding
+  the record with fresh anchors.
+
+- **The `SessionStart` instruction names a call the tool accepts, and a domain's mistake count
+  counts what the domain holds.** The standing line told the agent to call
+  `get_task_context(seeds)`, but the tool takes `files` and `entities` and rejects anything else,
+  so an agent that followed it made a call that failed validation. It now says
+  `get_task_context(files=[…])` with repo-relative paths, points at the check-plan skill before a
+  non-trivial change when it is available, and says to load the tool first if the host lists it
+  only by name. Separately, the per-domain count in the `SessionStart` map read "0 mistake(s)"
+  over a domain whose gotchas were anchored to its own code, because it counted only decisions
+  tagged to the domain itself. It now counts the accepted `gotcha`, `lesson` and `constraint`
+  decisions that `drill_down` serves for the domain, so the two show one number. The map's cache
+  records the store's digest, so a retrieval call on an unchanged store no longer rebuilds it, and
+  `SessionStart` reads the unratified list without building the whole map. The bindings table gains
+  an index by entity (an existing store gets it on its next open), which takes a rebuild of the map
+  from about 0.1 s to under 0.03 s on a real store, so the cost of a session start is what it was
+  before the count changed, also right after a store change and in a linked worktree. A worktree
+  builds its map with the main checkout's graph reader, so it counts the same decisions the main
+  checkout does. A map written by a path that has no graph reader (ratify, capture) leaves out
+  decisions anchored to a whole document until the next sync.
+
+- **A Claude Code subagent gets its own read nudges, and its touches are told apart.** A
+  subagent's hook payload carries its parent's session id plus an `agent_id` of its own, and
+  the `PreToolUse` nudge keys were per session: once the main agent had been nudged, every
+  subagent it started read anchored files blind. Each agent, the session's own and every
+  subagent, now gets one generic and one path-specific nudge. The
+  keys are claimed in a single statement, so a subagent's parallel opening reads cannot both
+  nudge, and `SessionStart` expires keys older than 30 days. The `retrieval_events` journal
+  gains a nullable `agent` column, added to an existing index on its next open, that records
+  which subagent made a touch; the row stays under the parent's session, so `sidegraph-stats`
+  counts the same sessions as before. Only `agent_id` counts, never `agent_type`: a main
+  session started with `claude --agent <name>` is still the session's own agent.
+
+- **An anchor written `Type.member` now resolves to the member.** Graphify labels a method
+  `.playClip()` and links it to its type, an agent writes `AudioPlayback.playClip`, and the two
+  never met: the anchor was born orphaned, and a seed naming it never reached the record, which
+  surfaced only through its community, as an unratified proposal. With a `file_path`, a name
+  with no exact match now falls back to a member of the named type in that file. It is for code
+  identifiers only (prose, a numbered heading or a hyphenated file name never reads as a
+  member). The name is split at the last `.`, `::` or `#` and the member is compared with its
+  case kept. A candidate that an edge ties to a different type is refused, and the answer stays
+  orphaned, never guessed, when several remain or when the file holds a case-only twin of the
+  member (a struct `Message` beside a method `.message()`, which the store treats as one
+  anchor). Without a file, and for a path-qualified name (`src/pkg/mod.py`), nothing changes.
+  On the read path a seed that names a stored anchor, and every node a seed resolves to, now
+  map to their store entities by the engine mapping, in the neighbour walk as well, so such a
+  record ranks as a mistake or decision again. The first `sidegraph-sync` after the upgrade
+  reruns once on its own (the sync stamp now carries a resolver revision, which a report does
+  not show) and heals the orphans this left behind. The skills and guides no longer say
+  `Type.member` names never resolve; the bare name with its file stays the preferred form.
+
+- **A hook command that cannot start no longer blocks or loops the host.** On `Stop`, both hosts
+  feed a hook's stderr back when the hook exits 2: Codex continues the turn, and Claude Code
+  continues the conversation, and Claude Code also blocks the tool call on `PreToolUse`. `uv`
+  exits 2 on some of its own errors (a project it cannot find, a cache it cannot write) and `dash`
+  exits 2 when the `cd` fails, so a hook command that never reached Python could do exactly that,
+  over and over in a headless `codex exec` run. Every shipped hook command, in both plugins and in
+  the manual recipes in the docs, now ends with a guard: `Stop` and `PreToolUse` answer `{}`, and
+  `SessionStart` answers a one-line `systemMessage` that says the hook could not start and to run
+  the hook command in a terminal to see the error. A command that starts Python behaves as
+  before. **Codex users: approve the two hooks again once after updating.** Codex records trust
+  per hook definition and the definition includes its command, so the changed commands do not run
+  until you approve them in `/hooks` or at the next interactive session's trust prompt. **If you
+  wired the hooks by hand**, append the guard to your own commands in `.claude/settings.json` or
+  `.codex/hooks.json`; the recipes in the docs show it. The Codex page also now says how to run a
+  headless review without Sidegraph's hooks.
+- **The capture nudge now arms on Codex.** The Stop hook's substance gate understood only Claude
+  Code transcripts, so on a Codex rollout it counted zero prompts and never nudged: every Codex
+  session ended without the capture reminder. The gate now reads a rollout too. A person's prompt
+  is a user message that is not text Codex wrote itself (the project instructions and environment
+  blocks, plugin and skill blocks, an aborted-turn note, a Stop hook's own block reason fed back);
+  nor does an answer to the agent's question, which arrives mid-turn, count as one. Each prompt
+  counts once although Codex mirrors it as an event. A thread arms after two real prompts, never
+  on tool calls. Subagent threads, Codex's automatic reviewer and headless `codex exec` runs, including
+  ones started through the Codex TypeScript SDK, never arm, so a review panel's `-o` output is
+  never replaced by a continuation. The nudge text, the once-per-session ledger and the hook
+  definitions are unchanged, so Codex's trust in the installed hooks stays valid. Claude Code
+  sessions are counted exactly as before.
+- **A session started in a subdirectory no longer opens a second, empty store.** Claude Code sets
+  `CLAUDE_PROJECT_DIR` to the directory it was launched in, so a launch in `repo/pkg` with the
+  plugin active created `repo/pkg/.sidegraph` beside the repository's own store, and the session
+  saw no memory. The hooks and the MCP server now use `repo/.sidegraph`, record touches relative
+  to it (`pkg/a.py`, so they join the anchors) and keep the nested-store case (`.config/sidegraph`)
+  repo-relative. The hooks also read the graph the store's project holds, as the CLI and the MCP
+  server do, so a store in a nested directory finds its own `graphify-out/graph.json`; a relative
+  `SIDEGRAPH_GRAPH` is no longer looked up under `$CLAUDE_PROJECT_DIR`. A store the old behaviour
+  already created is not touched: when the store a session uses is empty and the repository's
+  store above it holds records, `SessionStart` adds one line naming both. Remove the empty
+  `<subdirectory>/.sidegraph` to use the repository's. A stray store that holds any record (one
+  proposed decision from an old capture is enough) is not reported and keeps hiding the
+  repository's: review it with `sidegraph-ratify --db <subdirectory>/.sidegraph`, record what
+  matters again in the repository's store, then remove the stray directory.
+
+- **A code graph that never caught up with `HEAD` now says so.** Nothing compared the commit
+  `graph.json` was built at (`built_at_commit`) with `HEAD`, so a graph stuck at an old commit
+  looked up to date for good, and every `get_task_context` call seeded with a file added since
+  returned a bare `No context found.` The comparison now runs in the engine reader and counts a
+  graph as stale only when a file it should hold changed or appeared since the build (a commit
+  touching only file types the graph does not hold does not, and a graph built from a dirty tree
+  and committed afterwards does not). It surfaces in four places:
+  - `SessionStart` adds one line when the graph is stale, with the rebuild command
+    (`graphify update .` from the repository root);
+  - `get_task_context` appends a `## Not in the code graph` block after its answer when a seed is
+    not a file the graph holds, saying whether the graph is stale, shows no committed change since
+    its build (the file may be newer than the build, or one the engine skips) or could not be
+    compared, or whether the path is a directory, missing or not a normalized repo-relative path
+    (an absolute path, `./x`). Seeds the graph holds leave the answer byte-identical and cost no git call;
+  - `sidegraph-doctor` reports a new advisory finding, `graph-stale`. **`sidegraph-doctor --check`
+    now exits `2` on a stale graph**; a CI job that rebuilds the graph before running doctor is
+    unaffected;
+  - `sidegraph-stats` adds a `stale:` continuation line under the GRAPH counts, and its `--json`
+    gains `graph.freshness`, `built_at`, `commits_behind` and `stale_files`.
+
+  The docs no longer call a missed refresh "self-healing": the lazy check re-syncs a graph that
+  was rebuilt, and only a rebuild fixes one that never was.
+
+- **A linked worktree reads the main checkout's code graph, and a missing graph is said.**
+  `graphify-out/` is gitignored, so a `git worktree add` checkout had the tracked store and no
+  graph, and `get_task_context` resolved nothing there. When the store's own graph is missing and
+  its repository is a linked worktree of a main checkout, the read tools (`get_task_context`,
+  `query_structure`, `query_decisions`, `drill_down`) and `SessionStart` now open the main
+  checkout's graph, found from the worktree's `.git` file alone (no git call). That graph is synced
+  index-only: a worktree's index starts cold, and without the derived state (domain communities,
+  community bindings, engine mappings) `drill_down` lost most of a domain's decisions and
+  `get_task_context` its `## Related` section. The sync never rewrites a tracked file (its moved
+  rung, the one step that can, abstains), so the worktree's store stays as git checked it out.
+  `SessionStart` builds the domain map in memory from the store, adds a line saying whose graph it
+  reads, and names the main checkout in its stale-graph line. `get_task_context` tells a file that
+  exists only on the branch apart from one the main checkout's graph is stale for. A file the
+  branch changed that the main checkout also has is described as it is in the main checkout (its
+  symbols and the edges between them), and nothing warns about it.
+  `sync_anchors`, `list_domain_candidates`, every write tool and every CLI default keep reading the
+  store's own graph. A bare repository (also one cloned into `x/.git`), a git directory that is
+  separate and not itself named `.git`, a submodule and a plain `git clone` have no main checkout
+  to borrow from.
+- **`get_task_context` says when there is no code graph at all.** With no reader and at least one
+  seed, the answer ends with a `## No code graph` block naming the path that was looked at and
+  how to build it, instead of an answer that looked like a search with no hits. A graph that is
+  there and cannot be read is reported as not readable, not as missing.
+
 ## [0.6.0] — 2026-10-01
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.6.0
+Version: 0.7.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
@@ -167,7 +167,7 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  next session ◀── SessionStart TOC            anchored to entities in the
  of named domains ◀── get_task_context ◀────── engine's graph (read-only);
  mistakes first        drill_down             re-anchored after refactors
- blind Read/Grep ──▶ nudged back to get_task_context (each form once per session)
+ blind Read/Grep ──▶ nudged back to get_task_context (each form once per agent)
 ```
 
 Two layers age differently: the **structure** layer (the code graph — entities,

{sidegraph-0.6.0 → sidegraph-0.7.0}/README.md

@@ -139,7 +139,7 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  next session ◀── SessionStart TOC            anchored to entities in the
  of named domains ◀── get_task_context ◀────── engine's graph (read-only);
  mistakes first        drill_down             re-anchored after refactors
- blind Read/Grep ──▶ nudged back to get_task_context (each form once per session)
+ blind Read/Grep ──▶ nudged back to get_task_context (each form once per agent)
 ```
 
 Two layers age differently: the **structure** layer (the code graph — entities,

{sidegraph-0.6.0 → sidegraph-0.7.0}/docs/concepts/anchoring.md

@@ -15,6 +15,22 @@ enclosing-module info, so `name` + `file_path` is all identity has to work with.
 (lowercase, strip a leading `.`, drop call-decoration like `()`), so `.foo()` in a decision's
 anchor matches the graph node named `foo`.
 
+**`Type.member` names.** Graphify labels a method `.foo()` and links it to its type with a
+`method` edge (an enum case with `case_of`), so a name written `Type.foo` has no exact match.
+When none is found and the descriptor has a `file_path`, `resolve()` falls back to the member.
+It is for code identifiers only: the owner (its last segment, so `Outer.Inner.foo` reads as
+`Inner`) and the member must both be identifiers, and the candidate must be a `code` node, so
+prose with a dot in it, a numbered heading or `verify-release.sh` never reads as a member.
+The name is split at its last `.`, `::` or `#`, the node in that file whose label is the member
+is found (case kept), a candidate the graph ties to a different type is rejected, and, of
+several, those tied to the named type are kept. Anything that does not narrow to exactly one
+node is `unresolved`, the orphaned, healable leaf a bare miss has always been, never
+`ambiguous`. So is a name with a case-only twin in the file (a struct `Message` beside a
+method `.message()`): the store dedups an anchor by its lowercased name, so the two spellings
+are one entity, and binding either node would put the other's record on it. Without a file the
+fallback never runs, and a path-qualified name (`src/pkg/mod.py`, which reads as the member
+`py`) still never resolves.
+
 ## Lazy `Entity` creation
 
 An `Entity` is created the first time a decision references it — via
@@ -121,8 +137,8 @@ node and a file node are both just nodes.
 The same pattern applies to `concept` nodes from the semantic pass: a concept has no stable id
 either, so **anchor concept + file together**, not the concept alone. Re-extracting an edited
 file can rename or drop the concepts inside it — the same churn a code refactor causes to
-symbol names — and the rebind ladder below handles it identically: exact match, then unique
-name-only match, then orphaned. No special-casing for concepts versus code symbols.
+symbol names — and the rebind ladder below handles it identically: exact match, then a unique
+same-name match in a file that arrived with the old one's removal, then orphaned. No special-casing for concepts versus code symbols.
 
 ## What happens on rename or move
 
@@ -137,10 +153,13 @@ remembered under `pending_uncommitted_moves` are still re-verified once `HEAD` h
    re-pointing](../guides/surviving-refactors.md#community-re-pointing)).
 2. **Ambiguous** — leaf bindings flip to `degraded`; the node mapping is left untouched
    (never guess); community is re-pointed if a shared one is still resolvable.
-3. **Moved** — exact fails but a name-only retry resolves uniquely, *and* the new file has
-   the same suffix as the old `descriptor.file_path` (e.g. `.py` -> `.py`, `.md` -> `.md`),
-   *and* the old `file_path` is confirmed gone from the checkout ->
-   `descriptor.file_path` is updated to follow the file, leaf bindings heal to `live`.
+3. **Moved** — exact fails but a name-only retry resolves uniquely, *and* the hit is the
+   same name (decoration such as `()` or a leading `.` stripped from both sides, **case
+   kept**), *and* the new file has the same suffix as the old `descriptor.file_path` (e.g.
+   `.py` -> `.py`, `.md` -> `.md`), *and* the old `file_path` is confirmed gone from the
+   checkout, *and* git's history shows the new file arriving in the same change that
+   removed the old one -> `descriptor.file_path` is updated to follow the file, leaf
+   bindings heal to `live`.
    **Suffix guard:** a unique name-only hit whose file suffix *differs* from the old one
    (e.g. a vanished code symbol whose name happens to collide with a doc heading) is a
    **collision, not a move** — it is never adopted, and falls through to orphaned instead.
@@ -148,6 +167,15 @@ remembered under `pending_uncommitted_moves` are still re-verified once `HEAD` h
    still there — a symbol renamed *inside* a surviving file is not a move, however unique
    the name-only hit elsewhere looks, and "can't verify" counts as "still there" (see [why
    `moved` checks the disk](../guides/surviving-refactors.md#why-moved-checks-the-disk)).
+   **Name guard:** the name-only lookup ignores case, so a deleted type `Priority` can find
+   an old member `.priority` in an unrelated file. That is a different symbol, not a move,
+   and is never adopted. **Arrival guard:** a new path that already existed before the old
+   one was removed is a collision, not a move. So is an old path git cannot account for
+   (never committed, or beyond the history a shallow clone holds): any git answer that is
+   not a clear yes refuses. A refused move falls through to orphaned, which
+   `sidegraph:heal-anchors` repairs.
+   This rung resolves by name only, so a `Type.member` anchor cannot follow its file being
+   moved; the bare member name can.
 4. **Orphaned** — nothing resolves; leaf bindings flip to `orphaned`. Sync still tries to
    derive the entity's current community from its surviving file's nodes (useful when a
    symbol renamed but its file didn't move); that derivation only happens when the file's

{sidegraph-0.6.0 → sidegraph-0.7.0}/docs/concepts/mind-model.md

@@ -39,19 +39,19 @@ that suffices:
    summary, a mistake count, and a subdomain count (see
    [retrieval](retrieval.md#sessionstart-toc)). This is what an agent reads before touching
    anything — "what areas does this project have, and what should I already know about each."
-   The mistake count is narrower than "mistakes in this area": it counts only decisions
-   Tier-1-bound to the domain's own `domain:<slug>` entity (captured, or re-anchored, after
-   the domain was ratified) — a gotcha anchored to a leaf entity that happens to live in the
-   domain still surfaces in that entity's task context, just not in this count.
+   The mistake count is what `drill_down` would serve for the domain: the accepted `gotcha`,
+   `lesson` and `constraint` decisions in the union described under `drill_down` below, so a
+   gotcha anchored to a leaf entity that lives in the domain is counted too. Proposed and
+   superseded records are not.
 2. **`drill_down(domain_slug)`** — walk one domain: its full summary, its accepted subdomains,
    a capped sample of the code/doc entities that currently belong to it, and the decisions
-   about it (mistakes first). Unlike the TOC's narrower mistake count, `drill_down`'s
-   `decisions` list is the **union** of decisions tagged directly to the `domain:<slug>` entity,
+   about it (mistakes first). Its `decisions` list is the **union** of decisions tagged
+   directly to the `domain:<slug>` entity,
    decisions anchored to any code/doc entity that lives in one of the domain's communities
    (a community-membership join, deduplicated), and decisions anchored to a whole *document*
    entity whose file_path is one of the domain's covered files — so a gotcha anchored to a leaf
    entity in the domain, or an imported ADR that anchored to a doc rather than the domain
-   abstraction, *does* surface here even though it isn't counted in the TOC. The document branch
+   abstraction, *does* surface here, and is counted in the TOC. The document branch
    matters specifically on doc corpora: `sidegraph-import --docs` anchors an ADR to the
    document's own file-level node, but Graphify clusters every doc file-level node into one hub
    community, so that node's community is essentially never among the domain's `communities`

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

@@ -16,12 +16,14 @@ whether the store has any accepted domains yet:
   first domain is ratified — no sync required, see [below](#when-the-toc-goes-live)): one line
   per accepted domain (title, one-line summary truncated to 100 characters, mistake count,
   subdomain count when non-zero), then initiatives, then global mistakes. This is what "the
-  mind model comes alive" means in practice. The per-domain mistake count
-  (`_domain_mistake_count`) is narrower than "all mistakes in this area": it counts only
-  decisions Tier-1-bound to the domain's own `domain:<slug>` entity, i.e. captured (or
-  re-anchored) after the domain existed — a `gotcha`/`lesson`/`constraint` anchored only to a
-  leaf entity within the domain still surfaces in that entity's `get_task_context` output, it
-  just doesn't add to this count.
+  mind model comes alive" means in practice. The per-domain mistake count is what
+  [`drill_down`](#drill_downdomain_slug--the-axis-1-operation) would serve for that domain:
+  the accepted `gotcha`/`lesson`/`constraint` decisions in the union of those tagged to the
+  domain's own `domain:<slug>` entity, those anchored to a code or doc entity that lives in one
+  of its communities, and, when a graph reader is on hand, those anchored to a whole document
+  it covers. Proposed and superseded records are not counted. A TOC built without a reader
+  (the ratify and capture paths) leaves out the document branch until the next sync pass that
+  has one.
 - **`top_tier_map(store, reader)`** — the legacy, nameless fallback: top communities by member
   count (labeled only by god-node name), initiatives, global mistakes. Runs on demand (no
   cache) whenever the store has zero accepted domains — a fresh repo, or one that hasn't
@@ -33,34 +35,41 @@ prepends it once, at the hook-assembly level, ahead of whichever renderer's text
 `render_toc`/`top_tier_map` stay pure content formatters (see
 [`reference/hooks.md`](../reference/hooks.md#sidegraph-session-start)). The instruction now
 covers every search surface, not just `Read`/`Grep`: *"When you need to find or understand
-code in this project, call `get_task_context(seeds)` before any grep or file search —
-decisions, gotchas and a domain map are indexed here."* Both degrade gracefully — an empty
+code in this project, call `get_task_context(files=[…])` with repo-relative paths before any
+grep or file search — decisions, gotchas and a domain map are indexed here. Before a
+non-trivial change, run the sidegraph check-plan skill if it is available. If the tool is
+listed only by name, load it first."* Both degrade gracefully — an empty
 store still gets the instruction plus just the header. The `SessionStart` hook itself never
 blocks startup: any failure, or a cache it can't parse, falls back to `top_tier_map` rather
 than crashing; any failure in *that* prints `{}` and exits 0.
 
 ### When the TOC goes live
 
-`build_toc(store, reader=None)` precomputes the cache from store content alone (domains,
-initiatives, global mistakes — no graph needed) and is written to `store` meta under the
+`build_toc(store, reader=None)` precomputes the cache from the store (domains, initiatives,
+global mistakes; a graph reader is optional and only adds the document branch of the mistake
+count) and is written to `store` meta under the
 `toc_cache` key (see [configuration](../reference/configuration.md#domain-sync-and-the-toc-cache))
 at two points:
 
 1. **Every completed `sidegraph-sync` pass** (fresh or forced) — after the domain-community
    refresh, so the cache reflects that pass's own updates. **Also on a skipped
-   (already-up-to-date) pass**, whenever at least one accepted domain exists: a content-only
-   change such as `add_decision` bound to an existing domain entity never moves
-   `graph_version`, so without this a lazy `sidegraph-sync` right after it would report
-   "up to date" and leave the cache stale until an unrelated domain accept/drop happened to
-   rebuild it.
+   (already-up-to-date) pass**, whenever at least one accepted domain exists and the store
+   changed since the cache was built: a content-only change such as `add_decision` bound to an
+   existing domain entity never moves `graph_version`, so without this a lazy
+   `sidegraph-sync` right after it would report "up to date" and leave the cache stale until
+   an unrelated domain accept/drop happened to rebuild it. Every retrieval call runs this
+   pass, and a build counts every domain's decisions, so the cache records the store's
+   canonical digest and an unchanged digest keeps it. A cache written without a graph reader
+   carries no digest and is rebuilt once.
 2. **Every `ratify` call (MCP tool or `sidegraph-ratify` CLI) that actually accepted or dropped
    at least one domain** — immediately, without waiting for the next sync. This is what makes
    `bootstrap → ratify` visibly turn the TOC on in the very same session, even when no graph
    sync is needed.
 
 A decisions-only ratify (no domain ids in the batch) does not rebuild the cache immediately.
-It can change a rendered mistake count; the next completed or skipped sync refreshes that
-count. Domain acceptance is the special case refreshed in the ratify operation itself.
+It can change a rendered mistake count; the next completed sync pass, or skipped one that
+finds the store changed, refreshes that count, and so does the count after `add_decision`.
+Domain acceptance is the special case refreshed in the ratify operation itself.
 
 ## `drill_down(domain_slug)` — the Axis-1 operation
 
@@ -77,8 +86,8 @@ an empty list with an explanatory `"note"` key — everything store-derived (`do
 
 ## `get_task_context`: seeded, budgeted, mistakes-first
 
-`get_task_context(seeds, store, reader, budget)` is the core UX: given what the agent is
-about to touch, return a compact slice of structure *and* memory, memory ranked so the things
+`get_task_context(seeds, store, reader, budget)` is the core UX (the MCP tool of that name
+takes the seeds as `files` and `entities`): given what the agent is about to touch, return a compact slice of structure *and* memory, memory ranked so the things
 most likely to save it from a repeat mistake come first.
 
 ### Seeds
@@ -89,6 +98,11 @@ A `Seed` is either:
   anchors (see [anchoring](anchoring.md#descriptors-name--file)); an ambiguous ref keeps
   *all* candidates rather than guessing or dropping the seed.
 
+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
+`Type.member` is found), and every node a seed resolves to is mapped to the entity the store
+last saw it as (`last_seen_node_id`), with the node's own label still looked up beside that.
+
 Seeds are explicit — there is no semantic/embedding query matching; the caller (typically an
 MCP tool call with `files=[...]` and/or `entities=[{"name", "file_path"}, ...]`) names exactly
 what it's working on.
@@ -295,13 +309,22 @@ a decision doesn't vanish just because its most precise anchor did.
 Before rendering, every retrieval-facing MCP tool — `get_task_context`, `query_structure`,
 `query_decisions`, and `drill_down` — plus the `SessionStart` hook calls `maybe_sync(store,
 reader)` — best-effort, wrapped so a sync failure degrades to un-synced retrieval rather than
-erroring. `maybe_sync` is itself cheap in the common case: it compares the graph's current
-version against the store's `last_synced_graph_version` meta stamp and skips the full pass if they match (an entity remembered under
+erroring. A linked worktree that reads the main checkout's graph because it has none of its own
+syncs it too, index-only: the derived state fills its cold index, and no tracked file is rewritten
+(the moved rung abstains; see
+[the Graphify integration](../integrations/graphify.md#linked-worktrees-read-the-main-checkouts-graph)).
+`maybe_sync` is itself cheap in the common case: it compares the graph's current
+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 missed post-commit hook is simply
-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)).
+[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
+`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
+reported separately, by comparing the graph's build commit with `HEAD` (see
+[the Graphify integration](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks)), and
+only a rebuild fixes it.
 
 ### Rendering
 
@@ -310,7 +333,17 @@ accepted inline `evidence:` lines nested under the decision they support), **Kno
 (accepted standalone facts — see above), **Structural map** (the budgeted subgraph around the
 seeds, rendered as pointers — `- name (file_type) [file_path:line]`, never inlined code),
 **Related**, then **Unratified proposals**.
-Missing sections are omitted; an empty result renders `"No context found."`.
+Missing sections are omitted; an empty result renders `"No context found."`. After the
+rendered text, `get_task_context` appends a `## Not in the code graph` block when a seed path is
+not a file the graph holds, saying why: a file that exists but is missing from a stale graph
+(rebuild it), from a graph with no committed change since its build (the file may be newer than
+the build and uncommitted, or sit on a path or have a type the engine skips), or a path that is
+not a normalized repo-relative path to a file (check it). In a linked worktree that borrows the
+main checkout's graph, a file that exists only on the branch gets one sentence saying the graph
+does not hold it, and the rebuild advice for any other file names the main checkout. With no graph
+at all and at least one seed, a `## No code graph` block names the path looked at and says to build
+it (or, when the graph is there and cannot be read, that it is not readable). `render()` itself
+does not produce either block.
 
 ## See also
 

{sidegraph-0.6.0 → sidegraph-0.7.0}/docs/getting-started/claude-code-setup.md

@@ -90,7 +90,7 @@ Add to `.claude/settings.json` (merge into an existing file):
         "hooks": [
           {
             "type": "command",
-            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-session-start"
+            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-session-start || printf '%s\\n' '{\"systemMessage\":\"Sidegraph: the SessionStart hook could not start (uv/uvx, network or project path); run the hook command in a terminal to see the error\"}'"
           }
         ]
       }
@@ -100,7 +100,7 @@ Add to `.claude/settings.json` (merge into an existing file):
         "hooks": [
           {
             "type": "command",
-            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-stop"
+            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-stop || printf '{}\\n'"
           }
         ]
       }
@@ -111,7 +111,7 @@ Add to `.claude/settings.json` (merge into an existing file):
         "hooks": [
           {
             "type": "command",
-            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-pre-tool-use"
+            "command": "SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-pre-tool-use || printf '{}\\n'"
           }
         ]
       }
@@ -121,7 +121,13 @@ Add to `.claude/settings.json` (merge into an existing file):
 ```
 
 From a source checkout, replace each `uvx --from git+... <entrypoint>` above with `uv run
---project /ABSOLUTE/PATH/TO/sidegraph <entrypoint>` (see the note in step 1).
+--project /ABSOLUTE/PATH/TO/sidegraph <entrypoint>` (see the note in step 1). Keep the trailing
+`|| printf …` on each command: Claude Code treats a hook that exits 2 with text on stderr as a
+block on `Stop` (it continues the conversation) and on `PreToolUse` (it blocks the tool call), and
+`uvx` exits 2 on some of its own errors, so without the guard a command that cannot start would
+block you instead of just doing nothing. The guard makes it exit 0 and answer `{}`, or, on
+`SessionStart`, a `systemMessage` telling you to run the hook command in a terminal to see the
+error (see [`reference/hooks.md`](../reference/hooks.md#if-you-see-this-message)).
 
 The env vars are inlined into the command because Claude Code hook entries have no separate
 `env`/`cwd` fields.
@@ -138,8 +144,9 @@ The env vars are inlined into the command because Claude Code hook entries have
   nudge text and the substance gate's mechanics.
 - `PreToolUse` redirects a blind `Read`/`Grep` on a source file toward
   `get_task_context`/`drill_down` with a one-line, non-blocking nudge: a generic form and a
-  path-specific form, each firing at most once per session on its own one-shot key, so a
-  session can see up to two, only when the store actually has decision memory to offer. Set
+  path-specific form, each firing at most once per agent on its own one-shot key, so the
+  session's own agent can see up to two, and so can each subagent it starts, only when the
+  store actually has decision memory to offer. Set
   `SIDEGRAPH_GREP_NUDGE=off` (alongside the other env vars in the command) to disable it.
 
 > **Don't also run `graphify claude install`.** It writes its own `PreToolUse` hooks into

{sidegraph-0.6.0 → sidegraph-0.7.0}/docs/getting-started/codex-setup.md

@@ -96,7 +96,7 @@ Create `.codex/hooks.json` in the repo:
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" && SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-session-start"
+            "command": "cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" && SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-session-start || printf '%s\\n' '{\"systemMessage\":\"Sidegraph: the SessionStart hook could not start (uv/uvx, network or project path); run the hook command in a terminal to see the error\"}'"
           }
         ]
       }
@@ -106,7 +106,7 @@ Create `.codex/hooks.json` in the repo:
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" && SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-stop"
+            "command": "cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" && SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-stop || printf '{}\\n'"
           }
         ]
       }
@@ -122,6 +122,14 @@ working on a non-git corpus too (Sidegraph doesn't require the corpus to be a gi
 [`integrations/graphify.md`](../integrations/graphify.md#non-git-and-doc-only-corpora)), where a
 bare `git rev-parse --show-toplevel` would fail and leave `cd` with no argument.
 
+The trailing `|| printf …` is a guard, and it should stay. On `Stop`, Codex feeds a hook's stderr
+back to the model when the hook exits 2, and `uv` exits 2 on some of its own errors (a project it
+cannot find, a cache it cannot write), so a command that never reaches Python could keep
+continuing your session. With the guard the hook exits 0 and answers `{}`. On `SessionStart` it
+answers a `systemMessage` telling you to run the hook command in a terminal to see the error
+(see [`reference/hooks.md`](../reference/hooks.md#if-you-see-this-message)). The same guard ends
+every hook command in the plugin; see [`integrations/codex.md`](../integrations/codex.md#hooks-ga).
+
 No `PreToolUse` entry is included above. Codex can invoke that event for local function tools,
 but it has no stable `Read`/`Grep` tool pair to which Sidegraph's Claude-specific redirect can
 attach. Therefore Claude Code's Read/Grep redirect nudge