opencode-gbuild 0.4.0

package/reference/checklist.md

@@ -0,0 +1,36 @@
+# 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.
+
+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.
+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.)
+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.
+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.)
+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
+    `reference/cost-model.md`.
+13. **The graph, run end to end with every node passing review, actually reaches `destination`.** Read
+    the `Feature` node's `destination` property back against the node set: if every node completed, is
+    the feature actually done? A graph that's internally consistent but doesn't add up to the
+    destination is still wrong.

package/reference/cost-model.md

@@ -0,0 +1,39 @@
+# Cost model
+
+`plan` sets `model_tier` per node. `run` uses it to route model choice when the backend supports it
+(the `Workflow` tool's `agent()` `model` option); the Agent-tool fallback treats it as a hint in the
+dispatched agent's prompt when the harness offers a model choice, and otherwise ignores it — it is
+never load-bearing for correctness, only cost.
+
+## `cheap`
+
+Default. Use for:
+
+- `chore` nodes — mechanical, no judgement call.
+- `test` nodes covering already-specified behavior.
+- `code` nodes with a narrow, well-specified contract and concrete acceptance criteria (the review pass
+  is what catches a cheap model's mistakes, not the model tier).
+- `gbuild-reviewer` passes against short, mechanical acceptance lists.
+
+## `strong`
+
+Reserve for:
+
+- `decision` nodes — the thing being bought is judgement, not throughput.
+- `research` nodes where the answer requires synthesizing several sources, not just one lookup.
+- `code` nodes whose contract is underspecified or whose acceptance criteria require judgement to
+  evaluate (if a node needs `strong` for this reason, consider whether `plan` should have written
+  tighter acceptance criteria instead).
+- `verify` nodes doing adversarial or fact-checking work beyond the standard review.
+
+## Collapsing a cluster to one agent
+
+When a wave's nodes are all `cheap`, tightly scoped, and small enough that one context could hold all
+of them without losing precision, `plan` may note in the cluster's shape that `run` can dispatch them
+as one agent handling the whole wave sequentially, rather than N concurrent agents — trading real
+parallelism for lower overhead when the nodes are too small to be worth splitting. This is judgement
+`plan` exercises at authoring time, not something `run` decides on its own; a wave `plan` didn't flag
+this way is dispatched as one agent per node, per the default in `skills/run/SKILL.md`.
+
+Never collapse nodes with different `failure_policy` values, or where any node in the cluster is
+`strong` — those need to be dispatched (and possibly retried/repaired) independently.

package/reference/failure-policies.md

@@ -0,0 +1,31 @@
+# Failure policies
+
+Every node declares exactly one `failure_policy`. `run` applies it when a node's `gbuild-reviewer` pass
+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. |
+| `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
+
+- Most `code`/`test` nodes: `repair` — the reviewer's per-criterion verdict is exactly the feedback a
+  repair pass needs.
+- `research`/`decision` nodes: `retry` or `escalate` — there's rarely a mechanical "repair" for a wrong
+  answer; either try again with a fresh context or hand it to the user.
+- Nodes explicitly marked non-essential to the destination in `plan`'s own judgement: `skip`.
+- Nodes with a known, nameable alternate approach: `fallback`.
+- Anything whose failure would make a sibling's already-completed work suspect: `stop`. Use sparingly —
+  this is the escape hatch for "the graph's premise broke," not a normal failure mode.
+
+## 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 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

@@ -0,0 +1,240 @@
+# `graph.json` — normative format
+
+This file is normative. Where a skill disagrees with this doc, this doc wins.
+
+One file per feature: `.gbuild/<feature>/graph.json`, written once by `plan`, read-only during `run`.
+
+**`graph.json` is a CypherLite GraphData file.** Open it directly with CypherLite and query it with Cypher:
+
+```
+cypherlite .gbuild/<feature>/graph.json "MATCH (n:GbuildNode) RETURN n.slug, n.type"
+```
+
+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)
+
+```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>" }
+}
+```
+
+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
+
+```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"
+  }
+}
+```
+
+- `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.
+
+### The cut test
+
+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.
+
+### `acceptance` is mandatory and must be concrete
+
+`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.
+
+### `verify` is not the review
+
+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.
+
+### `type`
+
+| type       | label      | produces                                                              |
+| ---------- | ---------- | -------------------------------------------------------------------- |
+| `research` | `Research` | findings — an answer to a question, cited                             |
+| `decision` | `Decision` | a choice made and recorded, with the alternatives it ruled out         |
+| `code`     | `Code`     | a coherent, reviewable change, committed                               |
+| `test`     | `Test`     | coverage for behavior a `code` node landed, when genuinely separable  |
+| `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.
+
+### `model_tier`
+
+See `reference/cost-model.md` for the cheap/strong split and when a cluster should collapse to one agent.
+
+## Relationships
+
+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).
+
+### `DEPENDS_ON` — the dependency edge
+
+```jsonc
+{ "id": 6, "type": "DEPENDS_ON", "start_node": 5, "end_node": 4, "properties": {} }
+```
+
+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).
+
+### `HAS_ACCEPTANCE` — feature → acceptance
+
+```jsonc
+{ "id": 1, "type": "HAS_ACCEPTANCE", "start_node": 1, "end_node": 2, "properties": {} }
+```
+
+Ties each `Acceptance` node to its `Feature`. `start_node` must be the Feature node, `end_node` an Acceptance node. One per acceptance bullet.
+
+### `SATISFIES` — node → acceptance
+
+```jsonc
+{ "id": 3, "type": "SATISFIES", "start_node": 5, "end_node": 2, "properties": {} }
+```
+
+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 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`.
+
+## 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>"
+}
+```
+
+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.
+
+## Derived queries
+
+`scripts/graph.py` computes all of this (joining the GraphData plan with the sidecar checkpoints):
+
+```
+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
+
+-- 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
+
+-- nodes nobody depends on (final joins / leaves)
+MATCH (n:GbuildNode) WHERE NOT ()-[:DEPENDS_ON]->(n) RETURN n.slug
+
+-- 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
+
+-- feature-level bar
+MATCH (f:Feature)-[:HAS_ACCEPTANCE]->(a:Acceptance) RETURN a.id, a.text
+
+-- which nodes cover each criterion
+MATCH (a:Acceptance)<-[:SATISFIES]-(n:GbuildNode) RETURN a.id, n.slug
+
+-- uncovered criteria (a node is missing)
+MATCH (a:Acceptance) WHERE NOT ()-[:SATISFIES]->(a) RETURN a.id, a.text
+```

