opencode-gbuild 0.5.0 → 0.6.0

package/README.md

@@ -21,6 +21,8 @@ verification never grades itself.
 
 ## Install
 
+gbuild needs the `cypherlite` CLI on PATH — see [Runtime](#runtime).
+
 ### Claude Code
 
 From the marketplace:
@@ -91,13 +93,13 @@ OpenCode (same order, kebab-case names):
 /gbuild-pr add-oauth-login-with-github
 ```
 
-- **`plan`** decomposes a feature into `.gbuild/<feature>/db/graph.json` — a plain JSON graph file with
-  `Feature`, `Acceptance`, and `GbuildNode` nodes linked by `DEPENDS_ON`/`HAS_ACCEPTANCE`/`SATISFIES`
-  relationships. Every dependency edge passes the cut test (does the dependent actually read the
-  dependency's output?); every node has mandatory concrete acceptance criteria. Validated with
-  `scripts/validate_format.py` after every change.
+- **`plan`** charts a feature into a CypherLite graph store at `.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
+  mandatory concrete acceptance criteria. Written and validated entirely in Cypher.
 - **`run`** dispatches every node in the current ready wave concurrently — not one at a time — reviews
-  each node's output with a dedicated `gbuild-reviewer` subagent before checkpointing it complete, and
+  each node's output with a dedicated `gbuild-reviewer` subagent before recording it complete, and
   applies the node's declared failure policy on a review failure. Re-invoking after an interruption
   resumes only the remaining frontier.
 - **`status`** reports the graph — frontier, blocked, in-flight, completed, each node's review verdict,
@@ -119,16 +121,15 @@ incoming edge, and a controlled cycle gets a hard round cap instead of an open-e
 
 ## Node statuses
 
-A node's status lives in its own checkpoint file, `.gbuild/<feature>/nodes/<slug>.json` (keyed by the
-GbuildNode's `slug` property — the stable identity skills and checkpoints key on, since the graph file's
-integer `id` is authoring convenience). There are five,
-and each exists to answer a different question `run` has to ask on every invocation:
+A node's status is its `status` property in the store, next to its outputs and its review history
+(`Review` nodes, one per attempt). There are five, and each exists to answer a different question `run`
+has to ask on every invocation:
 
 | status        | means                                             | why it exists                                                                                                                                                              |
 | ------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pending`     | not started                                       | The default — a node with no checkpoint file *is* pending. Nothing has to be written to declare work undone, so an interrupted run leaves no cleanup behind.                 |
+| `pending`     | not started                                       | Every node is charted `pending`. Interrupted work goes back to `pending` when the next run resets it, so nothing is left half-declared.                                     |
 | `in_progress` | dispatched, no verdict yet                        | Distinguishes "running right now" from "never started", so a resumed run doesn't double-dispatch a node whose agent was killed mid-flight.                                   |
-| `completed`   | reviewed and passed                               | The only status that satisfies a dependent's edge on merit. Written only after `gbuild-reviewer` returns `VERDICT: pass` — an implementing agent cannot mark its own success. |
+| `completed`   | reviewed and passed                               | The only status that satisfies a dependent's edge on merit. The write refuses without a passing `Review` and a value for every output — an implementing agent cannot mark its own success. |
 | `cancelled`   | deliberately abandoned, dependents may proceed    | The `skip` failure policy's landing spot. Counts as satisfied, so abandoning an optional node doesn't permanently wedge everything downstream.                                |
 | `failed`      | escalated, dependents held                        | Records that the node is genuinely stuck and needs a human. Does **not** satisfy dependents — they stay blocked rather than building on a broken foundation.                  |
 
@@ -138,7 +139,7 @@ without me*, `failed` says *stop and wait*. Collapsing them into one "didn't wor
 `run` to guess which one a given failure meant.
 
 Everything else the tooling reports — `frontier`, `blocked`, `in_flight`, `waves` — is **derived** from
-these five by `scripts/graph.py`, never stored. Nothing can drift out of sync with itself, and the
+these five by `cypher/status.cypher`, never stored. Nothing can drift out of sync with itself, and the
 frontier is a query result rather than a judgement call:
 
 ```
@@ -151,12 +152,12 @@ in_flight = in_progress
 
 Subagents are forked, so they cannot talk to you directly — a subagent's final message is a tool result,
 not chat output. Anything it finds that needs a human decision therefore travels a specific path:
-the subagent reports it, `run` checkpoints it, and `run`'s report surfaces it. Nothing gets silently
+the subagent reports it, `run` records it, and `run`'s report surfaces it. Nothing gets silently
 resolved by the agent that found it, and nothing gets routed around.
 
 Three things can trigger it:
 
-- **A node exhausts its failure policy.** `escalate` checkpoints the node `failed`, stops dispatching
+- **A node exhausts its failure policy.** `escalate` sets the node `failed`, stops dispatching
   its dependents (siblings elsewhere in the graph keep going), and surfaces it as needing a decision.
   `repair` escalates the same way once its 2 attempts are spent; `retry` and `fallback` are capped at 2
   attempts too, so no policy can loop unbounded. See `reference/failure-policies.md`.
