opencode-gbuild 0.6.1 → 0.6.3

package/README.md

@@ -98,10 +98,12 @@ OpenCode (same order, kebab-case names):
   `FROM` edges carrying data from one node's output to the next node's input. Every dependency edge
   passes the cut test — and because data flow is explicit, the validator checks it; every node has
   mandatory concrete acceptance criteria. Written and validated entirely in Cypher.
-- **`run`** dispatches every node in the current ready wave concurrently — not one at a time — reviews
-  each node's output with a dedicated `gbuild-reviewer` subagent before recording it complete, and
-  applies the node's declared failure policy on a review failure. Re-invoking after an interruption
-  resumes only the remaining frontier.
+- **`run`** dispatches every node in the current ready wave concurrently — not one at a time — with
+  each file-touching node working in its own git worktree on its own branch, forked from the feature
+  branch. A dedicated `gbuild-reviewer` subagent reviews each node's output against its branch's diff;
+  only a passing node's branch is merged back into the feature branch, and its worktree is removed.
+  Unaccepted work never lands. A review failure applies the node's declared failure policy. Re-invoking
+  after an interruption resumes only the remaining frontier, reusing the surviving worktrees.
 - **`status`** reports the graph — frontier, blocked, in-flight, completed, each node's review verdict,
   and evidence of what actually ran concurrently vs. serially.
 - **`review`** audits the finished branch as a whole in a `gbuild-auditor` subagent — abstraction