package/reference/shapes.md

@@ -0,0 +1,53 @@
+# Graph shapes
+
+`plan` classifies each cluster of nodes it creates into one of these. `run` uses the classification to
+decide how to schedule it. This is a lens for judgement, not a field stored on the node — the shape
+falls out of `dependencies`.
+
+## Chain
+
+`A -> B -> C`. Each node genuinely reads the previous one's output. Runs serially — there is no
+fan-out to exploit. **Before encoding a chain, run the cut test on every edge** (see
+`graph-format.md`): a chain is often three unrelated nodes someone thought of in order, which should
+instead be three nodes in the same wave.
+
+## Diamond (fan-out / join)
+
+`A -> {B, C} -> D`. `A` produces something `B` and `C` both need; `D` needs both `B` and `C`. `B` and
+`C` have no edge between them — they land in the same wave and `run` dispatches them concurrently. `D`
+is the join: it waits for every incoming edge, not just the first.
+
+This is the shape gbuild exists to execute properly. hone-ai v1 would serialize `B` then `C` even
+though nothing requires it; the whole point of a real dependency graph is that `plan` states the truth
+(`B` and `C` are independent) and `run` acts on it (dispatches both at once).
+
+## Router
+
+One node whose output selects which of several downstream nodes actually runs — not all of them, not
+none, exactly the branch the output implies. Model this as a `decision`-type node whose `contract.output`
+names the chosen branch, with the downstream nodes each depending on it; `run`'s job is to only dispatch
+the node(s) the router's output actually selected, and mark the un-selected siblings `cancelled` (which,
+per the derived-queries rule, still satisfies anything waiting on "the router resolved").
+
+## Controlled cycle
+
+A bounded loop — e.g. generate → verify → repair → re-verify. Never an open-ended `while`. Every cycle
+in a graph must have, at plan time:
+
+- a **hard round cap** (a number, not "until it looks right")
+- a **dedup rule** against everything already seen this cycle, so repair doesn't re-surface a fix that
+  already failed once
+- an explicit **exit node** reached either by the verify passing or by hitting the cap and escalating
+
+`run` implements this as a bounded loop (see `skills/run/SKILL.md`), never as extra graph edges that
+loop back on themselves — `scripts/graph.py` rejects literal cycles in `dependencies` (that's how it
+catches a malformed graph). A controlled cycle is a *behavior* `run` executes around a small
+sub-cluster, not a topology `graph.py` has to tolerate.
+
+## Choosing a shape
+
+Ask, per pair of nodes: does one actually read the other's output (cut test)? If two nodes both come
+out "no" against everything else in the cluster, they're a diamond's fan-out, not a chain. If a node's
+output determines *which* of several next steps applies, it's a router, not a diamond (a diamond runs
+every branch; a router runs one). If the same node needs to run again based on feedback about its own
+prior output, it's a controlled cycle, not an edge back to itself.