@@ -175,24 +176,29 @@ decision is wanted; neither guesses.
 
 ## Runtime
 
-`scripts/graph.py` and `scripts/validate_format.py` are Python 3, stdlib only — no `pip install`
-required. That's also why the graph file is `graph.json` rather than YAML: Python's stdlib has no YAML
-parser, and adding PyYAML would defeat the zero-extra-dependencies goal. The file is written and read by
-agents, not hand-edited, so losing comments costs little — `/gbuild:status` is the human-facing view.
+gbuild **requires the [CypherLite](https://github.com/neo4j-labs/cypherlite) CLI**, 0.7.0 or newer:
 
-The plan is a CypherLite GraphData file at `.gbuild/<feature>/db/graph.json`; because CypherLite opens a
-*directory* store, it queries via the folder: `cypherlite .gbuild/<feature>/db "MATCH (n:GbuildNode) RETURN n.slug"`. Checkpoints stay in the sibling `.gbuild/<feature>/nodes/` dir, outside `db/`.
+```bash
+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:
 
 ```bash
-python3 plugins/gbuild/scripts/validate_format.py .gbuild/<feature>/db/graph.json   # format gate (run after every change)
-python3 plugins/gbuild/scripts/graph.py .gbuild/<feature>/db/graph.json --status     # frontier/blocked/waves
-python3 -m unittest plugins/gbuild/scripts/test_graph.py
+cypherlite .gbuild/<feature>/db -json < plugins/gbuild/cypher/validate.cypher   # format gate: [] = valid
+cypherlite .gbuild/<feature>/db -json < plugins/gbuild/cypher/status.cypher     # frontier/blocked/waves
+cypherlite .gbuild/<feature>/db -json "MATCH (n:GbuildNode) RETURN n.slug, n.status"   # anything else
 ```
 
-`validate_format.py` does stdlib JSON checks always; if the `cypherlite` binary is on PATH it *also*
-opens the graph with CypherLite to confirm the real loader accepts it (catches serde issues the stdlib
-walk can't). CypherLite is an optional consumer, not a dependency — absent binary → cross-check skipped
-silently; `--no-cypherlite` forces the skip.
+Required properties and their types are engine constraints, so an invalid write never lands; the rest of
+the contract (enums, edge shapes, coverage, acyclicity, the cut test) is `validate.cypher`. CypherLite
+locks a store while a process has it open, so only the main-context skill touches it, one command at a
+time — subagents get their inputs in their prompt and report back. `reference/cypher.md` has the full
+operating rules.
+
+Tests (repo-root `npm test`) run the Cypher layer against the real binary: `cypher.test.ts` drives the
+worked example through a full run and checks every validator rule and write guard.
 
 ## Layout
 
@@ -200,17 +206,17 @@ silently; `--no-cypherlite` forces the skip.
 plugins/gbuild/
   agents/gbuild-reviewer.md   # per-node review, ported from hone-ai's reviewer, never self-review
   agents/gbuild-auditor.md    # end-of-branch maintainability audit, ported from hone-ai's auditor
-  reference/                  # graph-format.md is normative; shapes/failure-policies/cost-model/checklist inform plan
-  scripts/validate_format.py  # the authoritative format contract — checks the GraphData file is CypherLite-loadable + gbuild-correct
-  scripts/graph.py            # query layer: topo-sort into waves, compute frontier/blocked/in-flight
-  templates/graph.json        # a worked 4-node diamond example (CypherLite GraphData)
+  reference/                  # graph-format.md (normative model) + cypher.md (how to talk to the store); shapes/failure-policies/cost-model/checklist inform plan
+  cypher/                     # schema, validate, status/node/feature reads, and run's write scripts
+  templates/example.cypher    # a worked 4-node diamond, written the way plan writes a feature
   skills/{plan,run,status,review,pr}/
   index.ts                    # OpenCode plugin entry: registers the skills + /gbuild-* commands, translating paths/names
   package.json                # OpenCode plugin manifest (npm package "opencode-gbuild")
-  smoke.test.ts               # node --test smoke test for the OpenCode translation (repo-root `npm test`)
+  cypher.test.ts              # node --test contract tests for the Cypher layer (repo-root `npm test`)
+  smoke.test.ts               # node --test smoke test for the OpenCode translation
 ```
 
-State lives outside the plugin, in the project: `.gbuild/<feature>/db/graph.json` (a CypherLite GraphData
-file, written once by `plan`) and `.gbuild/<feature>/nodes/<slug>.json` (one checkpoint per node,
-written by `run`). The graph sits alone in `db/` so CypherLite can open that folder as a database;
-`nodes/` is a sibling, outside the folder CypherLite opens.
+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
+history. Only `db/graph.json` (CypherLite's JSON snapshot, kept current by every write) and the store's
+own `.gitignore` are committed.

package/agents/gbuild-auditor.md

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

package/agents/gbuild-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: gbuild-reviewer
-description: Reviews a gbuild node's output against its contract and acceptance criteria. Runs after every node's implement pass, before it can be checkpointed complete. Never the same agent that implemented the node.
+description: Reviews a gbuild node's output against its contract and acceptance criteria. Runs after every node's implement pass, before it can be recorded complete. Never the same agent that implemented the node.
 ---
 
 You are reviewing one gbuild node's output. You did not implement it — do not defer to the implementer's
@@ -9,19 +9,25 @@ declared bar.
 
 ## WHAT YOU'RE GIVEN
 
-- The node's full definition from `.gbuild/<slug>/db/graph.json` (a CypherLite GraphData file): its `slug`, `title`, `type`,
-  `contract.input`, `contract.output`, and `acceptance` — all read from the GbuildNode's `properties`.
-- What the node's agent actually produced.
+- The node's definition, as the caller read it from the gbuild store: its `slug`, `title`, `type`,
+  `inputs` (each with `name`, `shape`, and — when read from another node — the upstream `value`),
+  `outputs` (each with `name` and `shape`), and `acceptance`. The contract is those input and output
+  fields.
+- What the node's agent actually produced, including the `outputs` object it reported.
 - For `code`/`test`/`chore` nodes: the git diff for this node's work (`git diff HEAD`, or
   `git diff --staged`, or `git log -1 -p` if it already committed).
 
+Everything you need is in your prompt — do not open `.gbuild/` or run `cypherlite`; the caller owns the
+store and records your verdict.
+
 ## REVIEW OBJECTIVE
 
 Two checks, in order:
 
-1. **Does the output match `contract.output`'s declared shape?** If the contract said this node
-   produces a specific structure and the output doesn't match it, that's a fail regardless of the
-   acceptance criteria — a downstream node depending on this output will break.
+1. **Does every output field have a value matching its declared `shape`?** A missing field, or a value
+   that doesn't match its shape, is a fail regardless of the acceptance criteria — a downstream node
+   reading it through `FROM` will break. Values must be scalars or lists of scalars; a nested value must
+   be a JSON-encoded string.
 2. **Does the output satisfy every bullet in `acceptance`, one at a time?** Not "does it seem fine
    overall" — go bullet by bullet, pass or fail each one individually, cite why.
 
@@ -89,6 +95,7 @@ Lead with the acceptance checklist, one line per bullet:
 Then, only if there are findings beyond acceptance: `Issue` or `Suggestion`, each with a `Priority`
 (`critical | high | medium | low`).
 
-Finish with one verdict line: `VERDICT: pass` only if `contract.output` matches shape and every
-acceptance bullet passed — otherwise `VERDICT: fail`. A single failed acceptance bullet or a
-`contract.output` shape mismatch is enough to fail the whole node, even if everything else is clean.
+Finish with one verdict line: `VERDICT: pass` only if every output field has a value matching its shape
+and every acceptance bullet passed — otherwise `VERDICT: fail`. A single failed acceptance bullet or an
+output shape mismatch is enough to fail the whole node, even if everything else is clean. The caller
+records each `[fail]` line's criterion as the review's failed criteria.

package/cypher/complete.cypher

@@ -0,0 +1,23 @@
+// Record a node as completed: store its output values on its OUTPUT fields
+// and the implementing agent's own start/finish times. Guarded — it writes
+// nothing unless the node is in_progress, has a passing Review, and $outputs
+// has a value for every declared output. Check `completed` in the result;
+// `missing_outputs` / `has_passing_review` say why when it is false.
+// Output values must be scalars or lists of scalars; JSON-encode anything
+// nested into a string.
+//   cypherlite .gbuild/<slug>/db -json --param slug=<node-slug> \
+//     --param 'outputs={"value": 7}' --param started_at=<iso> --param completed_at=<iso> \
+//     < cypher/complete.cypher
+MATCH (n:GbuildNode {slug: $slug})
+WITH n,
+     [k IN COLLECT { MATCH (n)-[:OUTPUT]->(f:Field) RETURN f.name } WHERE $outputs[k] IS NULL] AS missing,
+     EXISTS { (n)-[:REVIEWED]->(:Review {verdict: 'pass'}) } AS passed
+WITH n, missing, passed, (n.status = 'in_progress' AND passed AND size(missing) = 0) AS ok
+OPTIONAL MATCH (n)-[:OUTPUT]->(f:Field) WHERE ok
+SET f.value = $outputs[f.name]
+WITH DISTINCT n, missing, passed, ok
+FOREACH (_ IN CASE WHEN ok THEN [1] ELSE [] END |
+  SET n.status = 'completed', n.started_at = $started_at, n.completed_at = $completed_at)
+RETURN n.slug AS slug, ok AS completed, n.status AS status,
+       passed AS has_passing_review, missing AS missing_outputs;
+.checkpoint

package/cypher/dispatch.cypher

@@ -0,0 +1,13 @@
+// Mark frontier nodes in_progress just before run fans them out. Only nodes
+// that are pending AND whose every DEPENDS_ON target is completed or cancelled
+// are moved; anything else is silently skipped, so compare `dispatched`
+// against what you asked for.
+//   cypherlite .gbuild/<slug>/db -json --param 'slugs=["a","b"]' < cypher/dispatch.cypher
+UNWIND $slugs AS s
+MATCH (n:GbuildNode {slug: s})
+WHERE n.status = 'pending'
+  AND NOT EXISTS { MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode) WHERE NOT d.status IN ['completed', 'cancelled'] }
+SET n.status = 'in_progress'
+RETURN n.slug AS dispatched
+ORDER BY dispatched;
+.checkpoint

