opencode-gbuild 0.7.1 → 0.9.0

package/reference/cypher.md

@@ -1,9 +1,11 @@
 # Talking to the gbuild store
 
-Every gbuild skill reads and writes the feature store (`.gbuild/<feature>/db/` inside the feature's git
-worktree, modelled in
-`reference/graph-format.md`) with the `cypherlite` CLI and nothing else. This file is the full operating
-manual; the skills that only run plugin scripts carry the short version of these rules inline.
+Every gbuild skill reads and writes the feature store (modelled in `reference/graph-format.md`) with the
+`cypherlite` CLI and nothing else. `DB` throughout is the store path:
+`<git-common-dir>/gbuild/<feature>/db` — beside the feature worktree, machine-local, never committed.
+`INBOX` is `<git-common-dir>/gbuild/<feature>/inbox`, beside it: where `run`'s agents leave their result
+files for `record.cypher` to read. This file is the full operating manual; the skills that only run
+plugin scripts carry the short version of these rules inline.
 
 ## Requirement
 
@@ -23,42 +25,45 @@ require the explicit `query` verb. The old path-first form — database as the f
 
 ## One writer, one command at a time
 
-CypherLite takes an exclusive lock on the store while a process has it open. A second process — reader
-or writer — fails with `storage locked` (exit 5). So:
-
-- **Only the skill running in the main context runs `cypherlite` against the store.** Subagents never
-  do: give them what they need in their prompt, have them report results in their final message, and
-  record those results yourself.
-- **Never run two `cypherlite` commands against the same store at once** — no parallel tool calls on it.
-  Fan-out is for agents, not for store access.
-- On `storage locked` (exit 5), another process holds the store (another gbuild command, a REPL left
+The store is a directory store. A writable open takes its exclusive write lock; a `--read-only` open
+does not, so read-only queries open the store beside a writer. Only a second writer fails, with
+`storage locked` (exit 5). So:
+
+- **Only the skill running in the main context writes to the store.** It is the only writer: schema,
+  dispatch, record, set-status and authored writes run there and nowhere else.
+- **Subagents may run read-only queries, never writes.** `run`'s implementers and reviewers read their
+  own brief (`brief.cypher`), the helper registry (`symbols.cypher`) and their result check
+  (`check-result.cypher`), always with `--read-only` — their agent files list exactly what they run.
+  They report through files in `INBOX` plus a one-line reply; the orchestrator records them.
+- **One `cypherlite` command at a time from the main context** — no parallel tool calls on the store.
+  Fan-out is for agents, not for store writes.
+- On `storage locked` (exit 5), another writer holds the store (another gbuild command, a REPL left
   open). Wait a few seconds and retry, up to 3 times; then stop and report. Never delete
   `.cypherlite.lock`.
 
 ## Invocation
 
 Always pass `--mode jsonl`: one compact JSON object per row, one row per line, and no output at all when
-there are no rows. `DB` below is the feature store: `.gbuild/<feature>/db` inside the feature worktree
-(`<git-common-dir>/gbuild/<feature>/tree/`), or in the main tree for a feature charted before the
-worktree layout. Every call is `cypherlite query [STATEMENT] --database DB …`; with no STATEMENT the
-piped stdin is the script list.
+there are no rows. Every call is `cypherlite query [STATEMENT] --database DB …`; with no STATEMENT the
+piped stdin is the script list. Pure reads add `--read-only`: no exit flush, no lock (it opens beside
+a writer, as above), and a fail-fast on a wrong path — a read-only call never creates a missing store.
+Writes (schema creation, dispatch, record, set-status, authored heredocs) go without.
 
 ```
-# a plugin script
-cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+# a plugin read script
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 
-# a plugin script with parameters
-cypherlite query --database DB --mode jsonl --param 'slug="b-consume-doubled"' < ${CLAUDE_PLUGIN_ROOT}/cypher/node.cypher
+# a plugin read script with parameters
+cypherlite query --read-only --database DB --mode jsonl --param 'slug="b-consume-doubled"' < ${CLAUDE_PLUGIN_ROOT}/cypher/node.cypher
 
 # an ad-hoc read — return only the columns you need, and keep a LIMIT on anything that can grow
-cypherlite query "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20" --database DB --mode jsonl
+cypherlite query "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20" --read-only --database DB --mode jsonl
 
 # a write you author (plan, reopen, fixes) — quoted heredoc delimiter, so the shell expands nothing
 cypherlite query --database DB <<'CYPHER'
 .begin
 MATCH (n:GbuildNode {slug: 'b-consume-doubled'}) SET n.title = 'Consume the value, double it';
 .commit
-.checkpoint
 CYPHER
 ```
 
@@ -70,11 +75,13 @@ CYPHER
 - **Parameters are JSON.** Every `--param` value is JSON, single-quoted for the shell: strings in double
   quotes (`--param 'slug="01-scan-runners"'`), lists and objects as JSON (`--param 'slugs=["a","b"]'`).
   Bare values that start with a digit — timestamps, `01-…` slugs — are rejected, so always quote.
+  `--fetch-params NAME=<file>` binds a JSON file as `$NAME` instead — how `record` and `check-result`
+  read inbox files without anyone retyping them.
 - **String literals** in Cypher you author: single quotes by default; double quotes when the text
   contains an apostrophe (`"gbuild's"`); backslash-escape (`\'`, `\"`) when it contains both.
-- **Authored writes are atomic and checkpointed.** Wrap them in `.begin` / `.commit` — if any statement
-  fails, the whole transaction is discarded — and end with `.checkpoint` so `graph.json` on disk (what
-  git commits) is always current. The plugin write scripts already do both.
+- **Authored writes are atomic.** Wrap them in `.begin` / `.commit` — if any statement fails, the whole
+  transaction is discarded. The plugin write scripts already do. Never write `.checkpoint`: a writable
+  session checkpoints on exit by itself.
 - **Values are scalars or lists of scalars.** CypherLite cannot store a map as a property value;
   JSON-encode anything nested into a string.
 - **Read the result.** The plugin write scripts are guarded and return what they actually changed.
@@ -92,21 +99,26 @@ CYPHER
 
 ## Creating a store
 
-Only `plan` does this, once per feature, with `DB` = `.gbuild/<feature>/db` inside the feature worktree
-it just created:
+Only `plan` does this, once per feature:
 
 ```
 mkdir -p DB
 cypherlite query --database DB --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
-printf '*\n!.gitignore\n!graph.json\n' > DB/.gitignore
 ```
 
 `--snapshot-format json` belongs on this first call only (it applies to an empty directory). It installs
-the schema constraints and pins the JSON codec, so `graph.json` exists from the start.
+the schema constraints and pins the JSON codec for cross-build compatibility: a parquet-enabled
+CypherLite build defaults a new store to Parquet, and a JSON-pinned store opens in every build.
+
+## Migrating an old store
+
+Stores charted by gbuild ≤ 0.7.1 live at `<tree>/.gbuild/<slug>/db` and are git-tracked. Migrate with
+`git rm -r --cached .gbuild` (commit the removal) and
+`mv <tree>/.gbuild/<slug>/db <git-common-dir>/gbuild/<slug>/db`.
 
 ## Script catalog
 
-All in `${CLAUDE_PLUGIN_ROOT}/cypher/`. Writes end with `.checkpoint`.
+All in `${CLAUDE_PLUGIN_ROOT}/cypher/`.
 
 | script               | params                    | returns                                                        | used by |
 | -------------------- | ------------------------- | -------------------------------------------------------------- | ------- |
@@ -114,12 +126,15 @@ All in `${CLAUDE_PLUGIN_ROOT}/cypher/`. Writes end with `.checkpoint`.
 | `validate.cypher`    | —                         | one row per violation (`check`, `detail`); no rows = valid      | every skill |
 | `progress.cypher`    | —                         | one row per wave: `total`, counts per state, `open` (slugs not yet completed or cancelled) | every skill |
 | `attention.cypher`   | —                         | only nodes needing a decision: `slug`, `reason` (`failed` / `in_progress` / `blocked-by-failed`), `detail` | run, status |
-| `dispatch.cypher`    | —                         | claims the whole frontier (→ `in_progress`); per claimed node: `slug`, `title`, `type`, `acceptance`, `failure_policy`, `model_tier`, `verify`, `inputs` (`name`, `shape`, `value`), `outputs` (`name`, `shape`) | run |
-| `record.cypher`      | `results` — list of `{slug, verdict, failed_criteria, outputs, started_at, completed_at}` | per recorded node: `attempt`, `verdict`, `completed`, `missing_outputs` | run |
+| `dispatch.cypher`    | —                         | claims every frontier node (→ `in_progress`); per claimed node only the routing columns `slug`, `type`, `model_tier`, `failure_policy` — agents read the rest with `brief` | run (at start, and after every record / set-status) |
+| `brief.cypher`       | `slug`                    | one node's brief: `slug`, `title`, `type`, `acceptance`, `verify`, `inputs` (`name`, `shape`, `from`, `value`), `outputs` (`name`, `shape`), `failed_criteria` (the latest review's when it failed, else `[]`), `notes` (`topic`, `text`, `by` — every transitive upstream node's notes plus setup and testing notes from any node, upstream first, then newest, at most 20) | run's implementer and reviewer (read-only) |
+| `check-result.cypher` | `slug`; `result` (`--fetch-params result=INBOX/<slug>.json`) | `slug`, `missing_outputs`, `invalid_outputs`, `unknown_outputs`, `has_times` — clean when the three lists are `[]` and `has_times` is `true` | run's implementer and reviewer (read-only) |
+| `record.cypher`      | `verdict` — `{slug, verdict, failed_criteria}`; `result` — `--fetch-params result=INBOX/<slug>.json` on a pass whose file exists, else `{}`; `review` — `--fetch-params review=INBOX/<slug>.review.json` when it exists, else `{}` (all three always bound) | one call per node: `slug`, `attempt`, `verdict`, `completed`, `missing_outputs`, `notes_added`, `symbols_added`, `unselected`; the `Review` keeps the review file's `checklist`, and a completing pass stores the result file's outputs, times, `notes` (as `Note`) and `symbols` (as `Symbol`), skipping notes and symbols already stored | run |
+| `symbols.cypher`     | —                         | `name`, `file`, `purpose`, `by` — every completed node's registered helpers, by file and name, at most 100 | run's implementer and reviewer (read-only) |
 | `set-status.cypher`  | `slugs` (list), `status` (`pending` / `in_progress` / `failed` / `cancelled`) | `slug`, `status` per changed node | run |
-| `status.cypher`      | —                         | one row per node: `state`, `wave`, `waiting_on`, review summary, timestamps | status (human report) |
-| `node.cypher`        | `slug`                    | one node in full: properties, `inputs` (with `from`), `outputs`, `depends_on`, `satisfies`, `reviews` | plan (reopen), ad hoc |
+| `status.cypher`      | —                         | one row per node: `state`, `wave`, `waiting_on`, review summary, timestamps, `last_dependency_at` (latest `completed_at` among its completed dependencies, null without any) | status (human report) |
+| `node.cypher`        | `slug`                    | one node in full: properties, `inputs` (with `from`), `outputs`, `depends_on`, `satisfies`, `reviews` (`attempt`, `verdict`, `failed_criteria`, `checklist`, `at`) | plan (reopen), ad hoc |
 | `feature.cypher`     | —                         | `destination`, `context`, `out_of_scope`, `acceptance` (with `covered_by`) | review, pr |
 
-Ready-made ad-hoc queries (lineage, critical path, repair history, …) are in
+Ready-made ad-hoc queries (lineage, critical path, repair history, notes by topic, …) are in
 `${CLAUDE_PLUGIN_ROOT}/reference/queries.md`.

package/reference/graph-format.md

@@ -2,12 +2,12 @@
 
 This file is normative. Where a skill disagrees with this doc, this doc wins.
 
-One CypherLite store per feature: `.gbuild/<feature>/db/` inside the feature's git worktree
-(`<git-common-dir>/gbuild/<feature>/tree/` — `plan` creates the worktree; a feature charted before the
-worktree layout keeps its store in the main tree). `plan` creates and charts it, `run` records
-progress in it, and every skill reads it — **all through Cypher**. No skill reads or writes `graph.json`
-directly; it is CypherLite's snapshot of the store. How to talk to the store (the single-writer rule,
-invocation, quoting, the script catalog) is in `reference/cypher.md`.
+One CypherLite store per feature: `<git-common-dir>/gbuild/<feature>/db/`, beside the feature worktree
+(`<git-common-dir>/gbuild/<feature>/tree/`, which `plan` creates) — untracked, machine-local, never
+committed. `plan` creates and charts it, `run` records progress in it, and every skill reads it, as do
+`run`'s agents (read-only) — **all through Cypher**. No skill reads or writes `graph.json` directly; it
+is CypherLite's local snapshot of the store, not a gbuild artifact. How to talk to the store (the single-writer rule, invocation, quoting,
+the script catalog) is in `reference/cypher.md`.
 
 `templates/example.cypher` is a complete worked example — a 4-node diamond — written exactly the way
 `plan` writes a new feature.
