@multileaf/ai-workflow 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [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"];
 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,7 @@ export const BLOCKING_REASON_CODES = [
     "state_mismatch",
     "context_budget_exceeded",
     "stage_not_in_process",
+    "migration_required",
 ];
 function command(commandText) {
     return { kind: "command", command: commandText };
@@ -154,6 +155,11 @@ 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"),
+    },
 };
 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/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() {
@@ -636,9 +637,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 +1822,16 @@ 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(", ")}` };
+            }
             try {
                 parseManifest(fs.read(join(aiw, "manifest.yml")));
                 parseOwnership(fs.read(join(aiw, "ownership.yml")));
@@ -2141,6 +2153,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.
+- [ ] **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,4 @@ 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 |

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: 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 "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/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.13.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {