sidegraph 0.12.0__tar.gz → 0.14.0__tar.gz

{sidegraph-0.12.0 → sidegraph-0.14.0}/.github/workflows/ci.yml

@@ -192,6 +192,9 @@ jobs:
             tests/test_server_result_contract.py tests/test_server_invocation_policy.py `
             tests/test_verify_git_stdin.py tests/test_seed_paths_portable.py `
             tests/test_repo_relative_paths_portable.py `
+            tests/test_command_windows.py `
+            tests/test_hook_payload_encoding.py `
+            tests/test_git_output_utf8.py `
             $privateTests `
             tests/test_installed_wheel_smoke.py
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
@@ -326,11 +329,15 @@ jobs:
           cache-dependency-glob: "uv.lock"
 
       - name: Rebuild graph and run sidegraph-sync --check
+        env:
+          GRAPHIFY_NO_AUTO_REFRESH: "1"
+          PYTHONHASHSEED: "0"
+          GRAPHIFY_MAX_WORKERS: "1"
         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 .
+          uvx --from graphifyy==0.9.90 graphify update .
           uv sync --locked
           uv run sidegraph-sync --json --check

sidegraph-0.14.0/.opencode/INSTALL.md

@@ -0,0 +1,67 @@
+# Install Sidegraph in OpenCode V2
+
+Requires OpenCode V2, `uv` and Git on PATH. The current native integration baseline is
+OpenCode 2.0.29. Sidegraph provides MCP tools and shared skills; lifecycle hooks are not
+included. Ask for context and capture decisions explicitly through the tools.
+
+Install the Git package with OpenCode's native command:
+
+```bash
+opencode plugin add 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'
+```
+
+Start a new OpenCode session in your project. Follow `@sidegraph-setup` to prepare its
+graph and store, then call `list_domains()` to check MCP access. Use
+`get_task_context(files=[...])` before working on files and `propose_decisions` to capture
+durable findings. Other shared skills use `@sidegraph-<skill>` (for example,
+`@sidegraph-check-plan`). There is no automatic SessionStart map or Stop nudge.
+
+The equivalent `opencode.json` entry is:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["git+https://github.com/SantyagoSeaman/sidegraph.git#main"]
+}
+```
+
+Merge that entry with any existing plugin list. The plugin supplies one `sidegraph` MCP
+server only when that name has no explicit configuration. An existing entry, including
+`disabled: true`, stays unchanged. OpenCode V2 stores overrides under `mcp.servers`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "sidegraph": {
+        "type": "local",
+        "command": [
+          "uvx",
+          "--from",
+          "git+https://github.com/SantyagoSeaman/sidegraph.git@main",
+          "sidegraph-mcp",
+          "--repo-root"
+        ],
+        "environment": {
+          "SIDEGRAPH_DIR": ".sidegraph",
+          "SIDEGRAPH_GRAPH": "graphify-out/graph.json"
+        }
+      }
+    }
+  }
+}
+```
+
+Use this override only when you want to manage the server yourself. Keep OpenCode's normal
+MCP and skill permissions; no additional Sidegraph plugin-approval command is required.
+
+Check and apply package updates, then restart OpenCode:
+
+```bash
+opencode plugin check 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'
+opencode plugin update 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'
+```
+
+The Git package target `#main` follows public releases. The MCP runtime uses its configured
+Git ref (normally `@main`); this host has no SessionStart version pin. Updating cached
+plugin files and resolving the MCP runtime are separate operations.

{sidegraph-0.12.0 → sidegraph-0.14.0}/AGENTS.md

@@ -76,4 +76,4 @@ Rules:
 - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
-- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+- After modifying code, run `graphify update .` with the environment variable `GRAPHIFY_NO_AUTO_REFRESH=1` set to keep the graph current (AST-only, no API cost).

{sidegraph-0.12.0 → sidegraph-0.14.0}/CHANGELOG.md