@@ -15,17 +15,25 @@ invocation, quoting, the script catalog) is in `reference/cypher.md`.
 ## Store layout
 
 ```
-.gbuild/<feature>/db/
-  graph.json          CypherLite JSON snapshot — committed; always current (every write ends with .checkpoint)
-  .gitignore          "*", "!.gitignore", "!graph.json" — committed
-  manifest.json       engine files — ignored
-  wal/
-  .cypherlite.lock
+<git-common-dir>/gbuild/<feature>/
+  db/                 the store
+    graph.json        CypherLite JSON snapshot — the engine's local snapshot; gbuild never reads or writes it
+    manifest.json     engine files
+    wal/
+    .cypherlite.lock
+  inbox/              run's hand-off files: <slug>.json (implementer result), <slug>.review.json (reviewer checklist)
+  tree/               the feature worktree
+  <slug>/             a file-touching node's worktree, during run
 ```
 
-The store is created with the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) so
-`graph.json` diffs are reviewable in a PR, and a clone holding only `graph.json` is a complete store —
-data **and** constraints.
+The inbox is not part of the store: `run` empties it when it starts, agents write their files there, and
+`record.cypher` reads them with `--fetch-params` — a node's outputs, notes, symbols and checklist reach
+the store only through that record.
+
+The store lives outside every checkout: untracked, machine-local, never committed. It is created with
+the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) for cross-build compatibility: a
+parquet-enabled CypherLite build defaults a new store to Parquet, and a JSON-pinned store opens in every
+build.
 
 ## Nodes
 
