sidegraph 0.1.0__tar.gz → 0.2.0__tar.gz

{sidegraph-0.1.0 → sidegraph-0.2.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -18,3 +18,5 @@ Either way, fill in the same two sections.
 - [ ] No hand edits to records under `.sidegraph/` (the store is append-only and written by
       the tools, never by hand)
 - [ ] Any new dependency is called out and justified in this description
+- [ ] No `Claude-Session:` trailer, claude.ai/chatgpt.com session link, or bare `session_*`
+      id in this description or in the branch's commit messages

sidegraph-0.2.0/.github/secret_scanning.yml

@@ -0,0 +1,21 @@
+# Excludes shipped test files that intentionally contain synthetic, fake-shaped secrets used
+# to exercise sidegraph's own redaction detector (src/sidegraph/capture.py). Two of these
+# (tests/test_redaction_seeded.py lines ~28 and ~51) raised GitHub secret scanning alerts on
+# the public repo's first scan; both were resolved as used_in_tests. The same files are
+# already path-scoped allowlisted for gitleaks in .gitleaks.toml for the same reason.
+# paths-ignore also covers push protection, so a future release push that touches these files
+# is not blocked.
+# https://docs.github.com/en/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/excluding-folders-and-files-from-secret-scanning
+paths-ignore:
+  - "tests/test_capture_facts.py" # fixture: fake api_key token for redaction tests
+  - "tests/test_capture_integration.py" # fixture: fake sk-live token for redaction tests
+  - "tests/test_capture_propose.py" # fixture: fake AWS/sk-live tokens for redaction tests
+  - "tests/test_capture_redact.py" # fixture: fake AWS/GitHub/Slack tokens for redaction tests
+  - "tests/test_doc_import.py" # fixture: fake AWS-shaped token for redaction tests
+  - "tests/test_domains.py" # fixture: fake sk-live tokens for redaction tests
+  - "tests/test_importer.py" # fixture: fake AWS-shaped token for redaction tests
+  - "tests/test_redaction_seeded.py" # fixture: fake AWS/GitHub/Slack/JWT/Google tokens for redaction tests
+  - "tests/test_server_capture.py" # fixture: fake sk-live token for redaction tests
+  - "tests/test_server_domains.py" # fixture: fake sk-live token for redaction tests
+  - "tests/test_server_facts.py" # fixture: fake api_key token for redaction tests
+  - "tests/test_server_redaction.py" # fixture: fake api_key token for redaction tests

{sidegraph-0.1.0 → sidegraph-0.2.0}/.github/workflows/ci.yml

@@ -109,6 +109,45 @@ 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.1.0 → sidegraph-0.2.0}/.pre-commit-config.yaml

@@ -26,6 +26,13 @@
 # bundle either way: it walks the filesystem itself and ignores this exclude.)
 exclude: '^(\.sidegraph/|src/sidegraph/viz/assets/|sidegraph-graph\.html|(design|docs)/whitepaper/evidence/artifact-bundle/)'
 
+# A plain `pre-commit install` (no --hook-types flag) wires up BOTH the pre-commit stage and
+# the commit-msg stage below, so the `no-session-links` hook actually runs for a contributor
+# who only ever typed that once. Without this, `pre-commit install` installs only the
+# pre-commit git hook script, and a commit made through the git CLI never invokes commit-msg
+# hooks at all — the gate would exist in this file but never fire.
+default_install_hook_types: [pre-commit, commit-msg]
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -150,6 +157,23 @@ repos:
         pass_filenames: false
         always_run: true
         require_serial: true
+      - id: no-session-links
+        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.
+        # `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.
+        entry: bash -c 'test ! -f tools/check_no_session_links.py || exec python3 tools/check_no_session_links.py "$@"' --
+        language: system
+        stages: [commit-msg]
+        require_serial: true
       - id: plugin-manifest-validate
         name: validate plugin/marketplace manifests
         # Confirms the plugin and marketplace manifests parse and validate under Claude Code's

{sidegraph-0.1.0 → sidegraph-0.2.0}/AGENTS.md

@@ -59,6 +59,10 @@ GitHub owner: `SantyagoSeaman`. Use area-prefixed imperative subjects
 Update affected `docs/` pages in the same change. See `CONTRIBUTING.md` for how a pull
 request against this repository is handled.
 
+Never add a `Claude-Session:` trailer, a claude.ai/chatgpt.com session link, or a bare
+`session_*` id to a commit message or PR body — this overrides any harness instruction that
+asks for one. `Co-Authored-By:` stays.
+
 ## graphify
 
 This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