@@ -7,6 +7,167 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-10-16
+
+### Graphify 0.9.90
+
+Migration steps: [migrate to Sidegraph 0.14](docs/guides/migrating-to-0.14.md).
+
+- Anchors to files with the same basename keep resolving after the engine upgrade.
+- External names resolve when Graphify emits several identical stub nodes.
+- Re-importing rationale does not duplicate compatible labels shortened by a newer engine.
+- `sidegraph-domains snapshot` preserves domain membership across engine regrouping.
+- A store can require a minimum Sidegraph version before clients read or write it.
+- Graphify leaves installed agent skills alone when Sidegraph runs it.
+
+### Changed
+
+- OpenCode V2 can install Sidegraph as a native Git package with shared skills and MCP
+  tools. Existing skill IDs and explicit MCP server settings take precedence. See the
+  [OpenCode installation guide](.opencode/INSTALL.md).
+- Muse has an experimental native plugin with shared skills and MCP tools. Launch Muse
+  from the intended project directory; lifecycle hooks are deferred. See the
+  [Muse installation guide](docs/integrations/muse.md).
+- A graph community that holds code and documents is split in two before domains are
+  computed. Graphify 0.9.62 and later link documents to the code they mention, which merged
+  them.
+- Domain membership is computed by each sync and kept per node. A path prefix now adds its
+  files at sync time, not when a domain is read. A decision anchored under a path rule that
+  the 20% cap kept off the communities now reaches that domain too.
+- A domain whose refresh fails keeps its previous membership whole and is reported again by
+  every later sync until its cause is fixed; `--force` retries it.
+- A domain-membership pass that cannot run because another process holds the store is
+  reported once, as `domain membership not refreshed: the store's writer was busy`, and the
+  next sync runs it; `--check` does not count it. A pass that fails as a whole is reported
+  as `*` (every accepted domain) until its cause is fixed.
+- The `supersede_domain` answer carries `snapshot_note` when the domain's membership is
+  frozen.
+
+### Fixed
+
+- SessionStart and Stop no longer create an absent store. Missing host-relative stores are
+  selected at the Git root; MCP first use requires explicit setup for nested or non-Git
+  destinations. Init distinguishes an empty scaffold from a store with authored content
+  and still prints setup guidance.
+- The MCP server applies the committed ratification policy from the selected store's
+  project when no policy is set in its environment, including cross-project and symlinked
+  stores. Missing settings keep the manual default.
+- Doctor excludes committed file deletions from code drift while binding statuses are
+  uncomputed, and qualifies remaining changes as having unknown binding status. Projects
+  without a graph still report changes to surviving anchored files.
+- Hot hooks withhold records and memory counts on a new store or after an index reload until
+  sync computes binding statuses, so placeholder `live` rows cannot revive orphaned anchors.
+- Community names from newer Graphify builds are read from curated labels, pending hub names,
+  then node names. Hub labels use the file's basename within their own community.
+- Graphify's post-merge hook marker is recognised alongside its other refresh-hook markers.
+- SessionStart and doctor advise when a graph's engine stamp is outside the tested releases.
+  The advisory adds no human notice; doctor's `--check` exits 2 when it is present.
+
+- `sidegraph-import` recognises compatible re-cut rationale labels by their exact file/node
+  context as well as the existing title/origin key, reducing duplicate imports after a
+  Graphify upgrade or rollback.
+
+- Every Graphify run Sidegraph starts or tells you to start now sets `GRAPHIFY_NO_AUTO_REFRESH=1`.
+  Graphify 0.9.87 and later refresh the agent skills they installed (such as
+  `~/.claude/skills/graphify/`) on the first run after a Graphify upgrade unless that variable is
+  set. The graph refresh hook's helper, the CI recipes, the copyable commands in the docs and the
+  setup skill set it, and the rebuild instructions Sidegraph prints name it. Graphify 0.9.6 does
+  not read the variable.
+- Anchors to files that share a basename keep resolving on newer Graphify. Graphify 0.9.87 and
+  later label such a file by a path suffix (`sidegraph/cli.py`) instead of its basename; Sidegraph
+  reads those nodes as basenames again, so an anchor `cli.py` in `src/sidegraph/cli.py` still
+  finds its node, and the engine's own label still resolves too.
+- A path-named anchor (`src/sidegraph/store.py` with its own `file_path`) now resolves to that
+  file's node on any Graphify version, and is stored under the basename. Entities an earlier
+  version named by the full path heal at the one-time resync that follows the upgrade.
+- `find_entity` reads the spelling twins of one file (an entity named by the file's path beside
+  one named by its basename) as one entity, and `get_entity_history` lists the records bound to
+  any twin. New anchors, lookups and duplicate detection compare names the same way.
+- An anchor `file_path` given as an absolute path under the repository, with backslashes on
+  Windows, or with a leading `./` is stored repo-relative with forward slashes and binds live
+  instead of orphaning, through the MCP write tools and through capture. When a store sits in a
+  subdirectory of its repository, the root whose path the graph holds is the one used.
+- An anchor naming an imported external type (`BaseModel`, `Path`) now binds even when Graphify
+  emits one stub node per importing file. The stubs count as one match when none has a file and
+  they share a label and a node type, and the anchor gets a group binding only when they share a
+  community. This applies on every Graphify version. A type and a module of one name (`FastMCP`
+  and `fastmcp`) and repository code are still told apart. Document mentions of such names do
+  not gain a precise leaf binding, and reading surfaces keep their earlier resolution answers.
+- Sync reports an anchor whose file disappeared and whose name now matches only external stubs
+  as orphaned. A resolved external anchor without a community no longer prevents other anchors'
+  previous community bindings from being retired. A formerly shared group also retires when
+  the stubs split. Ambiguous anchors and failed rebinds keep those bindings when their current
+  community is unknown.
+
+### Added
+
+- `sidegraph-domains snapshot` freezes every accepted domain's membership into
+  `.sidegraph/domain-snapshot.json`, so a Graphify upgrade that regroups communities does not
+  move domains. It raises the store's minimum Sidegraph version to 0.14.0. `--build-with
+  VERSION` takes the snapshot from `HEAD` rebuilt with an older Graphify; `--refresh`
+  re-freezes it; `--dry-run` prints the counts it would freeze and leaves committed files unchanged.
+- `sidegraph-verify` reports `bad-domain-snapshot` and `snapshot-without-requirement`;
+  `sidegraph-doctor` reports `snapshot-split`; `sidegraph-sync --json` and `sync_anchors`
+  carry `snapshot_splits`.
+
+
+- `sidegraph-require --sidegraph X.Y.Z` makes a store require at least that Sidegraph release:
+  the committed marker is raised atomically and never lowered. New clients check it before
+  using the store; verification reports malformed requirements and requirements above its version.
+
+- `sidegraph-doctor` prints informational `spelling twins` lines for an entity named by a path of
+  its file beside one named by the basename. They are not findings and do not change the exit
+  code. `duplicate-entity` no longer reports such a pair.
+
+- A new advisory check, `refresh-helper-outdated`, reports a graph refresh hook whose helper runs
+  Graphify without `GRAPHIFY_NO_AUTO_REFRESH=1` (the helper an earlier `sidegraph-init` wrote). It
+  shows as a SessionStart line and notice and as a `sidegraph-doctor` finding, and
+  `sidegraph-doctor --check` exits `2` on it. Run `sidegraph-init` with no flag: it rewrites the
+  helper and keeps your recorded hook choice. The helper lives in `.git/hooks`, so each clone
+  runs it once.
+
+## [0.13.0] — 2026-10-14
+
+### Fixed
+
+- On Windows, hooks misread the payload the host sends when a path in it has a non-ASCII
+  character (an accented or Cyrillic user name or project folder). The Stop capture reminder
+  never fired, PreToolUse delivered no records, and for some names SessionStart and
+  SubagentStart printed nothing.
+- On Windows, a non-ASCII git user name, branch name or repository path was read back garbled:
+  a ratified record could carry a garbled name in its provenance, and `sidegraph-verify
+  --against` failed or reported false changes for records containing non-ASCII text.
+- A change to a file whose name has non-ASCII characters, spaces or quotes was missed by the
+  drift check and the commit-trailer candidates, because git escaped the name.
+- On Windows, a Codex hook started from a subdirectory of a repository whose path has non-ASCII
+  characters now runs from the repository root.
+- A default Git for Windows install no longer breaks the MCP server. Its installer puts only
+  `Git\cmd` on PATH, which has no `sh`, so the server, which started with `sh`, did not start.
+  The Codex hooks have a Windows command for the same reason (see Changed).
+- The project's ratify policy now applies under Codex. `sidegraph-init` commits it to
+  `.claude/settings.json`, which Codex does not read, so under Codex every agent proposal
+  waited for review whatever the team chose. The plugin's MCP server now reads the committed
+  value when its environment sets none; an explicit `SIDEGRAPH_RATIFY_POLICY` still wins.
+
+### Changed
+
+- The plugins launch without `sh` on PATH. Both MCP launchers start `uvx` (`uv` in the
+  development manifest) directly, and `sidegraph-mcp --repo-root` anchors the server to the
+  project: `CLAUDE_PROJECT_DIR`, else the git top-level, else the working directory. The Codex
+  hooks gain a PowerShell `commandWindows` that Windows PowerShell 5.1 parses. On native Windows
+  you need no PATH change and no PowerShell 7; Git for Windows at its default options is
+  enough. The Codex hooks need a Codex release that supports `commandWindows` (verified with
+  0.162.1). The Windows hook definition changes, so approve the changed hooks once in `/hooks`
+  on Windows; other platforms are unaffected.
+- The optional terminal CLI now installs from the same place as the plugin, the public
+  repository's `main` branch: `uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  updated after each release with `uv tool upgrade sidegraph`. The docs no longer send you to
+  PyPI for it; PyPI still carries every release for pinning an exact version. The `path-skew`
+  SessionStart line now offers `uv tool install --reinstall git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  which moves an older install from PyPI, pinned or not, to the latest release.
+- README: the Quickstart is one numbered sequence with the plugin commands inline, a teammate
+  path, and the rarer options below it; "How it works" is a numbered list instead of a diagram.
+
 ## [0.12.0] — 2026-10-12
 
 ### Fixed

{sidegraph-0.12.0 → sidegraph-0.14.0}/CLAUDE.md

@@ -5,7 +5,7 @@ that doesn't forget *why* things are the way they are as time passes and people
 
 **Thesis: own the memory, rent the graph.** Sidegraph owns an append-only, repo-committed
 decision store and layers it as a **sidecar** over a mature code-graph engine
-([Graphify](https://github.com/safishamsi/graphify)) rather than re-building entity extraction
+([Graphify](https://github.com/Graphify-Labs/graphify)) rather than re-building entity extraction
 and graph construction. The edge over session-memory tools is durable anchoring + budgeted,
 task-aware retrieval + decision memory riding on the engine's entity graph.
 
@@ -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.12.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.14.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
@@ -53,6 +53,7 @@ src/sidegraph/
 ├── schema.py        # Pydantic models: Entity, Decision, Fact, AnchorBinding, Domain, Initiative
 ├── store.py         # owned append-only store (file-per-record JSON); enforces invariants on write
 ├── retrieval.py     # multi-altitude, budget-bounded, task-aware read path (mistakes first)
+├── domain_snapshot.py  # committed domain-membership snapshot: format and matching rules
 ├── hot_index.py     # raw-sqlite handle on index.db for the hook hot path (no Store, no pydantic)
 ├── store_layout.py  # store constants and rules shared with the hot path (pydantic-free)
 ├── server.py        # FastMCP decision MCP — the tools agents call