@@ -36,12 +44,14 @@ data **and** constraints.
 | `GbuildNode` | one unit of work (always with a PascalCase type label) | one per node  |
 | `Field`      | one named input or output of a GbuildNode's contract | one per field   |
 | `Review`     | one `gbuild-reviewer` verdict on a GbuildNode      | one per review attempt |
+| `Note`       | a fact an implementer left for later agents        | 0–5 per completed node |
+| `Symbol`     | a reusable helper a completed node added           | 0–10 per completed node |
 
 ### `Feature`
 
 | property       | type           | meaning                                              |
 | -------------- | -------------- | ---------------------------------------------------- |
-| `feature`      | string         | the slug — matches the `.gbuild/<feature>/` dir in the feature worktree, immutable |
+| `feature`      | string         | the slug — matches the `<feature>` segment of the store path, immutable |
 | `destination`  | string         | one line: what is true once this is done             |
 | `context`      | string         | why this exists, one or two lines                    |
 | `out_of_scope` | list of string | bullets, may be empty                                |
@@ -62,7 +72,7 @@ universal label is for `MATCH (n:GbuildNode)`; the type label enables `MATCH (n:
 
 | property         | type           | meaning                                                        |
 | ---------------- | -------------- | -------------------------------------------------------------- |
-| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on; `tree` is reserved (the feature worktree's directory name) |
+| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on; `tree`, `db` and `inbox` are reserved (they name the directories beside the node worktrees) |
 | `title`          | string         | what the user reads; refer to nodes by title in conversation    |
 | `type`           | string         | `research \| decision \| code \| test \| verify \| chore`       |
 | `acceptance`     | list of string | node-level criteria — mandatory, non-empty, concrete            |
@@ -107,8 +117,36 @@ map as a property value. JSON-encode anything nested into a string and say so in
 ### `Review` — one reviewer verdict
 
 `attempt` (integer, 1-based, assigned by `record.cypher`), `verdict` (`pass | fail`),
-`failed_criteria` (list of the acceptance criteria the reviewer failed; empty on a pass), `at` (string).
-Reviews are never updated or deleted — the repair history stays visible to `status`.
+`failed_criteria` (list of the acceptance criteria the reviewer failed; empty on a pass), `checklist`
+(list of string — the reviewer's per-check lines from `<slug>.review.json`, at most 40, each cut to 300
+chars; `[]` when it wrote none), `at` (string). The verdict comes from the reviewer's reply, never from
+the checklist file. Reviews are never updated or deleted — the repair history stays visible to `status`.
+
+### `Note` — a fact left for later agents
+
+| property  | type   | meaning                                                              |
+| --------- | ------ | -------------------------------------------------------------------- |
+| `topic`   | string | `setup \| testing \| conventions \| gotcha`                           |
+| `text`    | string | non-blank, trimmed, at most 300 chars                                 |
+| `by_node` | string | slug of the writing GbuildNode — the note's only `WROTE` source       |
+| `at`      | string | the completing `Review`'s `at`                                        |
+
+### `Symbol` — a registered helper
+
+| property  | type   | meaning                                                              |
+| --------- | ------ | -------------------------------------------------------------------- |
+| `name`    | string | non-blank identifier, as written in code                              |
+| `file`    | string | non-blank repo-relative path                                          |
+| `purpose` | string | one line, at most 160 chars                                           |
+| `by_node` | string | slug of the defining GbuildNode — the symbol's only `DEFINES` source  |
+| `at`      | string | the completing `Review`'s `at`                                        |
+
+Only `record.cypher` writes them, from the optional `notes` and `symbols` in a node's result file, and
+only when it completes the node — so they exist only for completed nodes; a fail or a downgraded pass
+stores none. A node keeps at most 5 notes (any whose exact `topic` and `text` is already stored is
+skipped) and 10 symbols (the first of each `name` and `file`). `brief.cypher` gives a node its
+transitive upstream nodes' notes plus every `setup` and `testing` note; `symbols.cypher` lists every
+symbol.
 
 ## Relationships
 
@@ -121,6 +159,8 @@ Reviews are never updated or deleted — the repair history stays visible to `st
 | `OUTPUT`         | `GbuildNode` → `Field`     | the node produces this field                      |
 | `FROM`           | `Field` → `Field`          | an input field reads an upstream node's output field |
 | `REVIEWED`       | `GbuildNode` → `Review`    | a verdict on the node                             |