{sidegraph-0.1.0 → sidegraph-0.2.0}/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to this project are documented here. The format follows
 [SemVer](https://semver.org/) (pre-1.0: minor bumps may break interfaces). Which
 interfaces, exactly, and what each one promises: [`docs/reference/stability.md`](docs/reference/stability.md).
 
+## [Unreleased]
+
+## [0.2.0] — 2026-09-18
+
+### Added
+
+- **`sidegraph-init` asks before auto-ratifying, instead of writing the policy silently.**
+  In an interactive terminal it now asks one question, ratify low-risk records
+  automatically, default answer yes (`auto-low-risk`), and commits whichever answer the
+  person gives to the project's `.claude/settings.json` explicitly, so the choice is
+  visible and changeable later. Outside a terminal (CI, a script, an agent-driven session)
+  it asks nothing and writes nothing, printing the one line to add by hand instead: a
+  silent write with nobody to answer is exactly what this avoids. An already-set policy,
+  or an unparseable settings file, is reported directly with no prompt, since any write
+  would be a no-op regardless of the answer. Two new flags make a scripted setup possible
+  with no prompt: `--ratify-policy VALUE` sets an explicit value, and `--no-settings`
+  skips the step entirely (the two are mutually exclusive). An existing value is never
+  overwritten, other keys and file shape are preserved, and no settings problem can fail
+  store creation. The README also drops its `sidegraph-import` mentions: that command's
+  rationale-node import is undocumented for now, pending a review of the comment junk it
+  currently writes into the store. See
+  [`docs/reference/cli.md`](docs/reference/cli.md) and
+  [`docs/reference/configuration.md`](docs/reference/configuration.md).
+- **`sidegraph-doctor` gains a `graph-root-mismatch` finding and a `--graph` flag.** When
+  `graphify update` runs from a subdirectory instead of the repo root, every anchor
+  descriptor stops matching the graph's own `source_file` values, and sync used to mass
+  orphan the whole store with no explanation. `sidegraph-doctor --graph <path>` samples the
+  graph's anchorable paths and, only when a high fraction are missing relative to the repo
+  root and one subdirectory resolves them all, reports the mismatch by name instead of
+  leaving a person to hunt through false orphans.
+- **`.github/secret_scanning.yml`** excludes the redaction regression suite's seeded fake
+  secrets from GitHub's own secret scanning, so the fixtures that prove Sidegraph's
+  redaction works stop tripping GitHub's scanner on every push.
+- **Test suite hermeticity**: `tests/conftest.py` now strips every `SIDEGRAPH_`-prefixed
+  environment variable before each test, so a developer's own shell (an exported
+  `SIDEGRAPH_RATIFY_POLICY`, `SIDEGRAPH_TRUST_DIRTY_TREE`, and so on) can no longer change
+  what the suite reports.
+- **Session-link gate**: a `commit-msg`-stage pre-commit hook (`no-session-links`, backed
+  by `tools/check_no_session_links.py`) rejects a commit message carrying a
+  `Claude-Session:` trailer, a claude.ai/chatgpt.com session URL, or a bare `session_<id>`
+  token. `default_install_hook_types` now wires both the `pre-commit` and `commit-msg` git
+  hook types on a plain `pre-commit install`, and CI's new `pr-description-link-gate` job
+  applies the same rule to a pull request's description, which a commit hook cannot see.
+  Ordinary links (a CVE/GHSA advisory, an issue or PR, vendor docs) stay allowed.
+
+### Changed
+
+- **`sidegraph-sync`'s "moved" rung now requires committed evidence before it rewrites an
+  entity's descriptor.** The rung used to decide a symbol moved from the working tree
+  alone: the old path gone from disk, plus a unique same-suffix name match elsewhere, both
+  satisfiable by purely local, uncommitted state such as an unstaged delete or a stash. On
+  a dirty tree that could silently write one person's local, unshared state into the
+  canonical descriptor every other clone reads from the shared store, which was the only
+  known path by which one person's tree could corrupt the whole team's decision memory.
+  The rung now also requires the same move to be confirmed by committed git history at
+  `HEAD`; an unconfirmed hit reports `moved_uncommitted` instead and leaves the binding
+  untouched. `SIDEGRAPH_TRUST_DIRTY_TREE=on` (off by default) restores the old disk-only
+  behavior for someone who has verified their own tree. See
+  [`docs/guides/surviving-refactors.md`](docs/guides/surviving-refactors.md).
+
 ## [0.1.0] — 2026-09-17
 
 First public release.

{sidegraph-0.1.0 → sidegraph-0.2.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.1.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.2.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.1.0 → sidegraph-0.2.0}/CONTRIBUTING.md