package/cypher/feature.cypher

@@ -0,0 +1,21 @@
+// Feature-level context: destination, the acceptance bar with the nodes that
+// cover each criterion, and every node's recorded output values. What review
+// hands the auditor and what pr builds the description from.
+//   cypherlite .gbuild/<slug>/db -json < cypher/feature.cypher
+MATCH (f:Feature)
+RETURN f.feature AS feature,
+       f.destination AS destination,
+       f.context AS context,
+       f.out_of_scope AS out_of_scope,
+       COLLECT {
+         MATCH (f)-[:HAS_ACCEPTANCE]->(a:Acceptance)
+         WITH a ORDER BY a.id
+         RETURN {id: a.id, text: a.text,
+                 covered_by: COLLECT { MATCH (a)<-[:SATISFIES]-(n:GbuildNode) WITH n ORDER BY n.slug RETURN n.slug }}
+       } AS acceptance,
+       COLLECT {
+         MATCH (n:GbuildNode)
+         WITH n ORDER BY n.slug
+         RETURN {slug: n.slug, title: n.title, status: n.status,
+                 outputs: COLLECT { MATCH (n)-[:OUTPUT]->(o:Field) WITH o ORDER BY o.name RETURN {name: o.name, value: o.value} }}
+       } AS nodes;

