@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/dist/chunk-L2CBG5IX.js

@@ -0,0 +1,1892 @@
+import {
+  findArchivedTaskPath,
+  locateTaskFile,
+  validateStateTransition
+} from "./chunk-7LHJDJB3.js";
+import {
+  normalizeTaskStatus
+} from "./chunk-NAINGKHF.js";
+import {
+  getArchivedFilePath
+} from "./chunk-US3RT6CY.js";
+import {
+  classifyTaskDependency
+} from "./chunk-NXH3RX7O.js";
+import {
+  assertCompletionContractsMet,
+  normalizeCompletionContracts,
+  recordUnverifiedCompletion
+} from "./chunk-MCBNWZNO.js";
+import {
+  getPlanningRoot,
+  withIndexRegeneration,
+  withPlanningLock
+} from "./chunk-CSXLLEGB.js";
+import {
+  bucketArchiveRootForProjectRoot
+} from "./chunk-VAG6GUBR.js";
+import {
+  assertBucketWriteAvailable
+} from "./chunk-AJBTKGJZ.js";
+import {
+  getBucketArchivePathByKind,
+  getBucketByName,
+  getBucketPathByKind
+} from "./chunk-V3KLVK7B.js";
+import {
+  signalCoordinator
+} from "./chunk-GC4CRMTS.js";
+import {
+  evaluateStaleReclaim
+} from "./chunk-P7CQGPLS.js";
+import {
+  assertSafePathComponent
+} from "./chunk-S2VQCZO4.js";
+import {
+  generateId
+} from "./chunk-4DJL2VXA.js";
+import {
+  assertSafePlanningFileId,
+  ensureDirectoryExists,
+  listMarkdownFiles,
+  listMarkdownFilesRecursive,
+  readMarkdownFile,
+  resolvePlanningItemPath,
+  writeMarkdownFile
+} from "./chunk-352PCJLK.js";
+import {
+  lockOwnerIsAlive,
+  processIsAlive,
+  readProcessIdentity
+} from "./chunk-MT2WAIR3.js";
+import {
+  BUILD_SPRINT_LOCK_RETRY_TIMEOUT_MS,
+  BUILD_SPRINT_LOCK_STALE_AFTER_MS,
+  emitCustomWarning,
+  readEnv
+} from "./chunk-7VRJHTGZ.js";
+
+// src/planning/sprint-manager.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+
+// src/planning/sprint-lock.ts
+import { randomUUID } from "crypto";
+import * as fs from "fs/promises";
+import * as path from "path";
+var heldSprintLocks = /* @__PURE__ */ new Map();
+var DEFAULT_LOCK_RETRY_TIMEOUT_MS = 3e4;
+var DEFAULT_LOCK_STALE_AFTER_MS = 30 * 6e4;
+var SPRINT_LOCK_HANDOFF_ENV = "BUILD_SPRINT_LOCK_HANDOFF_TOKEN";
+function shouldReclaimSprintLock(params) {
+  if (params.ownerToken === null) {
+    return false;
+  }
+  return evaluateStaleReclaim(
+    {
+      ageMs: params.ageMs,
+      holder: params.existingPid === null ? null : { sameHost: true, pidAlive: params.ownerAlive }
+    },
+    {
+      staleMs: getSprintLockStaleAfterMs(),
+      corruptPayload: "reclaim",
+      foreignHost: { kind: "never" },
+      ageBoundary: "gte",
+      sameHostDeadPid: "immediate"
+    }
+  ) === "reclaim";
+}
+function emitSprintLockWarning(message, metadata) {
+  emitCustomWarning(
+    "WARN" /* WARN */,
+    "workspace_edits" /* WORKSPACE_EDITS */,
+    message,
+    {
+      taskId: "sprint-lock",
+      subsystem: "planning/sprint-lock",
+      executionPhase: "execution"
+    },
+    { metadata, skipConsole: true }
+  );
+}
+function getSprintLockRetryTimeoutMs() {
+  return readEnv(BUILD_SPRINT_LOCK_RETRY_TIMEOUT_MS).value ?? DEFAULT_LOCK_RETRY_TIMEOUT_MS;
+}
+function getSprintLockStaleAfterMs() {
+  return readEnv(BUILD_SPRINT_LOCK_STALE_AFTER_MS).value ?? DEFAULT_LOCK_STALE_AFTER_MS;
+}
+function getSprintLockPath(sprintId) {
+  const safeSprintId = assertSafePathComponent(sprintId, "sprintId");
+  return path.join(getPlanningRoot(), ".build-project", `sprint-${safeSprintId}.lock`);
+}
+function getSprintActivationLockPath() {
+  return path.join(getPlanningRoot(), ".build-project", "sprint-activation.lock");
+}
+async function readSprintLockOwnerToken(lockPath) {
+  try {
+    const content = await fs.readFile(lockPath, "utf-8");
+    return content.trim().split("\n")[0] ?? "";
+  } catch {
+    return null;
+  }
+}
+async function readSprintLockSnapshot(lockPath) {
+  const snapshotPath = `${lockPath}.snapshot.${process.pid}.${Date.now().toString(36)}.${randomUUID()}`;
+  try {
+    await fs.link(lockPath, snapshotPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  try {
+    const [content, stat2] = await Promise.all([
+      fs.readFile(snapshotPath, "utf-8"),
+      fs.stat(snapshotPath)
+    ]);
+    const lines = content.trim().split("\n");
+    return {
+      ownerToken: lines[0] ?? "",
+      ownerIdentity: lines[2]?.trim() || void 0,
+      dev: stat2.dev,
+      ino: stat2.ino,
+      mtimeMs: stat2.mtimeMs
+    };
+  } finally {
+    await fs.unlink(snapshotPath).catch(() => void 0);
+  }
+}
+async function unlinkSprintLockIfOwnerStillMatches(lockPath, expectedOwnerToken, expectedIdentity) {
+  const reclaimPath = `${lockPath}.reclaim.${process.pid}.${Date.now().toString(36)}.${randomUUID()}`;
+  try {
+    await fs.link(lockPath, reclaimPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    const [content, reclaimStat] = await Promise.all([
+      fs.readFile(reclaimPath, "utf-8"),
+      fs.stat(reclaimPath)
+    ]);
+    const currentOwnerToken = content.trim().split("\n")[0] ?? "";
+    if (currentOwnerToken !== expectedOwnerToken) {
+      return false;
+    }
+    if (expectedIdentity && (reclaimStat.dev !== expectedIdentity.dev || reclaimStat.ino !== expectedIdentity.ino)) {
+      return false;
+    }
+    const currentStat = await fs.stat(lockPath).catch(() => null);
+    if (!currentStat || currentStat.dev !== reclaimStat.dev || currentStat.ino !== reclaimStat.ino) {
+      return false;
+    }
+    await fs.unlink(lockPath);
+    return true;
+  } finally {
+    await fs.unlink(reclaimPath).catch(() => void 0);
+  }
+}
+async function unlinkPartialSprintLock(lockPath) {
+  await fs.unlink(lockPath).catch((unlinkError) => {
+    if (unlinkError.code !== "ENOENT") throw unlinkError;
+  });
+}
+async function acquireNamedLock(lockKey, lockPath, busyLabel, retryTimeoutMs = getSprintLockRetryTimeoutMs()) {
+  const heldLock = heldSprintLocks.get(lockKey);
+  if (heldLock) {
+    heldLock.count += 1;
+    return {
+      ownerToken: heldLock.ownerToken,
+      release: async () => {
+        heldLock.count -= 1;
+        if (heldLock.count <= 0) {
+          heldSprintLocks.delete(lockKey);
+          await heldLock.releaseFileLock();
+        }
+      }
+    };
+  }
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  const retryDeadlineMs = Date.now() + retryTimeoutMs;
+  let judgedOwner;
+  const createHeldLease = (ownerToken, identity) => {
+    const cleanupName = `planning-sprint-lock:${lockKey}:${ownerToken}`;
+    const releaseFileLock = async () => {
+      try {
+        await unlinkSprintLockIfOwnerStillMatches(lockPath, ownerToken, identity);
+      } catch {
+      } finally {
+        signalCoordinator.unregister(cleanupName);
+      }
+    };
+    const held = {
+      count: 1,
+      ownerToken,
+      releaseFileLock
+    };
+    heldSprintLocks.set(lockKey, held);
+    const release = async () => {
+      held.count -= 1;
+      if (held.count <= 0) {
+        heldSprintLocks.delete(lockKey);
+        await held.releaseFileLock();
+      }
+    };
+    signalCoordinator.register(cleanupName, release, {
+      priority: "critical",
+      phase: "artifact-cleanup"
+    });
+    return { ownerToken, release };
+  };
+  while (true) {
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      const ownerToken = `${process.pid}:${randomUUID()}`;
+      const ownerIdentity = readProcessIdentity(process.pid) ?? "";
+      try {
+        await handle.writeFile(
+          `${ownerToken}
+${(/* @__PURE__ */ new Date()).toISOString()}
+${ownerIdentity}
+`,
+          "utf-8"
+        );
+        await handle.close();
+      } catch (writeError) {
+        await handle.close().catch(() => {
+        });
+        await unlinkPartialSprintLock(lockPath);
+        throw writeError;
+      }
+      const stat2 = await fs.stat(lockPath);
+      return createHeldLease(ownerToken, { dev: stat2.dev, ino: stat2.ino });
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      const snapshot = await readSprintLockSnapshot(lockPath);
+      const firstLine = snapshot?.ownerToken ?? null;
+      const parsedPid = firstLine === null ? Number.NaN : Number.parseInt(firstLine.split(":")[0] ?? "", 10);
+      const existingPid = Number.isFinite(parsedPid) && parsedPid > 0 ? parsedPid : null;
+      const handoffToken = process.env[SPRINT_LOCK_HANDOFF_ENV];
+      if (handoffToken && firstLine === handoffToken) {
+        await unlinkSprintLockIfOwnerStillMatches(lockPath, handoffToken, snapshot ?? void 0);
+        continue;
+      }
+      let ownerAlive = false;
+      if (existingPid !== null && firstLine !== null) {
+        if (judgedOwner?.token !== firstLine) {
+          judgedOwner = {
+            token: firstLine,
+            alive: lockOwnerIsAlive(existingPid, snapshot?.ownerIdentity)
+          };
+        }
+        ownerAlive = judgedOwner.alive && processIsAlive(existingPid);
+      }
+      try {
+        const ageMs = Date.now() - (snapshot?.mtimeMs ?? Date.now());
+        if (firstLine !== null && shouldReclaimSprintLock({
+          ageMs,
+          ownerToken: firstLine,
+          existingPid,
+          ownerAlive
+        })) {
+          if (existingPid === null) {
+            emitSprintLockWarning(
+              `[sprint-lock] Reclaiming stale lock ${path.basename(lockPath)} (unknown owner, lock age ${Math.round(ageMs / 1e3)}s exceeds threshold).`,
+              {
+                lockKey,
+                lockPath,
+                ageMs,
+                operation: "reclaim-stale-lock"
+              }
+            );
+          }
+          await unlinkSprintLockIfOwnerStillMatches(lockPath, firstLine, snapshot ?? void 0);
+          continue;
+        }
+      } catch {
+      }
+      if (Date.now() < retryDeadlineMs) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        continue;
+      }
+      throw new Error(`${busyLabel} is busy (PID ${existingPid ?? "unknown"})`);
+    }
+  }
+}
+async function acquireSprintLock(sprintId) {
+  const lease = await acquireSprintLockLease(sprintId);
+  return lease.release;
+}
+async function acquireSprintLockLease(sprintId) {
+  return acquireNamedLock(`sprint:${sprintId}`, getSprintLockPath(sprintId), `Sprint ${sprintId}`);
+}
+async function withSprintLock(sprintId, fn) {
+  return withPlanningLock(getPlanningRoot(), async () => {
+    const lease = await acquireNamedLock(
+      `sprint:${sprintId}`,
+      getSprintLockPath(sprintId),
+      `Sprint ${sprintId}`,
+      0
+    );
+    try {
+      return await fn();
+    } finally {
+      await lease.release();
+    }
+  });
+}
+async function withSprintActivationLock(fn) {
+  return withPlanningLock(getPlanningRoot(), async () => {
+    const lease = await acquireNamedLock(
+      "activation",
+      getSprintActivationLockPath(),
+      "Sprint activation",
+      0
+    );
+    try {
+      return await fn();
+    } finally {
+      await lease.release();
+    }
+  });
+}
+function getSprintLockHandoffEnv(ownerToken) {
+  return { [SPRINT_LOCK_HANDOFF_ENV]: ownerToken };
+}
+async function getSprintLockOwnerToken(sprintId) {
+  return readSprintLockOwnerToken(getSprintLockPath(sprintId));
+}
+async function refreshSprintLock(sprintId) {
+  const lockKey = `sprint:${sprintId}`;
+  const heldLock = heldSprintLocks.get(lockKey);
+  if (!heldLock) return false;
+  const lockPath = getSprintLockPath(sprintId);
+  try {
+    const currentOwnerToken = await readSprintLockOwnerToken(lockPath);
+    if (currentOwnerToken !== heldLock.ownerToken) return false;
+    const now = /* @__PURE__ */ new Date();
+    await fs.utimes(lockPath, now, now);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function unlockSprintLock(sprintId, options = {}) {
+  const lockPath = getSprintLockPath(sprintId);
+  const snapshot = await readSprintLockSnapshot(lockPath);
+  let ownerToken = "";
+  if (!snapshot) {
+    return { success: true, message: `Sprint ${sprintId} is not locked` };
+  }
+  ownerToken = snapshot.ownerToken;
+  const ownerPid = Number.parseInt(ownerToken.split(":")[0] ?? "0", 10);
+  const ownerAlive = lockOwnerIsAlive(ownerPid, snapshot.ownerIdentity);
+  if (ownerAlive && !options.force) {
+    return {
+      success: false,
+      message: `Sprint ${sprintId} is locked by live PID ${ownerPid}; rerun with --force only after confirming the run is hung`
+    };
+  }
+  await unlinkSprintLockIfOwnerStillMatches(lockPath, ownerToken, {
+    dev: snapshot.dev,
+    ino: snapshot.ino
+  });
+  return { success: true, message: `Unlocked sprint ${sprintId}` };
+}
+
+// src/planning/sprint-manager.ts
+function isGenuinelyAbsentTaskError(error) {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = error.code;
+    if (code === "ENOENT") return true;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Task not found");
+}
+var DEFAULT_SPRINT_CAPACITY_HOURS = 40;
+function parseTaskNumber(value, fallback) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+function coerceSprintTaskFrontMatter(frontMatter) {
+  const id = typeof frontMatter.id === "string" ? frontMatter.id : "";
+  if (!id) {
+    throw new Error('Invalid task frontmatter: missing required field "id"');
+  }
+  const originalSprintId = typeof frontMatter.originalSprintId === "string" && frontMatter.originalSprintId ? frontMatter.originalSprintId : void 0;
+  const sprintId = typeof frontMatter.sprintId === "string" && frontMatter.sprintId || typeof frontMatter.sprint_id === "string" && frontMatter.sprint_id || originalSprintId || "";
+  if (!sprintId) {
+    throw new Error(`Invalid task frontmatter for '${id}': missing required field "sprintId"`);
+  }
+  const statusRaw = typeof frontMatter.status === "string" ? frontMatter.status : "todo";
+  const priorityRaw = typeof frontMatter.priority === "string" ? frontMatter.priority : void 0;
+  const priority = priorityRaw === "P0" || priorityRaw === "P1" || priorityRaw === "P2" || priorityRaw === "P3" ? priorityRaw : void 0;
+  return {
+    id,
+    title: typeof frontMatter.title === "string" && frontMatter.title ? frontMatter.title : id,
+    priority,
+    estimatedHours: parseTaskNumber(frontMatter.estimatedHours, 0),
+    ...typeof frontMatter.expectedRuntimeMinutes === "number" && Number.isFinite(frontMatter.expectedRuntimeMinutes) && frontMatter.expectedRuntimeMinutes > 0 ? { expectedRuntimeMinutes: frontMatter.expectedRuntimeMinutes } : {},
+    status: normalizeTaskStatus(statusRaw),
+    sprintId,
+    originalSprintId,
+    backlogItemId: typeof frontMatter.backlogItemId === "string" ? frontMatter.backlogItemId : void 0,
+    planArtifactPath: typeof frontMatter.planArtifactPath === "string" ? frontMatter.planArtifactPath : void 0,
+    resultArtifactPath: typeof frontMatter.resultArtifactPath === "string" ? frontMatter.resultArtifactPath : void 0,
+    planStageId: typeof frontMatter.planStageId === "string" ? frontMatter.planStageId : void 0,
+    dependencies: Array.isArray(frontMatter.dependencies) ? frontMatter.dependencies.filter((value) => typeof value === "string") : [],
+    blockedReason: typeof frontMatter.blockedReason === "string" ? frontMatter.blockedReason : void 0,
+    lastTransitionReason: typeof frontMatter.lastTransitionReason === "string" ? frontMatter.lastTransitionReason.trim() || void 0 : void 0,
+    version: parseTaskNumber(frontMatter.version, 0),
+    completionContract: normalizeCompletionContracts(frontMatter.completionContract)
+  };
+}
+async function loadTaskLookupFromFile(filePath, isArchived) {
+  const { frontMatter } = await readMarkdownFile(filePath);
+  return {
+    yaml: coerceSprintTaskFrontMatter(frontMatter),
+    filePath,
+    isArchived
+  };
+}
+async function getTask(taskId, options = {}) {
+  const { filePath, isArchived } = await locateTaskFile(taskId, options);
+  return loadTaskLookupFromFile(filePath, isArchived);
+}
+async function archiveTaskForSprintClose(taskId, options) {
+  const planningRoot = getPlanningRoot();
+  const bucket = getBucketByName("task", planningRoot);
+  if (!bucket) {
+    throw new Error("Bucket not configured: task");
+  }
+  const lookup = await getTask(taskId, { includeArchive: true });
+  if (lookup.isArchived) {
+    return {};
+  }
+  if (await findArchivedTaskPath(taskId, planningRoot)) {
+    throw new Error(
+      `Task ${taskId} has both active and archived records. Completion is blocked to avoid overwriting managed state. Run build doctor for details; do not edit managed files manually.`
+    );
+  }
+  const { frontMatter, body } = await readMarkdownFile(lookup.filePath);
+  const rawTask = frontMatter;
+  const task = coerceSprintTaskFrontMatter(rawTask);
+  const forceCompletion = options.force ?? false;
+  if (!forceCompletion && (task.status === "blocked" || task.status === "cancelled")) {
+    throw new Error(
+      `Cannot complete task ${task.id} from status "${task.status}" without --force. Move it to in_progress/review first.`
+    );
+  }
+  if (task.status !== "done" && !(forceCompletion && (task.status === "blocked" || task.status === "cancelled"))) {
+    const transition = await validateStateTransition(planningRoot, taskId, task.status, "done");
+    if (!transition.success) {
+      const details = transition.errors?.length ? `: ${transition.errors.join("; ")}` : "";
+      throw new Error(`${transition.message}${details}`);
+    }
+  }
+  const gate = await assertCompletionContractsMet({
+    contracts: task.completionContract,
+    workingDir: options.completionContractRoot
+  });
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (forceCompletion && task.status !== "done") {
+    rawTask.forceCompletedFrom = task.status;
+    if (options.preserveBlockedReason && task.status === "blocked" && task.blockedReason) {
+      rawTask.originalBlockedReason = task.blockedReason;
+    }
+  }
+  rawTask.status = "done";
+  rawTask.version = task.version + 1;
+  rawTask.completed_at = now;
+  rawTask.updated_at = now;
+  rawTask.archivedAt = now;
+  rawTask.originalSprintId = task.sprintId;
+  delete rawTask.sprintId;
+  delete rawTask.sprint_id;
+  const archivedPath = getArchivedFilePath(bucket, task.id, now, planningRoot);
+  await ensureDirectoryExists(path2.dirname(archivedPath));
+  await writeMarkdownFile(archivedPath, rawTask, body);
+  await recordUnverifiedCompletion(archivedPath, gate.unverifiedLabel, now);
+  await fs2.unlink(lookup.filePath);
+  return { archivedPath, unverifiedLabel: gate.unverifiedLabel };
+}
+async function findSprintOverlapConflict(sprintsDir, startDate, endDate) {
+  const start = parseStrictDateOnly(startDate);
+  const end = parseStrictDateOnly(endDate);
+  if (!start || !end) return null;
+  const existing = await listMarkdownFiles(sprintsDir).catch(() => []);
+  for (const file of existing) {
+    try {
+      const { frontMatter } = await readMarkdownFile(file);
+      const fm = frontMatter;
+      if (fm.status === "completed") continue;
+      const existingId = typeof fm.id === "string" ? fm.id : "";
+      const existingStart = typeof fm.startDate === "string" ? fm.startDate : typeof fm.start_date === "string" ? fm.start_date : "";
+      const existingEnd = typeof fm.endDate === "string" ? fm.endDate : typeof fm.end_date === "string" ? fm.end_date : "";
+      if (!existingStart) continue;
+      if (existingStart === startDate) {
+        return {
+          conflictingSprintId: existingId,
+          conflictingStartDate: existingStart,
+          conflictingEndDate: existingEnd,
+          kind: "exact"
+        };
+      }
+      if (existingStart && existingEnd) {
+        const existingStartDate = parseStrictDateOnly(existingStart);
+        const existingEndDate = parseStrictDateOnly(existingEnd);
+        if (existingStartDate && existingEndDate && start.getTime() < existingEndDate.getTime() && end.getTime() > existingStartDate.getTime()) {
+          return {
+            conflictingSprintId: existingId,
+            conflictingStartDate: existingStart,
+            conflictingEndDate: existingEnd,
+            kind: "range"
+          };
+        }
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function emitSprintManagerWarning(message, metadata, severity = "WARN" /* WARN */) {
+  emitCustomWarning(
+    severity,
+    "configuration" /* CONFIGURATION */,
+    message,
+    {
+      subsystem: "planning/sprint-manager",
+      executionPhase: "execution"
+    },
+    { metadata, skipConsole: true }
+  );
+}
+function parseStrictDateOnly(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return null;
+  const [, yearText, monthText, dayText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return null;
+  }
+  return date;
+}
+async function ensureSprintDoesNotAlreadyLinkBacklogItem(sprintId, taskIds, backlogItemId) {
+  if (!backlogItemId) return;
+  for (const existingTaskId of taskIds) {
+    try {
+      const linkedTask = await getTask(existingTaskId, {
+        includeArchive: true
+      });
+      if (linkedTask.yaml.backlogItemId === backlogItemId) {
+        throw new Error(
+          `Backlog item ${backlogItemId} is already represented in sprint ${sprintId} by task ${existingTaskId}`
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("already represented in sprint")) {
+        throw error;
+      }
+      if (error instanceof Error && error.message.startsWith("Task not found:")) {
+        continue;
+      }
+      emitSprintManagerWarning(
+        `Could not inspect task ${existingTaskId} while checking sprint ${sprintId}`,
+        {
+          sprintId,
+          taskId: existingTaskId,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw new Error(
+        `Cannot safely add task to sprint ${sprintId}: existing task ${existingTaskId} could not be inspected`
+      );
+    }
+  }
+}
+function formatSprintStatusLabel(status) {
+  switch (status) {
+    case "planning":
+      return "Planning";
+    case "active":
+      return "Active";
+    case "completed":
+      return "Completed";
+    default:
+      return "Planning";
+  }
+}
+function formatSprintTaskStatusLabel(status) {
+  switch (status) {
+    case "todo":
+      return "todo";
+    case "in_progress":
+      return "in_progress";
+    case "review":
+      return "review";
+    case "done":
+      return "done";
+    case "blocked":
+      return "blocked";
+    case "cancelled":
+      return "cancelled";
+    default:
+      return "todo";
+  }
+}
+function renderSprintTasksSummaryTable(tasks) {
+  const header = "| Task | Estimated Hours | Status |\n|------|-----------------|--------|";
+  if (tasks.length === 0) {
+    return `${header}
+| (No tasks yet) | - | - |`;
+  }
+  const rows = tasks.map((t) => {
+    const taskCell = `${t.id}: ${t.title}`.replaceAll("\n", " ").trim();
+    const estimateCell = t.estimatedHours > 0 ? `${t.estimatedHours}h` : "-";
+    return `| ${taskCell} | ${estimateCell} | ${formatSprintTaskStatusLabel(t.status)} |`;
+  }).join("\n");
+  return `${header}
+${rows}`;
+}
+function updateSprintBodyOverview(body, sprint, tasks) {
+  const total = tasks.length;
+  const done = tasks.filter((t) => t.status === "done").length;
+  const progressLine = total === 0 ? "**Progress**: 0 tasks" : `**Progress**: ${done}/${total} tasks (${(done / total * 100).toFixed(1)}%)`;
+  let updated = body;
+  if (/^\*\*Status\*\*:/m.test(updated)) {
+    updated = updated.replace(
+      /^\*\*Status\*\*:\s*.*$/m,
+      `**Status**: ${formatSprintStatusLabel(sprint.status)}`
+    );
+  }
+  if (/^\*\*Progress\*\*:/m.test(updated)) {
+    updated = updated.replace(/^\*\*Progress\*\*:\s*.*$/m, progressLine);
+  }
+  return updated;
+}
+function updateSprintBodyTasksSummary(body, tasks) {
+  const table = renderSprintTasksSummaryTable(tasks);
+  const replacement = `## Tasks Summary
+
+${table}
+`;
+  if (/^## Tasks Summary\s*$/m.test(body)) {
+    const headingMatch = body.match(/^## Tasks Summary\s*$/m);
+    if (headingMatch?.index !== void 0) {
+      const sectionStart = headingMatch.index;
+      const afterHeadingIndex = sectionStart + headingMatch[0].length;
+      const rest = body.slice(afterHeadingIndex);
+      const nextSectionMatch = rest.match(/\n## /);
+      const sectionEnd = nextSectionMatch && nextSectionMatch.index !== void 0 ? afterHeadingIndex + nextSectionMatch.index + 1 : body.length;
+      return `${body.slice(0, sectionStart)}${replacement.trimEnd()}
+${body.slice(sectionEnd)}`;
+    }
+  }
+  if (/^## Notes\s*$/m.test(body)) {
+    return body.replace(/^## Notes\s*$/m, `${replacement}
+## Notes`);
+  }
+  return `${body.trimEnd()}
+
+${replacement}
+`;
+}
+async function listArchivedDoneTasksForSprint(sprintId) {
+  const planningRoot = getPlanningRoot();
+  const archiveRoot = getBucketArchivePathByKind("task", planningRoot);
+  const files = await listMarkdownFilesRecursive(archiveRoot).catch(() => []);
+  const tasks = [];
+  for (const file of files) {
+    if (path2.basename(file).toLowerCase() === "readme.md") {
+      continue;
+    }
+    try {
+      const { frontMatter } = await readMarkdownFile(file);
+      const fm = frontMatter;
+      const originalSprintId = typeof fm.originalSprintId === "string" ? fm.originalSprintId : void 0;
+      if (originalSprintId !== sprintId) {
+        continue;
+      }
+      if (fm.status !== "done") {
+        continue;
+      }
+      const id = typeof fm.id === "string" ? fm.id : path2.basename(file, ".md");
+      tasks.push({
+        id,
+        title: typeof fm.title === "string" ? fm.title : id,
+        status: "done",
+        estimatedHours: typeof fm.estimatedHours === "number" ? fm.estimatedHours : 0
+      });
+    } catch {
+    }
+  }
+  return tasks;
+}
+function applyDerivedSprintMetrics(sprint, tasks, archivedDoneHours = 0) {
+  if (!sprint.velocity) {
+    return;
+  }
+  if (!Number.isFinite(sprint.velocity.forecast)) {
+    sprint.velocity.forecast = sprint.capacity.totalHours;
+  }
+  const activeDoneHours = tasks.filter((task) => task.status === "done").reduce((sum, task) => sum + task.estimatedHours, 0);
+  sprint.velocity.actual = activeDoneHours + archivedDoneHours;
+}
+function sourceHasLegacyCapacity(frontMatter) {
+  return frontMatter.capacity != null && typeof frontMatter.capacity === "object" || frontMatter.total_capacity_hours != null || frontMatter.totalHours != null || frontMatter.total_capacity != null;
+}
+function sourceHasLegacyVelocity(frontMatter) {
+  return frontMatter.velocity != null && typeof frontMatter.velocity === "object";
+}
+function toPersistedSprintFrontMatter(sprint, sourceFrontMatter, options = {}) {
+  const persisted = { ...sprint };
+  const keepCapacity = options.authorLegacyScrum === true || sourceFrontMatter !== void 0 && sourceHasLegacyCapacity(sourceFrontMatter);
+  const keepVelocity = options.authorLegacyScrum === true || sourceFrontMatter !== void 0 && sourceHasLegacyVelocity(sourceFrontMatter);
+  if (!keepCapacity) {
+    delete persisted.capacity;
+  }
+  if (!keepVelocity) {
+    delete persisted.velocity;
+  }
+  return persisted;
+}
+async function writeSprintMarkdownFile(filePath, sprint, body, sourceFrontMatter, options = {}) {
+  await writeMarkdownFile(
+    filePath,
+    toPersistedSprintFrontMatter(sprint, sourceFrontMatter, options),
+    body
+  );
+}
+async function refreshSprintMarkdownById(sprintId, options = {}) {
+  const sprintPath = await resolveSprintPath(sprintId, {
+    includeArchive: options.includeArchive
+  });
+  const { frontMatter, body } = await readMarkdownFile(sprintPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  const tasks = await listTasksInSprint(sprintId);
+  const archivedDoneTasks = await listArchivedDoneTasksForSprint(sprintId);
+  const archivedDoneHours = archivedDoneTasks.reduce((sum, task) => sum + task.estimatedHours, 0);
+  applyDerivedSprintMetrics(sprint, tasks, archivedDoneHours);
+  const reportedTasks = [...tasks, ...archivedDoneTasks];
+  const updatedBody = updateSprintBodyTasksSummary(
+    updateSprintBodyOverview(body, sprint, reportedTasks),
+    reportedTasks
+  );
+  sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+  await writeSprintMarkdownFile(
+    sprintPath,
+    sprint,
+    updatedBody,
+    frontMatter
+  );
+}
+async function fileExists(filePath) {
+  try {
+    await fs2.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function assertSprintFileExists(sprintId, options = {}) {
+  const filePath = await resolveSprintPath(sprintId, options);
+  if (!await fileExists(filePath)) {
+    throw new Error(`Sprint not found: ${sprintId}`);
+  }
+  return filePath;
+}
+async function resolveSprintPath(sprintId, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const sprintsDir = getBucketPathByKind("sprint", planningRoot);
+  const activePath = resolvePlanningItemPath(sprintsDir, sprintId, { label: "sprintId" });
+  if (await fileExists(activePath)) {
+    return activePath;
+  }
+  if (!options.includeArchive) {
+    return activePath;
+  }
+  const archiveRoot = bucketArchiveRootForProjectRoot(planningRoot, "sprint", sprintsDir);
+  if (!await fileExists(archiveRoot)) {
+    return activePath;
+  }
+  const archivedFiles = await listMarkdownFilesRecursive(archiveRoot).catch(() => []);
+  const match = archivedFiles.find((file) => path2.basename(file) === `${sprintId}.md`);
+  if (!match) {
+    return activePath;
+  }
+  return match;
+}
+function parseNumber(value, fallback) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+function coerceDateString(value) {
+  if (typeof value === "string") return value;
+  if (value instanceof Date && !Number.isNaN(value.getTime())) {
+    return formatLocalDateString(value);
+  }
+  return "";
+}
+function formatLocalDateString(value) {
+  const year = value.getFullYear();
+  const month = `${value.getMonth() + 1}`.padStart(2, "0");
+  const day = `${value.getDate()}`.padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function coerceSprintCapacity(frontMatter) {
+  const capacity = frontMatter.capacity;
+  if (capacity && typeof capacity === "object") {
+    const totalHours2 = parseNumber(capacity.totalHours, 0);
+    const allocatedHours2 = parseNumber(capacity.allocatedHours, 0);
+    const remainingHours2 = parseNumber(capacity.remainingHours, totalHours2 - allocatedHours2);
+    const utilizationPercent2 = totalHours2 > 0 ? parseNumber(capacity.utilizationPercent, allocatedHours2 / totalHours2 * 100) : 0;
+    return { totalHours: totalHours2, allocatedHours: allocatedHours2, remainingHours: remainingHours2, utilizationPercent: utilizationPercent2 };
+  }
+  const totalHours = parseNumber(
+    frontMatter.total_capacity_hours ?? frontMatter.totalHours ?? frontMatter.total_capacity,
+    0
+  );
+  const allocatedHours = parseNumber(
+    frontMatter.planned_capacity_hours ?? frontMatter.allocated_hours ?? frontMatter.allocatedHours,
+    0
+  );
+  const remainingHours = totalHours > 0 ? Math.max(0, totalHours - allocatedHours) : 0;
+  const utilizationPercent = totalHours > 0 ? allocatedHours / totalHours * 100 : 0;
+  return { totalHours, allocatedHours, remainingHours, utilizationPercent };
+}
+function coerceSprintYAML(frontMatter) {
+  const id = typeof frontMatter.id === "string" ? frontMatter.id : "";
+  if (!id) {
+    throw new Error('Invalid sprint frontmatter: missing required field "id"');
+  }
+  assertSafePlanningFileId(id, "sprintId");
+  const kindRaw = typeof frontMatter.kind === "string" ? frontMatter.kind : "sprint";
+  const kind = kindRaw === "sprint" ? "sprint" : "sprint";
+  const title = typeof frontMatter.title === "string" && frontMatter.title || typeof frontMatter.name === "string" && frontMatter.name || id;
+  const name = typeof frontMatter.name === "string" && frontMatter.name || typeof frontMatter.title === "string" && frontMatter.title || id;
+  const startDate = coerceDateString(frontMatter.startDate) || coerceDateString(frontMatter.start_date) || "";
+  const endDate = coerceDateString(frontMatter.endDate) || coerceDateString(frontMatter.end_date) || "";
+  if (!startDate || !endDate) {
+    throw new Error(
+      `Invalid sprint frontmatter for '${id}': missing "startDate"/"endDate" (or legacy start_date/end_date)`
+    );
+  }
+  const goal = typeof frontMatter.goal === "string" ? frontMatter.goal : typeof frontMatter.goal_summary === "string" ? frontMatter.goal_summary : void 0;
+  const statusRaw = typeof frontMatter.status === "string" ? frontMatter.status : "planning";
+  const status = statusRaw === "active" || statusRaw === "planning" || statusRaw === "completed" ? statusRaw : "planning";
+  const taskIds = Array.isArray(frontMatter.taskIds) ? frontMatter.taskIds.filter((v) => typeof v === "string") : [];
+  const completedTaskIds = Array.isArray(frontMatter.completedTaskIds) ? frontMatter.completedTaskIds.filter((v) => typeof v === "string") : [];
+  const createdAt = typeof frontMatter.created_at === "string" && frontMatter.created_at || typeof frontMatter.createdAt === "string" && frontMatter.createdAt || typeof frontMatter.created === "string" && frontMatter.created || (/* @__PURE__ */ new Date()).toISOString();
+  const updatedAt = typeof frontMatter.updated_at === "string" && frontMatter.updated_at || typeof frontMatter.updatedAt === "string" && frontMatter.updatedAt || typeof frontMatter.updated === "string" && frontMatter.updated || createdAt;
+  const velocityRaw = frontMatter.velocity;
+  const velocity = velocityRaw && typeof velocityRaw === "object" ? {
+    forecast: parseNumber(velocityRaw.forecast, 0),
+    actual: parseNumber(velocityRaw.actual, 0)
+  } : void 0;
+  return {
+    ...frontMatter,
+    id,
+    kind,
+    title,
+    name,
+    startDate,
+    endDate,
+    goal,
+    status,
+    capacity: coerceSprintCapacity(frontMatter),
+    taskIds,
+    completedTaskIds,
+    velocity,
+    created_at: createdAt,
+    updated_at: updatedAt,
+    completed_at: typeof frontMatter.completed_at === "string" ? frontMatter.completed_at : void 0
+  };
+}
+async function createSprint(name, startDate, endDate, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const sprintsDir = getBucketPathByKind("sprint", planningRoot);
+  assertBucketWriteAvailable(planningRoot);
+  await ensureDirectoryExists(sprintsDir);
+  const start = parseStrictDateOnly(startDate);
+  const end = parseStrictDateOnly(endDate);
+  if (!start || !end) {
+    throw new Error(`Invalid sprint dates: start=${startDate} end=${endDate}`);
+  }
+  if (end.getTime() <= start.getTime()) {
+    throw new Error("Invalid sprint date range: endDate must be after startDate");
+  }
+  return withSprintActivationLock(async () => {
+    if (!options.allowDuplicateStartDate) {
+      const conflict = await findSprintOverlapConflict(sprintsDir, startDate, endDate);
+      if (conflict) {
+        const idSuffix = conflict.conflictingSprintId ? ` (${conflict.conflictingSprintId})` : "";
+        if (conflict.kind === "exact") {
+          throw Object.assign(
+            new Error(
+              `Sprint already active for date ${startDate}${idSuffix}. View it: build plan sprint status. Close it: build plan sprint close${conflict.conflictingSprintId ? ` ${conflict.conflictingSprintId}` : ""}.`
+            ),
+            { code: "SPRINT_ALREADY_EXISTS_FOR_DATE" }
+          );
+        } else {
+          throw new Error(
+            `Sprint date range overlaps existing sprint${idSuffix} (${conflict.conflictingStartDate} to ${conflict.conflictingEndDate}). View it: build plan sprint status. Close it: build plan sprint close${conflict.conflictingSprintId ? ` ${conflict.conflictingSprintId}` : ""}.`
+          );
+        }
+      }
+    }
+    const sprintId = generateId(/* @__PURE__ */ new Date());
+    const filePath = resolvePlanningItemPath(sprintsDir, sprintId, { label: "sprintId" });
+    try {
+      await fs2.access(filePath);
+      throw new Error(
+        `Sprint already active for date ${startDate}. View it: build plan sprint status. Close it: build plan sprint close.`
+      );
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    const authoredHours = typeof options.totalHours === "number" && Number.isFinite(options.totalHours) ? options.totalHours : void 0;
+    const totalHours = authoredHours ?? 0;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const sprint = {
+      id: sprintId,
+      kind: "sprint",
+      title: name,
+      name,
+      startDate,
+      endDate,
+      goal: options.goal,
+      status: "planning",
+      capacity: {
+        totalHours,
+        allocatedHours: 0,
+        remainingHours: totalHours,
+        utilizationPercent: 0
+      },
+      taskIds: [],
+      ...authoredHours !== void 0 ? {
+        velocity: {
+          forecast: authoredHours,
+          actual: 0
+        }
+      } : {},
+      created_at: now,
+      updated_at: now
+    };
+    const body = `# Sprint: ${name}
+
+**Duration**: ${startDate} to ${endDate}
+**Status**: ${formatSprintStatusLabel(sprint.status)}
+**Progress**: 0 tasks
+
+## Sprint Goal
+
+${options.goal || "No specific goal set"}
+
+## Tasks Summary
+
+${renderSprintTasksSummaryTable([])}
+
+## Notes
+
+Sprint created on ${now}
+`;
+    await withIndexRegeneration(planningRoot, async () => {
+      await writeSprintMarkdownFile(filePath, sprint, body, void 0, {
+        authorLegacyScrum: authoredHours !== void 0
+      });
+    });
+    return sprint;
+  });
+}
+async function getCurrentSprint() {
+  const planningRoot = getPlanningRoot();
+  const sprintsDir = getBucketPathByKind("sprint", planningRoot);
+  try {
+    const files = await listMarkdownFiles(sprintsDir);
+    if (files.length === 0) return null;
+    let activeCandidate = null;
+    let planningCandidate = null;
+    for (const file of files) {
+      let sprint;
+      try {
+        const { frontMatter } = await readMarkdownFile(file);
+        sprint = coerceSprintYAML(frontMatter);
+      } catch {
+        continue;
+      }
+      if (sprint.status === "active") {
+        activeCandidate = { yaml: sprint, filePath: file };
+      } else if (sprint.status === "planning") {
+        planningCandidate = { yaml: sprint, filePath: file };
+      }
+    }
+    return activeCandidate ?? planningCandidate;
+  } catch {
+    return null;
+  }
+}
+async function assertSprintAcceptsNewTask(sprintId) {
+  const activePath = await resolveSprintPath(sprintId);
+  const isActive = await fileExists(activePath);
+  const resolvedPath = isActive ? activePath : await resolveSprintPath(sprintId, { includeArchive: true });
+  if (!isActive && !await fileExists(resolvedPath)) {
+    throw new Error(`Sprint not found: ${sprintId}`);
+  }
+  const { frontMatter } = await readMarkdownFile(resolvedPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  if (sprint.status === "completed") {
+    throw new Error(`Cannot add task to completed sprint ${sprintId}`);
+  }
+  if (!isActive) {
+    throw new Error(`Cannot add task to archived sprint ${sprintId}`);
+  }
+}
+async function addTaskToSprint(sprintId, taskId, estimatedHours) {
+  const planningRoot = getPlanningRoot();
+  const filePath = await assertSprintFileExists(sprintId);
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  return withSprintLock(sprintId, async () => {
+    const { frontMatter, body } = await readMarkdownFile(filePath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (sprint.status === "completed") {
+      throw new Error(`Cannot add task ${taskId} to completed sprint ${sprintId}`);
+    }
+    if (sprint.taskIds.includes(taskId)) {
+      throw new Error(`Task ${taskId} is already in sprint ${sprintId}`);
+    }
+    const taskLookup = await getTask(taskId, { includeArchive: true });
+    if (taskLookup.isArchived) {
+      throw new Error(
+        `Cannot add archived task ${taskId} to sprint ${sprintId}; restore the task before assigning it`
+      );
+    }
+    await ensureSprintDoesNotAlreadyLinkBacklogItem(
+      sprintId,
+      sprint.taskIds,
+      taskLookup.yaml.backlogItemId
+    );
+    const taskDependencies = Array.isArray(taskLookup?.yaml?.dependencies) ? taskLookup.yaml.dependencies : [];
+    if (taskDependencies.length > 0) {
+      const unsatisfiedDependencies = [];
+      const completedTaskIds = new Set(sprint.completedTaskIds ?? []);
+      for (const dependencyId of taskDependencies) {
+        try {
+          const dependencyLookup = await getTask(dependencyId, {
+            includeArchive: true
+          });
+          if (!dependencyLookup) {
+            unsatisfiedDependencies.push(dependencyId);
+            continue;
+          }
+          const classification = classifyTaskDependency(dependencyId, {
+            task: {
+              status: dependencyLookup.yaml.status,
+              isArchived: dependencyLookup.isArchived
+            }
+          });
+          const isInSameSprint = dependencyLookup.yaml.sprintId === sprintId && sprint.taskIds.includes(dependencyId);
+          if (!classification.satisfied && !isInSameSprint) {
+            unsatisfiedDependencies.push(dependencyId);
+          }
+        } catch {
+          const classification = classifyTaskDependency(dependencyId, {
+            task: null,
+            recordedComplete: completedTaskIds.has(dependencyId)
+          });
+          if (!classification.satisfied) {
+            unsatisfiedDependencies.push(dependencyId);
+          }
+        }
+      }
+      if (unsatisfiedDependencies.length > 0) {
+        throw new Error(
+          `Task ${taskId} has unsatisfied dependency/dependencies not in sprint ${sprintId}: ${unsatisfiedDependencies.join(", ")}`
+        );
+      }
+    }
+    sprint.taskIds.push(taskId);
+    sprint.completedTaskIds = (sprint.completedTaskIds ?? []).filter((id) => id !== taskId);
+    sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    let allocatedHours = 0;
+    for (const id of sprint.taskIds) {
+      try {
+        const taskPath = resolvePlanningItemPath(tasksDir, id, { label: "taskId" });
+        const { frontMatter: taskFrontMatter } = await readMarkdownFile(taskPath);
+        const tfm = taskFrontMatter;
+        const taskHours = typeof tfm.estimatedHours === "number" ? tfm.estimatedHours : 0;
+        allocatedHours += taskHours;
+      } catch {
+        if (id === taskId) {
+          allocatedHours += estimatedHours;
+        }
+      }
+    }
+    sprint.capacity.allocatedHours = allocatedHours;
+    sprint.capacity.remainingHours = Math.max(0, sprint.capacity.totalHours - allocatedHours);
+    sprint.capacity.utilizationPercent = sprint.capacity.totalHours > 0 ? allocatedHours / sprint.capacity.totalHours * 100 : 0;
+    await withIndexRegeneration(planningRoot, async () => {
+      const { frontMatter: taskFrontMatter, body: taskBody } = await readMarkdownFile(
+        taskLookup.filePath
+      );
+      const rawTask = taskFrontMatter;
+      const currentSprintId = typeof rawTask.sprintId === "string" ? rawTask.sprintId : typeof rawTask.sprint_id === "string" ? rawTask.sprint_id : void 0;
+      if (currentSprintId && currentSprintId !== sprintId) {
+        let stillLinkedToCurrentSprint = false;
+        try {
+          const currentSprintPath = await resolveSprintPath(currentSprintId, {
+            includeArchive: false
+          });
+          const { frontMatter: currentSprintFrontMatter } = await readMarkdownFile(currentSprintPath);
+          const currentSprint = coerceSprintYAML(
+            currentSprintFrontMatter
+          );
+          stillLinkedToCurrentSprint = currentSprint.taskIds.includes(taskId);
+        } catch {
+          stillLinkedToCurrentSprint = false;
+        }
+        if (stillLinkedToCurrentSprint) {
+          throw new Error(
+            `Task ${taskId} is already assigned to sprint ${currentSprintId}; remove it before adding to ${sprintId}`
+          );
+        }
+      }
+      rawTask.sprintId = sprintId;
+      delete rawTask.sprint_id;
+      rawTask.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+      rawTask.version = parseTaskNumber(rawTask.version, 0) + 1;
+      await writeMarkdownFile(
+        taskLookup.filePath,
+        rawTask,
+        taskBody
+      );
+      await writeSprintMarkdownFile(filePath, sprint, body, frontMatter);
+      try {
+        await refreshSprintMarkdownById(sprintId, { includeArchive: false });
+      } catch {
+      }
+    });
+    return sprint;
+  });
+}
+async function removeTaskFromSprint(sprintId, taskId, _estimatedHours) {
+  const planningRoot = getPlanningRoot();
+  const filePath = resolvePlanningItemPath(getBucketPathByKind("sprint", planningRoot), sprintId, {
+    label: "sprintId"
+  });
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  return withSprintLock(sprintId, async () => {
+    const { frontMatter, body } = await readMarkdownFile(filePath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (sprint.status === "completed") {
+      throw new Error(`Cannot remove task ${taskId} from completed sprint ${sprintId}`);
+    }
+    if (!sprint.taskIds.includes(taskId)) {
+      return sprint;
+    }
+    sprint.taskIds = sprint.taskIds.filter((id) => id !== taskId);
+    sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    let allocatedHours = 0;
+    for (const id of sprint.taskIds) {
+      try {
+        const taskPath = resolvePlanningItemPath(tasksDir, id, { label: "taskId" });
+        const { frontMatter: taskFrontMatter } = await readMarkdownFile(taskPath);
+        const tfm = taskFrontMatter;
+        const taskHours = typeof tfm.estimatedHours === "number" ? tfm.estimatedHours : 0;
+        allocatedHours += taskHours;
+      } catch {
+      }
+    }
+    sprint.capacity.allocatedHours = allocatedHours;
+    sprint.capacity.remainingHours = Math.max(0, sprint.capacity.totalHours - allocatedHours);
+    sprint.capacity.utilizationPercent = sprint.capacity.totalHours > 0 ? allocatedHours / sprint.capacity.totalHours * 100 : 0;
+    await withIndexRegeneration(planningRoot, async () => {
+      try {
+        const taskLookup = await getTask(taskId, { includeArchive: true });
+        const { frontMatter: taskFrontMatter, body: taskBody } = await readMarkdownFile(
+          taskLookup.filePath
+        );
+        const rawTask = taskFrontMatter;
+        if (rawTask.sprintId === sprintId || rawTask.sprint_id === sprintId) {
+          if (!rawTask.originalSprintId) {
+            rawTask.originalSprintId = rawTask.sprintId ?? rawTask.sprint_id;
+          }
+          delete rawTask.sprintId;
+          delete rawTask.sprint_id;
+          rawTask.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+          rawTask.version = parseTaskNumber(rawTask.version, 0) + 1;
+          await writeMarkdownFile(
+            taskLookup.filePath,
+            rawTask,
+            taskBody
+          );
+        }
+      } catch {
+      }
+      await writeSprintMarkdownFile(filePath, sprint, body, frontMatter);
+      try {
+        await refreshSprintMarkdownById(sprintId, { includeArchive: false });
+      } catch {
+      }
+    });
+    return sprint;
+  });
+}
+async function detachArchivedTaskFromSprint(sprintId, taskId, options = {}) {
+  const planningRoot = getPlanningRoot();
+  let filePath;
+  try {
+    filePath = await resolveSprintPath(sprintId, { includeArchive: true });
+  } catch (error) {
+    if (error instanceof Error && error.message.includes(`Sprint not found: ${sprintId}`)) {
+      const notFound = new Error(error.message);
+      notFound.code = "ENOENT";
+      throw notFound;
+    }
+    throw error;
+  }
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  return withSprintLock(sprintId, async () => {
+    const { frontMatter, body } = await readMarkdownFile(filePath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (!sprint.taskIds.includes(taskId)) {
+      return sprint;
+    }
+    sprint.taskIds = sprint.taskIds.filter((id) => id !== taskId);
+    if (options.completed) {
+      sprint.completedTaskIds = [.../* @__PURE__ */ new Set([...sprint.completedTaskIds ?? [], taskId])];
+    }
+    sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    let allocatedHours = 0;
+    for (const id of sprint.taskIds) {
+      try {
+        const taskPath = resolvePlanningItemPath(tasksDir, id, { label: "taskId" });
+        const { frontMatter: taskFrontMatter } = await readMarkdownFile(taskPath);
+        const tfm = taskFrontMatter;
+        const taskHours = typeof tfm.estimatedHours === "number" ? tfm.estimatedHours : 0;
+        allocatedHours += taskHours;
+      } catch {
+      }
+    }
+    sprint.capacity.allocatedHours = allocatedHours;
+    sprint.capacity.remainingHours = Math.max(0, sprint.capacity.totalHours - allocatedHours);
+    sprint.capacity.utilizationPercent = sprint.capacity.totalHours > 0 ? allocatedHours / sprint.capacity.totalHours * 100 : 0;
+    await withIndexRegeneration(planningRoot, async () => {
+      await writeSprintMarkdownFile(filePath, sprint, body, frontMatter);
+      try {
+        await refreshSprintMarkdownById(sprintId, { includeArchive: true });
+      } catch {
+      }
+    });
+    return sprint;
+  });
+}
+async function isTaskRecordedCompletedInSprint(sprintId, taskId) {
+  const sprintPath = await resolveSprintPath(sprintId, { includeArchive: true });
+  const { frontMatter } = await readMarkdownFile(sprintPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  return (sprint.completedTaskIds ?? []).includes(taskId);
+}
+async function assertSprintCanAcceptRestoredTask(sprintId, taskId) {
+  const sprintPath = await resolveSprintPath(sprintId, { includeArchive: true });
+  if (!await fileExists(sprintPath)) {
+    return { sprintExists: false, alreadyMember: false };
+  }
+  const { frontMatter } = await readMarkdownFile(sprintPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  if (sprint.status === "completed") {
+    throw new Error(
+      `Cannot restore task ${taskId} into completed sprint ${sprintId}; reopen the sprint or restore the task into an active sprint first.`
+    );
+  }
+  return { sprintExists: true, alreadyMember: sprint.taskIds.includes(taskId) };
+}
+async function calculateCapacity(sprintId) {
+  const filePath = await assertSprintFileExists(sprintId, { includeArchive: true });
+  const { frontMatter } = await readMarkdownFile(filePath);
+  const sprint = coerceSprintYAML(frontMatter);
+  let allocatedHours = 0;
+  for (const id of sprint.taskIds) {
+    try {
+      const taskHours = (await getTask(id, { includeArchive: true })).yaml.estimatedHours ?? 0;
+      allocatedHours += taskHours;
+    } catch {
+    }
+  }
+  const remainingHours = Math.max(0, sprint.capacity.totalHours - allocatedHours);
+  const utilizationPercent = sprint.capacity.totalHours > 0 ? allocatedHours / sprint.capacity.totalHours * 100 : 0;
+  return {
+    totalHours: sprint.capacity.totalHours,
+    allocatedHours,
+    remainingHours,
+    utilizationPercent
+  };
+}
+function checkCapacityWarning(capacity, additionalHours = 0) {
+  if (capacity.totalHours <= 0) {
+    return null;
+  }
+  const projectedAllocation = capacity.allocatedHours + additionalHours;
+  const projectedUtilization = projectedAllocation / capacity.totalHours * 100;
+  if (projectedUtilization > 100) {
+    return {
+      level: "error",
+      message: `Sprint overcommitted: ${projectedAllocation}h / ${capacity.totalHours}h (${projectedUtilization.toFixed(1)}% utilization)`
+    };
+  }
+  if (projectedUtilization >= 80) {
+    return {
+      level: "warning",
+      message: `Approaching capacity: ${projectedAllocation}h / ${capacity.totalHours}h (${projectedUtilization.toFixed(1)}% utilization)`
+    };
+  }
+  return null;
+}
+async function listTasksInSprint(sprintId) {
+  const sprintPath = await assertSprintFileExists(sprintId, {
+    includeArchive: true
+  });
+  const { frontMatter } = await readMarkdownFile(sprintPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  const tasks = [];
+  for (const taskId of sprint.taskIds) {
+    try {
+      const result = await getTask(taskId, { includeArchive: true });
+      if (result.isArchived) {
+        continue;
+      }
+      const taskFrontMatter = result.yaml;
+      const rawStatus = taskFrontMatter.status;
+      tasks.push({
+        id: taskFrontMatter.id ?? taskId,
+        title: taskFrontMatter.title ?? taskId,
+        priority: taskFrontMatter.priority,
+        estimatedHours: taskFrontMatter.estimatedHours ?? 0,
+        ...typeof taskFrontMatter.expectedRuntimeMinutes === "number" && taskFrontMatter.expectedRuntimeMinutes > 0 ? { expectedRuntimeMinutes: taskFrontMatter.expectedRuntimeMinutes } : {},
+        status: typeof rawStatus === "string" && ["todo", "in_progress", "review", "done", "blocked", "cancelled"].includes(rawStatus) ? rawStatus : "todo",
+        planArtifactPath: taskFrontMatter.planArtifactPath,
+        resultArtifactPath: taskFrontMatter.resultArtifactPath,
+        planStageId: taskFrontMatter.planStageId,
+        blockedReason: taskFrontMatter.blockedReason,
+        lastTransitionReason: taskFrontMatter.lastTransitionReason
+      });
+    } catch (error) {
+      if (!isGenuinelyAbsentTaskError(error)) {
+        throw error;
+      }
+      tasks.push({
+        id: taskId,
+        title: `(Missing Task: ${taskId})`,
+        estimatedHours: 0,
+        status: "todo",
+        missing: true
+      });
+    }
+  }
+  return tasks;
+}
+function computeSprintTerminalReadiness(tasks) {
+  const missingTaskIds = tasks.filter((t) => t.missing === true).map((t) => t.id);
+  const realTasks = tasks.filter((t) => t.missing !== true);
+  const incompleteTaskIds = realTasks.filter((t) => t.status !== "done").map((t) => t.id);
+  const allDone = realTasks.length > 0 && incompleteTaskIds.length === 0;
+  const ready = allDone && missingTaskIds.length === 0;
+  return { ready, allDone, incompleteTaskIds, missingTaskIds };
+}
+function assertSprintTerminalReady(sprintId, tasks, options = {}) {
+  const readiness = computeSprintTerminalReadiness(tasks);
+  if (options.force) return readiness;
+  const issues = [];
+  if (readiness.incompleteTaskIds.length > 0) {
+    issues.push(
+      `${readiness.incompleteTaskIds.length} task(s) not completed: ${readiness.incompleteTaskIds.join(", ")}`
+    );
+  }
+  if (readiness.missingTaskIds.length > 0) {
+    issues.push(
+      `${readiness.missingTaskIds.length} missing task ref(s): ${readiness.missingTaskIds.join(", ")} (run \`build plan sprint prune-missing ${sprintId}\` or pass --force)`
+    );
+  }
+  if (issues.length > 0) {
+    throw new Error(
+      `Cannot close sprint ${sprintId}: ${issues.join("; ")}. Use --force to override.`
+    );
+  }
+  return readiness;
+}
+async function countArchivedTasksForSprint(sprintId, status) {
+  const planningRoot = getPlanningRoot();
+  const archiveRoot = getBucketArchivePathByKind("task", planningRoot);
+  const files = await listMarkdownFilesRecursive(archiveRoot).catch(() => []);
+  let count = 0;
+  for (const file of files) {
+    if (path2.basename(file).toLowerCase() === "readme.md") {
+      continue;
+    }
+    try {
+      const { frontMatter } = await readMarkdownFile(file);
+      const fm = frontMatter;
+      const originalSprintId = typeof fm.originalSprintId === "string" ? fm.originalSprintId : void 0;
+      if (originalSprintId === sprintId && (status === void 0 || fm.status === status)) {
+        count++;
+      }
+    } catch {
+    }
+  }
+  return count;
+}
+async function findReadySprintsForBatchClose() {
+  const sprints = await listSprints(false);
+  const ready = [];
+  const skipped = [];
+  for (const sprint of sprints) {
+    if (sprint.status !== "active" && sprint.status !== "planning") {
+      continue;
+    }
+    const tasks = await listTasksInSprint(sprint.id);
+    const readiness = computeSprintTerminalReadiness(tasks);
+    if (readiness.ready) {
+      ready.push({ sprintId: sprint.id, totalTasks: tasks.length });
+      continue;
+    }
+    if (tasks.length === 0) {
+      const archivedTaskCount = await countArchivedTasksForSprint(sprint.id);
+      if (archivedTaskCount > 0 || sprint.taskIds.length > 0) {
+        ready.push({
+          sprintId: sprint.id,
+          totalTasks: archivedTaskCount > 0 ? archivedTaskCount : sprint.taskIds.length
+        });
+      }
+      continue;
+    }
+    if (readiness.allDone && readiness.missingTaskIds.length > 0) {
+      skipped.push({
+        sprintId: sprint.id,
+        reason: `${readiness.missingTaskIds.length} missing task ref(s); run prune-missing or close --force`
+      });
+    }
+  }
+  return { ready, skipped };
+}
+async function refreshSprintMarkdown(sprintId) {
+  await refreshSprintMarkdownById(sprintId, { includeArchive: false });
+}
+async function activateSprint(sprintId) {
+  await withSprintActivationLock(async () => {
+    const sprintPath = await resolveSprintPath(sprintId, {
+      includeArchive: false
+    });
+    const { frontMatter, body } = await readMarkdownFile(sprintPath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (sprint.status !== "planning") {
+      return;
+    }
+    sprint.status = "active";
+    sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    const tasks = await listTasksInSprint(sprintId);
+    const reportedTasks = [...tasks, ...await listArchivedDoneTasksForSprint(sprintId)];
+    const updatedBody = updateSprintBodyTasksSummary(
+      updateSprintBodyOverview(body, sprint, reportedTasks),
+      reportedTasks
+    );
+    await withIndexRegeneration(getPlanningRoot(), async () => {
+      await writeSprintMarkdownFile(
+        sprintPath,
+        sprint,
+        updatedBody,
+        frontMatter
+      );
+    });
+    const planningRoot = getPlanningRoot();
+    const sprintsDir = getBucketPathByKind("sprint", planningRoot);
+    const allFiles = await listMarkdownFiles(sprintsDir).catch(() => []);
+    for (const file of allFiles) {
+      if (file === sprintPath) continue;
+      try {
+        await withSprintLock(path2.basename(file, ".md"), async () => {
+          const { frontMatter: otherFm, body: otherBody } = await readMarkdownFile(file);
+          const other = coerceSprintYAML(otherFm);
+          if (other.status === "active") {
+            other.status = "planning";
+            other.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+            await writeSprintMarkdownFile(
+              file,
+              other,
+              otherBody,
+              otherFm
+            );
+          }
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("is busy") || message.includes("Timed out")) {
+          throw new Error(
+            `Cannot activate sprint ${sprintId}: another sprint file is locked (${path2.basename(file)}): ${message}`
+          );
+        }
+        emitSprintManagerWarning("Skipped sprint deactivation check during activation", {
+          sprintId,
+          file: path2.basename(file),
+          error: message
+        });
+      }
+    }
+  });
+}
+async function completeSprint(sprintId, options = {}) {
+  const forceTaskCompletion = options.forceTaskCompletion ?? false;
+  const planningRoot = getPlanningRoot();
+  const currentPath = resolvePlanningItemPath(
+    getBucketPathByKind("sprint", planningRoot),
+    sprintId,
+    { label: "sprintId" }
+  );
+  const archivedTaskPaths = [];
+  const unverifiedTasks = [];
+  let touchedPaths = [];
+  return withSprintLock(sprintId, async () => {
+    const sprintPath = await resolveSprintPath(sprintId, {
+      includeArchive: true
+    });
+    const { frontMatter, body } = await readMarkdownFile(sprintPath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (sprintPath !== currentPath && sprint.status === "completed") {
+      return { sprint, archivedPath: sprintPath, archivedTaskPaths: [], touchedPaths: [] };
+    }
+    sprint.status = "completed";
+    sprint.completed_at = (/* @__PURE__ */ new Date()).toISOString();
+    sprint.updated_at = sprint.completed_at;
+    const completedAt = sprint.completed_at;
+    const tasks = await listTasksInSprint(sprintId);
+    const archivedDoneTasks = await listArchivedDoneTasksForSprint(sprintId);
+    const archivedDoneHours = archivedDoneTasks.reduce((sum, task) => sum + task.estimatedHours, 0);
+    applyDerivedSprintMetrics(sprint, tasks, archivedDoneHours);
+    assertSprintTerminalReady(sprintId, tasks, { force: forceTaskCompletion });
+    const sprintBucket = getBucketByName("sprint", planningRoot);
+    if (!sprintBucket) throw new Error("Bucket not configured: sprint");
+    const archivedPath = getArchivedFilePath(sprintBucket, sprintId, completedAt, planningRoot);
+    const reportedTasks = [...tasks, ...archivedDoneTasks];
+    const updatedBody = updateSprintBodyTasksSummary(
+      updateSprintBodyOverview(body, sprint, reportedTasks),
+      reportedTasks
+    );
+    await withIndexRegeneration(planningRoot, async () => {
+      const sprintRollbackSnapshot = {
+        filePath: currentPath,
+        frontMatter,
+        body
+      };
+      const completedTaskSnapshots = [];
+      const rollbackCompletedTasks = async () => {
+        const rollbackFailures = [];
+        for (const snapshot of completedTaskSnapshots.reverse()) {
+          try {
+            await ensureDirectoryExists(path2.dirname(snapshot.activePath));
+            await writeMarkdownFile(snapshot.activePath, snapshot.frontMatter, snapshot.body);
+            await fs2.unlink(snapshot.archivedPath).catch(() => void 0);
+          } catch (rollbackErr) {
+            rollbackFailures.push(
+              `${snapshot.taskId}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`
+            );
+          }
+        }
+        try {
+          await writeMarkdownFile(
+            sprintRollbackSnapshot.filePath,
+            sprintRollbackSnapshot.frontMatter,
+            sprintRollbackSnapshot.body
+          );
+        } catch (rollbackErr) {
+          rollbackFailures.push(
+            `${sprintId}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`
+          );
+        }
+        return rollbackFailures;
+      };
+      const warnRollbackFailures = (rollbackFailures) => {
+        if (rollbackFailures.length > 0) {
+          emitSprintManagerWarning(
+            "Partial rollback during completeSprint; manual recovery required",
+            {
+              sprintId,
+              failures: rollbackFailures
+            },
+            "ERROR" /* ERROR */
+          );
+        }
+      };
+      for (const taskId of sprint.taskIds) {
+        try {
+          let taskSnapshot;
+          try {
+            const taskLookup = await getTask(taskId, { includeArchive: true });
+            if (!taskLookup.isArchived) {
+              const { frontMatter: taskFrontMatter, body: taskBody } = await readMarkdownFile(
+                taskLookup.filePath
+              );
+              taskSnapshot = {
+                activePath: taskLookup.filePath,
+                frontMatter: taskFrontMatter,
+                body: taskBody
+              };
+            }
+          } catch (snapshotError) {
+            const errorMessage = snapshotError instanceof Error ? snapshotError.message : String(snapshotError);
+            if (errorMessage.includes("Task not found")) {
+              continue;
+            }
+            throw snapshotError;
+          }
+          const completed = await archiveTaskForSprintClose(taskId, {
+            force: forceTaskCompletion,
+            preserveBlockedReason: true,
+            completionContractRoot: planningRoot
+          });
+          if (completed?.unverifiedLabel) {
+            unverifiedTasks.push({ taskId, label: completed.unverifiedLabel });
+          }
+          if (taskSnapshot) {
+            const archivedPath2 = completed?.archivedPath;
+            if (archivedPath2) {
+              completedTaskSnapshots.push({
+                taskId,
+                activePath: taskSnapshot.activePath,
+                archivedPath: archivedPath2,
+                frontMatter: taskSnapshot.frontMatter,
+                body: taskSnapshot.body
+              });
+              archivedTaskPaths.push({
+                id: taskId,
+                activePath: taskSnapshot.activePath,
+                archivedPath: archivedPath2
+              });
+            }
+          }
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          if (!errorMessage.includes("Task not found")) {
+            warnRollbackFailures(await rollbackCompletedTasks());
+            throw error;
+          }
+        }
+      }
+      try {
+        await ensureDirectoryExists(path2.dirname(archivedPath));
+        await writeSprintMarkdownFile(
+          archivedPath,
+          sprint,
+          updatedBody,
+          frontMatter
+        );
+        await fs2.unlink(currentPath);
+      } catch (error) {
+        await fs2.unlink(archivedPath).catch(() => void 0);
+        warnRollbackFailures(await rollbackCompletedTasks());
+        throw error;
+      }
+      const { completeSprintDependents } = await import("./sprint-completion-dependents-34SR7JVL.js");
+      const completionFiles = { planningRoot, currentPath, archivedPath, archivedTaskPaths };
+      touchedPaths = await completeSprintDependents(completionFiles, emitSprintManagerWarning);
+    });
+    return {
+      sprint,
+      archivedPath,
+      archivedTaskPaths,
+      touchedPaths,
+      ...unverifiedTasks.length > 0 ? { unverifiedTasks } : {}
+    };
+  });
+}
+async function closeSprint(sprintId, options = {}) {
+  const result = await closeSprintWithSyncPaths(sprintId, options);
+  return result.sprint;
+}
+async function closeSprintWithSyncPaths(sprintId, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const currentPath = await resolveSprintPath(sprintId, {
+    includeArchive: true
+  });
+  const { frontMatter } = await readMarkdownFile(currentPath);
+  const sprint = coerceSprintYAML(frontMatter);
+  if (options.dryRun) {
+    const tasks = await listTasksInSprint(sprintId);
+    assertSprintTerminalReady(sprintId, tasks, { force: options.force });
+    return { sprint, touchedPaths: [] };
+  }
+  if (options.noArchive) {
+    return withSprintLock(sprintId, async () => {
+      const { frontMatter: lockedFrontMatter, body: lockedBody } = await readMarkdownFile(currentPath);
+      const lockedSprint = coerceSprintYAML(lockedFrontMatter);
+      if (lockedSprint.status === "completed") {
+        return { sprint: lockedSprint, touchedPaths: [] };
+      }
+      const lockedTasks = await listTasksInSprint(sprintId);
+      assertSprintTerminalReady(sprintId, lockedTasks, { force: options.force });
+      lockedSprint.status = "completed";
+      lockedSprint.completed_at = (/* @__PURE__ */ new Date()).toISOString();
+      lockedSprint.updated_at = lockedSprint.completed_at;
+      const archivedDoneTasks = await listArchivedDoneTasksForSprint(sprintId);
+      const lockedArchivedDoneHours = archivedDoneTasks.reduce(
+        (sum, task) => sum + task.estimatedHours,
+        0
+      );
+      applyDerivedSprintMetrics(lockedSprint, lockedTasks, lockedArchivedDoneHours);
+      const reportedTasks = [...lockedTasks, ...archivedDoneTasks];
+      const updatedBody = updateSprintBodyTasksSummary(
+        updateSprintBodyOverview(lockedBody, lockedSprint, reportedTasks),
+        reportedTasks
+      );
+      await withIndexRegeneration(planningRoot, async () => {
+        await writeSprintMarkdownFile(
+          currentPath,
+          lockedSprint,
+          updatedBody,
+          lockedFrontMatter
+        );
+      });
+      return { sprint: lockedSprint, touchedPaths: [currentPath] };
+    });
+  }
+  const result = await completeSprint(sprintId, {
+    forceTaskCompletion: Boolean(options.force)
+  });
+  return {
+    sprint: result.sprint,
+    touchedPaths: result.touchedPaths,
+    ...result.unverifiedTasks ? { unverifiedTasks: result.unverifiedTasks } : {}
+  };
+}
+async function listSprints(archived = false) {
+  const planningRoot = getPlanningRoot();
+  const liveDir = getBucketPathByKind("sprint", planningRoot);
+  const sprintsDir = archived ? bucketArchiveRootForProjectRoot(planningRoot, "sprint", liveDir) : liveDir;
+  const files = archived ? await listMarkdownFilesRecursive(sprintsDir) : await listMarkdownFiles(sprintsDir);
+  const sprints = [];
+  for (const file of files) {
+    try {
+      const { frontMatter } = await readMarkdownFile(file);
+      sprints.push(coerceSprintYAML(frontMatter));
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      emitSprintManagerWarning("Skipping malformed sprint file", {
+        file,
+        error: msg,
+        archived
+      });
+    }
+  }
+  return sprints;
+}
+async function renameSprint(sprintId, newName) {
+  const trimmedName = newName.trim();
+  if (!trimmedName) {
+    throw new Error("Sprint name cannot be empty");
+  }
+  const planningRoot = getPlanningRoot();
+  return withSprintLock(sprintId, async () => {
+    const sprintPath = await resolveSprintPath(sprintId, {
+      includeArchive: false
+    });
+    const { frontMatter, body } = await readMarkdownFile(sprintPath);
+    const sprint = coerceSprintYAML(frontMatter);
+    if (sprint.status === "completed") {
+      throw new Error(
+        `Cannot rename sprint '${sprintId}': completed sprints are read-only (assumption A2)`
+      );
+    }
+    sprint.name = trimmedName;
+    sprint.title = trimmedName;
+    sprint.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    const updatedBody = body.replace(/^# Sprint:.*$/m, `# Sprint: ${trimmedName}`);
+    await withIndexRegeneration(planningRoot, async () => {
+      await writeSprintMarkdownFile(
+        sprintPath,
+        sprint,
+        updatedBody,
+        frontMatter
+      );
+    });
+    return sprint;
+  });
+}
+async function findFinishedSprints(options = {}) {
+  const referenceDate = options.referenceDate ?? /* @__PURE__ */ new Date();
+  const activeSprints = await listSprints(false);
+  const finishedSprints = [];
+  for (const sprint of activeSprints) {
+    if (sprint.status === "completed") {
+      continue;
+    }
+    if (!sprint.endDate) {
+      continue;
+    }
+    const refDateStr = formatLocalDateString(referenceDate);
+    if (sprint.endDate >= refDateStr) {
+      continue;
+    }
+    const tasks = await listTasksInSprint(sprint.id);
+    const readiness = computeSprintTerminalReadiness(tasks);
+    const completedTasks = tasks.filter((t) => t.missing !== true && t.status === "done").length;
+    const allTasksCompleted = tasks.length === 0 || readiness.ready;
+    if (allTasksCompleted) {
+      finishedSprints.push({
+        sprintId: sprint.id,
+        endDate: sprint.endDate,
+        totalTasks: tasks.length,
+        completedTasks
+      });
+    }
+  }
+  return finishedSprints;
+}
+
+export {
+  acquireSprintLock,
+  acquireSprintLockLease,
+  withSprintLock,
+  getSprintLockHandoffEnv,
+  getSprintLockOwnerToken,
+  refreshSprintLock,
+  unlockSprintLock,
+  DEFAULT_SPRINT_CAPACITY_HOURS,
+  findSprintOverlapConflict,
+  createSprint,
+  getCurrentSprint,
+  assertSprintAcceptsNewTask,
+  addTaskToSprint,
+  removeTaskFromSprint,
+  detachArchivedTaskFromSprint,
+  isTaskRecordedCompletedInSprint,
+  assertSprintCanAcceptRestoredTask,
+  calculateCapacity,
+  checkCapacityWarning,
+  listTasksInSprint,
+  computeSprintTerminalReadiness,
+  assertSprintTerminalReady,
+  countArchivedTasksForSprint,
+  findReadySprintsForBatchClose,
+  refreshSprintMarkdown,
+  activateSprint,
+  completeSprint,
+  closeSprint,
+  closeSprintWithSyncPaths,
+  listSprints,
+  renameSprint,
+  findFinishedSprints
+};
+//# sourceMappingURL=chunk-L2CBG5IX.js.map