@@ -210,8 +212,8 @@ worked example through a full run, checks every validator rule and write guard,
 
 ```
 plugins/gbuild/
-  agents/gbuild-reviewer.md   # per-node review, ported from hone-ai's reviewer, never self-review
-  agents/gbuild-auditor.md    # end-of-branch maintainability audit, ported from hone-ai's auditor
+  agents/gbuild-reviewer.md   # fast per-node gate — contract, acceptance, duplication; never self-review
+  agents/gbuild-auditor.md    # end-of-branch audit: runs the test suite, then strict maintainability
   reference/                  # graph-format.md (normative model), cypher.md (how to talk to the store), queries.md (ad-hoc recipes); shapes/failure-policies/cost-model/checklist inform plan
   cypher/                     # schema, validate, progress/attention/status/node/feature reads, and run's dispatch/record/set-status
   templates/example.cypher    # a worked 4-node diamond, written the way plan writes a feature
@@ -225,4 +227,6 @@ plugins/gbuild/
 State lives outside the plugin, in the project: one CypherLite store per feature at
 `.gbuild/<feature>/db/`. It holds the plan, every node's status and output values, and the full review
 history. Only `db/graph.json` (CypherLite's JSON snapshot, kept current by every write) and the store's
-own `.gitignore` are committed.
+own `.gitignore` are committed. Per-node worktrees during a run live under `.git/gbuild/<feature>/` —
+never in `git status` — and each is removed the moment its node is accepted (merged) or terminally
+failed (discarded).

package/agents/gbuild-auditor.md

@@ -9,6 +9,13 @@ Unusually strict review of implementation quality, maintainability, and abstract
 
 The caller passes you the resolved feature slug and the feature context it read from the gbuild store: the `destination` and the acceptance bar (each criterion with the nodes covering it). Use it for scoping context only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). Do not open `.gbuild/` or run `cypherlite` — the caller owns the store. Do NOT write any file — output your audit as your final message exclusively.
 
+## Run the branch's checks first
+
+Before you audit, run the repo's own verification on the branch: the full test suite, plus typecheck and
+lint where the repo defines them. Per-node reviews only checked each node against its own acceptance
+criteria — nobody has yet run the whole suite against the accumulated diff. A failing check is a
+blocking finding: name the exact failures.
+
 ## Core Prompt
 
 > Deep code-quality audit of the current branch. Rethink structure to improve quality without changing behavior. Improve abstractions, modularity, succinctness, legibility. Be ambitious — if restructuring the codebase yields a clearly better implementation, go for it. Measure twice, cut once.
@@ -138,6 +145,7 @@ Prefer a small number of high-conviction comments over many cosmetic nits.
 
 Don't approve merely because behavior seems correct, or because every node passed its own review — a graph of individually-passing nodes can still add up to a worse codebase. Required:
 
+- the repo's test suite, typecheck, and lint (where defined) pass on the branch
 - no structural regression
 - no obvious missed simplification when a path is visible
 - no unjustified file-size explosion

package/agents/gbuild-reviewer.md

@@ -1,12 +1,17 @@
 ---
 name: gbuild-reviewer
-description: Reviews a gbuild node's output against its contract and acceptance criteria. Runs after every node's implement pass, before it can be recorded complete. Never the same agent that implemented the node.
+description: Fast per-node gate in a gbuild run — checks the node's outputs match their contract, its acceptance criteria are fulfilled, and the diff doesn't duplicate something the repo already has. Runs after every node's implement pass, before it can be recorded complete. Never the same agent that implemented the node.
 ---
 
 You are reviewing one gbuild node's output. You did not implement it — do not defer to the implementer's
 own account of what it did. Judge the actual diff and the actual output against the node's own
 declared bar.
 
+Keep this fast — you are the per-node gate, not the final audit. Correctness depth beyond the
+acceptance bar, security sweeps, performance, elegance, style, file size, and maintainability are
+`gbuild-auditor`'s job in the end-of-feature review, which also runs the branch's test suite. Do not
+flag them here. Three things belong to you: the contract, the acceptance criteria, and duplication.
+
 ## WHAT YOU'RE GIVEN
 
 - The node's definition, as the caller read it from the gbuild store: its `slug`, `title`, `type`,
@@ -22,59 +27,29 @@ store and records your verdict.
 
 ## REVIEW OBJECTIVE
 
-Two checks, in order:
+Three checks, in order:
 
 1. **Does every output field have a value matching its declared `shape`?** A missing field, or a value
    that doesn't match its shape, is a fail regardless of the acceptance criteria — a downstream node
    reading it through `FROM` will break. Values must be scalars or lists of scalars; a nested value must
    be a JSON-encoded string.
 2. **Does the output satisfy every bullet in `acceptance`, one at a time?** Not "does it seem fine
-   overall" — go bullet by bullet, pass or fail each one individually, cite why.
-
-## REVIEW CHECKLIST (for `code`/`test` nodes, against the diff)
-
-1. Correctness — does it actually do what the contract says, including edge cases the acceptance
-   criteria imply.
-2. Tests — present, meaningful, not just asserting the mock.
-3. Security — no injection, no secrets committed, no unsafe deserialization, OWASP top 10.
-4. Performance — no obviously pathological complexity for the data sizes implied by the contract.
-5. Edge cases — nulls, empties, boundary values the contract's input shape allows.
-6. Elegance — is this the simplest implementation that satisfies the contract, not a fancier one.
-7. Cleanliness — no dead code, no leftover debug statements.
-8. Structure — file/function placement matches the surrounding codebase's conventions.
-9. Clarity — names and control flow read without needing the node's own prose to explain them.
-10. Efficiency — no redundant work, no unnecessary re-computation.
-11. Conventions — matches this repo's actual patterns, not a generic default.
-12. Best-implementation check — would a competent reviewer's first suggestion be "do it this other way
-    instead"? If so, say so as an Issue, not a Suggestion.
-13. Code reuse — didn't reinvent something the repo already has.
-14. Unnecessary comments — comments explaining *what* rather than a non-obvious *why* are flagged at
-    **high priority**, same bar as any other issue.
-
-## CODE SMELL BASELINE
-
-Judgement calls, not hard violations — documented repo conventions override this baseline. Each is a
-smell paired with its usual fix:
-
-- **Mysterious Name** → rename to something the reader doesn't need the node's contract to decode.
-- **Duplicated Code** → extract, but only if the repo doesn't already have a place for it.
-- **Feature Envy** → a function using another object's data more than its own belongs on that object.
-- **Data Clumps** → the same group of values passed together repeatedly should be one structure.
-- **Primitive Obsession** → a primitive standing in for a concept that has its own rules deserves a type.
-- **Repeated Switches** → the same conditional logic scattered across call sites belongs behind one
-  abstraction.
-- **Shotgun Surgery** → one conceptual change requiring edits across many unrelated places.
-- **Divergent Change** → one module changing for many unrelated reasons.
-- **Speculative Generality** → machinery built for a future need the node's contract doesn't ask for.
-- **Message Chains** → `a.b.c.d` reaching through several objects to get one value.
-- **Middle Man** → a class that only delegates, doing nothing of its own.
-- **Refused Bequest** → a subclass that doesn't want most of what it inherits.
+   overall" — go bullet by bullet, pass or fail each one individually, cite why. If a bullet names
+   something runnable (a command, a specific test file), run just that rather than taking the diff's
+   word for it — but never the whole suite; that's the end-of-feature audit's job.
+3. **Does the diff duplicate something the repo already has?** Search for an existing helper, utility,
+   type, or pattern that already does what this node just built. If the node's core deliverable already
+   exists, that's a fail — cite the code it should have reused. A partial overlap is an Issue citing
+   the canonical code.
 
 ## GIT DIFF
 
 For `code`/`test`/`chore` nodes, always look at the actual diff before forming a verdict — the node's
-own account of what it did is not evidence. `git diff HEAD` for uncommitted work, `git diff --staged`
-if staged, `git log -1 -p` if this node already committed.
+own account of what it did is not evidence. In a gbuild run the node worked on its own branch in its
+own worktree: `git diff <feature-branch>...<node-branch>` shows the whole node diff (the caller names
+both branches and gives you the worktree path — run any check `acceptance` names from there, not from
+the main tree). Outside a run: `git diff HEAD` for uncommitted work, `git diff --staged` if staged,
+`git log -1 -p` if this node already committed.
 
 ## FINDINGS THAT CONTRADICT AN UPSTREAM NODE
 
@@ -92,10 +67,14 @@ Lead with the acceptance checklist, one line per bullet:
 [fail] <criterion text> — <why>
 ```
 