package/cypher/node.cypher

@@ -0,0 +1,39 @@
+// Everything needed to dispatch or review one node, with inputs resolved
+// through FROM edges to the upstream output values. An input with no FROM is
+// external (from the codebase / environment): its `from` and `value` are null.
+//   cypherlite .gbuild/<slug>/db -json --param slug=<node-slug> < cypher/node.cypher
+MATCH (n:GbuildNode {slug: $slug})
+RETURN n.slug AS slug,
+       n.title AS title,
+       n.type AS type,
+       n.status AS status,
+       n.acceptance AS acceptance,
+       n.verify AS verify,
+       n.failure_policy AS failure_policy,
+       n.model_tier AS model_tier,
+       COLLECT {
+         MATCH (n)-[:INPUT]->(i:Field)
+         OPTIONAL MATCH (i)-[:FROM]->(o:Field)<-[:OUTPUT]-(u:GbuildNode)
+         WITH i, o, u ORDER BY i.name
+         RETURN {name: i.name, shape: i.shape, from: u.slug + '.output.' + o.name, value: o.value}
+       } AS inputs,
+       COLLECT {
+         MATCH (n)-[:OUTPUT]->(f:Field)
+         WITH f ORDER BY f.name
+         RETURN {name: f.name, shape: f.shape, value: f.value}
+       } AS outputs,
+       COLLECT {
+         MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode)
+         WITH d ORDER BY d.slug
+         RETURN d.slug
+       } AS depends_on,
+       COLLECT {
+         MATCH (n)-[:SATISFIES]->(a:Acceptance)
+         WITH a ORDER BY a.id
+         RETURN {id: a.id, text: a.text}
+       } AS satisfies,
+       COLLECT {
+         MATCH (n)-[:REVIEWED]->(r:Review)
+         WITH r ORDER BY r.attempt
+         RETURN {attempt: r.attempt, verdict: r.verdict, failed_criteria: r.failed_criteria, at: r.at}
+       } AS reviews;

package/cypher/record-review.cypher

@@ -0,0 +1,17 @@
+// Record one gbuild-reviewer verdict as a Review node. `attempt` is assigned
+// here (previous reviews + 1), so repair history is never lost.
+// failed_criteria is the list of acceptance criteria the reviewer failed
+// (pass `[]` on a pass).
+//   cypherlite .gbuild/<slug>/db -json --param slug=<node-slug> --param verdict=pass \
+//     --param 'failed_criteria=[]' < cypher/record-review.cypher
+MATCH (n:GbuildNode {slug: $slug})
+WHERE $verdict IN ['pass', 'fail']
+WITH n, COUNT { (n)-[:REVIEWED]->(:Review) } + 1 AS attempt
+CREATE (n)-[:REVIEWED]->(r:Review {
+  attempt: attempt,
+  verdict: $verdict,
+  failed_criteria: $failed_criteria,
+  at: toString(datetime())
+})
+RETURN n.slug AS slug, r.attempt AS attempt, r.verdict AS verdict;
+.checkpoint

