opencode-gbuild 0.4.0 → 0.5.0

package/README.md

@@ -38,17 +38,17 @@ claude --plugin-dir ./plugins/gbuild
 
 ### OpenCode
 
-The same directory is also an OpenCode (V2) plugin — `index.ts` registers the five skills and five
-slash commands (`/gbuild-plan`, `/gbuild-run`, `/gbuild-status`, `/gbuild-review`, `/gbuild-pr`) from
-the same markdown the Claude plugin uses.
-
-From GitHub (subdirectory selector):
+The same directory is also an OpenCode (V2) plugin, published to npm as
+[`opencode-gbuild`](https://www.npmjs.com/package/opencode-gbuild) — `index.ts` registers the five
+skills and five slash commands (`/gbuild-plan`, `/gbuild-run`, `/gbuild-status`, `/gbuild-review`,
+`/gbuild-pr`) from the same markdown the Claude plugin uses.
 
 ```bash
-opencode plugin add 'github:oskarhane/oskars.ai#main::path:plugins/gbuild'
+opencode plugin add opencode-gbuild
 ```
 
-Or point any `opencode.json(c)` at a local checkout:
+`opencode plugin update opencode-gbuild` moves to the latest published version. For local
+development, point any `opencode.json(c)` at a checkout instead:
 
 ```jsonc
 {
@@ -56,6 +56,14 @@ Or point any `opencode.json(c)` at a local checkout:
 }
 ```
 
+#### Releasing
+
+The npm package is published from this directory:
+
+1. Bump `version` in `package.json` — keep `.claude-plugin/plugin.json`'s version in sync.
+2. `npm publish` (2FA on the account; contents are whitelisted via `files` + `.npmignore`).
+3. Users pick it up with `opencode plugin update opencode-gbuild`.
+
 One translation note: OpenCode plugins can't register agents, so where the Claude plugin spawns its
 bundled `gbuild-reviewer`/`gbuild-auditor` agents, the OpenCode skills dispatch the built-in `general`
 subagent with the same `agents/gbuild-*.md` text inlined as its brief. The review is still a fresh,
@@ -83,7 +91,7 @@ OpenCode (same order, kebab-case names):
 /gbuild-pr add-oauth-login-with-github
 ```
 
-- **`plan`** decomposes a feature into `.gbuild/<feature>/graph.json` — a plain JSON graph file with
+- **`plan`** decomposes a feature into `.gbuild/<feature>/db/graph.json` — a plain JSON graph file with
   `Feature`, `Acceptance`, and `GbuildNode` nodes linked by `DEPENDS_ON`/`HAS_ACCEPTANCE`/`SATISFIES`
   relationships. Every dependency edge passes the cut test (does the dependent actually read the
   dependency's output?); every node has mandatory concrete acceptance criteria. Validated with
@@ -172,14 +180,17 @@ required. That's also why the graph file is `graph.json` rather than YAML: Pytho
 parser, and adding PyYAML would defeat the zero-extra-dependencies goal. The file is written and read by
 agents, not hand-edited, so losing comments costs little — `/gbuild:status` is the human-facing view.
 
+The plan is a CypherLite GraphData file at `.gbuild/<feature>/db/graph.json`; because CypherLite opens a
+*directory* store, it queries via the folder: `cypherlite .gbuild/<feature>/db "MATCH (n:GbuildNode) RETURN n.slug"`. Checkpoints stay in the sibling `.gbuild/<feature>/nodes/` dir, outside `db/`.
+
 ```bash
-python3 plugins/gbuild/scripts/validate_format.py .gbuild/<feature>/graph.json   # format gate (run after every change)
-python3 plugins/gbuild/scripts/graph.py .gbuild/<feature>/graph.json --status     # frontier/blocked/waves
+python3 plugins/gbuild/scripts/validate_format.py .gbuild/<feature>/db/graph.json   # format gate (run after every change)
+python3 plugins/gbuild/scripts/graph.py .gbuild/<feature>/db/graph.json --status     # frontier/blocked/waves
 python3 -m unittest plugins/gbuild/scripts/test_graph.py
 ```
 
 `validate_format.py` does stdlib JSON checks always; if the `cypherlite` binary is on PATH it *also*
-opens the file with CypherLite to confirm the real loader accepts it (catches serde issues the stdlib
+opens the graph with CypherLite to confirm the real loader accepts it (catches serde issues the stdlib
 walk can't). CypherLite is an optional consumer, not a dependency — absent binary → cross-check skipped
 silently; `--no-cypherlite` forces the skip.
 
@@ -199,6 +210,7 @@ plugins/gbuild/
   smoke.test.ts               # node --test smoke test for the OpenCode translation (repo-root `npm test`)
 ```
 
-State lives outside the plugin, in the project: `.gbuild/<feature>/graph.json` (a CypherLite GraphData
+State lives outside the plugin, in the project: `.gbuild/<feature>/db/graph.json` (a CypherLite GraphData
 file, written once by `plan`) and `.gbuild/<feature>/nodes/<slug>.json` (one checkpoint per node,
-written by `run`).
+written by `run`). The graph sits alone in `db/` so CypherLite can open that folder as a database;
+`nodes/` is a sibling, outside the folder CypherLite opens.

package/agents/gbuild-auditor.md

@@ -7,7 +7,7 @@ description: Strict end-of-feature maintainability auditor for a gbuild feature
 
 Unusually strict review of implementation quality, maintainability, and abstraction health. Push for **ambitious** restructurings — "code judo" moves that preserve behavior while making the code dramatically simpler, smaller, and more direct. Delete complexity; don't rearrange it.
 
-The caller passes you the resolved feature slug and its graph path (`.gbuild/<slug>/graph.json`, a CypherLite GraphData file). Read the `Feature` node's `destination` property, the `Acceptance` nodes (linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`), and the per-node `output` values in `.gbuild/<slug>/nodes/*.json` (keyed by the GbuildNode `slug` property) for scoping context only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). Do NOT write any file — output your audit as your final message exclusively.
+The caller passes you the resolved feature slug and its graph path (`.gbuild/<slug>/db/graph.json`, a CypherLite GraphData file). Read the `Feature` node's `destination` property, the `Acceptance` nodes (linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`), and the per-node `output` values in `.gbuild/<slug>/nodes/*.json` (keyed by the GbuildNode `slug` property) for scoping context only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). Do NOT write any file — output your audit as your final message exclusively.
 
 ## Core Prompt
 

package/agents/gbuild-reviewer.md

@@ -9,7 +9,7 @@ declared bar.
 
 ## WHAT YOU'RE GIVEN
 
-- The node's full definition from `graph.json` (a CypherLite GraphData file): its `slug`, `title`, `type`,
+- The node's full definition from `.gbuild/<slug>/db/graph.json` (a CypherLite GraphData file): its `slug`, `title`, `type`,
   `contract.input`, `contract.output`, and `acceptance` — all read from the GbuildNode's `properties`.
 - What the node's agent actually produced.
 - For `code`/`test`/`chore` nodes: the git diff for this node's work (`git diff HEAD`, or

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-gbuild",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OpenCode plugin for gbuild — graph-native task planning and execution with concurrent fan-out, per-node review, and durable checkpoints.",
   "type": "module",
   "license": "MIT",

package/reference/graph-format.md

@@ -2,14 +2,25 @@
 
 This file is normative. Where a skill disagrees with this doc, this doc wins.
 
-One file per feature: `.gbuild/<feature>/graph.json`, written once by `plan`, read-only during `run`.
+One file per feature: `.gbuild/<feature>/db/graph.json`, written once by `plan`, read-only during `run`.
 
-**`graph.json` is a CypherLite GraphData file.** Open it directly with CypherLite and query it with Cypher:
+**`graph.json` is a CypherLite GraphData file.** It lives alone in its own `db/` folder so CypherLite can open that folder as a database and query it with Cypher — CypherLite opens a *directory* holding `graph.json`, not a bare `.json` file:
 
 ```
-cypherlite .gbuild/<feature>/graph.json "MATCH (n:GbuildNode) RETURN n.slug, n.type"
+cypherlite .gbuild/<feature>/db "MATCH (n:GbuildNode) RETURN n.slug, n.type"
 ```
 
+The `db/` folder contains `graph.json` and nothing else that CypherLite cares about. Checkpoints live in the sibling `.gbuild/<feature>/nodes/` directory (see [State](#state-not-part-of-graphjson)) — deliberately *outside* `db/`, because CypherLite reads a directory named `nodes` as Parquet shards and would reject the store as "mixed snapshot codecs". Opening `db/` also makes CypherLite create a `db/wal/` directory; that is expected. **Only run read-only `MATCH … RETURN` Cypher against the plan** — a writing query could checkpoint and rewrite the write-once `graph.json`.
+
+### Interoperability with CypherLite
+
+`graph.json` is the *same* JSON snapshot CypherLite reads and writes — there is one store file, not a gbuild copy and a CypherLite copy. Two consequences:
+
+- **The store must be the JSON codec.** gbuild always writes `graph.json`, so the store is JSON by construction. A Parquet store directory is not readable by gbuild's stdlib parsers.
+- **A CypherLite checkpoint normalizes the file.** If a writing Cypher command is followed by `.checkpoint` (or the WAL rotates), CypherLite rewrites `graph.json` in full — adding `value_encoding` — and leaves `manifest.json` and `wal/` beside it. gbuild's parsers read only `nodes` / `relationships` / `next_node_id` / `next_rel_id` and ignore the rest, so the checkpointed snapshot remains valid and queryable by `graph.py` / `validate_format.py` unchanged.
+
+CypherLite can *read* every property gbuild writes, including the `contract` map. It cannot **write** map property values via Cypher (`InvalidPropertyType`), so a node authored purely through Cypher cannot carry `contract` today — direct JSON authoring remains the way `plan` writes it.
+
 JSON, not YAML — `scripts/graph.py` and `scripts/validate_format.py` are stdlib-only and Python's stdlib has no YAML parser. Comments are lost; that's fine, the file is agent-authored, not hand-typed. `/gbuild:status` is the human-facing view.
 
 **Validate after every change.** `scripts/validate_format.py <path>` is the format gate — run it after the initial write, after any reopen edit, after any hand-edit, before doing anything else with the file (including committing). It exits 0 + `valid: <feature>` on success, 1 + every error joined on failure. Fix the file and re-run until it passes; never hand off or run an invalid graph.

package/scripts/graph.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python3
 """gbuild graph utility: validate, topo-order, and query a graph.json feature graph.
 
-graph.json is a CypherLite GraphData file — openable with `cypherlite <path>` and
-queryable with Cypher. This module is the query layer (topo waves, frontier,
+graph.json is a CypherLite GraphData file. It lives at
+`.gbuild/<feature>/db/graph.json` so CypherLite can open the `db/` folder as a
+JSON-store database (CypherLite opens a *directory*, not a bare `.json` file)
+and query it with Cypher. This module is the query layer (topo waves, frontier,
 status report) over that file. Format validation lives in validate_format.py
 (the single source of truth for the contract); this module imports and re-exports
 its validate() and enum sets.
@@ -10,11 +12,11 @@ its validate() and enum sets.
 Stdlib only, no pip install required. Schema: ../reference/graph-format.md
 
 CLI:
-  python3 graph.py <graph.json> --waves     print the topological wave decomposition
-  python3 graph.py <graph.json> --frontier  print node ids ready to run right now
-  python3 graph.py <graph.json> --status    print the full status report (default)
+  python3 graph.py <feature>/db/graph.json --waves     print the topological wave decomposition
+  python3 graph.py <feature>/db/graph.json --frontier  print node ids ready to run right now
+  python3 graph.py <feature>/db/graph.json --status    print the full status report (default)
 
-Checkpoints are read from <graph dir>/nodes/<slug>.json by default, or --state-dir.
+Checkpoints are read from <feature>/nodes/<slug>.json by default, or --state-dir.
 """
 import argparse
 import json
@@ -195,13 +197,19 @@ def compute_frontier(graph, state_dir):
 
 
 def default_state_dir(graph_path):
-    return Path(graph_path).resolve().parent / "nodes"
+    """Checkpoints live in the sibling `nodes/` dir, next to the `db/` graph folder.
+
+    The plan is `<feature>/db/graph.json` and state is `<feature>/nodes/`; the
+    two are siblings so CypherLite's `nodes/` Parquet-shard detection never sees
+    the checkpoint dir inside the folder it opens.
+    """
+    return Path(graph_path).resolve().parent.parent / "nodes"
 
 
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument("graph_path")
-    parser.add_argument("--state-dir", default=None, help="checkpoint dir, default: <graph dir>/nodes")
+    parser.add_argument("--state-dir", default=None, help="checkpoint dir, default: <feature>/nodes")
     group = parser.add_mutually_exclusive_group()
     group.add_argument("--waves", action="store_true")
     group.add_argument("--frontier", action="store_true")

package/scripts/test_graph.py

@@ -26,6 +26,20 @@ TEMPLATE = PLUGIN_ROOT / "templates" / "graph.json"
 CYPHERLITE_BIN = shutil.which("cypherlite")
 
 
+def cypherlite_query(graph_path, query):
+    """Run a Cypher query against a GraphData file the way gbuild does.
+
+    CypherLite opens a directory store holding `graph.json`, not a bare `.json`
+    file, so stage the file in a scratch dir as `graph.json` and open that.
+    """
+    with tempfile.TemporaryDirectory() as d:
+        shutil.copyfile(graph_path, Path(d) / "graph.json")
+        return subprocess.run(
+            [CYPHERLITE_BIN, d, "-json", query],
+            capture_output=True, text=True,
+        )
+
+
 # --- canonical factories emitting GraphData ---------------------------------
 
 def _gbuild_node(nid, slug, ntype="code", deps=None, satisfies_acc=None, **overrides):
@@ -338,10 +352,7 @@ class CypherLiteLoadTests(unittest.TestCase):
     def test_template_loads_and_queries(self):
         g = load_graph(str(TEMPLATE))
         q = "MATCH (n:GbuildNode) RETURN n.slug AS slug ORDER BY slug"
-        res = subprocess.run(
-            [CYPHERLITE_BIN, str(TEMPLATE), "-json", q],
-            capture_output=True, text=True,
-        )
+        res = cypherlite_query(TEMPLATE, q)
         self.assertEqual(res.returncode, 0, res.stderr)
         rows = json.loads(res.stdout)
         slugs = [r["slug"] for r in rows]
@@ -350,13 +361,29 @@ class CypherLiteLoadTests(unittest.TestCase):
             "c-consume-squared", "d-join-and-sum",
         ])
 
+    def test_sibling_nodes_dir_does_not_collide(self):
+        # The plan lives in <feature>/db/ and checkpoints in <feature>/nodes/.
+        # CypherLite treats a directory named `nodes` inside the opened store as
+        # Parquet shards, so the checkpoint dir must stay outside `db/`.
+        with tempfile.TemporaryDirectory() as root:
+            feature = Path(root) / ".gbuild" / "example-diamond"
+            db = feature / "db"
+            nodes = feature / "nodes"
+            db.mkdir(parents=True)
+            nodes.mkdir(parents=True)
+            shutil.copyfile(TEMPLATE, db / "graph.json")
+            (nodes / "a-produce-shared-value.json").write_text('{"status": "completed"}')
+            res = subprocess.run(
+                [CYPHERLITE_BIN, str(db), "-json", "MATCH (n) RETURN count(n) AS c"],
+                capture_output=True, text=True,
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            self.assertEqual(json.loads(res.stdout)[0]["c"], 7)
+
     def test_template_transitive_deps(self):
         q = ("MATCH (n {slug:'d-join-and-sum'})-[:DEPENDS_ON*]->(d) "
              "RETURN DISTINCT d.slug AS slug ORDER BY slug")
-        res = subprocess.run(
-            [CYPHERLITE_BIN, str(TEMPLATE), "-json", q],
-            capture_output=True, text=True,
-        )
+        res = cypherlite_query(TEMPLATE, q)
         self.assertEqual(res.returncode, 0, res.stderr)
         rows = json.loads(res.stdout)
         self.assertEqual([r["slug"] for r in rows], [
@@ -366,10 +393,7 @@ class CypherLiteLoadTests(unittest.TestCase):
     def test_template_acceptance_query(self):
         q = ("MATCH (f:Feature)-[:HAS_ACCEPTANCE]->(a:Acceptance) "
              "RETURN a.id AS id ORDER BY id")
-        res = subprocess.run(
-            [CYPHERLITE_BIN, str(TEMPLATE), "-json", q],
-            capture_output=True, text=True,
-        )
+        res = cypherlite_query(TEMPLATE, q)
         self.assertEqual(res.returncode, 0, res.stderr)
         rows = json.loads(res.stdout)
         self.assertEqual([r["id"] for r in rows], ["a-1", "a-2"])

package/scripts/validate_format.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 """gbuild graph format validator — the authoritative contract for graph.json.
 
-graph.json is a CypherLite GraphData file (openable with `cypherlite <path>`).
+graph.json is a CypherLite GraphData file, living at
+`.gbuild/<feature>/db/graph.json` so CypherLite can open the `db/` folder as a
+JSON-store database (`cypherlite .gbuild/<feature>/db "MATCH ..."`).
 This module checks it is both CypherLite-loadable and gbuild-correct: the
 GraphData envelope, node shapes (Feature / Acceptance / GbuildNode), the three
 relationship types (DEPENDS_ON / HAS_ACCEPTANCE / SATISFIES), id/counter
@@ -12,7 +14,7 @@ Single source of truth for the format: graph.py imports VALID_* and
 SATISFIED_STATUSES from here, and its validate() calls validate() below.
 
 CLI:
-  python3 validate_format.py <graph.json>
+  python3 validate_format.py <feature>/db/graph.json
     exit 0 + "valid: <feature>"          on success
     exit 1 + "invalid: <errors joined>"  on failure
 """
@@ -20,6 +22,7 @@ import argparse
 import json
 import re
 import sys
+from pathlib import Path
 
 # --- enum sets (single definition site; graph.py imports these) -------------
 
@@ -297,23 +300,29 @@ def _detect_cycle(node_ids, edges):
 
 
 def _cypherlite_cross_check(graph_path):
-    """If cypherlite is on PATH, confirm CypherLite itself loads the file and
+    """If cypherlite is on PATH, confirm CypherLite itself loads the graph and
     can run a trivial query. Catches serde/encoding issues the stdlib walk can't
     (e.g. a top-level shape CypherLite's GraphData loader rejects). Returns an
     error string on failure, None on success or when cypherlite is absent.
 
+    CypherLite opens a *directory* store, not a bare `.json` file. To avoid
+    writing a WAL into the plan's `db/` folder during validation, copy the file
+    into a throwaway dir as `graph.json` and open that.
+
     Absence is silent — cypherlite is an optional consumer, not a dependency.
     """
     import shutil
     import subprocess
+    import tempfile
     bin_path = shutil.which("cypherlite")
     if bin_path is None:
         return None  # not installed — skip, not a failure
-    res = subprocess.run(
-        [bin_path, str(graph_path), "-json",
-         "MATCH (n) RETURN count(n) AS c"],
-        capture_output=True, text=True, timeout=30,
-    )
+    with tempfile.TemporaryDirectory() as scratch:
+        shutil.copyfile(graph_path, Path(scratch) / "graph.json")
+        res = subprocess.run(
+            [bin_path, scratch, "-json", "MATCH (n) RETURN count(n) AS c"],
+            capture_output=True, text=True, timeout=30,
+        )
     # cypherlite returns exit 0 even on some load failures (it prints the error
     # to stderr), so check both the exit code AND the output for failure markers.
     out = (res.stderr + res.stdout).strip()

package/skills/plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Decomposes a feature into a real dependency graph in .gbuild/<feature>/graph.json — nodes with typed contracts, mandatory concrete acceptance criteria, and edges that pass the cut test. Use when starting new gbuild work, before /gbuild:run.
+description: Decomposes a feature into a real dependency graph in .gbuild/<feature>/db/graph.json — nodes with typed contracts, mandatory concrete acceptance criteria, and edges that pass the cut test. Use when starting new gbuild work, before /gbuild:run.
 ---
 
 Plan the work described in `$ARGUMENTS` as a graph.
@@ -44,7 +44,7 @@ Report the branch. Everything below happens on it.
 
 ### 2. Analyse the codebase
 
-Read the project manifest(s), directory structure, `README.md`, and any existing `.gbuild/*/graph.json`
+Read the project manifest(s), directory structure, `README.md`, and any existing `.gbuild/*/db/graph.json`
 for related in-flight work. Resolve file paths or URLs in `$ARGUMENTS`; if a reference fails to load,
 say so and ask.
 
@@ -147,10 +147,12 @@ annotate around a failing item.
 
 ### 8. Write and validate
 
-Write `.gbuild/<slug>/graph.json` (a CypherLite GraphData file). **Run the format validator first:**
+Write `.gbuild/<slug>/db/graph.json` (a CypherLite GraphData file). It lives alone in the `db/` folder so
+CypherLite can open that folder as a JSON-store database; checkpoints stay in the sibling
+`.gbuild/<slug>/nodes/` directory. **Run the format validator first:**
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<slug>/graph.json
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<slug>/db/graph.json
 ```
 
 If it prints `invalid: ...`, fix the file and re-run — never hand off or commit a file that fails
@@ -161,14 +163,15 @@ initial write, reopen, any hand-edit, any fix-up — before doing anything else
 Then confirm run-readiness:
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/graph.json --status
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/db/graph.json --status
 ```
 
 The graph is now queryable with Cypher **if the `cypherlite` binary is on PATH** (`command -v
-cypherlite`) — in that case you can mention it to the user:
+cypherlite`) — in that case you can mention it to the user. Point CypherLite at the `db/` folder
+(not the `.json` file), and keep it read-only:
 
 ```
-cypherlite .gbuild/<slug>/graph.json "MATCH (n:GbuildNode) RETURN n.slug, n.type"
+cypherlite .gbuild/<slug>/db "MATCH (n:GbuildNode) RETURN n.slug, n.type"
 ```
 
 If the binary is absent, skip this without comment. CypherLite is an optional consumer, never a

package/skills/pr/SKILL.md

@@ -12,7 +12,7 @@ This skill MUST run in the **main conversation context**. It MUST NOT be invoked
 
 `$ARGUMENTS` is free-form text: an optional feature slug and an optional `--max-rounds N` flag.
 
-- **slug**: the first token that isn't a flag. If absent, infer it — the current branch commonly ends in the slug (`plan` checks out `<prefix>/<slug>`), otherwise fall back to the most recently modified `.gbuild/*/graph.json`. If neither resolves, leave `<slug>` unresolved (the auto-fix step degrades gracefully — see Step 4).
+- **slug**: the first token that isn't a flag. If absent, infer it — the current branch commonly ends in the slug (`plan` checks out `<prefix>/<slug>`), otherwise fall back to the most recently modified `.gbuild/*/db/graph.json`. If neither resolves, leave `<slug>` unresolved (the auto-fix step degrades gracefully — see Step 4).
 - **max_rounds**: the value of `--max-rounds N` (also accept `--max-rounds=N`). Default `3` when absent.
 
 ## Step 1: Preconditions
@@ -25,7 +25,7 @@ Verify the environment before touching the remote. Stop with a clear, actionable
 4. **Not on base.** Get the current branch (`git branch --show-current`). If it equals `<base>`, stop — there is nothing to open a PR for.
 5. **Clean tree.** Check for uncommitted changes (`git status --porcelain`). `/gbuild:run` commits each node's work as it goes, so the tree should be clean. If there are uncommitted changes, warn the user and ask whether to proceed (they may want to commit first).
 6. **Commits ahead of base.** Confirm the branch has commits the base lacks (`git log <base>..HEAD --oneline`). If empty, stop — nothing to push.
-7. **Graph finished.** When `<slug>` resolved, run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/graph.json --status`. If the frontier is non-empty or nodes are still `in_progress`, warn that the graph isn't finished and ask whether to open the PR anyway. If any node is `failed`, name it — a PR built on an escalated node is usually premature.
+7. **Graph finished.** When `<slug>` resolved, run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/db/graph.json --status`. If the frontier is non-empty or nodes are still `in_progress`, warn that the graph isn't finished and ask whether to open the PR anyway. If any node is `failed`, name it — a PR built on an escalated node is usually premature.
 
 ## Step 2: Determine the remote & push
 
@@ -45,7 +45,7 @@ Gather context from:
 
 - Commit subjects: `git log <base>..HEAD --oneline`.
 - File overview: `git diff <base>...HEAD --stat`.
-- When present: the `Feature` node's `destination` property and the `Acceptance` nodes (linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`) from `.gbuild/<slug>/graph.json` (a CypherLite GraphData file), and the per-node `output` values in `.gbuild/<slug>/nodes/*.json` (keyed by GbuildNode `slug`).
+- When present: the `Feature` node's `destination` property and the `Acceptance` nodes (linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`) from `.gbuild/<slug>/db/graph.json` (a CypherLite GraphData file), and the per-node `output` values in `.gbuild/<slug>/nodes/*.json` (keyed by GbuildNode `slug`).
 
 Derive a concise, conventional-commit-style title from the feature/branch and the changes (e.g. `feat(auth): add OAuth login`).
 

package/skills/review/SKILL.md

@@ -12,10 +12,10 @@ missed abstractions that only exist *between* nodes, which no per-node review ca
 
 `$ARGUMENTS` is optional. If present, treat it as the feature slug. If absent, infer it — the current
 branch commonly ends in the slug (`plan` checks out `<prefix>/<slug>`), otherwise fall back to the most
-recently modified `.gbuild/*/graph.json`. Do NOT write any file — this skill outputs to chat exclusively.
+recently modified `.gbuild/*/db/graph.json`. Do NOT write any file — this skill outputs to chat exclusively.
 
-Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<slug>/graph.json` then
-`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/graph.json --status` first. If the frontier is
+Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<slug>/db/graph.json` then
+`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<slug>/db/graph.json --status` first. If the frontier is
 non-empty or nodes are still `in_progress`, say the graph isn't finished and ask whether to audit anyway
 — auditing a half-built branch produces findings that the remaining nodes were going to address.
 
@@ -24,7 +24,7 @@ non-empty or nodes are still `in_progress`, say the graph isn't finished and ask
 Launch the `gbuild-auditor` subagent (agents/gbuild-auditor.md — this plugin's own copy, gbuild does not
 depend on hone-ai being installed). Pass it:
 
-- The resolved slug and its `.gbuild/<slug>/graph.json` path.
+- The resolved slug and its `.gbuild/<slug>/db/graph.json` path.
 - Tell it to audit the current branch.
 
 The sub-agent runs the full audit in its own fresh context and returns the audit as its final message.

package/skills/run/SKILL.md

@@ -2,26 +2,27 @@
 description: Executes a gbuild graph — dispatches every ready-and-independent node in the current wave concurrently, reviews each node's output with gbuild-reviewer before checkpointing it complete, and resumes only the remaining frontier on re-invocation. Use after /gbuild:plan has written graph.json.
 ---
 
-Run `.gbuild/$ARGUMENTS/graph.json` (the feature slug is `$ARGUMENTS`).
+Run `.gbuild/$ARGUMENTS/db/graph.json` (the feature slug is `$ARGUMENTS`).
 
 **CRITICAL: this skill must run in the main context, not inside a forked agent.** It dispatches its own
 subagents per node; a subagent cannot itself fan out further subagents reliably.
 
 ## Step 0: Load and query
 
-Load `.gbuild/<feature>/graph.json` (a CypherLite GraphData file — nodes keyed by integer `id`, with a
+Load `.gbuild/<feature>/db/graph.json` (a CypherLite GraphData file — nodes keyed by integer `id`, with a
 `slug` property; dependencies are `DEPENDS_ON` relationships, feature-level acceptance is `Acceptance`
-nodes linked by `HAS_ACCEPTANCE`/`SATISFIES`). **Confirm it's well-formed first:**
+nodes linked by `HAS_ACCEPTANCE`/`SATISFIES`; checkpoints live in the sibling `.gbuild/<feature>/nodes/`).
+**Confirm it's well-formed first:**
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<feature>/graph.json
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_format.py .gbuild/<feature>/db/graph.json
 ```
 
 If it prints `invalid: ...`, stop and report — do not attempt to run a graph `plan` didn't finish
 correctly. Then take the frontier:
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<feature>/graph.json --status
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<feature>/db/graph.json --status
 ```
 
 Take the `frontier` list (node **slugs**) from the status report. This is the set of nodes ready

package/skills/status/SKILL.md

@@ -15,15 +15,16 @@ Report status for `$ARGUMENTS`.
 
 ### 1. Load
 
-`.gbuild/<feature>/graph.json` (a CypherLite GraphData file — GbuildNodes have a `slug` property and are
-linked by `DEPENDS_ON` relationships; feature-level acceptance is `Acceptance` nodes linked by
-`HAS_ACCEPTANCE`/`SATISFIES`) and every `.gbuild/<feature>/nodes/*.json` checkpoint (keyed by slug). This
-is a small, bounded read — status doesn't scale with graph size the way loading full node prose would.
+`.gbuild/<feature>/db/graph.json` (a CypherLite GraphData file — GbuildNodes have a `slug` property and
+are linked by `DEPENDS_ON` relationships; feature-level acceptance is `Acceptance` nodes linked by
+`HAS_ACCEPTANCE`/`SATISFIES`) and every `.gbuild/<feature>/nodes/*.json` checkpoint (keyed by slug; the
+`nodes/` dir is a sibling of the `db/` graph folder). This is a small, bounded read — status doesn't
+scale with graph size the way loading full node prose would.
 
 ### 2. Compute
 
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<feature>/graph.json --status
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<feature>/db/graph.json --status
 ```
 
 Gives `frontier` / `blocked` / `in_flight` / `completed` / `cancelled` / `failed` / `waves` (all as slug
@@ -80,5 +81,5 @@ If all five are clear, say so in one line — don't let silence be ambiguous bet
 
 ## All-features mode
 
-For each `.gbuild/<slug>/graph.json` found, one line: slug, node counts by status, and whether the
+For each `.gbuild/<slug>/db/graph.json` found, one line: slug, node counts by status, and whether the
 frontier is empty (done or stuck) or has ready work. Point at `/gbuild:status <slug>` for detail.