opencode-gbuild 0.6.2 → 0.6.4

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
@@ -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-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: gbuild-reviewer
-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.
+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 neither duplicates something the repo already has nor adds a third copy where an abstraction is due. 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
@@ -37,16 +37,25 @@ Three checks, in order:
    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.
+3. **Does the diff duplicate functionality, or add a copy where an abstraction is due?** 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. Then count copies: if this diff adds a
+   **third** copy of the same logic (the other two anywhere in the repo, elsewhere in the diff, or one
+   of each), that's a missed abstraction and a fail — name all three sites and the shared helper that
+   should own the logic. Two copies can stand; the third is where extracting beats copying. The
+   counterweight is just as binding: YAGNI. Judge only copies that actually exist in the code today —
+   never fault the diff for lacking an abstraction that only hypothetical future callers would use,
+   and never treat a single concrete implementation left un-abstracted as a finding.
 
 ## 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
 
@@ -65,13 +74,14 @@ Lead with the acceptance checklist, one line per bullet:
 ```
 
 For a duplication fail, the `[fail]` line names what was duplicated: `[fail] duplicates <existing code> —
-<what should have been reused>`.
+<what should have been reused>`, or for a missed abstraction: `[fail] third copy of <logic> (<site 1>,
+<site 2>, this diff) — extract a shared <helper>`.
 
 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,
-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
+every acceptance bullet passed, and the diff neither substantially duplicates existing repo code nor adds
+a third copy where an abstraction is due — 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.2",
+  "version": "0.6.4",
   "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,25 @@ 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;
@@ -85,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:
 
    ```
@@ -103,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
 
@@ -145,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.