@felixdotgo/aidlc-kit 0.1.0 → 0.1.1

package/dist/src/tracker.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Backlog tracker integration: resolves tracker credentials from the environment
+ * and builds the HTTP requests used to mirror lifecycle phase transitions.
+ */
 import type { TrackerConfig } from "./model.js";
 export interface TrackerDiagnostic {
     code: "TRACKER_DISABLED" | "TRACKER_AUTH" | "TRACKER_RATE_LIMIT" | "TRACKER_REQUEST";
@@ -18,7 +22,9 @@ export type TrackerResolution = {
     config: TrackerConfig;
     token: string;
 };
+/** Resolves a tracker configuration into either an enabled resolution (with token) or a disabled diagnostic. */
 export declare const resolveTracker: (config: TrackerConfig | undefined, environment?: NodeJS.ProcessEnv) => TrackerResolution;
+/** Executes a single Backlog request, mapping HTTP failures to retryable diagnostics. */
 export declare const executeBacklog: (resolution: TrackerResolution, request: BacklogRequest, fetcher?: FetchLike) => Promise<{
     ok: true;
     body: unknown;
@@ -26,4 +32,5 @@ export declare const executeBacklog: (resolution: TrackerResolution, request: Ba
     ok: false;
     diagnostic: TrackerDiagnostic;
 }>;
+/** Builds the Backlog PATCH request that mirrors a lifecycle phase transition for an issue. */
 export declare const gateUpdate: (config: TrackerConfig, issue: string, phase: "clarify" | "plan" | "build" | "wrap" | "done", idempotencyKey: string) => BacklogRequest;

package/dist/src/tracker.js

@@ -1,3 +1,4 @@
+/** Resolves a tracker configuration into either an enabled resolution (with token) or a disabled diagnostic. */
 export const resolveTracker = (config, environment = process.env) => {
     if (!config)
         return { enabled: false, diagnostic: { code: "TRACKER_DISABLED", message: "Tracker is not configured; Git-only mode is active.", retryable: false } };
@@ -12,6 +13,7 @@ const form = (values) => {
         body.set(key, String(value));
     return body;
 };
+/** Executes a single Backlog request, mapping HTTP failures to retryable diagnostics. */
 export const executeBacklog = async (resolution, request, fetcher = fetch) => {
     if (!resolution.enabled)
         return { ok: false, diagnostic: resolution.diagnostic };
@@ -28,6 +30,7 @@ export const executeBacklog = async (resolution, request, fetcher = fetch) => {
         return { ok: false, diagnostic: { code: "TRACKER_REQUEST", message: `Backlog request failed with HTTP ${response.status}.`, retryable: response.status >= 500 } };
     return { ok: true, body: await response.json() };
 };
+/** Builds the Backlog PATCH request that mirrors a lifecycle phase transition for an issue. */
 export const gateUpdate = (config, issue, phase, idempotencyKey) => {
     const comment = `[aidlc:${idempotencyKey}] ${phase}`;
     if (config.workflow === "waterfall") {

package/dist/src/upgrade-board.d.ts

@@ -0,0 +1,5 @@
+import type { FileSpec, WorkflowState } from "./model.js";
+export declare const migrateLegacyBoard: (root: string) => {
+    state: WorkflowState;
+    files: FileSpec[];
+};

package/dist/src/upgrade-board.js

@@ -0,0 +1,89 @@
+/**
+ * Legacy v0.2.x BOARD.md migration. Parses the markdown task table into
+ * canonical lifecycle state and preserves each legacy task's prose files in
+ * the stable artifact layout so no legacy content is lost.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveProjectPath } from "./project-path.js";
+import { emptyState, renderWorkplan, validateState } from "./state.js";
+const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe upgrade path");
+const parseFrontmatter = (content) => {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    return Object.fromEntries(match[1].split("\n").flatMap((line) => {
+        const separator = line.indexOf(":");
+        return separator < 0 ? [] : [[line.slice(0, separator).trim(), line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, "")]];
+    }));
+};
+const cells = (line) => line.split("|").slice(1, -1).map((cell) => cell.trim().replace(/^`|`$/g, ""));
+/* Approval evidence is rebuilt from the row's phase: everything beyond plan implies G0 passed, etc. */
+const legacyEvidence = (phase, recordedAt) => {
+    const evidence = [];
+    if (["plan", "build", "wrap", "done"].includes(phase))
+        evidence.push({ kind: "approval", gate: "G0_confirm", source: "legacy state migration", result: "pass", recordedAt });
+    if (["build", "wrap", "done"].includes(phase))
+        evidence.push({ kind: "approval", gate: "G1_review", source: "legacy state migration", result: "pass", recordedAt });
+    return evidence;
+};
+/** Maps one legacy BOARD row to a canonical task, copying its prose files into the stable artifact layout. */
+const taskFromLegacyRow = (root, files, row, recordedAt) => {
+    const [id, title, phaseRaw, gateRaw, statusRaw, branch, areasRaw, doc] = row;
+    const oldDoc = safePath(root, doc);
+    const source = existsSync(oldDoc) ? readFileSync(oldDoc, "utf8") : "";
+    const frontmatter = parseFrontmatter(source);
+    const stableDir = `.agents/data/tasks/${id}`;
+    const prosePath = `${stableDir}/intent-design.md`;
+    const workplanPath = `${stableDir}/workplan.md`;
+    if (source)
+        files.push({ path: prosePath, owner: "aidlc-state", ownershipClass: "state", content: source });
+    const oldWorkplan = doc.replace(/\.md$/, ".workplan.md");
+    if (existsSync(safePath(root, oldWorkplan)))
+        files.push({ path: `${stableDir}/legacy-workplan.md`, owner: "aidlc-state", ownershipClass: "state", content: readFileSync(safePath(root, oldWorkplan), "utf8") });
+    const phase = ["clarify", "plan", "build", "wrap", "done"].includes(phaseRaw) ? phaseRaw : "clarify";
+    const gate = ["none", "G0_confirm", "G1_review", "G2_codereview"].includes(gateRaw) ? gateRaw : "G0_confirm";
+    return {
+        id,
+        title,
+        type: (["feature", "bug", "refactor", "infra"].includes(frontmatter.type) ? frontmatter.type : "infra"),
+        phase,
+        gate,
+        status: (["active", "blocked_on_user", "paused", "done"].includes(statusRaw) ? statusRaw : "paused"),
+        language: frontmatter.language === "en" ? "en" : "vi",
+        risk: "normal",
+        areas: areasRaw.split(",").map((area) => area.trim()).filter(Boolean),
+        branch: branch || "—",
+        artifacts: { intent: source ? prosePath : undefined, design: source ? prosePath : undefined, workplan: workplanPath },
+        decisions: [],
+        tasks: [],
+        evidence: [...legacyEvidence(phase, recordedAt), { kind: "diagnostic", source: "legacy state migration", result: "pass", detail: `Original artifacts preserved at ${doc}`, recordedAt }],
+        createdAt: recordedAt,
+        updatedAt: recordedAt
+    };
+};
+export const migrateLegacyBoard = (root) => {
+    const boardPath = join(resolve(root), ".agents/data/state/BOARD.md");
+    if (!existsSync(boardPath))
+        return { state: emptyState(), files: [] };
+    const content = readFileSync(boardPath, "utf8");
+    const state = emptyState();
+    const files = [];
+    let migratedRows = 0;
+    for (const line of content.split("\n")) {
+        if (!line.startsWith("|") || /^\|[- ]+\|/.test(line) || line.includes("| id |"))
+            continue;
+        const row = cells(line);
+        if (row.length < 8)
+            throw new Error("Legacy BOARD contains a malformed task row; refusing lossy migration");
+        migratedRows += 1;
+        const task = taskFromLegacyRow(root, files, row, new Date().toISOString());
+        state.tasks[task.id] = task;
+    }
+    if (!migratedRows && !content.includes("_No tasks in flight._"))
+        throw new Error("Legacy BOARD contains no recognizable task rows; refusing lossy migration");
+    for (const task of Object.values(state.tasks))
+        files.push({ path: task.artifacts.workplan, owner: "aidlc-state", ownershipClass: "state", content: renderWorkplan(task) });
+    validateState(state);
+    return { state, files };
+};

package/dist/src/upgrade.d.ts

@@ -1,11 +1,10 @@
-import type { FileSpec, LoopConfig, PlannedWrite, WorkflowState } from "./model.js";
-export declare const migrateLegacyBoard: (root: string) => {
-    state: WorkflowState;
-    files: FileSpec[];
-};
+import type { LoopConfig, PlannedWrite } from "./model.js";
+export { migrateLegacyBoard } from "./upgrade-board.js";
+/** Plans an upgrade transaction from the installed manifest to the current package. */
 export declare const planUpgrade: (root: string, loop?: LoopConfig) => PlannedWrite[];
 export interface UpgradeResult {
     backup: string;
     changed: number;
 }
+/** Applies a planned upgrade transaction with backup and rollback on failure. */
 export declare const applyUpgrade: (root: string, plan: PlannedWrite[]) => UpgradeResult;

package/dist/src/upgrade.js

@@ -6,8 +6,10 @@ import { legacyV021AdapterContents, legacyV021Hashes } from "./legacy.js";
 import { planProjectLayoutMigration } from "./project-migration.js";
 import { mergeManagedBlock } from "./managed-content.js";
 import { resolveProjectPath, resolveProjectPathWithoutSymlinks } from "./project-path.js";
-import { emptyState, prepareV4Migration, renderWorkplan, validateState } from "./state.js";
+import { prepareV4Migration, validateState } from "./state.js";
 import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec } from "./workflow.js";
+import { migrateLegacyBoard } from "./upgrade-board.js";
+export { migrateLegacyBoard } from "./upgrade-board.js";
 const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe upgrade path");
 const assertNoSymlinkPath = (root, relative) => { resolveProjectPathWithoutSymlinks(root, relative, "Unsafe upgrade path", "Refusing to upgrade symlink path"); };
 const legacyManifest = (root) => {
@@ -20,79 +22,9 @@ const legacyManifest = (root) => {
     }
     catch {
         return false;
-    }
-};
-const parseFrontmatter = (content) => {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match)
-        return {};
-    return Object.fromEntries(match[1].split("\n").flatMap((line) => {
-        const separator = line.indexOf(":");
-        return separator < 0 ? [] : [[line.slice(0, separator).trim(), line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, "")]];
-    }));
-};
-const cells = (line) => line.split("|").slice(1, -1).map((cell) => cell.trim().replace(/^`|`$/g, ""));
-export const migrateLegacyBoard = (root) => {
-    const boardPath = join(resolve(root), ".agents/data/state/BOARD.md");
-    if (!existsSync(boardPath))
-        return { state: emptyState(), files: [] };
-    const state = emptyState();
-    const files = [];
-    const boardContent = readFileSync(boardPath, "utf8");
-    let migratedRows = 0;
-    for (const line of boardContent.split("\n")) {
-        if (!line.startsWith("|") || /^\|[- ]+\|/.test(line) || line.includes("| id |"))
-            continue;
-        const row = cells(line);
-        if (row.length < 8)
-            throw new Error("Legacy BOARD contains a malformed task row; refusing lossy migration");
-        const [id, title, phaseRaw, gateRaw, statusRaw, branch, areasRaw, doc] = row;
-        migratedRows += 1;
-        const oldDoc = safePath(root, doc);
-        const source = existsSync(oldDoc) ? readFileSync(oldDoc, "utf8") : "";
-        const frontmatter = parseFrontmatter(source);
-        const stableDir = `.agents/data/tasks/${id}`;
-        const prosePath = `${stableDir}/intent-design.md`;
-        const workplanPath = `${stableDir}/workplan.md`;
-        if (source)
-            files.push({ path: prosePath, owner: "aidlc-state", ownershipClass: "state", content: source });
-        const oldWorkplan = doc.replace(/\.md$/, ".workplan.md");
-        if (existsSync(safePath(root, oldWorkplan)))
-            files.push({ path: `${stableDir}/legacy-workplan.md`, owner: "aidlc-state", ownershipClass: "state", content: readFileSync(safePath(root, oldWorkplan), "utf8") });
-        const phase = ["clarify", "plan", "build", "wrap", "done"].includes(phaseRaw) ? phaseRaw : "clarify";
-        const gate = ["none", "G0_confirm", "G1_review", "G2_codereview"].includes(gateRaw) ? gateRaw : "G0_confirm";
-        const evidence = [];
-        const now = new Date().toISOString();
-        if (["plan", "build", "wrap", "done"].includes(phase))
-            evidence.push({ kind: "approval", gate: "G0_confirm", source: "legacy state migration", result: "pass", recordedAt: now });
-        if (["build", "wrap", "done"].includes(phase))
-            evidence.push({ kind: "approval", gate: "G1_review", source: "legacy state migration", result: "pass", recordedAt: now });
-        state.tasks[id] = {
-            id,
-            title,
-            type: (["feature", "bug", "refactor", "infra"].includes(frontmatter.type) ? frontmatter.type : "infra"),
-            phase,
-            gate,
-            status: (["active", "blocked_on_user", "paused", "done"].includes(statusRaw) ? statusRaw : "paused"),
-            language: frontmatter.language === "en" ? "en" : "vi",
-            risk: "normal",
-            areas: areasRaw.split(",").map((area) => area.trim()).filter(Boolean),
-            branch: branch || "—",
-            artifacts: { intent: source ? prosePath : undefined, design: source ? prosePath : undefined, workplan: workplanPath },
-            decisions: [],
-            tasks: [],
-            evidence: [...evidence, { kind: "diagnostic", source: "legacy state migration", result: "pass", detail: `Original artifacts preserved at ${doc}`, recordedAt: now }],
-            createdAt: now,
-            updatedAt: now
-        };
-    }
-    if (!migratedRows && !boardContent.includes("_No tasks in flight._"))
-        throw new Error("Legacy BOARD contains no recognizable task rows; refusing lossy migration");
-    for (const task of Object.values(state.tasks))
-        files.push({ path: task.artifacts.workplan, owner: "aidlc-state", ownershipClass: "state", content: renderWorkplan(task) });
-    validateState(state);
-    return { state, files };
+    } /* intentional: a malformed/missing manifest is not a legacy v0.x install */
 };
+/* --- Managed file planning -------------------------------------------------- */
 const planManaged = (root, spec, installedHash, legacy) => {
     const target = safePath(root, spec.path);
     if (!existsSync(target))
@@ -113,124 +45,221 @@ const planManaged = (root, spec, installedHash, legacy) => {
         return { ...spec, content: next, action: "conflict", reason: "managed prompt block was modified" };
     return { ...spec, content: next, action: "conflict", reason: legacy ? "legacy core differs from known baseline" : "managed file differs from installed hash" };
 };
-export const planUpgrade = (root, loop) => {
-    const project = resolve(root);
-    const installed = readManifest(project);
-    const legacy = !installed && legacyManifest(project);
-    if (!installed && !legacy)
-        throw new Error("No owned AI-DLC installation found. Use init instead of upgrade.");
-    const upgradeAdapters = resolvedAdaptersForUpgrade();
-    const requested = installed?.adapters?.length ? installed.adapters : upgradeAdapters.filter((adapter) => adapter.detect(project)).map((adapter) => adapter.id);
-    const selected = requested.filter((id) => findAdapterForUpgrade(id));
-    const agentFiles = selected.flatMap((id) => findAdapterForUpgrade(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
-    const managed = [...coreWorkflowFiles(), ...agentFiles];
+/** Merges a later owner of a shared managed-block path into the already-emitted plan entry. */
+const mergeSharedBlockOwner = (project, previous, spec, installed) => {
+    if (!["create", "update", "skip"].includes(previous.action))
+        return;
+    const target = safePath(project, spec.path);
+    const current = existsSync(target) ? readFileSync(target, "utf8") : "";
+    // Every owner block is checked before merging so a user edit to a later
+    // adapter's block is reported instead of being silently overwritten.
+    const installedBlockHash = installedHashFor(installed?.files, spec);
+    const currentBlockHash = managedContentHash(spec, current);
+    if (installedBlockHash !== undefined && currentBlockHash !== undefined && installedBlockHash !== currentBlockHash) {
+        previous.action = "conflict";
+        previous.reason = "managed prompt block was modified";
+        return;
+    }
+    previous.content = mergeManagedBlock(spec, previous.content);
+    previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
+    previous.reason = "managed prompt block";
+};
+/** Plans managed replacements and shared managed-block writes across every owner. */
+const planManagedFiles = (project, managed, installed, legacy) => {
     const plan = [];
     const mergedBlocks = new Map();
     for (const spec of managed) {
+        const installedHash = installedHashFor(installed?.files, spec);
         if (spec.strategy !== "managed-block") {
-            plan.push(planManaged(project, spec, installedHashFor(installed?.files, spec), legacy));
+            plan.push(planManaged(project, spec, installedHash, legacy));
             continue;
         }
         const previous = mergedBlocks.get(spec.path);
         if (!previous) {
-            const write = planManaged(project, spec, installedHashFor(installed?.files, spec), legacy);
+            const write = planManaged(project, spec, installedHash, legacy);
             plan.push(write);
             mergedBlocks.set(spec.path, write);
             continue;
         }
-        if (!["create", "update", "skip"].includes(previous.action))
+        mergeSharedBlockOwner(project, previous, spec, installed);
+    }
+    return plan;
+};
+/* --- Obsolete files and project-owned files ---------------------------------- */
+/** Deletes obsolete managed files tracked by the installed manifest that no longer ship in this release. */
+const planObsoleteRemovals = (project, plan, installed, managed) => {
+    for (const [key, item] of Object.entries(installed.files)) {
+        const path = key.includes("#") ? key.slice(0, key.lastIndexOf("#")) : key;
+        // Shared prompt blocks are upgraded through the merged plan above; never delete their whole path here.
+        if (item.strategy === "managed-block")
             continue;
-        const target = safePath(project, spec.path);
-        const current = existsSync(target) ? readFileSync(target, "utf8") : "";
-        // Every owner block is checked before merging so a user edit to a later
-        // adapter's block is reported instead of being silently overwritten.
-        const installedBlockHash = installedHashFor(installed?.files, spec);
-        const currentBlockHash = managedContentHash(spec, current);
-        if (installedBlockHash !== undefined && currentBlockHash !== undefined && installedBlockHash !== currentBlockHash) {
-            previous.action = "conflict";
-            previous.reason = "managed prompt block was modified";
+        if (managed.some((spec) => spec.path === path))
             continue;
-        }
-        previous.content = mergeManagedBlock(spec, previous.content);
-        previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
-        previous.reason = "managed prompt block";
-    }
-    if (installed) {
-        for (const [key, item] of Object.entries(installed.files)) {
-            const path = key.includes("#") ? key.slice(0, key.lastIndexOf("#")) : key;
-            // Shared prompt blocks are upgraded through the merged plan above; never delete their whole path here.
-            if (item.strategy === "managed-block")
-                continue;
-            if (managed.some((spec) => spec.path === path))
-                continue;
-            const target = safePath(project, path);
-            if (!existsSync(target))
-                continue;
-            const current = readFileSync(target, "utf8");
-            const hash = managedContentHash({ owner: item.owner, strategy: item.strategy }, current);
-            plan.push({ path, owner: item.owner, strategy: item.strategy, ownershipClass: "managed", content: "", action: hash === item.hash ? "delete" : "conflict", reason: hash === item.hash ? "obsolete unchanged managed file" : "obsolete managed file was modified" });
-        }
+        const target = safePath(project, path);
+        if (!existsSync(target))
+            continue;
+        const current = readFileSync(target, "utf8");
+        const hash = managedContentHash({ owner: item.owner, strategy: item.strategy }, current);
+        plan.push({ path, owner: item.owner, strategy: item.strategy, ownershipClass: "managed", content: "", action: hash === item.hash ? "delete" : "conflict", reason: hash === item.hash ? "obsolete unchanged managed file" : "obsolete managed file was modified" });
     }
+};
+const preserveProjectFiles = (project, plan, legacy) => {
     for (const spec of initialProjectFiles()) {
         if (legacy && spec.path === ".agents/data/state/aidlc-state.json" && !existsSync(safePath(project, spec.path)))
             continue;
         const target = safePath(project, spec.path);
         plan.push(existsSync(target) ? { ...spec, content: readFileSync(target, "utf8"), action: "preserve", reason: `${spec.ownershipClass}-owned file` } : { ...spec, action: "create", reason: `new ${spec.ownershipClass}-owned file` });
     }
+};
+/* --- Canonical state and legacy BOARD migration -------------------------------- */
+/** Migrates a preserved canonical state file (schema v1–v3) to v4 with immutable archived-task records. */
+const migrateCanonicalState = (project, plan, canonicalState) => {
+    if (canonicalState.action !== "preserve")
+        return;
+    const parsed = JSON.parse(canonicalState.content);
+    const normalized = validateState(parsed);
+    if (parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2 && parsed.schemaVersion !== 3)
+        return;
+    const migration = prepareV4Migration(normalized);
+    canonicalState.content = `${JSON.stringify(migration.state, null, 2)}\n`;
+    canonicalState.action = "migrate";
+    canonicalState.reason = `migrate canonical state schema v${parsed.schemaVersion} to v4 compact catalog${migration.stamped.length ? ` and stamp pre-existing ready G2 waits: ${migration.stamped.join(", ")}` : " without changing task content"}`;
+    for (const record of migration.records) {
+        assertNoSymlinkPath(project, record.path);
+        const target = safePath(project, record.path);
+        if (!existsSync(target))
+            plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "write immutable terminal task record" });
+        else if (readFileSync(target, "utf8") !== record.content)
+            plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "conflict", reason: "terminal task record conflicts with prior canonical content" });
+    }
+    const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
+    if (!lessonIndex)
+        throw new Error("Lesson index plan is missing");
+    lessonIndex.content = `${JSON.stringify(migration.lessonIndex, null, 2)}\n`;
+    lessonIndex.action = "migrate";
+    lessonIndex.reason = "build derived lesson index from canonical task records";
+};
+/** Seeds the plan from a legacy BOARD.md when no canonical state file exists yet. */
+const migrateLegacyState = (project, plan, legacy) => {
+    if (!legacy || existsSync(safePath(project, ".agents/data/state/aidlc-state.json")))
+        return;
+    const migration = migrateLegacyBoard(project);
+    const compact = prepareV4Migration(migration.state);
+    plan.push({ path: ".agents/data/state/aidlc-state.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(compact.state, null, 2)}\n`, action: "migrate", reason: "migrate legacy BOARD to canonical v4 state" });
+    for (const record of compact.records)
+        plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "preserve legacy terminal task as immutable record" });
+    const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
+    if (lessonIndex) {
+        lessonIndex.content = `${JSON.stringify(compact.lessonIndex, null, 2)}\n`;
+        lessonIndex.action = "migrate";
+        lessonIndex.reason = "build derived lesson index during legacy migration";
+    }
+    for (const file of migration.files)
+        plan.push({ ...file, action: "migrate", reason: "preserve legacy task prose in stable task directory" });
+};
+/** Removes the duplicate BOARD.md projection only when the planned canonical state validates. */
+const removeLegacyBoard = (project, plan) => {
+    const boardPath = safePath(project, ".agents/data/state/BOARD.md");
+    if (!existsSync(boardPath))
+        return;
+    const stateItem = plan.find((item) => item.path === ".agents/data/state/aidlc-state.json");
+    if (!stateItem)
+        throw new Error("Canonical state must be present before removing legacy BOARD");
+    validateState(JSON.parse(stateItem.content));
+    plan.push({ path: ".agents/data/state/BOARD.md", owner: "aidlc-state", ownershipClass: "state", content: "", action: "delete", reason: "remove duplicate lifecycle-state projection after canonical JSON validation" });
+};
+/* --- planUpgrade orchestration ------------------------------------------------ */
+/** Selects which adapters to upgrade: manifest-registered ones, else auto-detected installable ones. */
+const selectedUpgradeAgents = (project, installed) => {
+    const upgradeAdapters = resolvedAdaptersForUpgrade();
+    const requested = installed?.adapters?.length ? installed.adapters : upgradeAdapters.filter((adapter) => adapter.detect(project)).map((adapter) => adapter.id);
+    return requested.filter((id) => findAdapterForUpgrade(id));
+};
+const agentUpgradeFiles = (selected) => selected.flatMap((id) => findAdapterForUpgrade(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
+/** Plans an upgrade transaction from the installed manifest to the current package. */
+export const planUpgrade = (root, loop) => {
+    const project = resolve(root);
+    const installed = readManifest(project);
+    const legacy = !installed && legacyManifest(project);
+    if (!installed && !legacy)
+        throw new Error("No owned AI-DLC installation found. Use init instead of upgrade.");
+    const selected = selectedUpgradeAgents(project, installed);
+    const managed = [...coreWorkflowFiles(), ...agentUpgradeFiles(selected)];
+    const plan = planManagedFiles(project, managed, installed, legacy);
+    if (installed)
+        planObsoleteRemovals(project, plan, installed, managed);
+    preserveProjectFiles(project, plan, legacy);
     const canonicalState = plan.find((item) => item.path === ".agents/data/state/aidlc-state.json");
-    if (canonicalState && canonicalState.action === "preserve") {
-        const parsed = JSON.parse(canonicalState.content);
-        const normalized = validateState(parsed);
-        if (parsed.schemaVersion === 1 || parsed.schemaVersion === 2 || parsed.schemaVersion === 3) {
-            const migration = prepareV4Migration(normalized);
-            canonicalState.content = `${JSON.stringify(migration.state, null, 2)}\n`;
-            canonicalState.action = "migrate";
-            canonicalState.reason = `migrate canonical state schema v${parsed.schemaVersion} to v4 compact catalog${migration.stamped.length ? ` and stamp pre-existing ready G2 waits: ${migration.stamped.join(", ")}` : " without changing task content"}`;
-            for (const record of migration.records) {
-                assertNoSymlinkPath(project, record.path);
-                const target = safePath(project, record.path);
-                if (!existsSync(target))
-                    plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "write immutable terminal task record" });
-                else if (readFileSync(target, "utf8") !== record.content)
-                    plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "conflict", reason: "terminal task record conflicts with prior canonical content" });
-            }
-            const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
-            if (!lessonIndex)
-                throw new Error("Lesson index plan is missing");
-            lessonIndex.content = `${JSON.stringify(migration.lessonIndex, null, 2)}\n`;
-            lessonIndex.action = "migrate";
-            lessonIndex.reason = "build derived lesson index from canonical task records";
+    if (canonicalState)
+        migrateCanonicalState(project, plan, canonicalState);
+    planProjectLayoutMigration(project, plan);
+    migrateLegacyState(project, plan, legacy);
+    removeLegacyBoard(project, plan);
+    plan.push({ ...manifestSpec(managed, selected), action: "update", reason: legacy ? "migrate manifest to schema v2" : "update manifest inventory" });
+    planLoopSelection(plan, loop);
+    return plan;
+};
+/** Copies each affected original into the backup and stages the new content outside the live tree. */
+const stageUpgradedWrites = (project, writes, backup, stage, journal) => {
+    for (const item of writes) {
+        const target = safePath(project, item.path);
+        assertNoSymlinkPath(project, item.path);
+        const existed = existsSync(target);
+        journal.push({ path: item.path, existed, action: item.action });
+        if (existed) {
+            const destination = join(backup, item.path);
+            mkdirSync(dirname(destination), { recursive: true });
+            copyFileSync(target, destination);
+        }
+        if (item.action !== "delete") {
+            const staged = join(stage, item.path);
+            mkdirSync(dirname(staged), { recursive: true });
+            writeFileSync(staged, item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : item.content);
+            if (item.path.endsWith(".json") && item.contentEncoding !== "base64")
+                JSON.parse(item.content);
         }
     }
-    planProjectLayoutMigration(project, plan);
-    if (legacy && !existsSync(safePath(project, ".agents/data/state/aidlc-state.json"))) {
-        const migration = migrateLegacyBoard(project);
-        const compact = prepareV4Migration(migration.state);
-        plan.push({ path: ".agents/data/state/aidlc-state.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(compact.state, null, 2)}\n`, action: "migrate", reason: "migrate legacy BOARD to canonical v4 state" });
-        for (const record of compact.records)
-            plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "preserve legacy terminal task as immutable record" });
-        const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
-        if (lessonIndex) {
-            lessonIndex.content = `${JSON.stringify(compact.lessonIndex, null, 2)}\n`;
-            lessonIndex.action = "migrate";
-            lessonIndex.reason = "build derived lesson index during legacy migration";
+};
+const writeUpgradeJournal = (backup, journal) => {
+    mkdirSync(backup, { recursive: true });
+    writeFileSync(join(backup, "journal.json"), `${JSON.stringify(journal, null, 2)}\n`, "utf8");
+};
+const commitStagedWrites = (project, writes, stage) => {
+    for (const item of writes) {
+        const target = safePath(project, item.path);
+        if (item.action === "delete")
+            rmSync(target, { force: true });
+        else {
+            mkdirSync(dirname(target), { recursive: true });
+            if (existsSync(target))
+                rmSync(target, { force: true });
+            renameSync(join(stage, item.path), target);
         }
-        for (const file of migration.files)
-            plan.push({ ...file, action: "migrate", reason: "preserve legacy task prose in stable task directory" });
     }
-    const boardPath = safePath(project, ".agents/data/state/BOARD.md");
-    if (existsSync(boardPath)) {
-        const stateItem = plan.find((item) => item.path === ".agents/data/state/aidlc-state.json");
-        if (!stateItem)
-            throw new Error("Canonical state must be present before removing legacy BOARD");
-        validateState(JSON.parse(stateItem.content));
-        plan.push({ path: ".agents/data/state/BOARD.md", owner: "aidlc-state", ownershipClass: "state", content: "", action: "delete", reason: "remove duplicate lifecycle-state projection after canonical JSON validation" });
+};
+const pruneEmptyDirectories = (directory) => {
+    if (!existsSync(directory) || !lstatSync(directory).isDirectory())
+        return;
+    for (const entry of readdirSync(directory, { withFileTypes: true }))
+        if (entry.isDirectory())
+            pruneEmptyDirectories(join(directory, entry.name));
+    if (readdirSync(directory).length === 0)
+        rmdirSync(directory);
+};
+/** Restores the journaled originals so a failed upgrade leaves no partial state. */
+const restoreFromJournal = (project, journal, backup) => {
+    for (const entry of journal.reverse()) {
+        const target = safePath(project, entry.path);
+        const source = join(backup, entry.path);
+        if (entry.existed && existsSync(source)) {
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+        }
+        else if (!entry.existed)
+            rmSync(target, { force: true });
     }
-    const manifest = manifestSpec(managed, selected);
-    plan.push({ ...manifest, action: "update", reason: legacy ? "migrate manifest to schema v2" : "update manifest inventory" });
-    planLoopSelection(plan, loop);
-    return plan;
 };
+/** Applies a planned upgrade transaction with backup and rollback on failure. */
 export const applyUpgrade = (root, plan) => {
     const conflicts = plan.filter((item) => item.action === "conflict");
     if (conflicts.length)
@@ -244,61 +273,15 @@ export const applyUpgrade = (root, plan) => {
     mkdirSync(stage, { recursive: true });
     const journal = [];
     try {
-        for (const item of writes) {
-            const target = safePath(project, item.path);
-            assertNoSymlinkPath(project, item.path);
-            const existed = existsSync(target);
-            journal.push({ path: item.path, existed, action: item.action });
-            if (existed) {
-                const destination = join(backup, item.path);
-                mkdirSync(dirname(destination), { recursive: true });
-                copyFileSync(target, destination);
-            }
-            if (item.action !== "delete") {
-                const staged = join(stage, item.path);
-                mkdirSync(dirname(staged), { recursive: true });
-                writeFileSync(staged, item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : item.content);
-                if (item.path.endsWith(".json") && item.contentEncoding !== "base64")
-                    JSON.parse(item.content);
-            }
-        }
-        mkdirSync(backup, { recursive: true });
-        writeFileSync(join(backup, "journal.json"), `${JSON.stringify(journal, null, 2)}\n`, "utf8");
-        for (const item of writes) {
-            const target = safePath(project, item.path);
-            if (item.action === "delete")
-                rmSync(target, { force: true });
-            else {
-                mkdirSync(dirname(target), { recursive: true });
-                if (existsSync(target))
-                    rmSync(target, { force: true });
-                renameSync(join(stage, item.path), target);
-            }
-        }
-        const pruneEmpty = (directory) => {
-            if (!existsSync(directory) || !lstatSync(directory).isDirectory())
-                return;
-            for (const entry of readdirSync(directory, { withFileTypes: true }))
-                if (entry.isDirectory())
-                    pruneEmpty(join(directory, entry.name));
-            if (readdirSync(directory).length === 0)
-                rmdirSync(directory);
-        };
-        pruneEmpty(safePath(project, ".aidlc"));
+        stageUpgradedWrites(project, writes, backup, stage, journal);
+        writeUpgradeJournal(backup, journal);
+        commitStagedWrites(project, writes, stage);
+        pruneEmptyDirectories(safePath(project, ".aidlc"));
         rmSync(stage, { recursive: true, force: true });
         return { backup: backupRelative, changed: writes.length };
     }
     catch (error) {
-        for (const entry of journal.reverse()) {
-            const target = safePath(project, entry.path);
-            const source = join(backup, entry.path);
-            if (entry.existed && existsSync(source)) {
-                mkdirSync(dirname(target), { recursive: true });
-                copyFileSync(source, target);
-            }
-            else if (!entry.existed)
-                rmSync(target, { force: true });
-        }
+        restoreFromJournal(project, journal, backup);
         rmSync(stage, { recursive: true, force: true });
         throw error;
     }