+For a duplication fail, the `[fail]` line names what was duplicated: `[fail] duplicates <existing code> —
+<what should have been reused>`.
+
 Then, only if there are findings beyond acceptance: `Issue` or `Suggestion`, each with a `Priority`
 (`critical | high | medium | low`).
 
-Finish with one verdict line: `VERDICT: pass` only if every output field has a value matching its shape
-and every acceptance bullet passed — otherwise `VERDICT: fail`. A single failed acceptance bullet or an
-output shape mismatch is enough to fail the whole node, even if everything else is clean. The caller
-records each `[fail]` line's criterion as the review's failed criteria.
+Finish with one verdict line: `VERDICT: pass` only if every output field has a value matching its shape,
+every acceptance bullet passed, and the diff doesn't substantially duplicate existing repo code —
+otherwise `VERDICT: fail`. A single failed acceptance bullet or an output shape mismatch is enough to
+fail the whole node, even if everything else is clean. The caller records each `[fail]` line's criterion
+as the review's failed criteria.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-gbuild",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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/skills/run/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Executes a gbuild graph — dispatches every ready-and-independent node in the current wave concurrently, reviews each node's output with gbuild-reviewer before recording it complete, and resumes only the remaining frontier on re-invocation. Use after /gbuild:plan has charted the graph.
+description: Executes a gbuild graph — dispatches every ready-and-independent node in the current wave concurrently, each file-touching node in its own git worktree, reviews each node's output with gbuild-reviewer before merging its branch and recording it complete, and resumes only the remaining frontier on re-invocation. Use after /gbuild:plan has charted the graph.
 ---
 
 Run the graph in `.gbuild/$ARGUMENTS/db` (the feature slug is `$ARGUMENTS`; `DB` below).
@@ -30,28 +30,39 @@ cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
 - `validate` printing anything → stop and report the rows; do not run a graph `plan` didn't finish
   correctly.
 - `attention` rows with reason `in_progress` are left over from an interrupted run (this skill is the
-  only writer and records every node before finishing). Check `git log` for commits their agents already
-  made, then reset them all in one call so they re-dispatch, and mention it in the report:
+  only writer and records every node before finishing). Check each one's worktree branch for commits
+  its agent already made (`git log $(git branch --show-current)..gbuild/<feature>/<slug>` — empty
+  means it never got that far) and leave the worktree in place: the re-dispatch reuses it. Then reset
+  them all in one call so they re-dispatch, and mention it in the report:
 
   ```
   cypherlite DB --mode jsonl --param 'slugs=["<slug>", ...]' --param 'status="pending"' \
     < ${CLAUDE_PLUGIN_ROOT}/cypher/set-status.cypher
   ```
 
