sidegraph 0.5.0__tar.gz → 0.7.0__tar.gz

{sidegraph-0.5.0 → sidegraph-0.7.0}/.github/workflows/ci.yml

@@ -108,45 +108,6 @@ jobs:
           base="$(git merge-base "origin/$GITHUB_BASE_REF" HEAD)"
           uv run sidegraph-verify --against "$base" --json
 
-  # A commit-msg hook (see .pre-commit-config.yaml's `no-session-links`) cannot see a pull
-  # request's description, so this is the PR-body half of the same owner ruling: never
-  # publish an external session link. Shares tools/check_no_session_links.py's pattern list
-  # with that hook, rather than a second copy, so the rule cannot drift between the two.
-  # `if: github.event_name == 'pull_request'` matters here specifically: this workflow is
-  # also invoked via `workflow_call` by publish.yml on a tag push, which carries no PR body.
-  # Lives in ci.yml, not its own workflow file: it is a lint-shaped gate exactly like the
-  # local corpus-leak/public-twins/shipped-links checkers, ci.yml already hosts other
-  # `pull_request`-only jobs (store-lint, anchor-health) with the identical self-guard shape,
-  # and a fourth workflow file would buy nothing a job here doesn't already give.
-  # Self-guarded like those checkers: tools/ is not in the public repo's release ALLOWLIST,
-  # so this exits 0 cleanly on an external contributor's PR there instead of failing on a
-  # checker that by design does not exist in that snapshot.
-  pr-description-link-gate:
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: Check PR description for forbidden session links
-        # The PR body is untrusted (attacker-controlled on a fork PR), so it goes through an
-        # env var rather than being interpolated into the script text via `${{ }}` — that
-        # would be a script-injection hole. `github.event.pull_request.body` is `null` for an
-        # empty description; GitHub renders that as an empty env var, and `printf '%s'` on an
-        # empty string just produces an empty file, which the checker reports as clean.
-        env:
-          PR_BODY: ${{ github.event.pull_request.body }}
-        run: |
-          if [ ! -f tools/check_no_session_links.py ]; then
-            echo "tools/check_no_session_links.py not present (public snapshot) — skipping"
-            exit 0
-          fi
-          printf '%s' "$PR_BODY" > "$RUNNER_TEMP/pr-body.txt"
-          python3 tools/check_no_session_links.py "$RUNNER_TEMP/pr-body.txt"
-
   # Recipe 1 self-applied: rebuild the graph from scratch and fail on attention findings
   # (stale decisions, empty/overbroad domains, slug conflicts, refresh failures). A
   # cache-less rebuild was verified label-identical to the local cached graph and the

sidegraph-0.7.0/.github/workflows/session-link-gate.yml

