sidegraph 0.6.0__tar.gz → 0.8.0__tar.gz

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

@@ -7,6 +7,327 @@ 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
+
+- **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.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.6.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.6.0 → sidegraph-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.6.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
@@ -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.8.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.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.6.0 → sidegraph-0.8.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.8.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`