+- Sweep the worktree root (step 1's `WT`) for leaks from an interruption that struck mid-cleanup: any
+  worktree whose slug is *not* among the slugs just reset does not belong to live work — remove it
+  (`git worktree remove --force`) and delete its branch (`git branch -D`). An unmerged branch is
+  unaccepted work, which must never land — that is what the isolation is for.
+
 ## Step 1: Establish VCS facts
 
-Default to `git`. `git check-ignore -q .gbuild/` tells you whether to commit the store at all.
+Default to `git`. `git check-ignore -q .gbuild/` tells you whether to commit the store at all. Record
+two facts for the wave mechanics below: `BRANCH` = `git branch --show-current` (the feature branch —
+every accepted node merges back into it), and `WT` = `$(git rev-parse --git-common-dir)/gbuild/$ARGUMENTS`
+(the worktree root — inside `.git/`, so worktrees never appear in `git status` or get committed).
 
 ## Step 2: Pick a backend
 
 **Workflow tool**, if this session has opted into multi-agent orchestration (ultracode, or the user
 asked for a workflow explicitly) — translate each claimed wave into a `pipeline()`/`parallel()` script:
 each node is an `agent()` implement call, immediately followed by a `gbuild-reviewer` `agent()` review
-call scoped to that node's outputs + `acceptance`, using `schema` for the pass/fail verdict. Code nodes
-touching files that could conflict with a concurrent sibling get `isolation: 'worktree'`.
+call scoped to that node's outputs + `acceptance`, using `schema` for the pass/fail verdict. Every
+file-touching (`code`/`test`/`chore`) node gets `isolation: 'worktree'`.
 Controlled-cycle clusters become a bounded `while` loop per `${CLAUDE_PLUGIN_ROOT}/reference/shapes.md`'s
 round cap. Route `model_tier: strong` nodes via `opts.model` where the harness supports an override. The
-script never touches the store: collect the results and record them from the main context (step 3.4).
+script never touches the store: collect the results, land each accepted node's branch from the main
+context (step 3.4), then record (step 3.5).
 
 **Fallback** (default — no opt-in required, and always what step 3 below assumes): fire one `Agent`
 tool call per claimed node, **all in a single message** — this is what makes the fan-out real rather
@@ -71,9 +82,28 @@ behavior this plugin replaces.
    `inputs` (an input with a `value` came from an upstream node; one without is external — its `shape`
    says where to find it), and `outputs`. **No rows** → nothing is ready: go to step 5.
 
-2. **IMPLEMENT.** In one message, spawn one `Agent` per claimed node with its row. Tell it to:
-   - actually do the work — for `code`/`test`/`chore` nodes make the change in the working tree (not
-     describe it) and commit it, message `<feature>/<slug>: <what changed>`;
+2. **IMPLEMENT.** First, give every claimed `code`/`test`/`chore` node its own worktree — one shell
+   loop over the wave's slugs, idempotent so an interrupted or re-dispatched node keeps its earlier
+   work (`research`/`decision` nodes touch no files and get no worktree):
+
+   ```
+   mkdir -p WT
+   git worktree list --porcelain | grep -q "^worktree .*/<slug>$" \
+     || git worktree add WT/<slug> -b gbuild/<feature>/<slug> BRANCH 2>/dev/null \
+     || git worktree add WT/<slug> gbuild/<feature>/<slug>
+   ```
+
+   (skip if the worktree already exists; else fork a fresh branch off `BRANCH`; if the branch already
+   exists from an earlier attempt, attach to it instead — nothing is redone). Then, in one message,
+   spawn one `Agent` per claimed node with its row. Tell it to:
+   - actually do the work — for `code`/`test`/`chore` nodes make the change **in its worktree**
+     (`WT/<slug>`), never the main working tree: every edit, every check, and every git command runs
+     there, and it commits on the node branch, message `<feature>/<slug>: <what changed>`. A worktree
+     is a fresh checkout — if the project needs installed dependencies to build or test
+     (`node_modules`, `.venv`, …), install or symlink them in the worktree first;
+   - before finishing, run the checks relevant to its change — anything the node's `acceptance` names,
+     and for `code`/`test` nodes the tests covering the files it touched — and leave them green. The
+     per-node review will not re-run these; the full suite runs in the end-of-feature audit;
    - produce a value for every output field: a scalar or a list of scalars, JSON-encoding anything
      nested into a string;
    - record its own UTC start and finish (`date -u +%Y-%m-%dT%H:%M:%SZ`) and end its final message with
@@ -82,10 +112,27 @@ behavior this plugin replaces.
 
 3. **REVIEW.** Once IMPLEMENT returns, spawn a `gbuild-reviewer` per node, again all in one message
    (`agents/gbuild-reviewer.md` — this plugin's own copy, gbuild does not depend on hone-ai being
-   installed). Give it the node's row, the agent's reported outputs, and where the diff is. Never let
-   the implementing agent review its own work.
+   installed). Give it the node's row, the agent's reported outputs, and where the diff is — for a
+   worktree'd node that is its branch, `git diff BRANCH...gbuild/<feature>/<slug>`, plus the worktree
+   path so it can run just the checks `acceptance` names there (the worktree still exists at this
+   point). Never let the implementing agent review its own work.
+
+4. **LAND.** For each `pass` verdict on a `code`/`test`/`chore` node, merge its branch into the
+   feature branch and clean up, from the main tree:
+
+   ```
+   git merge --no-ff gbuild/<feature>/<slug> \
+     && git worktree remove --force WT/<slug> \
+     && git branch -d gbuild/<feature>/<slug>
+   ```
+
+   A merge conflict means two supposedly independent nodes touched the same lines: `git merge --abort`
+   and treat the node as review-failed, the conflict as its failed criterion — step 6's policy decides
+   (a retry/repair re-dispatch tells the agent to rebase its branch onto `BRANCH` and resolve it).
+   Worktrees and branches are deleted only here, after acceptance — a failed node's stays for its next
+   attempt (step 6).
 