package/cypher/schema.cypher

@@ -0,0 +1,45 @@
+// gbuild store schema. Run once, when plan creates the store:
+//   cypherlite .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;
+CREATE CONSTRAINT feature_name_exists FOR (n:Feature) REQUIRE n.feature IS NOT NULL;
+CREATE CONSTRAINT feature_destination FOR (n:Feature) REQUIRE n.destination IS :: STRING;
+CREATE CONSTRAINT feature_destination_exists FOR (n:Feature) REQUIRE n.destination IS NOT NULL;
+CREATE CONSTRAINT feature_context FOR (n:Feature) REQUIRE n.context IS :: STRING;
+CREATE CONSTRAINT feature_context_exists FOR (n:Feature) REQUIRE n.context IS NOT NULL;
+CREATE CONSTRAINT feature_out_of_scope FOR (n:Feature) REQUIRE n.out_of_scope IS :: LIST<STRING NOT NULL>;
+CREATE CONSTRAINT feature_out_of_scope_exists FOR (n:Feature) REQUIRE n.out_of_scope IS NOT NULL;
+CREATE CONSTRAINT acceptance_id FOR (n:Acceptance) REQUIRE n.id IS UNIQUE;
+CREATE CONSTRAINT acceptance_id_exists FOR (n:Acceptance) REQUIRE n.id IS NOT NULL;
+CREATE CONSTRAINT acceptance_text FOR (n:Acceptance) REQUIRE n.text IS :: STRING;
+CREATE CONSTRAINT acceptance_text_exists FOR (n:Acceptance) REQUIRE n.text IS NOT NULL;
+CREATE CONSTRAINT node_slug FOR (n:GbuildNode) REQUIRE n.slug IS UNIQUE;
+CREATE CONSTRAINT node_slug_exists FOR (n:GbuildNode) REQUIRE n.slug IS NOT NULL;
+CREATE CONSTRAINT node_title FOR (n:GbuildNode) REQUIRE n.title IS :: STRING;
+CREATE CONSTRAINT node_title_exists FOR (n:GbuildNode) REQUIRE n.title IS NOT NULL;
+CREATE CONSTRAINT node_type FOR (n:GbuildNode) REQUIRE n.type IS :: STRING;
+CREATE CONSTRAINT node_type_exists FOR (n:GbuildNode) REQUIRE n.type IS NOT NULL;
+CREATE CONSTRAINT node_acceptance FOR (n:GbuildNode) REQUIRE n.acceptance IS :: LIST<STRING NOT NULL>;
+CREATE CONSTRAINT node_acceptance_exists FOR (n:GbuildNode) REQUIRE n.acceptance IS NOT NULL;
+CREATE CONSTRAINT node_failure_policy FOR (n:GbuildNode) REQUIRE n.failure_policy IS :: STRING;
+CREATE CONSTRAINT node_failure_policy_exists FOR (n:GbuildNode) REQUIRE n.failure_policy IS NOT NULL;
+CREATE CONSTRAINT node_model_tier FOR (n:GbuildNode) REQUIRE n.model_tier IS :: STRING;
+CREATE CONSTRAINT node_model_tier_exists FOR (n:GbuildNode) REQUIRE n.model_tier IS NOT NULL;
+CREATE CONSTRAINT node_status FOR (n:GbuildNode) REQUIRE n.status IS :: STRING;
+CREATE CONSTRAINT node_status_exists FOR (n:GbuildNode) REQUIRE n.status IS NOT NULL;
+CREATE CONSTRAINT node_verify FOR (n:GbuildNode) REQUIRE n.verify IS :: STRING;
+CREATE CONSTRAINT node_started_at FOR (n:GbuildNode) REQUIRE n.started_at IS :: STRING;
+CREATE CONSTRAINT node_completed_at FOR (n:GbuildNode) REQUIRE n.completed_at IS :: STRING;
+CREATE CONSTRAINT field_name FOR (n:Field) REQUIRE n.name IS :: STRING;
+CREATE CONSTRAINT field_name_exists FOR (n:Field) REQUIRE n.name IS NOT NULL;
+CREATE CONSTRAINT field_shape FOR (n:Field) REQUIRE n.shape IS :: STRING;
+CREATE CONSTRAINT field_shape_exists FOR (n:Field) REQUIRE n.shape IS NOT NULL;
+CREATE CONSTRAINT review_attempt FOR (n:Review) REQUIRE n.attempt IS :: INTEGER;
+CREATE CONSTRAINT review_attempt_exists FOR (n:Review) REQUIRE n.attempt IS NOT NULL;
+CREATE CONSTRAINT review_verdict FOR (n:Review) REQUIRE n.verdict IS :: STRING;
+CREATE CONSTRAINT review_verdict_exists FOR (n:Review) REQUIRE n.verdict IS NOT NULL;
+CREATE CONSTRAINT review_at FOR (n:Review) REQUIRE n.at IS :: STRING;
+CREATE CONSTRAINT review_at_exists FOR (n:Review) REQUIRE n.at IS NOT NULL;
+CREATE CONSTRAINT review_failed_criteria FOR (n:Review) REQUIRE n.failed_criteria IS :: LIST<STRING NOT NULL>;
+.checkpoint

