opencode-gbuild 0.8.0 → 0.9.0

package/cypher/dispatch.cypher

@@ -1,30 +1,13 @@
-// Claim the next wave: move every frontier node (pending, every DEPENDS_ON
-// target completed or cancelled) to in_progress, and return exactly what its
-// implementing agent needs — nothing about the rest of the graph. An input
-// with a `value` was read from an upstream node; one with a null value is
-// external, and its `shape` says where to find it. No rows = nothing is
-// ready (the graph is done or stuck — ask progress.cypher / attention.cypher).
-// For a router, cancel the unselected branches with set-status.cypher first.
+// Claim every frontier node (pending, every DEPENDS_ON target completed or
+// cancelled): move it to in_progress and return only what the orchestrator
+// routes on. Each agent reads its own definition with brief.cypher, so no
+// title, acceptance, inputs or outputs pass through the orchestrator. Run it
+// at the start of a run and again after every record.cypher / set-status.cypher
+// call. No rows = nothing newly ready (ask progress.cypher / attention.cypher
+// whether the graph is done or stuck).
 //   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/dispatch.cypher
 MATCH (n:GbuildNode {status: 'pending'})
 WHERE NOT EXISTS { MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode) WHERE NOT d.status IN ['completed', 'cancelled'] }
 SET n.status = 'in_progress'
-RETURN n.slug AS slug,
-       n.title AS title,
-       n.type AS type,
-       n.acceptance AS acceptance,
-       n.failure_policy AS failure_policy,
-       n.model_tier AS model_tier,
-       n.verify AS verify,
-       COLLECT {
-         MATCH (n)-[:INPUT]->(i:Field)
-         OPTIONAL MATCH (i)-[:FROM]->(o:Field)
-         WITH i, o ORDER BY i.name
-         RETURN {name: i.name, shape: i.shape, value: o.value}
-       } AS inputs,
-       COLLECT {
-         MATCH (n)-[:OUTPUT]->(f:Field)
-         WITH f ORDER BY f.name
-         RETURN {name: f.name, shape: f.shape}
-       } AS outputs
+RETURN n.slug AS slug, n.type AS type, n.model_tier AS model_tier, n.failure_policy AS failure_policy
 ORDER BY slug;

package/cypher/node.cypher

@@ -1,8 +1,9 @@
 // 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.
-// Used for reopen and ad-hoc inspection; run gets its definitions from
-// dispatch.cypher instead.
+// Each review carries the reviewer's checklist ([] when it wrote none). Used
+// for status, reopen and ad-hoc inspection; run's agents read their own
+// definition with brief.cypher instead.
 //   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl --param 'slug="<node-slug>"' < cypher/node.cypher
 MATCH (n:GbuildNode {slug: $slug})
 RETURN n.slug AS slug,
@@ -37,5 +38,5 @@ RETURN n.slug AS slug,
        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}
+         RETURN {attempt: r.attempt, verdict: r.verdict, failed_criteria: r.failed_criteria, checklist: r.checklist, at: r.at}
        } AS reviews;

package/cypher/record.cypher

