@multileaf/ai-workflow 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-11-04
+
+### Added
+
+- Orchestration depth (OPP-017): `aiw orchestrate integrate --plan=<path>` prints the wave-ordered integration forecast — a deterministic `git merge-tree` dry run per isolated task branch against the current branch, reporting conflicts before any human merge. Isolated executions now record per-task duration, diff stat, and plan wall-clock time in the checkpoint, and `aiw doctor` reports leaked managed worktrees with the cleanup continuation (`worktrees_leaked` typed reason).
+- `docs/orchestration.md` gains the per-harness worktree honor matrix and the minimal adapter contract for `task.worktree`.
+
+### Fixed
+
+- `orchestrate integrate` works before option parsing (previously subcommand form collided with `--plan` validation).
+
 ## [0.13.0] - 2026-11-03
 
 ### Added

package/dist/blocking-reasons.d.ts

@@ -7,7 +7,7 @@
  * command resolves the block it was printed for. See ADR-001 and
  * docs/opportunities/OPP-004-exact-continuation-commands.md.
  */
-export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing", "workflow_still_active", "workflow_not_active", "workflow_complete", "installation_required", "state_mismatch", "context_budget_exceeded", "stage_not_in_process", "migration_required"];
+export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing", "workflow_still_active", "workflow_not_active", "workflow_complete", "installation_required", "state_mismatch", "context_budget_exceeded", "stage_not_in_process", "migration_required", "worktrees_leaked", "orchestration_not_executed"];
 export type BlockingReasonCode = (typeof BLOCKING_REASON_CODES)[number];
 /** How the user or agent gets past a block. Exactly one of three kinds. */
 export type BlockingContinuation = 

package/dist/blocking-reasons.js