@@ -0,0 +1,76 @@
+# The PR half of the owner ruling "never publish an external session link", shared with the
+# `no-session-links` commit-msg hook (.pre-commit-config.yaml) through
+# tools/check_no_session_links.py, so the rule cannot drift between them. A commit-msg hook
+# cannot see a pull request's title or description, and a commit made without the hook never
+# passes through it, so this checks all three places text gets published:
+#   - the PR title and description, verbatim (lines starting with `#` are markdown headings
+#     there, not comments), and the title again because the default merge commit carries it;
+#   - the PR's recorded commit messages, exactly as they sit in history.
+# Its own workflow file, not a job in ci.yml, so `edited` can re-run it without re-running
+# the whole CI on every description edit. Every event for an open PR runs both steps: an
+# `edited` run that skipped the commit check would go green on the same head SHA and replace
+# a red run in the checks view. Edits to a closed or merged PR skip the commit check, so old
+# history is not re-checked. No `concurrency` block: with one, a later run could cancel an
+# in-flight `synchronize` run and leave the commits unchecked. The job takes seconds.
+# Fails closed: the checker ships in the public snapshot too, and a run without it fails
+# instead of skipping, so deleting or moving it cannot turn the gate green.
+# Actions are pinned to commit SHAs (the tag comment records the version).
+name: session-link-gate
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-description-link-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      # fetch-depth 0: the commit step needs the whole base..head range.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Check PR title and description for forbidden session links
+        # Title and body are untrusted (attacker-controlled on a fork PR), so they go through
+        # env vars rather than `${{ }}` in the script text, which would be a script-injection
+        # hole. `github.event.pull_request.body` is `null` for an empty description; GitHub
+        # renders that as an empty env var. Reported line numbers run two higher than in the
+        # body: the title and a blank line come first.
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          if [ ! -f tools/check_no_session_links.py ]; then
+            echo "::error::tools/check_no_session_links.py is missing; the session-link gate cannot run"
+            exit 1
+          fi
+          printf '%s\n\n%s\n' "$PR_TITLE" "$PR_BODY" > "$RUNNER_TEMP/pr-text.txt"
+          python3 tools/check_no_session_links.py --published "$RUNNER_TEMP/pr-text.txt"
+
+      - name: Check the PR's commit messages for forbidden session links
+        # Runs on every event for an open PR, description edits included: a green run with
+        # this step skipped would replace a red one on the same head SHA. A closed or merged
+        # PR (its commits predate this gate) is not re-checked. A SHA matches no pattern, so
+        # each reported line points into the commit named above it; on failure the step lists
+        # the `commit` start lines (SHAs and line numbers only, never the offending text).
+        if: github.event.pull_request.state == 'open'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if [ ! -f tools/check_no_session_links.py ]; then
+            echo "::error::tools/check_no_session_links.py is missing; the session-link gate cannot run"
+            exit 1
+          fi
+          git log --format='commit %H%n%B' "$BASE_SHA..$HEAD_SHA" > "$RUNNER_TEMP/pr-commits.txt"
+          python3 tools/check_no_session_links.py --published "$RUNNER_TEMP/pr-commits.txt" || {
+            echo "commit start lines in the checked log:"
+            grep -n '^commit ' "$RUNNER_TEMP/pr-commits.txt"
+            exit 1
+          }

{sidegraph-0.5.0 → sidegraph-0.7.0}/.gitleaks.toml

@@ -28,5 +28,6 @@ paths = [
   '''^tests/test_server_redaction\.py$''',
   '''^design/superpowers/plans/2026-07-06-capture-ratification\.md$''',
   '''^design/superpowers/plans/2026-07-10-facts-layer\.md$''',
+  '''^design/superpowers/reviews/2026-09-28-grok-whole-repo-review\.md$''',
   '''^src/sidegraph/viz/assets/vis-network\.min\.js$''',
 ]

{sidegraph-0.5.0 → sidegraph-0.7.0}/.pre-commit-config.yaml

@@ -115,10 +115,11 @@ repos:
         # nothing and would couple the gate to uv project discovery — which fails outright in a
         # tree whose pyproject uv cannot parse (the release script's own test fixtures).
         # The `test -f` guard exists because THIS FILE SHIPS: .pre-commit-config.yaml is in the
-        # release ALLOWLIST while tools/ is not, and the release script verifies the snapshot by
-        # running `pre-commit run --all-files` inside it. Without the guard, an always_run hook
-        # would look for a checker that by design does not exist there and fail every release,
-        # the public repo's CI, and every public contributor's first commit.
+        # release ALLOWLIST while tools/ ships only the session-link checker, and the release
+        # script verifies the snapshot by running `pre-commit run --all-files` inside it.
+        # Without the guard, an always_run hook would look for a checker that by design does
+        # not exist there and fail every release, the public repo's CI, and every public
+        # contributor's first commit.
         entry: bash -c 'test ! -f tools/corpus_leak.py || exec python3 tools/corpus_leak.py'
         language: system
         pass_filenames: false
@@ -139,8 +140,8 @@ repos:
         # AGENTS.public.md) with no base counterpart, or a plugin manifest that still points
         # at the working tree instead of the released package, would otherwise ship broken
         # and surface only when a consumer's install fails. Self-guarded like