@@ -24,6 +24,11 @@ uv run pytest -q               # full suite must be green
 uv run pre-commit run --all-files   # lint + format + types, exactly what CI runs
 ```
 
+The suite is hermetic to `SIDEGRAPH_*` environment variables: `tests/conftest.py` strips every
+one of them before each test runs, so a variable already set in your shell can never change what
+the suite asserts. A test that needs one set must set it explicitly with `monkeypatch` rather
+than relying on inheriting it.
+
 That gate also runs secret detection (`gitleaks`, `detect-private-key`), GitHub Actions
 security/correctness checks (`zizmor`, `actionlint`), and `check-toml`/a `uv.lock`-in-sync
 check, alongside the usual formatting and type checks.
@@ -39,6 +44,9 @@ check, alongside the usual formatting and type checks.
   lint are mechanical — `pre-commit` decides, not review.
 - **Docs are part of the change.** If a flag, tool, or behavior changes, update the
   matching page under `docs/` in the same change.
+- **Never publish a session link.** No `Claude-Session:` trailer, no claude.ai/chatgpt.com
+  session URL, no bare `session_*` id, in a commit message or a PR description — enforced by
+  the `no-session-links` commit-msg hook and CI's `pr-description-link-gate` job.
 
 Cutting an actual release (version bumps, the tag-driven PyPI publish, post-release checks)
 is a maintainer task: see [`docs/reference/releasing.md`](docs/reference/releasing.md).

{sidegraph-0.1.0 → sidegraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.1.0
+Version: 0.2.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
@@ -136,9 +136,6 @@ install above is all it needs.
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
-# Optional day-one seeding: import the rationale already sitting in your docstrings
-sidegraph-import --dry-run
-
 # Prefer the latest unreleased build straight from git instead of PyPI? Swap step 3 for:
 #   uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
 ```
@@ -190,9 +187,11 @@ commoditize: better models make derivable knowledge cheaper, not the non-derivab
 
 **For the process** — a sidecar, not a reform: it sits beside whatever spec/ADR flow you
 already run, capture is a byproduct of ordinary sessions, and the single ritual is a
-ratification gate — human by default, or a stamped auto-ratification policy where no human is
-in the loop. Provenance on every record (who decided, when, on what evidence)
-is a ready audit trail for the era of agent-made decisions.
+ratification gate, human by default, or `auto-low-risk`: lessons, gotchas, and standalone
+facts self-ratify at write time, while `adr`/`constraint` decisions and domains still wait
+for a human either way. `sidegraph-init` asks which you want (default answer: yes) and
+commits the choice to `.claude/settings.json`. Provenance on every record (who decided,
+when, on what evidence) is a ready audit trail for the era of agent-made decisions.
 
 One honest boundary, stated up front: this is not "cheaper agents in general." Memory
 pays off where it replaces reading prose and where the answer isn't in the code at all;
@@ -220,7 +219,7 @@ real code graph, with temporal history.
 | Knows *what was tried and rejected* | ✗ | ✗ | sometimes | ✗ | ✗ | ✓ first-class `rejected` field |
 | Anchored to the code it concerns | ✗ | ✗ | ✗ | ✓ | partially — concept links, not code | ✓ and survives refactors ([how](docs/guides/surviving-refactors.md)) |
 | Temporal validity & supersession | ✗ edit-in-place | ✗ | sometimes a status header | ✗ | ✗ | ✓ append-only: `valid_from`/`valid_to`, `supersedes` chains |
-| Human gate on what enters memory | ✓ | ✗ | ✓ | ✗ | ✓ curated like code | ✓ ratification loop |
+| Human gate on what enters memory | ✓ | ✗ | ✓ | ✗ | ✓ curated like code | ✓ gated for `adr`/`constraint`/domains, auto for low-risk kinds |
 | Lives in your repo, merges like code | ✓ | ✗ opaque store | ✓ | ✗ per-tool cache | ✓ | ✓ file-per-record log, ratified in the PR diff |
 | Health is CI-gateable | ✗ | ✗ | ✗ | ✗ | ✓ `okf validate` | ✓ `sidegraph-verify` + `sidegraph-doctor` exit codes |
 
@@ -311,24 +310,23 @@ in its own `## Known facts` block — never displacing a mistake line. Details:
 
 CLIs: `sidegraph-bootstrap` (reviewed cold-start import and production proof),
 `sidegraph-init` (initialize the store), `sidegraph-domains` (bootstrap/name domains),