@@ -1,37 +1,90 @@
-// Record a whole wave's review verdicts in one atomic call. Each result adds a
-// Review (attempt = previous reviews + 1). A pass with a value for every
-// OUTPUT field also completes the node: output values stored on its fields,
-// the implementing agent's own times on the node. A pass missing outputs is
-// recorded as a fail listing them, so the review history stays truthful.
-// Only in_progress nodes are recorded: compare the returned slugs with what
-// you sent. Output values must be scalars or lists of scalars — one nested
-// value rejects the whole batch (InvalidPropertyType); JSON-encode it and
-// resend.
-//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl --param 'results=[
-//     {"slug": "a", "verdict": "pass", "failed_criteria": [], "outputs": {"value": 7},
-//      "started_at": "<iso>", "completed_at": "<iso>"},
-//     {"slug": "b", "verdict": "fail", "failed_criteria": ["<criterion>"]}
-//   ]' < cypher/record.cypher
-UNWIND $results AS r
-MATCH (n:GbuildNode {slug: r.slug})
-WHERE n.status = 'in_progress' AND r.verdict IN ['pass', 'fail']
-WITH n, r,
+// Record one node attempt per call. Every call adds a Review (attempt =
+// previous reviews + 1) holding the verdict, its failed criteria and the
+// reviewer's checklist. A pass with a value for every OUTPUT field also
+// completes the node: output values stored on its fields, the implementing
+// agent's own times on the node, and its notes and symbols stored as
+// (n)-[:WROTE]->(:Note) and (n)-[:DEFINES]->(:Symbol). A pass missing outputs
+// is recorded as a fail listing them, so the review history stays truthful. A
+// fail stores the Review only: no outputs, notes or symbols.
+// Three params, always all bound (the script can't tell --param from
+// --fetch-params):
+//   verdict  {"slug", "verdict": "pass"|"fail", "failed_criteria": [...]} — the
+//            only source of slug, verdict and failed criteria
+//   result   <inbox>/<node-slug>.json (outputs, started_at, completed_at, and
+//            optional notes and symbols) on a pass whose file exists, else {};
+//            any slug/verdict key in it is ignored
+//   review   <inbox>/<node-slug>.review.json ({checklist}) when it exists, else
+//            {}; string entries only, the first 40, each cut to 300 chars
+// Notes keep only maps with a topic of setup|testing|conventions|gotcha and
+// non-blank string text (trimmed, cut to 300 chars): the first 5 distinct ones,
+// skipping any whose exact (topic, text) is already stored. Symbols keep only
+// maps with string name, file and purpose and a non-blank name and file
+// (trimmed, purpose cut to 160 chars): the first 10 distinct (name, file),
+// skipping any whose (name, file) is already stored. The missing-output
+// expression is text-identical to check-result.cypher's (test-pinned).
+// No row unless the node is in_progress: compare the returned slug with the
+// one sent. Output values must be scalars or lists of scalars — a nested value
+// fails the whole call with InvalidPropertyType and writes nothing.
+// `unselected`: for a completed decision node, the pending dependents reading
+// one of its outputs whose string / list-of-strings value names some readers
+// but not them — cancel them with set-status.cypher before the next dispatch.
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl \
+//     --param 'verdict={"slug":"<node-slug>","verdict":"pass","failed_criteria":[]}' \
+//     --fetch-params result=<git-common-dir>/gbuild/<slug>/inbox/<node-slug>.json \
+//     --fetch-params review=<git-common-dir>/gbuild/<slug>/inbox/<node-slug>.review.json < cypher/record.cypher
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl \
+//     --param 'verdict={"slug":"<node-slug>","verdict":"fail","failed_criteria":["implementer failed: <reason>"]}' \
+//     --param 'result={}' --param 'review={}' < cypher/record.cypher
+WITH $verdict AS v, $result AS res, $review AS rev
+MATCH (n:GbuildNode {slug: v.slug})
+WHERE n.status = 'in_progress' AND v.verdict IN ['pass', 'fail']
+WITH n, v, res, rev,
      COUNT { (n)-[:REVIEWED]->(:Review) } + 1 AS attempt,
-     CASE WHEN r.verdict = 'pass'
-          THEN [k IN COLLECT { MATCH (n)-[:OUTPUT]->(f:Field) RETURN f.name } WHERE r.outputs[k] IS NULL]
+     CASE WHEN v.verdict = 'pass'
+          THEN [k IN COLLECT { MATCH (n)-[:OUTPUT]->(f:Field) WITH f ORDER BY f.name RETURN f.name } WHERE res.outputs[k] IS NULL]
           ELSE [] END AS missing
-WITH n, r, attempt, missing, (r.verdict = 'pass' AND size(missing) = 0) AS ok
+WITH n, v, res, rev, attempt, missing, (v.verdict = 'pass' AND size(missing) = 0) AS ok
+WITH n, v, res, attempt, missing, ok,
+     [c IN coalesce(rev.checklist, []) WHERE (c IS :: STRING) | left(c, 300)][0..40] AS checklist,
+     CASE WHEN ok AND res.notes IS :: LIST<ANY> NOT NULL THEN reduce(acc = [], x IN [x IN res.notes WHERE CASE
+         WHEN NOT x IS :: MAP NOT NULL THEN false
+         WHEN NOT x.text IS :: STRING NOT NULL THEN false
+         WHEN NOT coalesce(x.topic, '') IN ['setup', 'testing', 'conventions', 'gotcha'] THEN false
+         ELSE trim(x.text) <> '' END
+       | {topic: x.topic, text: left(trim(x.text), 300)}] | CASE WHEN x IN acc THEN acc ELSE acc + [x] END)[0..5] ELSE [] END AS notes,
+     CASE WHEN ok AND res.symbols IS :: LIST<ANY> NOT NULL THEN reduce(acc = [], x IN [x IN res.symbols WHERE CASE
+         WHEN NOT x IS :: MAP NOT NULL THEN false
+         WHEN NOT (x.name IS :: STRING NOT NULL AND x.file IS :: STRING NOT NULL AND x.purpose IS :: STRING NOT NULL) THEN false
+         ELSE trim(x.name) <> '' AND trim(x.file) <> '' END
+       | {name: trim(x.name), file: trim(x.file), purpose: left(trim(x.purpose), 160)}]
+       | CASE WHEN any(y IN acc WHERE y.name = x.name AND y.file = x.file) THEN acc ELSE acc + [x] END)[0..10] ELSE [] END AS symbols
 CREATE (n)-[:REVIEWED]->(review:Review {
   attempt: attempt,
   verdict: CASE WHEN ok THEN 'pass' ELSE 'fail' END,
-  failed_criteria: coalesce(r.failed_criteria, []) + [k IN missing | 'missing output value: ' + k],
+  failed_criteria: coalesce(v.failed_criteria, []) + [k IN missing | 'missing output value: ' + k],
+  checklist: checklist,
   at: toString(datetime())
 })
-WITH n, r, attempt, missing, ok, review
+WITH n, res, attempt, missing, ok, review, notes, symbols
 OPTIONAL MATCH (n)-[:OUTPUT]->(f:Field) WHERE ok
-SET f.value = r.outputs[f.name]
-WITH DISTINCT n, r, attempt, missing, ok, review
+SET f.value = res.outputs[f.name]
+WITH DISTINCT n, res, attempt, missing, ok, review, notes, symbols
 FOREACH (_ IN CASE WHEN ok THEN [1] ELSE [] END |
-  SET n.status = 'completed', n.started_at = r.started_at, n.completed_at = r.completed_at)
-RETURN n.slug AS slug, attempt, review.verdict AS verdict, ok AS completed, missing AS missing_outputs
-ORDER BY slug;
+  SET n.status = 'completed', n.started_at = res.started_at, n.completed_at = res.completed_at)
+WITH n, attempt, missing, ok, review,
+     [x IN notes WHERE NOT EXISTS { MATCH (o:Note) WHERE o.topic = x.topic AND o.text = x.text }] AS notes,
+     [x IN symbols WHERE NOT EXISTS { MATCH (o:Symbol) WHERE o.name = x.name AND o.file = x.file }] AS symbols
+FOREACH (x IN notes |
+  CREATE (n)-[:WROTE]->(:Note {topic: x.topic, text: x.text, by_node: n.slug, at: review.at}))
+FOREACH (x IN symbols |
+  CREATE (n)-[:DEFINES]->(:Symbol {name: x.name, file: x.file, purpose: x.purpose, by_node: n.slug, at: review.at}))
+RETURN n.slug AS slug, attempt, review.verdict AS verdict, ok AS completed, missing AS missing_outputs,
+       size(notes) AS notes_added, size(symbols) AS symbols_added,
+       CASE WHEN ok AND n.type = 'decision' THEN COLLECT {
+         MATCH (n)-[:OUTPUT]->(f:Field)
+         WITH f, COLLECT { MATCH (f)<-[:FROM]-(:Field)<-[:INPUT]-(d:GbuildNode {status: 'pending'}) RETURN d.slug } AS readers,
+              CASE WHEN f.value IS :: STRING THEN [f.value] WHEN f.value IS :: LIST<STRING> THEN f.value ELSE [] END AS named
+         WHERE any(r IN readers WHERE r IN named)
+         UNWIND [r IN readers WHERE NOT r IN named] AS u
+         RETURN DISTINCT u ORDER BY u
+       } ELSE [] END AS unselected;

package/cypher/schema.cypher

@@ -42,3 +42,22 @@ CREATE CONSTRAINT review_verdict_exists FOR (n:Review) REQUIRE n.verdict IS NOT
 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>;
+CREATE CONSTRAINT review_checklist FOR (n:Review) REQUIRE n.checklist IS :: LIST<STRING NOT NULL>;
+CREATE CONSTRAINT note_topic FOR (n:Note) REQUIRE n.topic IS :: STRING;
+CREATE CONSTRAINT note_topic_exists FOR (n:Note) REQUIRE n.topic IS NOT NULL;
+CREATE CONSTRAINT note_text FOR (n:Note) REQUIRE n.text IS :: STRING;
+CREATE CONSTRAINT note_text_exists FOR (n:Note) REQUIRE n.text IS NOT NULL;
+CREATE CONSTRAINT note_by_node FOR (n:Note) REQUIRE n.by_node IS :: STRING;
+CREATE CONSTRAINT note_by_node_exists FOR (n:Note) REQUIRE n.by_node IS NOT NULL;
+CREATE CONSTRAINT note_at FOR (n:Note) REQUIRE n.at IS :: STRING;
+CREATE CONSTRAINT note_at_exists FOR (n:Note) REQUIRE n.at IS NOT NULL;
+CREATE CONSTRAINT symbol_name FOR (n:Symbol) REQUIRE n.name IS :: STRING;
+CREATE CONSTRAINT symbol_name_exists FOR (n:Symbol) REQUIRE n.name IS NOT NULL;
+CREATE CONSTRAINT symbol_file FOR (n:Symbol) REQUIRE n.file IS :: STRING;
+CREATE CONSTRAINT symbol_file_exists FOR (n:Symbol) REQUIRE n.file IS NOT NULL;
+CREATE CONSTRAINT symbol_purpose FOR (n:Symbol) REQUIRE n.purpose IS :: STRING;
+CREATE CONSTRAINT symbol_purpose_exists FOR (n:Symbol) REQUIRE n.purpose IS NOT NULL;
+CREATE CONSTRAINT symbol_by_node FOR (n:Symbol) REQUIRE n.by_node IS :: STRING;
+CREATE CONSTRAINT symbol_by_node_exists FOR (n:Symbol) REQUIRE n.by_node IS NOT NULL;
+CREATE CONSTRAINT symbol_at FOR (n:Symbol) REQUIRE n.at IS :: STRING;
+CREATE CONSTRAINT symbol_at_exists FOR (n:Symbol) REQUIRE n.at IS NOT NULL;

package/cypher/status.cypher

@@ -4,16 +4,20 @@
 //   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.
+// `last_dependency_at` is the latest completed_at among the node's completed
+// DEPENDS_ON targets (null without any): its gap to `started_at` is how long
+// the node waited for dispatch once its last dependency landed.
 //   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/status.cypher
 MATCH (n:GbuildNode)
 OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
 WITH n, coalesce(max(length(p)), 0) AS wave
 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
+WITH n, wave, [x IN collect(d) WHERE NOT x.status IN ['completed', 'cancelled'] | x.slug] AS waiting_on,
+     max(CASE WHEN d.status = 'completed' THEN d.completed_at END) AS last_dependency_at
 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
+WITH n, wave, waiting_on, last_dependency_at, r ORDER BY r.attempt DESC
+WITH n, wave, waiting_on, last_dependency_at, collect(r) AS reviews
 RETURN n.slug AS slug,
        n.title AS title,
        n.type AS type,
@@ -29,5 +33,6 @@ RETURN n.slug AS slug,
        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
+       n.completed_at AS completed_at,
+       last_dependency_at
 ORDER BY wave, slug;

package/cypher/symbols.cypher

@@ -0,0 +1,9 @@
+// Helpers, types and utilities completed nodes added, for reuse: the reviewer
+// reads it before grepping for duplication, the implementer before writing a
+// new helper. Only completed (merged) nodes' symbols exist, so nodes running at
+// the same time can't see each other's unmerged helpers. At most 100 rows.
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/symbols.cypher
+MATCH (:GbuildNode)-[:DEFINES]->(s:Symbol)
+RETURN s.name AS name, s.file AS file, s.purpose AS purpose, s.by_node AS by
+ORDER BY file, name
+LIMIT 100;

package/cypher/validate.cypher

@@ -3,16 +3,17 @@
 // 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.
+// edge shapes, coverage, acyclicity, the data-flow (FROM) cut test, and the
+// topics and owners of agent notes and symbols.
 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)
+  MATCH (n) WHERE NOT (n:Feature OR n:Acceptance OR n:GbuildNode OR n:Field OR n:Review OR n:Note OR n:Symbol)
   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
+  MATCH (n:GbuildNode) WHERE NOT n.slug =~ '^[a-z0-9]+(-[a-z0-9]+)*$' OR n.slug IN ['tree', 'db', 'inbox']
+  RETURN 'bad-slug' AS check, n.slug + ': slug must be kebab-case and not tree, db or inbox' 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
@@ -54,7 +55,9 @@ UNION ALL
           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))
+          OR (type(r) = 'REVIEWED' AND x:GbuildNode AND y:Review)
+          OR (type(r) = 'WROTE' AND x:GbuildNode AND y:Note)
+          OR (type(r) = 'DEFINES' AND x:GbuildNode AND y:Symbol))
   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
@@ -100,6 +103,18 @@ UNION ALL
 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
+UNION ALL
+  MATCH (nt:Note) WHERE NOT nt.topic IN ['setup', 'testing', 'conventions', 'gotcha'] OR trim(nt.text) = ''
+  RETURN 'bad-note' AS check, nt.by_node + ': note topic ' + nt.topic + ' must be setup, testing, conventions or gotcha, with non-blank text' AS detail
+UNION ALL
+  MATCH (nt:Note) WITH nt, COLLECT { MATCH (w:GbuildNode)-[:WROTE]->(nt) RETURN w.slug } AS by WHERE by <> [nt.by_node]
+  RETURN 'note-owner' AS check, nt.by_node + ': note must have exactly one WROTE edge, from the node named by by_node' AS detail
+UNION ALL
+  MATCH (s:Symbol) WHERE trim(s.name) = '' OR trim(s.file) = ''
+  RETURN 'bad-symbol' AS check, s.by_node + ': symbol needs a non-blank name and file' AS detail
+UNION ALL
+  MATCH (s:Symbol) WITH s, COLLECT { MATCH (w:GbuildNode)-[:DEFINES]->(s) RETURN w.slug } AS by WHERE by <> [s.by_node]
+  RETURN 'symbol-owner' AS check, s.by_node + '.' + s.name + ': symbol must have exactly one DEFINES edge, from the node named by by_node' AS detail
 }
 RETURN check, detail
 ORDER BY check, detail;

package/index.ts

@@ -29,17 +29,25 @@ const OPENCODE_NOTES = `
 You are running under OpenCode, not Claude Code. Apply these mappings to the
 instructions above:
 
-- \`Agent\`/\`Task\` tool dispatches (including run's per-node fan-out) use the
-  \`subagent\` tool. Fan-out stays real: one \`subagent\` call per frontier node,
-  all in a single message.
-- \`gbuild-reviewer\` and \`gbuild-auditor\` are not registered agents here. When
-  the instructions say to spawn one, dispatch the built-in \`general\` subagent
-  and start its prompt with the full text of
-  \`${join(root, "agents", "gbuild-reviewer.md")}\` (or
-  \`${join(root, "agents", "gbuild-auditor.md")}\`, minus the frontmatter) as its
-  instructions, followed by everything the instructions say to give it (node
-  definition, diff locations, expected verdict format). It is still a fresh,
-  isolated agent — never the one that implemented the node.
+- \`Agent\`/\`Task\` tool dispatches (including run's per-node dispatch) use the
+  \`subagent\` tool: one call per ready node, with \`background: true\` where
+  Claude Code says \`run_in_background: true\`. Handle each completion as it
+  arrives instead of waiting for a whole wave. The auditor runs in the
+  foreground (no background flag).
+- \`gbuild-implementer\`, \`gbuild-reviewer\` and \`gbuild-auditor\` are not
+  registered agents here. When the instructions say to spawn one, dispatch the
+  built-in \`general\` subagent instead:
+  - \`gbuild-implementer\` / \`gbuild-reviewer\`: the prompt is run's dispatch
+    template as written, prefixed with \`Read <Agent file> and follow it.\`,
+    where \`<Agent file>\` is the template's own \`Agent file:\` path
+    (\`${join(root, "agents", "gbuild-implementer.md")}\` /
+    \`${join(root, "agents", "gbuild-reviewer.md")}\`).
+  - \`gbuild-auditor\`: send
+    \`Read ${join(root, "agents", "gbuild-auditor.md")} and follow it.\`
+    followed by exactly what the review skill says to pass it.
+  Never paste the agent file's text into the prompt; the subagent reads it
+  itself. Each is still a fresh, isolated agent — a reviewer is never the one
+  that implemented the node.
 - \`$ARGUMENTS\` refers to the arguments this skill was invoked with in the
   conversation.
 - run's "Workflow tool" backend is Claude-specific; always use the fallback

package/package.json

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

package/reference/cypher.md

@@ -3,8 +3,9 @@
 Every gbuild skill reads and writes the feature store (modelled in `reference/graph-format.md`) with the
 `cypherlite` CLI and nothing else. `DB` throughout is the store path:
 `<git-common-dir>/gbuild/<feature>/db` — beside the feature worktree, machine-local, never committed.
-This file is the full operating manual; the skills that only run plugin scripts carry the short version
-of these rules inline.
+`INBOX` is `<git-common-dir>/gbuild/<feature>/inbox`, beside it: where `run`'s agents leave their result
+files for `record.cypher` to read. This file is the full operating manual; the skills that only run
+plugin scripts carry the short version of these rules inline.
 
 ## Requirement
 
@@ -24,15 +25,19 @@ require the explicit `query` verb. The old path-first form — database as the f
 
 ## 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 5). So:
-
-- **Only the skill running in the main context runs `cypherlite` against the store.** Subagents never
-  do: give them what they need in their prompt, have them report results in their final message, and
-  record those results yourself.
-- **Never run two `cypherlite` commands against the same store at once** — no parallel tool calls on it.
-  Fan-out is for agents, not for store access.
-- On `storage locked` (exit 5), another process holds the store (another gbuild command, a REPL left
+The store is a directory store. A writable open takes its exclusive write lock; a `--read-only` open
+does not, so read-only queries open the store beside a writer. Only a second writer fails, with
+`storage locked` (exit 5). So:
+
+- **Only the skill running in the main context writes to the store.** It is the only writer: schema,
+  dispatch, record, set-status and authored writes run there and nowhere else.
+- **Subagents may run read-only queries, never writes.** `run`'s implementers and reviewers read their
+  own brief (`brief.cypher`), the helper registry (`symbols.cypher`) and their result check
+  (`check-result.cypher`), always with `--read-only` — their agent files list exactly what they run.
+  They report through files in `INBOX` plus a one-line reply; the orchestrator records them.
+- **One `cypherlite` command at a time from the main context** — no parallel tool calls on the store.
+  Fan-out is for agents, not for store writes.
+- On `storage locked` (exit 5), another writer 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`.
 
