@multileaf/ai-workflow 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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
+
+- `aiw migrate [--dry-run|--rollback]` (OPP-018): supported migration path for legacy pre-ownership installations — snapshots everything touched under `.aiw/checkpoints/migration-<ts>/original/` for atomic rollback, rebuilds the ownership inventory with drift-safe checksum semantics (diverging legacy files are preserved by sync as conflicts for manual review, never silently overwritten), normalizes legacy manifests to the modern artifact-language policy, and writes a migration report. Doctor and install detect the legacy signature (`migration_required` typed reason) and point at the command; ambiguous entries fail closed as manual actions.
+- `docs/release-process.md` now documents the working release chain (Auto-tag → reusable-workflow Release call; npm environment trusting `v*.*.*` tags and `main`).
+
 ## [0.12.0] - 2026-11-01
 
 ### 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"];
+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

@@ -26,6 +26,9 @@ export const BLOCKING_REASON_CODES = [
     "state_mismatch",
     "context_budget_exceeded",
     "stage_not_in_process",
+    "migration_required",
+    "worktrees_leaked",
+    "orchestration_not_executed",
 ];
 function command(commandText) {
     return { kind: "command", command: commandText };
@@ -154,6 +157,21 @@ export const BLOCKING_REASON_INVENTORY = {
         description: "This stage does not exist in the active workflow's process; use the process's own stages.",
         continuation: () => action("Run `aiw task status` to see the stages this process defines, or start the workflow with `--process=feature` when the staged specification sequence is what the work needs."),
     },
+    migration_required: {
+        code: "migration_required",
+        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/legacy-migration.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OPP-018: supported migration path for legacy (pre-ownership) installations.
+ *
+ * Installations older than the ownership inventory (~≤0.9.x) entered a closed
+ * loop: install preserves, uninstall refuses (ownership unverifiable), repair
+ * ignores, sync demands ownership. `aiw migrate` breaks the loop with a
+ * transactional, rollback-protected move to the modern state — archival never
+ * deletes, ambiguity fails closed, and user configuration stays byte-identical.
+ */
+import { createOwnedFile } from "./ownership.js";
+import type { FileSystem } from "./types.js";
+export declare function detectLegacyState(aiw: string, fs: FileSystem): boolean;
+export type MigrationPlan = {
+    archived: string[];
+    preserved: string[];
+    rebuilt: string[];
+    /** Managed files that differ from shipped content — preserved as sync conflicts for manual review. */
+    userModified: string[];
+    manualActions: string[];
+    rollbackSnapshot: string;
+};
+/**
+ * Classify the legacy layout. Managed candidates recorded in the rebuilt
+ * ownership inventory with their CURRENT disk content — sync then treats stale
+ * resources as safe updates, and anything that diverges from the shipped
+ * content is reported for manual review instead of being silently overwritten.
+ */
+export declare function planLegacyMigration(root: string, aiw: string, fs: FileSystem, managedCandidates: {
+    path: string;
+    bundled?: string;
+}[], now?: string): MigrationPlan;
+export type ManagedCandidate = {
+    /** Absolute path of the managed candidate file. */
+    path: string;
+    /** Current shipped content when identifiable; checksum semantics depend on it:
+     *  disk == bundled → owned as disk (sync may update safely);
+     *  disk != bundled → owned as bundled (sync preserves as a conflict for
+     *  manual review — legacy-user-modified, never silently overwritten). */
+    bundled?: string;
+    metadata?: Parameters<typeof createOwnedFile>[2];
+};
+/** Apply the migration: snapshot, archive superseded files, rebuild ownership. */
+export declare function applyMigration(root: string, aiw: string, fs: FileSystem, managedCandidates: ManagedCandidate[], plan: MigrationPlan): void;
+/** Restore the latest migration snapshot atomically. */
+export declare function rollbackMigration(root: string, aiw: string, fs: FileSystem): string;

package/dist/legacy-migration.js

@@ -0,0 +1,175 @@
+/**
+ * OPP-018: supported migration path for legacy (pre-ownership) installations.
+ *
+ * Installations older than the ownership inventory (~≤0.9.x) entered a closed
+ * loop: install preserves, uninstall refuses (ownership unverifiable), repair
+ * ignores, sync demands ownership. `aiw migrate` breaks the loop with a
+ * transactional, rollback-protected move to the modern state — archival never
+ * deletes, ambiguity fails closed, and user configuration stays byte-identical.
+ */
+import { join } from "node:path";
+import { createOwnedFile, serializeOwnership } from "./ownership.js";
+// lock.yml and recommendations.yml are LIVE files: their owning commands
+// (`aiw recommend`, `aiw skills install`, `aiw sync`) rewrite them in the
+// modern format, so migration leaves them in place rather than archiving.
+const SUPERSEDED_FILES = [];
+const PRESERVED_CONFIG = [
+    "decision.yml",
+    "semantic.yml",
+    "organization.yml",
+    "heartbeats.yml",
+    "settings.yml",
+    "usage.yml",
+    "profile.yml",
+];
+const PRESERVED_DIRECTORIES = ["checkpoints", "generated", "context", "semantic", "resources"];
+export function detectLegacyState(aiw, fs) {
+    return (fs.exists(join(aiw, "manifest.yml")) &&
+        fs.exists(join(aiw, "lock.yml")) &&
+        !fs.exists(join(aiw, "ownership.yml")));
+}
+function listEntries(fs, directory) {
+    return fs.list?.(directory) ?? [];
+}
+/**
+ * Classify the legacy layout. Managed candidates recorded in the rebuilt
+ * ownership inventory with their CURRENT disk content — sync then treats stale
+ * resources as safe updates, and anything that diverges from the shipped
+ * content is reported for manual review instead of being silently overwritten.
+ */
+export function planLegacyMigration(root, aiw, fs, managedCandidates, now = new Date().toISOString()) {
+    const archived = SUPERSEDED_FILES.filter((name) => fs.exists(join(aiw, name))).map((name) => `.aiw/${name}`);
+    const preserved = PRESERVED_CONFIG.filter((name) => fs.exists(join(aiw, name))).map((name) => `.aiw/${name}`);
+    for (const directory of PRESERVED_DIRECTORIES) {
+        if (fs.pathType?.(join(aiw, directory)) === "directory") {
+            preserved.push(`.aiw/${directory}/`);
+        }
+    }
+    const known = new Set([
+        "manifest.yml",
+        "ownership.yml",
+        "migration-report.yml",
+        "lock.yml",
+        "recommendations.yml",
+        ...PRESERVED_CONFIG,
+        ...PRESERVED_DIRECTORIES.map((directory) => `${directory}/`),
+    ]);
+    const manualActions = [];
+    for (const entry of listEntries(fs, aiw)) {
+        const isDirectory = fs.pathType?.(join(aiw, entry)) === "directory";
+        const key = isDirectory ? `${entry}/` : entry;
+        if (!known.has(key))
+            manualActions.push(`.aiw/${key} — unrecognized legacy entry; classify or remove manually`);
+    }
+    const rebuilt = [];
+    const userModified = [];
+    const rollbackSnapshot = join(aiw, "checkpoints", `migration-${now.replace(/[:.]/g, "-")}`);
+    for (const candidate of managedCandidates) {
+        const relativePath = candidate.path.startsWith(`${root}/`)
+            ? candidate.path.slice(root.length + 1)
+            : candidate.path;
+        if (!fs.exists(candidate.path))
+            continue;
+        rebuilt.push(relativePath);
+        if (candidate.bundled !== undefined && fs.read(candidate.path) !== candidate.bundled) {
+            userModified.push(`${relativePath} — legacy-user-modified (differs from shipped content); sync will preserve it as a conflict for manual review`);
+        }
+    }
+    return {
+        archived,
+        preserved,
+        rebuilt,
+        userModified,
+        manualActions,
+        rollbackSnapshot,
+    };
+}
+/** Apply the migration: snapshot, archive superseded files, rebuild ownership. */
+export function applyMigration(root, aiw, fs, managedCandidates, plan) {
+    if (plan.manualActions.length > 0)
+        throw new Error(`Migration requires manual action first: ${plan.manualActions.join("; ")}`);
+    // Transactional snapshot of everything the migration touches.
+    const snapshot = plan.rollbackSnapshot;
+    fs.mkdir(snapshot);
+    fs.mkdir(join(snapshot, "original"));
+    for (const name of PRESERVED_CONFIG) {
+        const path = join(aiw, name);
+        if (fs.exists(path))
+            fs.write(join(snapshot, "original", name), fs.read(path));
+    }
+    const ownershipEntries = [];
+    for (const candidate of managedCandidates) {
+        if (!fs.exists(candidate.path))
+            continue;
+        const relativePath = candidate.path.startsWith(`${root}/`)
+            ? candidate.path.slice(root.length + 1)
+            : candidate.path;
+        const disk = fs.read(candidate.path);
+        fs.write(join(snapshot, "original", candidate.path), disk);
+        const ownedContent = candidate.bundled !== undefined && disk !== candidate.bundled ? candidate.bundled : disk;
+        ownershipEntries.push(createOwnedFile(relativePath, ownedContent, candidate.metadata));
+    }
+    for (const name of SUPERSEDED_FILES) {
+        const path = join(aiw, name);
+        if (fs.exists(path)) {
+            fs.write(join(snapshot, "original", name), fs.read(path));
+            fs.remove?.(path);
+        }
+    }
+    fs.write(join(aiw, "ownership.yml"), serializeOwnership(ownershipEntries));
+    // Normalize legacy manifests: the modern doctor requires the English
+    // artifact-language policy, which ancient manifests never carried.
+    const manifestPath = join(aiw, "manifest.yml");
+    if (fs.exists(manifestPath)) {
+        const manifest = fs.read(manifestPath);
+        if (!manifest.includes("artifact_language")) {
+            fs.write(manifestPath, `${manifest.replace(/\n*$/, "")}\npolicies:\n  artifact_language: en\n`);
+        }
+    }
+    fs.write(join(aiw, "migration-report.yml"), [
+        "schema: 1",
+        `archived: [${plan.archived.map((entry) => JSON.stringify(entry)).join(", ")}]`,
+        `preserved: [${plan.preserved.map((entry) => JSON.stringify(entry)).join(", ")}]`,
+        `rebuilt: [${plan.rebuilt.map((entry) => JSON.stringify(entry)).join(", ")}]`,
+        `manualActions: [${plan.manualActions.map((entry) => JSON.stringify(entry)).join(", ")}]`,
+        `userModified: [${plan.userModified.map((entry) => JSON.stringify(entry)).join(", ")}]`,
+        `rollbackSnapshot: ${JSON.stringify(snapshot)}`,
+        "",
+    ].join("\n"));
+}
+/** Restore the latest migration snapshot atomically. */
+export function rollbackMigration(root, aiw, fs) {
+    const base = join(aiw, "checkpoints");
+    const snapshots = (fs.list?.(base) ?? [])
+        .filter((entry) => entry.startsWith("migration-"))
+        .sort()
+        .reverse();
+    if (snapshots.length === 0)
+        throw new Error("No migration snapshot found; nothing to roll back.");
+    const snapshot = join(base, snapshots[0], "original");
+    // Remove files the migration itself created (the snapshot originals never
+    // contained them): ownership + report. Unwinding a later sync is out of scope.
+    fs.remove?.(join(aiw, "ownership.yml"));
+    fs.remove?.(join(aiw, "migration-report.yml"));
+    for (const entry of listEntries(fs, snapshot)) {
+        const source = join(snapshot, entry);
+        if (fs.pathType?.(source) === "directory") {
+            copyDirectory(fs, source, join(aiw, entry));
+        }
+        else {
+            fs.write(join(aiw, entry), fs.read(source));
+        }
+    }
+    return join(base, snapshots[0]);
+}
+function copyDirectory(fs, source, target) {
+    fs.mkdir(target);
+    for (const entry of listEntries(fs, source)) {
+        const sourcePath = join(source, entry);
+        const targetPath = join(target, entry);
+        if (fs.pathType?.(sourcePath) === "directory")
+            copyDirectory(fs, sourcePath, targetPath);
+        else
+            fs.write(targetPath, fs.read(sourcePath));
+    }
+}

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

@@ -67,6 +67,7 @@ import { buildTraceabilityGraph, serializeTraceabilityGraph } from "./traceabili
 import { evaluateQualityGate } from "./quality-gates.js";
 import { BlockingError, blockingResultToJson, describeBlockingReason, formatBlockingOutput, } from "./blocking-reasons.js";
 import { assessRisk, collectWorkingTreeChanges, hasCoveringTest, runRiskAssess, } from "./risk-assess.js";
+import { applyMigration, detectLegacyState, planLegacyMigration, rollbackMigration, } from "./legacy-migration.js";
 import { extractStandards, parseStandardsIndex } from "./standards.js";
 import { digestPath, digestFreshness, extractDigest, formatDigestLine, serializeDigest, } from "./digest.js";
 function installationRequired() {
@@ -88,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)
@@ -559,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) {
@@ -598,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
                     ? {
@@ -612,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
                     ? {
@@ -636,9 +669,12 @@ export async function runCommand(args, root, fs, services = {}) {
             if (fs.pathType?.(manifestPath) === "file") {
                 const manifest = fs.read(manifestPath);
                 const active = manifest.match(/^\s*active:\s*(.+)$/m)?.[1]?.trim() ?? "unknown";
+                const legacyHint = detectLegacyState(aiw, fs)
+                    ? "\nLegacy pre-ownership state detected. Run `aiw migrate --dry-run` to review, then `aiw migrate` to upgrade to the current state layout."
+                    : "";
                 return {
                     exitCode: 0,
-                    output: `AI Workflow is already installed for target: ${active}. Existing state preserved.`,
+                    output: `AI Workflow is already installed for target: ${active}. Existing state preserved.${legacyHint}`,
                 };
             }
             const aiInitPath = join(root, renderAiInitPath(target));
@@ -1818,8 +1854,24 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "doctor") {
             const required = ["manifest.yml", "profile.yml", "lock.yml", "ownership.yml"];
             const missing = required.filter((file) => !fs.exists(join(aiw, file)));
-            if (missing.length)
+            if (missing.length) {
+                if (detectLegacyState(aiw, fs))
+                    return {
+                        exitCode: 1,
+                        error: formatBlockingOutput(describeBlockingReason("migration_required", {
+                            detail: "Legacy pre-ownership state detected; review the migration plan first.",
+                        })) + "\nNext: run `aiw migrate --dry-run`, then `aiw migrate`.",
+                    };
                 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")));
@@ -2141,6 +2193,70 @@ export async function runCommand(args, root, fs, services = {}) {
                 error: "Usage: aiw standards <extract|list|confirm|reject> [topic] — standards are inferred until a human confirms them.",
             };
         }
+        if (command === "migrate") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return installationRequired();
+            const dry = args.includes("--dry-run");
+            const doRollback = args.includes("--rollback");
+            if (doRollback) {
+                const restored = rollbackMigration(root, aiw, fs);
+                return { exitCode: 0, output: `Legacy state restored from snapshot: ${restored}` };
+            }
+            if (!detectLegacyState(aiw, fs))
+                return {
+                    exitCode: 0,
+                    output: "Nothing to migrate: state already includes the ownership inventory.",
+                };
+            const manifestPath = join(aiw, "manifest.yml");
+            const manifestTarget = /^\s*active:\s*(.+)$/m.exec(fs.read(manifestPath))?.[1]?.trim() ||
+                detectTarget(root, fs) ||
+                "codex";
+            if (!isTarget(manifestTarget))
+                throw new Error(`Unsupported target: ${manifestTarget}`);
+            const managedCandidates = [];
+            for (const resource of loadBundledResources(manifestTarget)) {
+                managedCandidates.push({
+                    path: join(root, renderResourcePath(manifestTarget, resource.type, resource.id)),
+                    bundled: resource.content,
+                    metadata: {
+                        target: manifestTarget,
+                        resourceType: resource.type,
+                        resourceId: resource.id,
+                        kind: "target-resource",
+                    },
+                });
+            }
+            managedCandidates.push({
+                path: join(root, describeResource(manifestTarget, "context", "project").path),
+                metadata: {
+                    target: manifestTarget,
+                    resourceType: "context",
+                    resourceId: "project",
+                    kind: "target-resource",
+                },
+            });
+            const plan = planLegacyMigration(root, aiw, fs, managedCandidates);
+            const report = [
+                `Target: ${manifestTarget}`,
+                plan.archived.length
+                    ? `Archived (superseded machine state): ${plan.archived.join(", ")}`
+                    : "",
+                plan.preserved.length ? `Preserved byte-identical: ${plan.preserved.join(", ")}` : "",
+                `Rebuilt: ownership inventory (${plan.rebuilt.length} managed paths)`,
+                ...plan.userModified.map((entry) => `Legacy-user-modified (sync preserves for review): ${entry}`),
+                ...plan.manualActions.map((entry) => `MANUAL ACTION REQUIRED: ${entry}`),
+                dry ? "Mode: dry-run — nothing written." : `Rollback snapshot: ${plan.rollbackSnapshot}`,
+            ].filter((line) => line.length > 0);
+            if (dry)
+                return { exitCode: 0, output: ["Migration plan (dry-run):", ...report].join("\n") };
+            try {
+                applyMigration(root, aiw, fs, managedCandidates, plan);
+            }
+            catch (error) {
+                return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
+            }
+            return { exitCode: 0, output: ["Migration complete.", ...report].join("\n") };
+        }
         if (command === "digest") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return installationRequired();

package/docs/backlog.md

@@ -128,6 +128,9 @@ Derived from the Gentle-AI ODD/RDD analysis; scope and rejected alternatives rec
 - [x] **OPP-013** Read-Optimized Artifacts — fingerprint-bound digest layer so downstream stages read digests instead of re-reading full artifacts. _Acceptance:_ see [OPP-013](../opportunities/OPP-013-read-optimized-artifacts-digest-layer.md); digests extracted deterministically at approval, stale-safe (fail toward full read), ≥60% reduction in recorded full-artifact reads, no model-generated summaries.
 - [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.
+- [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

@@ -26,3 +26,6 @@ Every blocking `aiw` exit carries a stable reason code plus either an exact runn
 | `state_mismatch`                | AI Workflow state files are inconsistent with each other; run diagnostics to inspect and repair.         | runnable command |
 | `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-016-behavioral-eval-scenarios.md

@@ -0,0 +1,44 @@
+# OPP-016: Behavioral evaluation phase 2 — scenario registry replayed against real harness CLIs
+
+- Status: Proposed
+- Priority: P2
+- Added: 2026-11-01
+- Decision: extends [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) Decision A
+- Source signal: external qualitative assessment scored "Behavioral evaluation 3/5 — deterministic evals; lacks real behavioral validation". Agreed: OPP-011 proves the skills **say** the right things; nothing yet proves agents **do** them.
+
+## Problem
+
+The shipped stage skills carry contract invariants (wait for explicit human reply, gate before approve, reasons required), and OPP-011's harness checks those invariants as text. What remains unvalidated is the behavior that emerges when a real coding agent reads them in a real repository: does the agent actually stop at the approval boundary, or does it proceed? Does a light-lane task really skip durable artifacts? Text invariants cannot answer behavior questions — only replaying scenarios against real harness CLIs can.
+
+## Proposal
+
+1. **Scenario registry**: declarative descriptors (YAML) per scenario — fixture repository state (files, git history), the harness command to run (`claude -p "…"` with `--permission-mode` bounded, `codex exec …`, `gemini -p …`), a bounded prompt driving one workflow action, and the **deterministic expected outcomes**: exit code, `.aiw/` state files (workflow.yml fields, approvals ledger statuses, checkpoint existence), and typed output envelopes (reason codes, digests). No prose assertions — state asserts only.
+2. **Runner**: `aiw eval run --scenarios` executes each scenario in an isolated fixture copy, enforces wall-clock and token-usage ceilings per scenario, and asserts state outcomes exactly as the e2e suite does today. Missing harness CLI → the scenario is **skipped with an explicit marker** in results (never a silent pass). Retry policy: one retry on harness transport failure; a retry-passing scenario is reported as `flaky-suspect`, not green.
+3. **CI shape**: a bounded smoke set (one scenario per stage family) runs on PRs touching `resources/` or templates; the full registry runs nightly. Both are advisory-first (report-only) for two release cycles before becoming gates — behavioral flakiness must be characterized before it can block.
+4. **Determinism floor unchanged**: OPP-011 textual invariants and OPP-006's command ratchet remain the fast deterministic layer; scenarios are the behavioral layer on top.
+
+## Affected areas
+
+- New `src/eval/scenarios.ts` (registry parser, runner, result schema `aiw.scenario-results/v1`)
+- `scenarios/*.yml` (initial registry: approval boundary, light-lane skip, escalation, bugfix process, rejection → re-gate)
+- `.github/workflows/` (nightly behavioral job; advisory mode first)
+- `docs/quality.md`, OPP-011 cross-link
+
+## Acceptance criteria
+
+- Given a scenario run twice on unchanged inputs, when results compare, then outcomes are identical (determinism), with token counts recorded per run via the usage sidecar.
+- Given a harness CLI missing from the machine, when its scenarios are evaluated, then results mark them `skipped-harness-unavailable` and CI does not count them as passing.
+- Given a fixture where the agent must stop at the approval boundary, when the scenario runs, then `.aiw/approvals.yml` shows `pending-human` and no later stage is started; an agent that proceeded fails the scenario.
+- Given two consecutive release cycles, when the advisory period elapses, then at least the approval-boundary scenarios become CI gates (ratchet declared up front).
+- Given no harness installed at all, when `aiw eval run --scenarios` runs, then it exits 0 with every scenario marked skipped and a summary naming what is missing.
+
+## Non-goals
+
+- No LLM-as-judge in CI; no free-form prose assertions; no behavioral guarantees for arbitrary user projects (fixtures only).
+- No long-horizon scenarios (multi-hour sessions) — bounded, single-action scenarios first.
+
+## Open questions
+
+- Which harness CLIs are CI-available vs local-only, and how is availability detected robustly?
+- Token ceiling per scenario run (real harness calls cost money) — pooled nightly budget vs per-scenario?
+- Should scenario fixtures double as documentation examples?

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

@@ -0,0 +1,50 @@
+# OPP-017: Orchestration depth — integration tooling, leak reporting, per-harness guidance
+
+- 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
+- Source signal: external qualitative assessment scored "Multi-agent orchestration 3/5 — scheduler and isolation; runtime delegated to host". Agreed: the delegation is by design, but three concrete pieces of depth on aiw's side of the contract are missing.
+
+## Problem
+
+After OPP-010, isolated execution exists: branch-per-task worktrees, evidence-bound checkpoints, cleanup. What remains missing keeps orchestration at 3/5:
+
+1. **No integration tooling**: after a plan passes, the task branches (`aiw/<plan>/<task>`) sit without guidance — the human must remember merge order (waves) and discover conflicts by trial.
+2. **No leak reporting**: `orchestrate --cleanup` removes managed worktrees, but `aiw doctor` does not report them — leaked worktrees from crashed runs are invisible in diagnostics.
+3. **No per-harness guidance**: whether a given harness integration honors `OrchestrationTask.worktree` is undocumented — teams cannot know before running.
+
+## Proposal
+
+1. **`aiw orchestrate integrate --plan=<id>`** (read-only): prints the merge order derived from the execution waves, and for each task branch runs `git merge-tree` (dry-run) against the target branch, reporting conflicts per task before anything is merged. Merges stay human-executed (delivery boundary unchanged); the command is a conflict _forecast_, not an executor.
+2. **Doctor leak reporting**: doctor gains a managed-worktree check (reuse `listManagedWorktrees`) — leaked worktrees are reported with plan/task attribution and the cleanup continuation (`orchestrate --cleanup --execute`), per the OPP-004 typed-continuation contract.
+3. **Diff-stat evidence**: the checkpoint gains per-task changed-file stats (`git -C <worktree> diff --stat <base>..<final>`), so integration review starts from real scope numbers.
+4. **Per-harness honor guidance**: a documented matrix in `docs/orchestration.md` — for each documented harness integration, whether (and how) it consumes `task.worktree`, plus the minimal adapter contract statement ("run the task with the worktree as cwd, or fail with a typed error").
+5. **Parallel evidence**: when a plan executes with `--max-parallel > 1`, the checkpoint records wall-clock duration and per-task overlap so parallel execution is evidenced, not assumed.
+
+## Affected areas
+
+- `src/orchestration.ts` (integrate preview: wave-ordered merge plan + merge-tree dry run; diff-stat collection)
+- `src/workflow.ts` (orchestrate subcommand wiring; doctor leak check)
+- `docs/orchestration.md` (honor matrix + adapter contract statement)
+- `docs/backlog.md` (this file)
+
+## Acceptance criteria
+
+- Given a passed isolated plan, when `orchestrate integrate --plan=<id>` runs, then it prints merge order respecting waves and flags conflicting task branches via merge-tree without merging anything.
+- Given leaked managed worktrees, when `aiw doctor` runs, then they are reported with plan/task attribution and the cleanup continuation command (typed reason, OPP-004 contract).
+- Given a task branch in conflict with the target, when the integrate forecast runs, then the conflict is reported before any merge is attempted.
+- Given an isolated execution with `--max-parallel=2`, when the checkpoint is written, then per-task wall-clock and overlap evidence are present.
+- Given no isolation, when orchestrate/integrate/doctor run, then behavior is unchanged.
+
+## Non-goals
+
+- No automatic merge, push, or orphan-branch deletion (human-owned integration).
+- No remote/cloud orchestration; no cross-repository worktrees.
+- No behavioral parity claims for harnesses that do not declare worktree support.
+
+## Open questions
+
+- Integrate target: main directly, or stacked branches per wave (easier review, harder bookkeeping)?
+- Should integrate also propose squash strategy per task from the checkpoint's commit evidence?
+- Doctor leak threshold: report all, or only worktrees older than N hours?

package/docs/opportunities/OPP-018-legacy-migration.md

@@ -0,0 +1,59 @@
+# OPP-018: Supported migration path for legacy installations
+
+- Status: Implemented (2026-11-03): aiw migrate with dry-run/rollback, doctor and install detection, deterministic-floor classification
+- Priority: P1 (field-verified pain; cheapest large-value gap in the backlog)
+- Added: 2026-11-01
+- Decision: extends [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) Decision A
+- Source signal: **field-verified during inception** — this repository itself ran an ancient (pre-ownership) installation and had to be migrated by hand: install preserves, uninstall refuses (ownership unverifiable), repair ignores, sync demands ownership. A controlled backup → fresh install → selective restore worked but is undiscoverable for a normal user. An external evaluation separately scored provider portability 4/5 citing "variable depth per harness" — migration depth is part of that.
+
+## Problem
+
+Installations created before the ownership inventory (roughly ≤0.9.x) enter a **closed loop** under 0.12+:
+
+- `doctor` reports missing `ownership.yml` and stops;
+- `install` sees existing state and preserves it without rebuilding the inventory;
+- `uninstall` refuses to remove resources it cannot verify ownership of (fail-closed — correct);
+- `sync` refuses to apply plans without the inventory;
+- `repair` does not cover the gap.
+
+Result: the only paths are hand-crafted file surgery (undiscoverable, undocumented) or staying on a broken state. Every user who installed before the inventory is stranded on upgrade.
+
+## Proposal
+
+1. **`aiw migrate`** (with `--dry-run` first): detects legacy state (`manifest.yml`/`lock.yml` present, `ownership.yml` absent) and performs a transactional, rollback-protected migration:
+   - snapshot legacy machine state (`lock.yml`, `recommendations.yml`) into `.aiw/checkpoints/migration-<timestamp>/` for history, but leave the live files in place — their owning commands (`aiw recommend`, `aiw skills install`, `aiw sync`) rewrite them in the modern format;
+   - rebuild the ownership inventory by scanning current AI-Workflow-managed paths and classifying each file: `managed-unchanged` (matches known content), `legacy-user-modified` (preserved as user-owned, listed for manual review), `unknown` (listed as manual action);
+   - preserve byte-identical user configuration (`decision.yml`, `semantic.yml`, `organization.yml`, `heartbeats.yml`, `settings.yml`) and all checkpoints/generated artifacts;
+   - produce a migration report: what was archived, rebuilt, preserved, and what needs manual review.
+2. **Detection and guidance**: `doctor` detects the legacy signature and reports it with the typed continuation `aiw migrate --dry-run`; `install` on legacy state suggests the same (instead of the bare "already installed" message).
+3. **Rollback**: apply writes a rollback checkpoint (the archived originals); `aiw migrate --rollback` restores them atomically — mirroring the target-migration rollback contract (MIG-002).
+4. **Fail-closed on ambiguity**: non-standard files that cannot be classified are listed as manual actions and never silently adopted or deleted.
+
+## Affected areas
+
+- New `src/legacy-migration.ts` (detection, classification, transactional apply, rollback)
+- `src/workflow.ts` (command wiring; doctor legacy detection; install legacy suggestion)
+- `src/ownership.ts` (inventory builder for legacy layouts)
+- Tests with fixture legacy layouts (0.7-era and 0.9-era shapes: no ownership, old lock format, old ai-init skill)
+- `docs/` (migration guide; release-process note that v0.12+ environments also trust `main` for the release chain)
+
+## Acceptance criteria
+
+- Given a 0.7-era layout fixture (no ownership, old lock, old ai-init skill), when `aiw migrate --dry-run` runs, then it lists exactly: archived files, rebuilt files, preserved files, and manual actions — without writing anything.
+- Given `aiw migrate` applied, when `aiw doctor` runs, then health passes; when `aiw sync --dry-run` runs, then it produces a plan (ownership present); and user config files are byte-identical to before.
+- Given migration applied, when `aiw migrate --rollback` runs, then the original legacy state is restored atomically and doctor reports the legacy condition again.
+- Given a fixture with a hand-modified generated rule, when migration runs, then the file is classified `legacy-user-modified`, preserved as user-owned, and listed for manual review — never overwritten.
+- Given ambiguous non-standard files, when migration runs, then it refuses to complete and names them as manual actions (fail-closed).
+- Given an installation already on the modern inventory, when `aiw migrate` runs, then it reports nothing to do and changes nothing.
+
+## Non-goals
+
+- No automatic schema upgrades beyond recreating the base state (schema 1 is forward-compatible; legacy artifacts are archived, not transformed).
+- No adoption of ambiguous files without explicit human action.
+- No deletion of any user data at any point (archival, never removal).
+
+## Open questions
+
+- Version heuristic: absence of `ownership.yml` + presence of `lock.yml` is the signature — is any additional fingerprint needed to distinguish 0.7-era from hand-rolled directories?
+- Should `migrate` offer to re-run `scan`+`recommend` at the end (guided continuation), or stop after the transactional state move?
+- Does the ownership rebuild need to recognize resources from known historical package versions to classify `managed-unchanged` accurately, or is content-hash matching against current bundled resources sufficient?

package/docs/opportunities/README.md

@@ -21,6 +21,9 @@ The guiding principle: **ceremony should scale with the consequence of the chang
 | [OPP-013](OPP-013-read-optimized-artifacts-digest-layer.md)  | Read-Optimized Artifacts — fingerprint-bound digest layer for downstream reads       | P1       | OPP-004 (typed blocks), CTX-002/004     |
 | [OPP-014](OPP-014-paired-verification-contract.md)           | Paired Verification Contract — expected vs observed, mechanically compared           | P2       | OPP-004 (reason codes)                  |
 | [OPP-015](OPP-015-token-recovery-governance.md)              | Token & Recovery Governance — enforced budgets, recovery block, advisory suggestions | P2       | CTX-004, OPP-002 (advisory signal)      |
+| [OPP-016](OPP-016-behavioral-eval-scenarios.md)              | Behavioral evaluation phase 2 — scenario registry replayed against real harness CLIs | P2       | OPP-011 (deterministic floor)           |
+| [OPP-017](OPP-017-orchestration-depth.md)                    | Orchestration depth — integration forecast, leak reporting, honor matrix             | P2       | OPP-010 (isolation)                     |
+| [OPP-018](OPP-018-legacy-migration.md)                       | Supported migration path for legacy installations                                    | P1       | — (field-verified pain)                 |
 
 Suggested starting order: **OPP-004 → OPP-002 → OPP-006 → OPP-001 → OPP-005 → OPP-003** (smallest/least invasive first; OPP-004's reason codes feed OPP-005 and OPP-006).
 
@@ -30,6 +33,10 @@ OPP-007 and OPP-008 are **model-integration addenda**: deliberately left for aft
 
 OPP-009 through OPP-012 derive from a November 2026 landscape scan (spec-kit 145K★ shipping independent entry points; Spec Kitty / Conductor normalizing isolated-worktree parallel agents; promptfoo 26K★ establishing artifact evals; Agent OS 5.5K★ on standards discovery). The scan also **validated** the existing positioning: spec-driven development and human-in-the-loop governance are growing markets where AI Workflow's evidence ledger is the differentiator. Deliberately not chased: generic memory layers (audit-first philosophy), cloud-agent infrastructure (harness territory), commercial AI-review feature parity.
 
+### Evaluation-sourced addendum (OPP-016..018)
+
+An external qualitative assessment (Nov 2026) scored the release: specification-driven engineering, token governance, and workflow governance at 5/5; multi-agent orchestration and behavioral evaluation at 3/5; provider portability 4/5. The scores match the internal read — the 5s are the differentiators, the 3s are the frontier. OPP-016 (behavioral scenarios against real harness CLIs), OPP-017 (orchestration integration forecast, leak reporting, honor matrix) and OPP-018 (supported legacy migration, field-verified pain during inception) are the levers on those scores. The assessment also missed two documented strengths: the honest threat-model boundary and the friction benchmark as a quality instrument.
+
 ### Token-analysis addendum (OPP-013..015)
 
 Measured on this repository's own full-lane artifacts (~2.2K-token specification, ~4.1K-token plan): downstream re-reads cost ~25-30K tokens per feature — roughly 80% of an artifact's lifetime token cost is re-reading, not writing. OPP-013 (digests), OPP-014 (paired verification) and OPP-015 (governance) attack that multiplier and make observed proof mechanically checkable, synthesizing the shared insight across spec-kit, ODD and HDAE: the full artifact is for humans; agents need a derived, verifiable view.

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/docs/release-process.md

@@ -8,7 +8,7 @@ AI Workflow releases are reproducible, evidence-backed, and published only from
 2. A maintainer reviews and merges the pull request into `main`.
 3. The `Auto-tag releases` workflow notices that the merged version has no `v<version>` tag yet, creates the tag on the merge commit, and the `Release` workflow takes over: it validates the tagged source and publishes with npm trusted publishing and provenance.
 
-No manual tagging and no environment approvals: merging an reviewed pull request with a version bump is the entire release action. Merges that do not bump the version are ignored by the auto-tag workflow.
+No manual tagging and no environment approvals: merging an reviewed pull request with a version bump is the entire release action. Since 0.11.0 the Auto-tag workflow invokes the Release workflow directly (reusable-workflow call) — tags created through the API with the default `GITHUB_TOKEN` do not trigger other workflows — and the `npm` environment's deployment policy trusts both `v*.*.*` tags and `main` for that call chain. Merges that do not bump the version are ignored by the auto-tag workflow.
 
 ## Preconditions
 

package/package.json

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