sidegraph 0.1.0__tar.gz

sidegraph-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "sidegraph",
+  "description": "Sidegraph — durable decision memory for AI coding agents.",
+  "plugins": [
+    {
+      "name": "sidegraph",
+      "source": {
+        "source": "local",
+        "path": "./plugin/sidegraph"
+      },
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors."
+    }
+  ]
+}

sidegraph-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "sidegraph",
+  "description": "Sidegraph — durable decision memory for AI coding agents.",
+  "owner": { "name": "SantyagoSeaman", "url": "https://github.com/SantyagoSeaman" },
+  "plugins": [
+    {
+      "name": "sidegraph",
+      "source": "./plugin/sidegraph",
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors.",
+      "homepage": "https://github.com/SantyagoSeaman/sidegraph"
+    }
+  ]
+}

sidegraph-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# One maintainer today; narrow this as the project grows co-maintainers.
+* @SantyagoSeaman

sidegraph-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: Bug report
+description: Something in Sidegraph behaves differently than documented.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you ran, what you expected, what you got.
+      placeholder: |
+        Command: uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-verify
+        Expected: exit 0
+        Got: ...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: The smallest sequence that shows the problem.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Sidegraph version
+      description: "Output of: uv run python -c \"import importlib.metadata as m; print(m.version('sidegraph'))\""
+    validations:
+      required: true
+  - type: input
+    id: graphify
+    attributes:
+      label: Graphify version
+      description: The engine version whose graph.json you are reading.
+  - type: markdown
+    attributes:
+      value: "For security issues do **not** open an issue — see [SECURITY.md](../blob/main/SECURITY.md)."

sidegraph-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/SantyagoSeaman/sidegraph/security/policy
+    about: Report privately — never in a public issue.

sidegraph-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Propose a change to Sidegraph.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What decision memory is failing you today? Describe the situation, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+    validations:
+      required: true
+  - type: checkboxes
+    id: invariants
+    attributes:
+      label: Invariant check
+      description: See CLAUDE.md. Proposals that break these will not land.
+      options:
+        - label: Does not write into the engine's graph.json (read-only input)
+        - label: Does not hard-delete a Decision (the store is append-only)
+        - label: Is obviously useful to an LLM consuming the memory

sidegraph-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!--
+This file ships in two places. On the internal repo, this PR is the normal path to merge.
+On the public repo (a released snapshot, see CONTRIBUTING.md), this PR is a proposal: it is
+reviewed here and ported upstream with attribution, then arrives back with the next release.
+Either way, fill in the same two sections.
+-->
+
+## What changed and why
+
+<!-- One or two sentences: what this PR does and the problem it solves. -->
+
+## Checklist
+
+- [ ] Tests pass (`uv run pytest -q`)
+- [ ] `uv run pre-commit run --all-files` is clean
+- [ ] Docs under `docs/` are updated for any behaviour change
+- [ ] A CHANGELOG entry is added under `[Unreleased]` for any user-visible change
+- [ ] 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

sidegraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+# Project lint+type+test gate. `lint` runs the SAME .pre-commit-config.yaml a developer
+# runs locally, so there is one definition of lint rather than a CI copy that drifts.
+# Mostly distinct from the sidegraph-recipe workflows in docs/guides/ci-cd-maintenance.md
+# (recipes for USER repos consuming Sidegraph) — except `store-lint`, which is Recipe 2
+# self-applied to this repo's own dogfood store (2026-08-09 maintenance retrospective,
+# cadence lever): the store rides every PR, so its transition rules should gate every PR.
+#
+# Actions are pinned to commit SHAs (the tag comment records the version): a mutable tag
+# is a supply-chain hole, and this workflow ships to the public repo by snapshot.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:   # reused as the pre-publish gate by publish.yml (tag builds)
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes, so the checkout's git credentials should not
+      # persist into the runner's git config where a later step (or an uploaded artifact) could
+      # leak them.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Cache pre-commit hooks
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  # Recipe 2 (docs/guides/ci-cd-maintenance.md) on our own store: catch a hand-edited or
+  # history-rewritten record no MCP tool would produce. Diffs against the PR's merge base
+  # (never a moving branch name — see the recipe for why). Skips cleanly when the checkout
+  # carries no store: the public snapshot ships .sidegraph only on the demo branch, and
+  # this workflow ships to the public repo.
+  store-lint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0   # full history — merge-base needs it
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: sidegraph-verify --against merge-base
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — store lint not applicable"
+            exit 0
+          fi
+          uv sync --locked
+          git fetch origin "$GITHUB_BASE_REF"
+          base="$(git merge-base "origin/$GITHUB_BASE_REF" HEAD)"
+          uv run sidegraph-verify --against "$base" --json
+
+  # 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
+  # check green on it (2026-08-09 retrospective, cadence lever) — so a red here is a real
+  # finding, not CI-environment noise. Lone orphaned/ambiguous entities do NOT fail the
+  # check: multi-anchor tolerates them by design. The engine is version-pinned (engine-
+  # seam invariant); the sync writes only to the ephemeral checkout's .sidegraph/.
+  anchor-health:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Rebuild graph and run sidegraph-sync --check
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — anchor health not applicable"
+            exit 0
+          fi
+          uvx --from graphifyy==0.9.6 graphify update .
+          uv sync --locked
+          uv run sidegraph-sync --json --check

