@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/dist/chunk-NKLPMBNV.js

@@ -0,0 +1,1154 @@
+import {
+  TaskTypeAliasMap
+} from "./chunk-2KO7HVZM.js";
+import {
+  boundTypeFromIntent,
+  calculateGuidanceTier,
+  extractFileHintPaths,
+  generatePromptInjection,
+  generateSpecQualitySignals,
+  getBoundType,
+  hasUnfilledMarkers,
+  validateTaskSpec
+} from "./chunk-UAPHFJPN.js";
+import {
+  TaskTypeRegistry
+} from "./chunk-6T6NHXK4.js";
+import {
+  fromPersistedFormat,
+  generateEnhancements,
+  getArchivedFilePath,
+  hintsFromEnhancements,
+  isInArchive,
+  resolveBucketArchiveRoot,
+  toEnhancementSet,
+  toPersistedFormat
+} from "./chunk-US3RT6CY.js";
+import {
+  validateCompletionContracts
+} from "./chunk-MCBNWZNO.js";
+import {
+  appendActivity,
+  keepActivity
+} from "./chunk-J2QCFLUN.js";
+import {
+  withIndexRegeneration
+} from "./chunk-CSXLLEGB.js";
+import {
+  createWorkItemFile
+} from "./chunk-CIHWPGS5.js";
+import {
+  getBucketByName
+} from "./chunk-V3KLVK7B.js";
+import {
+  resolvePlanningContext
+} from "./chunk-BBPIILO2.js";
+import {
+  isValidId
+} from "./chunk-4DJL2VXA.js";
+import {
+  detectProjectCapabilities
+} from "./chunk-AHU3FKPA.js";
+import {
+  isPersistedWorkEdge,
+  listMarkdownFiles,
+  listMarkdownFilesRecursive,
+  parseMarkdownFile,
+  writeMarkdownFile
+} from "./chunk-352PCJLK.js";
+import {
+  emitCustomWarning
+} from "./chunk-7VRJHTGZ.js";
+
+// src/planning/backlog-manager.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+
+// src/planning/schema-validator.ts
+var BACKLOG_STATUSES = ["inbox", "reviewed", "archived", "done"];
+var PRIORITIES = ["P0", "P1", "P2", "P3"];
+var DEBT_SEVERITIES = ["critical", "high", "medium", "low"];
+var DEBT_EFFORTS = ["low", "medium", "high"];
+var DEBT_STATUSES = ["pending", "in-progress", "completed", "blocked", "archived"];
+var PARKING_STATUSES = ["current", "reconsidering", "re-prioritized", "archived"];
+var SPRINT_STATUSES = ["planning", "active", "completed", "archived"];
+var TASK_STATUSES = [
+  "todo",
+  "in_progress",
+  "review",
+  "done",
+  "pending",
+  "in-progress",
+  "completed",
+  "blocked",
+  "archived",
+  "cancelled",
+  "canceled"
+];
+function validateBaseFrontMatter(frontMatter, expectedKind, errors) {
+  if (typeof frontMatter.id !== "string" || frontMatter.id.length === 0) {
+    errors.push({
+      field: "id",
+      message: "Missing required field: id",
+      suggestion: "Use format: YYYYMMDDTHHMMSSZ-<uuidHex12> (UTC)"
+    });
+  } else if (!isValidId(frontMatter.id)) {
+    errors.push({
+      field: "id",
+      message: `Invalid id format: ${frontMatter.id}`,
+      suggestion: "Expected: YYYYMMDDTHHMMSSZ-<uuidHex12> (UTC)"
+    });
+  }
+  if (typeof frontMatter.kind !== "string" || frontMatter.kind.length === 0) {
+    errors.push({
+      field: "kind",
+      message: "Missing required field: kind",
+      suggestion: `Must be: ${expectedKind}`
+    });
+  } else if (frontMatter.kind !== expectedKind) {
+    errors.push({
+      field: "kind",
+      message: `Invalid kind: ${frontMatter.kind}`,
+      suggestion: `Must be: ${expectedKind}`
+    });
+  }
+  if (typeof frontMatter.title !== "string" || frontMatter.title.trim().length === 0) {
+    errors.push({
+      field: "title",
+      message: "Missing required field: title",
+      suggestion: "Provide a descriptive title"
+    });
+  }
+}
+function validateExpectedRuntimeMinutes(value, errors) {
+  if (value === void 0) return;
+  const minutes = Number(value);
+  if (Number.isNaN(minutes) || !Number.isFinite(minutes) || minutes <= 0) {
+    errors.push({
+      field: "expectedRuntimeMinutes",
+      message: `Invalid expectedRuntimeMinutes: ${String(value)}`,
+      suggestion: "Must be a positive number of minutes"
+    });
+  }
+}
+function validateBacklogItem(frontMatter) {
+  const errors = [];
+  validateBaseFrontMatter(frontMatter, "backlog", errors);
+  if (!frontMatter.status) {
+    errors.push({
+      field: "status",
+      message: "Missing required field: status",
+      suggestion: `Must be one of: ${BACKLOG_STATUSES.join(", ")}`
+    });
+  } else if (!BACKLOG_STATUSES.includes(frontMatter.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${frontMatter.status}`,
+      suggestion: `Must be one of: ${BACKLOG_STATUSES.join(", ")}`
+    });
+  }
+  if (frontMatter.priority && !PRIORITIES.includes(frontMatter.priority)) {
+    errors.push({
+      field: "priority",
+      message: `Invalid priority: ${frontMatter.priority}`,
+      suggestion: `Must be one of: ${PRIORITIES.join(", ")}`
+    });
+  }
+  if (frontMatter.estimatedComplexity !== void 0) {
+    const complexity = Number(frontMatter.estimatedComplexity);
+    if (Number.isNaN(complexity) || complexity < 0 || complexity > 1) {
+      errors.push({
+        field: "estimatedComplexity",
+        message: `Invalid estimatedComplexity: ${frontMatter.estimatedComplexity}`,
+        suggestion: "Must be a number between 0.0 and 1.0"
+      });
+    }
+  }
+  validateExpectedRuntimeMinutes(frontMatter.expectedRuntimeMinutes, errors);
+  if (frontMatter.workEdges !== void 0) {
+    if (!Array.isArray(frontMatter.workEdges)) {
+      errors.push({
+        field: "workEdges",
+        message: "workEdges must be an array of persisted canonical edges",
+        suggestion: "Run `build plan backlog graph migrate` to inspect legacy/unbound edges"
+      });
+    } else {
+      frontMatter.workEdges.forEach((edge, index) => {
+        if (!isPersistedWorkEdge(edge)) {
+          errors.push({
+            field: `workEdges[${index}]`,
+            message: "Malformed persisted work edge",
+            suggestion: "Each edge needs non-empty from/to/declaredOn/declaredTarget, a valid type (depends_on|supersedes), known fromKind/toKind, and a known declaredBy (blocks|blocked-by|supersedes|superseded_by)"
+          });
+        }
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateDebtItem(frontMatter) {
+  const errors = [];
+  validateBaseFrontMatter(frontMatter, "tech-debt", errors);
+  if (frontMatter.severity && !DEBT_SEVERITIES.includes(frontMatter.severity)) {
+    errors.push({
+      field: "severity",
+      message: `Invalid severity: ${frontMatter.severity}`,
+      suggestion: `Must be one of: ${DEBT_SEVERITIES.join(", ")}`
+    });
+  }
+  if (!frontMatter.status) {
+    errors.push({
+      field: "status",
+      message: "Missing required field: status",
+      suggestion: `Must be one of: ${DEBT_STATUSES.join(", ")}`
+    });
+  } else if (!DEBT_STATUSES.includes(frontMatter.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${frontMatter.status}`,
+      suggestion: `Must be one of: ${DEBT_STATUSES.join(", ")}`
+    });
+  }
+  if (frontMatter.effort && !DEBT_EFFORTS.includes(frontMatter.effort)) {
+    errors.push({
+      field: "effort",
+      message: `Invalid effort: ${frontMatter.effort}`,
+      suggestion: `Must be one of: ${DEBT_EFFORTS.join(", ")}`
+    });
+  }
+  if (frontMatter.estimatedComplexity !== void 0) {
+    const complexity = Number(frontMatter.estimatedComplexity);
+    if (Number.isNaN(complexity) || complexity < 0 || complexity > 1) {
+      errors.push({
+        field: "estimatedComplexity",
+        message: `Invalid estimatedComplexity: ${frontMatter.estimatedComplexity}`,
+        suggestion: "Must be a number between 0.0 and 1.0"
+      });
+    }
+  }
+  validateExpectedRuntimeMinutes(frontMatter.expectedRuntimeMinutes, errors);
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateParkingItem(frontMatter) {
+  const errors = [];
+  validateBaseFrontMatter(frontMatter, "parking-lot", errors);
+  if (!frontMatter.status) {
+    errors.push({
+      field: "status",
+      message: "Missing required field: status",
+      suggestion: `Must be one of: ${PARKING_STATUSES.join(", ")}`
+    });
+  } else if (!PARKING_STATUSES.includes(frontMatter.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${frontMatter.status}`,
+      suggestion: `Must be one of: ${PARKING_STATUSES.join(", ")}`
+    });
+  }
+  if (frontMatter.estimatedComplexity !== void 0) {
+    const complexity = Number(frontMatter.estimatedComplexity);
+    if (Number.isNaN(complexity) || complexity < 0 || complexity > 1) {
+      errors.push({
+        field: "estimatedComplexity",
+        message: `Invalid estimatedComplexity: ${frontMatter.estimatedComplexity}`,
+        suggestion: "Must be a number between 0.0 and 1.0"
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateSprintItem(frontMatter) {
+  const errors = [];
+  validateBaseFrontMatter(frontMatter, "sprint", errors);
+  if (!frontMatter.status) {
+    errors.push({
+      field: "status",
+      message: "Missing required field: status",
+      suggestion: `Must be one of: ${SPRINT_STATUSES.join(", ")}`
+    });
+  } else if (!SPRINT_STATUSES.includes(frontMatter.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${frontMatter.status}`,
+      suggestion: `Must be one of: ${SPRINT_STATUSES.join(", ")}`
+    });
+  }
+  if (frontMatter.capacity) {
+    const cap = frontMatter.capacity;
+    if (typeof cap !== "object") {
+      errors.push({
+        field: "capacity",
+        message: "capacity must be an object",
+        suggestion: "Use format: { totalHours, allocatedHours, remainingHours, utilizationPercent }"
+      });
+    } else {
+      if (cap.totalHours !== void 0 && typeof cap.totalHours !== "number") {
+        errors.push({
+          field: "capacity.totalHours",
+          message: "capacity.totalHours must be a number"
+        });
+      }
+      if (cap.allocatedHours !== void 0 && typeof cap.allocatedHours !== "number") {
+        errors.push({
+          field: "capacity.allocatedHours",
+          message: "capacity.allocatedHours must be a number"
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateTaskItem(frontMatter) {
+  const errors = [];
+  validateBaseFrontMatter(frontMatter, "task", errors);
+  if (!frontMatter.status) {
+    errors.push({
+      field: "status",
+      message: "Missing required field: status",
+      suggestion: `Must be one of: ${TASK_STATUSES.join(", ")}`
+    });
+  } else if (!TASK_STATUSES.includes(frontMatter.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${frontMatter.status}`,
+      suggestion: `Must be one of: ${TASK_STATUSES.join(", ")}`
+    });
+  }
+  if (frontMatter.priority && !PRIORITIES.includes(frontMatter.priority)) {
+    errors.push({
+      field: "priority",
+      message: `Invalid priority: ${frontMatter.priority}`,
+      suggestion: `Must be one of: ${PRIORITIES.join(", ")}`
+    });
+  }
+  if (frontMatter.complexity !== void 0) {
+    const complexity = Number(frontMatter.complexity);
+    if (Number.isNaN(complexity) || complexity < 0 || complexity > 1) {
+      errors.push({
+        field: "complexity",
+        message: `Invalid complexity: ${frontMatter.complexity}`,
+        suggestion: "Must be a number between 0.0 and 1.0"
+      });
+    }
+  }
+  if (frontMatter.estimatedHours !== void 0) {
+    const hours = Number(frontMatter.estimatedHours);
+    if (Number.isNaN(hours) || hours < 0) {
+      errors.push({
+        field: "estimatedHours",
+        message: `Invalid estimatedHours: ${frontMatter.estimatedHours}`,
+        suggestion: "Must be a positive number"
+      });
+    }
+  }
+  validateExpectedRuntimeMinutes(frontMatter.expectedRuntimeMinutes, errors);
+  if (frontMatter.dependencies !== void 0 && !Array.isArray(frontMatter.dependencies)) {
+    errors.push({
+      field: "dependencies",
+      message: "dependencies must be an array of task IDs",
+      suggestion: 'Use format: ["<id>", "<id>"]'
+    });
+  }
+  if (frontMatter.completionContract !== void 0) {
+    const contractValidation = validateCompletionContracts(frontMatter.completionContract);
+    for (const contractError of contractValidation.errors) {
+      errors.push({
+        field: contractError.field,
+        message: contractError.message,
+        suggestion: "Use typed completion contracts: path_exists, file_contains, glob_exists, command_passes, test_passes, llm_judge"
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// src/planning/backlog-manager.ts
+async function resolveDeclaredTypeAtCreation(rootDir, declaredType) {
+  if (typeof declaredType !== "string" || declaredType.length === 0) return void 0;
+  try {
+    const [registry, aliasMap] = await Promise.all([
+      TaskTypeRegistry.load({ cwd: rootDir }),
+      TaskTypeAliasMap.load({ cwd: rootDir })
+    ]);
+    if (aliasMap.isEmpty()) return void 0;
+    const mappedId = aliasMap.resolve(declaredType);
+    if (typeof mappedId === "string" && mappedId.length > 0 && registry.get(mappedId)) {
+      return mappedId;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function emitBacklogManagerWarning(message, metadata) {
+  emitCustomWarning(
+    "WARN" /* WARN */,
+    "configuration" /* CONFIGURATION */,
+    message,
+    {
+      subsystem: "planning/backlog-manager",
+      executionPhase: "execution"
+    },
+    { metadata, skipConsole: true }
+  );
+}
+async function tryLoadPackageJsonScripts(repoRoot) {
+  try {
+    const raw = await fs.readFile(path.join(repoRoot, "package.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    const scripts = parsed.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {};
+    return new Set(Object.keys(scripts));
+  } catch {
+    return void 0;
+  }
+}
+function buildScaffoldingFromEnhancements(enhancements) {
+  if (enhancements.length === 0) return "";
+  const hasScope = enhancements.some((e) => e.kind === "scope");
+  const hasAcceptance = enhancements.some((e) => e.kind === "acceptance");
+  const hasTesting = enhancements.some((e) => e.kind === "testing");
+  const hasReproducibility = enhancements.some((e) => e.kind === "reproducibility");
+  const hasResearch = enhancements.some((e) => e.kind === "research");
+  const hasAdr = enhancements.some((e) => e.kind === "adr");
+  const sections = [];
+  if (hasAdr) {
+    sections.push(`## Context
+
+<<<FILL: What is the background? What problem are we solving?>>>
+Example: The current caching strategy causes stale data issues during deployments.
+
+## Decision
+
+<<<FILL: What did we decide?>>>
+Example: Use cache invalidation via Redis pub/sub on deploy events.
+
+## Alternatives Considered
+
+<<<FILL: What other options were evaluated?>>>
+Example:
+- Time-based TTL (rejected: unpredictable staleness)
+- Manual cache clear (rejected: error-prone)
+
+## Consequences
+
+<<<FILL: What are the implications of this decision?>>>
+Example:
+- (+) Fresh data immediately after deploys
+- (-) Added Redis dependency`);
+    return sections.join("\n\n");
+  }
+  if (hasResearch) {
+    sections.push(`## Research Questions
+
+- <<<FILL: Primary question to answer>>>
+- <<<FILL: Secondary question>>>
+Example:
+- Which caching libraries fit the project's language and runtime?
+- What are the performance trade-offs?
+
+## Deliverable
+
+<<<FILL: What must the result help its reader understand, compare, or decide? Name any required evidence or constraints; prescribe a format only when the format itself is required.>>>
+Example: A document that answers the research questions, shows the evidence and the
+remaining uncertainty, and states what it means for the intended use or decision.`);
+    return sections.join("\n\n");
+  }
+  if (hasReproducibility) {
+    sections.push(`## Reproduction Steps
+
+1. <<<FILL: First step>>>
+2. <<<FILL: Next step>>>
+Example:
+1. Open the settings page and save the form
+2. Reload the page
+
+**Expected:** <<<FILL: What should happen>>>
+Example: The saved values are shown
+
+**Actual:** <<<FILL: What actually happens>>>
+Example: An error appears and the values are lost`);
+  }
+  if (hasScope) {
+    sections.push(`## Scope / Surfaces Affected
+
+Describe what areas of the codebase are involved:
+<<<FILL: e.g., "settings page", "export service", "storage layer" >>>`);
+  }
+  sections.push(`## Non-goals
+
+- <<<FILL: What is explicitly out of scope?>>>
+Example:
+- Not changing the database schema
+- Not adding new CLI flags`);
+  if (hasAcceptance) {
+    sections.push(`## Acceptance Criteria
+
+- [ ] <<<FILL: Specific criterion 1>>>
+- [ ] <<<FILL: Specific criterion 2>>>
+- [ ] Tests pass
+- [ ] No regressions
+Example:
+- [ ] Command outputs JSON when --json flag is passed
+- [ ] Error message shown when item not found`);
+  }
+  if (hasTesting) {
+    sections.push(`## How to Verify
+
+\`\`\`bash
+<<<FILL: Exact command to verify this works>>>
+\`\`\`
+Replace the placeholder with the test or check command this project uses.`);
+  }
+  return sections.join("\n\n");
+}
+function buildSpawnedFollowupVerifySection(repoRoot) {
+  let testCommand;
+  try {
+    testCommand = detectProjectCapabilities(repoRoot).verification.test[0];
+  } catch {
+    testCommand = void 0;
+  }
+  if (testCommand) {
+    return `## How to Verify
+
+\`\`\`bash
+${testCommand}
+\`\`\``;
+  }
+  return "## How to Verify\n\nRun the project's test suite.";
+}
+function buildSpawnedFollowupBody(parentTitle, parentBody, repoRoot) {
+  const filePaths = extractFileHintPaths(parentBody, 3);
+  const sections = [];
+  sections.push(
+    `Spawned follow-up from: ${parentTitle}
+
+> This spec needs refinement. Run \`build plan backlog refine <id>\` to add detail before executing.`
+  );
+  if (filePaths.length > 0) {
+    const fileLines = filePaths.map((f) => `- FILE: ${f}`).join("\n");
+    sections.push(`## Files to Modify
+
+${fileLines}`);
+  }
+  sections.push(
+    "## Acceptance Criteria\n\n- [ ] Implement changes as described in the title\n- [ ] Tests pass\n- [ ] No regressions"
+  );
+  sections.push(buildSpawnedFollowupVerifySection(repoRoot));
+  return sections.join("\n\n");
+}
+function mergeUniqueNumbers(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const value of values) {
+    if (typeof value !== "number" || Number.isNaN(value)) continue;
+    if (!seen.has(value)) {
+      seen.add(value);
+      merged.push(value);
+    }
+  }
+  return merged;
+}
+function mergeUniqueStrings(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const value of values) {
+    if (typeof value !== "string" || value.trim().length === 0) continue;
+    if (!seen.has(value)) {
+      seen.add(value);
+      merged.push(value);
+    }
+  }
+  return merged;
+}
+async function createBacklogItem(backlogDir, title, options = {}) {
+  const rootDir = resolvePlanningContext(backlogDir).projectRoot;
+  return withIndexRegeneration(rootDir, async () => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const initialBody = options.body?.trim();
+    let effectiveDescription;
+    let effectiveEnhancements;
+    let effectiveEnhancementSet;
+    let effectiveHints;
+    let guidance;
+    if (initialBody) {
+      guidance = generateEnhancements({ title, description: initialBody, itemKind: "backlog" });
+      effectiveDescription = initialBody;
+      effectiveEnhancements = toPersistedFormat(guidance.enhancements);
+      effectiveEnhancementSet = toEnhancementSet(guidance);
+      effectiveHints = hintsFromEnhancements(guidance.enhancements);
+    } else {
+      const baseDescription = options.description?.trim() || "(Add description here)";
+      guidance = generateEnhancements({ title, description: baseDescription, itemKind: "backlog" });
+      const scaffolding = buildScaffoldingFromEnhancements(guidance.enhancements);
+      effectiveDescription = scaffolding ? `${baseDescription}
+
+${scaffolding}` : baseDescription;
+      effectiveEnhancements = toPersistedFormat(guidance.enhancements);
+      effectiveEnhancementSet = toEnhancementSet(guidance);
+      effectiveHints = hintsFromEnhancements(guidance.enhancements);
+    }
+    const status = options.status || "inbox";
+    const priority = options.priority === void 0 ? null : options.priority;
+    const declaredTypeRaw = options.workType ?? options.type;
+    const declaredType = typeof declaredTypeRaw === "string" && declaredTypeRaw.trim().length > 0 ? declaredTypeRaw : void 0;
+    const declaredMethodology = typeof options.declaredMethodology === "string" && options.declaredMethodology.trim().length > 0 ? options.declaredMethodology : void 0;
+    const domain = declaredType ?? options.domain ?? "general";
+    const resolvedTaskTypeId = await resolveDeclaredTypeAtCreation(rootDir, declaredType);
+    const boundType = boundTypeFromIntent(guidance.intent);
+    const boundAt = now;
+    const result = await createWorkItemFile({
+      repoRoot: rootDir,
+      bucket: "backlog",
+      title,
+      description: effectiveDescription,
+      metadata: {
+        submittedDate: now,
+        submittedBy: options.submittedBy || "User",
+        status,
+        priority,
+        estimatedComplexity: options.complexity ?? 0.5,
+        // AI runtime estimate is optional and never defaulted (absence is honest).
+        ...typeof options.expectedRuntimeMinutes === "number" && options.expectedRuntimeMinutes > 0 ? { expectedRuntimeMinutes: options.expectedRuntimeMinutes } : {},
+        domain,
+        rationale: "",
+        relatedTasks: [],
+        createdHeadSha: options.createdHeadSha,
+        // Persist the enhancementSet (carrying intent) ALWAYS, even when zero
+        // enhancements were generated, so binding intent is never silently lost
+        // for very complete specs (fixes the prior omission).
+        enhancementSet: effectiveEnhancementSet,
+        ...effectiveEnhancements.length > 0 ? { enhancements: effectiveEnhancements } : {},
+        // Explicit top-level binding, set once at creation.
+        ...boundType ? { boundType, boundAt } : {},
+        // Declared terminology (verbatim, opaque) + its resolved canonical id.
+        ...declaredType ? { declaredType } : {},
+        ...declaredMethodology ? { declaredMethodology } : {},
+        ...resolvedTaskTypeId ? { resolvedTaskTypeId } : {},
+        ...effectiveHints.length > 0 ? { hints: effectiveHints } : {},
+        ...options.tags && options.tags.length > 0 ? { tags: options.tags } : {}
+      }
+    });
+    guidance.nextCommands = guidance.nextCommands.map((cmd) => cmd.replace("<item-id>", result.id));
+    const baseCompleteness = validateTaskSpec(effectiveDescription, guidance.enhancements);
+    const packageJsonScripts = await tryLoadPackageJsonScripts(rootDir);
+    const qualitySignals = generateSpecQualitySignals(
+      effectiveDescription,
+      rootDir,
+      packageJsonScripts
+    );
+    const completeness = qualitySignals.length > 0 ? { ...baseCompleteness, qualitySignals } : baseCompleteness;
+    const itemStatus = completeness.complete ? "created" : "draft";
+    const guidanceTier = calculateGuidanceTier(completeness);
+    const promptInjection = generatePromptInjection(completeness, guidanceTier);
+    return {
+      id: result.id,
+      filePath: result.path,
+      guidance,
+      completeness,
+      status: itemStatus,
+      guidanceTier,
+      encouragementLevel: guidanceTier,
+      // Backwards compat alias
+      promptInjection,
+      ...declaredType ? { declaredType } : {},
+      ...resolvedTaskTypeId ? { resolvedTaskTypeId } : {},
+      ...effectiveHints.length > 0 ? { hints: effectiveHints } : {}
+    };
+  });
+}
+async function moveToReviewed(backlogDir, itemId, options = {}) {
+  const rootDir = resolvePlanningContext(backlogDir).projectRoot;
+  return withIndexRegeneration(rootDir, async () => {
+    const item = await findBacklogItem(backlogDir, itemId);
+    if (!item) {
+      throw new Error(`Backlog item not found: ${itemId}`);
+    }
+    if (item.filePath !== path.join(backlogDir, `${itemId}.md`)) {
+      throw new Error(`Cannot review archived backlog item: ${itemId}`);
+    }
+    if (item.yaml.status && item.yaml.status !== "inbox" && item.yaml.status !== "reviewed") {
+      throw new Error(`Cannot review backlog item from status "${item.yaml.status}": ${itemId}`);
+    }
+    const { yaml: yamlData, body } = await parseMarkdownFile(item.filePath);
+    yamlData.status = "reviewed";
+    yamlData.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (options.reviewedAt) {
+      yamlData.reviewedAt = options.reviewedAt;
+    }
+    if (options.reviewedHeadSha) {
+      yamlData.reviewedHeadSha = options.reviewedHeadSha;
+    }
+    if (options.reviewedFiles && options.reviewedFiles.length > 0) {
+      yamlData.reviewedFiles = options.reviewedFiles;
+    }
+    await writeMarkdownFile(item.filePath, yamlData, body);
+    return { filePath: item.filePath, reviewedHeadSha: yamlData.reviewedHeadSha };
+  });
+}
+function hasExistingSpecMetadata(yamlData) {
+  return Array.isArray(yamlData.enhancements) || Boolean(yamlData.enhancementSet) || Array.isArray(yamlData.hints);
+}
+function existingBoundEnhancements(yamlData) {
+  const setEnhancements = yamlData.enhancementSet?.enhancements;
+  if (Array.isArray(setEnhancements) && setEnhancements.some(isBoundEnhancementKind)) {
+    return setEnhancements;
+  }
+  if (Array.isArray(yamlData.enhancements) && yamlData.enhancements.some(isBoundEnhancementKind)) {
+    return yamlData.enhancements;
+  }
+  return void 0;
+}
+function isBoundEnhancementKind(e) {
+  return e.kind === "adr" || e.kind === "research" || e.kind === "reproducibility";
+}
+function enhancementKindForBoundType(bound) {
+  return bound === "bug" ? "reproducibility" : bound;
+}
+function activityForBoundType(bound) {
+  switch (bound) {
+    case "bug":
+      return "debugging";
+    case "adr":
+      return "architecture";
+    case "research":
+      return "research";
+    default:
+      return "development";
+  }
+}
+function bindingAlignedGuidance(guidance, rebound) {
+  const targetKind = rebound === void 0 ? void 0 : enhancementKindForBoundType(rebound);
+  const enhancements = guidance.enhancements.filter(
+    (e) => !isBoundEnhancementKind(e) || e.kind === targetKind
+  );
+  return {
+    ...guidance,
+    enhancements,
+    intent: { ...guidance.intent, activity: activityForBoundType(rebound) }
+  };
+}
+function syncSpecMetadataFromBody(yamlData, body, options) {
+  if (options.explicitBoundType !== void 0) {
+    const rebound = options.explicitBoundType === "dev" ? void 0 : options.explicitBoundType;
+    const rawGuidance = generateEnhancements({
+      title: yamlData.title,
+      description: body,
+      itemKind: "backlog"
+    });
+    const rebindGuidance = bindingAlignedGuidance(rawGuidance, rebound);
+    const rebindSet = toEnhancementSet(rebindGuidance);
+    return {
+      enhancements: toPersistedFormat(rebindGuidance.enhancements),
+      enhancementSet: rebindSet,
+      hints: hintsFromEnhancements(rebindGuidance.enhancements),
+      boundType: rebound,
+      boundAt: rebound === void 0 ? void 0 : (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  if (options.mode === "preserve" && hasExistingSpecMetadata(yamlData)) {
+    return {
+      enhancements: yamlData.enhancements,
+      enhancementSet: yamlData.enhancementSet,
+      hints: yamlData.hints,
+      boundType: yamlData.boundType,
+      boundAt: yamlData.boundAt
+    };
+  }
+  const guidance = generateEnhancements({
+    title: yamlData.title,
+    description: body,
+    itemKind: "backlog"
+  });
+  const regeneratedEnhancements = toPersistedFormat(guidance.enhancements);
+  const regeneratedSet = toEnhancementSet(guidance);
+  const regeneratedHints = hintsFromEnhancements(guidance.enhancements);
+  const existingBoundType = getBoundType(yamlData);
+  if (options.mode === "regenerate" && existingBoundType !== void 0) {
+    const existingSet = yamlData.enhancementSet;
+    const boundEnhancements = existingBoundEnhancements(yamlData);
+    const enhancements = boundEnhancements ?? yamlData.enhancements;
+    const mergedSet = {
+      ...regeneratedSet,
+      // Bound intent is part of the bound type; the existing bound intent wins.
+      // Fall back to the regenerated intent only when no intent was stored.
+      intent: existingSet?.intent ?? regeneratedSet.intent,
+      // Pin the bound enhancement kinds to the existing (authoritative) set when present.
+      ...boundEnhancements ? { enhancements: boundEnhancements } : {}
+    };
+    if (existingSet?.acceptanceCriteria !== void 0) {
+      mergedSet.acceptanceCriteria = existingSet.acceptanceCriteria;
+    }
+    if (existingSet?.constraints !== void 0) {
+      mergedSet.constraints = existingSet.constraints;
+    }
+    if (existingSet?.artifactSources !== void 0) {
+      mergedSet.artifactSources = existingSet.artifactSources;
+    }
+    return {
+      enhancements,
+      // Hints describe the bound enhancement kinds; keep stored hints when present
+      // (they match the preserved bound type), else derive from the bound kinds.
+      enhancementSet: mergedSet,
+      hints: yamlData.hints ?? (enhancements ? hintsFromEnhancements(fromPersistedFormat(enhancements)) : regeneratedHints),
+      // Bound binding survives verbatim. Backfill boundType/boundAt for legacy
+      // bound items that predate the explicit fields, so the persisted authority
+      // becomes self-describing after this mutation (mutating path, not read).
+      boundType: yamlData.boundType ?? existingBoundType,
+      boundAt: yamlData.boundAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  const regeneratedBoundType = boundTypeFromIntent(regeneratedSet.intent);
+  return {
+    enhancements: regeneratedEnhancements,
+    enhancementSet: regeneratedSet,
+    hints: regeneratedHints,
+    ...regeneratedBoundType ? { boundType: regeneratedBoundType, boundAt: yamlData.boundAt ?? (/* @__PURE__ */ new Date()).toISOString() } : { boundType: void 0, boundAt: yamlData.boundAt }
+  };
+}
+function resolvePlanningRootFromBacklogFile(filePath) {
+  return resolvePlanningContext(path.dirname(filePath)).projectRoot;
+}
+async function updateBacklogItem(filePath, updates, bodyOverride, options = {}) {
+  const rootDir = resolvePlanningRootFromBacklogFile(filePath);
+  await withIndexRegeneration(rootDir, async () => {
+    const { yaml: yamlData, body } = await parseMarkdownFile(filePath);
+    if (options.expectedBody !== void 0 && body !== options.expectedBody) {
+      throw new Error(`Backlog item ${yamlData.id} changed since it was read; nothing saved.`);
+    }
+    const effectiveUpdates = options.resolveUpdatesFromLockedItem ? { ...updates, ...await options.resolveUpdatesFromLockedItem(yamlData) } : updates;
+    const mergeArrayField = (key, target) => {
+      const next = effectiveUpdates[key];
+      const current = yamlData[key];
+      if (!Array.isArray(next) || !Array.isArray(current)) return;
+      if (next.length === 0) {
+        target[key] = current;
+        return;
+      }
+      target[key] = Array.from(/* @__PURE__ */ new Set([...current, ...next]));
+    };
+    const updated = {
+      ...yamlData,
+      ...effectiveUpdates,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    mergeArrayField("linkedPrs", updated);
+    if (!options.replaceTags) {
+      mergeArrayField("tags", updated);
+    }
+    mergeArrayField("linkedCommits", updated);
+    mergeArrayField("followups", updated);
+    const explicitBoundType = "boundType" in effectiveUpdates ? effectiveUpdates.boundType === void 0 ? "dev" : effectiveUpdates.boundType : void 0;
+    const hasBodyOverride = typeof bodyOverride === "string";
+    const nextBody = keepActivity(`Backlog item ${yamlData.id}`, body, bodyOverride ?? body);
+    const needsMetadataSync = hasBodyOverride || "title" in effectiveUpdates || "domain" in effectiveUpdates || explicitBoundType !== void 0;
+    if (needsMetadataSync) {
+      Object.assign(
+        updated,
+        syncSpecMetadataFromBody(updated, nextBody, {
+          mode: hasBodyOverride ? "regenerate" : "preserve",
+          explicitBoundType
+        })
+      );
+    }
+    const validation = validateBacklogItem(updated);
+    if (!validation.valid) {
+      throw new Error(
+        `Backlog validation failed: ${validation.errors.map((error) => `${error.field}: ${error.message}`).join(", ")}`
+      );
+    }
+    await writeMarkdownFile(filePath, updated, nextBody);
+  });
+}
+async function listBacklogItems(dir, status, filters, options) {
+  try {
+    const isArchiveDir = options?.archiveRoot === true || dir.replace(/\\/g, "/").endsWith("/archive");
+    const items = [];
+    const files = isArchiveDir ? await listMarkdownFilesRecursive(dir) : await listMarkdownFiles(dir);
+    for (const filePath of files) {
+      let yamlData;
+      let body;
+      try {
+        ({ yaml: yamlData, body } = await parseMarkdownFile(filePath));
+      } catch (parseError) {
+        const reason = parseError instanceof Error ? parseError.message : String(parseError);
+        emitBacklogManagerWarning(
+          `Skipping unparseable backlog file ${path.basename(filePath)}: ${reason}`,
+          {
+            filePath,
+            fileName: path.basename(filePath),
+            reason
+          }
+        );
+        continue;
+      }
+      const id = typeof yamlData.id === "string" && yamlData.id.length > 0 ? yamlData.id : path.basename(filePath).replace(/\.md$/, "");
+      const title = typeof yamlData.title === "string" ? yamlData.title : "(Untitled)";
+      const rawStatus = typeof yamlData.status === "string" ? yamlData.status : "inbox";
+      const normalizedStatus = rawStatus === "done" ? "archived" : rawStatus === "inbox" || rawStatus === "reviewed" || rawStatus === "archived" ? rawStatus : "inbox";
+      if (status && normalizedStatus !== status) continue;
+      const priority = typeof yamlData.priority === "string" ? yamlData.priority : null;
+      const complexity = typeof yamlData.estimatedComplexity === "number" ? yamlData.estimatedComplexity : typeof yamlData.estimated_complexity === "number" ? yamlData.estimated_complexity : null;
+      const domain = typeof yamlData.domain === "string" ? yamlData.domain : typeof yamlData.activity === "string" ? yamlData.activity : null;
+      const createdAt = typeof yamlData.createdAt === "string" ? yamlData.createdAt : null;
+      const updatedAt = typeof yamlData.updatedAt === "string" ? yamlData.updatedAt : null;
+      const createdHeadSha = typeof yamlData.createdHeadSha === "string" ? yamlData.createdHeadSha : null;
+      const reviewedAt = typeof yamlData.reviewedAt === "string" ? yamlData.reviewedAt : null;
+      const reviewedHeadSha = typeof yamlData.reviewedHeadSha === "string" ? yamlData.reviewedHeadSha : null;
+      const reviewedFiles = Array.isArray(yamlData.reviewedFiles) && yamlData.reviewedFiles.every((f) => typeof f === "string") ? yamlData.reviewedFiles : null;
+      const archivedReason = typeof yamlData.archivedReason === "string" ? yamlData.archivedReason : null;
+      const rawLinkedPrs = Array.isArray(yamlData.linkedPrs) ? yamlData.linkedPrs : null;
+      const linkedPrs = rawLinkedPrs && rawLinkedPrs.length > 0 ? mergeUniqueNumbers(
+        rawLinkedPrs.map(
+          (value) => typeof value === "string" ? Number.parseInt(value, 10) : value
+        )
+      ) : null;
+      const rawLinkedCommits = Array.isArray(yamlData.linkedCommits) ? yamlData.linkedCommits : null;
+      const linkedCommits = rawLinkedCommits && rawLinkedCommits.length > 0 ? mergeUniqueStrings(rawLinkedCommits) : null;
+      const spawnedFrom = typeof yamlData.spawnedFrom === "string" ? yamlData.spawnedFrom : null;
+      const followups = Array.isArray(yamlData.followups) && yamlData.followups.every((f) => typeof f === "string") ? yamlData.followups : null;
+      const declaredType = typeof yamlData.declaredType === "string" ? yamlData.declaredType : null;
+      const resolvedTaskTypeId = typeof yamlData.resolvedTaskTypeId === "string" ? yamlData.resolvedTaskTypeId : null;
+      if (filters?.linkedPr !== void 0) {
+        if (!linkedPrs || !linkedPrs.includes(filters.linkedPr)) continue;
+      }
+      if (filters?.linkedCommit) {
+        if (!linkedCommits || !linkedCommits.includes(filters.linkedCommit)) continue;
+      }
+      if (filters?.spawnedFrom) {
+        if (spawnedFrom !== filters.spawnedFrom) continue;
+      }
+      if (filters?.hasFollowups) {
+        if (!followups || followups.length === 0) continue;
+      }
+      items.push({
+        id,
+        title,
+        complexity,
+        domain,
+        priority,
+        status: normalizedStatus,
+        createdAt,
+        updatedAt,
+        createdHeadSha,
+        reviewedAt,
+        reviewedHeadSha,
+        reviewedFiles,
+        archivedReason,
+        linkedPrs,
+        linkedCommits,
+        spawnedFrom,
+        followups,
+        needsRefinement: hasUnfilledMarkers(body),
+        declaredType,
+        resolvedTaskTypeId
+      });
+    }
+    return items;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+function applyBacklogListFilters(items, filters) {
+  if (!filters) return items;
+  return items.filter((item) => {
+    if (filters.linkedPr !== void 0) {
+      if (!item.linkedPrs || !item.linkedPrs.includes(filters.linkedPr)) return false;
+    }
+    if (filters.linkedCommit) {
+      if (!item.linkedCommits || !item.linkedCommits.includes(filters.linkedCommit)) return false;
+    }
+    if (filters.spawnedFrom) {
+      if (item.spawnedFrom !== filters.spawnedFrom) return false;
+    }
+    if (filters.hasFollowups) {
+      if (!item.followups || item.followups.length === 0) return false;
+    }
+    return true;
+  });
+}
+async function queryArchivedMerged(backlogDir, filters) {
+  const archiveDir = resolveBucketArchiveRoot("backlog", backlogDir);
+  const [liveItems, archivedItems] = await Promise.all([
+    listBacklogItems(backlogDir, "archived"),
+    listBacklogItems(archiveDir, "archived", void 0, { archiveRoot: true }).catch(() => [])
+  ]);
+  const seen = new Set(archivedItems.map((i) => i.id));
+  const merged = [...archivedItems, ...liveItems.filter((i) => !seen.has(i.id))];
+  return applyBacklogListFilters(merged, filters);
+}
+async function queryBacklogList(backlogDir, status, filters) {
+  if (status !== "archived") {
+    return listBacklogItems(backlogDir, status, filters);
+  }
+  return queryArchivedMerged(backlogDir, filters);
+}
+async function queryBacklogListScoped(backlogDir, scope, filters) {
+  const [inbox, reviewed, archived] = await Promise.all([
+    listBacklogItems(backlogDir, "inbox", filters),
+    listBacklogItems(backlogDir, "reviewed", filters),
+    queryArchivedMerged(backlogDir, filters)
+  ]);
+  const active = [...inbox, ...reviewed];
+  const items = scope === "with-archived" ? [...active, ...archived] : active;
+  return { items, archivedCount: archived.length };
+}
+async function archiveBacklogItem(backlogBaseDir, itemId, options = {}) {
+  const rootDir = resolvePlanningContext(backlogBaseDir).projectRoot;
+  return withIndexRegeneration(rootDir, async () => {
+    const item = await findBacklogItem(backlogBaseDir, itemId);
+    if (!item) {
+      throw new Error(`Backlog item not found: ${itemId}`);
+    }
+    if (isInArchive(resolveBucketArchiveRoot("backlog", backlogBaseDir), item.filePath)) {
+      return { id: itemId, archivedPath: item.filePath };
+    }
+    const { yaml: yamlData, body } = await parseMarkdownFile(item.filePath);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const followupIds = [];
+    const spawnTitles = options.spawnFollowups?.filter((title) => title.trim().length > 0) || [];
+    if (spawnTitles.length > 0) {
+      for (const followupTitle of spawnTitles) {
+        const followupBody = buildSpawnedFollowupBody(yamlData.title, body, rootDir);
+        const followup = await createBacklogItem(backlogBaseDir, followupTitle, {
+          domain: yamlData.domain,
+          complexity: yamlData.estimatedComplexity,
+          submittedBy: yamlData.submittedBy,
+          body: followupBody
+        });
+        followupIds.push(followup.id);
+        await updateBacklogItem(followup.filePath, {
+          spawnedFrom: itemId,
+          ...yamlData.priority ? { priority: yamlData.priority } : {}
+        });
+      }
+    }
+    const updated = {
+      ...yamlData,
+      status: "archived",
+      updatedAt: now,
+      archivedAt: now,
+      restoredStatus: yamlData.status === "inbox" || yamlData.status === "reviewed" ? yamlData.status : void 0,
+      ...options.reason ? { archivedReason: options.reason } : {},
+      ...followupIds.length > 0 ? {
+        followups: mergeUniqueStrings([
+          ...Array.isArray(yamlData.followups) ? yamlData.followups : [],
+          ...followupIds
+        ])
+      } : {}
+    };
+    const bucketConfig = getBucketByName("backlog", rootDir);
+    if (!bucketConfig) {
+      throw new Error("Bucket not configured: backlog");
+    }
+    const archivedPath = getArchivedFilePath(bucketConfig, itemId, now, rootDir);
+    await fs.mkdir(path.dirname(archivedPath), { recursive: true });
+    await writeMarkdownFile(archivedPath, updated, body);
+    await fs.unlink(item.filePath);
+    await appendActivity(archivedPath, {
+      timestamp: now,
+      type: "completed",
+      description: `Archived (reason: ${options.reason ?? "Not specified"}, by: ${options.actor ?? "unknown"})`
+    });
+    return followupIds.length > 0 ? { id: itemId, archivedPath, followupIds } : { id: itemId, archivedPath };
+  });
+}
+async function findBacklogItem(backlogBaseDir, itemId) {
+  const currentPath = path.join(backlogBaseDir, `${itemId}.md`);
+  try {
+    const { yaml: yamlData2, body: body2 } = await parseMarkdownFile(currentPath);
+    if (yamlData2.id === itemId) return { filePath: currentPath, yaml: yamlData2, body: body2 };
+  } catch {
+  }
+  const archiveRoot = resolveBucketArchiveRoot("backlog", backlogBaseDir);
+  const archivedFiles = await listMarkdownFilesRecursive(archiveRoot);
+  const match = archivedFiles.find((f) => path.basename(f) === `${itemId}.md`);
+  if (!match) return null;
+  const { yaml: yamlData, body } = await parseMarkdownFile(match);
+  if (yamlData.id === itemId) return { filePath: match, yaml: yamlData, body };
+  return null;
+}
+async function linkBacklogItem(backlogBaseDir, itemId, options) {
+  const rootDir = resolvePlanningContext(backlogBaseDir).projectRoot;
+  if (!options.pr && !options.commit) {
+    throw new Error("At least one link (--pr or --commit) is required");
+  }
+  return withIndexRegeneration(rootDir, async () => {
+    const item = await findBacklogItem(backlogBaseDir, itemId);
+    if (!item) {
+      throw new Error(`Backlog item not found: ${itemId}`);
+    }
+    const existingLinkedPrs = Array.isArray(item.yaml.linkedPrs) ? mergeUniqueNumbers(
+      item.yaml.linkedPrs.map(
+        (value) => typeof value === "string" ? Number.parseInt(value, 10) : value
+      )
+    ) : [];
+    const existingLinkedCommits = Array.isArray(item.yaml.linkedCommits) && item.yaml.linkedCommits.every((value) => typeof value === "string") ? item.yaml.linkedCommits : [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const updated = {
+      ...item.yaml,
+      updatedAt: now
+    };
+    if (options.pr !== void 0) {
+      updated.linkedPrs = mergeUniqueNumbers([...existingLinkedPrs, options.pr]);
+    }
+    if (options.commit) {
+      updated.linkedCommits = mergeUniqueStrings([...existingLinkedCommits, options.commit]);
+    }
+    await writeMarkdownFile(item.filePath, updated, item.body);
+    const linkParts = [];
+    if (options.pr !== void 0) {
+      linkParts.push(`PR #${options.pr}`);
+    }
+    if (options.commit) {
+      linkParts.push(`commit ${options.commit}`);
+    }
+    const description = `Linked to ${linkParts.join(" and ")} (by: ${options.actor ?? "unknown"})`;
+    await appendActivity(item.filePath, {
+      timestamp: now,
+      type: "progress",
+      description,
+      metadata: options.pr !== void 0 ? { prNumber: options.pr } : void 0
+    });
+    return {
+      filePath: item.filePath,
+      linkedPrs: updated.linkedPrs ?? [],
+      linkedCommits: updated.linkedCommits ?? []
+    };
+  });
+}
+
+export {
+  validateBacklogItem,
+  validateDebtItem,
+  validateParkingItem,
+  validateSprintItem,
+  validateTaskItem,
+  createBacklogItem,
+  moveToReviewed,
+  updateBacklogItem,
+  listBacklogItems,
+  queryBacklogList,
+  queryBacklogListScoped,
+  archiveBacklogItem,
+  findBacklogItem,
+  linkBacklogItem
+};
+//# sourceMappingURL=chunk-NKLPMBNV.js.map