@@ -40,9 +45,9 @@ or writer — fails with `storage locked` (exit 5). So:
 
 Always pass `--mode jsonl`: one compact JSON object per row, one row per line, and no output at all when
 there are no rows. Every call is `cypherlite query [STATEMENT] --database DB …`; with no STATEMENT the
-piped stdin is the script list. Pure reads add `--read-only`: no exit flush, a shared lock, and a
-fail-fast on a wrong path — a read-only call never creates a missing store. Writes (schema creation,
-dispatch, record, set-status, authored heredocs) go without.
+piped stdin is the script list. Pure reads add `--read-only`: no exit flush, no lock (it opens beside
+a writer, as above), and a fail-fast on a wrong path — a read-only call never creates a missing store.
+Writes (schema creation, dispatch, record, set-status, authored heredocs) go without.
 
 ```
 # a plugin read script
@@ -70,6 +75,8 @@ CYPHER
 - **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.
+  `--fetch-params NAME=<file>` binds a JSON file as `$NAME` instead — how `record` and `check-result`
+  read inbox files without anyone retyping them.
 - **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.** Wrap them in `.begin` / `.commit` — if any statement fails, the whole
@@ -119,12 +126,15 @@ All in `${CLAUDE_PLUGIN_ROOT}/cypher/`.
 | `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 |