sidegraph-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+# Build and publish sidegraph to PyPI on a version tag — gated on the full test suite.
+#
+# Trigger: push a semver tag, e.g. `git tag v0.1.0 && git push origin v0.1.0`. Deliberately
+#          no `workflow_dispatch`: a manual run has no tag ref, and the "tag matches pyproject
+#          version" check below only means something against a real tag ref. Keeping a manual
+#          trigger around that can never pass that check is pointless at best; before Trusted
+#          Publishing goes live for 0.1.0 it would be one stray click away from publishing an
+#          untagged tree under whatever version pyproject.toml happens to carry.
+# Gate:    the `test` job reuses ci.yml (pre-commit lint + pytest across the Python matrix);
+#          build/publish only run if it passes. `git-tag == pyproject version` is enforced
+#          unconditionally (not just `if: startsWith(github.ref, 'refs/tags/')`) so a mistyped
+#          tag never ships, and so a future trigger that isn't a tag push fails this check
+#          loudly instead of silently skipping it.
+# Auth:    PyPI Trusted Publishing (OIDC) — no API token stored. One-time PyPI setup:
+#          project `sidegraph` → Trusted Publishers → add owner `SantyagoSeaman`, repo
+#          `sidegraph`, workflow `publish.yml`, environment `pypi`. Also create a GitHub
+#          environment named `pypi` (Settings → Environments) for the protection rule.
+# TestPyPI dry run first (recommended): locally `uv build` then
+#          `uv publish --publish-url https://test.pypi.org/legacy/` (needs a TestPyPI token),
+#          and `pip install -i https://test.pypi.org/simple/ sidegraph` to smoke the wheel.
+name: publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # zizmor self-repository: flags this as the older `./...` reusable-workflow reference and
+    # suggests the newer `$/...` form. Not applied: GA support for `$/...` on the runners this
+    # workflow actually executes on is unconfirmed, and this reference is exactly the job graph
+    # the task guardrails say not to touch on a guess — a broken reusable-workflow call here
+    # would silently skip the test gate in front of a PyPI publish. `./...` is GitHub's
+    # documented, stable syntax for a same-repo reusable workflow.
+    uses: ./.github/workflows/ci.yml # zizmor: ignore[self-repository] stable syntax kept; see comment above
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Tag matches pyproject version
+        # Unconditional on purpose: `on:` above only triggers this workflow from a tag push,
+        # but this check is the backstop if that ever changes (e.g. workflow_dispatch comes
+        # back without this comment being read first). A non-tag ref fails it cleanly instead
+        # of silently skipping straight to build/publish.
+        run: |
+          VERSION=$(uv run --no-project python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG="${GITHUB_REF_NAME#v}"
+          [ "$VERSION" = "$TAG" ] || { echo "tag v$TAG != pyproject version $VERSION — bump one to match" >&2; exit 1; }
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

sidegraph-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,46 @@
+name: scorecard
+
+# OpenSSF Scorecard — supply-chain / security-health analysis. Publishes to the public
+# OpenSSF API so the README badge works.
+#
+# This file ships to the public repo by snapshot but must not run in the internal
+# development repo (private; the analysis is meaningless there) — hence the repository guard
+# on the job rather than a public-only overlay mechanism.
+on:
+  workflow_dispatch:
+  branch_protection_rule:
+  schedule:
+    - cron: "20 7 * * 1" # weekly, Monday 07:20 UTC
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    if: github.repository == 'SantyagoSeaman/sidegraph'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write # publish results to the OpenSSF API (required for the badge)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5

sidegraph-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# Sidegraph local store (the committed sidecar lives in the target repo, not here)
+sidegraph.db
+*.db-journal
+
+# Graphify engine output — read-only input, regenerated by `graphify update` (invariant #1)
+graphify-out/
+
+# sidegraph-viz output — generated artifact, regenerated by `sidegraph-viz`
+sidegraph-graph.html
+sidegraph-graph.json
+
+# Corpus leak-gate secondary token denylist (never committed — holds sensitive markers)
+/.corpus-leak-denylist
+
+# promote-fixtures displaces originals here while copying; removed on every controlled path,
+# but a hard kill (SIGKILL) can leave one behind
+tests/fixtures/.promote-fixtures-trash-*
+
+# The private sidegraph-sandbox testbed is never nested inside this OSS repo
+/sidegraph-sandbox/
+
+# Corpus working copies must never live inside this tree (spec §3). The guard test is the
+# mechanism; this entry is the backstop that stops an accidental nesting being committed
+# before the guard runs.
+sandboxes/
+
+# Machine-local host/tool configs and flow scratch — never repo state. .mcp.json points at
+# a localhost MCP port that dies with the IDE session; .codex/ is the Codex CLI's local
+# config; .superpowers/ is the flow's working scratch (briefs/diffs/tokens) whose durable
+# outputs are distilled into design/superpowers/ and the store.
+#
+# Anchored to the repo root (leading "/"): these patterns exist only to ignore the developer's
+# OWN root-level scratch files/dirs, never a project file that happens to share the basename.
+# Unanchored, they matched (and silently untracked-from-`git add -A`) tracked, force-added
+# project content at any depth — plugin/sidegraph/.mcp.json (the Claude plugin's MCP manifest)
+# and three Codex bootstrap fixtures under tests/fixtures/ — which is exactly how the first
+# real public release's commit shipped missing those four files (design/testing intact on
+# disk, dropped from the commit because the public checkout's `git add -A` obeys .gitignore).
+/.mcp.json
+/.codex/
+/.superpowers/
+/.worktrees/

sidegraph-0.1.0/.gitleaks.toml

@@ -0,0 +1,32 @@
+title = "sidegraph gitleaks config"
+
+# Extends gitleaks' default ruleset rather than replacing it.
+[extend]
+useDefault = true
+
+# Path-scoped allowlist, never a global disable: every path below either belongs to the
+# redaction feature's own test fixtures (deliberately shaped like a real credential so the
+# redaction regexes in src/sidegraph/capture.py have something to catch — see
+# tests/test_capture_redact.py's docstring), a design-plan doc quoting the same fixtures, or
+# vendored third-party content we do not edit. A real secret anywhere else in the repo still
+# fails the scan. This file ships to the public repo (tests/ ships wholesale with the same
+# fixtures), so it has to hold there too.
+[allowlist]
+description = "Known-fake secrets in redaction-feature fixtures and vendored/planning content"
+paths = [
+  '''^tests/test_capture_redact\.py$''',
+  '''^tests/test_redaction_seeded\.py$''',
+  '''^tests/test_capture_propose\.py$''',
+  '''^tests/test_capture_integration\.py$''',
+  '''^tests/test_capture_facts\.py$''',
+  '''^tests/test_importer\.py$''',
+  '''^tests/test_doc_import\.py$''',
+  '''^tests/test_domains\.py$''',
+  '''^tests/test_server_capture\.py$''',
+  '''^tests/test_server_domains\.py$''',
+  '''^tests/test_server_facts\.py$''',
+  '''^tests/test_server_redaction\.py$''',
+  '''^design/superpowers/plans/2026-07-06-capture-ratification\.md$''',
+  '''^design/superpowers/plans/2026-07-10-facts-layer\.md$''',
+  '''^src/sidegraph/viz/assets/vis-network\.min\.js$''',
+]

sidegraph-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,162 @@
+# The single definition of "lint" for this repo. The same file drives the local
+# pre-commit hook, `uv run pre-commit run --all-files`, the CI `lint` job, and the
+# release script's snapshot verification — so those four can never disagree.
+#
+# ruff and mypy run as `repo: local` hooks through `uv run` rather than through their
+# upstream pre-commit mirrors: that keeps exactly ONE version of each tool (the one
+# pinned in uv.lock), and lets mypy see the real project environment, which it needs
+# for the pydantic.mypy plugin configured in pyproject.toml.
+#
+# .sidegraph/ is excluded repo-wide: the store is append-only and machine-written, and
+# letting a whitespace fixer rewrite its records would mutate the store as a side effect
+# of committing. src/sidegraph/viz/assets/ holds a vendored 688 KB bundle that is not
+# ours to reformat. sidegraph-graph.html is the --demo release's generated decision-graph
+# viz (tools/release-public.sh force-adds it since it's gitignored internally): it's over a
+# megabyte and its size tracks the store, so check-added-large-files (--maxkb=1024) would
+# fail the FIRST --demo release at its own verification gate — a generated release artifact,
+# not something to lint or size-cap.
+# The whitepaper's VERBATIM raw-artifact bundle is excluded under BOTH of its paths: it
+# lives at design/whitepaper/evidence/artifact-bundle/ here and the release relocates it
+# to docs/whitepaper/evidence/artifact-bundle/ in the public snapshot, where this same
+# config runs again as the snapshot's verification step. Its scripts ship byte-identical
+# to what produced the published numbers, under a SHA-256 manifest — a formatter "fixing"
+# them falsifies both the verbatim promise and every hash. Measured, not hypothetical:
+# with only the internal path excluded, the first snapshot build reformatted nine bundle
+# scripts and broke 41 of the manifest's hashes. (The corpus leak gate still scans the
+# 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/)'
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]   # keep intentional two-space hard breaks in docs
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      # Catches a malformed pyproject.toml (or other tracked .toml) before it reaches CI's
+      # `uv sync --locked`, which fails on the same file far less legibly.
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: debug-statements
+      # Refuses a commit that adds a real private key (RSA/DSA/EC/OpenSSH) as a tracked file —
+      # the capture-redaction feature (src/sidegraph/capture.py) already regexes decision
+      # CONTENT for this pattern; this guards the source tree itself. Excludes the redaction
+      # feature's own fake-key test fixtures and the design note that quotes them, none of
+      # which is a real key.
+      - id: detect-private-key
+        exclude: |
+          (?x)^(
+            tests/test_capture_redact\.py|
+            tests/test_redaction_seeded\.py|
+            design/superpowers/plans/2026-07-06-capture-ratification\.md
+          )$
+
+  # Broad secret-detection net (AWS/GCP/GitHub/Slack tokens, private keys, etc.) beyond the
+  # corpus leak gate's fixed denylist and the redaction feature's own patterns — catches a
+  # live credential anywhere in a tracked file, not just the paths those two already watch.
+  # `.gitleaks.toml` path-scopes allowlisting for the redaction feature's own fake-token test
+  # fixtures (tests/test_capture_redact.py etc.), never a global disable.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  # Finds GitHub Actions supply-chain/security issues (unpinned actions, script injection via
+  # untrusted `${{ }}` template interpolation, excessive `permissions:`) in the workflows that
+  # ship to the public repo — the class of defect a human diff review easily misses.
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.30.1
+    hooks:
+      - id: zizmor
+
+  # Static-checks GitHub Actions workflow YAML (invalid expressions, undefined contexts,
+  # shellcheck issues inside `run:` steps) — complements zizmor's security focus with
+  # correctness checks zizmor does not cover.
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.12
+    hooks:
+      - id: actionlint
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+      - id: corpus-leak-gate
+        name: corpus leak gate
+        # `python3`, not `uv run python`: the checker is deliberately stdlib-only, so uv buys
+        # 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.
+        entry: bash -c 'test ! -f tools/corpus_leak.py || exec python3 tools/corpus_leak.py'
+        language: system
+        pass_filenames: false
+        always_run: true
+        require_serial: true
+      - id: uv-lock-check
+        name: uv.lock is in sync with pyproject.toml
+        # Catches a dependency bumped in pyproject.toml without refreshing uv.lock, which
+        # `uv sync --locked` (CI, and the release script's VERIFY_CMD/VIZ_CMD) would otherwise
+        # refuse at a much less convenient point — mid-release, or mid-CI-run.
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+      - id: check-public-twins
+        name: public-twin contract check
+        # A `.public.` twin (plugin manifest, CLAUDE.public.md, CONTRIBUTING.public.md,
+        # 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.
+        entry: bash -c 'test ! -f tools/check_public_twins.py || exec python3 tools/check_public_twins.py'
+        language: system
+        pass_filenames: false
+        always_run: true
+        require_serial: true
+      - id: check-shipped-links
+        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.
+        entry: bash -c 'test ! -f tools/check_shipped_links.py || exec python3 tools/check_shipped_links.py'
+        language: system
+        pass_filenames: false
+        always_run: true
+        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
+        # own schema before they ship, catching a manifest that would fail to install silently
+        # different from how it fails here. Skips cleanly (exit 0) where the `claude` CLI is
+        # not on PATH, e.g. the public repo's CI.
+        entry: bash -c 'command -v claude >/dev/null || exit 0; claude plugin validate .claude-plugin/marketplace.json && claude plugin validate plugin/sidegraph'
+        language: system
+        pass_filenames: false
+        files: ^(\.claude-plugin/|plugin/sidegraph/)

sidegraph-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13