@@ -27,6 +27,8 @@ export const BLOCKING_REASON_CODES = [
     "context_budget_exceeded",
     "stage_not_in_process",
     "migration_required",
+    "worktrees_leaked",
+    "orchestration_not_executed",
 ];
 function command(commandText) {
     return { kind: "command", command: commandText };
@@ -160,6 +162,16 @@ export const BLOCKING_REASON_INVENTORY = {
         description: "Legacy pre-ownership state detected; review the migration plan before continuing.",
         continuation: () => command("aiw migrate --dry-run"),
     },
+    worktrees_leaked: {
+        code: "worktrees_leaked",
+        description: "Managed orchestration worktrees remain on disk after their plan finished; clean them up.",
+        continuation: () => action("Run `aiw orchestrate --cleanup --execute` to remove them."),
+    },
+    orchestration_not_executed: {
+        code: "orchestration_not_executed",
+        description: "The plan has not been executed yet; there is no checkpoint to integrate.",
+        continuation: () => action("Run `aiw orchestrate --plan=<path> --execute` first; integration forecasts need the checkpoint evidence."),
+    },
 };
 export function getBlockingReasonDefinition(code) {
     const definition = BLOCKING_REASON_INVENTORY[code];

package/dist/orchestration.d.ts

@@ -21,6 +21,9 @@ export type OrchestrationTaskResult = {
     worktree?: string;
     baseCommit?: string;
     finalCommit?: string;
+    /** OPP-017 execution evidence. */
+    durationMs?: number;
+    diffStat?: string;
 };
 export type IsolationOptions = {
     /** Repository root the plan runs in. */
@@ -41,6 +44,23 @@ export declare function createTaskWorktrees(root: string, aiw: string, plan: Orc
 }>;
 /** Final commit recorded from an isolated worktree (evidence for the checkpoint). */
 export declare function worktreeFinalCommit(worktree: string): string | undefined;
+/**
+ * OPP-017 integration forecast: wave-ordered merge preview for the isolated
+ * task branches against the current branch. Deterministic `git merge-tree`
+ * dry runs — nothing is merged. Conflicts surface per task before any human
+ * merge is attempted.
+ */
+export type IntegrationForecastLine = {
+    wave: number;
+    taskId: string;
+    branch: string;
+    state: "clean" | "conflict" | "missing" | "identical";
+    conflicts?: string[];
+};
+export declare function currentBranch(root: string): string;
+export declare function forecastIntegration(root: string, plan: OrchestrationPlan, results: OrchestrationTaskResult[]): IntegrationForecastLine[];
+/** Parse a serialized orchestration checkpoint back into task results. */
+export declare function parseOrchestrationResults(content: string): OrchestrationTaskResult[];
 /** Remove isolated worktrees; failed-task worktrees are kept unless forced. */
 export declare function removeWorktrees(root: string, paths: Iterable<string>, options?: {
     force?: boolean;
@@ -64,4 +84,4 @@ export declare function executeOrchestrationPlan(plan: OrchestrationPlan, orches
 }): Promise<OrchestrationTaskResult[]>;
 export declare function validateOrchestrationParallelism(value: number): number;
 export declare function serializeOrchestrationPreview(plan: OrchestrationPlan): string;
-export declare function serializeOrchestrationResults(plan: OrchestrationPlan, results: OrchestrationTaskResult[]): string;
+export declare function serializeOrchestrationResults(plan: OrchestrationPlan, results: OrchestrationTaskResult[], wallClockMs?: number): string;

package/dist/orchestration.js

@@ -35,6 +35,110 @@ export function worktreeFinalCommit(worktree) {
         return undefined;
     }
 }
+function gitDiffStat(root, worktree, base, final) {
+    try {
+        return execFileSync("git", ["-C", worktree, "diff", "--stat", `${base}..${final}`], {
+            cwd: root,
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function boundedDiffStat(stat) {
+    if (!stat)
+        return undefined;
+    const lines = stat.split("\n");
+    const bounded = lines.slice(0, 20).join("\n");
+    return lines.length > 20 ? `${bounded}\n(truncated)` : bounded;
+}
+export function currentBranch(root) {
+    return git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+}
+export function forecastIntegration(root, plan, results) {
+    const waves = orchestrationWaves(plan);
+    const byId = new Map(results.map((result) => [result.id, result]));
+    const target = currentBranch(root);
+    const lines = [];
+    waves.forEach((wave, index) => {
+        for (const taskId of wave) {
+            const branch = `aiw/${plan.id}/${taskId}`;
+            let branchTip;
+            try {
+                branchTip = git(root, ["rev-parse", "--verify", branch]);
+            }
+            catch {
+                lines.push({ wave: index + 1, taskId, branch, state: "missing" });
+                continue;
+            }
+            const result = byId.get(taskId);
+            if (result?.finalCommit && result.finalCommit === branchTip) {
+                // nothing new on the branch beyond the recorded final commit
+            }
+            let output;
+            let conflict = false;
+            try {
+                output = execFileSync("git", ["merge-tree", "--write-tree", "--name-only", target, branchTip], { cwd: root, encoding: "utf8" });
+            }
+            catch (error) {
+                conflict = true;
+                output =
+                    error instanceof Error && "stdout" in error
+                        ? String(error.stdout ?? "")
+                        : "";
+            }
+            if (conflict) {
+                const conflictFiles = output
+                    .split("\n")
+                    .filter((line) => line.length > 0 && !line.startsWith("^[0-9a-f]"))
+                    .filter((line) => !/^[0-9a-f]{40}$/.test(line.trim()))
+                    .slice(0, 5);
+                lines.push({
+                    wave: index + 1,
+                    taskId,
+                    branch,
+                    state: "conflict",
+                    conflicts: conflictFiles.length > 0 ? conflictFiles : ["merge conflicts detected"],
+                });
+                continue;
+            }
+            const mergedTree = output.split("\n")[0]?.trim();
+            const identical = mergedTree === git(root, ["rev-parse", target + "^{tree}"]);
+            lines.push({
+                wave: index + 1,
+                taskId,
+                branch,
+                state: identical ? "identical" : "clean",
+            });
+        }
+    });
+    return lines;
+}
+/** Parse a serialized orchestration checkpoint back into task results. */
+export function parseOrchestrationResults(content) {
+    const results = [];
+    const blocks = content.split(/\n(?= {2}- id: )/);
+    for (const block of blocks) {
+        const id = /^ {2}- id: (.+)$/m.exec(block)?.[1];
+        if (!id)
+            continue;
+        const status = /^ {4}status: (.+)$/m.exec(block)?.[1];
+        const detail = /^ {4}detail: (.+)$/m.exec(block)?.[1];
+        const worktree = /^ {4}worktree: "?([^"\n]+)"?$/m.exec(block)?.[1];
+        const baseCommit = /^ {4}baseCommit: "?([^"\n]+)"?$/m.exec(block)?.[1];
+        const finalCommit = /^ {4}finalCommit: "?([^"\n]+)"?$/m.exec(block)?.[1];
+        results.push({
+            id,
+            status: status ?? "blocked",
+            detail: detail?.replace(/^"|"$/g, "") ?? "",
+            ...(worktree ? { worktree } : {}),
+            ...(baseCommit ? { baseCommit } : {}),
+            ...(finalCommit ? { finalCommit } : {}),
+        });
+    }
+    return results;
+}
 /** Remove isolated worktrees; failed-task worktrees are kept unless forced. */
 export function removeWorktrees(root, paths, options = {}) {
     for (const path of paths) {
@@ -139,19 +243,26 @@ export async function executeOrchestrationPlan(plan, orchestrator, maxParallel,
                     results.set(id, { id, status: "blocked", detail: "A dependency did not pass." });
                     return;
                 }
+                const startedAt = Date.now();
                 try {
                     const isolated = isolation?.worktrees.get(id);
                     const outcome = await orchestrator.run(isolated ? { ...task, worktree: isolated.worktree } : task);
                     const base = isolation?.worktrees.get(id);
+                    const finalCommit = base ? worktreeFinalCommit(base.worktree) : undefined;
+                    const diffStat = base && finalCommit
+                        ? boundedDiffStat(gitDiffStat(isolation.options.root, base.worktree, base.baseCommit, finalCommit))
+                        : undefined;
                     results.set(id, {
                         id,
                         status: outcome.success ? "passed" : "failed",
                         detail: safeDetail(outcome.detail),
+                        durationMs: Date.now() - startedAt,
                         ...(base
                             ? {
                                 worktree: base.worktree,
                                 baseCommit: base.baseCommit,
-                                finalCommit: worktreeFinalCommit(base.worktree),
+                                finalCommit,
+                                ...(diffStat ? { diffStat } : {}),
                             }
                             : {}),
                     });
@@ -178,15 +289,17 @@ export function serializeOrchestrationPreview(plan) {
         .map((wave, index) => `  - index: ${index + 1}\n    tasks: [${wave.join(", ")}]`)
         .join("\n")}\n`;
 }
-export function serializeOrchestrationResults(plan, results) {
+export function serializeOrchestrationResults(plan, results, wallClockMs) {
     return `schema: 1\nplan: ${plan.id}\nresults:\n${results
         .map((result) => {
         const isolation = result.worktree
-            ? `\n    worktree: ${JSON.stringify(result.worktree)}\n    baseCommit: ${JSON.stringify(result.baseCommit ?? "")}\n    finalCommit: ${JSON.stringify(result.finalCommit ?? "")}`
-            : "";
+            ? `\n    worktree: ${JSON.stringify(result.worktree)}\n    baseCommit: ${JSON.stringify(result.baseCommit ?? "")}\n    finalCommit: ${JSON.stringify(result.finalCommit ?? "")}${result.durationMs !== undefined ? `\n    durationMs: ${result.durationMs}` : ""}${result.diffStat ? `\n    diffStat: ${JSON.stringify(result.diffStat)}` : ""}`
+            : result.durationMs !== undefined
+                ? `\n    durationMs: ${result.durationMs}`
+                : "";
         return `  - id: ${result.id}\n    status: ${result.status}\n    detail: ${JSON.stringify(result.detail)}${isolation}`;
     })
-        .join("\n")}\n`;
+        .join("\n")}${wallClockMs !== undefined ? `\nwallClockMs: ${wallClockMs}` : ""}\n`;
 }
 function assertPlanGraph(tasks) {
     const ids = tasks.map(({ id }) => id);

package/dist/workflow.js

@@ -89,7 +89,7 @@ import { parsePrivateRegistries, parseTeamPreset, serializePrivateRegistries, se
 import { enforcePolicyGate, gitPolicyTracking } from "./policy-gate.js";
 import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, offerTelemetryConsent, parseTelemetryConfig, purgeTelemetryBuffer, readTelemetryBuffer, serializeTelemetryMapping, TELEMETRY_BUFFER_CAP, TELEMETRY_BUFFER_FILE, } from "./telemetry.js";
 import { createPluginScaffold, validatePluginDirectory, writePluginScaffold, } from "./plugin-sdk.js";
-import { createTaskWorktrees, executeOrchestrationPlan, listManagedWorktrees, removeWorktrees, parseOrchestrationPlan, serializeOrchestrationPreview, serializeOrchestrationResults, validateOrchestrationParallelism, } from "./orchestration.js";
+import { createTaskWorktrees, executeOrchestrationPlan, forecastIntegration, listManagedWorktrees, currentBranch, parseOrchestrationResults, removeWorktrees, parseOrchestrationPlan, serializeOrchestrationPreview, serializeOrchestrationResults, validateOrchestrationParallelism, } from "./orchestration.js";
 function laneAdvisory(root, fs, lightChosen) {
     const paths = collectWorkingTreeChanges(root);
     if (!paths || paths.length === 0)
@@ -560,6 +560,37 @@ export async function runCommand(args, root, fs, services = {}) {
                     error: "Usage: aiw orchestrate --plan=path [--execute] [--isolate] [--cleanup] [--max-parallel=number]",
                 };
             const execute = executeCount === 1;
+            const integrateRequested = args[1] === "integrate";
+            if (integrateRequested) {
+                const integrateParsed = parseNamedOptions(args.slice(2), ["plan"]);
+                if (!integrateParsed?.plan)
+                    return { exitCode: 1, error: "Usage: aiw orchestrate integrate --plan=path" };
+                const planPath = safeProjectFile(root, integrateParsed.plan, fs);
+                const plan = parseOrchestrationPlan(fs.read(planPath));
+                const checkpoint = join(aiw, `checkpoints/orchestration-${plan.id}.yml`);
+                if (!fs.exists(checkpoint))
+                    throw new BlockingError(describeBlockingReason("orchestration_not_executed", {
+                        detail: `No checkpoint for plan ${plan.id} — the plan has not been executed yet.`,
+                    }));
+                const results = parseOrchestrationResults(fs.read(checkpoint));
+                const forecast = forecastIntegration(root, plan, results);
+                const lines = [`Integration forecast for plan ${plan.id} → ${currentBranch(root)}`];
+                let conflicts = 0;
+                for (const line of forecast) {
+                    if (line.state === "conflict")
+                        conflicts += 1;
+                    lines.push(line.state === "conflict"
+                        ? `wave ${line.wave} · ${line.taskId} (${line.branch}): CONFLICTS — ${(line.conflicts ?? []).join(", ")}`
+                        : line.state === "missing"
+                            ? `wave ${line.wave} · ${line.taskId}: branch missing (${line.branch})`
+                            : line.state === "identical"
+                                ? `wave ${line.wave} · ${line.taskId}: already integrated`
+                                : `wave ${line.wave} · ${line.taskId} (${line.branch}): clean merge`);
+                }
+                lines.push(`conflicts: ${conflicts}`);
+                const output = lines.join("\n");
+                return conflicts > 0 ? { exitCode: 1, output, error: undefined } : { exitCode: 0, output };
+            }
             const isolate = args.includes("--isolate");
             const cleanup = args.includes("--cleanup");
             if (cleanup) {
@@ -599,6 +630,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     exitCode: 1,
                     error: `Orchestration checkpoint already exists; use a new plan id: ${checkpoint}`,
                 };
+            const wallClockStart = Date.now();
             try {
                 const isolation = isolate
                     ? {
@@ -613,7 +645,7 @@ export async function runCommand(args, root, fs, services = {}) {
                         .map(({ worktree }) => worktree);
                     removeWorktrees(root, passedPaths);
                 }
-                fs.write(checkpoint, serializeOrchestrationResults(plan, results));
+                fs.write(checkpoint, serializeOrchestrationResults(plan, results, Date.now() - wallClockStart));
                 const failed = results.filter(({ status }) => status !== "passed");
                 return failed.length
                     ? {
@@ -1832,6 +1864,14 @@ export async function runCommand(args, root, fs, services = {}) {
                     };
                 return { exitCode: 1, error: `Missing AI Workflow files: ${missing.join(", ")}` };
             }
+            const leakedWorktrees = listManagedWorktrees(root, aiw);
+            if (leakedWorktrees.length > 0)
+                return {
+                    exitCode: 1,
+                    error: formatBlockingOutput(describeBlockingReason("worktrees_leaked", {
+                        detail: `${leakedWorktrees.length} managed orchestration worktree(s) leaked: ${leakedWorktrees.join(", ")}`,
+                    })),
+                };
             try {
                 parseManifest(fs.read(join(aiw, "manifest.yml")));
                 parseOwnership(fs.read(join(aiw, "ownership.yml")));

package/docs/backlog.md

@@ -129,7 +129,7 @@ Derived from the Gentle-AI ODD/RDD analysis; scope and rejected alternatives rec
 - [x] **OPP-014** Paired Verification Contract — plan declares `command → expected`, evidence records `command → observed`, gates compare pairs. _Acceptance:_ see [OPP-014](../opportunities/OPP-014-paired-verification-contract.md); mismatch/missing pairs fail with typed reasons and machine-readable task ids; gates never execute commands; legacy format accepted with advisory.
 - [x] **OPP-015** Token & Recovery Governance — enforced stage budgets, context-recovery managed block, advisory lane suggestion, regression-pinning declaration. _Acceptance:_ see [OPP-015](../opportunities/OPP-015-token-recovery-governance.md); budgets derive from saved baselines and default-inert; recovery block in every adapter rendering; advisory line never blocks.
 - [ ] **OPP-016** Behavioral evaluation phase 2 — scenario registry replayed against real harness CLIs. _Acceptance:_ see [OPP-016](../opportunities/OPP-016-behavioral-eval-scenarios.md); deterministic state-outcome assertions, skipped-harness markers, advisory-first before gates, usage recorded per run.
-- [ ] **OPP-017** Orchestration depth — integration forecast, doctor leak reporting, diff-stat evidence, per-harness honor matrix. _Acceptance:_ see [OPP-017](../opportunities/OPP-017-orchestration-depth.md); wave-ordered merge forecast with merge-tree dry run, typed cleanup continuation from doctor, no auto-merge.
+- [x] **OPP-017** Orchestration depth — integration forecast, doctor leak reporting, diff-stat evidence, per-harness honor matrix. _Acceptance:_ see [OPP-017](../opportunities/OPP-017-orchestration-depth.md); wave-ordered merge forecast with merge-tree dry run, typed cleanup continuation from doctor, no auto-merge.
 - [x] **OPP-018** Supported migration path for legacy (pre-ownership) installations. _Acceptance:_ see [OPP-018](../opportunities/OPP-018-legacy-migration.md); dry-run lists archived/rebuilt/preserved/manual, transactional apply with rollback, fail-closed on ambiguity, doctor/install point at `aiw migrate`.
 
 ## Backlog rules

package/docs/continuation-inventory.md

@@ -27,3 +27,5 @@ Every blocking `aiw` exit carries a stable reason code plus either an exact runn
 | `context_budget_exceeded`       | The served context exceeds the declared ceiling for this stage; trim it or raise the ceiling explicitly. | explicit action  |
 | `stage_not_in_process`          | This stage does not exist in the active workflow's process; use the process's own stages.                | explicit action  |
 | `migration_required`            | Legacy pre-ownership state detected; review the migration plan before continuing.                        | runnable command |
+| `worktrees_leaked`              | Managed orchestration worktrees remain on disk after their plan finished; clean them up.                 | explicit action  |
+| `orchestration_not_executed`    | The plan has not been executed yet; there is no checkpoint to integrate.                                 | explicit action  |

package/docs/opportunities/OPP-017-orchestration-depth.md

@@ -1,6 +1,6 @@
 # OPP-017: Orchestration depth — integration tooling, leak reporting, per-harness guidance
 
-- Status: Proposed
+- Status: Implemented (2026-11-04): integration forecast, doctor leak reporting, diff-stat and wall-clock evidence, honor matrix documented; parallel-execution harness parity tests remain an open question
 - Priority: P2
 - Added: 2026-11-01
 - Decision: extends [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) Decision A

package/docs/orchestration.md

@@ -35,6 +35,22 @@ The first command prints deterministic execution waves and does not invoke an ag
 
 Each executed plan writes one `.aiw/checkpoints/orchestration-<plan-id>.yml` result. Existing checkpoints are never overwritten: use a new plan identifier for a new run. Agent result details are bounded and serialized safely.
 
+## Isolation and integration (OPP-010/OPP-017)
+
+`aiw orchestrate --plan=plan.yml --execute --isolate` creates one branch-per-task git worktree (`aiw/<plan>/<task>` from the plan HEAD) and hands the path to the adapter through the optional `worktree` field on the orchestration task. Passed-task worktrees are removed after evidence capture; failed-task worktrees are kept for diagnosis. Checkpoints record per-task worktree path, base commit, final commit, diff stat, and duration, plus the plan's wall-clock time.
+
+`aiw orchestrate integrate --plan=plan.yml` prints the wave-ordered integration forecast for the task branches: a deterministic `git merge-tree` dry run against the current branch, reporting conflicts per task before any human merge. Conflicts make the command exit nonzero; nothing is ever merged by the tool. `aiw orchestrate --cleanup --execute` removes managed worktrees left by crashed runs, and `aiw doctor` reports leaks with the cleanup continuation.
+
+### Worktree honor matrix
+
+The adapter contract owns process execution; aiw owns git isolation. What each documented integration does with `task.worktree`:
+
+| Integration                                                  | Honor                                                                                                   | Notes                                                                                        |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Host-integrated adapters (in-process)                        | Receives the path; runs the task with the worktree as its working directory or fails with a typed error | The minimal adapter contract: never run against the main tree when a worktree is provided    |
+| Claude Code / Codex / Gemini CLIs launched by a host adapter | Honored by passing the worktree as the session working directory                                        | Harness-native worktree features may substitute; the checkpoint evidence stays authoritative |
+| Adapters without worktree support                            | Must reject `--isolate` before any task runs                                                            | The plan fails before execution rather than silently running in the main tree                |
+
 ## Adapter contract
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {