opencode-gbuild 0.5.0 → 0.6.0

package/skills/status/SKILL.md

@@ -4,6 +4,9 @@ description: Reports a gbuild feature's graph — frontier, blocked, in-flight,
 
 Report status for `$ARGUMENTS`.
 
+Read `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md` first and run its version check. This skill only reads
+the store; `DB` below is `.gbuild/<feature>/db`.
+
 ## Mode
 
 | arguments         | mode                                  |
@@ -15,71 +18,57 @@ Report status for `$ARGUMENTS`.
 
 ### 1. Load
 
-`.gbuild/<feature>/db/graph.json` (a CypherLite GraphData file — GbuildNodes have a `slug` property and
-are linked by `DEPENDS_ON` relationships; feature-level acceptance is `Acceptance` nodes linked by
-`HAS_ACCEPTANCE`/`SATISFIES`) and every `.gbuild/<feature>/nodes/*.json` checkpoint (keyed by slug; the
-`nodes/` dir is a sibling of the `db/` graph folder). This is a small, bounded read — status doesn't
-scale with graph size the way loading full node prose would.
-
-### 2. Compute
-
 ```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph.py .gbuild/<feature>/db/graph.json --status
+cypherlite DB -json < ${CLAUDE_PLUGIN_ROOT}/cypher/status.cypher
+cypherlite DB -json < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
 ```
 
-Gives `frontier` / `blocked` / `in_flight` / `completed` / `cancelled` / `failed` / `waves` (all as slug
-lists) directly — don't re-derive these by hand.
+One call after the other. `status.cypher` gives one row per node with its derived `state`
+(`frontier` / `blocked` / `in_progress` / `completed` / `cancelled` / `failed`), `wave`, `waiting_on`,
+review summary and timestamps — don't re-derive any of these by hand. This is a small, bounded read —
+status doesn't scale with graph size the way loading full node prose would.
 
-### 3. Render the graph
+### 2. Render the graph
 
-Draw the DAG with a marker per node status:
+Draw the DAG with a marker per node state:
 
 ```
-✓ completed   ◐ in_progress   ○ pending (frontier)   ● pending (blocked)   ✗ failed
+✓ completed   ◐ in_progress   ○ frontier   ● blocked   ✗ failed   – cancelled
 ```
 
-Annotate blocked nodes with what they're waiting on: `● d-join-and-sum ← b-consume-doubled, c-consume-squared`.
+Annotate blocked nodes with what they're waiting on (`waiting_on`):
+`● d-join-and-sum ← b-consume-doubled, c-consume-squared`.
 
-Group by wave (from `--waves`) so fan-out is visible in the layout, not just in the dependency list.
+Group by `wave` so fan-out is visible in the layout, not just in the dependency list.
 
-### 4. Review verdicts
+### 3. Review verdicts
 
-For every `completed` node, one line: pass outright, or passed after N repair attempts, from its
-checkpoint's `review` field. For `failed` nodes, the last review's failed acceptance bullets verbatim —
-this is what a human needs to make the `escalate`/`stop` call.
+For every `completed` node, one line: passed outright (`review_attempts: 1`), or passed after N repair
+attempts. For `failed` nodes, `last_failed_criteria` verbatim — this is what a human needs to make the
+`escalate`/`stop` call.
 
-### 5. Concurrency evidence
+### 4. Concurrency evidence
 
-For each wave with more than one node, compare `started_at` timestamps across that wave's checkpoints.
-Report whether they actually overlapped (real concurrent dispatch) or ran sequentially despite being in
-the same wave (a sign the fallback backend was invoked one node at a time — a bug in how `run` was
-driven, not a graph problem).
+For each wave with more than one completed node, compare the implementing agents' `started_at` /
+`completed_at` intervals. Report whether they actually overlapped (real concurrent dispatch) or ran
+back-to-back despite being in the same wave (a sign the fallback backend was invoked one node at a time —
+a bug in how `run` was driven, not a graph problem).
 
-### 6. Next action
+### 5. Next action
 
 One priority-ordered list: what `/gbuild:run <feature>` would do next (the current frontier), and
-anything needing a human decision first (`failed`/`escalate`d nodes, an empty frontier with incomplete
-nodes remaining).
-
-### 7. Invariant checks
-
-Numbered, only reporting violations (silence on an item means it passed, not that it was skipped):
+anything needing a human decision first (`failed` nodes, an empty frontier with incomplete nodes
+remaining, `in_progress` nodes when no run is active — an interrupted wave `run` will reset).
 
-1. Every GbuildNode has non-empty `acceptance` (should already be caught by `validate_format.py`'s own
-   validation — report if a node manages to lack it anyway, since that means the file was hand-edited or
-   written by something other than `plan`).
-2. Every `Acceptance` node is `SATISFIES`-covered by at least one GbuildNode (enforced by
-   `validate_format.py` — report if one slips through anyway).
-3. `DEPENDS_ON` is acyclic (validated by `validate_format.py`/`graph.py` already; report if it somehow
-   wasn't checked).
-4. No `completed` node's checkpoint is missing a `review` field with `verdict: pass` — a node marked
-   complete without a passing review means `run` skipped the review step.
-5. Every `chore`-type GbuildNode is the target of at least one `DEPENDS_ON` edge.
+### 6. Invariant checks
 
-If all five are clear, say so in one line — don't let silence be ambiguous between "checked, clear" and
-"not checked."
+`validate.cypher` is the invariant check — it covers non-empty acceptance, acceptance coverage,
+acyclicity, completed nodes without a passing review or missing an output value, orphan chores, and the
+`FROM` cut test. Report every row it returned, numbered. If it returned `[]`, say so in one line — don't
+let silence be ambiguous between "checked, clear" and "not checked."
 
 ## All-features mode
 
-For each `.gbuild/<slug>/db/graph.json` found, one line: slug, node counts by status, and whether the
-frontier is empty (done or stuck) or has ready work. Point at `/gbuild:status <slug>` for detail.
+For each `.gbuild/<slug>/db` found, run `status.cypher` — one store at a time — and print one line: slug,
+node counts by state, and whether the frontier is empty (done or stuck) or has ready work. Point at
+`/gbuild:status <slug>` for detail.

package/templates/example.cypher

@@ -0,0 +1,57 @@
+// A worked 4-node diamond: A produces a value, B and C each consume it
+// independently, D joins both. This is exactly the script plan writes for a
+// new feature — one atomic statement, piped into the store:
+//   cypherlite .gbuild/<slug>/db < plan.cypher
+// Variables (f, a1, a, a_value, ...) are only scoped to this one statement, so
+// the whole graph is created in a single CREATE chain.
+.begin
+CREATE (f:Feature {
+  feature: 'example-diamond',
+  destination: 'A tiny worked example: A produces a shared value, B and C each consume it independently, D joins both.',
+  context: "Ships with the plugin as the toy graph used in gbuild's own tests. Not a real feature.",
+  out_of_scope: ['Anything beyond demonstrating fan-out and join scheduling.']
+})
+CREATE (a1:Acceptance {id: 'a-1', text: 'run dispatches B and C concurrently, not one after the other'})
+CREATE (a2:Acceptance {id: 'a-2', text: 'D does not start until both B and C are recorded completed'})
+CREATE (f)-[:HAS_ACCEPTANCE]->(a1), (f)-[:HAS_ACCEPTANCE]->(a2)
+
+CREATE (a:GbuildNode:Chore {
+  slug: 'a-produce-shared-value', title: 'Produce the shared value B and C both need', type: 'chore',
+  acceptance: ['output.value is a single integer'],
+  failure_policy: 'retry', model_tier: 'cheap', status: 'pending'
+})
+CREATE (a)-[:OUTPUT]->(a_value:Field {name: 'value', shape: '<integer>'})
+
+CREATE (b:GbuildNode:Code {
+  slug: 'b-consume-doubled', title: 'Consume the shared value, produce its double', type: 'code',
+  acceptance: ['output.doubled equals input.value multiplied by 2'],
+  failure_policy: 'repair', model_tier: 'cheap', status: 'pending'
+})
+CREATE (b)-[:DEPENDS_ON]->(a)
+CREATE (b)-[:INPUT]->(:Field {name: 'value', shape: '<integer>'})-[:FROM]->(a_value)
+CREATE (b)-[:OUTPUT]->(b_doubled:Field {name: 'doubled', shape: '<integer>'})
+CREATE (b)-[:SATISFIES]->(a1)
+
+CREATE (c:GbuildNode:Code {
+  slug: 'c-consume-squared', title: 'Consume the shared value, produce its square', type: 'code',
+  acceptance: ['output.squared equals input.value raised to the power of 2'],
+  failure_policy: 'repair', model_tier: 'cheap', status: 'pending'
+})
+CREATE (c)-[:DEPENDS_ON]->(a)
+CREATE (c)-[:INPUT]->(:Field {name: 'value', shape: '<integer>'})-[:FROM]->(a_value)
+CREATE (c)-[:OUTPUT]->(c_squared:Field {name: 'squared', shape: '<integer>'})
+CREATE (c)-[:SATISFIES]->(a1)
+
+CREATE (d:GbuildNode:Code {
+  slug: 'd-join-and-sum', title: 'Join B and C, produce their sum', type: 'code',
+  acceptance: ['output.sum equals input.doubled plus input.squared',
+               'only runs after both b-consume-doubled and c-consume-squared are recorded completed'],
+  failure_policy: 'repair', model_tier: 'cheap', status: 'pending'
+})
+CREATE (d)-[:DEPENDS_ON]->(b), (d)-[:DEPENDS_ON]->(c)
+CREATE (d)-[:INPUT]->(:Field {name: 'doubled', shape: '<integer>'})-[:FROM]->(b_doubled)
+CREATE (d)-[:INPUT]->(:Field {name: 'squared', shape: '<integer>'})-[:FROM]->(c_squared)
+CREATE (d)-[:OUTPUT]->(:Field {name: 'sum', shape: '<integer>'})
+CREATE (d)-[:SATISFIES]->(a2);
+.commit
+.checkpoint

package/scripts/graph.py

@@ -1,239 +0,0 @@
-#!/usr/bin/env python3
-"""gbuild graph utility: validate, topo-order, and query a graph.json feature graph.
-
-graph.json is a CypherLite GraphData file. It lives at
-`.gbuild/<feature>/db/graph.json` so CypherLite can open the `db/` folder as a
-JSON-store database (CypherLite opens a *directory*, not a bare `.json` file)
-and query it 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 <feature>/db/graph.json --waves     print the topological wave decomposition
-  python3 graph.py <feature>/db/graph.json --frontier  print node ids ready to run right now
-  python3 graph.py <feature>/db/graph.json --status    print the full status report (default)
-
-Checkpoints are read from <feature>/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):
-    """Checkpoints live in the sibling `nodes/` dir, next to the `db/` graph folder.
-
-    The plan is `<feature>/db/graph.json` and state is `<feature>/nodes/`; the
-    two are siblings so CypherLite's `nodes/` Parquet-shard detection never sees
-    the checkpoint dir inside the folder it opens.
-    """
-    return Path(graph_path).resolve().parent.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: <feature>/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())