package/cypher/set-status.cypher

@@ -0,0 +1,11 @@
+// Move a node to a non-completed status: `cancelled` (skip policy), `failed`
+// (escalate, or an exhausted retry/repair), or `pending` (reset a node an
+// interrupted run left in_progress). `completed` is rejected here — only
+// complete.cypher may set it, so it can enforce the review and outputs.
+//   cypherlite .gbuild/<slug>/db -json --param slug=<node-slug> --param status=cancelled \
+//     < cypher/set-status.cypher
+MATCH (n:GbuildNode {slug: $slug})
+WHERE $status IN ['pending', 'in_progress', 'failed', 'cancelled']
+SET n.status = $status
+RETURN n.slug AS slug, n.status AS status;
+.checkpoint

package/cypher/status.cypher

@@ -0,0 +1,33 @@
+// One row per GbuildNode, in wave order. `state` is derived, never stored:
+//   frontier  = pending, every DEPENDS_ON target completed or cancelled
+//   blocked   = pending, some DEPENDS_ON target not completed or cancelled
+//   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 -json < cypher/status.cypher
+MATCH (n:GbuildNode)
+OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
+WITH n, coalesce(max(length(p)), 0) AS wave
+OPTIONAL MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode)
+WITH n, wave, d ORDER BY d.slug
+WITH n, wave, [x IN collect(d) WHERE NOT x.status IN ['completed', 'cancelled'] | x.slug] AS waiting_on
+OPTIONAL MATCH (n)-[:REVIEWED]->(r:Review)
+WITH n, wave, waiting_on, r ORDER BY r.attempt DESC
+WITH n, wave, waiting_on, collect(r) AS reviews
+RETURN n.slug AS slug,
+       n.title AS title,
+       n.type AS type,
+       n.status AS status,
+       CASE
+         WHEN n.status = 'pending' AND size(waiting_on) = 0 THEN 'frontier'
+         WHEN n.status = 'pending' THEN 'blocked'
+         ELSE n.status
+       END AS state,
+       wave,
+       waiting_on,
+       size(reviews) AS review_attempts,
+       reviews[0].verdict AS last_verdict,
+       reviews[0].failed_criteria AS last_failed_criteria,
+       n.started_at AS started_at,
+       n.completed_at AS completed_at
+ORDER BY wave, slug;

package/cypher/validate.cypher

