forgedock 1.22.0 → 1.23.1

package/bin/engine/outcome-codes.mjs

@@ -44,6 +44,13 @@ export const OUTCOME_CODES = Object.freeze({
   DEPENDENCY_UNREADABLE: "dependency.unreadable",
   INVALID: "invalid",
   DECOMPOSED: "decomposed",
+  // Lean core work-on (bin/lean) needs-human causes.
+  BUILDER_BLOCKED: "builder.blocked",
+  BUILDER_NO_EVIDENCE: "builder.no_evidence",
+  BUILDER_NO_COMMIT: "builder.no_commit",
+  REVIEW_FAILED: "review.failed",
+  REVIEW_NO_VERDICT: "review.no_verdict",
+  MERGE_HEAD_MISMATCH: "merge.head_mismatch",
   // Non-failure terminals, so a RUN_TERMINAL for a healthy run is not counted as a gap.
   COMPLETED: "completed",
   AWAITING_MERGE: "awaiting_merge",
@@ -115,7 +122,9 @@ export function codeForTerminalReason(reason) {
     case "phase-complete":
     case "investigation":
       return OUTCOME_CODES.COMPLETED;
-    case "awaiting-merge": return OUTCOME_CODES.AWAITING_MERGE;
+    case "awaiting-merge":
+    case "ci-pending":
+      return OUTCOME_CODES.AWAITING_MERGE;
     case "invalid": return OUTCOME_CODES.INVALID;
     case "decomposed": return OUTCOME_CODES.DECOMPOSED;
     case "engine-error": return OUTCOME_CODES.ENGINE_ERROR;

package/bin/lean/lean.mjs

@@ -76,9 +76,9 @@ export async function runCore(o) {
   }
 
   let done = null, wtCreated = false;
-  async function finish(reason, detail = "", extra = {}) {
+  async function finish(reason, detail = "", extra = {}, codeOverride = null) {
     if (done) return done; // idempotent: exactly one RUN_TERMINAL and one telemetry emit
-    const code = codeForTerminalReason(reason);
+    const code = codeOverride ?? codeForTerminalReason(reason);
     ev({ event: "RUN_TERMINAL", reason, code });
     await emit({ event: "RUN_TERMINAL", reason, code });
     if (["needs-human", "engine-error"].includes(reason)) {
@@ -93,12 +93,12 @@ export async function runCore(o) {
     done = { terminalReason: reason, detail, branch, worktree: wt, cost_usd: usage.cost_usd, tokens: { input: usage.input, output: usage.output, cache: usage.cache }, wall_ms: now() - t0, ...extra };
     return done;
   }
-  async function needsHuman(why) {
+  async function needsHuman(why, code = OUTCOME_CODES.ENGINE_ERROR) {
     try {
       await post("FORGE:NEEDS_HUMAN", `## Needs human\n${why}\n\n_${usageLine()}_`);
       await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]);
     } catch { /* best effort */ }
-    return finish("needs-human", why);
+    return finish("needs-human", why, { code }, code);
   }
 
   async function builder(n, prompt, resume) {
@@ -178,7 +178,7 @@ export async function runCore(o) {
       const evidence = (Array.isArray(result?.evidence) ? result.evidence : []).filter((x) => typeof x === "string" && x.trim());
       const verdict = result ? (result.status === "fixed" ? "valid" : result.status) : null;
       const closing = ["invalid", "already-fixed"].includes(result?.status);
-      if (closing && !evidence.length) return await needsHuman(`Builder reported "${result.status}" without evidence, so the issue is not closed automatically.\n\n${result.summary ?? "(no summary)"}`);
+      if (closing && !evidence.length) return await needsHuman(`Builder reported "${result.status}" without evidence, so the issue is not closed automatically.\n\n${result.summary ?? "(no summary)"}`, OUTCOME_CODES.BUILDER_NO_EVIDENCE);
       // The validation comment (no model call): verdict, evidence, one-line summary. For invalid/already-fixed it IS the evidence comment.
       if (verdict) validateUrl = await post("FORGE:VALIDATE", renderValidate(result, verdict));
       if (closing) {
@@ -186,8 +186,8 @@ export async function runCore(o) {
         await label("invalid");
         return await finish("invalid", result.summary ?? result.status);
       }
-      if (result?.status === "blocked") return await needsHuman(`Builder is blocked: ${result.summary ?? "(no summary)"}`);
-      if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`);
+      if (result?.status === "blocked") return await needsHuman(`Builder is blocked: ${result.summary ?? "(no summary)"}`, OUTCOME_CODES.BUILDER_BLOCKED);
+      if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`, OUTCOME_CODES.BUILDER_NO_COMMIT);
       planUrl = await post("FORGE:PLAN", renderPlan(result, files0));
     }
 
@@ -208,14 +208,14 @@ export async function runCore(o) {
       return null;
     };
     review = await doReview();
-    if (!review) return await needsHuman("Reviewer returned no parseable verdict twice.");
+    if (!review) return await needsHuman("Reviewer returned no parseable verdict twice.", OUTCOME_CODES.REVIEW_NO_VERDICT);
     if (review.fail) {
-      if (!sessionId) return await needsHuman(`Review FAIL and the builder session id is unknown, cannot resume: ${review.reason}`);
+      if (!sessionId) return await needsHuman(`Review FAIL and the builder session id is unknown, cannot resume: ${review.reason}`, OUTCOME_CODES.REVIEW_FAILED);
       await builder(++attemptN, resumeBuilderPrompt(review.reason), sessionId);
       result = (await readResult()) ?? result;
       review = await doReview();
-      if (!review) return await needsHuman("Reviewer returned no parseable verdict twice (re-review).");
-      if (review.fail) return await needsHuman(`Review FAIL twice. Last reason: ${review.reason}`);
+      if (!review) return await needsHuman("Reviewer returned no parseable verdict twice (re-review).", OUTCOME_CODES.REVIEW_NO_VERDICT);
+      if (review.fail) return await needsHuman(`Review FAIL twice. Last reason: ${review.reason}`, OUTCOME_CODES.REVIEW_FAILED);
     }
     reviewUrl = await post("FORGE:REVIEW", renderReview(review));
     ev({ event: "PHASE_COMMIT", phase: "review" });
@@ -251,13 +251,13 @@ export async function runCore(o) {
         if (policy === "all") {
           const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
           if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
-          if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`);
+          if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`, OUTCOME_CODES.CI_RED);
         } else {
           let states = [];
           try { states = (await io.checkStates(pr)) ?? []; } catch { states = []; }
           const st = (n) => states.find((x) => x.name === n)?.state ?? "pending";
           const failed = required.filter((n) => st(n) === "failure");
-          if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`);
+          if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`, OUTCOME_CODES.CI_RED);
           if (required.every((n) => st(n) === "success")) break;
         }
         if (now() - startedAt >= ciMaxMinutes * 60000) {
@@ -269,7 +269,7 @@ export async function runCore(o) {
         await sleep(ciPollDelayMs(pollIndex++, random));
       }
       if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
-        return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`);
+        return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`, OUTCOME_CODES.MERGE_HEAD_MISMATCH);
       }
     }
     await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);

package/bin/lean/lean.test.mjs

@@ -194,6 +194,20 @@ describe("core work-on", () => {
     assert.equal((await run(world({ changed: [] }))).terminalReason, "needs-human");
   });
 
+  it("needs-human terminals carry a specific outcome code, never unclassified", async () => {
+    const code = async (w, extra) => {
+      const dir = tmpDir("lean-code-");
+      const r = await run(w, { dir, ...extra });
+      const term = readLog(dir, 7).filter((e) => e.event === "RUN_TERMINAL");
+      assert.equal(term.length, 1);
+      assert.equal(term[0].code, r.code);
+      return term[0].code;
+    };
+    assert.equal(await code(world({ result: { status: "blocked", summary: "need creds" } })), "builder.blocked");
+    assert.equal(await code(world({ changed: [] })), "builder.no_commit");
+    assert.equal(await code(world({ waits: [{ rc: 1, text: "lint failed" }] }), { mergeWait: "all" }), "ci.red");
+  });
+
   it("red remote CI is needs-human; slow CI polls with backoff and ends ci-pending, never needs-human", async () => {
     const w = world({ waits: [{ rc: 1, text: "lint failed" }] });
     assert.equal((await run(w, { mergeWait: "all" })).terminalReason, "needs-human");

package/commands/orchestrate/legacy.md

@@ -0,0 +1,88 @@
+---
+description: Legacy full orchestrator (triage, investigation wave, synthesis, DAG) — reached via /orchestrate --path full
+argument-hint: "[milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0] [--auto|--confirm]"
+user-invocable: false
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Multi-Issue Parallel Orchestrator
+
+**Input**: $ARGUMENTS
+
+`--auto` and `--confirm` authorize the dispatch checkpoint; they are control
+flags, not part of the issue-set query. `--deep-plan` requests the full analysis
+path, and `--max-concurrent N` only tunes the dispatch cap.
+
+This file is the slim dispatcher. Detailed phase content lives in `commands/orchestrate/`.
+
+## OpenCode Preflight
+
+When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), run the
+deterministic preflight at `$FORGE_HOME/bin/orchestrate-preflight.mjs` immediately,
+before reading `orchestrate/config.md`, this workflow, or any phase spec. The helper
+resolves the repository from `forge.yaml`, including a parent config when the target
+is a nested Git worktree:
+
+```bash
+node "$FORGE_HOME/bin/orchestrate-preflight.mjs" \
+  --repo "$GH_REPO" \
+  --args "$ARGUMENTS"
+```
+
+The preflight is a compact mechanical adapter for issue resolution, eligibility,
+explicit dependencies, scoped issue-body file overlap, database serialization, and
+the initial ready queue. If it returns a supported plan with `requiresDeepPlan: false`
+and `confirmed: true`, launch `dispatchNow` with native background `task` calls
+immediately. Without an explicit `--auto` or `--confirm` argument, present the
+compact plan and ask for one confirmation; after the user confirms, launch the
+plan's ready queue without re-reading the large phase files. Do not load the full
+Phase 3 or Phase 4 prose just to ask that question.
+
+Continue through the phase files when the plan says `requiresDeepPlan`, the input is
+unsupported, preflight fails, or a task-result event requires recovery. This adapter
+never closes, deduplicates, or edits issues; the full shared workflow remains the
+authority for investigations, review-finding cascade handling, recovery, cleanup,
+and reporting.
+
+For a supported compact OpenCode plan, stop after the fast-path dispatch. The phase
+execution order below is the fallback path for deep plans, unsupported inputs,
+preflight failures, and task-result recovery; do not read it merely to confirm or
+dispatch a compact plan.
+
+## Execution Order
+
+Read and execute phases in sequence. Each phase file is self-contained. Resolve every path from the spec root defined in the Quick Reference below.
+
+| Step | File | Description |
+|------|------|-------------|
+| 0 | `orchestrate/config.md` | Hard rules, config resolution, multi-repo support — READ FIRST |
+| 1 | `orchestrate/phase-1-resolve.md` | Resolve the issue set from input |
+| 2 | `orchestrate/phase-2-triage.md` | Investigation-first triage, Wave 0 |
+| 2.5 | `orchestrate/phase-2.5-synthesis.md` | Investigation synthesis and deconfliction |
+| 3 | `orchestrate/phase-3-dependency.md` | Dependency analysis, DAG construction, execution plan |
+| 4 | `orchestrate/phase-4-execution.md` | Streaming DAG execution, agent dispatch, stall detection |
+| 5 | `orchestrate/phase-5-cleanup.md` | Post-batch cleanup sweep and agent audit |
+| 6 | `orchestrate/phase-6-report.md` | Consolidated report and pipeline summary |
+| — | `orchestrate/safety.md` | Safety rules and examples (reference) |
+
+## Quick Reference
+
+**Spec root (MANDATORY)**: read every file below from `${CLAUDE_PLUGIN_ROOT}` — the install root of the ForgeDock plugin that is running this command (Claude Code fills it in when it loads the spec). Only if that path does not start with `/` (not a Claude Code plugin session: install.sh, Codex, OpenCode) use `$FORGE_HOME` instead. Never read sub-files from `$FORGE_HOME` when the plugin root resolved: an exported `FORGE_HOME` can point at a different, older ForgeDock checkout, and mixing roots runs stale phase specs.
+
+**Raw reads are not substituted (MANDATORY)**: Claude Code fills in the plugin root only in the spec it loads (this file), never in files you open with Read. The phase files contain the placeholder written as `$` immediately followed by `{CLAUDE_PLUGIN_ROOT}`. Before running any bash block taken from a phase file, replace every occurrence of that placeholder with `${CLAUDE_PLUGIN_ROOT}` (the resolved root shown here), exactly as Claude Code would have. Left unreplaced it is rejected as a non-absolute path and resolution falls back to `$FORGE_HOME`, which may be stale.
+
+```
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/config.md       # ALWAYS READ FIRST
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-1-resolve.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-2-triage.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-2.5-synthesis.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-3-dependency.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-4-execution.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-5-cleanup.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-6-report.md
+```
+
+The orchestrator reads only the phase file(s) relevant to the current step rather than
+loading the full 2300-line monolith upfront.

package/commands/orchestrate.md

@@ -1,86 +1,85 @@
 ---
-description: Orchestrate parallel work on multiple issues or an entire milestone — spawns sub-agents that each run the full /work-on pipeline
-argument-hint: "[milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0] [--auto|--confirm]"
+description: Orchestrate several issues in parallel — launches one lean work-on lane per issue (background shell or agent), GitHub is the register
+argument-hint: "<#1 #2 #3 | milestone <slug> | label <name>> [--parallel K] [--lane L] [--path full]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
-# /orchestrate — Multi-Issue Parallel Orchestrator
+# /orchestrate — parallel lean work-on lanes
 
 **Input**: $ARGUMENTS
 
-`--auto` and `--confirm` authorize the dispatch checkpoint; they are control
-flags, not part of the issue-set query. `--deep-plan` requests the full analysis
-path, and `--max-concurrent N` only tunes the dispatch cap.
-
-This file is the slim dispatcher. Detailed phase content lives in `commands/orchestrate/`.
-
-## OpenCode Preflight
-
-When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), run the
-deterministic preflight at `$FORGE_HOME/bin/orchestrate-preflight.mjs` immediately,
-before reading `orchestrate/config.md`, this workflow, or any phase spec. The helper
-resolves the repository from `forge.yaml`, including a parent config when the target
-is a nested Git worktree:
-
-```bash
-node "$FORGE_HOME/bin/orchestrate-preflight.mjs" \
-  --repo "$GH_REPO" \
-  --args "$ARGUMENTS"
-```
-
-The preflight is a compact mechanical adapter for issue resolution, eligibility,
-explicit dependencies, scoped issue-body file overlap, database serialization, and
-the initial ready queue. If it returns a supported plan with `requiresDeepPlan: false`
-and `confirmed: true`, launch `dispatchNow` with native background `task` calls
-immediately. Without an explicit `--auto` or `--confirm` argument, present the
-compact plan and ask for one confirmation; after the user confirms, launch the
-plan's ready queue without re-reading the large phase files. Do not load the full
-Phase 3 or Phase 4 prose just to ask that question.
-
-Continue through the phase files when the plan says `requiresDeepPlan`, the input is
-unsupported, preflight fails, or a task-result event requires recovery. This adapter
-never closes, deduplicates, or edits issues; the full shared workflow remains the
-authority for investigations, review-finding cascade handling, recovery, cleanup,
-and reporting.
-
-For a supported compact OpenCode plan, stop after the fast-path dispatch. The phase
-execution order below is the fallback path for deep plans, unsupported inputs,
-preflight failures, and task-result recovery; do not read it merely to confirm or
-dispatch a compact plan.
-
-## Execution Order
-
-Read and execute phases in sequence. Each phase file is self-contained. Resolve every path from the spec root defined in the Quick Reference below.
-
-| Step | File | Description |
-|------|------|-------------|
-| 0 | `orchestrate/config.md` | Hard rules, config resolution, multi-repo support — READ FIRST |
-| 1 | `orchestrate/phase-1-resolve.md` | Resolve the issue set from input |
-| 2 | `orchestrate/phase-2-triage.md` | Investigation-first triage, Wave 0 |
-| 2.5 | `orchestrate/phase-2.5-synthesis.md` | Investigation synthesis and deconfliction |
-| 3 | `orchestrate/phase-3-dependency.md` | Dependency analysis, DAG construction, execution plan |
-| 4 | `orchestrate/phase-4-execution.md` | Streaming DAG execution, agent dispatch, stall detection |
-| 5 | `orchestrate/phase-5-cleanup.md` | Post-batch cleanup sweep and agent audit |
-| 6 | `orchestrate/phase-6-report.md` | Consolidated report and pipeline summary |
-| — | `orchestrate/safety.md` | Safety rules and examples (reference) |
-
-## Quick Reference
-
-**Spec root (MANDATORY)**: read every file below from `${CLAUDE_PLUGIN_ROOT}` — the install root of the ForgeDock plugin that is running this command (Claude Code fills it in when it loads the spec). Only if that path does not start with `/` (not a Claude Code plugin session: install.sh, Codex, OpenCode) use `$FORGE_HOME` instead. Never read sub-files from `$FORGE_HOME` when the plugin root resolved: an exported `FORGE_HOME` can point at a different, older ForgeDock checkout, and mixing roots runs stale phase specs.
-
-**Raw reads are not substituted (MANDATORY)**: Claude Code fills in the plugin root only in the spec it loads (this file), never in files you open with Read. The phase files contain the placeholder written as `$` immediately followed by `{CLAUDE_PLUGIN_ROOT}`. Before running any bash block taken from a phase file, replace every occurrence of that placeholder with `${CLAUDE_PLUGIN_ROOT}` (the resolved root shown here), exactly as Claude Code would have. Left unreplaced it is rejected as a non-absolute path and resolution falls back to `$FORGE_HOME`, which may be stale.
-
-```
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/config.md       # ALWAYS READ FIRST
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-1-resolve.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-2-triage.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-2.5-synthesis.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-3-dependency.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-4-execution.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-5-cleanup.md
-Read: ${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/phase-6-report.md
-```
-
-The orchestrator reads only the phase file(s) relevant to the current step rather than
-loading the full 2300-line monolith upfront.
+You are the orchestrator. Resolve the issues, order them, and run each one in its own lane. Each lane
+runs the lean work-on (validate → plan → implement → fix/regression review → PR → merge), which records
+every step on the issue. You triage and order the set yourself (no sub-agent investigations), but never implement an
+issue yourself.
+
+## 1. Legacy path
+
+If the input contains `--path full`, stop: read `${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/legacy.md`
+and follow it instead (the previous multi-phase orchestrator).
+
+## 2. Resolve, triage and build the DAG
+
+Do this yourself from issue text and the code. Spawn no sub-agents here.
+
+1. **Resolve.**
+   - Explicit numbers (`#12 13 14`) are used as given.
+   - `milestone <slug>` uses `gh issue list --milestone "<slug>" --state open --json number --jq '.[].number'`.
+   - `label <name>` uses the same with `--label`.
+
+   Keep only plain integers and drop closed issues.
+2. **Triage.** For each issue, read it once (`gh issue view N --json title,body,labels`) and record:
+   - **Ready / skip.** Skip when it is labelled `needs-human` or `workflow:merged`, or an open PR already
+     closes it (`gh pr list --search "Closes #N" --state open`). Say why.
+   - **Files.** The files or areas it will likely touch: paths named in the issue, or a quick
+     `git grep` of the symbols it names. Keep this to a few greps per issue, not an investigation.
+   - **Size.** S, M or L, from the scope the issue describes.
+3. **Build the DAG.** Edge X → N means N waits until X merges:
+   - **Explicit:** `Depends on #X` / `Blocked by #X` where X is in the set. An open X outside the set
+     means N is skipped as blocked.
+   - **Conflict:** two issues that will edit the same file or the same function run one after the
+     other (smaller first), so their PRs don't conflict. Different files run in parallel.
+   - **Logical:** one issue's fix is needed by another (for example, it adds the helper the other uses).
+
+   If you find a cycle, break it at the weakest (conflict) edge and say so.
+4. **Show the plan** as one table: issue, title, size, likely files, waits-on. There are no waves. Then proceed
+   without asking.
+
+`K` = `--parallel` (default 3). `L` = `--lane` if given, otherwise the repo's base lane from forge.yaml.
+
+## 3. Launch lanes
+
+Schedule from the DAG, not in waves. An issue is **ready** when every issue it waits on has merged (or it
+waits on nothing). Keep at most K lanes running. Whenever a lane is free, start the highest-priority ready
+issue right away (priority label first, then the smaller size). Never hold a ready issue back until other
+lanes finish.
+
+- **Shell lane (default, when `forgedock` is on PATH).** One `Bash` call per issue with
+  `run_in_background: true`:
+
+  ```bash
+  forgedock run-issue <N> --lane <L>
+  ```
+
+  The harness notifies you when the lane exits. Its last line is `issue #N → <outcome>`.
+- **Agent lane (only when the `forgedock` CLI is unavailable).** Spawn one background agent per issue.
+  The prompt is:
+
+  > Resolve issue #N (gh issue view N --comments). If already fixed or invalid, comment the file:line
+  > evidence and stop. Otherwise fix it with a regression test, run the relevant tests, commit on a
+  > branch, push, open a PR with Closes #N, and comment a summary (root cause, changes, tests, PR) on
+  > the issue.
+
+  The agent does not merge.
+
+When a lane finishes:
+- `merged` or `invalid`: start the next ready issue.
+- `needs-human`: read the issue's last comment for the reason, and mark its dependents skipped.
+- `engine-error`: relaunch it once.
+- `ci-pending` or `deferred`: leave it. A later `/orchestrate` resumes it.
+
+## 4. Report
+
+When all lanes have finished, print one table: issue, outcome, PR, minutes. Then list each
+`needs-human` or skipped issue with its one-line reason. Nothing else.

package/docs/OUTCOME-CODES.md

@@ -43,6 +43,12 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `dependency.unreadable` | The issue body or a declared dependency could not be read, so the run was refused (fail closed) | engine | Failed or unparsable `gh api` read |
 | `invalid` | Issue is invalid or in a divergent closed state | investigate, engine | `INVESTIGATION:INVALID` marker, or live snapshot |
 | `decomposed` | Issue was decomposed into sub-issues | investigate, decompose | `FORGE:DECOMPOSED` or the decomposition assessment |
+| `builder.blocked` | Core work-on: the builder reported it cannot proceed without a human decision (design, credentials, infra) | lean | `result.json` status `blocked` |
+| `builder.no_evidence` | Core work-on: the builder reported invalid/already-fixed without file:line evidence, so the issue was not closed | lean | `result.json` with empty `evidence` |
+| `builder.no_commit` | Core work-on: the builder made no commit for a fix | lean | No changed files after the builder session |
+| `review.failed` | Core work-on: the fix/regression review failed twice (or could not resume the builder) | lean | Reviewer verdict FAIL |
+| `review.no_verdict` | Core work-on: the reviewer returned no parseable verdict twice | lean | Unparsable reviewer output |
+| `merge.head_mismatch` | Core work-on: CI passed for a head other than the reviewed head; merge refused | lean | Gate head differs from the reviewed head |
 | `completed` | Non-failure terminal (merged, phase-complete, investigation) | engine | Terminal reason |
 | `awaiting_merge` | Clean result held for a merge decision | remediate | Terminal reason `awaiting-merge` |
 | `unclassified` | Fallback for an absent or unknown code | engine | The raw reason is kept alongside |

package/docs/site/command-reference.md

@@ -155,20 +155,17 @@ Deterministically verifies a staging→main bundle's acceptance criteria against
 
 ### `/orchestrate`
 
-**Parallel multi-issue pipeline.**
+**Parallel lean work-on lanes.**
 
-Spawns sub-agents that each run the full `/work-on` pipeline in parallel.
+Resolves the issues, triages them and builds a dependency DAG (explicit `Depends on`, same-file conflicts, logical order), then launches one lane per issue (`forgedock run-issue N` as a background shell, or an agent when the CLI is unavailable), at most K at a time. Each lane runs the lean work-on and records every step on its issue.
 
 ```bash
-/orchestrate milestone launch-campaign   # All issues in a milestone
 /orchestrate #42 #43 #44                 # Specific issues
-/orchestrate next 5                      # Top 5 priority issues
-/orchestrate fast-lane                   # All staging-lane issues
-/orchestrate P0                          # All P0 issues
+/orchestrate milestone launch-campaign   # All open issues in a milestone
+/orchestrate label bug --parallel 4      # All open issues with a label, 4 lanes
+/orchestrate #42 #43 --path full         # Legacy multi-phase orchestrator
 ```
 
-Each sub-agent gets its own git worktree and GitHub issue thread. No interference between parallel agents.
-
 ---
 
 #### `/milestone`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"