package/scripts/graph.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""gbuild graph utility: validate, topo-order, and query a graph.json feature graph.
+
+graph.json is a CypherLite GraphData file — openable with `cypherlite <path>` and
+queryable with Cypher. This module is the query layer (topo waves, frontier,
+status report) over that file. Format validation lives in validate_format.py
+(the single source of truth for the contract); this module imports and re-exports
+its validate() and enum sets.
+
+Stdlib only, no pip install required. Schema: ../reference/graph-format.md
+
+CLI:
+  python3 graph.py <graph.json> --waves     print the topological wave decomposition
+  python3 graph.py <graph.json> --frontier  print node ids ready to run right now
+  python3 graph.py <graph.json> --status    print the full status report (default)
+
+Checkpoints are read from <graph dir>/nodes/<slug>.json by default, or --state-dir.
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Format contract + enum sets live in validate_format (single definition site).
+from validate_format import (
+    GraphError,
+    SATISFIED_STATUSES,
+    VALID_FAILURE_POLICIES,
+    VALID_MODEL_TIERS,
+    VALID_NODE_TYPES,
+    VALID_TYPE_LABELS,
+    validate,
+)
+
+
+# --- helpers over the GraphData shape ---------------------------------------
+
+def _labels(node):
+    return set(node.get("labels", []))
+
+
+def _props(node):
+    return node.get("properties", {}) if isinstance(node.get("properties"), dict) else {}
+
+
+def gbuild_nodes(graph):
+    """GbuildNode-labelled nodes, as a list."""
+    return [n for n in graph.get("nodes", []) if "GbuildNode" in _labels(n)]
+
+
+def node_by_id(graph, nid):
+    for n in graph.get("nodes", []):
+        if n.get("id") == nid:
+            return n
+    return None
+
+
+def node_by_slug(graph, slug):
+    for n in gbuild_nodes(graph):
+        if _props(n).get("slug") == slug:
+            return n
+    return None
+
+
+def slug_of(graph, nid):
+    n = node_by_id(graph, nid)
+    return _props(n).get("slug") if n else None
+
+
+def id_of_slug(graph, slug):
+    n = node_by_slug(graph, slug)
+    return n.get("id") if n else None
+
+
+def deps(graph, node_id):
+    """node_ids this node depends on (DEPENDS_ON end_nodes)."""
+    return [
+        r["end_node"]
+        for r in graph.get("relationships", [])
+        if r.get("type") == "DEPENDS_ON" and r.get("start_node") == node_id
+    ]
+
+
+def satisfies(graph, node_id):
+    """acceptance node_ids this node covers (SATISFIES end_nodes)."""
+    return [
+        r["end_node"]
+        for r in graph.get("relationships", [])
+        if r.get("type") == "SATISFIES" and r.get("start_node") == node_id
+    ]
+
+
+def feature(graph):
+    """the single Feature node, or None."""
+    for n in graph.get("nodes", []):
+        if "Feature" in _labels(n):
+            return n
+    return None
+
+
+def acceptance_nodes(graph):
+    return [n for n in graph.get("nodes", []) if "Acceptance" in _labels(n)]
+
+
+# --- core query layer --------------------------------------------------------
+
+def load_graph(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def topo_waves(graph):
+    """Layer GbuildNodes into parallel-safe waves by slug.
+
+    wave N contains every node whose DEPENDS_ON targets all resolved in <N.
+    Returns a list of lists of slugs.
+    """
+    gn = gbuild_nodes(graph)
+    # map node id -> slug, and slug -> dep slugs
+    id_to_slug = {n["id"]: _props(n).get("slug") for n in gn}
+    remaining = {id_to_slug[n["id"]]: n for n in gn}
+    resolved = set()
+    waves = []
+
+    while remaining:
+        wave = []
+        for slug, node in remaining.items():
+            dep_ids = deps(graph, node["id"])
+            dep_slugs = {id_to_slug.get(d) for d in dep_ids}
+            if dep_slugs.issubset(resolved):
+                wave.append(slug)
+        if not wave:
+            raise GraphError(f"cycle detected among: {', '.join(sorted(remaining))}")
+        wave.sort()
+        waves.append(wave)
+        for slug in wave:
+            resolved.add(slug)
+            del remaining[slug]
+
+    return waves
+
+
+def read_checkpoint(state_dir, slug):
+    path = Path(state_dir) / f"{slug}.json"
+    if not path.exists():
+        return {"status": "pending"}
+    with open(path) as f:
+        return json.load(f)
+
+
+def node_statuses(graph, state_dir):
+    """slug -> status, for every GbuildNode."""
+    return {
+        _props(n).get("slug"): read_checkpoint(state_dir, _props(n).get("slug")).get("status", "pending")
+        for n in gbuild_nodes(graph)
+    }
+
+
+def compute_report(graph, state_dir):
+    statuses = node_statuses(graph, state_dir)
+    id_slug = {n["id"]: _props(n).get("slug") for n in gbuild_nodes(graph)}
+    frontier, blocked, in_flight, completed, cancelled, failed = [], [], [], [], [], []
+
+    for node in gbuild_nodes(graph):
+        slug = _props(node).get("slug")
+        status = statuses.get(slug, "pending")
+        dep_ids = deps(graph, node["id"])
+        dep_statuses = [statuses.get(id_slug.get(d), "pending") for d in dep_ids]
+        if status == "completed":
+            completed.append(slug)
+        elif status == "cancelled":
+            cancelled.append(slug)
+        elif status == "in_progress":
+            in_flight.append(slug)
+        elif status == "failed":
+            failed.append(slug)
+        elif all(ds in SATISFIED_STATUSES for ds in dep_statuses):
+            frontier.append(slug)
+        else:
+            blocked.append(slug)
+
+    return {
+        "frontier": sorted(frontier),
+        "blocked": sorted(blocked),
+        "in_flight": sorted(in_flight),
+        "completed": sorted(completed),
+        "cancelled": sorted(cancelled),
+        "failed": sorted(failed),
+        "waves": topo_waves(graph),
+    }
+
+
+def compute_frontier(graph, state_dir):
+    return compute_report(graph, state_dir)["frontier"]
+
+
+def default_state_dir(graph_path):
+    return Path(graph_path).resolve().parent / "nodes"
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("graph_path")
+    parser.add_argument("--state-dir", default=None, help="checkpoint dir, default: <graph dir>/nodes")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--waves", action="store_true")
+    group.add_argument("--frontier", action="store_true")
+    group.add_argument("--status", action="store_true")
+    args = parser.parse_args(argv)
+
+    graph = load_graph(args.graph_path)
+    try:
+        validate(graph)
+    except GraphError as e:
+        print(f"invalid graph: {e}", file=sys.stderr)
+        return 1
+
+    state_dir = args.state_dir or default_state_dir(args.graph_path)
+
+    if args.waves:
+        print(json.dumps(topo_waves(graph)))
+    elif args.frontier:
+        print(json.dumps(compute_frontier(graph, state_dir)))
+    else:
+        print(json.dumps(compute_report(graph, state_dir), indent=2))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())