@@ -0,0 +1,105 @@
+// gbuild format gate. Zero rows = valid; every row is one violation.
+//   cypherlite .gbuild/<slug>/db -json < 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,
+// edge shapes, coverage, acyclicity, and the data-flow (FROM) cut test.
+CALL {
+  MATCH (f:Feature) WITH count(f) AS c WHERE c <> 1
+  RETURN 'feature-count' AS check, 'expected exactly 1 Feature node, found ' + toString(c) AS detail
+UNION ALL
+  MATCH (n) WHERE NOT (n:Feature OR n:Acceptance OR n:GbuildNode OR n:Field OR n:Review)
+  RETURN 'unknown-node' AS check, 'node with labels [' + reduce(s = '', l IN labels(n) | s + ' ' + l) + ' ] is not part of the gbuild model' AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT n.slug =~ '^[a-z0-9]+(-[a-z0-9]+)*$'
+  RETURN 'bad-slug' AS check, n.slug + ': slug must be kebab-case' AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT n.type IN ['research', 'decision', 'code', 'test', 'verify', 'chore']
+  RETURN 'bad-type' AS check, n.slug + ': invalid type ' + n.type AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT n.failure_policy IN ['retry', 'fallback', 'skip', 'repair', 'escalate', 'stop']
+  RETURN 'bad-failure-policy' AS check, n.slug + ': invalid failure_policy ' + n.failure_policy AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT n.model_tier IN ['cheap', 'strong']
+  RETURN 'bad-model-tier' AS check, n.slug + ': invalid model_tier ' + n.model_tier AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT n.status IN ['pending', 'in_progress', 'completed', 'failed', 'cancelled']
+  RETURN 'bad-status' AS check, n.slug + ': invalid status ' + n.status AS detail
+UNION ALL
+  WITH {research: 'Research', decision: 'Decision', code: 'Code', test: 'Test', verify: 'Verify', chore: 'Chore'} AS label
+  MATCH (n:GbuildNode)
+  WITH n, label[n.type] AS want,
+       [l IN labels(n) WHERE l IN ['Research', 'Decision', 'Code', 'Test', 'Verify', 'Chore']] AS have
+  WHERE want IS NOT NULL AND have <> [want]
+  RETURN 'type-label' AS check, n.slug + ': type ' + n.type + ' needs exactly the type label ' + want AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE size(n.acceptance) = 0 OR any(c IN n.acceptance WHERE trim(c) = '')
+  RETURN 'bad-acceptance' AS check, n.slug + ': acceptance must be a non-empty list of non-blank criteria' AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE n.verify IS NOT NULL AND NOT EXISTS { MATCH (v:GbuildNode) WHERE v.slug = n.verify }
+  RETURN 'verify-target' AS check, n.slug + ': verify names unknown node ' + n.verify AS detail
+UNION ALL
+  MATCH (a:Acceptance) WHERE NOT a.id =~ '^a-[0-9]+$' OR trim(a.text) = ''
+  RETURN 'bad-acceptance-node' AS check, a.id + ': id must look like a-1 and text must be non-blank' AS detail
+UNION ALL
+  MATCH (a:Acceptance) WHERE NOT EXISTS { (:Feature)-[:HAS_ACCEPTANCE]->(a) }
+  RETURN 'acceptance-unlinked' AS check, a.id + ': no HAS_ACCEPTANCE from the Feature' AS detail
+UNION ALL
+  MATCH (a:Acceptance) WHERE NOT EXISTS { (:GbuildNode)-[:SATISFIES]->(a) }
+  RETURN 'acceptance-uncovered' AS check, a.id + ': no node SATISFIES it' AS detail
+UNION ALL
+  MATCH (x)-[r]->(y)
+  WHERE NOT ((type(r) = 'HAS_ACCEPTANCE' AND x:Feature AND y:Acceptance)
+          OR (type(r) = 'SATISFIES' AND x:GbuildNode AND y:Acceptance)
+          OR (type(r) = 'DEPENDS_ON' AND x:GbuildNode AND y:GbuildNode)
+          OR (type(r) IN ['INPUT', 'OUTPUT'] AND x:GbuildNode AND y:Field)
+          OR (type(r) = 'FROM' AND x:Field AND y:Field)
+          OR (type(r) = 'REVIEWED' AND x:GbuildNode AND y:Review))
+  RETURN 'bad-edge' AS check,
+         type(r) + ' from ' + coalesce(x.slug, x.id, x.name, '?') + ' to ' + coalesce(y.slug, y.id, y.name, '?') + ' is not an allowed edge' AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE EXISTS { (n)-[:DEPENDS_ON*]->(n) }
+  RETURN 'cycle' AS check, n.slug + ': DEPENDS_ON cycle' AS detail
+UNION ALL
+  MATCH (n:GbuildNode {type: 'chore'}) WHERE NOT EXISTS { ()-[:DEPENDS_ON]->(n) }
+  RETURN 'orphan-chore' AS check, n.slug + ': chore is not depended on by any node' AS detail
+UNION ALL
+  MATCH (n:GbuildNode) WHERE NOT EXISTS { (n)-[:OUTPUT]->(:Field) }
+  RETURN 'no-output' AS check, n.slug + ': declares no OUTPUT field' AS detail
+UNION ALL
+  MATCH (f:Field) WITH f, COUNT { ()-[:INPUT|OUTPUT]->(f) } AS owners WHERE owners <> 1
+  RETURN 'field-owner' AS check, f.name + ': field has ' + toString(owners) + ' owning nodes, want 1' AS detail
+UNION ALL
+  MATCH (n:GbuildNode)-[r:INPUT|OUTPUT]->(f:Field)
+  WITH n, type(r) AS dir, f.name AS name, count(*) AS c WHERE c > 1
+  RETURN 'duplicate-field' AS check, n.slug + ': ' + dir + ' field ' + name + ' declared ' + toString(c) + ' times' AS detail
+UNION ALL
+  MATCH (i:Field)-[:FROM]->(o:Field)
+  WHERE NOT EXISTS { (:GbuildNode)-[:INPUT]->(i) } OR NOT EXISTS { (:GbuildNode)-[:OUTPUT]->(o) }
+  RETURN 'bad-from' AS check, i.name + ' -> ' + o.name + ': FROM must run from an INPUT field to an OUTPUT field' AS detail
+UNION ALL
+  MATCH (i:Field) WITH i, COUNT { (i)-[:FROM]->() } AS c WHERE c > 1
+  RETURN 'multi-from' AS check, i.name + ': input field has ' + toString(c) + ' FROM edges, want at most 1' AS detail
+UNION ALL
+  MATCH (n:GbuildNode)-[:INPUT]->(i:Field)-[:FROM]->(:Field)<-[:OUTPUT]-(u:GbuildNode)
+  WHERE NOT EXISTS { (n)-[:DEPENDS_ON]->(u) }
+  RETURN 'from-without-dependency' AS check, n.slug + '.' + i.name + ' reads ' + u.slug + ' but does not DEPENDS_ON it' AS detail
+UNION ALL
+  MATCH (n:GbuildNode)-[:DEPENDS_ON]->(u:GbuildNode)
+  WHERE NOT EXISTS { (n)-[:INPUT]->(:Field)-[:FROM]->(:Field)<-[:OUTPUT]-(u) }
+  RETURN 'dependency-without-from' AS check, n.slug + ' DEPENDS_ON ' + u.slug + ' but reads none of its outputs (cut test)' AS detail
+UNION ALL
+  MATCH (n:GbuildNode {status: 'completed'}) WHERE NOT EXISTS { (n)-[:REVIEWED]->(:Review {verdict: 'pass'}) }
+  RETURN 'completed-without-pass' AS check, n.slug + ': completed without a passing Review' AS detail
+UNION ALL
+  MATCH (n:GbuildNode {status: 'completed'})-[:OUTPUT]->(f:Field) WHERE f.value IS NULL
+  RETURN 'completed-missing-output' AS check, n.slug + '.' + f.name + ': completed node has no value for this output' AS detail
+UNION ALL
+  MATCH (r:Review) WHERE NOT r.verdict IN ['pass', 'fail'] OR r.attempt < 1
+  RETURN 'bad-review' AS check, 'review attempt ' + toString(r.attempt) + ' has verdict ' + r.verdict AS detail
+UNION ALL
+  MATCH (r:Review) WITH r, COUNT { (:GbuildNode)-[:REVIEWED]->(r) } AS c WHERE c <> 1
+  RETURN 'review-owner' AS check, 'review attempt ' + toString(r.attempt) + ' has ' + toString(c) + ' owning nodes, want 1' AS detail
+}
+RETURN check, detail
+ORDER BY check, detail;