-        # corpus-leak-gate: tools/ is not in the release ALLOWLIST, so this checker does not
-        # exist in the public snapshot or its CI.
+        # corpus-leak-gate: tools/ ships only the session-link checker, so this checker does
+        # not exist in the public snapshot or its CI.
         entry: bash -c 'test ! -f tools/check_public_twins.py || exec python3 tools/check_public_twins.py'
         language: system
         pass_filenames: false
@@ -150,8 +151,8 @@ repos:
         name: shipped-docs link check
         # A relative Markdown link that resolves in THIS repo can still 404 once the release
         # mapping is applied (design/whitepaper/draft.md -> docs/whitepaper/index.md, `.public.`
-        # twins renamed onto their base names, design/ and tools/ absent) — this catches that
-        # before the commit lands. Self-guarded: tools/ is not in the release ALLOWLIST.
+        # twins renamed onto their base names, design/ absent, tools/ reduced to the
+        # session-link checker) — this catches that before the commit lands. Self-guarded: tools/ ships only the session-link checker.
         entry: bash -c 'test ! -f tools/check_shipped_links.py || exec python3 tools/check_shipped_links.py'
         language: system
         pass_filenames: false
@@ -161,15 +162,15 @@ repos:
         name: no session links in commit message
         # Reads the commit message file git passes a commit-msg hook, never the changed
         # files — the forbidden patterns are tools/check_no_session_links.py's four
-        # session-link shapes, the same ones .github/workflows/ci.yml's
-        # `pr-description-link-gate` job checks against a PR body.
+        # session-link shapes, the same ones .github/workflows/session-link-gate.yml
+        # checks against a PR's title, body and recorded commit messages.
         # `stages: [commit-msg]` is load-bearing, not decoration: a hook with no explicit
         # `stages` inherits EVERY stage, and `pre-commit run --all-files` (CI's lint job, and
         # a developer's own habit) defaults to `--hook-stage pre-commit` — without this pin,
         # that plain run would try to execute this hook anyway, with no COMMIT_EDITMSG file
         # to check, and fail every lint run for a reason that has nothing to do with lint.
-        # Self-guarded like corpus-leak-gate: tools/ is not in the release ALLOWLIST, so this
-        # exits 0 cleanly in the public snapshot and on a public contributor's first commit.
+        # Self-guarded like corpus-leak-gate, though the checker does ship: the guard only covers a
+        # deleted checker, and the session-link-gate workflow is the gate that fails then.
         entry: bash -c 'test ! -f tools/check_no_session_links.py || exec python3 tools/check_no_session_links.py "$@"' --
         language: system
         stages: [commit-msg]

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