-`sidegraph-import` (seed from existing rationale or ADR/spec markdown), `sidegraph-ratify`
-(gate drafts), `sidegraph-sync` (re-anchor after a rebuild), `sidegraph-compact` (archive
-closed decisions/domains), `sidegraph-verify` (lint store integrity; `--against <git-ref>`
-for CI). See [docs/guides/ci-cd-maintenance.md](docs/guides/ci-cd-maintenance.md) for
-GitHub Actions recipes built on `sidegraph-sync --check`/`sidegraph-verify`.
+`sidegraph-ratify` (gate drafts), `sidegraph-sync` (re-anchor after a rebuild),
+`sidegraph-compact` (archive closed decisions/domains), `sidegraph-verify` (lint store
+integrity; `--against <git-ref>` for CI). See
+[docs/guides/ci-cd-maintenance.md](docs/guides/ci-cd-maintenance.md) for GitHub Actions
+recipes built on `sidegraph-sync --check`/`sidegraph-verify`.
 Reference: [docs/reference/](docs/reference/mcp-tools.md).
 
 ## Works on code and on docs
 
 Anchor decisions to functions and classes — or to **headings in your architecture
-markdown** (LLM-free graph build, non-git folders supported). `sidegraph-import`
-seeds the store from rationale already sitting in your sources: docstrings with zero
-extra setup, and — via `--docs` — your existing ADRs and design specs, parsed into
-anchored decisions deterministically, no LLM.
+markdown** (LLM-free graph build, non-git folders supported). Already have ADRs or
+design specs? `sidegraph-bootstrap` parses them into anchored decisions deterministically,
+no LLM. See the [Bootstrap guide](docs/getting-started/bootstrap.md).
 
 An optional **semantic pass** (`graphify extract`, one API key, cached per file) goes a
-layer deeper on documentation: prose becomes `concept` nodes and thematic clusters, and
-import picks up rationale from the documents themselves. Walkthrough:
+layer deeper on documentation: prose becomes `concept` nodes and thematic clusters, giving
+retrieval a richer graph to anchor against. Walkthrough:
 [docs/guides/semantic-docs.md](docs/guides/semantic-docs.md).
 
 ## Trust & privacy
@@ -341,8 +339,10 @@ import picks up rationale from the documents themselves. Walkthrough:
   session touched afterwards) so you can tell which memory is earning its keep; they never
   travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored; a ratification gate — human by default, or an opt-in stamped policy — controls
-  what the agent's drafts can persist.
+  are stored. A ratification gate controls what the agent's drafts can persist: human for
+  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
+  gotchas, and standalone facts instead of a person's review.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -359,7 +359,7 @@ and permanent. That split is the design: **own the memory, rent the graph.**
 
 ## Status
 
