@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/commands/advance.js

@@ -1,10 +1,13 @@
 import { advanceWorkState } from "../core/phase.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export { advanceWorkState };
 
-export async function runAdvance({ target, packageRoot, to }) {
+export async function runAdvance({ target, packageRoot, to, taskId, task }) {
   if (!to) throw new Error("--to is required for advance");
-  return advanceWorkState(target, to, { packageRoot });
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "advance", async (ctx) => {
+    return advanceWorkState(target, to, { packageRoot, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatAdvanceResult(result) {

package/src/commands/audit.js

@@ -1,6 +1,16 @@
 import { evaluateAudit } from "../core/audit.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export { evaluateAudit as runAudit };
+export { evaluateAudit };
+
+export async function runAudit(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    return evaluateAudit({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatAuditResult(result) {
   const lines = [`FORGELOOP AUDIT: ${result.status}`];

package/src/commands/clear-continuity.js

@@ -1,7 +1,10 @@
 import { clearContinuity } from "../core/continuity.js";
+import { withTaskMutation } from "../core/task-command.js";
 
-export async function runClearContinuity({ target } = {}) {
-  return clearContinuity(target);
+export async function runClearContinuity({ target, taskId, task, packageRoot } = {}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "clear-continuity", async (ctx) => {
+    return clearContinuity(target, { taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatClearContinuityResult(result) {

package/src/commands/clear-state.js

@@ -1,9 +1,12 @@
 import { clearWorkState } from "../core/work-state.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export { clearWorkState };
 
-export async function runClearState({ target }) {
-  return clearWorkState(target);
+export async function runClearState({ target, taskId, task, packageRoot } = {}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "clear-state", async (ctx) => {
+    return clearWorkState(target, { taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatClearStateResult(result) {

package/src/commands/complete.js

@@ -1,6 +1,14 @@
 import { runComplete as evaluateAndComplete } from "../core/completion.js";
+import { withTaskMutation } from "../core/task-command.js";
 
-export { evaluateAndComplete as runComplete };
+export async function runComplete(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withTaskMutation(target, { taskId, packageRoot }, "complete", async (ctx) => {
+    return evaluateAndComplete({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatCompleteResult(result) {
   const lines = [`FORGELOOP COMPLETE: ${result.status}`];

package/src/commands/continuity.js

@@ -1,7 +1,10 @@
 import { reconcileContinuity } from "../core/continuity-reconciliation.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runContinuity({ target, packageRoot } = {}) {
-  return reconcileContinuity({ target, packageRoot });
+export async function runContinuity({ target, packageRoot, taskId, task } = {}) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
+    return reconcileContinuity({ target, packageRoot, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatContinuityResult(result) {

package/src/commands/inspect.js

@@ -1,6 +1,14 @@
-import { inspectTarget } from "../core/inspect.js";
+import { inspectTarget as coreInspectTarget } from "../core/inspect.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export { inspectTarget };
+export async function inspectTarget(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    return coreInspectTarget({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatInspectResult(report) {
   const lines = [

package/src/commands/next.js

@@ -1,7 +1,10 @@
 import { getNextAction } from "../core/next-action.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runNext({ target, packageRoot }) {
-  return getNextAction({ target, packageRoot });
+export async function runNext({ target, packageRoot, taskId, task }) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
+    return getNextAction({ target, packageRoot, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatNextActionResult(result) {

package/src/commands/preflight.js

@@ -1,6 +1,14 @@
 import { runPreflight as evaluateAndPersistPreflight } from "../core/preflight.js";
+import { withTaskMutation } from "../core/task-command.js";
 
-export { evaluateAndPersistPreflight as runPreflight };
+export async function runPreflight(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withTaskMutation(target, { taskId, packageRoot }, "preflight", async (ctx) => {
+    return evaluateAndPersistPreflight({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatPreflightResult(result) {
   const lines = [`FORGELOOP PREFLIGHT: ${result.status}`];

package/src/commands/prepare-completion.js

@@ -1,9 +1,12 @@
 import { prepareCompletion as prepareCompletionArtifacts } from "../core/completion-artifacts.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export { prepareCompletionArtifacts as prepareCompletion };
 
-export async function runPrepareCompletion({ target, packageRoot, authorityContext, runtimeContext }) {
-  return prepareCompletionArtifacts({ target, packageRoot, authorityContext, runtimeContext });
+export async function runPrepareCompletion({ target, packageRoot, authorityContext, runtimeContext, taskId, task, ...rest } = {}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "prepare-completion", async (ctx) => {
+    return prepareCompletionArtifacts({ target, packageRoot, authorityContext, runtimeContext, taskId: ctx?.taskId ?? null, ...rest });
+  });
 }
 
 export function formatPrepareCompletionResult(result) {

package/src/commands/reconcile-continuity.js

@@ -1,7 +1,10 @@
 import { reconcileContinuity } from "../core/continuity-reconciliation.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runReconcileContinuity({ target, packageRoot } = {}) {
-  return reconcileContinuity({ target, packageRoot });
+export async function runReconcileContinuity({ target, packageRoot, taskId, task } = {}) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
+    return reconcileContinuity({ target, packageRoot, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatReconcileContinuityResult(result) {

package/src/commands/record-check.js

@@ -1,9 +1,15 @@
 import { recordCheck as recordCheckArtifact } from "../core/completion-artifacts.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export { recordCheckArtifact as recordCheck };
 
 export async function runRecordCheck(input) {
-  return recordCheckArtifact(input);
+  const target = input.target;
+  const packageRoot = input.packageRoot;
+  const taskId = input.taskId ?? input.task ?? null;
+  return withTaskMutation(target, { taskId, packageRoot }, "record-check", async (ctx) => {
+    return recordCheckArtifact({ ...input, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatRecordCheckResult(result) {

package/src/commands/record-continuity.js

@@ -1,4 +1,5 @@
 import { writeContinuity } from "../core/continuity.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 function parseWorkItem(value, label) {
   if (typeof value !== "string") throw new Error(`${label} must use <id>:<summary>`);
@@ -27,24 +28,30 @@ export async function runRecordContinuity({
   repositoryFingerprint,
   now,
   dryRun = false,
+  taskId,
+  task,
 } = {}) {
   if ((focusId && !focusSummary) || (!focusId && focusSummary)) {
     throw new Error("record-continuity requires --focus-id and --focus-summary together");
   }
-  return writeContinuity(target, {
-    ...(focusId ? { currentFocus: { id: focusId, summary: focusSummary } } : {}),
-    remainingWork: remaining.map((item) => parseWorkItem(item, "--remaining")),
-    knownIssues: knownIssues.map((item) => parseWorkItem(item, "--known-issue")),
-    changedAreas,
-    inspectFirst,
-    ...(resumeNote ? { resumeNote } : {}),
-  }, {
-    packageRoot,
-    ...(state ? { state } : {}),
-    ...(contract ? { contract } : {}),
-    ...(repositoryFingerprint ? { repositoryFingerprint } : {}),
-    ...(now ? { now } : {}),
-    dryRun,
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-continuity", async (ctx) => {
+    const effectiveTaskId = ctx?.taskId ?? null;
+    return writeContinuity(target, {
+      ...(focusId ? { currentFocus: { id: focusId, summary: focusSummary } } : {}),
+      remainingWork: remaining.map((item) => parseWorkItem(item, "--remaining")),
+      knownIssues: knownIssues.map((item) => parseWorkItem(item, "--known-issue")),
+      changedAreas,
+      inspectFirst,
+      ...(resumeNote ? { resumeNote } : {}),
+    }, {
+      packageRoot,
+      ...(state ? { state } : {}),
+      ...(contract ? { contract } : {}),
+      ...(repositoryFingerprint ? { repositoryFingerprint } : {}),
+      ...(now ? { now } : {}),
+      dryRun,
+      taskId: effectiveTaskId,
+    });
   });
 }
 

package/src/commands/record-terminal-result.js

@@ -1,9 +1,15 @@
 import { recordTerminalResult as recordTerminalResultArtifact } from "../core/completion-artifacts.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export { recordTerminalResultArtifact as recordTerminalResult };
 
 export async function runRecordTerminalResult(input) {
-  return recordTerminalResultArtifact(input);
+  const target = input.target;
+  const packageRoot = input.packageRoot;
+  const taskId = input.taskId ?? input.task ?? null;
+  return withTaskMutation(target, { taskId, packageRoot }, "record-terminal-result", async (ctx) => {
+    return recordTerminalResultArtifact({ ...input, taskId: ctx?.taskId ?? null });
+  });
 }
 
 export function formatRecordTerminalResult(result) {

package/src/commands/route.js

@@ -1,26 +1,30 @@
 import { evaluateRoute } from "../core/router.js";
 import { persistRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
+import { withTaskMutation } from "../core/task-command.js";
 
-export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange }) {
-  const route = evaluateRoute({
-    workType,
-    surfaces,
-    risks,
-    platforms,
-    behaviorChange,
-    executableChange,
-  });
-  if (target && packageRoot) {
-    let contractFingerprint;
-    try {
-      contractFingerprint = (await readContract(target, packageRoot)).fingerprint;
-    } catch {
-      contractFingerprint = undefined;
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, taskId, task }) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "route", async (ctx) => {
+    const effectiveTaskId = ctx?.taskId ?? null;
+    const route = evaluateRoute({
+      workType,
+      surfaces,
+      risks,
+      platforms,
+      behaviorChange,
+      executableChange,
+    });
+    if (target && packageRoot) {
+      let contractFingerprint;
+      try {
+        contractFingerprint = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).fingerprint;
+      } catch {
+        contractFingerprint = undefined;
+      }
+      await persistRoute(target, route, packageRoot, { contractFingerprint, taskId: effectiveTaskId });
     }
-    await persistRoute(target, route, packageRoot, { contractFingerprint });
-  }
-  return route;
+    return route;
+  });
 }
 
 export function formatRouteResult(result) {

package/src/commands/run-check.js

@@ -3,6 +3,7 @@ import {
   recordCheck as recordCheckArtifact,
 } from "../core/completion-artifacts.js";
 import { runCommandExecution } from "../core/execution.js";
+import { withTaskMutation } from "../core/task-command.js";
 
 export async function runCheck({
   target,
@@ -13,57 +14,64 @@ export async function runCheck({
   details,
   authorityContext,
   runtimeContext,
+  taskId,
+  task,
 }) {
   if (typeof id !== "string" || id.trim() === "" || typeof requirement !== "string" || requirement.trim() === "") {
     const error = new Error("run-check requires non-empty id and requirement");
     error.code = "E_CHECK_INVALID";
     throw error;
   }
-  const ready = await assertRecordCheckPrerequisites({
-    target,
-    packageRoot,
-    requirement,
-    status: "passed",
-    evidenceKind: "OBSERVED",
-    authorityContext,
-    runtimeContext,
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "run-check", async (ctx) => {
+    const effectiveTaskId = ctx?.taskId ?? null;
+    const ready = await assertRecordCheckPrerequisites({
+      target,
+      packageRoot,
+      requirement,
+      status: "passed",
+      evidenceKind: "OBSERVED",
+      authorityContext,
+      runtimeContext,
+      taskId: effectiveTaskId,
+    });
+    const verificationCycle = ready.state.verificationCycle ?? 1;
+    const execution = await runCommandExecution({
+      target,
+      packageRoot,
+      taskId: ready.contract.value.taskId,
+      checkId: id,
+      requirement,
+      verificationCycle,
+      argv,
+      details,
+      authorityContext,
+      runtimeContext,
+    });
+    const status = execution.execution.status === "passed" ? "passed" : "failed";
+    const recorded = await recordCheckArtifact({
+      target,
+      packageRoot,
+      id,
+      kind: "command",
+      requirement,
+      status,
+      evidenceKind: "OBSERVED",
+      command: execution.execution.argv.join(" "),
+      result: execution.result,
+      ...(execution.execution.exitCode === null ? {} : { exitCode: execution.execution.exitCode }),
+      details,
+      executionRef: execution.execution.executionId,
+      provenance: "FORGELOOP_EXECUTED",
+      authorityContext,
+      runtimeContext,
+      taskId: effectiveTaskId,
+    });
+    return {
+      ...recorded,
+      execution: execution.execution,
+      executionPath: execution.path,
+    };
   });
-  const verificationCycle = ready.state.verificationCycle ?? 1;
-  const execution = await runCommandExecution({
-    target,
-    packageRoot,
-    taskId: ready.contract.value.taskId,
-    checkId: id,
-    requirement,
-    verificationCycle,
-    argv,
-    details,
-    authorityContext,
-    runtimeContext,
-  });
-  const status = execution.execution.status === "passed" ? "passed" : "failed";
-  const recorded = await recordCheckArtifact({
-    target,
-    packageRoot,
-    id,
-    kind: "command",
-    requirement,
-    status,
-    evidenceKind: "OBSERVED",
-    command: execution.execution.argv.join(" "),
-    result: execution.result,
-    ...(execution.execution.exitCode === null ? {} : { exitCode: execution.execution.exitCode }),
-    details,
-    executionRef: execution.execution.executionId,
-    provenance: "FORGELOOP_EXECUTED",
-    authorityContext,
-    runtimeContext,
-  });
-  return {
-    ...recorded,
-    execution: execution.execution,
-    executionPath: execution.path,
-  };
 }
 
 export function formatRunCheckResult(result) {

package/src/commands/status.js

@@ -1,19 +1,25 @@
 import { readAndClassifyWorkState } from "../core/work-state.js";
 import { inspectSchemaHealth } from "../core/schema-validation.js";
 import { reconcileContinuity } from "../core/continuity-reconciliation.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runStatus({ target, packageRoot, contractFile = null }) {
-  const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
-  const [protocol, continuity] = await Promise.all([
-    inspectSchemaHealth(target),
-    reconcileContinuity({ target, packageRoot }),
-  ]);
-  return {
-    ...state,
-    protocol,
-    continuity,
-    evidence: [...(state.evidence ?? []), ...(protocol.evidence ?? [])],
-  };
+export async function runStatus({ target, packageRoot, contractFile = null, taskId, task } = {}) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
+    const effectiveTaskId = ctx?.taskId ?? null;
+    const state = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId: effectiveTaskId });
+    const [protocol, continuity] = await Promise.all([
+      inspectSchemaHealth(target),
+      reconcileContinuity({ target, packageRoot, taskId: effectiveTaskId }),
+    ]);
+    return {
+      ...state,
+      taskId: effectiveTaskId,
+      taskKey: ctx?.taskKey ?? null,
+      protocol,
+      continuity,
+      evidence: [...(state.evidence ?? []), ...(protocol.evidence ?? [])],
+    };
+  });
 }
 
 export function formatStatusResult(result) {

package/src/commands/task-create.js

@@ -0,0 +1,94 @@
+import { readFile } from "node:fs/promises";
+import { assertTaskId } from "../core/task-identity.js";
+import { createTaskDescriptor, writeTaskDescriptor } from "../core/task-descriptor.js";
+import { normalizeWriteClaims, assertNoScopeConflicts, assertScopeClean } from "../core/task-scope.js";
+import { discoverTasks, findTaskById } from "../core/task-discovery.js";
+import { withProjectClaimsLock, withTaskLock } from "../core/task-lock.js";
+import { taskDirectory } from "../core/task-paths.js";
+import { ensureWithin, fileExists } from "../core/filesystem.js";
+import { validateContract, writeContract } from "../core/contract.js";
+import { appendProtocolEvent } from "../core/events.js";
+import { E_TASK_REQUIRED, E_TASK_ALREADY_EXISTS, E_TASK_DESCRIPTOR_INVALID } from "../core/error-codes.js";
+
+function taskError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+export async function runTaskCreate({ target, packageRoot, taskId, claims = [], contractFile = null } = {}) {
+  if (!taskId) {
+    throw taskError(E_TASK_REQUIRED, "--task is required for task-create");
+  }
+  assertTaskId(taskId);
+
+  const existing = await findTaskById(target, taskId, packageRoot);
+  if (existing) {
+    throw taskError(E_TASK_ALREADY_EXISTS, `Task already exists: ${taskId}`);
+  }
+
+  const normalizedClaims = normalizeWriteClaims(claims ?? []);
+
+  return withProjectClaimsLock(target, async () => {
+    const allTasks = await discoverTasks(target, packageRoot);
+    assertNoScopeConflicts(normalizedClaims, allTasks, taskId);
+    if (normalizedClaims.length > 0) {
+      await assertScopeClean(target, normalizedClaims);
+    }
+
+    return withTaskLock(target, taskId, "task-create", async () => {
+      const descriptor = createTaskDescriptor({
+        taskId,
+        writeClaims: normalizedClaims,
+      });
+      const written = await writeTaskDescriptor(target, descriptor, packageRoot);
+
+      let contractCopied = false;
+      if (contractFile) {
+        const sourcePath = ensureWithin(target, contractFile);
+        if (!(await fileExists(sourcePath))) {
+          throw taskError("E_CONTRACT_MISSING", `Specified contract file not found: ${contractFile}`);
+        }
+        const raw = await readFile(sourcePath, "utf8");
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          throw taskError("E_CONTRACT_INVALID", `Specified contract file is not valid JSON: ${contractFile}`);
+        }
+        await validateContract(parsed, packageRoot);
+        if (parsed.taskId && parsed.taskId !== taskId) {
+          throw taskError(
+            E_TASK_DESCRIPTOR_INVALID,
+            `Contract taskId "${parsed.taskId}" does not match requested taskId "${taskId}"`,
+          );
+        }
+        parsed.taskId = taskId;
+        await writeContract(target, parsed, packageRoot, { taskId });
+        contractCopied = true;
+      }
+
+      await appendProtocolEvent(target, {
+        taskId,
+        event: "TASK_RECEIVED",
+        details: { createdAt: descriptor.createdAt },
+      }, packageRoot, { taskId });
+
+      return {
+        taskId: descriptor.taskId,
+        taskKey: descriptor.taskKey,
+        directory: taskDirectory(taskId),
+        descriptorPath: written.path,
+        writeClaims: descriptor.writeClaims,
+        contractCopied,
+        createdAt: descriptor.createdAt,
+      };
+    });
+  });
+}
+
+export function formatTaskCreateResult(result) {
+  const claims = result.writeClaims.length === 0 ? "none" : result.writeClaims.join(", ");
+  return `created task: ${result.taskId}\nkey: ${result.taskKey}\ndirectory: ${result.directory}\nclaims: ${claims}\n`;
+}

package/src/commands/task-list.js

@@ -0,0 +1,48 @@
+import { discoverTasks } from "../core/task-discovery.js";
+
+export async function runTaskList({ target, packageRoot } = {}) {
+  const tasks = await discoverTasks(target, packageRoot);
+  return {
+    tasks: tasks.map((task) => {
+      if (task.healthy === false) {
+        return {
+          taskId: task.taskId ?? null,
+          taskKey: task.taskKey,
+          directory: task.directory,
+          healthy: false,
+          error: task.error,
+        };
+      }
+      return {
+        taskId: task.taskId,
+        taskKey: task.taskKey,
+        directory: task.directory,
+        healthy: true,
+        phase: task.phase,
+        writeClaims: task.writeClaims ?? [],
+        locked: task.locked,
+        hasContinuity: task.hasContinuity,
+        hasReceipt: task.hasReceipt,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      };
+    }),
+  };
+}
+
+export function formatTaskListResult(result) {
+  if (result.tasks.length === 0) {
+    return "no tasks found\n";
+  }
+  const lines = ["Tasks:"];
+  for (const task of result.tasks) {
+    if (task.healthy === false) {
+      lines.push(`- ${task.taskKey} [CORRUPT]: ${task.error?.message ?? "unhealthy task namespace"}`);
+    } else {
+      const lockStr = task.locked ? " [LOCKED]" : "";
+      const claimsStr = task.writeClaims.length > 0 ? ` (claims: ${task.writeClaims.join(", ")})` : "";
+      lines.push(`- ${task.taskId}: ${task.phase ?? "UNINITIALIZED"}${lockStr}${claimsStr}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/task-migrate.js

@@ -0,0 +1,34 @@
+import { migrateLegacyLayout } from "../core/task-migration.js";
+
+export async function runTaskMigrate({ target, packageRoot, dryRun = false } = {}) {
+  const result = await migrateLegacyLayout(target, { packageRoot, dryRun });
+  return result;
+}
+
+export function formatTaskMigrateResult(result) {
+  if (!result.migrated) {
+    if (result.dryRun) {
+      const lines = [
+        `[dry-run] task: ${result.taskId}`,
+        `key: ${result.taskKey}`,
+        `destination: ${result.targetDirectory}`,
+        "legacy artifacts:",
+        ...(result.legacyFiles ?? []).map((artifact) => `  - ${artifact}`),
+      ];
+
+      return `${lines.join("\n")}\n`;
+    }
+
+    return `${result.message ?? "no legacy layout detected; nothing to migrate"}\n`;
+  }
+
+  const lines = [
+    `migrated task: ${result.taskId}`,
+    `key: ${result.taskKey}`,
+    `destination: ${result.targetDirectory}`,
+    "migrated artifacts:",
+    ...(result.migratedArtifacts ?? []).map((artifact) => `  - ${artifact}`),
+  ];
+
+  return `${lines.join("\n")}\n`;
+}