@poetic-ai/poetic 1.42.0

package/dist/chunk-5LTN43AS.js

@@ -0,0 +1,1972 @@
+import {
+  StaleVersionError
+} from "./chunk-TDSEX5CF.js";
+import {
+  generateEnhancements,
+  hintsFromEnhancements,
+  toEnhancementSet,
+  toPersistedFormat
+} from "./chunk-LIVJ6266.js";
+import {
+  BUILT_IN_VARIANT_STRATEGIES
+} from "./chunk-VXF4Q3FW.js";
+import {
+  getDefaultActivityForCategory
+} from "./chunk-4RCCF5BR.js";
+import {
+  isTaskStatus,
+  validateStateTransition
+} from "./chunk-KNT72VR6.js";
+import {
+  classifyTaskDependency,
+  loadAllItems
+} from "./chunk-3BCUNHKF.js";
+import {
+  getArchiveShard,
+  getArchivedFilePath
+} from "./chunk-OYZYO7TV.js";
+import {
+  generateId,
+  isValidId
+} from "./chunk-VNSYKC25.js";
+import {
+  assertCompletionContractsMet,
+  normalizeCompletionContracts
+} from "./chunk-R35PEUKH.js";
+import {
+  getPlanningRoot,
+  withIndexRegeneration
+} from "./chunk-OPYFYTWQ.js";
+import {
+  getBucketArchivePathByKind,
+  getBucketByName,
+  getBucketPathByKind
+} from "./chunk-HOYBYAOA.js";
+import {
+  assertSafePlanningFileId,
+  ensureDirectoryExists,
+  listMarkdownFiles,
+  listMarkdownFilesRecursive,
+  listMarkdownFilesRecursiveStrict,
+  readMarkdownFile,
+  resolvePlanningItemPath,
+  writeMarkdownFile
+} from "./chunk-OIS7J26S.js";
+import {
+  emitCustomWarning
+} from "./chunk-EJGCZGUF.js";
+
+// src/planning/task-manager.ts
+import * as crypto from "crypto";
+import * as fs from "fs/promises";
+import * as path from "path";
+function isBuiltInStrategy(value) {
+  return typeof value === "string" && BUILT_IN_VARIANT_STRATEGIES.includes(value);
+}
+function emitTaskManagerWarning(message, metadata) {
+  emitCustomWarning(
+    "WARN" /* WARN */,
+    "configuration" /* CONFIGURATION */,
+    message,
+    {
+      subsystem: "planning/task-manager",
+      executionPhase: "execution"
+    },
+    { metadata, skipConsole: true }
+  );
+}
+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 parseOptionalNumber(value) {
+  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 void 0;
+}
+var RUNTIME_ESTIMATE_PROVENANCES = ["heuristic", "telemetry", "blended", "explicit"];
+var RUNTIME_ESTIMATE_CONFIDENCES = ["low", "medium", "high"];
+function coerceRuntimeEstimateFields(frontMatter) {
+  const result = {};
+  const minutes = parseOptionalNumber(frontMatter.expectedRuntimeMinutes);
+  if (typeof minutes === "number" && minutes > 0) {
+    result.expectedRuntimeMinutes = minutes;
+  }
+  const provenance = frontMatter.runtimeEstimateProvenance;
+  if (typeof provenance === "string" && RUNTIME_ESTIMATE_PROVENANCES.includes(provenance)) {
+    result.runtimeEstimateProvenance = provenance;
+  }
+  const confidence = frontMatter.runtimeEstimateConfidence;
+  if (typeof confidence === "string" && RUNTIME_ESTIMATE_CONFIDENCES.includes(confidence)) {
+    result.runtimeEstimateConfidence = confidence;
+  }
+  return result;
+}
+var VALID_STAGE_OUTPUT_TYPES = [
+  "diff",
+  "files",
+  "text",
+  "testResults",
+  "json"
+];
+function coerceStageOutputs(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const outputs = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (!key || typeof key !== "string") continue;
+    if (typeof raw !== "string") continue;
+    if (!VALID_STAGE_OUTPUT_TYPES.includes(raw)) continue;
+    outputs[key] = raw;
+  }
+  return Object.keys(outputs).length > 0 ? outputs : void 0;
+}
+function coerceStageValidationOverride(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  const enabled = typeof raw.enabled === "boolean" ? raw.enabled : void 0;
+  const target = typeof raw.target === "string" ? raw.target : void 0;
+  const threshold = parseOptionalNumber(raw.threshold);
+  const maxRetries = parseOptionalNumber(raw.maxRetries);
+  const requiredFiles = Array.isArray(raw.requiredFiles) ? raw.requiredFiles.filter(
+    (value2) => typeof value2 === "string" && value2.trim().length > 0
+  ) : void 0;
+  const checks = Array.isArray(raw.checks) ? raw.checks : void 0;
+  const semanticChecks = Array.isArray(raw.semanticChecks) ? raw.semanticChecks : void 0;
+  if (enabled === void 0 && target === void 0 && threshold === void 0 && maxRetries === void 0 && requiredFiles === void 0 && checks === void 0 && semanticChecks === void 0) {
+    return void 0;
+  }
+  return {
+    ...enabled !== void 0 ? { enabled } : {},
+    ...target ? { target } : {},
+    ...threshold !== void 0 ? { threshold } : {},
+    ...maxRetries !== void 0 ? { maxRetries } : {},
+    ...requiredFiles && requiredFiles.length > 0 ? { requiredFiles } : {},
+    ...checks ? { checks } : {},
+    ...semanticChecks ? { semanticChecks } : {}
+  };
+}
+function coerceVariantSpec(value) {
+  if (typeof value === "string") {
+    const [providerRaw, strategyRaw2] = value.split(":").map((v) => v.trim());
+    if (!providerRaw) return null;
+    const strategy2 = isBuiltInStrategy(strategyRaw2) ? strategyRaw2 : void 0;
+    return { provider: providerRaw, ...strategy2 ? { strategy: strategy2 } : {} };
+  }
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const provider = typeof raw.provider === "string" ? raw.provider : void 0;
+  if (!provider) return null;
+  const model = typeof raw.model === "string" ? raw.model : void 0;
+  const strategyRaw = typeof raw.strategy === "string" ? raw.strategy : void 0;
+  const strategy = isBuiltInStrategy(strategyRaw) ? strategyRaw : void 0;
+  const reasoning = typeof raw.reasoning === "string" ? raw.reasoning : void 0;
+  return {
+    provider,
+    ...model ? { model } : {},
+    ...strategy ? { strategy } : {},
+    ...reasoning ? { reasoning } : {}
+  };
+}
+function coerceCompetitionConfig(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  const variantsRaw = raw.variants;
+  const variants = Array.isArray(variantsRaw) ? variantsRaw.map(coerceVariantSpec).filter((v) => Boolean(v)) : [];
+  if (variants.length === 0) return void 0;
+  const judgeConfigRaw = raw.judgeConfig;
+  const judgeConfig = judgeConfigRaw && typeof judgeConfigRaw === "object" ? {
+    type: (() => {
+      const obj = judgeConfigRaw;
+      const typeRaw = obj.type;
+      if (typeof typeRaw === "string" && (typeRaw === "multi-lens" || typeRaw === "multi-agent" || typeRaw === "ai")) {
+        return typeRaw;
+      }
+      return void 0;
+    })(),
+    threshold: parseOptionalNumber(judgeConfigRaw.threshold),
+    runComparison: (() => {
+      const value2 = judgeConfigRaw.runComparison;
+      return typeof value2 === "boolean" ? value2 : void 0;
+    })()
+  } : void 0;
+  const preserveCandidates = typeof raw.preserveCandidates === "boolean" ? raw.preserveCandidates : void 0;
+  const applyWinner = typeof raw.applyWinner === "boolean" ? raw.applyWinner : void 0;
+  const tieBreakerRaw = raw.tieBreaker;
+  const tieBreaker = tieBreakerRaw && typeof tieBreakerRaw === "object" ? {
+    mode: (() => {
+      const obj = tieBreakerRaw;
+      const modeRaw = obj.mode;
+      if (modeRaw === "prefer-first-ranked" || modeRaw === "prefer-strategy" || modeRaw === "prefer-low-drift" || modeRaw === "prefer-smaller-diff" || modeRaw === "prefer-low-drift-then-diff") {
+        return modeRaw;
+      }
+      return void 0;
+    })(),
+    strategy: (() => {
+      const obj = tieBreakerRaw;
+      const strategyRaw = obj.strategy;
+      if (strategyRaw === "conservative" || strategyRaw === "innovative") {
+        return strategyRaw;
+      }
+      return void 0;
+    })()
+  } : void 0;
+  const normalizedTieBreaker = tieBreaker?.mode ? {
+    mode: tieBreaker.mode,
+    ...tieBreaker.strategy ? { strategy: tieBreaker.strategy } : {}
+  } : void 0;
+  const verificationPolicyRaw = typeof raw.verificationPolicy === "string" ? raw.verificationPolicy : void 0;
+  const verificationPolicy = verificationPolicyRaw === "findings" || verificationPolicyRaw === "blocking" ? verificationPolicyRaw : void 0;
+  const repairRaw = raw.repairOnFindings;
+  const repairObj = repairRaw && typeof repairRaw === "object" ? repairRaw : null;
+  const repairOnFindings = repairObj ? {
+    enabled: Boolean(repairObj.enabled),
+    ...parseOptionalNumber(repairObj.maxIterations) !== void 0 ? {
+      maxIterations: parseOptionalNumber(repairObj.maxIterations)
+    } : {},
+    ...parseOptionalNumber(repairObj.timeboxMs) !== void 0 ? { timeboxMs: parseOptionalNumber(repairObj.timeboxMs) } : {}
+  } : void 0;
+  const result = {
+    variants,
+    ...judgeConfig?.type ? {
+      judgeConfig: {
+        type: judgeConfig.type,
+        ...Number.isFinite(judgeConfig.threshold) ? { threshold: judgeConfig.threshold } : {},
+        ...judgeConfig.runComparison !== void 0 ? { runComparison: judgeConfig.runComparison } : {}
+      }
+    } : {},
+    ...preserveCandidates !== void 0 ? { preserveCandidates } : {},
+    ...applyWinner !== void 0 ? { applyWinner } : {},
+    ...verificationPolicy ? { verificationPolicy } : {},
+    ...repairOnFindings ? { repairOnFindings } : {},
+    ...normalizedTieBreaker ? { tieBreaker: normalizedTieBreaker } : {}
+  };
+  return result;
+}
+function coerceFlywheelConfig(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  const typeRaw = typeof raw.type === "string" ? raw.type : void 0;
+  const type = typeRaw === "standard" || typeRaw === "competition" || typeRaw === "verify" || typeRaw === "refinement" || typeRaw === "autoloop" ? typeRaw : void 0;
+  const inputs = Array.isArray(raw.inputs) ? raw.inputs.filter(
+    (v) => typeof v === "string" && v.length > 0
+  ) : void 0;
+  const allowlist = Array.isArray(raw.allowlist) ? raw.allowlist.filter((v) => typeof v === "string" && v.length > 0) : void 0;
+  const allowDenylist = Array.isArray(raw.allowDenylist) ? raw.allowDenylist.filter(
+    (v) => typeof v === "string" && v.length > 0
+  ) : void 0;
+  const allowlistModeRaw = typeof raw.allowlistMode === "string" ? raw.allowlistMode : void 0;
+  const allowlistMode = allowlistModeRaw === "off" || allowlistModeRaw === "warn" || allowlistModeRaw === "strict" || allowlistModeRaw === "filter" ? allowlistModeRaw : void 0;
+  const verifyRaw = raw.verify;
+  const verifyObj = verifyRaw && typeof verifyRaw === "object" ? verifyRaw : null;
+  const verify = verifyObj && Array.isArray(verifyObj.commands) ? {
+    commands: verifyObj.commands.filter(
+      (v) => typeof v === "string" && v.length > 0
+    )
+  } : void 0;
+  const outputs = coerceStageOutputs(raw.outputs);
+  const validation = coerceStageValidationOverride(raw.validation);
+  const competition = coerceCompetitionConfig(raw.competition);
+  const allowEmptyResults = typeof raw.allowEmptyResults === "boolean" ? raw.allowEmptyResults : void 0;
+  const autoloopRaw = raw.autoloop;
+  const autoloopObj = autoloopRaw && typeof autoloopRaw === "object" ? autoloopRaw : null;
+  const autoloop = autoloopObj ? {
+    ...parseOptionalNumber(autoloopObj.maxIterations) !== void 0 ? {
+      maxIterations: parseOptionalNumber(autoloopObj.maxIterations)
+    } : {},
+    ...parseOptionalNumber(autoloopObj.timeboxMs) !== void 0 ? { timeboxMs: parseOptionalNumber(autoloopObj.timeboxMs) } : {},
+    ...parseOptionalNumber(autoloopObj.minProgress) !== void 0 ? {
+      minProgress: parseOptionalNumber(autoloopObj.minProgress)
+    } : {},
+    ...typeof autoloopObj.stopOnQualityGate === "boolean" ? { stopOnQualityGate: autoloopObj.stopOnQualityGate } : {},
+    ...Array.isArray(autoloopObj.qualityGateCommands) ? {
+      qualityGateCommands: autoloopObj.qualityGateCommands.filter(
+        (v) => typeof v === "string" && v.length > 0
+      )
+    } : {}
+  } : void 0;
+  const hasAutoloopFields = Boolean(
+    autoloop && (autoloop.maxIterations !== void 0 || autoloop.timeboxMs !== void 0 || autoloop.minProgress !== void 0 || autoloop.stopOnQualityGate !== void 0 || Array.isArray(autoloop.qualityGateCommands) && autoloop.qualityGateCommands.length > 0)
+  );
+  if (!type && (!inputs || inputs.length === 0) && (!allowlist || allowlist.length === 0) && (!allowDenylist || allowDenylist.length === 0) && !allowlistMode && !verify && !outputs && !validation && !competition && allowEmptyResults === void 0 && !hasAutoloopFields)
+    return void 0;
+  return {
+    ...type ? { type } : {},
+    ...inputs && inputs.length > 0 ? { inputs } : {},
+    ...allowlist && allowlist.length > 0 ? { allowlist } : {},
+    ...allowDenylist && allowDenylist.length > 0 ? { allowDenylist } : {},
+    ...allowlistMode ? { allowlistMode } : {},
+    ...verify && verify.commands.length > 0 ? { verify } : {},
+    ...outputs ? { outputs } : {},
+    ...validation ? { validation } : {},
+    ...competition ? { competition } : {},
+    ...allowEmptyResults !== void 0 ? { allowEmptyResults } : {},
+    ...hasAutoloopFields ? { autoloop } : {}
+  };
+}
+function coerceTaskYAML(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"`);
+  }
+  assertSafePlanningFileId(id, "taskId");
+  assertSafePlanningFileId(sprintId, "sprintId");
+  if (originalSprintId) {
+    assertSafePlanningFileId(originalSprintId, "originalSprintId");
+  }
+  const title = typeof frontMatter.title === "string" ? frontMatter.title : "";
+  if (!title) {
+    throw new Error(`Invalid task frontmatter for '${id}': missing required field "title"`);
+  }
+  const version = parseNumber(frontMatter.version, 0);
+  const statusRaw = typeof frontMatter.status === "string" ? frontMatter.status : "todo";
+  const statusMap = {
+    // Canonical statuses
+    todo: "todo",
+    in_progress: "in_progress",
+    review: "review",
+    done: "done",
+    blocked: "blocked",
+    cancelled: "cancelled",
+    canceled: "cancelled",
+    // Legacy statuses (kebab-case and alternatives)
+    pending: "todo",
+    "in-progress": "in_progress",
+    completed: "done",
+    archived: "done"
+  };
+  const status = statusMap[statusRaw] ?? "todo";
+  const priorityRaw = typeof frontMatter.priority === "string" ? frontMatter.priority : "P2";
+  const priority = priorityRaw === "P0" || priorityRaw === "P1" || priorityRaw === "P2" || priorityRaw === "P3" ? priorityRaw : "P2";
+  const dependencies = Array.isArray(frontMatter.dependencies) ? frontMatter.dependencies.filter((v) => typeof v === "string") : [];
+  const subtasksRaw = Array.isArray(frontMatter.subtasks) ? frontMatter.subtasks : [];
+  const subtasks = subtasksRaw.map((st) => {
+    if (!st || typeof st !== "object") return null;
+    const stObj = st;
+    const text = typeof stObj.text === "string" ? stObj.text : "";
+    if (!text) return null;
+    return {
+      text,
+      completed: Boolean(stObj.completed)
+    };
+  }).filter((v) => Boolean(v));
+  const createdAt = typeof frontMatter.created_at === "string" && frontMatter.created_at || typeof frontMatter.created === "string" && frontMatter.created || (/* @__PURE__ */ new Date()).toISOString();
+  const updatedAt = typeof frontMatter.updated_at === "string" && frontMatter.updated_at || typeof frontMatter.updated === "string" && frontMatter.updated || createdAt;
+  const metadataRaw = frontMatter.metadata;
+  let metadata = metadataRaw && typeof metadataRaw === "object" ? {
+    executionIntent: metadataRaw.executionIntent === "analysis" || metadataRaw.executionIntent === "edit" ? metadataRaw.executionIntent : void 0
+  } : void 0;
+  const routingRaw = frontMatter.routing;
+  let routing;
+  if (routingRaw && typeof routingRaw === "object") {
+    const routingObj = routingRaw;
+    const provider = typeof routingObj.provider === "string" ? routingObj.provider : void 0;
+    const model = typeof routingObj.model === "string" ? routingObj.model : void 0;
+    const strategyRaw = typeof routingObj.strategy === "string" ? routingObj.strategy : void 0;
+    const strategy = isBuiltInStrategy(strategyRaw) ? strategyRaw : void 0;
+    const reasoning = typeof routingObj.reasoning === "string" ? routingObj.reasoning : void 0;
+    const profile = typeof routingObj.profile === "string" ? routingObj.profile : void 0;
+    if (provider || model || strategy || reasoning || profile) {
+      routing = { provider, model, strategy, reasoning, profile };
+    }
+  }
+  const executionIntentRaw = frontMatter.executionIntent;
+  if (!metadata?.executionIntent && (executionIntentRaw === "analysis" || executionIntentRaw === "edit")) {
+    metadata = { executionIntent: executionIntentRaw };
+  }
+  if (!routing) {
+    const provider = typeof frontMatter.provider === "string" ? frontMatter.provider : void 0;
+    const model = typeof frontMatter.model === "string" ? frontMatter.model : void 0;
+    if (provider && provider !== "multi" || model) {
+      routing = {
+        provider: provider && provider !== "multi" ? provider : void 0,
+        model
+      };
+    }
+  }
+  const flywheel = coerceFlywheelConfig(frontMatter.flywheel);
+  const taskClassificationRaw = frontMatter.taskClassification;
+  let taskClassification;
+  if (taskClassificationRaw && typeof taskClassificationRaw === "object") {
+    const classObj = taskClassificationRaw;
+    const categoryRaw = typeof classObj.category === "string" ? classObj.category : void 0;
+    const activityRaw = typeof classObj.activity === "string" ? classObj.activity : void 0;
+    const validCategories = ["execute", "review", "analyze", "test", "document"];
+    const validActivities = [
+      "planning",
+      "research",
+      "architecture",
+      "design",
+      "development",
+      "debugging"
+    ];
+    const category = categoryRaw && validCategories.includes(categoryRaw) ? categoryRaw : void 0;
+    let activity = activityRaw && validActivities.includes(activityRaw) ? activityRaw : void 0;
+    if (category && !activity) {
+      activity = getDefaultActivityForCategory(category);
+    }
+    if (category || activity) {
+      taskClassification = { category, activity };
+    }
+  }
+  const taskTypeRaw = frontMatter.taskType ?? frontMatter.task_type;
+  const taskType = typeof taskTypeRaw === "string" && taskTypeRaw.trim().length > 0 ? taskTypeRaw.trim() : void 0;
+  const declaredType = typeof frontMatter.declaredType === "string" ? frontMatter.declaredType : void 0;
+  const declaredMethodology = typeof frontMatter.declaredMethodology === "string" ? frontMatter.declaredMethodology : void 0;
+  const resolvedTaskTypeId = typeof frontMatter.resolvedTaskTypeId === "string" ? frontMatter.resolvedTaskTypeId : void 0;
+  const hints = Array.isArray(frontMatter.hints) ? frontMatter.hints.filter((h) => typeof h === "string") : void 0;
+  function coerceEnhancementIntent(value) {
+    if (!value || typeof value !== "object") return void 0;
+    const obj = value;
+    const categoryRaw = typeof obj.category === "string" ? obj.category : void 0;
+    const activityRaw = typeof obj.activity === "string" ? obj.activity : void 0;
+    const confidenceRaw = typeof obj.confidence === "number" ? obj.confidence : void 0;
+    const validCategories = ["execute", "review", "analyze", "test", "document"];
+    const validActivities = [
+      "planning",
+      "research",
+      "architecture",
+      "design",
+      "development",
+      "debugging"
+    ];
+    const category = categoryRaw && validCategories.includes(categoryRaw) ? categoryRaw : void 0;
+    const activity = activityRaw && validActivities.includes(activityRaw) ? activityRaw : void 0;
+    if (!category || !activity) return void 0;
+    const confidence = typeof confidenceRaw === "number" && confidenceRaw >= 0 && confidenceRaw <= 1 ? confidenceRaw : void 0;
+    if (confidence === void 0) return void 0;
+    return { category, activity, confidence };
+  }
+  const enhancementSetRaw = frontMatter.enhancementSet;
+  const enhancementSet = enhancementSetRaw && typeof enhancementSetRaw === "object" ? (() => {
+    const obj = enhancementSetRaw;
+    const version2 = obj.version === 1 ? 1 : void 0;
+    const intentRaw = obj.intent;
+    if (version2 !== 1 || !intentRaw || typeof intentRaw !== "object") return void 0;
+    const intent = coerceEnhancementIntent(intentRaw);
+    if (!intent) return void 0;
+    const enhancementsRaw = obj.enhancements ?? void 0;
+    const enhancements2 = Array.isArray(
+      enhancementsRaw
+    ) ? enhancementsRaw.map((e) => {
+      if (!e || typeof e !== "object") return null;
+      const eObj = e;
+      const kind = typeof eObj.kind === "string" ? eObj.kind : void 0;
+      const snippet = typeof eObj.snippet === "string" ? eObj.snippet : void 0;
+      if (!kind || !snippet) return null;
+      return { kind, snippet };
+    }).filter(
+      (e) => e !== null
+    ) : void 0;
+    if (!enhancements2) return void 0;
+    const acceptanceCriteriaRaw = obj.acceptanceCriteria;
+    const acceptanceCriteria = Array.isArray(acceptanceCriteriaRaw) ? acceptanceCriteriaRaw.map((c) => {
+      if (!c || typeof c !== "object") return null;
+      const cObj = c;
+      const id2 = typeof cObj.id === "string" ? cObj.id : void 0;
+      const description = typeof cObj.description === "string" ? cObj.description : void 0;
+      if (!id2 || !description) return null;
+      const weight = typeof cObj.weight === "number" ? cObj.weight : void 0;
+      const verification = cObj.verification && typeof cObj.verification === "object" ? cObj.verification : void 0;
+      return {
+        id: id2,
+        description,
+        weight,
+        verification
+      };
+    }).filter((c) => c !== null) : void 0;
+    const constraintsRaw = obj.constraints;
+    const constraints = Array.isArray(constraintsRaw) ? constraintsRaw.map((c) => {
+      if (!c || typeof c !== "object") return null;
+      const cObj = c;
+      const id2 = typeof cObj.id === "string" ? cObj.id : void 0;
+      const rule = typeof cObj.rule === "string" ? cObj.rule : void 0;
+      if (!id2 || !rule) return null;
+      const penaltyPoints = typeof cObj.penaltyPoints === "number" ? cObj.penaltyPoints : void 0;
+      const scope = cObj.scope && typeof cObj.scope === "object" ? cObj.scope : void 0;
+      const allowIf = Array.isArray(cObj.allowIf) ? cObj.allowIf : void 0;
+      return {
+        id: id2,
+        rule,
+        penaltyPoints,
+        scope,
+        allowIf
+      };
+    }).filter((c) => c !== null) : void 0;
+    const artifactSourcesRaw = obj.artifactSources;
+    const artifactSources = artifactSourcesRaw && typeof artifactSourcesRaw === "object" ? (() => {
+      const a = artifactSourcesRaw;
+      const preferred = Array.isArray(a.preferred) ? a.preferred.filter((v) => typeof v === "string") : void 0;
+      const fallback = Array.isArray(a.fallback) ? a.fallback.filter((v) => typeof v === "string") : void 0;
+      if (!preferred && !fallback) return void 0;
+      return { preferred, fallback };
+    })() : void 0;
+    return {
+      version: 1,
+      intent,
+      enhancements: enhancements2,
+      acceptanceCriteria,
+      constraints,
+      artifactSources
+    };
+  })() : void 0;
+  const enhancementsLegacyRaw = frontMatter.enhancements;
+  const enhancementsLegacy = Array.isArray(
+    enhancementsLegacyRaw
+  ) ? enhancementsLegacyRaw.map((e) => {
+    if (!e || typeof e !== "object") return null;
+    const obj = e;
+    const kind = typeof obj.kind === "string" ? obj.kind : void 0;
+    const snippet = typeof obj.snippet === "string" ? obj.snippet : void 0;
+    if (!kind || !snippet) return null;
+    return { kind, snippet };
+  }).filter((e) => e !== null) : void 0;
+  const enhancements = enhancementSet?.enhancements ?? enhancementsLegacy;
+  const blockedReason = typeof frontMatter.blockedReason === "string" && frontMatter.blockedReason.trim() ? frontMatter.blockedReason.trim() : void 0;
+  const blockedReasonHistory = Array.isArray(frontMatter.blockedReasonHistory) ? frontMatter.blockedReasonHistory.filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  ) : void 0;
+  const forceCompletedFrom = isTaskStatus(frontMatter.forceCompletedFrom) && frontMatter.forceCompletedFrom !== "done" ? frontMatter.forceCompletedFrom : void 0;
+  const originalBlockedReason = typeof frontMatter.originalBlockedReason === "string" && frontMatter.originalBlockedReason.trim() ? frontMatter.originalBlockedReason.trim() : void 0;
+  const cancelledAt = typeof frontMatter.cancelledAt === "string" && frontMatter.cancelledAt.trim() ? frontMatter.cancelledAt.trim() : void 0;
+  const cancelledReason = typeof frontMatter.cancelledReason === "string" && frontMatter.cancelledReason.trim() ? frontMatter.cancelledReason.trim() : void 0;
+  const completionContract = normalizeCompletionContracts(frontMatter.completionContract);
+  const appliedTransitions = Array.isArray(frontMatter.appliedTransitions) ? frontMatter.appliedTransitions.filter(
+    (value) => typeof value === "string" && value.length > 0
+  ) : void 0;
+  const lastTransitionReason = typeof frontMatter.lastTransitionReason === "string" && frontMatter.lastTransitionReason.trim() ? frontMatter.lastTransitionReason.trim() : void 0;
+  const statusBypassAudit = Array.isArray(frontMatter.statusBypassAudit) ? frontMatter.statusBypassAudit.map((entry) => {
+    if (!entry || typeof entry !== "object") return null;
+    const obj = entry;
+    const fromStatus = obj.fromStatus;
+    const toStatus = obj.toStatus;
+    const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+    const at = typeof obj.at === "string" ? obj.at : "";
+    if (!isTaskStatus(fromStatus) || !isTaskStatus(toStatus) || !reason || !at) {
+      return null;
+    }
+    const actor = typeof obj.actor === "string" && obj.actor.trim() ? obj.actor.trim() : void 0;
+    return { at, fromStatus, toStatus, reason, actor };
+  }).filter(
+    (entry) => Boolean(entry)
+  ) : void 0;
+  return {
+    ...frontMatter,
+    id,
+    kind: "task",
+    version,
+    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,
+    planIntentHash: typeof frontMatter.planIntentHash === "string" ? frontMatter.planIntentHash : void 0,
+    planStageId: typeof frontMatter.planStageId === "string" ? frontMatter.planStageId : void 0,
+    splitStrategy: frontMatter.splitStrategy === "ai" || frontMatter.splitStrategy === "rule-based" ? frontMatter.splitStrategy : void 0,
+    splitMode: frontMatter.splitMode === "rule" || frontMatter.splitMode === "shadow" || frontMatter.splitMode === "llm" ? frontMatter.splitMode : void 0,
+    splitTaskType: typeof frontMatter.splitTaskType === "string" ? frontMatter.splitTaskType : void 0,
+    taskType,
+    declaredType,
+    declaredMethodology,
+    resolvedTaskTypeId,
+    title,
+    status,
+    priority,
+    assignee: typeof frontMatter.assignee === "string" ? frontMatter.assignee : void 0,
+    estimatedHours: parseNumber(frontMatter.estimatedHours, 0),
+    // AI runtime estimate fields: preserved only when present and valid. Never
+    // synthesized — a legacy task without them stays without them (no fake data).
+    ...coerceRuntimeEstimateFields(frontMatter),
+    timeLoggedHours: parseNumber(frontMatter.timeLoggedHours, 0),
+    dependencies,
+    subtasks,
+    hints,
+    enhancements,
+    enhancementSet,
+    routing,
+    flywheel,
+    taskClassification,
+    blockedReason,
+    blockedReasonHistory,
+    forceCompletedFrom,
+    originalBlockedReason,
+    statusBypassAudit,
+    ...completionContract.length > 0 ? { completionContract } : {},
+    ...appliedTransitions && appliedTransitions.length > 0 ? { appliedTransitions } : {},
+    ...lastTransitionReason ? { lastTransitionReason } : {},
+    metadata,
+    created_at: createdAt,
+    updated_at: updatedAt,
+    started_at: typeof frontMatter.started_at === "string" ? frontMatter.started_at : void 0,
+    completed_at: typeof frontMatter.completed_at === "string" ? frontMatter.completed_at : void 0,
+    cancelledAt,
+    cancelledReason
+  };
+}
+async function generateTaskId(sprintId, title) {
+  void sprintId;
+  void title;
+  return generateId(/* @__PURE__ */ new Date());
+}
+async function createTask(title, sprintId, options = {}, repoRoot) {
+  const result = await createTaskWithGuidance(title, sprintId, options, repoRoot);
+  return result.task;
+}
+async function createTaskWithGuidance(title, sprintId, options = {}, repoRoot) {
+  const planningRoot = repoRoot ?? getPlanningRoot();
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    await ensureDirectoryExists(tasksDir);
+    assertSafePlanningFileId(sprintId, "sprintId");
+    const taskId = await generateTaskId(sprintId, title);
+    const filePath = resolvePlanningItemPath(tasksDir, taskId, { label: "taskId" });
+    const dependencies = [...new Set(options.dependencies ?? [])];
+    if (dependencies.includes(taskId)) {
+      throw new Error(`Task cannot depend on itself: ${taskId}`);
+    }
+    if (dependencies.length > 0) {
+      const taskPath = getBucketPathByKind("task", planningRoot);
+      const taskArchivePath = getBucketArchivePathByKind("task", planningRoot);
+      const allItems = await loadAllItems(planningRoot, [taskPath, taskArchivePath]);
+      const allIds = new Set(allItems.map((item) => item.id));
+      const missingDependencies = dependencies.filter((depId) => !allIds.has(depId));
+      if (missingDependencies.length > 0) {
+        throw new Error(`Dependency task not found: ${missingDependencies.join(", ")}`);
+      }
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const task = {
+      id: taskId,
+      kind: "task",
+      version: 1,
+      sprintId,
+      backlogItemId: options.backlogItemId,
+      planArtifactPath: options.planArtifactPath,
+      planIntentHash: options.planIntentHash,
+      planStageId: options.planStageId,
+      splitStrategy: options.splitStrategy,
+      splitMode: options.splitMode,
+      splitTaskType: options.splitTaskType,
+      // Declared terminology (verbatim, opaque) + its resolved canonical id are
+      // carried through from the originating backlog item / decomposition so the
+      // declared term actually reaches sprint workflow resolution. Only set when
+      // present so legacy tasks stay clean.
+      ...typeof options.declaredType === "string" && options.declaredType.length > 0 ? { declaredType: options.declaredType } : {},
+      ...typeof options.declaredMethodology === "string" && options.declaredMethodology.length > 0 ? { declaredMethodology: options.declaredMethodology } : {},
+      ...typeof options.resolvedTaskTypeId === "string" && options.resolvedTaskTypeId.length > 0 ? { resolvedTaskTypeId: options.resolvedTaskTypeId } : {},
+      title,
+      status: "todo",
+      priority: options.priority ?? "P2",
+      assignee: options.assignee,
+      estimatedHours: options.estimatedHours ?? 4,
+      // AI runtime estimate is optional and never defaulted (absence is honest,
+      // not zero/fake). estimatedHours default is untouched.
+      ...typeof options.expectedRuntimeMinutes === "number" && options.expectedRuntimeMinutes > 0 ? { expectedRuntimeMinutes: options.expectedRuntimeMinutes } : {},
+      ...options.runtimeEstimateProvenance ? { runtimeEstimateProvenance: options.runtimeEstimateProvenance } : {},
+      ...options.runtimeEstimateConfidence ? { runtimeEstimateConfidence: options.runtimeEstimateConfidence } : {},
+      timeLoggedHours: 0,
+      dependencies,
+      subtasks: options.subtasks || [],
+      routing: options.routing,
+      flywheel: options.flywheel,
+      created_at: now,
+      updated_at: now
+    };
+    const description = typeof options.description === "string" && options.description.trim().length > 0 ? options.description.trim() : "Task created from sprint planning.";
+    let guidance;
+    if (options.planStageId) {
+      guidance = {
+        intent: { category: "execute", activity: "development", confidence: 1 },
+        enhancements: [],
+        quickReply: "",
+        nextCommands: []
+      };
+    } else {
+      guidance = generateEnhancements({
+        title,
+        description,
+        id: taskId,
+        itemKind: "task",
+        sprintId
+      });
+      const persistedEnhancements = toPersistedFormat(guidance.enhancements);
+      if (persistedEnhancements.length > 0) {
+        task.enhancements = persistedEnhancements;
+        task.enhancementSet = toEnhancementSet(guidance);
+      }
+      const hints = hintsFromEnhancements(guidance.enhancements);
+      if (hints.length > 0) task.hints = hints;
+    }
+    const body = `# Task: ${title}
+
+**Sprint**: ${sprintId}
+**Status**: To Do
+**Estimated**: ${task.estimatedHours > 0 ? `${task.estimatedHours}h` : "unestimated"}
+${task.planArtifactPath ? `**Plan Artifact**: ${task.planArtifactPath}
+` : ""}${task.planStageId ? `**Plan Stage**: ${task.planStageId}
+` : ""}
+
+## Description
+
+${description}
+
+## Subtasks
+
+${task.subtasks.length > 0 ? task.subtasks.map((st, _i) => `- [ ] ${st.text}`).join("\n") : "(No subtasks defined)"}
+
+## Notes
+
+Created on ${now}
+`;
+    await writeMarkdownFile(
+      filePath,
+      task,
+      body
+    );
+    return { task, filePath, guidance };
+  });
+}
+function formatTaskStatusLabel(status) {
+  switch (status) {
+    case "todo":
+      return "To Do";
+    case "in_progress":
+      return "In Progress";
+    case "review":
+      return "Review";
+    case "done":
+      return "Done";
+    case "blocked":
+      return "Blocked";
+    case "cancelled":
+      return "Cancelled";
+    default:
+      return "To Do";
+  }
+}
+function updateTaskBodyStatusLine(body, status) {
+  const desiredLine = `**Status**: ${formatTaskStatusLabel(status)}`;
+  if (/^\*\*Status\*\*:/m.test(body)) {
+    return body.replace(/^\*\*Status\*\*:\s*.*$/m, desiredLine);
+  }
+  const afterSprint = body.match(/^\*\*Sprint\*\*:\s*.*$/m);
+  if (afterSprint?.index !== void 0) {
+    const insertAt = afterSprint.index + afterSprint[0].length;
+    return `${body.slice(0, insertAt)}
+${desiredLine}${body.slice(insertAt)}`;
+  }
+  return `${desiredLine}
+
+${body}`;
+}
+function normalizeDescriptionSectionContent(description) {
+  const trimmed = description.trim();
+  const headingMatch = trimmed.match(/^##\s+Description\b[^\n]*\n?/i);
+  if (!headingMatch) return trimmed;
+  return trimmed.slice(headingMatch[0].length).trim();
+}
+function isTaskHeaderMetadataLine(line) {
+  const trimmed = line.trim();
+  return /^#\s+Task:/i.test(trimmed) || /^\*\*(?:Sprint|Status|Estimated|Plan Artifact|Plan Stage)\*\*:/i.test(trimmed);
+}
+function keepTaskHeaderMetadata(prefix) {
+  const lines = prefix.split("\n");
+  let lastMetadataLineIndex = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (isTaskHeaderMetadataLine(lines[index] ?? "")) {
+      lastMetadataLineIndex = index;
+    }
+  }
+  if (lastMetadataLineIndex < 0) return "";
+  return lines.slice(0, lastMetadataLineIndex + 1).join("\n").trimEnd();
+}
+function updateTaskBodyDescriptionSection(body, description) {
+  const content = normalizeDescriptionSectionContent(description);
+  const section = `## Description
+
+${content}`;
+  const existingHeading = body.match(/^##\s+Description\b[^\n]*$/im);
+  if (existingHeading?.index !== void 0) {
+    const headingStart = existingHeading.index;
+    const afterHeading = headingStart + existingHeading[0].length;
+    const nextSectionRelative = body.slice(afterHeading).search(/\n##\s+/);
+    const sectionEnd = nextSectionRelative >= 0 ? afterHeading + nextSectionRelative : body.length;
+    const before = body.slice(0, headingStart).trimEnd();
+    const after = body.slice(sectionEnd).trimStart();
+    return `${before}
+
+${section}${after ? `
+
+${after}` : ""}`.trim();
+  }
+  const insertBefore = body.search(
+    /^##\s+(?:Subtasks|Checklist|Notes|Activity|Acceptance Criteria)\b/im
+  );
+  if (insertBefore >= 0) {
+    const before = keepTaskHeaderMetadata(body.slice(0, insertBefore));
+    const after = body.slice(insertBefore).trimStart();
+    return `${before ? `${before}
+
+` : ""}${section}
+
+${after}`.trim();
+  }
+  const existingMetadata = keepTaskHeaderMetadata(body);
+  if (!existingMetadata) return `${section}
+`;
+  return `${existingMetadata}
+
+${section}`;
+}
+async function updateTaskFields(taskId, updates) {
+  const planningRoot = getPlanningRoot();
+  if (updates.description !== void 0 && updates.body !== void 0) {
+    throw new Error("Cannot update both description and body in one operation");
+  }
+  if (updates.body !== void 0 && updates.body.trim().length === 0) {
+    throw new Error("Task body cannot be empty");
+  }
+  return withIndexRegeneration(planningRoot, async () => {
+    const lookup = await getTask(taskId, { includeArchive: false });
+    const { frontMatter, body } = await readMarkdownFile(lookup.filePath);
+    const nextFrontMatter = {
+      ...frontMatter,
+      ...lookup.yaml
+    };
+    if (updates.title !== void 0) {
+      const title = updates.title.trim();
+      if (!title) throw new Error("Task title cannot be empty");
+      nextFrontMatter.title = title;
+    }
+    if (updates.priority !== void 0) {
+      nextFrontMatter.priority = updates.priority;
+    }
+    if (updates.estimatedHours !== void 0) {
+      nextFrontMatter.estimatedHours = updates.estimatedHours;
+    }
+    if (updates.expectedRuntimeMinutes !== void 0) {
+      nextFrontMatter.expectedRuntimeMinutes = updates.expectedRuntimeMinutes;
+    }
+    if (updates.assignee !== void 0) {
+      const assignee = updates.assignee?.trim() ?? "";
+      if (assignee) {
+        nextFrontMatter.assignee = assignee;
+      } else {
+        delete nextFrontMatter.assignee;
+      }
+    }
+    nextFrontMatter.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    nextFrontMatter.version = (lookup.yaml.version ?? 0) + 1;
+    const updatedTask = coerceTaskYAML(nextFrontMatter);
+    const nextBody = updates.body !== void 0 ? updates.body.trim() : updates.description !== void 0 ? updateTaskBodyDescriptionSection(body, updates.description) : body;
+    await writeMarkdownFile(
+      lookup.filePath,
+      nextFrontMatter,
+      updateTaskBodyStatusLine(nextBody, updatedTask.status)
+    );
+    return updatedTask;
+  });
+}
+async function updateTaskStatus(taskId, newStatus, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const bypassReasonPre = options.bypassValidation?.reason.trim();
+  let contractEval;
+  if (newStatus === "done" && !bypassReasonPre) {
+    const preEval = await readTaskForCompletionEval(taskId, planningRoot);
+    if (preEval.task.status !== "done" && (preEval.task.completionContract?.length ?? 0) > 0) {
+      const evaluatedVersion = preEval.task.version;
+      const contractKey = completionContractSnapshotKey(preEval.task.completionContract);
+      await assertCompletionContractsMet({
+        contracts: preEval.task.completionContract,
+        bypassReason: bypassReasonPre,
+        workingDir: options.completionContractRoot
+      });
+      contractEval = { evaluatedVersion, contractKey };
+    }
+  }
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(tasksDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    const currentVersion = task.version;
+    if (options.expectedVersion !== void 0 && currentVersion !== options.expectedVersion) {
+      throw new StaleVersionError(currentVersion, options.expectedVersion, taskId);
+    }
+    if (task.status === newStatus && newStatus !== "blocked") {
+      if (options?.resultArtifactPath && task.resultArtifactPath !== options.resultArtifactPath) {
+        task.resultArtifactPath = options.resultArtifactPath;
+        task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+        task.version = currentVersion + 1;
+        await writeMarkdownFile(
+          taskFile,
+          task,
+          updateTaskBodyStatusLine(body, task.status)
+        );
+      }
+      return task;
+    }
+    const bypass = options.bypassValidation;
+    const bypassReason = bypass?.reason.trim();
+    if (bypass && !bypassReason) {
+      throw new Error("Task status validation bypass requires a reason");
+    }
+    if (!bypass) {
+      const transition = await validateStateTransition(
+        planningRoot,
+        taskId,
+        task.status,
+        newStatus
+      );
+      if (!transition.success) {
+        const details = transition.errors?.length ? `: ${transition.errors.join("; ")}` : "";
+        throw new Error(`${transition.message}${details}`);
+      }
+    }
+    if (newStatus === "done") {
+      if (contractEval) {
+        if (currentVersion !== contractEval.evaluatedVersion || completionContractSnapshotKey(task.completionContract) !== contractEval.contractKey) {
+          throw new StaleVersionError(
+            currentVersion,
+            contractEval.evaluatedVersion,
+            taskId,
+            "completionContract",
+            "concurrent task mutation between completion-contract evaluation and status write"
+          );
+        }
+      } else {
+        await assertCompletionContractsMet({
+          contracts: task.completionContract,
+          bypassReason,
+          workingDir: options.completionContractRoot
+        });
+      }
+    }
+    const previousStatus = task.status;
+    task.status = newStatus;
+    task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    task.version = currentVersion + 1;
+    if (bypass && bypassReason) {
+      task.statusBypassAudit = [
+        ...task.statusBypassAudit ?? [],
+        {
+          at: task.updated_at,
+          fromStatus: previousStatus,
+          toStatus: newStatus,
+          reason: bypassReason,
+          ...bypass.actor ? { actor: bypass.actor } : {}
+        }
+      ];
+    }
+    if (previousStatus === "blocked" && newStatus === "blocked" && task.blockedReason && options?.blockedReason && task.blockedReason !== options.blockedReason) {
+      task.blockedReasonHistory = [...task.blockedReasonHistory ?? [], task.blockedReason];
+    }
+    if (newStatus === "blocked" && options?.blockedReason) {
+      task.blockedReason = options.blockedReason;
+    } else if (newStatus !== "blocked") {
+      task.blockedReason = void 0;
+    }
+    if (newStatus === "in_progress" && !task.started_at) {
+      task.started_at = task.updated_at;
+    }
+    if (newStatus === "done") {
+      task.completed_at = task.updated_at;
+    } else if (previousStatus === "done") {
+      task.completed_at = void 0;
+    }
+    if (previousStatus === "cancelled" && newStatus !== "cancelled") {
+      task.cancelledAt = void 0;
+      task.cancelledReason = void 0;
+    }
+    if (options?.resultArtifactPath) {
+      task.resultArtifactPath = options.resultArtifactPath;
+    }
+    await writeMarkdownFile(
+      taskFile,
+      task,
+      updateTaskBodyStatusLine(body, task.status)
+    );
+    if (newStatus === "done") {
+      const unblockedTaskIds = await autoUnblockDependentTasks(task.id, planningRoot);
+      if (unblockedTaskIds.length > 0) {
+        options.onDependentsUnblocked?.(unblockedTaskIds);
+      }
+    }
+    if (task.sprintId) {
+      try {
+        const { refreshSprintMarkdown } = await import("./sprint-manager-IDQUDNQI.js");
+        await refreshSprintMarkdown(task.sprintId);
+      } catch (refreshError) {
+        const msg = refreshError instanceof Error ? refreshError.message : String(refreshError);
+        emitTaskManagerWarning("Failed to refresh sprint markdown after task status change", {
+          sprintId: task.sprintId,
+          taskId: task.id,
+          error: msg
+        });
+      }
+    }
+    return task;
+  });
+}
+async function updateTaskStatusWithTransitionValidation(taskId, newStatus, options) {
+  const { isArchived } = await getTask(taskId, {
+    includeArchive: true
+  });
+  if (isArchived) {
+    throw new Error(
+      `Cannot update archived task "${taskId}". Reopen or restore the task before changing status.`
+    );
+  }
+  return updateTaskStatus(taskId, newStatus, options);
+}
+async function addTaskDependency(taskId, dependsOnTaskId) {
+  const planningRoot = getPlanningRoot();
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(tasksDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    if (task.dependencies.includes(dependsOnTaskId)) {
+      throw new Error(`Dependency already exists: ${taskId} \u2192 ${dependsOnTaskId}`);
+    }
+    if (task.id === dependsOnTaskId) {
+      throw new Error(`Task cannot depend on itself: ${taskId}`);
+    }
+    const taskPath = getBucketPathByKind("task", planningRoot);
+    const taskArchivePath = getBucketArchivePathByKind("task", planningRoot);
+    const allItems = await loadAllItems(planningRoot, [taskPath, taskArchivePath]);
+    const dependencyExists = allItems.some((item) => item.id === dependsOnTaskId);
+    if (!dependencyExists) {
+      throw new Error(`Dependency task not found: ${dependsOnTaskId}`);
+    }
+    const createsCycle = hasDependencyPath(dependsOnTaskId, task.id, allItems);
+    if (createsCycle) {
+      throw new Error(
+        `Circular dependency detected: adding ${task.id} -> ${dependsOnTaskId} would create a cycle`
+      );
+    }
+    task.dependencies.push(dependsOnTaskId);
+    task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    task.version = task.version + 1;
+    await writeMarkdownFile(
+      taskFile,
+      task,
+      body
+    );
+    return task;
+  });
+}
+async function removeTaskDependency(taskId, dependsOnTaskId) {
+  const planningRoot = getPlanningRoot();
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(tasksDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    if (!task.dependencies.includes(dependsOnTaskId)) {
+      throw new Error(`Dependency not found on task: ${taskId} \u2192 ${dependsOnTaskId}`);
+    }
+    task.dependencies = task.dependencies.filter((id) => id !== dependsOnTaskId);
+    task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    task.version += 1;
+    await writeMarkdownFile(
+      taskFile,
+      task,
+      body
+    );
+    return task;
+  });
+}
+function hasDependencyPath(startTaskId, targetTaskId, allItems, visited = /* @__PURE__ */ new Set()) {
+  if (startTaskId === targetTaskId) {
+    return true;
+  }
+  if (visited.has(startTaskId)) {
+    return false;
+  }
+  visited.add(startTaskId);
+  const task = allItems.find((item) => item.id === startTaskId);
+  const dependencies = task?.frontMatter.dependencies;
+  if (!Array.isArray(dependencies) || dependencies.length === 0) {
+    return false;
+  }
+  for (const depId of dependencies) {
+    if (hasDependencyPath(depId, targetTaskId, allItems, visited)) {
+      return true;
+    }
+  }
+  return false;
+}
+async function autoUnblockDependentTasks(completedTaskId, planningRoot) {
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  const files = await listMarkdownFiles(tasksDir);
+  const unblockedTaskIds = [];
+  const rewrites = [];
+  for (const filePath of files) {
+    try {
+      const { frontMatter, body } = await readMarkdownFile(filePath);
+      const task = coerceTaskYAML(frontMatter);
+      if (task.id === completedTaskId) continue;
+      if (task.status !== "blocked") continue;
+      if (!task.dependencies.includes(completedTaskId)) continue;
+      let hasRemainingBlockers = false;
+      for (const depId of task.dependencies) {
+        const dep = await getTaskDependency(depId, { sprintId: task.sprintId });
+        if (dep.missing || !dep.satisfied) {
+          hasRemainingBlockers = true;
+          break;
+        }
+      }
+      if (hasRemainingBlockers) continue;
+      task.status = "todo";
+      task.blockedReason = void 0;
+      task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+      task.version = task.version + 1;
+      rewrites.push({
+        filePath,
+        originalFrontMatter: frontMatter,
+        originalBody: body,
+        nextFrontMatter: task,
+        nextBody: updateTaskBodyStatusLine(body, task.status),
+        taskId: task.id
+      });
+    } catch {
+    }
+  }
+  const applied = [];
+  for (const rewrite of rewrites) {
+    try {
+      await writeMarkdownFile(rewrite.filePath, rewrite.nextFrontMatter, rewrite.nextBody);
+      applied.push(rewrite);
+      unblockedTaskIds.push(rewrite.taskId);
+    } catch (error) {
+      for (const previous of applied.reverse()) {
+        await writeMarkdownFile(
+          previous.filePath,
+          previous.originalFrontMatter,
+          previous.originalBody
+        ).catch(() => void 0);
+      }
+      throw error;
+    }
+  }
+  return unblockedTaskIds;
+}
+async function validateTaskExecution(taskId, options = {}) {
+  const { includeArchive = false } = options;
+  const { yaml: task } = await getTask(taskId, { includeArchive });
+  const blockers = [];
+  if (task.status === "blocked") {
+    blockers.push(`${taskId} (blocked)`);
+  }
+  for (const depId of task.dependencies) {
+    const dep = await getTaskDependency(depId, { sprintId: task.sprintId });
+    if (dep.missing) {
+      blockers.push(`${depId} (not found)`);
+      continue;
+    }
+    if (!dep.satisfied) {
+      blockers.push(`${depId} (status: ${dep.task?.status ?? "unknown"})`);
+    }
+  }
+  return {
+    canExecute: blockers.length === 0,
+    blockers
+  };
+}
+async function logTaskTime(taskId, hours) {
+  const planningRoot = getPlanningRoot();
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(tasksDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    task.timeLoggedHours += hours;
+    task.version = task.version + 1;
+    task.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    await writeMarkdownFile(
+      taskFile,
+      task,
+      body
+    );
+    return task;
+  });
+}
+function deriveTransitionIdentity(input) {
+  if (input.transitionId) {
+    return crypto.createHash("sha256").update(`id\0${input.transitionId}`).digest("hex");
+  }
+  const payload = [
+    "content",
+    input.taskId,
+    input.targetStatus,
+    input.hoursLogged && input.hoursLogged > 0 ? String(input.hoursLogged) : "0",
+    input.resultArtifactPath ?? ""
+  ].join("\0");
+  return crypto.createHash("sha256").update(payload).digest("hex");
+}
+async function applyTaskTransitionOutcome(taskId, input) {
+  const planningRoot = getPlanningRoot();
+  const { isArchived } = await getTask(taskId, { includeArchive: true });
+  if (isArchived) {
+    throw new Error(
+      `Cannot update archived task "${taskId}". Reopen or restore the task before changing status.`
+    );
+  }
+  return withIndexRegeneration(planningRoot, async () => {
+    const tasksDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(tasksDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    const constituents = input.constituents && input.constituents.length > 0 ? input.constituents : [
+      {
+        identity: deriveTransitionIdentity({
+          taskId,
+          targetStatus: input.targetStatus,
+          hoursLogged: input.hoursLogged,
+          resultArtifactPath: input.resultArtifactPath
+        }),
+        hoursLogged: input.hoursLogged
+      }
+    ];
+    const recordedSet = new Set(task.appliedTransitions ?? []);
+    const pendingHourIdentities = [];
+    const seenThisCall = /* @__PURE__ */ new Set();
+    let pendingHours = 0;
+    for (const c of constituents) {
+      if (recordedSet.has(c.identity) || seenThisCall.has(c.identity)) continue;
+      seenThisCall.add(c.identity);
+      pendingHourIdentities.push(c.identity);
+      if (c.hoursLogged && c.hoursLogged > 0) {
+        pendingHours += c.hoursLogged;
+      }
+    }
+    const hoursPending = pendingHours > 0;
+    const statusChanged = task.status !== input.targetStatus;
+    const artifactChanged = Boolean(
+      input.resultArtifactPath && task.resultArtifactPath !== input.resultArtifactPath
+    );
+    const reason = input.reason?.trim();
+    const reasonChanged = Boolean(reason && task.lastTransitionReason !== reason);
+    if (!statusChanged && !artifactChanged && !reasonChanged && !hoursPending) {
+      return { task, statusChanged: false, fileUpdated: false, hoursApplied: 0 };
+    }
+    if (statusChanged) {
+      const transition = await validateStateTransition(
+        planningRoot,
+        taskId,
+        task.status,
+        input.targetStatus
+      );
+      if (!transition.success) {
+        const details = transition.errors?.length ? `: ${transition.errors.join("; ")}` : "";
+        throw new Error(`${transition.message}${details}`);
+      }
+    }
+    if (statusChanged && input.targetStatus === "done") {
+      await assertCompletionContractsMet({
+        contracts: task.completionContract
+      });
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const previousStatus = task.status;
+    if (statusChanged) {
+      task.status = input.targetStatus;
+      if (input.targetStatus === "in_progress" && !task.started_at) {
+        task.started_at = now;
+      }
+      if (input.targetStatus === "done") {
+        task.completed_at = now;
+      } else if (previousStatus === "done") {
+        task.completed_at = void 0;
+      }
+      if (input.targetStatus !== "blocked") {
+        task.blockedReason = void 0;
+      }
+    }
+    if (artifactChanged && input.resultArtifactPath) {
+      task.resultArtifactPath = input.resultArtifactPath;
+    }
+    if (reasonChanged && reason) {
+      task.lastTransitionReason = reason;
+    }
+    let hoursApplied = 0;
+    if (hoursPending) {
+      task.timeLoggedHours += pendingHours;
+      hoursApplied = pendingHours;
+      const next = task.appliedTransitions ? [...task.appliedTransitions] : [];
+      for (const id of pendingHourIdentities) {
+        next.push(id);
+      }
+      task.appliedTransitions = next;
+    }
+    task.version = task.version + 1;
+    task.updated_at = now;
+    await writeMarkdownFile(
+      taskFile,
+      task,
+      updateTaskBodyStatusLine(body, task.status)
+    );
+    if (statusChanged && input.targetStatus === "done") {
+      await autoUnblockDependentTasks(task.id, planningRoot).catch((error) => {
+        emitTaskManagerWarning("Failed to auto-unblock dependent tasks after transition", {
+          taskId: task.id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    }
+    if (task.sprintId) {
+      try {
+        const { refreshSprintMarkdown } = await import("./sprint-manager-IDQUDNQI.js");
+        await refreshSprintMarkdown(task.sprintId);
+      } catch (refreshError) {
+        const msg = refreshError instanceof Error ? refreshError.message : String(refreshError);
+        emitTaskManagerWarning("Failed to refresh sprint markdown after task transition", {
+          sprintId: task.sprintId,
+          taskId: task.id,
+          error: msg
+        });
+      }
+    }
+    return { task, statusChanged, fileUpdated: true, hoursApplied };
+  });
+}
+async function findArchivedDuplicate(taskId, planningRoot) {
+  const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+  return findArchivedTaskFile(archiveDir, taskId);
+}
+async function readTaskForCompletionEval(taskId, planningRoot) {
+  const currentDir = getBucketPathByKind("task", planningRoot);
+  const files = await listMarkdownFiles(currentDir);
+  const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+  if (!taskFile) {
+    throw new Error(`Task not found: ${taskId}`);
+  }
+  const { frontMatter } = await readMarkdownFile(taskFile);
+  const task = coerceTaskYAML(frontMatter);
+  return { task };
+}
+function completionContractSnapshotKey(contracts) {
+  if (!contracts || contracts.length === 0) return "";
+  return JSON.stringify(contracts);
+}
+async function completeTask(taskId, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const forceCompletion = options.force ?? false;
+  const bypass = options.bypassValidation;
+  const bypassReason = bypass?.reason.trim();
+  if (bypass && !bypassReason) {
+    throw new Error("Task status validation bypass requires a reason");
+  }
+  const preEval = await readTaskForCompletionEval(taskId, planningRoot);
+  const preEvalArchivedDuplicate = await findArchivedDuplicate(taskId, planningRoot);
+  if (preEvalArchivedDuplicate) {
+    throw new Error(
+      `Task ${taskId} has both active and archived records. Completion is blocked to avoid overwriting managed state. Run poetic doctor for details; do not edit managed files manually.`
+    );
+  }
+  if (!forceCompletion && (preEval.task.status === "blocked" || preEval.task.status === "cancelled")) {
+    throw new Error(
+      `Cannot complete task ${preEval.task.id} from status "${preEval.task.status}" without --force. Move it to in_progress/review first.`
+    );
+  }
+  const evaluatedVersion = preEval.task.version;
+  const evaluatedContractKey = completionContractSnapshotKey(preEval.task.completionContract);
+  await assertCompletionContractsMet({
+    contracts: preEval.task.completionContract,
+    bypassReason,
+    workingDir: options.completionContractRoot
+  });
+  return withIndexRegeneration(planningRoot, async () => {
+    const bucket = getBucketByName("task", planningRoot);
+    if (!bucket) {
+      throw new Error("Bucket not configured: task");
+    }
+    const currentDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(currentDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const archivedDuplicate = await findArchivedDuplicate(taskId, planningRoot);
+    if (archivedDuplicate) {
+      throw new Error(
+        `Task ${taskId} has both active and archived records. Completion is blocked to avoid overwriting managed state. Run poetic doctor for details; do not edit managed files manually.`
+      );
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    if (task.version !== evaluatedVersion || completionContractSnapshotKey(task.completionContract) !== evaluatedContractKey) {
+      throw new StaleVersionError(
+        task.version,
+        evaluatedVersion,
+        taskId,
+        "completionContract",
+        "concurrent task mutation between completion-contract evaluation and archive write"
+      );
+    }
+    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")) && !bypass) {
+      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 now = (/* @__PURE__ */ new Date()).toISOString();
+    if (forceCompletion && task.status !== "done") {
+      task.forceCompletedFrom = task.status;
+      if (options.preserveBlockedReason && task.status === "blocked" && task.blockedReason) {
+        task.originalBlockedReason = task.blockedReason;
+      }
+    }
+    const previousStatus = task.status;
+    task.status = "done";
+    task.version = task.version + 1;
+    task.completed_at = now;
+    task.updated_at = now;
+    task.archivedAt = now;
+    task.originalSprintId = task.sprintId;
+    if (bypass && bypassReason) {
+      task.statusBypassAudit = [
+        ...task.statusBypassAudit ?? [],
+        {
+          at: now,
+          fromStatus: previousStatus,
+          toStatus: "done",
+          reason: bypassReason,
+          ...bypass.actor ? { actor: bypass.actor } : {}
+        }
+      ];
+    }
+    const archivedPath = getArchivedFilePath(bucket, task.id, now, planningRoot);
+    await ensureDirectoryExists(path.dirname(archivedPath));
+    await writeMarkdownFile(archivedPath, toArchivedTaskFrontMatter(task), body);
+    try {
+      await detachArchivedTaskFromSprintMembership(task, "archiving");
+    } catch (error) {
+      await fs.unlink(archivedPath).catch(() => void 0);
+      throw error;
+    }
+    const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+    const archivedIndex = archivedTaskIndexes.get(archiveDir);
+    if (archivedIndex) {
+      archivedIndex.set(task.id, archivedPath);
+    }
+    await fs.unlink(taskFile);
+    const unblockedTaskIds = await autoUnblockDependentTasks(task.id, planningRoot).catch(
+      (error) => {
+        emitTaskManagerWarning("Failed to auto-unblock dependent tasks after completion", {
+          taskId: task.id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return [];
+      }
+    );
+    return { task, archivedPath, unblockedTaskIds };
+  });
+}
+function toArchivedTaskFrontMatter(task) {
+  const frontMatter = { ...task };
+  delete frontMatter.sprintId;
+  delete frontMatter.sprint_id;
+  return frontMatter;
+}
+function getErrorCode(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) return void 0;
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+async function detachArchivedTaskFromSprintMembership(task, action) {
+  if (!task.sprintId) return;
+  try {
+    const { detachArchivedTaskFromSprint } = await import("./sprint-manager-IDQUDNQI.js");
+    await detachArchivedTaskFromSprint(task.sprintId, task.id, {
+      completed: action === "archiving"
+    });
+  } catch (removeError) {
+    if (getErrorCode(removeError) === "ENOENT") {
+      return;
+    }
+    const removeMessage = removeError instanceof Error ? removeError.message : String(removeError);
+    try {
+      const { refreshSprintMarkdown } = await import("./sprint-manager-IDQUDNQI.js");
+      await refreshSprintMarkdown(task.sprintId);
+    } catch (refreshError) {
+      emitTaskManagerWarning(`Failed to refresh sprint markdown after ${action} task`, {
+        sprintId: task.sprintId,
+        taskId: task.id,
+        action,
+        error: refreshError instanceof Error ? refreshError.message : String(refreshError)
+      });
+    }
+    throw new Error(
+      `Failed to remove task ${task.id} from sprint ${task.sprintId} after ${action}: ${removeMessage}`
+    );
+  }
+}
+function getCancelledTaskArchivePath(taskId, cancelledAt, planningRoot) {
+  const shard = getArchiveShard(cancelledAt);
+  const taskBucket = getBucketPathByKind("task", planningRoot);
+  const archiveRoot = getBucketArchivePathByKind("task", planningRoot);
+  const extraSegments = path.relative(taskBucket, archiveRoot).split(path.sep).filter(Boolean);
+  extraSegments.push("abandoned", shard.year, shard.month);
+  return resolvePlanningItemPath(taskBucket, taskId, {
+    label: "taskId",
+    extraSegments
+  });
+}
+async function cancelTask(taskId, options) {
+  const planningRoot = getPlanningRoot();
+  const reason = options.reason.trim();
+  if (!reason) {
+    throw new Error("Cancellation reason is required");
+  }
+  return withIndexRegeneration(planningRoot, async () => {
+    const currentDir = getBucketPathByKind("task", planningRoot);
+    const files = await listMarkdownFiles(currentDir);
+    const taskFile = files.find((f) => path.basename(f) === `${taskId}.md`);
+    if (!taskFile) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    const { frontMatter, body } = await readMarkdownFile(taskFile);
+    const task = coerceTaskYAML(frontMatter);
+    if (options.expectedVersion !== void 0 && task.version !== options.expectedVersion) {
+      throw new StaleVersionError(task.version, options.expectedVersion, taskId);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const bypass = options.bypassValidation;
+    const bypassReason = bypass?.reason.trim();
+    if (bypass && !bypassReason) {
+      throw new Error("Task status validation bypass requires a reason");
+    }
+    if (!bypass) {
+      const transition = await validateStateTransition(
+        planningRoot,
+        taskId,
+        task.status,
+        "cancelled"
+      );
+      if (!transition.success) {
+        const details = transition.errors?.length ? `: ${transition.errors.join("; ")}` : "";
+        throw new Error(`${transition.message}${details}`);
+      }
+    }
+    const previousStatus = task.status;
+    task.status = "cancelled";
+    task.version = task.version + 1;
+    task.cancelledAt = now;
+    task.cancelledReason = reason;
+    task.updated_at = now;
+    task.archivedAt = now;
+    task.completed_at = void 0;
+    task.originalSprintId = task.sprintId;
+    if (bypass && bypassReason) {
+      task.statusBypassAudit = [
+        ...task.statusBypassAudit ?? [],
+        {
+          at: now,
+          fromStatus: previousStatus,
+          toStatus: "cancelled",
+          reason: bypassReason,
+          ...bypass.actor ? { actor: bypass.actor } : {}
+        }
+      ];
+    }
+    const archivedPath = getCancelledTaskArchivePath(task.id, now, planningRoot);
+    await ensureDirectoryExists(path.dirname(archivedPath));
+    await writeMarkdownFile(archivedPath, toArchivedTaskFrontMatter(task), body);
+    try {
+      await detachArchivedTaskFromSprintMembership(task, "cancelling");
+    } catch (error) {
+      await fs.unlink(archivedPath).catch(() => void 0);
+      throw error;
+    }
+    const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+    const archivedIndex = archivedTaskIndexes.get(archiveDir);
+    if (archivedIndex) {
+      archivedIndex.set(task.id, archivedPath);
+    }
+    await fs.unlink(taskFile);
+    return { task, archivedPath };
+  });
+}
+async function restoreTask(taskId, options = {}) {
+  const planningRoot = getPlanningRoot();
+  const targetStatus = options.status ?? "in_progress";
+  return withIndexRegeneration(planningRoot, async () => {
+    const { filePath, isArchived } = await getTask(taskId, { includeArchive: true });
+    const { frontMatter, body } = await readMarkdownFile(filePath);
+    const task = coerceTaskYAML(frontMatter);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    let restoreIntoSprint = false;
+    let sprintAlreadyMember = false;
+    if (task.sprintId) {
+      const { assertSprintCanAcceptRestoredTask } = await import("./sprint-manager-IDQUDNQI.js");
+      const acceptance = await assertSprintCanAcceptRestoredTask(task.sprintId, task.id);
+      if (acceptance.sprintExists) {
+        restoreIntoSprint = true;
+        sprintAlreadyMember = acceptance.alreadyMember;
+      }
+    }
+    task.status = targetStatus;
+    task.version = task.version + 1;
+    task.updated_at = now;
+    task.completed_at = void 0;
+    delete task.archivedAt;
+    delete task.cancelledAt;
+    delete task.cancelledReason;
+    delete task.originalSprintId;
+    const restoredPath = resolvePlanningItemPath(
+      getBucketPathByKind("task", planningRoot),
+      taskId,
+      { label: "taskId" }
+    );
+    await ensureDirectoryExists(path.dirname(restoredPath));
+    await writeMarkdownFile(
+      restoredPath,
+      task,
+      body
+    );
+    try {
+      if (restoreIntoSprint && task.sprintId) {
+        const { addTaskToSprint, refreshSprintMarkdown, removeTaskFromSprint } = await import("./sprint-manager-IDQUDNQI.js");
+        if (isArchived && !sprintAlreadyMember) {
+          await addTaskToSprint(task.sprintId, task.id, task.estimatedHours);
+        }
+        try {
+          await refreshSprintMarkdown(task.sprintId);
+        } catch (refreshError) {
+          if (isArchived && !sprintAlreadyMember) {
+            await removeTaskFromSprint(task.sprintId, task.id).catch(() => void 0);
+          }
+          throw refreshError;
+        }
+      }
+    } catch (restoreError) {
+      if (isArchived) {
+        await fs.unlink(restoredPath).catch(() => void 0);
+      }
+      throw restoreError;
+    }
+    if (isArchived) {
+      await fs.unlink(filePath);
+      const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+      const archivedIndex = archivedTaskIndexes.get(archiveDir);
+      archivedIndex?.delete(task.id);
+    }
+    return { task, restoredPath };
+  });
+}
+var MAX_AMBIGUOUS_MATCH_PREVIEW = 5;
+function resolveTaskIdFromPrefix(candidateIds, query) {
+  const uniqueIds = [...new Set(candidateIds)];
+  const matches = uniqueIds.filter((id) => id === query || id.startsWith(query));
+  if (matches.length === 0) {
+    return null;
+  }
+  if (matches.length === 1) {
+    return matches[0] ?? null;
+  }
+  const preview = matches.slice(0, MAX_AMBIGUOUS_MATCH_PREVIEW).join(", ");
+  const suffix = matches.length > MAX_AMBIGUOUS_MATCH_PREVIEW ? ", ..." : "";
+  throw new Error(
+    `Ambiguous task ID prefix "${query}": matches ${matches.length} tasks (${preview}${suffix}). Use a longer prefix or the full ID.`
+  );
+}
+async function loadTaskLookupFromFile(filePath, isArchived) {
+  const { frontMatter } = await readMarkdownFile(filePath);
+  return {
+    yaml: coerceTaskYAML(frontMatter),
+    filePath,
+    isArchived
+  };
+}
+async function collectKnownTaskIds(planningRoot, tasksDir, includeArchive) {
+  const ids = [];
+  const activeFiles = await listMarkdownFiles(tasksDir);
+  for (const filePath of activeFiles) {
+    const id = path.basename(filePath, ".md");
+    if (id) {
+      ids.push(id);
+    }
+  }
+  if (includeArchive) {
+    try {
+      const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+      const index = await getArchivedTaskIndex(archiveDir);
+      ids.push(...index.keys());
+    } catch {
+    }
+  }
+  return ids;
+}
+async function getTask(taskId, options = {}) {
+  const { includeArchive = false } = options;
+  const planningRoot = getPlanningRoot();
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  const activeTaskFile = resolvePlanningItemPath(tasksDir, taskId, { label: "taskId" });
+  try {
+    await fs.access(activeTaskFile);
+    return loadTaskLookupFromFile(activeTaskFile, false);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  if (includeArchive) {
+    try {
+      const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+      const archivedTaskFile = await findArchivedTaskFile(archiveDir, taskId);
+      if (archivedTaskFile) {
+        return loadTaskLookupFromFile(archivedTaskFile, true);
+      }
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  const resolvedId = resolveTaskIdFromPrefix(
+    await collectKnownTaskIds(planningRoot, tasksDir, includeArchive),
+    taskId
+  );
+  if (resolvedId && resolvedId !== taskId) {
+    return getTask(resolvedId, options);
+  }
+  throw new Error(`Task not found: ${taskId}`);
+}
+var archivedTaskIndexes = /* @__PURE__ */ new Map();
+function clearArchivedTaskIndex() {
+  archivedTaskIndexes.clear();
+}
+async function buildArchivedTaskIndex(archiveDir) {
+  const files = await listMarkdownFilesRecursiveStrict(archiveDir);
+  const index = /* @__PURE__ */ new Map();
+  for (const filePath of files) {
+    const base = path.basename(filePath);
+    if (!base.endsWith(".md")) continue;
+    const id = base.slice(0, -3);
+    if (!id) continue;
+    index.set(id, filePath);
+  }
+  return index;
+}
+async function getArchivedTaskIndex(archiveDir) {
+  let index = archivedTaskIndexes.get(archiveDir);
+  if (!index) {
+    index = await buildArchivedTaskIndex(archiveDir);
+    archivedTaskIndexes.set(archiveDir, index);
+  }
+  return index;
+}
+async function findArchivedTaskFile(archiveDir, taskId) {
+  if (isValidId(taskId)) {
+    const index = await getArchivedTaskIndex(archiveDir);
+    const directMatch = index.get(taskId);
+    if (directMatch) {
+      return directMatch;
+    }
+    const rebuiltIndex = await buildArchivedTaskIndex(archiveDir);
+    archivedTaskIndexes.set(archiveDir, rebuiltIndex);
+    return rebuiltIndex.get(taskId) ?? null;
+  }
+  const files = await listMarkdownFilesRecursiveStrict(archiveDir);
+  return files.find((f) => path.basename(f) === `${taskId}.md`) ?? null;
+}
+async function getTaskAny(taskId) {
+  return getTask(taskId, { includeArchive: true });
+}
+async function resolveTask(taskId) {
+  return getTask(taskId, { includeArchive: true });
+}
+async function getTaskActive(taskId) {
+  return getTask(taskId, { includeArchive: false });
+}
+async function getTaskDependency(depId, options = {}) {
+  try {
+    const result = await getTask(depId, { includeArchive: true });
+    const classification = classifyTaskDependency(depId, {
+      task: { status: result.yaml.status, isArchived: result.isArchived }
+    });
+    return {
+      missing: classification.state === "missing",
+      satisfied: classification.satisfied,
+      isArchived: classification.isArchived,
+      task: result.yaml
+    };
+  } catch {
+    let recordedComplete = false;
+    if (options.sprintId) {
+      try {
+        const { isTaskRecordedCompletedInSprint } = await import("./sprint-manager-IDQUDNQI.js");
+        recordedComplete = await isTaskRecordedCompletedInSprint(options.sprintId, depId);
+      } catch {
+      }
+    }
+    const classification = classifyTaskDependency(depId, {
+      task: null,
+      recordedComplete
+    });
+    return {
+      missing: classification.state === "missing",
+      satisfied: classification.satisfied,
+      isArchived: classification.isArchived
+    };
+  }
+}
+async function getAllTasks(options = {}) {
+  const { includeArchive = false } = options;
+  const planningRoot = getPlanningRoot();
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  const results = [];
+  const activeFiles = await listMarkdownFiles(tasksDir);
+  for (const filePath of activeFiles) {
+    try {
+      const { frontMatter } = await readMarkdownFile(filePath);
+      results.push({
+        yaml: coerceTaskYAML(frontMatter),
+        filePath,
+        isArchived: false
+      });
+    } catch {
+    }
+  }
+  if (includeArchive) {
+    try {
+      const archiveDir = getBucketArchivePathByKind("task", planningRoot);
+      const archiveFiles = await listMarkdownFilesRecursive(archiveDir);
+      for (const filePath of archiveFiles) {
+        try {
+          const { frontMatter } = await readMarkdownFile(filePath);
+          results.push({
+            yaml: coerceTaskYAML(frontMatter),
+            filePath,
+            isArchived: true
+          });
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
+  return results;
+}
+async function listTasksLinkedToBacklogItem(backlogItemId, options = {}) {
+  const { includeArchive = false } = options;
+  const allTasks = await getAllTasks({ includeArchive });
+  return allTasks.filter((result) => result.yaml.backlogItemId === backlogItemId).map((result) => ({
+    id: result.yaml.id,
+    title: result.yaml.title,
+    status: result.yaml.status,
+    sprintId: result.yaml.sprintId
+  })).sort((a, b) => a.id.localeCompare(b.id));
+}
+async function listTasksInSprint(sprintId, statusFilter) {
+  try {
+    const { listTasksInSprint: listSprintTaskRefs } = await import("./sprint-manager-IDQUDNQI.js");
+    const sprintTasks = await listSprintTaskRefs(sprintId);
+    const tasks2 = [];
+    for (const sprintTask of sprintTasks) {
+      if (sprintTask.missing === true) continue;
+      try {
+        const { yaml: task, isArchived } = await getTask(sprintTask.id, { includeArchive: true });
+        if (isArchived) continue;
+        if (!statusFilter || task.status === statusFilter) {
+          tasks2.push(task);
+        }
+      } catch {
+      }
+    }
+    return tasks2;
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : void 0;
+    const message = error instanceof Error ? error.message : String(error);
+    if (code !== "ENOENT" && !message.includes(`Sprint not found: ${sprintId}`)) {
+      throw error;
+    }
+  }
+  const planningRoot = getPlanningRoot();
+  const tasksDir = getBucketPathByKind("task", planningRoot);
+  const files = await listMarkdownFiles(tasksDir);
+  const tasks = [];
+  for (const file of files) {
+    let task;
+    try {
+      const { frontMatter } = await readMarkdownFile(file);
+      task = coerceTaskYAML(frontMatter);
+    } catch {
+      continue;
+    }
+    if (task.sprintId === sprintId) {
+      if (!statusFilter || task.status === statusFilter) {
+        tasks.push(task);
+      }
+    }
+  }
+  return tasks;
+}
+
+export {
+  generateTaskId,
+  createTask,
+  createTaskWithGuidance,
+  updateTaskFields,
+  updateTaskStatus,
+  updateTaskStatusWithTransitionValidation,
+  addTaskDependency,
+  removeTaskDependency,
+  validateTaskExecution,
+  logTaskTime,
+  deriveTransitionIdentity,
+  applyTaskTransitionOutcome,
+  completeTask,
+  cancelTask,
+  restoreTask,
+  resolveTaskIdFromPrefix,
+  getTask,
+  clearArchivedTaskIndex,
+  getTaskAny,
+  resolveTask,
+  getTaskActive,
+  getTaskDependency,
+  getAllTasks,
+  listTasksLinkedToBacklogItem,
+  listTasksInSprint
+};
+//# sourceMappingURL=chunk-5LTN43AS.js.map