@@ -7,6 +7,440 @@ 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-verify` reports `unsafe-record-id`.** A record file, `bindings/` file or
+  archive line whose id is not a single safe path segment is now a finding, and a
+  non-string id in a record or archive file no longer crashes the run with `unhashable type`.
+- **`sidegraph-verify` reports a symlinked store entry as `symlinked-store-entry`.** One
+  violation per store-owned directory or file that is a symlink, so a committed link fails the
+  CI gate; `sidegraph-doctor` inherits it.
+
+### Changed
+
+- **A `--graph` typed as a relative path resolves against the shell in `sidegraph-ratify`
+  and `sidegraph-stats`.** It used to resolve against the store's project. The default and
+  `$SIDEGRAPH_GRAPH` still follow the store. The same holds in every command that reads a
+  graph, so the copy-and-sync workflow works with `--graph graphify-out/graph.json` typed from
+  the repository.
+- **A store in a nested directory needs an absolute `SIDEGRAPH_GRAPH`.** With
+  `SIDEGRAPH_DIR=.config/sidegraph` and a relative `SIDEGRAPH_GRAPH`, the CLI now looks for the
+  graph under `.config/` (the store's project) instead of using the shell's copy. A command
+  that needs the graph fails with a hint; `init`, `ratify`, `doctor` and `stats`, for which it
+  is optional, continue and print the hint (`stats` reports its graph metrics as unavailable). Set an absolute `SIDEGRAPH_GRAPH` or pass `--graph`. The MCP server now
+  follows the same rule (next entry); the hooks are unaffected.
+- **The MCP server reads the graph that belongs to its store.** A relative `SIDEGRAPH_GRAPH`
+  (or the default `graphify-out/graph.json`) used to resolve against the server's working
+  directory, so a store reached by an absolute `SIDEGRAPH_DIR`, or a store in a nested directory,
+  could be synced against one project's graph by the CLI and another's by `sync_anchors` and the
+  retrieval tools, and the store's graph version flipped back and forth. It now resolves against
+  the store's project, the same rule the CLI uses, and an empty `SIDEGRAPH_GRAPH` counts as unset.
+  With the default layout (`.sidegraph` in the project, the server started there) nothing changes.
+  A nested store needs an absolute `SIDEGRAPH_GRAPH`; `sync_anchors` reports `graph not readable`
+  with the path and names the graph it found beside the working directory, when there is one.
+- **A document is imported again once, if its `provenance.ref` changes.** A document
+  imported before this release from a subdirectory or by an absolute path is imported
+  again under its repository path. The old record stays. A leftover that is still `proposed` can be dropped with
+  `sidegraph-ratify --drop <id>`. An `accepted` leftover has no one-step retirement: leave
+  it, or supersede it by hand with `supersede_decision`, which writes a new record.
+- **`sidegraph-import --path` (and domain `--paths`) match on directory boundaries.**
+  `--path payments` no longer imports `payments_v2/b.py`, and a partial-name prefix such as
+  `--path docs/adr/00` matches nothing; a prefix matches a file under that directory or
+  that exact file. `--path ""` still matches everything, and mixed with a real prefix it is
+  ignored. The domain `--paths` help already behaved this way and now says so.
+- **The Stop hook skips the transcript of a session that is already captured.** It now peeks
+  at the capture ledger read-only before parsing the transcript, so every Stop after the
+  capturing one no longer re-reads the whole file.
+
+### Fixed
+
+- **The derived initiative names the store's repository branch.** It used to come from the
+  branch of whatever directory the MCP server or CLI ran in. An inherited `GIT_DIR` or
+  `GIT_WORK_TREE` no longer redirects either the derived initiative or the captured commit.
+- **A timestamp in the future no longer counts as fresh.** The capture session-id fallback and
+  the session attribution of retrieval telemetry treated a marker stamped ahead of the clock
+  as current; they now ignore it. The SessionStart dedupe still treats a same-session stamp
+  less than 60 seconds ahead as a duplicate (a parallel hook can write one), but a stamp
+  further ahead no longer suppresses the map until the clock catches up.
+- **Every CLI command that takes a store and a `--graph` pairs the store with its own
+  project's graph by default.** `sidegraph-sync`, `sidegraph-import` (both modes),
+  `sidegraph-domains bootstrap`, `sidegraph-doctor` and `sidegraph-init` (whose found/missing
+  line used the shell's path) read the default graph relative to the
+  shell, so `--db A/.sidegraph` run from project B stamped A's store with B's graph version
+  and could rewrite A's anchors, import decisions, or bootstrap domains from B's graph. The
+  default and `$SIDEGRAPH_GRAPH` (an empty value counts as unset) now resolve against the
+  store's project, as `sidegraph-ratify` and `sidegraph-stats` already did; a store reached
+  through a symlinked `.sidegraph` keeps the link's project. When the store's project has no
+  graph but the same path exists beside the shell (a store copied elsewhere), one stderr hint
+  names `--graph <path>`; when both exist, a note says which was used. Error lines name the
+  resolved path.
+- **`SIDEGRAPH_DB` naming a missing path no longer scaffolds its parent.** A missing
+  `SIDEGRAPH_DB=/proj/.sidegraph`, or a dangling link, resolved to `/proj` and a store was
+  created in the project root. Only a path ending in `.db` is rescued to its parent now; any
+  other missing path is used as given, and a dangling link fails to open without creating
+  anything.
+- **`sidegraph-sync --check` documents domain-refresh failures.** The help and the module
+  docstring omitted the finding that already makes `--check` exit 2.
+- **A move left `moved_uncommitted` is now re-verified after you commit it, even when the
+  graph was not rebuilt.** Committing a rename does not change `graph.json`, so the version
+  gate skipped every later sync and the leaf kept its old path until `--force`. Sync now
+  remembers such entities with the git `HEAD` it saw, and the first sync after `HEAD` moves
+  re-verifies just them (a narrow pass that leaves domain membership alone). The comment that
+  promised the next sync would heal it was wrong, and is corrected.
+- **A decision with two leaves in one community no longer loses that community's binding when
+  one leaf leaves it.** Both leaves share one Tier-1 `community:*` row, and a renumber that
+  moved one leaf orphaned the row the other still held, so the decision stopped surfacing for
+  that community. Sync now settles a record's community rows after every leaf has been
+  rebound, and a new row carries the moved leaf's relation instead of `affects`. Damage from
+  earlier syncs is repaired when a later repoint touches the record, or when the index is
+  next rebuilt from the committed files.
+- **Secret redaction covers quoted values and quoted keys.** `password: "one two"`,
+  `` token: `abc def` `` and `password = 'a b c'` were cut at the first space, leaving the rest
+  of the secret in the store, and `{"password": "hunter2 two"}` was not matched at all. A
+  quoted value is now taken whole, with any text glued to its closing quote, and a quoted
+  key matches too. JSON keys such as `"token_count"` now redact like the unquoted
+  `token_count:` already did. An escaped quote (`"alpha\" beta"`) does not end a quoted
+  value, and a quoted key stops at the next JSON field, so `{"password":"x y","reason":"z"}`
+  keeps `reason`.
+- **A decision whose attached fact failed is left proposed under an auto-ratify policy,** and
+  an auto-accepted fact's write-guard message points to `add_anchors` instead of a drop that
+  the store refuses.
+- **An initiative name is redacted before it becomes an entity, on every write path.** A
+  secret in `initiative`, or in a branch name the propose path derives one from, used to land
+  in the canonical `initiative:<name>` entity file. A blank or all-secret initiative now binds
+  nothing, and a padded name is trimmed (`"  proj  "` keys as `initiative:proj`).
+- **`add_decision` binds its initiative with no graph or no anchors.** The Tier-0 binding was
+  made only inside the per-anchor loop, so a call without a reader or without an anchor
+  dropped it silently.
+- **`add_domain`, `supersede_domain` and `sidegraph-domains add` redact the title and
+  summary.** Only `propose_domains` and the bootstrap did. The MCP results now carry
+  `redactions`, and the CLI prints a count line when it redacted something.
+- **`propose_decisions` dedups a decision on its redacted title.** A title that held a secret
+  was compared raw against the stored, redacted one, so proposing it twice wrote it twice.
+- **One failing draft no longer aborts a propose batch.** A step after the write (anchors,
+  initiative, tags, attached facts, auto-ratify) now leaves the result `written` with a
+  `reason`; an error before the write makes that draft `rejected`; each attached fact and each
+  domain is isolated the same way, and a failed TOC rebuild after `propose_domains` is
+  reported as a `toc:` warning. `KeyboardInterrupt` still propagates.
+- **A record id can no longer become a path outside the store.** Every canonical writer built
+  `<dir>/<id>.json` from the id as given, so an id like `../../x` wrote outside the store.
+  The store now refuses to write an id that is not a single path segment, and the OKF export
+  skips such a decision, fact or entity with a warning.
+- **A canonical file whose JSON id does not match its filename is skipped on reload, with a
+  warning on every open.** A file with a crafted id was indexed under that id, so one later
+  ratify could write outside the store. Duplicate ids let the later file silently win, and a
+  file with no id got a fresh ULID on every rebuild. Such files are now left out of the index
+  and named in a warning until they are fixed or removed. An existing index reloads once to
+  apply the rule. An archive line with an unsafe or non-string id is skipped instead of
+  making `Store()` fail.
+- **An interrupted legacy migration no longer loses its staged work.** The legacy file is
+  renamed to its backup only after the staged directories have moved in, so an interruption
+  leaves it in place and the next open migrates again. A bare-file migration, which has to
+  rename first, keeps its staging directory and leaves a sentinel so the next open says what
+  to do. A sentinel younger than 60 seconds means a migration is running now: the open
+  refuses with "retry in a minute" and touches nothing, and deleting that sentinel early is
+  unsafe. A legacy row with an unsafe id fails the migration before anything is written, and
+  a row whose JSON omits its id takes its SQL primary key instead of a fresh one per retry.
+- **The bootstrap catalog applies the same identity rule.** A record file with no id was
+  given a fresh ULID on every load, so the catalog fingerprint changed between two loads of
+  one store. Such files are now skipped with a warning.
+- **The store refuses a symlinked directory or store file inside itself.** A symlinked
+  `decisions/` sent every record write, from the MCP server, the hooks and bootstrap alike, to
+  the link's target, and a symlinked `index.db` made SQLite write there. `Store()` now raises
+  before any migration or write, naming the entry, and `sidegraph-bootstrap` refuses before
+  the review prompts. A symlinked store root stays allowed. Bootstrap's action summary now
+  names the store path and any symlink between the repository root and it.
+- **`sidegraph-bootstrap --report` no longer overwrites a file it is hard-linked to, and
+  protects the Codex hooks file the verifier really reads.** The guard compared resolved
+  paths, so a hard link to a host config passed it and the report truncated the shared file.
+  It also protected only the legacy `.codex/hooks/hooks.json`, not `.codex/hooks.json`. The
+  report is now published by replace, and one list of host-config paths feeds both the
+  verifier and the guard. The guard covers every host's config file, whichever `--host` is
+  selected.
+- **`sidegraph-import --docs` keys a document inside the repository by its repository path,
+  whatever directory it runs from.** Run from a subdirectory or given an absolute path, a
+  document used to miss its file node in the graph, skip as unanchorable, and get a
+  different `provenance.ref` from the same document imported at the root. Profile discovery
+  also finds the profile's documents from any directory in the repository, and the
+  unanchorable warning now fires only outside a git work tree, where the current directory
+  stands in for the root. Build the graph from the repository root: a graph built from a
+  subdirectory leaves documents unanchorable.
+- **`--docs` refuses a markdown file that is a symlink to a target outside the repository.**
+  It used to read the target under `--any-doc`. The document is counted as `refused: a symlink
+  pointing outside the repository`, and so is a profile-discovery hit that resolves outside
+  the repository (for example through a symlinked directory). A symlinked directory inside
+  the repository that points inside it imports under the path you named, and one that points
+  outside the repository is refused. A symlink to a file inside the repository imports under
+  its link path.
+- **A re-import repairs a record that has no anchors.** A document whose record was written
+  but whose bindings never landed (a run that stopped in between, leaving no anchor other
+  than `tag:` bindings) used to be skipped as existing for good. It is now bound on the next import and reported as `had their anchors
+  repaired`.
+- **The `import_docs` docstring describes what it does:** the five compared fields, the
+  statuses it matches, the repair and the refusal.
+- **`sidegraph-init` no longer writes `.claude/settings.json` through a symlink, and no
+  longer prints a traceback when the write fails.** A symlinked `.claude/` or `settings.json`
+  (live or dangling) is left untouched and the `env` line to add by hand is printed. A merge
+  into an existing file is now published by replacing it atomically, so an interruption
+  cannot leave a truncated file, and any write failure (a read-only `.claude/`, for example)
+  is reported the same way instead of raising. An `env` block that is `null` or not an
+  object, and a settings file that changes while init runs, are skipped the same way, not
+  raised, and a link swapped in just before the write is refused. A write-protected file is
+  respected when init runs as root too.
+- **`sidegraph-doctor`, the drift refresh the session hooks run, and `sidegraph-stats` now
+  open the index correctly when the store's path contains `#`, `?`, or `%` followed by two
+  hex digits.** Their read-only SQLite URI was built from the unquoted path.
+  **Doctor reported its index checks as skipped**, blaming a missing index and suggesting
+  `sidegraph-sync`, which could not help. **The session drift refresh silently stopped
+  excluding orphaned bindings.** **Stats failed.** For `#` and `?`, an empty file was also
+  created at the store path cut short at that character, and an unrelated database there
+  could be read instead.
+- **The session-link gate checks every line that gets published.** Lines starting with `#` in
+  a PR description, and in commit messages made with `git commit -m`/`-F`, which git records,
+  are now checked. The PR title and the PR's recorded commit messages are checked too. The
+  check re-runs when a PR description is edited. The public repository runs the check too:
+  the release snapshot ships the checker, and the workflow fails when the checker is missing
+  instead of skipping.
+- **`sidegraph-export-okf` refuses a symlinked `--out`, and a failed export no longer
+  destroys the previous one.** A symlinked output directory used to be written through, or
+  cleared, wherever it pointed, and a write that failed midway left a partial bundle after
+  the old export was already deleted. The new bundle is now built beside `--out` and
+  swapped in only when complete, except for a mount point, a `--out` that is the current
+  directory, an unwritable or non-directory parent, or a previous export that cannot be
+  renamed aside, which are written in place as before (a write failure there can leave a
+  partial export). The in-place write goes to the validated, resolved directory.
+- **An unreadable store or graph directory no longer ends in a traceback.** On Python 3.13 a store or
+  graph whose directory could not be read (permission denied) made `sidegraph-sync`,
+  `sidegraph-import`, `sidegraph-domains bootstrap`, `sidegraph-init`, `sidegraph-stats` and
+  `sidegraph-ratify` (on a domain accept) exit with an uncaught `PermissionError`. An unreadable
+  store is now reported on the command's error line (exit 1; 2 for `sidegraph-stats`). An
+  unreadable graph is treated as a missing one: `sidegraph-sync`, `sidegraph-import` and
+  `sidegraph-domains bootstrap` stop with `graph not readable`, and the other commands carry on
+  without a graph.
+  A working directory that cannot be read skips the graph hint and the `sync_anchors` hint instead of
+  raising; other code that resolves a relative path against it may still raise.
+- **A retried Tier-1 reconcile that could not run is no longer reported as done.** A
+  remembered community reconcile whose record still has a live or degraded Tier-2 anchor
+  with no recorded community kept being treated as a success: the key was cleared, the sync
+  said `moved`, and the stale row stayed live. It is now kept, and retried silently on every
+  sync.
+- **Sync, verify and doctor ask git about the repository their own files are in.**
+  `sidegraph-sync` (the graph's directory), `sidegraph-verify --against` and
+  `sidegraph-doctor` (the store's, and its graph-root check's) no longer inherit an ambient `GIT_DIR` or
+  `GIT_WORK_TREE`, which could make sync read another repository's `HEAD` and adopt a rename
+  that was never committed. The lazy sync run by `SessionStart` and retrieval, and the
+  `SessionStart` drift cache, are fixed too. `sidegraph-init` and `sidegraph-import` resolve
+  the repository root from the current directory the same way. A work tree whose repository
+  is found only through `GIT_DIR` now needs a `.git` file containing `gitdir: <path>`, and
+  `core.bare=false` in that repository.
+- **The sync docs list every condition that prevents a skip.** A remembered Tier-1
+  reconcile that is repaired or fails again also makes a plain sync report instead of
+  skipping.
+- **Documentation and help text match what the code does.** The PreToolUse docs name the
+  real `Read|Grep|Edit|Write` matcher and the two nudge forms, each at most once per session.
+  The `add_decision`, `supersede_decision`, `add_fact`, `supersede_fact` and
+  `propose_decisions` tool descriptions list `anchors_orphaned`. `sidegraph-ratify --help`
+  says `--all` also accepts standalone facts, and `--help` for `sidegraph-verify`,
+  `-doctor` and `-blame` no longer promises a legacy `*.db` migration they never perform.
+  `SECURITY.md` states local retrieval telemetry and the output paths commands write to.
+
 ## [0.5.0] — 2026-09-23
 
 ### Changed