sidegraph 0.1.0__tar.gz → 0.3.0__tar.gz

{sidegraph-0.1.0 → sidegraph-0.3.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.3.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.3.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.3.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.3.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.3.0}/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.3.0] — 2026-09-19
+
+### Added
+
+- **`sidegraph-stats` — one screen of local usage statistics.** Reads the gitignored
+  `.sidegraph/index.db` and reports how often memory was asked for, how much of the code
+  worked on has memory anchored to it, what the store holds, and anchor health, with activation
+  first. It states what was shown, asked and touched, and makes no claim about effect.
+  Flags: `--db`, `--window DAYS` (default 30, the journal's retention), `--graph` and
+  `--json` (the same report as data, with a figure the text withholds as `null`, never a
+  zero). Read-only: it never creates or rebuilds the index,
+  exits `2` on a bad `--window`, a missing index, an unreadable one or an unparseable record
+  row, and says so in the report when there is too little data to print a ratio, when
+  recording is off, when the budget counts were never recorded, or when the index is behind
+  the committed records after a `git pull` (it never opens the store, so it states that
+  rather than printing the old numbers). A new console script, so a committed surface: see
+  [`docs/reference/cli.md`](docs/reference/cli.md) and
+  [`docs/reference/stability.md`](docs/reference/stability.md).
+- **`/sidegraph:stats` skill**, with its Codex twin (explicit invocation only). It runs
+  `sidegraph-stats` and shows the output verbatim, without restating or interpreting the
+  numbers.
+- **A `render_events` journal and an optional `intent` parameter.** `get_task_context` and
+  `query_decisions` now record what each render selected and what survived the budget in a
+  new table of the local index (`drill_down` records the decisions it returned there too, with
+  no budget figures), and accept an optional `intent` label for what asked. The
+  label is recorded for statistics only and never affects what is returned. Both stay local:
+  no network calls, `SIDEGRAPH_TELEMETRY=off` stops the recording, and the 30-day pruning
+  keeps running when it is off, so opting out only reduces what is kept. See
+  [`docs/reference/store-format.md`](docs/reference/store-format.md) and
+  [`docs/reference/mcp-tools.md`](docs/reference/mcp-tools.md).
+
+### Changed
+
+- **The README's privacy note describes the local diagnostics as what was shown and
+  touched**, rather than which memory is "earning its keep".
+
+## [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.3.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.3.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.3.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).