opencode-gbuild 0.6.4 → 0.7.1

package/README.md

@@ -12,6 +12,10 @@ Plan in conversation first (your agent's normal plan mode), then hand that plan
 3. `/gbuild:review <slug>` — audit the accumulated branch
 4. Issues? `/gbuild:plan <slug> --add "<fix>"`, then `/gbuild:run` again. Clean? `/gbuild:pr <slug>`
 
+The feature branch lives in its own git worktree (created by `plan`) — your checkout never changes
+branches, your uncommitted work is never in the way, and several features can be in flight in parallel
+without racing each other's `HEAD`.
+
 (OpenCode: `/gbuild-plan`, `/gbuild-run`, … — same loop.)
 
 Inspired by the graph-engineering thread at
@@ -93,7 +97,8 @@ OpenCode (same order, kebab-case names):
 /gbuild-pr add-oauth-login-with-github
 ```
 
-- **`plan`** charts a feature into a CypherLite graph store at `.gbuild/<feature>/db/` — `Feature`,
+- **`plan`** creates the feature branch in its own git worktree and charts the feature into a
+  CypherLite graph store there (`.gbuild/<feature>/db/`) — `Feature`,
   `Acceptance`, and `GbuildNode` nodes, each node's contract as `INPUT`/`OUTPUT` `Field` nodes, and
   `FROM` edges carrying data from one node's output to the next node's input. Every dependency edge
   passes the cut test — and because data flow is explicit, the validator checks it; every node has
@@ -101,12 +106,14 @@ OpenCode (same order, kebab-case names):
 - **`run`** dispatches every node in the current ready wave concurrently — not one at a time — with
   each file-touching node working in its own git worktree on its own branch, forked from the feature
   branch. A dedicated `gbuild-reviewer` subagent reviews each node's output against its branch's diff;
-  only a passing node's branch is merged back into the feature branch, and its worktree is removed.
+  only a passing node's branch is merged back into the feature branch — in the feature's worktree, not
+  your checkout — and its worktree is removed.
   Unaccepted work never lands. A review failure applies the node's declared failure policy. Re-invoking
   after an interruption resumes only the remaining frontier, reusing the surviving worktrees.
 - **`status`** reports the graph — frontier, blocked, in-flight, completed, each node's review verdict,
   and evidence of what actually ran concurrently vs. serially.
-- **`review`** audits the finished branch as a whole in a `gbuild-auditor` subagent — abstraction
+- **`review`** audits the finished branch as a whole in a `gbuild-auditor` subagent, working in the
+  feature worktree (the full suite runs there) — abstraction
   quality, file size, spaghetti growth, and the cross-node duplication that per-node review can't see
   (two nodes, two contexts, same sub-problem solved twice). Blocking findings go back into the graph as
   a `plan --add` requirement. Ported from hone-ai's `review`.
@@ -178,19 +185,20 @@ decision is wanted; neither guesses.
 
 ## Runtime
 
-gbuild **requires the [CypherLite](https://github.com/neo4j-labs/cypherlite) CLI**, 0.7.0 or newer:
+gbuild **requires the [CypherLite](https://github.com/neo4j-labs/cypherlite) CLI**, 0.12.0 or newer:
 
 ```bash
 curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash
 ```
 
 Every skill reads and writes the graph with `cypherlite` and nothing else — there is no Python and no
-direct JSON editing. The plugin ships the queries as `.cypher` files; skills pipe them into the store:
+direct JSON editing. The plugin ships the queries as `.cypher` files; skills pipe them into the store
+(`.gbuild/<feature>/db` inside the feature's worktree — examples below run from there):
 
 ```bash
-cypherlite .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/validate.cypher   # format gate: no output = valid
-cypherlite .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/progress.cypher   # one row per wave: counts + open nodes
-cypherlite .gbuild/<feature>/db --mode jsonl "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug"   # anything else
+cypherlite query --database .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/validate.cypher   # format gate: no output = valid
+cypherlite query --database .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/progress.cypher   # one row per wave: counts + open nodes
+cypherlite query "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug" --database .gbuild/<feature>/db --mode jsonl   # anything else
 ```
 
 Reads are deliberately narrow so a run doesn't pay for the whole graph on every step: `run` claims a
@@ -225,8 +233,11 @@ plugins/gbuild/
 ```
 
 State lives outside the plugin, in the project: one CypherLite store per feature at
-`.gbuild/<feature>/db/`. It holds the plan, every node's status and output values, and the full review
+`.gbuild/<feature>/db/` inside the feature's own git worktree. It holds the plan, every node's status
+and output values, and the full review
 history. Only `db/graph.json` (CypherLite's JSON snapshot, kept current by every write) and the store's
-own `.gitignore` are committed. Per-node worktrees during a run live under `.git/gbuild/<feature>/` —
-never in `git status` — and each is removed the moment its node is accepted (merged) or terminally
-failed (discarded).
+own `.gitignore` are committed (on the feature branch). All of a feature's worktrees live under
+`.git/gbuild/<feature>/` — never in `git status`: `tree/` is the feature worktree itself, created by
+`plan` and kept until the feature is done, and during a run each file-touching node gets a `<node>/`
+worktree that is removed the moment its node is accepted (merged into the feature branch, in `tree/`)
+or terminally failed (discarded).

package/agents/gbuild-auditor.md

@@ -1,24 +1,26 @@
 ---
 name: gbuild-auditor
-description: Strict end-of-feature maintainability auditor for a gbuild feature branch. Audits abstraction quality, file size, spaghetti growth, and missed code-judo simplifications across the current branch. Use during the final review phase of a gbuild feature, after the graph's nodes are all complete.
+description: Strict end-of-feature maintainability auditor for a gbuild feature branch. Audits abstraction quality, file size, spaghetti growth, and missed code-judo simplifications across the feature branch's accumulated diff, working in the feature's git worktree. Use during the final review phase of a gbuild feature, after the graph's nodes are all complete.
 ---
 
 # gbuild Auditor
 
 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 the feature context it read from the gbuild store: the `destination` and the acceptance bar (each criterion with the nodes covering it). Use it 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 open `.gbuild/` or run `cypherlite` — the caller owns the store. Do NOT write any file — output your audit as your final message exclusively.
+The caller passes you the resolved feature slug, the **feature worktree** path, and the feature context it read from the gbuild store: the `destination` and the acceptance bar (each criterion with the nodes covering it). Use the context for scoping 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). The feature branch is checked out in the feature worktree: every file read, every check, and every git command runs there (`git -C <worktree> …` or with it as your working directory), never in the main tree. Do not open `.gbuild/` or run `cypherlite` — the caller owns the store. Do NOT write any file — output your audit as your final message exclusively.
 
 ## Run the branch's checks first
 
-Before you audit, run the repo's own verification on the branch: the full test suite, plus typecheck and
-lint where the repo defines them. Per-node reviews only checked each node against its own acceptance
+Before you audit, run the repo's own verification on the branch, in the feature worktree: the full test suite, plus typecheck and
+lint where the repo defines them. A worktree is a fresh checkout — if the project needs installed
+dependencies to build or test (`node_modules`, `.venv`, …), install or symlink them there first.
+Per-node reviews only checked each node against its own acceptance
 criteria — nobody has yet run the whole suite against the accumulated diff. A failing check is a
 blocking finding: name the exact failures.
 
 ## Core Prompt
 
-> Deep code-quality audit of the current branch. Rethink structure to improve quality without changing behavior. Improve abstractions, modularity, succinctness, legibility. Be ambitious — if restructuring the codebase yields a clearly better implementation, go for it. Measure twice, cut once.
+> Deep code-quality audit of the feature branch. Rethink structure to improve quality without changing behavior. Improve abstractions, modularity, succinctness, legibility. Be ambitious — if restructuring the codebase yields a clearly better implementation, go for it. Measure twice, cut once.
 
 ## Standards
 

package/cypher/attention.cypher

@@ -3,7 +3,7 @@
 //   in_progress        claimed but not recorded; if no run is active, an interrupted wave left it
 //   blocked-by-failed  pending behind a failed node, so it can never unblock on its own;
 //                      `detail` = the failed nodes it waits on
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/attention.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/attention.cypher
 CALL {
   MATCH (n:GbuildNode {status: 'failed'})
   RETURN n.slug AS slug, 'failed' AS reason,

package/cypher/dispatch.cypher

@@ -5,7 +5,7 @@
 // external, and its `shape` says where to find it. No rows = nothing is
 // ready (the graph is done or stuck — ask progress.cypher / attention.cypher).
 // For a router, cancel the unselected branches with set-status.cypher first.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/dispatch.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/dispatch.cypher
 MATCH (n:GbuildNode {status: 'pending'})
 WHERE NOT EXISTS { MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode) WHERE NOT d.status IN ['completed', 'cancelled'] }
 SET n.status = 'in_progress'

package/cypher/feature.cypher

@@ -2,7 +2,7 @@
 // nodes that cover each criterion. What review hands the auditor and what pr
 // builds the description from. Per-node output values are not included — get
 // one node's with node.cypher if you actually need it.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/feature.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/feature.cypher
 MATCH (f:Feature)
 RETURN f.feature AS feature,
        f.destination AS destination,

package/cypher/node.cypher

@@ -3,7 +3,7 @@
 // external (from the codebase / environment): its `from` and `value` are null.
 // Used for reopen and ad-hoc inspection; run gets its definitions from
 // dispatch.cypher instead.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'slug="<node-slug>"' < cypher/node.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl --param 'slug="<node-slug>"' < cypher/node.cypher
 MATCH (n:GbuildNode {slug: $slug})
 RETURN n.slug AS slug,
        n.title AS title,

package/cypher/progress.cypher

@@ -2,7 +2,7 @@
 // that wave not yet completed or cancelled. A wave with `open: []` is done;
 // the graph is done when every row's `open` is empty. `wave` is the longest
 // DEPENDS_ON chain below a node (0 = no dependencies).
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/progress.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/progress.cypher
 MATCH (n:GbuildNode)
 OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
 WITH n, coalesce(max(length(p)), 0) AS wave

package/cypher/record.cypher

@@ -7,7 +7,7 @@
 // you sent. Output values must be scalars or lists of scalars — one nested
 // value rejects the whole batch (InvalidPropertyType); JSON-encode it and
 // resend.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'results=[
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl --param 'results=[
 //     {"slug": "a", "verdict": "pass", "failed_criteria": [], "outputs": {"value": 7},
 //      "started_at": "<iso>", "completed_at": "<iso>"},
 //     {"slug": "b", "verdict": "fail", "failed_criteria": ["<criterion>"]}

package/cypher/schema.cypher

@@ -1,5 +1,5 @@
 // gbuild store schema. Run once, when plan creates the store:
-//   cypherlite .gbuild/<slug>/db --snapshot-format json < cypher/schema.cypher
+//   cypherlite query --database .gbuild/<slug>/db --snapshot-format json < cypher/schema.cypher
 // Everything the engine can enforce at write time lives here; the rest of the
 // contract is checked by validate.cypher.
 CREATE CONSTRAINT feature_name FOR (n:Feature) REQUIRE n.feature IS :: STRING;

package/cypher/set-status.cypher

@@ -3,7 +3,7 @@
 // retry/repair, stop), or `pending` (reset nodes an interrupted run left
 // in_progress). `completed` is rejected — only record.cypher may set it, so it
 // can require a passing review and every output value.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'slugs=["a","b"]' --param 'status="cancelled"' \
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl --param 'slugs=["a","b"]' --param 'status="cancelled"' \
 //     < cypher/set-status.cypher
 UNWIND $slugs AS s
 MATCH (n:GbuildNode {slug: s})

package/cypher/status.cypher

@@ -4,7 +4,7 @@
 //   otherwise = the stored status (in_progress, completed, failed, cancelled)
 // `wave` is the longest DEPENDS_ON chain below the node (0 = no dependencies),
 // so nodes sharing a wave are safe to run concurrently.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/status.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/status.cypher
 MATCH (n:GbuildNode)
 OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
 WITH n, coalesce(max(length(p)), 0) AS wave

package/cypher/validate.cypher

@@ -1,5 +1,5 @@
 // gbuild format gate. Zero rows = valid; every row is one violation.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/validate.cypher
+//   cypherlite query --database .gbuild/<slug>/db --mode jsonl < cypher/validate.cypher
 // Required properties, their types and slug/acceptance-id uniqueness are
 // engine constraints (schema.cypher) — a write that breaks them never lands.
 // This query checks everything the engine can't: enums, label/type agreement,

package/index.ts

@@ -43,7 +43,7 @@ instructions above:
 - \`$ARGUMENTS\` refers to the arguments this skill was invoked with in the
   conversation.
 - run's "Workflow tool" backend is Claude-specific; always use the fallback
-  backend described in step 3.
+  backend described in step 2.
 `
 
 const frontmatter = (raw: string): { description: string; body: string } => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-gbuild",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "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/cypher.md

@@ -1,12 +1,13 @@
 # Talking to the gbuild store
 
-Every gbuild skill reads and writes the feature store (`.gbuild/<feature>/db/`, modelled in
+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.
 
 ## Requirement
 
-`cypherlite` 0.7.0 or newer must be on PATH. Check first, in every skill:
+`cypherlite` 0.12.0 or newer must be on PATH. Check first, in every skill:
 
 ```
 cypherlite --version
@@ -16,36 +17,44 @@ If the command is missing, stop and tell the user gbuild needs it:
 `curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash`. Never fall back to reading or
 editing `graph.json` by hand.
 
+The floor is the ADR-0200 CLI cutover: the store path is a flag (`-d` / `--database PATH`), the first
+positional is the Cypher statement (never the database), and piped scripts and the interactive shell
+require the explicit `query` verb. The old path-first form — database as the first argument — hard-fails.
+
 ## 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 1). So:
+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`, another process 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`.
+- On `storage locked` (exit 5), another process 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 `.gbuild/<feature>/db`.
+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.
 
 ```
 # a plugin script
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 
 # a plugin script with parameters
-cypherlite DB --mode jsonl --param 'slug="b-consume-doubled"' < ${CLAUDE_PLUGIN_ROOT}/cypher/node.cypher
+cypherlite query --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 DB --mode jsonl "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20"
+cypherlite query "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20" --database DB --mode jsonl
 
 # a write you author (plan, reopen, fixes) — quoted heredoc delimiter, so the shell expands nothing
-cypherlite DB <<'CYPHER'
+cypherlite query --database DB <<'CYPHER'
 .begin
 MATCH (n:GbuildNode {slug: 'b-consume-doubled'}) SET n.title = 'Consume the value, double it';
 .commit
@@ -70,17 +79,26 @@ CYPHER
   JSON-encode anything nested into a string.
 - **Read the result.** The plugin write scripts are guarded and return what they actually changed.
   Compare it with what you asked for; never assume a write landed.
-- **Exit code 1 is a failure** — lock, constraint violation (`ConstraintValidationFailed`), syntax. Read
-  stderr, fix, retry the whole transaction.
+- **Check the exit code.** `0` is success (an empty result included). `5` is `storage locked` or a
+  write conflict — wait and retry as above. `6` is a rejected statement — syntax, semantic, or type
+  error, including `ConstraintValidationFailed` and writes on a `--read-only` store — read stderr, fix,
+  retry the whole transaction. `2` is a usage error — fix the invocation, not the data. `1` is any other
+  runtime failure. With `--mode jsonl` a failure also prints one JSON error envelope on stdout, after
+  any rows already written: `{"error":{"code","exit_code","kind","message","retryable"}}`.
+- **Agent output is capped at 100 rows.** Under a detected agent harness with non-terminal stdout —
+  gbuild skills always are — a statement prints at most 100 rows, warns on stderr, and still exits `0`.
+  Keep a `LIMIT` on anything that can grow; when you genuinely need every row, pass `--max-rows 0` (or
+  set `CYPHERLITE_MAX_ROWS=0`).
 
 ## Creating a store
 
-Only `plan` does this, once per feature:
+Only `plan` does this, once per feature, with `DB` = `.gbuild/<feature>/db` inside the feature worktree
+it just created:
 
 ```
-mkdir -p .gbuild/<feature>/db
-cypherlite .gbuild/<feature>/db --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
-printf '*\n!.gitignore\n!graph.json\n' > .gbuild/<feature>/db/.gitignore
+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

package/reference/graph-format.md

@@ -2,7 +2,9 @@
 
 This file is normative. Where a skill disagrees with this doc, this doc wins.
 
-One CypherLite store per feature: `.gbuild/<feature>/db/`. `plan` creates and charts it, `run` records
+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`.
@@ -39,7 +41,7 @@ data **and** constraints.
 
 | property       | type           | meaning                                              |
 | -------------- | -------------- | ---------------------------------------------------- |
-| `feature`      | string         | the slug — matches the `.gbuild/<feature>/` dir, immutable |
+| `feature`      | string         | the slug — matches the `.gbuild/<feature>/` dir in the feature worktree, 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                                |
@@ -60,7 +62,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 |
+| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on; `tree` is reserved (the feature worktree's directory name) |
 | `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            |

package/reference/queries.md

@@ -1,8 +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 .gbuild/<feature>/db --mode jsonl "<query>"`, one at a
-time; 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>" --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.
 
 ```cypher
 -- the whole plan with progress

package/skills/plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Decomposes a feature into a real dependency graph in the gbuild CypherLite store (.gbuild/<feature>/db) — nodes with typed field 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 the gbuild CypherLite store — nodes with typed field contracts, mandatory concrete acceptance criteria, and edges that pass the cut test. Creates the feature branch in its own git worktree, never touching the main checkout. Use when starting new gbuild work, before /gbuild:run.
 ---
 
 Plan the work described in `$ARGUMENTS` as a graph.
@@ -24,30 +24,45 @@ 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 `.gbuild/<slug>/db/` is a description, not a slug — chart it.
+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).
 
 ## Chart
 
-### 1. Slug and branch
+### 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
 `Feature` node's `feature` property — immutable once charted.
 
-Then get onto a branch for it, so `run`'s commits land somewhere isolated:
+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:
 
-- Working tree dirty → stop and ask. Don't stash or sweep someone else's changes into your branch.
-- Already on a branch ending in `<slug>` → stay there, say so.
-- Otherwise `git checkout -b <prefix>/<slug>` from current HEAD. 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.
+- `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
+  charted before the worktree layout usually has it in the main tree), that location is `FT`; otherwise
+  attach it: `git worktree add FT <branch>`.
+- Otherwise create branch and worktree in one step, forked from the current HEAD:
 
-Report the branch. Everything below happens on it.
+  ```
+  git worktree add FT -b <prefix>/<slug> HEAD
+  ```
+
+  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`.
 
 ### 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 `.gbuild/*/db`, one at a time). Resolve
+`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
 file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask.
 
 ### 3. Validate and explore
@@ -140,7 +155,7 @@ Then write the whole graph as **one** Cypher script, piped through a quoted here
 the edges), `.commit`, `.checkpoint`.
 
 ```
-cypherlite .gbuild/<slug>/db <<'CYPHER'
+cypherlite query --database DB <<'CYPHER'
 .begin
 CREATE (f:Feature {feature: '<slug>', destination: '...', context: '...', out_of_scope: ['...']})
 CREATE (a1:Acceptance {id: 'a-1', text: '...'})
@@ -163,7 +178,7 @@ slug) fails the transaction and writes nothing — fix the script and run it aga
 ### 9. Validate
 
 ```
-cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --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` …
@@ -173,7 +188,7 @@ hand off or commit a graph that fails validation, and never edit `graph.json` di
 Then confirm run-readiness:
 
 ```
-cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --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
@@ -181,18 +196,21 @@ One row per wave: each row's `open` slugs are the decomposition, and the `fronti
 
 ### 10. Commit and stop
 
-Commit `.gbuild/<slug>/` unless the repo ignores it (`git 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`.
-Message: `<slug>: chart graph`.
+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, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
+Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
 
 ## Reopen
 
 `--add "<requirement>"`:
 
-0. Check out the feature's existing branch if you're not on it. Never chart a reopen onto a different
-   branch than the one the graph was charted on.
+0. Resolve `FT` and `DB` exactly as Chart's step 1 describes (reuse the existing feature worktree;
+   attach it if the branch is checked out nowhere). Never chart a reopen onto a different branch than
+   the one the graph was charted on, and never into the user's main checkout unless that's where the
+   feature branch already lives (a legacy feature).
 1. Read the current graph narrowly: `progress.cypher` for its shape and what's done, and `node.cypher`
    only for the nodes the requirement touches.
 2. Design the delta: a new `Acceptance` node (next `a-` id) linked from the `Feature`, and whatever new
@@ -202,7 +220,7 @@ Report the branch, the waves, and the frontier. Close with `next: /gbuild:run <s
 3. Write it as one script that `MATCH`es what it connects to and `CREATE`s the rest:
 
    ```
-   cypherlite .gbuild/<slug>/db <<'CYPHER'
+   cypherlite query --database DB <<'CYPHER'
    .begin
    MATCH (f:Feature), (up:GbuildNode {slug: '<existing-slug>'})-[:OUTPUT]->(up_out:Field {name: '<field>'})
    CREATE (f)-[:HAS_ACCEPTANCE]->(a:Acceptance {id: 'a-3', text: '...'})
@@ -216,8 +234,9 @@ Report the branch, the waves, and the frontier. Close with `next: /gbuild:run <s
    CYPHER
    ```
 
-4. **Re-run `validate.cypher`** until it prints nothing, then `progress.cypher`. Commit
-   (`<slug>: reopen graph — <what was added>`), report the new frontier.
+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.
 
 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

@@ -1,5 +1,5 @@
 ---
-description: Pushes the current gbuild feature branch to the appropriate remote, opens a pull request with a concise description that classifies the change (new feature, fix, optimization, etc.) and notes any user-facing impact, then monitors CI checks in the background and auto-triggers a graph reopen + run if any fail. Use after /gbuild:review reports nothing blocking, to publish the finished feature branch.
+description: Pushes the gbuild feature branch to the appropriate remote, opens a pull request with a concise description that classifies the change (new feature, fix, optimization, etc.) and notes any user-facing impact, then monitors CI checks in the background and auto-triggers a graph reopen + run if any fail. Works from the feature's own worktree, never touching the main checkout's branch. Use after /gbuild:review reports nothing blocking, to publish the finished feature branch.
 ---
 
 Publish a finished feature branch: push it to the right remote, open a well-formed pull request, then watch the PR's CI checks and drive a graph reopen automatically when a check goes red — looping until the checks are green or a round cap is hit.
@@ -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 — the current branch commonly ends in the slug (`plan` checks out `<prefix>/<slug>`), otherwise fall back to the store whose `.gbuild/*/db/graph.json` was most recently modified. 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/*/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).
 
-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`.
+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`).
 - **max_rounds**: the value of `--max-rounds N` (also accept `--max-rounds=N`). Default `3` when absent.
 
 ## Step 1: Preconditions
@@ -24,10 +24,10 @@ Verify the environment before touching the remote. Stop with a clear, actionable
 1. **Git repo.** This skill is git + GitHub specific. If the repo is not git, stop and explain that `/gbuild:pr` only supports git + GitHub (`gh`).
 2. **GitHub CLI.** Confirm `gh` is installed and authenticated (`gh auth status`). If not, stop and tell the user to install/authenticate `gh`.
 3. **Base branch.** Determine the upstream default branch: `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`. Call it `<base>`.
-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 `cypherlite .gbuild/<slug>/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.
+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.
 
 ## Step 2: Determine the remote & push
 
@@ -37,7 +37,8 @@ Choose the push remote from the project's actual remotes:
 2. **Exactly one remote** → use it.
 3. **Multiple remotes** → look for a push-target hint in `AGENTS.md` or `CLAUDE.md` (e.g. an explicit statement that the project pushes to a fork). If a clear hint exists, use it. Otherwise, use `AskUserQuestion` to let the user pick which remote to push to (e.g. `origin` vs a fork remote).
 
-Push the current branch and set upstream: `git push -u <remote> <branch>`.
+Push the feature branch and set upstream: `git push -u <remote> <branch>` (branch names are refs — the
+main tree's checkout is irrelevant).
 
 ## Step 3: Open the pull request
 
@@ -45,9 +46,9 @@ Build a **short, well-formed** description, then open the PR.
 
 Gather context from:
 
-- Commit subjects: `git log <base>..HEAD --oneline`.
-- File overview: `git diff <base>...HEAD --stat`.
-- When `<slug>` resolved: `cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher` — the `destination` and the acceptance bar (with the nodes covering each criterion).
+- 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).
 
 Derive a concise, conventional-commit-style title from the feature/branch and the changes (e.g. `feat(auth): add OAuth login`).
 
@@ -72,13 +73,13 @@ This description was auto generated
 
 The trailing `This description was auto generated` line is **mandatory** — it always ends the body, after every other section, and is never dropped or reworded.
 
-Create the PR: `gh pr create --base <base> --title "<title>" --body "<body>"`. Let `gh` resolve the head branch (it handles fork `owner:branch` head refs automatically). Capture the PR URL and number (`<pr>`).
+Create the PR: `gh pr create --base <base> --title "<title>" --body "<body>"` — run it with `FT` as the working directory, so `gh` resolves the head from the feature branch (it handles fork `owner:branch` head refs automatically). Capture the PR URL and number (`<pr>`).
 
 ## Step 4: Monitor checks in the background → auto-fix loop
 
 Watch the PR's CI checks and react when they fail. Run for at most `max_rounds` rounds:
 
-1. **Launch the watch in the background.** Run `gh pr checks <pr> --watch --fail-fast` via the Bash tool with `run_in_background: true`. It exits `0` when all checks pass and non-zero when a check fails; the harness re-invokes this skill when the command exits, so continue from the result.
+1. **Launch the watch in the background.** Run `gh pr checks <pr> --watch --fail-fast` (from `FT`) via the Bash tool with `run_in_background: true`. It exits `0` when all checks pass and non-zero when a check fails; the harness re-invokes this skill when the command exits, so continue from the result.
 2. **Checks green (exit 0):** report success and go to Step 5.
 3. **Checks red (non-zero exit):**
    - Collect the failure detail: `gh pr checks <pr>` for the failed-check list, and `gh run view <run-id> --log-failed` for the failing logs.
@@ -88,7 +89,7 @@ Watch the PR's CI checks and react when they fail. Run for at most `max_rounds`
      2. Run it unattended. `plan`'s Reopen asks nothing, but if executing it would prompt the user (an ambiguous decomposition), resolve it yourself from the failing logs and note the choice in the final report — `/gbuild:pr` runs without a human present.
      3. If Reopen concludes the requirement needs no new nodes, stop the loop and go to Step 5 with an `unresolved` status — the failure isn't something the graph can act on, so surface the logs to the user.
      4. Read `${CLAUDE_PLUGIN_ROOT}/skills/run/SKILL.md` and execute it inline against `<slug>` to run the newly-unblocked frontier. Suppress its trailing `next: /gbuild:status…` line — this skill owns the transition.
-   - After the run completes, push the new commits (`git push`) and **re-launch the watch** (next round).
+   - After the run completes, push the new commits (`git -C FT push`) and **re-launch the watch** (next round).
 
 4. **Round cap reached while still red:** stop, print the still-failing checks and their logs, and tell the user to inspect manually. Go to Step 5 with an `unresolved` status.
 
@@ -100,3 +101,6 @@ Report the outcome:
 PR: <url>  (checks: green | fixed after <rounds> round(s) | unresolved after <max_rounds> round(s))
 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.

package/skills/review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Performs a strict end-of-feature maintainability audit of the current gbuild branch — abstraction quality, file size, spaghetti growth, cross-node duplication, missed code-judo simplifications. Runs the audit in the gbuild-auditor sub-agent and relays its result to chat. Use after /gbuild:run finishes a graph, before /gbuild:pr.
+description: Performs a strict end-of-feature maintainability audit of a gbuild feature branch — abstraction quality, file size, spaghetti growth, cross-node duplication, missed code-judo simplifications. Runs the audit in the gbuild-auditor sub-agent, in the feature's worktree, and relays its result to chat. Use after /gbuild:run finishes a graph, before /gbuild:pr.
 ---
 
 Run the strict end-of-feature maintainability audit in a dedicated sub-agent, then relay its result.
@@ -10,10 +10,14 @@ missed abstractions that only exist *between* nodes, which no per-node review ca
 
 ## Arguments
 
-`$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 store
-whose `.gbuild/*/db/graph.json` was most recently modified. Do NOT write any file — this skill outputs to
-chat exclusively.
+`$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
+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`.
 
 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
@@ -22,7 +26,7 @@ command at a time, always `--mode jsonl` (no output = no rows); on `storage lock
 Check the graph is finished — one row per wave, cheap:
 
 ```
-cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --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
@@ -34,7 +38,7 @@ address.
 Fetch the feature context:
 
 ```
-cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher
+cypherlite query --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
@@ -43,7 +47,8 @@ depend on hone-ai being installed). Pass it:
 - The resolved slug and the `feature.cypher` result verbatim (destination and the acceptance bar with
   the nodes covering each criterion) — the auditor never opens the store itself, and reads the code from
   the branch diff.
-- Tell it to audit the current branch.
+- The feature worktree path `FT` and the feature branch name — it audits the branch's code from `FT`:
+  every read, every check, and every git command runs there, never in the main tree.
 
 The sub-agent runs the full audit in its own fresh context and returns the audit as its final message.
 That message is a tool result — it is NOT shown to the user. So once it returns:

package/skills/run/SKILL.md

@@ -2,7 +2,8 @@
 description: Executes a gbuild graph — dispatches every ready-and-independent node in the current wave concurrently, each file-touching node in its own git worktree, reviews each node's output with gbuild-reviewer before merging its branch and recording it complete, and resumes only the remaining frontier on re-invocation. Use after /gbuild:plan has charted the graph.
 ---
 
-Run the graph in `.gbuild/$ARGUMENTS/db` (the feature slug is `$ARGUMENTS`; `DB` below).
+Run the graph for the feature `$ARGUMENTS` (the slug; step 0 resolves `DB`, the store — it lives in
+the feature's own worktree, so this skill never changes the branch of the user's checkout).
 
 **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. It is also the store's
@@ -20,39 +21,51 @@ back in their final message, and this skill records it.
   Exit code 1 = failure; read stderr. Anything beyond the scripts below: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
 - Never re-read what you already hold. The claimed wave's definitions stay valid for its retries.
 
-## Step 0: Check and recover
+## Step 0: Establish VCS facts, then check and recover
+
+Default to `git`. Resolve these facts first, absolute paths, and reuse them throughout:
+
+- `GC` = `git rev-parse --git-common-dir`, resolved to an absolute path; `WT` = `GC/gbuild/$ARGUMENTS`
+  (the worktree root — inside `.git/`, so worktrees never appear in `git status` or get committed).
+- `FT` = the feature worktree and `BRANCH` = the feature branch — the one place `BRANCH` is checked
+  out, and where every merge and store commit below lands:
+  1. `WT/tree` is a registered worktree (`git worktree list --porcelain`) → `FT` = it, `BRANCH` =
+     `git -C FT branch --show-current`.
+  2. Else a worktree whose branch is `$ARGUMENTS` or ends `/$ARGUMENTS` → `FT` = that worktree's path
+     (a feature charted before the worktree layout usually has its branch in the main tree).
+  3. Else such a branch exists but is checked out nowhere → attach it: `git worktree add WT/tree
+     <branch>`, `FT` = `WT/tree`.
+  4. Else → stop: there is no feature branch for `$ARGUMENTS` — chart it with `/gbuild:plan` first.
+- `DB` = `FT/.gbuild/$ARGUMENTS/db`. `git -C FT check-ignore -q .gbuild/` tells you whether to commit
+  the store at all.
+
+Then check and recover:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
 ```
 
 - `validate` printing anything → stop and report the rows; do not run a graph `plan` didn't finish
   correctly.
 - `attention` rows with reason `in_progress` are left over from an interrupted run (this skill is the
   only writer and records every node before finishing). Check each one's worktree branch for commits
-  its agent already made (`git log $(git branch --show-current)..gbuild/<feature>/<slug>` — empty
+  its agent already made (`git log BRANCH..gbuild/<feature>/<slug>` — empty
   means it never got that far) and leave the worktree in place: the re-dispatch reuses it. Then reset
   them all in one call so they re-dispatch, and mention it in the report:
 
   ```
-  cypherlite DB --mode jsonl --param 'slugs=["<slug>", ...]' --param 'status="pending"' \
+  cypherlite query --database DB --mode jsonl --param 'slugs=["<slug>", ...]' --param 'status="pending"' \
     < ${CLAUDE_PLUGIN_ROOT}/cypher/set-status.cypher
   ```
 
-- Sweep the worktree root (step 1's `WT`) for leaks from an interruption that struck mid-cleanup: any
-  worktree whose slug is *not* among the slugs just reset does not belong to live work — remove it
+- Sweep the worktree root `WT` for leaks from an interruption that struck mid-cleanup: any worktree
+  under `WT` — **except `FT` itself (`WT/tree`)** — whose slug is *not* among the slugs just reset does
+  not belong to live work — remove it
   (`git worktree remove --force`) and delete its branch (`git branch -D`). An unmerged branch is
   unaccepted work, which must never land — that is what the isolation is for.
 
-## Step 1: Establish VCS facts
-
-Default to `git`. `git check-ignore -q .gbuild/` tells you whether to commit the store at all. Record
-two facts for the wave mechanics below: `BRANCH` = `git branch --show-current` (the feature branch —
-every accepted node merges back into it), and `WT` = `$(git rev-parse --git-common-dir)/gbuild/$ARGUMENTS`
-(the worktree root — inside `.git/`, so worktrees never appear in `git status` or get committed).
-
-## Step 2: Pick a backend
+## Step 1: Pick a backend
 
 **Workflow tool**, if this session has opted into multi-agent orchestration (ultracode, or the user
 asked for a workflow explicitly) — translate each claimed wave into a `pipeline()`/`parallel()` script:
@@ -62,25 +75,25 @@ file-touching (`code`/`test`/`chore`) node gets `isolation: 'worktree'`.
 Controlled-cycle clusters become a bounded `while` loop per `${CLAUDE_PLUGIN_ROOT}/reference/shapes.md`'s
 round cap. Route `model_tier: strong` nodes via `opts.model` where the harness supports an override. The
 script never touches the store: collect the results, land each accepted node's branch from the main
-context (step 3.4), then record (step 3.5).
+context (step 2.4), then record (step 2.5).
 
-**Fallback** (default — no opt-in required, and always what step 3 below assumes): fire one `Agent`
+**Fallback** (default — no opt-in required, and always what step 2 below assumes): fire one `Agent`
 tool call per claimed node, **all in a single message** — this is what makes the fan-out real rather
 than claimed. Do not dispatch them one at a time across separate messages; that's exactly the serial
 behavior this plugin replaces.
 
-## Step 3: One wave
+## Step 2: One wave
 
 1. **CLAIM.**
 
    ```
-   cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/dispatch.cypher
+   cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/dispatch.cypher
    ```
 
    It moves the whole frontier to `in_progress` and prints one row per claimed node with everything its
    agent needs: `slug`, `title`, `type`, `acceptance`, `failure_policy`, `model_tier`, `verify`,
    `inputs` (an input with a `value` came from an upstream node; one without is external — its `shape`
-   says where to find it), and `outputs`. **No rows** → nothing is ready: go to step 5.
+   says where to find it), and `outputs`. **No rows** → nothing is ready: go to step 4.
 
 2. **IMPLEMENT.** First, give every claimed `code`/`test`/`chore` node its own worktree — one shell
    loop over the wave's slugs, idempotent so an interrupted or re-dispatched node keeps its earlier
@@ -93,7 +106,8 @@ behavior this plugin replaces.
      || git worktree add WT/<slug> gbuild/<feature>/<slug>
    ```
 
-   (skip if the worktree already exists; else fork a fresh branch off `BRANCH`; if the branch already
+   (skip if the worktree already exists; else fork a fresh branch off `BRANCH` — just a ref here, the
+   cwd doesn't matter; if the branch already
    exists from an earlier attempt, attach to it instead — nothing is redone). Then, in one message,
    spawn one `Agent` per claimed node with its row. Tell it to:
    - actually do the work — for `code`/`test`/`chore` nodes make the change **in its worktree**
@@ -118,25 +132,26 @@ behavior this plugin replaces.
    point). Never let the implementing agent review its own work.
 
 4. **LAND.** For each `pass` verdict on a `code`/`test`/`chore` node, merge its branch into the
-   feature branch and clean up, from the main tree:
+   feature branch — in the feature worktree `FT`, never the user's checkout — and clean up:
 
    ```
-   git merge --no-ff gbuild/<feature>/<slug> \
+   git -C FT merge --no-ff gbuild/<feature>/<slug> \
      && git worktree remove --force WT/<slug> \
      && git branch -d gbuild/<feature>/<slug>
    ```
 
-   A merge conflict means two supposedly independent nodes touched the same lines: `git merge --abort`
-   and treat the node as review-failed, the conflict as its failed criterion — step 6's policy decides
+   A merge conflict means two supposedly independent nodes touched the same lines: `git -C FT merge
+   --abort`
+   and treat the node as review-failed, the conflict as its failed criterion — step 5's policy decides
    (a retry/repair re-dispatch tells the agent to rebase its branch onto `BRANCH` and resolve it).
    Worktrees and branches are deleted only here, after acceptance — a failed node's stays for its next
-   attempt (step 6).
+   attempt (step 5).
 
 5. **RECORD** the whole wave in one call — one result per node, `verdict` from the reviewer's
    `VERDICT:` line, `failed_criteria` from its `[fail]` lines:
 
    ```
-   cypherlite DB --mode jsonl --param 'results=[
+   cypherlite query --database DB --mode jsonl --param 'results=[
      {"slug": "<slug>", "verdict": "pass", "failed_criteria": [], "outputs": {...},
       "started_at": "<iso>", "completed_at": "<iso>"},
      {"slug": "<slug>", "verdict": "fail", "failed_criteria": ["<criterion>"]}
@@ -165,20 +180,21 @@ behavior this plugin replaces.
      `set-status.cypher` before the next claim.
 
 Nodes in the same wave never read each other's outputs, and every file-touching node works in its own
-worktree, so true concurrent dispatch is safe by construction — the store calls and the merges onto
-`BRANCH` are the only serialized points.
+worktree, so true concurrent dispatch is safe by construction — the store calls and the merges in `FT`
+are the only serialized points, and since `FT` belongs to this feature alone, other features (or the
+user) changing branches in their own checkouts cannot race them.
 
-## Step 4: Next wave
+## Step 3: Next wave
 
-If `.gbuild/` isn't ignored, commit the store: `git add .gbuild/<feature>/db` and
-`git commit -m "<feature>: record wave <n>"`. Then claim again (step 3). Keep going until a claim
-returns no rows.
+If `.gbuild/` isn't ignored, commit the store in the feature worktree: `git -C FT add
+.gbuild/<feature>/db` and `git -C FT commit -m "<feature>: record wave <n>"`. Then claim again (step 2).
+Keep going until a claim returns no rows.
 
-## Step 5: Report and stop
+## Step 4: Report and stop
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
 ```
 
 Every `progress` row with `open: []` → the graph is done. Otherwise `attention` names what's stuck
@@ -194,7 +210,7 @@ Report: which nodes ran this invocation, which passed review outright vs. needed
 
 ## Resuming
 
-Re-invoking `/gbuild:run <feature>` after an interruption re-runs step 0 fresh: nodes an interrupted
-wave left `in_progress` are reset (their worktrees and any commits on their branches survive — the
-re-dispatch reuses them), and the next claim picks up exactly the remaining frontier. Nothing needs to
-be told what already finished — the store is the memory.
+Re-invoking `/gbuild:run <feature>` after an interruption re-runs step 0 fresh: the feature worktree is
+resolved or re-attached, nodes an interrupted wave left `in_progress` are reset (their worktrees and any
+commits on their branches survive — the re-dispatch reuses them), and the next claim picks up exactly
+the remaining frontier. Nothing needs to be told what already finished — the store is the memory.

package/skills/status/SKILL.md

@@ -2,7 +2,11 @@
 description: Reports a gbuild feature's graph — frontier, blocked, in-flight, completed, each node's review verdict, and the cluster shapes with evidence of what actually ran concurrently. Use to check progress or diagnose a stuck run.
 ---
 
-Report status for `$ARGUMENTS`. This skill only reads the store; `DB` below is `.gbuild/<feature>/db`.
+Report status for `$ARGUMENTS`. This skill only reads the store. `DB` below is the feature's store:
+`FT/.gbuild/<feature>/db`, where `FT` is the feature worktree at `<git-common-dir>/gbuild/<feature>/tree`
+(a feature charted before the worktree layout keeps its store at `.gbuild/<feature>/db` in the main
+tree). Status never creates or attaches worktrees — if neither store exists, say the feature's worktree
+is gone and that `git worktree add <git-common-dir>/gbuild/<feature>/tree <branch>` reattaches it.
 
 ## Store rules
 
@@ -17,7 +21,7 @@ Report status for `$ARGUMENTS`. This skill only reads the store; `DB` below is `
 
 | arguments         | mode                                  |
 | ------------------ | -------------------------------------- |
-| empty              | every feature under `.gbuild/`         |
+| empty              | every feature store                    |
 | a feature slug     | that feature only                      |
 
 ## Single feature
@@ -27,8 +31,8 @@ This is the human-facing report, so it's the one place that reads every node.
 ### 1. Load
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/status.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/status.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
 ```
 
 One call after the other. `status.cypher` gives one row per node with its derived `state`
@@ -76,10 +80,11 @@ don't let silence be ambiguous between "checked, clear" and "not checked."
 
 ## All-features mode
 
-Don't read every node of every feature. For each `.gbuild/<slug>/db` found, one store at a time:
+Don't read every node of every feature. For each store found — `<git-common-dir>/gbuild/*/tree/.gbuild/*/db`,
+plus any legacy `.gbuild/*/db` in the main tree — one store at a time:
 
 ```
-cypherlite .gbuild/<slug>/db --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 Print one line per feature: slug, node counts by state summed over its waves, and whether it's done

package/templates/example.cypher

@@ -1,7 +1,7 @@
 // A worked 4-node diamond: A produces a value, B and C each consume it
 // independently, D joins both. This is exactly the script plan writes for a
 // new feature — one atomic statement, piped into the store:
-//   cypherlite .gbuild/<slug>/db < plan.cypher
+//   cypherlite query --database .gbuild/<slug>/db < plan.cypher
 // Variables (f, a1, a, a_value, ...) are only scoped to this one statement, so
 // the whole graph is created in a single CREATE chain.
 .begin