@oisincoveney/pipeline 2.6.0 → 2.8.0

package/docs/config-architecture.md

@@ -164,6 +164,13 @@ Project-authored skill and rule paths resolve from the project root and must
 exist for runtime use. If default skill files are missing, run `moka init` to
 install them before executing workflows.
 
+`moka init --skill-scope` (PIPE-83.12) chooses how the default set is installed:
+`project` (default) vendors a repo-local copy (`skills add … --copy`,
+`skills-lock.json`); `personal` installs once at user/global scope
+(`skills add … --global`) so every repo the user opens inherits the skills with
+no per-repo copy and no project lockfile — the standardization path for a single
+user across many projects.
+
 MCP-enabled profiles use one gateway grant:
 
 ```yaml
@@ -352,6 +359,104 @@ The toposort uses `@dagrejs/graphlib` for the graph model but an iterative
 traversal for the topological sort, because graphlib's recursive topsort can
 overflow the call stack on deep generated workflow chains.
 
+## Context, durability & best-of-N features (PIPE-83)
+
+The shipped `defaults/pipeline.yaml` turns **`context_handoff`, `repo_map`,
+`durability`, `best_of_n` (n=2 on green), and `parallel_worktrees` ON** — moka
+uses its architecture by default. `best_of_n` is the cost/quality dial: n=2
+~doubles green-node spend, so lower `n` or set `enabled: false` to spend the
+minimum. Each block can be overridden in `pipeline.yaml`; the per-block
+`# default …` notes below mark the *schema* default that applies when a block is
+omitted entirely.
+
+### `context_handoff` — curated node-to-node handoffs
+
+```yaml
+context_handoff:
+  enabled: true          # default false
+  model: openai/gpt-5.5-fast   # optional cheap model for the deriving call
+```
+
+When enabled, each agent node derives a structured `NodeHandoff`
+(`summary`, `decisions`, `artifacts`, `testNames`, `openQuestions`) from its raw
+output via a cheap read-only finalizer. Downstream nodes then receive that
+curated handoff in their prompt instead of the upstream node's full transcript
+(`renderAgentPrompt`), which kills the prompt-bloat from re-hydrating every
+ancestor's output. When a node produces no handoff, consumers fall back to the
+raw output text, so disabling the flag is byte-identical to prior behaviour.
+
+### `parallel_worktrees` — isolated parallel children
+
+```yaml
+parallel_worktrees:
+  enabled: true          # default false
+```
+
+When enabled, every child of a `kind: parallel` node runs in its own git
+worktree on an auto-named branch (`.pipeline/worktrees/...`), so concurrent
+candidate edits cannot collide. Teardown is idempotent and crash-safe: a
+worktree with dirty or unpushed work is retained (never deleted), and orphaned
+worktrees are GC'd on the next parallel node under the same guard. A worktree is
+*not* a sandbox (node_modules/build state are shared) — real isolation remains
+k8s mode. SDK-runner nodes honour the per-child directory via `plan.cwd`.
+
+### `best_of_n` — generate N candidates and select the winner
+
+```yaml
+best_of_n:
+  enabled: true          # default false
+  n: 3                   # candidates per matching node (default 1 = off)
+  categories: [green]    # which node categories fan out (id-substring match)
+  judge_model: openai/gpt-5.5   # optional LLM judge; omit for status-only
+```
+
+When enabled with `n > 1`, the `candidates` schedule pass expands each matching
+agent node into a `kind: parallel` of N candidate children
+(`<node>--candidates`) feeding a `select-candidate` builtin that keeps the
+original node id. Each candidate builds in its own worktree (pair with
+`parallel_worktrees`) and is throttled by its category's
+`token_budget.fan_out_width` cap. The selector scores candidates by a hybrid of
+execution status (PASS/FAIL) and, when `judge_model` is set, a 0..1 LLM judge
+score; it emits the winner's output and **never self-fixes** — if no candidate
+passes, the node fails with evidence.
+
+### `durability` — durable crash-resume
+
+```yaml
+durability:
+  enabled: true              # default false
+  dir: .pipeline/journal     # default
+```
+
+When enabled, the scheduler journals each terminal node result to an
+append-only JSONL log under `dir`, keyed by run id (`<dir>/<runId>.jsonl`). A
+killed run, re-invoked with the same run id, resumes from the last **passed**
+node — finished nodes are not re-run and their tokens are not re-spent — while a
+failed node and everything downstream replay so fail-fast and blocked-descendant
+handling stay live. The journal is a swappable seam (`RunJournal`): the shipped
+`fileRunJournal` needs zero external infra; a future `@effect/workflow` / cluster
+provider can implement the same interface without touching the scheduler. Off by
+default → the scheduler runs purely in-memory, exactly as before.
+
+### `mcp_gateway.host_scope` — register the gateway once globally
+
+```yaml
+mcp_gateway:
+  provider: toolhive
+  mode: hosted
+  host_scope: global       # default "project"
+```
+
+The singleton pipeline gateway is normally synthesized into each repo's
+`.opencode/opencode.json` (`host_scope: project`, the default — unchanged
+goldens). Setting `host_scope: global` stops that per-project synthesis: the
+generated project config omits the `pipeline-gateway` MCP entry and instead
+inherits one global registration written once via
+`moka gateway configure-host --scope global` (which targets
+`$OPENCODE_CONFIG_DIR`/`$XDG_CONFIG_HOME/opencode/opencode.json`). This is the
+PIPE-83.11 standardization path — register the MCP gateway once per machine
+rather than re-emitting it into every project.
+
 ## Troubleshooting
 
 - Missing host resources: run `moka install-commands`; `moka run` loads the

package/package.json

@@ -6,18 +6,23 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "commander": "^14.0.3",
+    "effect": "^3.21.3",
     "execa": "^9.5.2",
     "git-url-parse": "^16.1.0",
+    "graphology": "0.26.0",
+    "graphology-metrics": "2.4.0",
     "gray-matter": "^4.0.3",
     "js-tiktoken": "^1.0.21",
     "jsonc-parser": "^3.3.1",
     "ky": "^2.0.2",
     "micromatch": "^4.0.8",
-    "p-limit": "^7.3.0",
     "package-manager-detector": "^1.6.0",
     "pino": "^10.3.1",
     "secure-json-parse": "^4.1.0",
     "simple-git": "^3.36.0",
+    "tree-sitter-javascript": "0.25.0",
+    "tree-sitter-typescript": "0.23.2",
+    "web-tree-sitter": "0.26.9",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
@@ -121,7 +126,7 @@
     "prepack": "bun run build:cli"
   },
   "type": "module",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Config-driven multi-agent pipeline runner for repository work",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",