opencode-gbuild 0.5.0 → 0.6.1

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

package/reference/cypher.md

@@ -0,0 +1,107 @@
+# Talking to the gbuild store
+
+Every gbuild skill reads and writes the feature store (`.gbuild/<feature>/db/`, 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 --version
+```
+
+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.
+
+## 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:
+
+- **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`.
+
+## 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`.
+
+```
+# a plugin script
+cypherlite 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
+
+# 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"
+
+# a write you author (plan, reopen, fixes) — quoted heredoc delimiter, so the shell expands nothing
+cypherlite DB <<'CYPHER'
+.begin
+MATCH (n:GbuildNode {slug: 'b-consume-doubled'}) SET n.title = 'Consume the value, double it';
+.commit
+.checkpoint
+CYPHER
+```
+
+## Rules
+
+- **Read narrowly.** Prefer the smallest script that answers the question — `progress` for "how far
+  along / is it done", `attention` for "what needs a decision", `dispatch` for "what runs next". The full
+  per-node `status` is for the human-facing `/gbuild:status` report, not for loops.
+- **Parameters are JSON.** Every `--param` value is JSON, single-quoted for the shell: strings in double
+  quotes (`--param 'slug="01-scan-runners"'`), lists and objects as JSON (`--param 'slugs=["a","b"]'`).
+  Bare values that start with a digit — timestamps, `01-…` slugs — are rejected, so always quote.
+- **String literals** in Cypher you author: single quotes by default; double quotes when the text
+  contains an apostrophe (`"gbuild's"`); backslash-escape (`\'`, `\"`) when it contains both.
+- **Authored writes are atomic and checkpointed.** Wrap them in `.begin` / `.commit` — if any statement
+  fails, the whole transaction is discarded — and end with `.checkpoint` so `graph.json` on disk (what
+  git commits) is always current. The plugin write scripts already do both.
+- **Values are scalars or lists of scalars.** CypherLite cannot store a map as a property value;
+  JSON-encode anything nested into a string.
+- **Read the result.** The plugin write scripts are guarded and return what they actually changed.
+  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.
+
+## Creating a store
+
+Only `plan` does this, once per feature:
+
+```
+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
+```
+
+`--snapshot-format json` belongs on this first call only (it applies to an empty directory). It installs
+the schema constraints and pins the JSON codec, so `graph.json` exists from the start.
+
+## Script catalog
+
+All in `${CLAUDE_PLUGIN_ROOT}/cypher/`. Writes end with `.checkpoint`.
+
+| script               | params                    | returns                                                        | used by |
+| -------------------- | ------------------------- | -------------------------------------------------------------- | ------- |
+| `schema.cypher`      | —                         | nothing (installs constraints)                                  | plan    |
+| `validate.cypher`    | —                         | one row per violation (`check`, `detail`); no rows = valid      | every skill |
+| `progress.cypher`    | —                         | one row per wave: `total`, counts per state, `open` (slugs not yet completed or cancelled) | every skill |
+| `attention.cypher`   | —                         | only nodes needing a decision: `slug`, `reason` (`failed` / `in_progress` / `blocked-by-failed`), `detail` | run, status |
+| `dispatch.cypher`    | —                         | claims the whole frontier (→ `in_progress`); per claimed node: `slug`, `title`, `type`, `acceptance`, `failure_policy`, `model_tier`, `verify`, `inputs` (`name`, `shape`, `value`), `outputs` (`name`, `shape`) | run |
+| `record.cypher`      | `results` — list of `{slug, verdict, failed_criteria, outputs, started_at, completed_at}` | per recorded node: `attempt`, `verdict`, `completed`, `missing_outputs` | run |
+| `set-status.cypher`  | `slugs` (list), `status` (`pending` / `in_progress` / `failed` / `cancelled`) | `slug`, `status` per changed node | run |
+| `status.cypher`      | —                         | one row per node: `state`, `wave`, `waiting_on`, review summary, timestamps | status (human report) |
+| `node.cypher`        | `slug`                    | one node in full: properties, `inputs` (with `from`), `outputs`, `depends_on`, `satisfies`, `reviews` | plan (reopen), ad hoc |
+| `feature.cypher`     | —                         | `destination`, `context`, `out_of_scope`, `acceptance` (with `covered_by`) | review, pr |
+
+Ready-made ad-hoc queries (lineage, critical path, repair history, …) are in
+`${CLAUDE_PLUGIN_ROOT}/reference/queries.md`.

package/reference/failure-policies.md

@@ -6,10 +6,10 @@ returns `fail`, or the node's own agent errors out.
 | policy     | `run` does                                                                                          |
 | ---------- | ----------------------------------------------------------------------------------------------------- |
 | `retry`    | Re-dispatch the same node, same contract, up to 2 more attempts. Same agent role, fresh context.      |
-| `fallback` | On failure, dispatch a named alternate approach (`plan` records it in the node's `contract.input`) instead of retrying the same approach. |
-| `skip`     | Mark `cancelled`, not `failed`. Downstream nodes treat it as satisfied (see derived queries). Use only when the node is genuinely optional to the destination. |
-| `repair`   | Feed the reviewer's `acceptance_results` failures back into a repair pass targeting just the failed criteria, then re-review. Bounded: 2 repair attempts, then escalate. |
-| `escalate` | Stop dispatching this node's dependents, checkpoint it `failed`, and surface it to the user in `/gbuild:status` as needing a decision. `run` does not guess a fix. |
+| `fallback` | On failure, dispatch a named alternate approach (`plan` records it as an external `INPUT` field named `fallback`, whose `shape` describes the approach) instead of retrying the same approach. |
+| `skip`     | Mark `cancelled` (`set-status.cypher`), not `failed`. Downstream nodes treat it as satisfied (see the status lifecycle in `graph-format.md`). Use only when the node is genuinely optional to the destination. |
+| `repair`   | Feed the reviewer's failed criteria (the latest `Review`'s `failed_criteria`) back into a repair pass targeting just those criteria, then re-review. Bounded: 2 repair attempts, then escalate. |
+| `escalate` | Stop dispatching this node's dependents, set it `failed` (`set-status.cypher`), and surface it to the user in `/gbuild:status` as needing a decision. `run` does not guess a fix. |
 | `stop`     | Halt the entire run — not just this node's downstream. Reserved for failures that put the whole graph's premise in doubt (e.g. a `decision` node's answer contradicts an already-completed node). |
 
 ## Choosing a policy at plan time
@@ -25,7 +25,7 @@ returns `fail`, or the node's own agent errors out.
 
 ## Bounds are mandatory
 
-`retry`, `repair`, and `fallback` all have hard caps enforced by `run` (2 attempts unless the node
-overrides it in `contract.input`). No policy allows an unbounded loop — that's what turns a bounded
+`retry`, `repair`, and `fallback` all have hard caps enforced by `run`: 2 attempts, counted from the
+node's `Review` nodes. No policy allows an unbounded loop — that's what turns a bounded
 retry into the "controlled cycle" shape's job (`reference/shapes.md`), which has its own explicit round
 cap and dedup rule.

package/reference/graph-format.md

@@ -1,131 +1,78 @@
-# `graph.json` — normative format
+# gbuild graph model — normative
 
 This file is normative. Where a skill disagrees with this doc, this doc wins.
 
-One file per feature: `.gbuild/<feature>/db/graph.json`, written once by `plan`, read-only during `run`.
+One CypherLite store per feature: `.gbuild/<feature>/db/`. `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`.
 
-**`graph.json` is a CypherLite GraphData file.** It lives alone in its own `db/` folder so CypherLite can open that folder as a database and query it with Cypher — CypherLite opens a *directory* holding `graph.json`, not a bare `.json` file:
+`templates/example.cypher` is a complete worked example — a 4-node diamond — written exactly the way
+`plan` writes a new feature.
 
-```
-cypherlite .gbuild/<feature>/db "MATCH (n:GbuildNode) RETURN n.slug, n.type"
-```
-
-The `db/` folder contains `graph.json` and nothing else that CypherLite cares about. Checkpoints live in the sibling `.gbuild/<feature>/nodes/` directory (see [State](#state-not-part-of-graphjson)) — deliberately *outside* `db/`, because CypherLite reads a directory named `nodes` as Parquet shards and would reject the store as "mixed snapshot codecs". Opening `db/` also makes CypherLite create a `db/wal/` directory; that is expected. **Only run read-only `MATCH … RETURN` Cypher against the plan** — a writing query could checkpoint and rewrite the write-once `graph.json`.
-
-### Interoperability with CypherLite
-
-`graph.json` is the *same* JSON snapshot CypherLite reads and writes — there is one store file, not a gbuild copy and a CypherLite copy. Two consequences:
-
-- **The store must be the JSON codec.** gbuild always writes `graph.json`, so the store is JSON by construction. A Parquet store directory is not readable by gbuild's stdlib parsers.
-- **A CypherLite checkpoint normalizes the file.** If a writing Cypher command is followed by `.checkpoint` (or the WAL rotates), CypherLite rewrites `graph.json` in full — adding `value_encoding` — and leaves `manifest.json` and `wal/` beside it. gbuild's parsers read only `nodes` / `relationships` / `next_node_id` / `next_rel_id` and ignore the rest, so the checkpointed snapshot remains valid and queryable by `graph.py` / `validate_format.py` unchanged.
-
-CypherLite can *read* every property gbuild writes, including the `contract` map. It cannot **write** map property values via Cypher (`InvalidPropertyType`), so a node authored purely through Cypher cannot carry `contract` today — direct JSON authoring remains the way `plan` writes it.
-
-JSON, not YAML — `scripts/graph.py` and `scripts/validate_format.py` are stdlib-only and Python's stdlib has no YAML parser. Comments are lost; that's fine, the file is agent-authored, not hand-typed. `/gbuild:status` is the human-facing view.
-
-**Validate after every change.** `scripts/validate_format.py <path>` is the format gate — run it after the initial write, after any reopen edit, after any hand-edit, before doing anything else with the file (including committing). It exits 0 + `valid: <feature>` on success, 1 + every error joined on failure. Fix the file and re-run until it passes; never hand off or run an invalid graph.
-
-The validator does its stdlib JSON checks always. If the `cypherlite` binary is on PATH, it *also* opens the file with CypherLite and runs a trivial `MATCH` — confirming CypherLite itself loads it, not just that the stdlib walk approves the shape. CypherLite is an optional consumer, not a dependency: if the binary is absent the cross-check is skipped silently (`--no-cypherlite` forces the skip too).
-
-## Top level — the GraphData envelope
-
-```jsonc
-{
-  "nodes": [ /* Feature, Acceptance, GbuildNode — see below */ ],
-  "relationships": [ /* DEPENDS_ON, HAS_ACCEPTANCE, SATISFIES */ ],
-  "indexes": [],
-  "constraints": [],
-  "next_node_id": 8,   // max(node.id) + 1 (1 if empty) — CypherLite trusts this
-  "next_rel_id": 10    // max(rel.id) + 1 (1 if empty)
-}
-```
-
-`indexes` and `constraints` are empty for gbuild graphs — kept only because CypherLite's loader expects them. `next_node_id`/`next_rel_id` are the id allocator counters; they must equal `max(id)+1` for each kind, and the validator enforces this.
-
-## Node labels
-
-Three node kinds, distinguished by label:
-
-| label        | meaning                                  | count per graph |
-| ------------ | ---------------------------------------- | --------------- |
-| `Feature`    | the one feature this graph is for         | exactly 1       |
-| `Acceptance` | one feature-level acceptance bullet        | one per bullet  |
-| `GbuildNode` | one unit of work in the dependency graph   | one per node    |
-
-### `Feature` node (id 1)
+## Store layout
 
-```jsonc
-{
-  "id": 1,
-  "labels": ["Feature"],
-  "properties": {
-    "feature": "gbuild-mvp",                 // slug, matches the .gbuild/<feature>/ dir
-    "destination": "<one line — what \"done\" looks like>",
-    "context": "<why this exists, one or two lines>",
-    "out_of_scope": ["<bullet>"]
-  }
-}
 ```
-
-Keep `destination`/`context`/`out_of_scope` short — bullets, not paragraphs. Detail lives on the nodes, not here. Same discipline as hone's 150-line `spec.md` budget, for the same reason: this block gets re-read every invocation. **Do not put an `acceptance` property here** — feature-level acceptance lives in `Acceptance` nodes.
-
-### `Acceptance` nodes
-
-One per feature-level acceptance bullet:
-
-```jsonc
-{
-  "id": 2,
-  "labels": ["Acceptance"],
-  "properties": { "id": "a-1", "text": "<bullet>" }
-}
+.gbuild/<feature>/db/
+  graph.json          CypherLite JSON snapshot — committed; always current (every write ends with .checkpoint)
+  .gitignore          "*", "!.gitignore", "!graph.json" — committed
+  manifest.json       engine files — ignored
+  wal/
+  .cypherlite.lock
 ```
 
-Each is linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`. A node that serves a criterion gets `GbuildNode -[:SATISFIES]-> Acceptance` (see below). Normalizing the bar into nodes makes it queryable on its own and joinable to the nodes that cover it.
-
-### `GbuildNode` — a unit of work
+The store is created with the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) so
+`graph.json` diffs are reviewable in a PR, and a clone holding only `graph.json` is a complete store —
+data **and** constraints.
 
-```jsonc
-{
-  "id": 4,
-  "labels": ["GbuildNode", "Code"],        // PascalCase type label, always alongside GbuildNode
-  "properties": {
-    "slug": "01-scan-existing-runners",      // filename-safe kebab-case, immutable, the stable identity
-    "title": "<string>",
-    "type": "code",                          // lowercase enum — kept as a property too (matches the label)
-    "contract": { "input": {}, "output": {} },  // structured shapes, not prose
-    "acceptance": [                          // node-level local criteria (mandatory, concrete)
-      "<concrete, checkable-by-a-fresh-context criterion>"
-    ],
-    "verify": null,                          // slug of an *additional* verify-type node, or null
-    "failure_policy": "retry | fallback | skip | repair | escalate | stop",
-    "model_tier": "cheap | strong"
-  }
-}
-```
+## Nodes
 
-- `id` — integer, sequential, unique, never reused even if a node is removed. Authoring convenience, not semantic identity — `slug` is the stable identity skills and checkpoints key on.
-- `labels` — `["GbuildNode", <PascalCase type>]`. The universal `GbuildNode` label is for `MATCH (n:GbuildNode)`; the type label (`Research`, `Decision`, `Code`, `Test`, `Verify`, `Chore`) enables `MATCH (n:Code)`.
-- `slug` — the human/inter-skill identifier. Checkpoint files are named `<slug>.json`; skills refer to nodes by slug in anything the user reads. Immutable once created.
-- `type` — lowercase enum, duplicated as a property alongside the PascalCase label so `n.type` works for sort/filter and survives any label-casing edge. The validator checks the label matches the type.
-- `contract.input` / `contract.output` — structured shapes, not prose. A downstream node's `input` should reference an upstream node's `output` field directly (by slug path in the doc string, e.g. `"<integer, from a-produce-shared-value.output.value>"`).
-- `acceptance` — **mandatory, non-empty, concrete.** The validator rejects empty or all-blank lists. Concrete means checkable by a fresh context with no other information — not `"looks correct"` or `"works well"`.
-- `verify` — only set when this node needs something *beyond* the standard `gbuild-reviewer` pass. Usually `null`.
-- **no `satisfies` property** — which global acceptance ids this node serves is expressed as `SATISFIES` edges, not an array. The validator rejects a stray `satisfies` property.
+| label        | meaning                                            | count             |
+| ------------ | -------------------------------------------------- | ----------------- |
+| `Feature`    | the one feature this store is for                  | exactly 1         |
+| `Acceptance` | one feature-level acceptance bullet                | one per bullet    |
+| `GbuildNode` | one unit of work (always with a PascalCase type label) | one per node  |
+| `Field`      | one named input or output of a GbuildNode's contract | one per field   |
+| `Review`     | one `gbuild-reviewer` verdict on a GbuildNode      | one per review attempt |
 
-### The cut test
+### `Feature`
 
-Before adding an edge `B -[:DEPENDS_ON]-> A`, ask: does B actually read something A produced? If B would run exactly the same way with A deleted, it's not a dependency — it's just the order you thought of them in. Sequence ≠ dependency. Nodes with no real edge between them belong in the same wave, not a chain.
+| property       | type           | meaning                                              |
+| -------------- | -------------- | ---------------------------------------------------- |
+| `feature`      | string         | the slug — matches the `.gbuild/<feature>/` dir, 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                                |
 
-### `acceptance` is mandatory and must be concrete
+Keep these short — bullets, not paragraphs. Detail lives on the nodes. There is no `acceptance` property:
+the feature-level bar is `Acceptance` nodes.
 
-`validate_format.py` rejects the file if any GbuildNode has an empty or all-blank `acceptance` list (same rule as hone's invariant: every build task has ≥1 acceptance criterion). Concrete means checkable by a fresh context with no other information — not `"looks correct"` or `"works well"`. Prefer criteria that name a file, a command's exit code, a specific behavior, or a literal output shape.
+### `Acceptance`
 
-### `verify` is not the review
+`id` (string, `a-1`, `a-2`, …, unique) and `text` (string, non-blank). Each is linked
+`(:Feature)-[:HAS_ACCEPTANCE]->(:Acceptance)` and covered by at least one
+`(:GbuildNode)-[:SATISFIES]->(:Acceptance)`.
 
-Every node — regardless of `type` — goes through `gbuild-reviewer` before it's checkpointed complete (see `agents/gbuild-reviewer.md`). `verify` is for something *beyond* that default: a dedicated fact-checker, an adversarial multi-vote, a human-approval gate. Most nodes have `verify: null` and are still reviewed.
+### `GbuildNode` — a unit of work
 
-### `type`
+Labels: `GbuildNode` plus exactly one type label matching `type` — `(:GbuildNode:Code {...})`. The
+universal label is for `MATCH (n:GbuildNode)`; the type label enables `MATCH (n:Code)`.
+
+| property         | type           | meaning                                                        |
+| ---------------- | -------------- | -------------------------------------------------------------- |
+| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on |
+| `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            |
+| `verify`         | string, optional | slug of an *additional* verify-type node; usually absent      |
+| `failure_policy` | string         | `retry \| fallback \| skip \| repair \| escalate \| stop` — `reference/failure-policies.md` |
+| `model_tier`     | string         | `cheap \| strong` — `reference/cost-model.md`                   |
+| `status`         | string         | `pending` at creation — see [Status lifecycle](#status-lifecycle) |
+| `started_at`     | string, optional | implementing agent's own UTC start time, set on completion    |
+| `completed_at`   | string, optional | implementing agent's own UTC finish time, set on completion   |
+
+The contract is not a property — it is the node's `Field`s (below). Which feature criteria the node
+serves is `SATISFIES` edges, not a property.
 
 | type       | label      | produces                                                              |
 | ---------- | ---------- | -------------------------------------------------------------------- |
@@ -136,116 +83,102 @@ Every node — regardless of `type` — goes through `gbuild-reviewer` before it
 | `verify`   | `Verify`   | a check on another node's output — never the same agent, never self  |
 | `chore`    | `Chore`    | mechanical work with no behavior change                                |
 
-### `failure_policy`
-
-See `reference/failure-policies.md` for how `run` applies each value.
+**`acceptance` must be concrete** — checkable by a fresh context with no other information. Not
+"looks correct" or "works well": name a file, a command's exit code, a specific behavior, or a literal
+output value.
 
-### `model_tier`
+**`verify` is not the review.** Every node goes through `gbuild-reviewer` before it can be completed
+(`agents/gbuild-reviewer.md`). `verify` is for something *beyond* that: a fact-checker, an adversarial
+multi-vote, a human-approval gate.
 
-See `reference/cost-model.md` for the cheap/strong split and when a cluster should collapse to one agent.
+### `Field` — one contract field
 
-## Relationships
+| property | type   | meaning                                                                 |
+| -------- | ------ | ----------------------------------------------------------------------- |
+| `name`   | string | unique per node and direction                                            |
+| `shape`  | string | what the value is — `<integer>`, `<list of changed file paths>`, `<commit sha>` |
+| `value`  | scalar or list of scalars, optional | outputs only — recorded when the node completes |
 
-Three types. Each gets a sequential integer `id` (never reused), `start_node`/`end_node` reference node ids, `properties` is an object (empty for all gbuild edges today).
+Output values must be scalars (string, number, boolean) or lists of scalars; CypherLite cannot store a
+map as a property value. JSON-encode anything nested into a string and say so in `shape`.
 
-### `DEPENDS_ON` — the dependency edge
+### `Review` — one reviewer verdict
 
-```jsonc
-{ "id": 6, "type": "DEPENDS_ON", "start_node": 5, "end_node": 4, "properties": {} }
-```
+`attempt` (integer, 1-based, assigned by `record.cypher`), `verdict` (`pass | fail`),
+`failed_criteria` (list of the acceptance criteria the reviewer failed; empty on a pass), `at` (string).
+Reviews are never updated or deleted — the repair history stays visible to `status`.
 
-Direction: **dependent → dependency** (`start_node` depends on `end_node`). So `MATCH (n)-[:DEPENDS_ON]->(d)` is "what does n need", and `MATCH (n)<-[:DEPENDS_ON]-(d)` is "what waits on n". Both endpoints must be `GbuildNode`s — you can't depend on the Feature or an Acceptance. The `DEPENDS_ON` graph must be acyclic (validator enforces).
+## Relationships
 
-### `HAS_ACCEPTANCE` — feature → acceptance
+| type             | from → to                  | meaning                                           |
+| ---------------- | -------------------------- | ------------------------------------------------- |
+| `HAS_ACCEPTANCE` | `Feature` → `Acceptance`   | the criterion belongs to the feature              |
+| `SATISFIES`      | `GbuildNode` → `Acceptance`| the node covers the criterion                     |
+| `DEPENDS_ON`     | `GbuildNode` → `GbuildNode`| dependent → dependency; must be acyclic           |
+| `INPUT`          | `GbuildNode` → `Field`     | the node reads this field                         |
+| `OUTPUT`         | `GbuildNode` → `Field`     | the node produces this field                      |
+| `FROM`           | `Field` → `Field`          | an input field reads an upstream node's output field |
+| `REVIEWED`       | `GbuildNode` → `Review`    | a verdict on the node                             |
 
-```jsonc
-{ "id": 1, "type": "HAS_ACCEPTANCE", "start_node": 1, "end_node": 2, "properties": {} }
-```
+No other edge shapes are valid. `MATCH (n)-[:DEPENDS_ON]->(d)` is "what does n need";
+`MATCH (n)<-[:DEPENDS_ON]-(d)` is "what waits on n".
 
-Ties each `Acceptance` node to its `Feature`. `start_node` must be the Feature node, `end_node` an Acceptance node. One per acceptance bullet.
+### The contract: `INPUT`, `OUTPUT`, `FROM`
 
-### `SATISFIES` — node → acceptance
+A node's contract is its fields. Every node declares at least one `OUTPUT` — a node that produces
+nothing structured gives `gbuild-reviewer` nothing to check. An `INPUT` field with a `FROM` edge reads
+that upstream output: when the upstream completes, the value flows to the consumer through the edge
+(`node.cypher` resolves it). An `INPUT` without `FROM` is external — the codebase, the environment, the
+user — and its `shape` says where it comes from.
 
-```jsonc
-{ "id": 3, "type": "SATISFIES", "start_node": 5, "end_node": 2, "properties": {} }
+```cypher
+(b:GbuildNode)-[:DEPENDS_ON]->(a:GbuildNode)
+(a)-[:OUTPUT]->(v:Field {name: 'value', shape: '<integer>'})
+(b)-[:INPUT]->(:Field {name: 'value', shape: '<integer>'})-[:FROM]->(v)
 ```
 
-Ties a `GbuildNode` to a feature-level criterion it covers (replaces the old `satisfies` array property). `start_node` a GbuildNode, `end_node` an Acceptance. Every `Acceptance` must be the target of at least one `SATISFIES` — an uncovered criterion means a node is missing (validator enforces).
-
-## ID authoring rules
+### The cut test, machine-checked
 
-- The skill authors integer ids directly in the file, sequential: `Feature` = 1, then `Acceptance` nodes, then `GbuildNode`s in any stable order. Relationship ids are sequential across all three types.
-- `next_node_id` / `next_rel_id` must equal `max(id)+1` for each kind (or 1 if empty). The validator enforces this because CypherLite trusts these counters on load — a stale counter can collide with a live id.
-- Never reuse an id, even if a node is removed. Slugs are the stable identity; ids are authoring convenience.
-- On reopen: append new `Acceptance`/`GbuildNode` nodes with the next available ids, add their edges, bump the counters, then re-run `validate_format.py`.
+Before adding `B -[:DEPENDS_ON]-> A`, ask: does B actually read something A produced? If B would run
+exactly the same way with A deleted, it is not a dependency — it is the order you thought of them in.
+Sequence ≠ dependency; nodes with no real edge between them belong in the same wave, not a chain.
 
-## State (not part of `graph.json`)
-
-`.gbuild/<feature>/nodes/<slug>.json`, one file per GbuildNode, written by `run`:
-
-```jsonc
-{
-  "status": "pending | in_progress | completed | failed | cancelled",
-  "output": {},              // matches the node's contract.output shape
-  "review": {
-    "verdict": "pass | fail",
-    "acceptance_results": [{ "criterion": "<text>", "passed": true }]
-  },
-  "started_at": "<ISO8601>",
-  "completed_at": "<ISO8601>"
-}
-```
+In this model the question has a checkable answer, and `validate.cypher` enforces both directions:
 
-A missing checkpoint file means `pending`. Each node owns its own file, so parallel writers never collide. Checkpoints stay as sidecar files by design: `graph.json` is write-once (plan), checkpoints are write-many (run), and only the plan needs to be CypherLite-queryable. Runtime status is joined in by `graph.py --status`, not stored in the graph.
+- every `DEPENDS_ON` carries at least one `FROM` from B's inputs to A's outputs — no edge without data
+  (`dependency-without-from`);
+- every `FROM` points at an output of a node B `DEPENDS_ON` — no data without an edge
+  (`from-without-dependency`).
 
-## Derived queries
+## Status lifecycle
 
-`scripts/graph.py` computes all of this (joining the GraphData plan with the sidecar checkpoints):
+`status` is stored on the node; `frontier` and `blocked` are derived by `status.cypher`, never stored.
 
 ```
-frontier  = status pending ∧ every DEPENDS_ON target completed-or-cancelled
-blocked   = status pending ∧ some DEPENDS_ON target not completed-or-cancelled
-in_flight = status in_progress
-waves     = topological layering — wave N holds every node whose deps all resolved in wave < N
-```
-
-A `cancelled` dependency counts as satisfied — cancelling a node must not permanently block its dependents.
-
-## Querying with Cypher
-
-Because `graph.json` is a CypherLite GraphData file, the *plan structure* is queryable directly with Cypher (no conversion). Runtime status is not — it lives in sidecar checkpoint files, so `frontier`/`blocked`/`completed` come from `graph.py --status`, not pure Cypher. Dependency-derived questions are pure Cypher:
-
-```cypher
--- the whole plan
-MATCH (n:GbuildNode) RETURN n.slug, n.type, n.title
+pending ──dispatch──▶ in_progress ──record (pass)──▶ completed
+                          │
+                          ├──set-status──▶ failed      (escalate, exhausted retry/repair, stop)
+                          └──set-status──▶ cancelled   (skip)
 
--- nodes by type
-MATCH (n:Code) RETURN n.slug, n.title
-
--- what does node d depend on (direct)
-MATCH (n {slug:'d-join-and-sum'})-[:DEPENDS_ON]->(d) RETURN d.slug
-
--- full transitive dependency chain
-MATCH (n {slug:'d-join-and-sum'})-[:DEPENDS_ON*]->(d) RETURN DISTINCT d.slug
-
--- what waits on a given node
-MATCH (n)<-[:DEPENDS_ON]-(dependent) WHERE n.slug='a-produce-shared-value' RETURN dependent.slug
-
--- nodes with no dependencies (first wave / roots)
-MATCH (n:GbuildNode) WHERE NOT (n)-[:DEPENDS_ON]->() RETURN n.slug
+frontier = pending ∧ every DEPENDS_ON target completed-or-cancelled
+blocked  = pending ∧ some DEPENDS_ON target not completed-or-cancelled
+```
 
--- nodes nobody depends on (final joins / leaves)
-MATCH (n:GbuildNode) WHERE NOT ()-[:DEPENDS_ON]->(n) RETURN n.slug
+A `cancelled` dependency counts as satisfied — abandoning an optional node must not wedge its
+dependents. A `failed` one does not — dependents stay blocked rather than build on a broken foundation.
+`completed` can only be set by `record.cypher`, and only for an `in_progress` node whose review passed
+with a value for every `OUTPUT` — a pass missing outputs is recorded as a failed review naming them.
 
--- critical path (longest dependency chain)
-MATCH p=(n:GbuildNode)-[:DEPENDS_ON*]->(m:GbuildNode) RETURN length(p) AS d, p ORDER BY d DESC LIMIT 1
+## Who enforces what
 
--- feature-level bar
-MATCH (f:Feature)-[:HAS_ACCEPTANCE]->(a:Acceptance) RETURN a.id, a.text
+| layer                     | enforces                                                                 |
+| ------------------------- | ------------------------------------------------------------------------ |
+| engine constraints (`cypher/schema.cypher`) | required properties and their types; unique `slug` and `Acceptance.id` — a violating write never lands |
+| `cypher/validate.cypher`  | exactly one `Feature`; enums; type label matches `type`; non-blank acceptance; `verify` target exists; acceptance linked and covered; allowed edge shapes only; acyclic `DEPENDS_ON`; every chore depended on; every node has an output; field ownership and uniqueness; the `FROM` cut test; completed nodes have a passing review and all output values |
+| write scripts (`cypher/*.cypher`) | `dispatch` claims only frontier nodes; `record` completes a node only on a pass with every output; `set-status` never sets `completed` |
 
--- which nodes cover each criterion
-MATCH (a:Acceptance)<-[:SATISFIES]-(n:GbuildNode) RETURN a.id, n.slug
+## Querying
 
--- uncovered criteria (a node is missing)
-MATCH (a:Acceptance) WHERE NOT ()-[:SATISFIES]->(a) RETURN a.id, a.text
-```
+The plan and its progress are one graph, so any question is a Cypher query. The plugin scripts cover
+what the skills need (`reference/cypher.md` § Script catalog); ready-made ad-hoc queries are in
+`reference/queries.md`.

package/reference/queries.md

@@ -0,0 +1,37 @@
+# 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.
+
+```cypher
+-- the whole plan with progress
+MATCH (n:GbuildNode) RETURN n.slug, n.type, n.status, n.title ORDER BY n.slug
+
+-- nodes by type
+MATCH (n:Code) RETURN n.slug, n.title
+
+-- full transitive dependency chain of a node
+MATCH (n:GbuildNode {slug: 'd-join-and-sum'})-[:DEPENDS_ON*]->(d) RETURN DISTINCT d.slug
+
+-- what waits on a node
+MATCH (n:GbuildNode {slug: 'a-produce-shared-value'})<-[:DEPENDS_ON]-(w) RETURN w.slug
+
+-- where a node's inputs come from
+MATCH (:GbuildNode {slug: 'd-join-and-sum'})-[:INPUT]->(i)-[:FROM]->(o)<-[:OUTPUT]-(u)
+RETURN i.name, u.slug, o.name, o.value
+
+-- everything downstream of a node's output field (data lineage)
+MATCH (:GbuildNode {slug: 'a-produce-shared-value'})-[:OUTPUT]->(o)<-[:FROM]-(i)<-[:INPUT]-(c)
+RETURN o.name, c.slug, i.name
+
+-- critical path (longest dependency chain)
+MATCH p = (n:GbuildNode)-[:DEPENDS_ON*]->(m:GbuildNode) RETURN [x IN nodes(p) | x.slug] AS path
+ORDER BY length(p) DESC LIMIT 1
+
+-- which nodes cover each feature criterion
+MATCH (a:Acceptance)<-[:SATISFIES]-(n:GbuildNode) RETURN a.id, collect(n.slug)
+
+-- nodes that needed a repair pass
+MATCH (n:GbuildNode)-[:REVIEWED]->(r:Review {verdict: 'fail'}) RETURN n.slug, count(r) AS failed_reviews
+```