package/package.json

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

package/reference/checklist.md

@@ -1,31 +1,31 @@
 # Ship checklist
 
-`plan` runs this checklist against the graph it just wrote, before committing `graph.json`. Any item
-that fails means revise the graph, not add a caveat in prose.
+`plan` runs this checklist against the graph it just wrote, before committing the store. Any item that
+fails means revise the graph (with Cypher), not add a caveat in prose.
 
 1. **Risky assumptions are resolved, not deferred.** Every assumption that would invalidate nodes or
    edges if wrong has either been confirmed against the codebase/docs, or is charted as a `research`
    node that answers it. An assumption left as "probably fine" is a hole.
-2. **Every edge passes the cut test.** For each `DEPENDS_ON` relationship, the dependent node actually
-   reads something the dependency produced. No edge exists just because one node was thought of after
-   another.
-3. **Independent nodes are actually in the same wave.** Run `python3 scripts/graph.py <path> --waves`
-   and confirm nodes with no real edge between them land together, not in a chain.
-4. **Every node has non-empty, concrete acceptance criteria.** `validate_format.py` enforces non-empty;
-   `plan` itself is responsible for concrete — no `"looks correct"`, no criterion a fresh context
-   couldn't check unaided.
-5. **Every node's `contract.output` is structured, not free text.** A downstream node's `contract.input`
-   should be able to reference it directly.
+2. **Every edge passes the cut test.** For each `DEPENDS_ON`, the dependent reads one of the
+   dependency's `OUTPUT` fields through a `FROM` edge. `validate.cypher` rejects an edge with no data
+   behind it and data with no edge behind it — but an agent can still invent a field just to satisfy it,
+   so ask honestly whether the dependent *needs* that value.
+3. **Independent nodes are actually in the same wave.** Read `wave` from `status.cypher` and confirm
+   nodes with no real edge between them land together, not in a chain.
+4. **Every node has non-empty, concrete acceptance criteria.** The schema requires a list and
+   `validate.cypher` rejects blanks; `plan` itself is responsible for concrete — no `"looks correct"`, no
+   criterion a fresh context couldn't check unaided.
+5. **Every `OUTPUT` field has a precise `shape`**, not free text. Downstream `INPUT` fields read it
+   through `FROM` rather than re-describing it.
 6. **Every `Acceptance` node is `SATISFIES`-covered** by at least one GbuildNode. An uncovered
-   feature-level acceptance bullet means a node is missing. (`validate_format.py` enforces this.)
+   feature-level acceptance bullet means a node is missing. (`validate.cypher` enforces this.)
 7. **No node restates a global acceptance bullet verbatim as its own criterion.** Node-level acceptance
    is the local, observable slice; the `Acceptance` nodes keep the whole-feature bar.
 8. **Every controlled cycle has a hard round cap and a dedup rule**, stated in the node(s) that form the
    cycle — not left implicit.
-9. **`DEPENDS_ON` is acyclic.** `validate_format.py` (and `graph.py --waves`) reject a cycle; confirm
-   they don't.
+9. **`DEPENDS_ON` is acyclic.** `validate.cypher` rejects a cycle; confirm it doesn't.
 10. **Every `chore` node is depended on by at least one other node.** A chore nobody depends on isn't in
-    scope — it's either wired wrong or shouldn't exist. (`validate_format.py` enforces this.)
+    scope — it's either wired wrong or shouldn't exist. (`validate.cypher` enforces this.)
 11. **`failure_policy` fits the node type**, per `reference/failure-policies.md` — not defaulted to
     `retry` everywhere without thinking about it.
 12. **`model_tier` is `strong` only where judgement, not throughput, is the bottleneck** — see