+| `WROTE`          | `GbuildNode` → `Note`      | the node left this note                           |
+| `DEFINES`        | `GbuildNode` → `Symbol`    | the node added this helper                        |
 
 No other edge shapes are valid. `MATCH (n)-[:DEPENDS_ON]->(d)` is "what does n need";
 `MATCH (n)<-[:DEPENDS_ON]-(d)` is "what waits on n".
@@ -175,9 +215,9 @@ with a value for every `OUTPUT` — a pass missing outputs is recorded as a fail
 
 | layer                     | enforces                                                                 |
 | ------------------------- | ------------------------------------------------------------------------ |
-| engine constraints (`cypher/schema.cypher`) | required properties and their types; unique `slug` and `Acceptance.id` — a violating write never lands |
-| `cypher/validate.cypher`  | exactly one `Feature`; enums; type label matches `type`; non-blank acceptance; `verify` target exists; acceptance linked and covered; allowed edge shapes only; acyclic `DEPENDS_ON`; every chore depended on; every node has an output; field ownership and uniqueness; the `FROM` cut test; completed nodes have a passing review and all output values |
-| write scripts (`cypher/*.cypher`) | `dispatch` claims only frontier nodes; `record` completes a node only on a pass with every output; `set-status` never sets `completed` |
+| engine constraints (`cypher/schema.cypher`) | required properties and their types (including every `Note` and `Symbol` property, and `Review.checklist` as a list of strings); unique `slug` and `Acceptance.id` — a violating write never lands |
+| `cypher/validate.cypher`  | exactly one `Feature`; enums; kebab-case slugs other than `tree`, `db`, `inbox` (`bad-slug`); type label matches `type`; non-blank acceptance; `verify` target exists; acceptance linked and covered; allowed labels and edge shapes only (`WROTE`, `DEFINES` included); acyclic `DEPENDS_ON`; every chore depended on; every node has an output; field ownership and uniqueness; the `FROM` cut test; completed nodes have a passing review and all output values; note topic and non-blank text (`bad-note`); non-blank symbol name and file (`bad-symbol`); each note and symbol owned by exactly its `by_node` (`note-owner`, `symbol-owner`) |
+| write scripts (`cypher/*.cypher`) | `dispatch` claims only frontier nodes; `record` completes a node only on a pass with every output, and stores notes and symbols only then; `set-status` never sets `completed` |
 
 ## Querying
 

