opencode-gbuild 0.7.0 → 0.7.1

package/README.md

@@ -185,7 +185,7 @@ 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
@@ -196,9 +196,9 @@ direct JSON editing. The plugin ships the queries as `.cypher` files; skills pip
 (`.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

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/package.json

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

@@ -7,7 +7,7 @@ manual; the skills that only run plugin scripts carry the short version of these
 
 ## 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
@@ -17,38 +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 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.
+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
@@ -73,8 +79,16 @@ 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
 
@@ -83,7 +97,7 @@ it just created:
 
 ```
 mkdir -p DB
-cypherlite DB --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
+cypherlite query --database DB --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
 printf '*\n!.gitignore\n!graph.json\n' > DB/.gitignore
 ```
 

package/reference/queries.md

@@ -1,7 +1,7 @@
 # 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 DB --mode jsonl "<query>"`, one at a
+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.
 

package/skills/plan/SKILL.md

@@ -155,7 +155,7 @@ Then write the whole graph as **one** Cypher script, piped through a quoted here
 the edges), `.commit`, `.checkpoint`.
 
 ```
-cypherlite 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: '...'})
@@ -178,7 +178,7 @@ slug) fails the transaction and writes nothing — fix the script and run it aga
 ### 9. Validate
 
 ```
-cypherlite 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` …
@@ -188,7 +188,7 @@ hand off or commit a graph that fails validation, and never edit `graph.json` di
 Then confirm run-readiness:
 
 ```
-cypherlite 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
@@ -220,7 +220,7 @@ Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:
 3. Write it as one script that `MATCH`es what it connects to and `CREATE`s the rest:
 
    ```
-   cypherlite 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: '...'})

package/skills/pr/SKILL.md

@@ -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 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 --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 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 --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`).
 

package/skills/review/SKILL.md

@@ -26,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 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
@@ -38,7 +38,7 @@ address.
 Fetch the feature context:
 
 ```
-cypherlite 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

package/skills/run/SKILL.md

@@ -42,8 +42,8 @@ Default to `git`. Resolve these facts first, absolute paths, and reuse them thro
 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
@@ -55,7 +55,7 @@ cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
   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
   ```
 
@@ -87,7 +87,7 @@ behavior this plugin replaces.
 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
@@ -151,7 +151,7 @@ behavior this plugin replaces.
    `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>"]}
@@ -193,8 +193,8 @@ Keep going until a claim returns no rows.
 ## 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

package/skills/status/SKILL.md

@@ -31,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`
@@ -84,7 +84,7 @@ Don't read every node of every feature. For each store found — `<git-common-di
 plus any legacy `.gbuild/*/db` in the main tree — one store at a time:
 
 ```
-cypherlite 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