+| `dispatch.cypher`    | —                         | claims every frontier node (→ `in_progress`); per claimed node only the routing columns `slug`, `type`, `model_tier`, `failure_policy` — agents read the rest with `brief` | run (at start, and after every record / set-status) |
+| `brief.cypher`       | `slug`                    | one node's brief: `slug`, `title`, `type`, `acceptance`, `verify`, `inputs` (`name`, `shape`, `from`, `value`), `outputs` (`name`, `shape`), `failed_criteria` (the latest review's when it failed, else `[]`), `notes` (`topic`, `text`, `by` — every transitive upstream node's notes plus setup and testing notes from any node, upstream first, then newest, at most 20) | run's implementer and reviewer (read-only) |
+| `check-result.cypher` | `slug`; `result` (`--fetch-params result=INBOX/<slug>.json`) | `slug`, `missing_outputs`, `invalid_outputs`, `unknown_outputs`, `has_times` — clean when the three lists are `[]` and `has_times` is `true` | run's implementer and reviewer (read-only) |
+| `record.cypher`      | `verdict` — `{slug, verdict, failed_criteria}`; `result` — `--fetch-params result=INBOX/<slug>.json` on a pass whose file exists, else `{}`; `review` — `--fetch-params review=INBOX/<slug>.review.json` when it exists, else `{}` (all three always bound) | one call per node: `slug`, `attempt`, `verdict`, `completed`, `missing_outputs`, `notes_added`, `symbols_added`, `unselected`; the `Review` keeps the review file's `checklist`, and a completing pass stores the result file's outputs, times, `notes` (as `Note`) and `symbols` (as `Symbol`), skipping notes and symbols already stored | run |
+| `symbols.cypher`     | —                         | `name`, `file`, `purpose`, `by` — every completed node's registered helpers, by file and name, at most 100 | run's implementer and reviewer (read-only) |
 | `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 |
+| `status.cypher`      | —                         | one row per node: `state`, `wave`, `waiting_on`, review summary, timestamps, `last_dependency_at` (latest `completed_at` among its completed dependencies, null without any) | status (human report) |
+| `node.cypher`        | `slug`                    | one node in full: properties, `inputs` (with `from`), `outputs`, `depends_on`, `satisfies`, `reviews` (`attempt`, `verdict`, `failed_criteria`, `checklist`, `at`) | 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
+Ready-made ad-hoc queries (lineage, critical path, repair history, notes by topic, …) are in
 `${CLAUDE_PLUGIN_ROOT}/reference/queries.md`.

package/reference/graph-format.md

@@ -4,9 +4,9 @@ This file is normative. Where a skill disagrees with this doc, this doc wins.
 
 One CypherLite store per feature: `<git-common-dir>/gbuild/<feature>/db/`, beside the feature worktree
 (`<git-common-dir>/gbuild/<feature>/tree/`, which `plan` creates) — untracked, machine-local, never
-committed. `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 local snapshot of
-the store, not a gbuild artifact. How to talk to the store (the single-writer rule, invocation, quoting,
+committed. `plan` creates and charts it, `run` records progress in it, and every skill reads it, as do
+`run`'s agents (read-only) — **all through Cypher**. No skill reads or writes `graph.json` directly; it
+is CypherLite's local snapshot of the store, not a gbuild artifact. How to talk to the store (the single-writer rule, invocation, quoting,
 the script catalog) is in `reference/cypher.md`.
 
 `templates/example.cypher` is a complete worked example — a 4-node diamond — written exactly the way
@@ -15,13 +15,21 @@ the script catalog) is in `reference/cypher.md`.
 ## Store layout
 
 ```
-<git-common-dir>/gbuild/<feature>/db/
-  graph.json          CypherLite JSON snapshot — the engine's local snapshot; gbuild never reads or writes it
-  manifest.json       engine files
-  wal/
-  .cypherlite.lock
+<git-common-dir>/gbuild/<feature>/
+  db/                 the store
+    graph.json        CypherLite JSON snapshot — the engine's local snapshot; gbuild never reads or writes it
+    manifest.json     engine files
+    wal/
+    .cypherlite.lock
+  inbox/              run's hand-off files: <slug>.json (implementer result), <slug>.review.json (reviewer checklist)
+  tree/               the feature worktree
+  <slug>/             a file-touching node's worktree, during run
 ```
 
+The inbox is not part of the store: `run` empties it when it starts, agents write their files there, and
+`record.cypher` reads them with `--fetch-params` — a node's outputs, notes, symbols and checklist reach
+the store only through that record.
+
 The store lives outside every checkout: untracked, machine-local, never committed. It is created with
 the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) for cross-build compatibility: a
 parquet-enabled CypherLite build defaults a new store to Parquet, and a JSON-pinned store opens in every