package/reference/queries.md

@@ -1,9 +1,9 @@
 # Ad-hoc queries
 
 The plugin scripts (`reference/cypher.md` § Script catalog) cover everything the skills do. These are for
-the questions in between. Run them with `cypherlite query "<query>" --database DB --mode jsonl`, one at a
-time — `DB` is the feature store (`.gbuild/<feature>/db` inside the feature worktree);
-return only the columns you need and keep a `LIMIT` on anything that can grow.
+the questions in between. Run them with `cypherlite query "<query>" --read-only --database DB --mode
+jsonl`, one at a time — `DB` is the feature store (`reference/cypher.md`); return only the columns you
+need and keep a `LIMIT` on anything that can grow.
 
 ```cypher
 -- the whole plan with progress
@@ -35,4 +35,8 @@ MATCH (a:Acceptance)<-[:SATISFIES]-(n:GbuildNode) RETURN a.id, collect(n.slug)
 
 -- nodes that needed a repair pass
 MATCH (n:GbuildNode)-[:REVIEWED]->(r:Review {verdict: 'fail'}) RETURN n.slug, count(r) AS failed_reviews
+
+-- notes by topic, newest first (topics: setup, testing, conventions, gotcha)
+MATCH (nt:Note) WHERE nt.topic IN ['setup'] RETURN nt.topic AS topic, nt.text AS text, nt.by_node AS by
+ORDER BY nt.at DESC, text LIMIT 20
 ```