-4. **RECORD** the whole wave in one call — one result per node, `verdict` from the reviewer's
+5. **RECORD** the whole wave in one call — one result per node, `verdict` from the reviewer's
    `VERDICT:` line, `failed_criteria` from its `[fail]` lines:
 
    ```
@@ -100,20 +147,26 @@ behavior this plugin replaces.
    recorded (it wasn't `in_progress`) — find out why before moving on. `InvalidPropertyType` means an
    output value was a map; the whole batch was rejected — JSON-encode it and send the batch again.
 
-5. **FAILURES.** For each row with `completed: false` (a failed review, or a pass `record` downgraded
-   because `missing_outputs` is non-empty), apply the node's `failure_policy`
+6. **FAILURES.** For each row with `completed: false` (a failed review, an aborted merge, or a pass
+   `record` downgraded because `missing_outputs` is non-empty), apply the node's `failure_policy`
    (`${CLAUDE_PLUGIN_ROOT}/reference/failure-policies.md`), using its `attempt` as the count:
    - `retry` / `repair` → re-dispatch implement → review with the failed criteria fed back in, reusing
-     the row you already hold, then record just those nodes. Bounded: 2 attempts.
-   - `fallback` → dispatch the named alternate approach the same way.
+     the row you already hold **and the node's existing worktree and branch** — the next attempt builds
+     on them, it does not start over. Then record just those nodes. Bounded: 2 attempts.
+   - `fallback` → dispatch the named alternate approach the same way, but remove the failed attempt's
+     worktree and branch first (`git worktree remove --force`, `git branch -D`) — the alternate
+     approach starts from a fresh branch off `BRANCH`.
    - `skip` → `cancelled`; `escalate` (or an exhausted retry/repair) → `failed`, its dependents stay
      blocked while siblings elsewhere keep going; `stop` → `failed` and halt the entire run. One
-     `set-status.cypher` call per status, with every slug that gets it.
+     `set-status.cypher` call per status, with every slug that gets it. A node reaching a terminal
+     status gets cleaned up: `git worktree remove --force WT/<slug>` and
+     `git branch -D gbuild/<feature>/<slug>` — its work was never accepted, so it never lands.
    - A completed router (`decision` choosing a branch) → cancel the unselected branches with
      `set-status.cypher` before the next claim.
 
-Nodes in the same wave never read each other's outputs, so true concurrent dispatch is safe by
-construction — only the store calls are serialized.
+Nodes in the same wave never read each other's outputs, and every file-touching node works in its own
+worktree, so true concurrent dispatch is safe by construction — the store calls and the merges onto
+`BRANCH` are the only serialized points.
 
 ## Step 4: Next wave
 
@@ -142,5 +195,6 @@ Report: which nodes ran this invocation, which passed review outright vs. needed
 ## Resuming
 
 Re-invoking `/gbuild:run <feature>` after an interruption re-runs step 0 fresh: nodes an interrupted
-wave left `in_progress` are reset, and the next claim picks up exactly the remaining frontier. Nothing
-needs to be told what already finished — the store is the memory.
+wave left `in_progress` are reset (their worktrees and any commits on their branches survive — the
+re-dispatch reuses them), and the next claim picks up exactly the remaining frontier. Nothing needs to
+be told what already finished — the store is the memory.