@@ -36,6 +44,8 @@ build.
 | `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 |
+| `Note`       | a fact an implementer left for later agents        | 0–5 per completed node |
+| `Symbol`     | a reusable helper a completed node added           | 0–10 per completed node |
 
 ### `Feature`
 
@@ -62,7 +72,7 @@ universal label is for `MATCH (n:GbuildNode)`; the type label enables `MATCH (n:
 
 | property         | type           | meaning                                                        |
 | ---------------- | -------------- | -------------------------------------------------------------- |
-| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on; `tree` is reserved (the feature worktree's directory name) |
+| `slug`           | string         | kebab-case, unique, immutable — the identity every skill keys on; `tree`, `db` and `inbox` are reserved (they name the directories beside the node worktrees) |
 | `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            |
@@ -107,8 +117,36 @@ map as a property value. JSON-encode anything nested into a string and say so in
 ### `Review` — one reviewer verdict
 
 `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`.
+`failed_criteria` (list of the acceptance criteria the reviewer failed; empty on a pass), `checklist`
+(list of string — the reviewer's per-check lines from `<slug>.review.json`, at most 40, each cut to 300
+chars; `[]` when it wrote none), `at` (string). The verdict comes from the reviewer's reply, never from
+the checklist file. Reviews are never updated or deleted — the repair history stays visible to `status`.
+
+### `Note` — a fact left for later agents
+
+| property  | type   | meaning                                                              |
+| --------- | ------ | -------------------------------------------------------------------- |
+| `topic`   | string | `setup \| testing \| conventions \| gotcha`                           |
+| `text`    | string | non-blank, trimmed, at most 300 chars                                 |
+| `by_node` | string | slug of the writing GbuildNode — the note's only `WROTE` source       |
+| `at`      | string | the completing `Review`'s `at`                                        |
+
+### `Symbol` — a registered helper
+
+| property  | type   | meaning                                                              |
+| --------- | ------ | -------------------------------------------------------------------- |
+| `name`    | string | non-blank identifier, as written in code                              |
+| `file`    | string | non-blank repo-relative path                                          |
+| `purpose` | string | one line, at most 160 chars                                           |
+| `by_node` | string | slug of the defining GbuildNode — the symbol's only `DEFINES` source  |
+| `at`      | string | the completing `Review`'s `at`                                        |
+
+Only `record.cypher` writes them, from the optional `notes` and `symbols` in a node's result file, and
+only when it completes the node — so they exist only for completed nodes; a fail or a downgraded pass
+stores none. A node keeps at most 5 notes (any whose exact `topic` and `text` is already stored is
+skipped) and 10 symbols (the first of each `name` and `file`). `brief.cypher` gives a node its
+transitive upstream nodes' notes plus every `setup` and `testing` note; `symbols.cypher` lists every
+symbol.
 
 ## Relationships
 
@@ -121,6 +159,8 @@ Reviews are never updated or deleted — the repair history stays visible to `st
 | `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                             |
+| `WROTE`          | `GbuildNode` → `Note`      | the node left this note                           |
+| `DEFINES`        | `GbuildNode` → `Symbol`    | the node added this helper                        |
 
 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".
@@ -175,9 +215,9 @@ with a value for every `OUTPUT` — a pass missing outputs is recorded as a fail
 
 | 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` |
+| engine constraints (`cypher/schema.cypher`) | required properties and their types (including every `Note` and `Symbol` property, and `Review.checklist` as a list of strings); unique `slug` and `Acceptance.id` — a violating write never lands |
+| `cypher/validate.cypher`  | exactly one `Feature`; enums; kebab-case slugs other than `tree`, `db`, `inbox` (`bad-slug`); type label matches `type`; non-blank acceptance; `verify` target exists; acceptance linked and covered; allowed labels and edge shapes only (`WROTE`, `DEFINES` included); 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; note topic and non-blank text (`bad-note`); non-blank symbol name and file (`bad-symbol`); each note and symbol owned by exactly its `by_node` (`note-owner`, `symbol-owner`) |
+| write scripts (`cypher/*.cypher`) | `dispatch` claims only frontier nodes; `record` completes a node only on a pass with every output, and stores notes and symbols only then; `set-status` never sets `completed` |
 
 ## Querying
 

package/reference/queries.md

@@ -35,4 +35,8 @@ 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
+
+-- notes by topic, newest first (topics: setup, testing, conventions, gotcha)
+MATCH (nt:Note) WHERE nt.topic IN ['setup'] RETURN nt.topic AS topic, nt.text AS text, nt.by_node AS by
+ORDER BY nt.at DESC, text LIMIT 20
 ```

package/skills/plan/SKILL.md

@@ -7,9 +7,9 @@ Plan the work described in `$ARGUMENTS` as a graph.
 ## The loop
 
 The intended workflow: plan in ordinary conversation first, then chart that plan here. After this
-skill: `/gbuild:run <slug>` once — it iterates waves until the graph completes. Then
-`/gbuild:review <slug>`; if it finds issues, reopen with `/gbuild:plan <slug> --add "<fix>"` and
-`/gbuild:run` again; if clean, `/gbuild:pr <slug>`.
+skill: `/gbuild:run <slug>` once — it starts each node as its dependencies complete, until the graph
+completes. Then `/gbuild:review <slug>`; if it finds issues, reopen with
+`/gbuild:plan <slug> --add "<fix>"` and `/gbuild:run` again; if clean, `/gbuild:pr <slug>`.
 
 Read `${CLAUDE_PLUGIN_ROOT}/reference/graph-format.md` (the normative graph model) and
 `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md` (how to talk to the store) before doing anything, and run