package/skills/plan/SKILL.md

@@ -7,9 +7,9 @@ Plan the work described in `$ARGUMENTS` as a graph.
 ## The loop
 
 The intended workflow: plan in ordinary conversation first, then chart that plan here. After this
-skill: `/gbuild:run <slug>` once — it iterates waves until the graph completes. Then
-`/gbuild:review <slug>`; if it finds issues, reopen with `/gbuild:plan <slug> --add "<fix>"` and
-`/gbuild:run` again; if clean, `/gbuild:pr <slug>`.
+skill: `/gbuild:run <slug>` once — it starts each node as its dependencies complete, until the graph
+completes. Then `/gbuild:review <slug>`; if it finds issues, reopen with
+`/gbuild:plan <slug> --add "<fix>"` and `/gbuild:run` again; if clean, `/gbuild:pr <slug>`.
 
 Read `${CLAUDE_PLUGIN_ROOT}/reference/graph-format.md` (the normative graph model) and
 `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md` (how to talk to the store) before doing anything, and run
@@ -24,23 +24,24 @@ inform the choices below. `${CLAUDE_PLUGIN_ROOT}/reference/checklist.md` is the
 | a description, link, or file path             | **Chart** — new feature |
 | an existing feature slug with `--add "<req>"` | **Reopen**              |
 
-A bare slug with no store is a description, not a slug — chart it. A slug's store lives in its feature
-worktree at `<git-common-dir>/gbuild/<slug>/tree/.gbuild/<slug>/db` (a feature charted before the
-worktree layout keeps its store at `.gbuild/<slug>/db` in the main tree).
+A bare slug with no store is a description, not a slug — chart it. A slug's store lives beside its
+feature worktree at `<git-common-dir>/gbuild/<slug>/db`, machine-local and never committed (a gbuild ≤ 0.7.1
+store needs the move in `reference/cypher.md`).
 
 ## Chart
 
 ### 1. Slug, branch, and feature worktree
 
 Derive the feature slug from `$ARGUMENTS`: kebab-case, ≤4 words, names the outcome not the mechanism
-(`oauth-device-flow`, not `add-some-auth-stuff`). It's the `.gbuild/<slug>/` directory name and the
+(`oauth-device-flow`, not `add-some-auth-stuff`). It's the `gbuild/<slug>/` directory name and the
 `Feature` node's `feature` property — immutable once charted.
 
 gbuild never changes the branch of the user's checkout: the feature branch lives in its own **feature
 worktree**, so several features can be charted and run in parallel without racing each other's `HEAD`,
-and uncommitted work in the main tree is irrelevant — there is no dirty-tree check. Resolve two paths,
-both absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolute path), and `FT` =
-`GC/gbuild/<slug>/tree` — the feature worktree, the one place the feature branch is checked out. Then:
+and uncommitted work in the main tree is irrelevant — there is no dirty-tree check. Resolve these paths,
+all absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolute path), `WT` =
+`GC/gbuild/<slug>` — the feature's worktree root, inside `.git/` so nothing under it is ever committed —
+and `FT` = `WT/tree`, the feature worktree, the one place the feature branch is checked out. Then:
 
 - `FT` is already a registered worktree (`git worktree list --porcelain`) → reuse it, say so.
 - A branch named `<slug>` or ending `/<slug>` already exists → if it's checked out somewhere (a feature
@@ -55,14 +56,13 @@ both absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolut
   Take `<prefix>` from the repo's convention — project or user instructions first, else the dominant
   pattern in `git branch --list` — and fall back to `gbuild` when there is none.
 
-Report the branch and `FT`. Everything below happens in `FT`; `DB` below is
-`FT/.gbuild/<slug>/db`.
+Report the branch and `FT`. Everything below happens in `FT`; `DB` below is `WT/db`.
 
 ### 2. Analyse the codebase
 
 Read the project manifest(s), directory structure, `README.md`, and — for related in-flight work — the
-`Feature` of every existing store (`feature.cypher` against each `GC/gbuild/*/tree/.gbuild/*/db`, plus
-any legacy `.gbuild/*/db` in the main tree, one at a time). Resolve
+`Feature` of every existing store (`feature.cypher` with `--read-only` against each `GC/gbuild/*/db`,
+one at a time). Resolve
 file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask.
 
 ### 3. Validate and explore
@@ -146,13 +146,13 @@ design, don't annotate around a failing item.
 
 ### 8. Create the store and write the graph
 