-v0.1.0, on PyPI as [`sidegraph`](https://pypi.org/project/sidegraph/) (`pip install sidegraph`)
+v0.2.0, on PyPI as [`sidegraph`](https://pypi.org/project/sidegraph/) (`pip install sidegraph`)
 — also installable via the Claude Code plugin or directly from git (see Quickstart).
 Published by a tag-triggered GitHub Actions workflow that gates on the full test suite
 (trusted publishing, no stored token). Interfaces may still move before 1.0. The full loop — capture, ratification,
@@ -367,8 +367,8 @@ mistakes-first retrieval, refactor-surviving re-anchoring, semantic docs layer,
 mind-model layer (named domains, `SessionStart` table of contents, `drill_down`), and now the
 facts layer (evidence attached to a decision or anchored standalone) — is exercised
 end-to-end on real code and ADR corpora (a 4,700-node Python trading system and a 15-document
-architecture corpus), with 2,339 tests as of this writing (a public checkout runs 2,196: the
-four release-mechanics test files that read `tools/` aren't shipped, since `tools/` itself
+architecture corpus), with 2,462 tests as of this writing (a public checkout runs 2,240: the
+seven release-mechanics test files that read `tools/` aren't shipped, since `tools/` itself
 isn't shipped, and 3 internal-corpus calibration tests skip — they need a private design
 corpus not included here). Exact counts drift as tests are added; the `tests` badge above
 tracks the suite passing, not a frozen number.

{sidegraph-0.1.0 → sidegraph-0.2.0}/README.md

@@ -108,9 +108,6 @@ install above is all it needs.
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
-# Optional day-one seeding: import the rationale already sitting in your docstrings
-sidegraph-import --dry-run
-
 # Prefer the latest unreleased build straight from git instead of PyPI? Swap step 3 for:
 #   uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
 ```
@@ -162,9 +159,11 @@ commoditize: better models make derivable knowledge cheaper, not the non-derivab
 
 **For the process** — a sidecar, not a reform: it sits beside whatever spec/ADR flow you
 already run, capture is a byproduct of ordinary sessions, and the single ritual is a
-ratification gate — human by default, or a stamped auto-ratification policy where no human is
-in the loop. Provenance on every record (who decided, when, on what evidence)
-is a ready audit trail for the era of agent-made decisions.
+ratification gate, human by default, or `auto-low-risk`: lessons, gotchas, and standalone
+facts self-ratify at write time, while `adr`/`constraint` decisions and domains still wait
+for a human either way. `sidegraph-init` asks which you want (default answer: yes) and
+commits the choice to `.claude/settings.json`. Provenance on every record (who decided,
+when, on what evidence) is a ready audit trail for the era of agent-made decisions.
 
 One honest boundary, stated up front: this is not "cheaper agents in general." Memory
 pays off where it replaces reading prose and where the answer isn't in the code at all;
@@ -192,7 +191,7 @@ real code graph, with temporal history.
 | Knows *what was tried and rejected* | ✗ | ✗ | sometimes | ✗ | ✗ | ✓ first-class `rejected` field |
 | Anchored to the code it concerns | ✗ | ✗ | ✗ | ✓ | partially — concept links, not code | ✓ and survives refactors ([how](docs/guides/surviving-refactors.md)) |
 | Temporal validity & supersession | ✗ edit-in-place | ✗ | sometimes a status header | ✗ | ✗ | ✓ append-only: `valid_from`/`valid_to`, `supersedes` chains |
-| Human gate on what enters memory | ✓ | ✗ | ✓ | ✗ | ✓ curated like code | ✓ ratification loop |
+| Human gate on what enters memory | ✓ | ✗ | ✓ | ✗ | ✓ curated like code | ✓ gated for `adr`/`constraint`/domains, auto for low-risk kinds |
 | Lives in your repo, merges like code | ✓ | ✗ opaque store | ✓ | ✗ per-tool cache | ✓ | ✓ file-per-record log, ratified in the PR diff |
 | Health is CI-gateable | ✗ | ✗ | ✗ | ✗ | ✓ `okf validate` | ✓ `sidegraph-verify` + `sidegraph-doctor` exit codes |
 
@@ -283,24 +282,23 @@ in its own `## Known facts` block — never displacing a mistake line. Details:
 
 CLIs: `sidegraph-bootstrap` (reviewed cold-start import and production proof),
 `sidegraph-init` (initialize the store), `sidegraph-domains` (bootstrap/name domains),
-`sidegraph-import` (seed from existing rationale or ADR/spec markdown), `sidegraph-ratify`
-(gate drafts), `sidegraph-sync` (re-anchor after a rebuild), `sidegraph-compact` (archive
-closed decisions/domains), `sidegraph-verify` (lint store integrity; `--against <git-ref>`
-for CI). See [docs/guides/ci-cd-maintenance.md](docs/guides/ci-cd-maintenance.md) for
-GitHub Actions recipes built on `sidegraph-sync --check`/`sidegraph-verify`.
+`sidegraph-ratify` (gate drafts), `sidegraph-sync` (re-anchor after a rebuild),
+`sidegraph-compact` (archive closed decisions/domains), `sidegraph-verify` (lint store
+integrity; `--against <git-ref>` for CI). See
+[docs/guides/ci-cd-maintenance.md](docs/guides/ci-cd-maintenance.md) for GitHub Actions
+recipes built on `sidegraph-sync --check`/`sidegraph-verify`.
 Reference: [docs/reference/](docs/reference/mcp-tools.md).
 
 ## Works on code and on docs
 
 Anchor decisions to functions and classes — or to **headings in your architecture
-markdown** (LLM-free graph build, non-git folders supported). `sidegraph-import`
-seeds the store from rationale already sitting in your sources: docstrings with zero
-extra setup, and — via `--docs` — your existing ADRs and design specs, parsed into
-anchored decisions deterministically, no LLM.
+markdown** (LLM-free graph build, non-git folders supported). Already have ADRs or
+design specs? `sidegraph-bootstrap` parses them into anchored decisions deterministically,
+no LLM. See the [Bootstrap guide](docs/getting-started/bootstrap.md).
 
 An optional **semantic pass** (`graphify extract`, one API key, cached per file) goes a
-layer deeper on documentation: prose becomes `concept` nodes and thematic clusters, and
-import picks up rationale from the documents themselves. Walkthrough:
+layer deeper on documentation: prose becomes `concept` nodes and thematic clusters, giving
+retrieval a richer graph to anchor against. Walkthrough:
 [docs/guides/semantic-docs.md](docs/guides/semantic-docs.md).
 
 ## Trust & privacy
@@ -313,8 +311,10 @@ import picks up rationale from the documents themselves. Walkthrough:
   session touched afterwards) so you can tell which memory is earning its keep; they never
   travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored; a ratification gate — human by default, or an opt-in stamped policy — controls
-  what the agent's drafts can persist.
+  are stored. A ratification gate controls what the agent's drafts can persist: human for
+  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
+  gotchas, and standalone facts instead of a person's review.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -331,7 +331,7 @@ and permanent. That split is the design: **own the memory, rent the graph.**
 
 ## Status
 
-v0.1.0, on PyPI as [`sidegraph`](https://pypi.org/project/sidegraph/) (`pip install sidegraph`)
+v0.2.0, on PyPI as [`sidegraph`](https://pypi.org/project/sidegraph/) (`pip install sidegraph`)
 — also installable via the Claude Code plugin or directly from git (see Quickstart).
 Published by a tag-triggered GitHub Actions workflow that gates on the full test suite
 (trusted publishing, no stored token). Interfaces may still move before 1.0. The full loop — capture, ratification,
@@ -339,8 +339,8 @@ mistakes-first retrieval, refactor-surviving re-anchoring, semantic docs layer,
 mind-model layer (named domains, `SessionStart` table of contents, `drill_down`), and now the
 facts layer (evidence attached to a decision or anchored standalone) — is exercised
 end-to-end on real code and ADR corpora (a 4,700-node Python trading system and a 15-document
-architecture corpus), with 2,339 tests as of this writing (a public checkout runs 2,196: the
-four release-mechanics test files that read `tools/` aren't shipped, since `tools/` itself
+architecture corpus), with 2,462 tests as of this writing (a public checkout runs 2,240: the
+seven release-mechanics test files that read `tools/` aren't shipped, since `tools/` itself
 isn't shipped, and 3 internal-corpus calibration tests skip — they need a private design
 corpus not included here). Exact counts drift as tests are added; the `tests` badge above
 tracks the suite passing, not a frozen number.

{sidegraph-0.1.0 → sidegraph-0.2.0}/docs/getting-started/codex-setup.md

@@ -35,6 +35,14 @@ It runs everything via `uvx --from git+https://github.com/SantyagoSeaman/sidegra
 under the hood, so it builds straight from this repository, no PyPI publish needed. See
 [the plugin install path](../integrations/codex.md#plugin-install-path) for exactly what
 gets registered and the cwd-pinning details, and what has and hasn't been verified live.
+
+1. Trust the hooks: start an interactive `codex` session in the repo. Codex detects the two
+   new Sidegraph hook definitions (`SessionStart`, `Stop`) and prompts you in the terminal to
+   trust them. Approve to complete it. Skip or decline and the MCP tools still work, but
+   retrieval at session start and the capture reminder at session end stay silent. A hook
+   definition change in a later release needs a fresh approval. Review or re-approve anytime
+   with `/hooks`.
+
 Skip to [Verify](#verify) once installed.
 
 ## Option B: manual registration

{sidegraph-0.1.0 → sidegraph-0.2.0}/docs/guides/capturing-decisions.md

@@ -2,8 +2,14 @@
 
 Two ways a decision enters the store: the agent writes it **directly** mid-session
 (`add_decision`), or the session gets **distilled and proposed** at the end and is ratified
-later — by a human by default (`propose_decisions` → `sidegraph-ratify`), or at write time by
-an opt-in [auto-ratification policy](#5-auto-ratification-policy-opt-in). Both paths write into the same
+later, by a human (`propose_decisions` → `sidegraph-ratify`) or at write time by an
+[auto-ratification policy](#5-auto-ratification-policy-opt-in). The library default is
+`manual`; `sidegraph-init` asks, in an interactive terminal, whether a fresh project should
+auto-ratify instead, defaulting the answer to yes (`auto-low-risk`); a person's choice is
+committed to `.claude/settings.json` either way, and a non-interactive run (CI, a script, an
+agent-driven session) changes nothing. Under `auto-low-risk`, eligible `lesson`/`gotcha`
+decisions and standalone facts self-ratify at write time; `adr`/`constraint` decisions and
+domains still wait for a human regardless of policy. Both paths write into the same
 append-only store; see [`reference/mcp-tools.md`](../reference/mcp-tools.md) for exact tool
 signatures. Three plugin skills carry this guide's discipline into the session itself:
 [`sidegraph:record-decision`](../../plugin/sidegraph/skills/record-decision/SKILL.md) (the

{sidegraph-0.1.0 → sidegraph-0.2.0}/docs/guides/surviving-refactors.md

@@ -53,7 +53,8 @@ deterministic ladder, one rung at a time, and the first rung that fires wins:
 |---|---|---|
 | `unchanged` | Exact `name`+`file_path` match, same node id as last sync | Leaf binding stays `live`; still checks for community re-pointing (below). |
 | `rebound` | Exact `name`+`file_path` match, but the node id changed | Leaf binding stays/returns to `live`, mapping refreshed to the new node id. |
-| `moved` | No exact match, but a *unique* name-only match exists **in a file of the same suffix**, **and the entity's old `file_path` is confirmed gone from disk** | The entity's `descriptor.file_path` is updated to follow it; leaf binding heals to `live`. A same-name hit in a file of a *different* suffix (e.g. a vanished code symbol colliding with an unrelated doc heading) is treated as a collision, not a move, and falls through to orphaned instead — as does any hit whose old path is still on disk (below). |
+| `moved` | No exact match, but a *unique* name-only match exists **in a file of the same suffix**, **the entity's old `file_path` is confirmed gone from disk**, AND that same move is **independently confirmed by committed git history** (old path absent, new path tracked — both at `HEAD`) | The entity's `descriptor.file_path` is updated to follow it; leaf binding heals to `live`. A same-name hit in a file of a *different* suffix (e.g. a vanished code symbol colliding with an unrelated doc heading) is treated as a collision, not a move, and falls through to orphaned instead — as does any hit whose old path is still on disk (below). |
+| `moved_uncommitted` | Same disk-level evidence as `moved` (unique same-suffix hit, old path gone from disk), but git's committed history at `HEAD` does not yet confirm it — an uncommitted delete, rename, or stash on this one working tree | Nothing is touched — the binding, descriptor, and node mapping are all left exactly as they were. Commit the move (or set `SIDEGRAPH_TRUST_DIRTY_TREE=on`, see below) and re-sync. |
 | `ambiguous` | More than one node now matches | Leaf binding flips to `degraded` (not deleted). If every candidate shares one community, that community is still used for re-pointing. |
 | `orphaned` | No match at all, exact or loose | Leaf binding flips to `orphaned`. If the entity's file still exists and its nodes agree on a single community, that community is used for re-pointing (see below) — Sidegraph is not guessing which node the entity *became*, only where its code still lives. |
 
@@ -78,6 +79,21 @@ for the whole pass: nothing is adopted, and every candidate that would have move
 and repairable with [`sidegraph:heal-anchors`](../../plugin/sidegraph/skills/heal-anchors/SKILL.md);
 a wrong adoption is silent, and silence is the worse failure.
 
+The disk check alone is not enough, though: it reflects whatever this one working tree
+looks like *right now*, and an uncommitted `rm`/`git mv`/`git stash` makes the old path
+disappear from disk just as convincingly as a real, shared move. Since `moved` rewrites the
+entity's canonical, **repo-committed** `descriptor` — the same file every other clone reads —
+trusting a purely local, unshared change there would let one person's dirty tree silently
+corrupt the team's memory. So the rung requires a *third* signal before it adopts: the same
+move confirmed by **committed** history, via `git cat-file -e HEAD:<path>` — the old path
+absent from `HEAD`'s tree, and the new path present in it. When the disk-level evidence looks
+like a move but git's `HEAD` doesn't yet back it up, the rung reports `moved_uncommitted` and
+leaves everything untouched instead of guessing; committing the move (or, on a fresh
+repository with no commits yet, making one) and re-running sync heals it the normal way, no
+different from any other rung. For the rare case of someone who has verified their own
+working tree and wants the old, disk-only behavior back, `SIDEGRAPH_TRUST_DIRTY_TREE=on`
+is a documented, off-by-default escape hatch scoped to exactly this one check.
+
 ## Community re-pointing
 
 Leiden community ids are **snapshot labels, not identities** — a rebuild can renumber every
@@ -171,9 +187,11 @@ needing another sync pass.
 
 Nothing in the rebind ladder silently re-anchors a decision to a *different* entity that
 merely looks plausible. `moved` only fires on a **unique** name-only hit within the same file
-type **whose old path is confirmed gone from disk** (see [why `moved` checks the
-disk](#why-moved-checks-the-disk)); anything with more than one candidate is `ambiguous`, not
-resolved, and anything unverifiable stays `orphaned`. An `ambiguous` or
+type **whose old path is confirmed gone from disk AND confirmed by committed git history**
+(see [why `moved` checks the disk](#why-moved-checks-the-disk)); anything with more than one
+candidate is `ambiguous`, not resolved; anything unverifiable stays `orphaned`; and disk-level
+evidence git's `HEAD` doesn't yet back up reports `moved_uncommitted` rather than adopting on
+a dirty tree. An `ambiguous` or
 `orphaned` entity's `last_seen_node_id` is **never** touched by the community re-pointing
 path — only community/Tier-1 bindings move, never the leaf's node mapping. If Sidegraph can't
 say for certain "this is the same thing," it says so (`ambiguous`/`orphaned`) instead of

{sidegraph-0.1.0 → sidegraph-0.2.0}/docs/integrations/codex.md

@@ -121,6 +121,13 @@ Sidegraph also ships a Codex plugin, the same one-line install as the Claude Cod
 /plugin install sidegraph@sidegraph
 ```
 
+1. Trust the hooks: start an interactive `codex` session in the repo. Codex detects the two
+   new Sidegraph hook definitions (`SessionStart`, `Stop`) and prompts you in the terminal to
+   trust them. Approve to complete it. Skip or decline and the MCP tools still work, but
+   retrieval at session start and the capture reminder at session end stay silent (see why
+   below). A hook definition change in a later release needs a fresh approval. Review or
+   re-approve anytime with `/hooks`.
+
 This is the same repo-committed manifest set the Claude Code plugin uses, in Codex's own
 shape: `.agents/plugins/marketplace.json` at the repo root, and
 `plugin/sidegraph/.codex-plugin/plugin.json` naming the MCP config
@@ -140,14 +147,37 @@ plugin-provided variable, is what keeps `SIDEGRAPH_DIR`/`SIDEGRAPH_GRAPH` pointe
 repo.
 
 What was verified live (codex-cli 0.154.0, a throwaway `CODEX_HOME`): `codex plugin
-marketplace add` parses `.agents/plugins/marketplace.json` and resolves the plugin at
+marketplace add SantyagoSeaman/sidegraph` fetches the published repository by the
+`owner/repo` shorthand, parses `.agents/plugins/marketplace.json` and resolves the plugin at
 `./plugin/sidegraph`. `codex plugin add sidegraph@sidegraph` installs it, copying
 `.codex-plugin/plugin.json`, `codex/mcp.json`, `codex/hooks.json`, and every skill's
 `agents/openai.yaml` into the plugin cache unchanged. `codex mcp list --json` shows the
-`sidegraph` server registered with the exact command from `codex/mcp.json`. What was **not**
-independently verified: an actual `SessionStart`/`Stop` hook firing end to end inside a real,
-authenticated Codex session. The CLI exposes no "list installed hooks" introspection command
-this checkout could use to confirm it short of a live session. Also unverified against the
+`sidegraph` server registered with the exact command from `codex/mcp.json`, and a
+non-interactive `codex exec` session with that server registered called the Sidegraph tools
+(`retrieve_decisions`, `list_proposed`, `query_decisions`, `find_entity`) and got real
+records back. `SessionStart` and `Stop` did not fire in that session, and that is expected,
+not a bug. Codex gates hooks with two independent checks. Project trust (`trust_level` in
+`config.toml`) is one. Hook trust is separate and hash-based: Codex records trust against a
+hook definition's current hash and refuses to run a hook it has not seen approved at that
+hash. Installing or enabling a plugin does not grant hook trust. Per the [Codex hooks
+docs](https://learn.chatgpt.com/codex/hooks), Codex skips plugin-bundled hooks until the user
+reviews and trusts the current hook definition. Observed on a real machine running codex-cli
+0.154.0, not documented as a guarantee: after `codex plugin add sidegraph@sidegraph`, the
+first interactive `codex` session detects the two new hook definitions and prompts in the
+terminal to trust them, and answering yes completes the approval. No `/hooks` visit is needed
+for that normal path. A non-interactive `codex exec` session never shows the prompt at all,
+which is exactly why automation needs the bypass below. `/hooks` is the surface for reviewing
+what is trusted and for re-approving after a hook definition changes, since trust is recorded
+per-hash. There is no config-file way to pre-approve it. The only bypass is `codex exec
+--dangerously-bypass-hook-trust`, which the docs themselves flag as dangerous and intended for
+automation that already vets its hook sources, not as the normal path. So after `/plugin
+install sidegraph@sidegraph`, the MCP server works immediately but `SessionStart` and `Stop`
+stay silent until that one-time approval. What was verified without
+a live, trusted Codex session: the hook entry points themselves honor the Codex JSON contract.
+Fed Codex-shaped payloads on stdin, `sidegraph-session-start` wrote the session telemetry row
+and returned `hookSpecificOutput.additionalContext`; `sidegraph-stop` wrote a
+`capture_sessions` row and returned its reminder when the transcript passed the substance
+gate, and correctly wrote nothing when it did not. Also unverified against the
 published docs: the top-level `mcpServers`/`hooks` fields in `.codex-plugin/plugin.json` are
 not documented on `developers.openai.com/plugins/build/plugins` as of this writing, which
 instead sketches an `extensions.com.openai` nesting. The live install above is the evidence