-Create the store exactly as `reference/cypher.md` § Creating a store shows (`mkdir`, `schema.cypher` with
-`--snapshot-format json`, the `db/.gitignore`).
+Create the store exactly as `reference/cypher.md` § Creating a store shows (`mkdir -p DB`, then
+`schema.cypher` with `--snapshot-format json`).
 
 Then write the whole graph as **one** Cypher script, piped through a quoted heredoc.
 `${CLAUDE_PLUGIN_ROOT}/templates/example.cypher` is a complete worked example — follow its structure:
 `.begin`, a single statement of `CREATE` clauses (so variables like `a1` or `a_value` stay in scope for
-the edges), `.commit`, `.checkpoint`.
+the edges), `.commit`.
 
 ```
 cypherlite query --database DB <<'CYPHER'
@@ -168,7 +168,6 @@ CREATE (m)-[:DEPENDS_ON]->(n)
 CREATE (m)-[:INPUT]->(:Field {name: '...', shape: '<...>'})-[:FROM]->(n_out)
 CREATE (m)-[:SATISFIES]->(a1);
 .commit
-.checkpoint
 CYPHER
 ```
 
@@ -178,30 +177,26 @@ slug) fails the transaction and writes nothing — fix the script and run it aga
 ### 9. Validate
 
 ```
-cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
 ```
 
 No output means valid. Every row is a violation (`check`, `detail`): fix it with Cypher — a `.begin` …
-`.commit` … `.checkpoint` script of `MATCH … SET/CREATE/DELETE` — and re-run until it prints nothing. Never
-hand off or commit a graph that fails validation, and never edit `graph.json` directly.
+`.commit` script of `MATCH … SET/CREATE/DELETE` — and re-run until it prints nothing. Never
+hand off a graph that fails validation, and never edit `graph.json` directly.
 
 Then confirm run-readiness:
 
 ```
-cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 One row per wave: each row's `open` slugs are the decomposition, and the `frontier` counts are what
 `run` claims first. Nodes you expected to run together should share a wave.
 
-### 10. Commit and stop
+### 10. Report and stop
 
-Commit `.gbuild/<slug>/` on the feature branch unless the repo ignores it (`git -C FT check-ignore -q
-.gbuild/`; if true, don't stage anything under it). The store's own `.gitignore` limits that to
-`db/graph.json` and `db/.gitignore`. Stage and commit from the feature worktree:
-`git -C FT add .gbuild/<slug>` and `git -C FT commit -m "<slug>: chart graph"`.
-
-Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
+There is nothing to commit — the store is machine-local, outside every checkout. Report the branch,
+`FT`, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
 
 ## Reopen
 
@@ -230,13 +225,11 @@ Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:
    CREATE (n)-[:OUTPUT]->(:Field {name: '...', shape: '<...>'})
    CREATE (n)-[:SATISFIES]->(a);
    .commit
-   .checkpoint
    CYPHER
    ```
 
-4. **Re-run `validate.cypher`** until it prints nothing, then `progress.cypher`. Commit in `FT`
-   (`git -C FT commit -m "<slug>: reopen graph — <what was added>"` after staging `.gbuild/<slug>`,
-   same ignore rule as Chart's step 10), report the new frontier.
+4. **Re-run `validate.cypher`** until it prints nothing, then `progress.cypher`, and report the new
+   frontier.
 
 If the requirement needs no new nodes (an existing node's contract already covers it), say so and stop
 — don't manufacture graph churn.

package/skills/pr/SKILL.md

@@ -12,9 +12,9 @@ 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 — if exactly one feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the most recently modified `graph.json` under `<git-common-dir>/gbuild/*/tree/.gbuild/*/db` (or, for features charted before the worktree layout, `.gbuild/*/db/graph.json` in the main tree). 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 — if exactly one feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the most recently modified `graph.json` under `<git-common-dir>/gbuild/*/db`. If neither resolves, leave `<slug>` unresolved (the auto-fix step degrades gracefully — see Step 4).
 
-When `<slug>` resolved, every graph read below goes through `cypherlite`: run `cypherlite --version` first (missing → stop; gbuild needs it), one command at a time, always `--mode jsonl` (no output = no rows), and on `storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`. `DB` below is `FT/.gbuild/<slug>/db` (see Step 1 for `FT`).
+When `<slug>` resolved, every graph read below goes through `cypherlite`: run `cypherlite --version` first (missing → stop; gbuild needs it), one command at a time, always `--read-only --mode jsonl` (no output = no rows — this skill only reads the store), and on `storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`. `DB` below is `<git-common-dir>/gbuild/<slug>/db`, beside the feature worktree (a gbuild ≤ 0.7.1 store needs the move in `reference/cypher.md`).
 - **max_rounds**: the value of `--max-rounds N` (also accept `--max-rounds=N`). Default `3` when absent.
 
 ## Step 1: Preconditions
@@ -27,7 +27,7 @@ Verify the environment before touching the remote. Stop with a clear, actionable
 4. **Feature worktree and branch.** Resolve `FT` (the feature worktree) and `<branch>` (the feature branch checked out there) exactly as `/gbuild:run`'s step 0 describes — the registered worktree at `<git-common-dir>/gbuild/<slug>/tree`, a legacy feature whose branch is in the main tree, or attach a branch that is checked out nowhere. When `<slug>` is unresolved, use the main tree's current branch as `<branch>` and its root as `FT`. If `<branch>` equals `<base>`, stop — there is nothing to open a PR for.
 5. **Clean tree.** Check for uncommitted changes in the feature worktree (`git -C FT status --porcelain`). `/gbuild:run` commits each node's work as it goes, so it 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>..<branch> --oneline`). If empty, stop — nothing to push.
-7. **Graph finished.** When `<slug>` resolved, run `cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher`. If any row's `open` is non-empty, warn that the graph isn't finished (name the open nodes) and ask whether to open the PR anyway. If any row has `failed` > 0, get their names from `attention.cypher` and name them — a PR built on an escalated node is usually premature.
+7. **Graph finished.** When `<slug>` resolved, run `cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher`. If any row's `open` is non-empty, warn that the graph isn't finished (name the open nodes) and ask whether to open the PR anyway. If any row has `failed` > 0, get their names from `attention.cypher` and name them — a PR built on an escalated node is usually premature.
 
 ## Step 2: Determine the remote & push
 
@@ -48,7 +48,7 @@ Gather context from:
 
 - Commit subjects: `git log <base>..<branch> --oneline`.
 - File overview: `git diff <base>...<branch> --stat`.
-- When `<slug>` resolved: `cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher` — the `destination` and the acceptance bar (with the nodes covering each criterion).
+- When `<slug>` resolved: `cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher` — the `destination` and the acceptance bar (with the nodes covering each criterion).
 
 Derive a concise, conventional-commit-style title from the feature/branch and the changes (e.g. `feat(auth): add OAuth login`).
 
@@ -103,4 +103,6 @@ next: /gbuild:status <slug>
 ```
 
 The feature worktree `FT` keeps the branch checked out until removed — once the PR is merged and the
-graph is no longer needed, `git worktree remove FT` (and `git branch -d <branch>`) cleans up.
+graph is no longer needed, `git worktree remove WT/tree && rm -rf WT && git branch -d <branch>` (with
+`WT` = `<git-common-dir>/gbuild/<slug>`) cleans up: the whole `WT`, store included, dies with the
+feature.

package/skills/review/SKILL.md

@@ -12,21 +12,22 @@ 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 — if exactly one
 feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the
-most recently modified `graph.json` under `<git-common-dir>/gbuild/*/tree/.gbuild/*/db` (or, for
-features charted before the worktree layout, `.gbuild/*/db/graph.json` in the main tree). Do NOT write
+most recently modified `graph.json` under `<git-common-dir>/gbuild/*/db`. Do NOT write
 any file — this skill outputs to chat exclusively.
 
 Resolve `FT`, the feature worktree, exactly as `/gbuild:run`'s step 0 describes (reuse the registered
-worktree, attach if the feature branch is checked out nowhere). `DB` below is `FT/.gbuild/<slug>/db`.
+worktree, attach if the feature branch is checked out nowhere). `DB` below is
+`<git-common-dir>/gbuild/<slug>/db`, beside the worktree (a gbuild ≤ 0.7.1 store needs the move in
+`reference/cypher.md`).
 
 Store rules: run `cypherlite --version` first (missing → stop; gbuild needs it). One `cypherlite`
-command at a time, always `--mode jsonl` (no output = no rows); on `storage locked` wait and retry up to
-3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
+command at a time, always `--read-only --mode jsonl` (no output = no rows — this skill only reads); on
+`storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
 
 Check the graph is finished — one row per wave, cheap:
 
 ```
-cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 If any row's `open` is non-empty, say the graph isn't finished (name the open nodes) and ask whether to
@@ -38,7 +39,7 @@ address.
 Fetch the feature context:
 
 ```
-cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher
 ```
 
 Launch the `gbuild-auditor` subagent (agents/gbuild-auditor.md — this plugin's own copy, gbuild does not