@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/dist/chunk-MTU7VTNN.js

@@ -0,0 +1,1122 @@
+import {
+  errorEvent,
+  infoEvent
+} from "./chunk-GQXLXRFA.js";
+import {
+  collectTrailerItemIds,
+  fetchGitHubPrView
+} from "./chunk-AJJNW7XT.js";
+import {
+  createCliOutputRenderer
+} from "./chunk-3UBZI5DW.js";
+import {
+  TRACKED_EXECUTE_NOTE
+} from "./chunk-UVKWU3SM.js";
+import {
+  emitPlanningStateWarning
+} from "./chunk-RQFX6YRN.js";
+import {
+  listTasksInSprint
+} from "./chunk-L2CBG5IX.js";
+import {
+  parseKindOption,
+  queryNextItems
+} from "./chunk-S6TAFQI5.js";
+import {
+  queryBacklogList
+} from "./chunk-NKLPMBNV.js";
+import {
+  backlogExecutionStatusCarriesDelivery,
+  evaluateAutoFinalizeEligibility,
+  isBacklogExecutionProvenanceActivelyExecuting,
+  listBacklogExecutionProvenanceByStatus,
+  loadBacklogExecutionProvenance,
+  updateBacklogExecutionProvenance
+} from "./chunk-3WY5TU2O.js";
+import {
+  ExitCodeError
+} from "./chunk-Y4ZDDHB6.js";
+import {
+  getPlanningRoot
+} from "./chunk-CSXLLEGB.js";
+import {
+  checkSharedBucketReadability
+} from "./chunk-AJBTKGJZ.js";
+import {
+  getBucketPathByKind
+} from "./chunk-V3KLVK7B.js";
+import {
+  loadManifest
+} from "./chunk-6TRD7TEE.js";
+import {
+  resolvePlanningContextForRoot
+} from "./chunk-BBPIILO2.js";
+import {
+  detectRemoteConfiguration
+} from "./chunk-EPRMH6HO.js";
+import {
+  classifyBranchRole,
+  isDisposableBranchRole,
+  resolveManagedSyncDefaultBranch
+} from "./chunk-XGU6PBO5.js";
+import {
+  execGit
+} from "./chunk-MHLEZQQI.js";
+import {
+  PLANNING_GIT_NETWORK_TIMEOUT_MS
+} from "./chunk-I56TH7VM.js";
+import {
+  resolveCliRepoRoot
+} from "./chunk-7VRJHTGZ.js";
+
+// src/cli/commands/next.ts
+import * as fs from "fs/promises";
+import * as path2 from "path";
+import { Command } from "commander";
+
+// src/planning/backlog-delivery-evidence.ts
+import { execa } from "execa";
+async function refreshBacklogFinalizationTarget(root) {
+  try {
+    const branch = await resolveManagedSyncDefaultBranch(root);
+    if (!branch) return void 0;
+    const fetched = await execGit(["fetch", "origin", branch], {
+      cwd: root,
+      timeoutMs: PLANNING_GIT_NETWORK_TIMEOUT_MS
+    });
+    return fetched.exitCode === 0 ? `origin/${branch}` : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function inspectBacklogDeliveryEvidence(root, record, options = {}) {
+  const unknown = (reason) => ({ state: "unknown", reason });
+  const contradicted = (reason) => ({
+    state: "contradicted",
+    reason
+  });
+  try {
+    if (record.status === "archived") {
+      const archived = await queryBacklogList(getBucketPathByKind("backlog", root), "archived");
+      return archived.some((item) => item.id === record.backlogItemId) ? { state: "confirmed", reason: "The item has an archive record." } : unknown("The recorded archive is unavailable in this checkout.");
+    }
+    if (record.status === "delivered-local") {
+      return unknown("This local-delivery receipt contains no applied commit or target witness.");
+    }
+    if (record.prNumber === null || !options.queryPr) {
+      return unknown("Current PR evidence is unavailable; the recorded delivery is preserved.");
+    }
+    const pr = await fetchGitHubPrView(execa, root, record.prNumber);
+    const merged = pr.state === "MERGED" || Boolean(pr.mergedAt);
+    if (pr.state === "CLOSED" && !merged) {
+      return contradicted(`PR #${record.prNumber} is closed without merging.`);
+    }
+    if (pr.state === "OPEN" && record.status === "pr-open") {
+      return { state: "confirmed", reason: `PR #${record.prNumber} is open.` };
+    }
+    if (!merged) return unknown("The PR does not establish the recorded merge.");
+    const commit = pr.mergeCommit?.oid;
+    if (!commit || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(commit)) {
+      return unknown("The merged PR has no usable merge commit evidence.");
+    }
+    if (record.mergeCommit) {
+      if (!/^[a-f0-9]{4,64}$/i.test(record.mergeCommit)) {
+        return unknown("The recorded merge commit is not an immutable commit identifier.");
+      }
+      const recorded = await execGit(
+        [
+          "rev-parse",
+          "--verify",
+          "--end-of-options",
+          `${record.mergeCommit.toLowerCase()}^{commit}`
+        ],
+        { cwd: root }
+      );
+      if (recorded.exitCode !== 0) return unknown("The recorded merge commit cannot be resolved.");
+      if (recorded.stdout.trim().toLowerCase() !== commit.toLowerCase()) {
+        return contradicted("The recorded merge commit differs from the PR merge commit.");
+      }
+    }
+    if (!options.remoteTarget) {
+      return unknown("The finalization target could not be refreshed.");
+    }
+    const valid = await execGit(["rev-parse", "--verify", `${commit}^{commit}`], { cwd: root });
+    if (valid.exitCode !== 0) return unknown("The PR merge commit is not available locally.");
+    const onTarget = await execGit(["merge-base", "--is-ancestor", commit, options.remoteTarget], {
+      cwd: root
+    });
+    if (onTarget.exitCode === 1) {
+      return contradicted("The PR merge commit is absent from the refreshed finalization target.");
+    }
+    if (onTarget.exitCode !== 0) return unknown("The finalization target could not be inspected.");
+    const eligibility = evaluateAutoFinalizeEligibility({ ...record, status: "pr-open" }, commit, {
+      validCommit: true,
+      mergeCommitOnRemoteDefault: true,
+      prMerged: true,
+      mergeCommitMatchesPr: true,
+      backlogItemMatchesPr: collectTrailerItemIds(pr.commits ?? []).declared.includes(
+        record.backlogItemId
+      )
+    });
+    return eligibility.eligible ? {
+      state: "confirmed",
+      reason: `PR #${record.prNumber} is merged on the finalization target.`,
+      readyMergeCommit: eligibility.mergeCommit
+    } : unknown(eligibility.reason);
+  } catch {
+    return unknown("Delivery evidence could not be read; the recorded delivery is preserved.");
+  }
+}
+
+// src/cli/commands/backlog-execution-state.ts
+import * as path from "path";
+function backlogExecutionBranchName(backlogItemId, sequence = 0) {
+  const suffix = sequence > 0 ? `-${sequence + 1}` : "";
+  return `run/backlog-${backlogItemId}${suffix}`;
+}
+function isBacklogExecutionBranchName(backlogItemId, branch) {
+  if (!backlogItemId || !branch) return false;
+  if (branch === backlogExecutionBranchName(backlogItemId, 0)) return true;
+  const prefix = `run/backlog-${backlogItemId}-`;
+  if (!branch.startsWith(prefix)) return false;
+  const rest = branch.slice(prefix.length);
+  return /^[1-9]\d*$/.test(rest) && Number(rest) >= 2;
+}
+function backlogSyncBranchName(backlogItemId) {
+  return `chore/backlog-sync-${backlogItemId}`;
+}
+function backlogExecuteSignalCleanupName(backlogItemId) {
+  return `BacklogExecute:${backlogItemId}:${process.pid}`;
+}
+function backlogFinalizeSignalCleanupName(backlogItemId) {
+  return `BacklogFinalize:${backlogItemId}:${process.pid}`;
+}
+function backlogExecuteTerminalStatusCopy(status, backlogItemId) {
+  if (status === "delivered-local") {
+    return {
+      statusText: `Backlog item ${backlogItemId} was delivered locally.`,
+      nextActionText: `  Complete or archive explicitly: build plan backlog archive ${backlogItemId} --reason <reason>`
+    };
+  }
+  return {
+    statusText: `Backlog item ${backlogItemId} is already merged.`,
+    nextActionText: "  Run `build plan backlog finalize <id> --pr <n> --commit <sha>` to archive it."
+  };
+}
+async function backlogExecuteReceiptCopy(root, record) {
+  const id = record.backlogItemId;
+  if (record.status === "delivered-local") {
+    return { ...backlogExecuteTerminalStatusCopy(record.status, id), confirmed: true };
+  }
+  if (record.status === "pr-open" && record.prNumber === null && hasReusableExecutionResult(record)) {
+    return null;
+  }
+  if (!["pr-open", "merged", "archived"].includes(record.status)) return null;
+  const remoteTarget = record.status === "archived" || record.prNumber === null ? void 0 : await refreshBacklogFinalizationTarget(root);
+  const evidence = await inspectBacklogDeliveryEvidence(root, record, {
+    remoteTarget,
+    queryPr: true
+  });
+  if (evidence.state !== "confirmed") {
+    return {
+      confirmed: false,
+      statusText: `Backlog item ${id} needs reconciliation: ${evidence.reason}`,
+      nextActionText: "  Recorded delivery is preserved; inspect before resetting execution."
+    };
+  }
+  if (record.status === "archived") {
+    return {
+      confirmed: true,
+      statusText: `Backlog item ${id} is already archived.`,
+      nextActionText: "  Archive evidence is present."
+    };
+  }
+  if (evidence.readyMergeCommit) {
+    return {
+      confirmed: true,
+      statusText: `Backlog item ${id} is already merged.`,
+      nextActionText: `  Finalize: build plan backlog finalize ${id} --pr ${record.prNumber} --commit ${evidence.readyMergeCommit}`
+    };
+  }
+  return {
+    confirmed: true,
+    statusText: `Backlog item ${id} already has an open PR.`,
+    nextActionText: `  Existing PR: #${record.prNumber}; finalize after merge.`
+  };
+}
+function finalizeFailureProvenanceUpdate(params) {
+  const base = {
+    prNumber: params.prNumber,
+    mergeCommit: params.mergeCommit,
+    archiveSyncPrNumber: params.archiveSyncPrNumber
+  };
+  if (params.archiveSyncPending) {
+    return {
+      ...base,
+      archiveSyncWarning: params.errorMessage,
+      status: "archive-sync-pending",
+      lastCompletedStep: "finalize",
+      failedAtStep: null,
+      errorMessage: null
+    };
+  }
+  if (backlogExecutionStatusCarriesDelivery(params.priorStatus)) {
+    return {
+      archiveSyncWarning: null,
+      // Status and delivery evidence are intentionally omitted: the stored
+      // record remains truthful when a retry supplies bad values.
+      failedAtStep: "finalize",
+      errorMessage: params.errorMessage
+    };
+  }
+  return {
+    ...base,
+    archiveSyncWarning: null,
+    status: "failed",
+    failedAtStep: "finalize",
+    errorMessage: params.errorMessage
+  };
+}
+function finalizeInterruptProvenanceUpdate(prNumber, mergeCommit, archiveSyncPrNumber, signal, priorStatus) {
+  return finalizeFailureProvenanceUpdate({
+    priorStatus: priorStatus ?? null,
+    prNumber,
+    mergeCommit,
+    archiveSyncPrNumber,
+    archiveSyncPending: archiveSyncPrNumber !== null,
+    errorMessage: `Interrupted by ${signal}`
+  });
+}
+function parsePrNumberFromUrl(prUrl) {
+  const match = prUrl.match(/\/pull\/(\d+)$/);
+  if (!match?.[1]) return null;
+  const parsed = Number.parseInt(match[1], 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function extractWorkflowIdFromOutput(output) {
+  const match = output.match(/(?:^|\n)\s*Workflow ID:\s*([^\s]+)/i);
+  if (match?.[1]?.trim()) {
+    return match[1].trim();
+  }
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed.workflowId === "string" && parsed.workflowId.trim().length > 0) {
+        return parsed.workflowId.trim();
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function tryParseJsonObjectAt(source, startIndex) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = startIndex; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === void 0) break;
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "{") {
+      depth += 1;
+      continue;
+    }
+    if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          return JSON.parse(source.slice(startIndex, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+function extractUnansweredMustHaveBlockerPayload(stderr) {
+  const marker = '{"error":"unanswered_must_have_blockers"';
+  const startIndex = stderr.lastIndexOf(marker);
+  if (startIndex < 0) return null;
+  const parsed = tryParseJsonObjectAt(stderr, startIndex);
+  if (!parsed || typeof parsed !== "object") return null;
+  const candidate = parsed;
+  if (candidate.error !== "unanswered_must_have_blockers" || !Array.isArray(candidate.blockers)) {
+    return null;
+  }
+  const blockers = candidate.blockers.filter((entry) => {
+    return !!entry && typeof entry === "object" && typeof entry.question === "string";
+  }).map((entry) => ({
+    ...typeof entry.id === "string" ? { id: entry.id } : {},
+    question: entry.question,
+    ...Array.isArray(entry.stageIds) ? {
+      stageIds: entry.stageIds.filter(
+        (stageId) => typeof stageId === "string"
+      )
+    } : {}
+  }));
+  if (blockers.length === 0) return null;
+  return { error: "unanswered_must_have_blockers", blockers };
+}
+function extractPlanExecuteFailurePayload(output) {
+  const marker = '{"error":"planned_build_failed"';
+  const startIndex = output.lastIndexOf(marker);
+  if (startIndex < 0) return null;
+  const parsed = tryParseJsonObjectAt(output, startIndex);
+  if (!parsed || typeof parsed !== "object") return null;
+  const candidate = parsed;
+  if (candidate.error !== "planned_build_failed") return null;
+  const errors = Array.isArray(candidate.errors) ? candidate.errors.filter((entry) => typeof entry === "string") : void 0;
+  return {
+    error: "planned_build_failed",
+    ...typeof candidate.message === "string" ? { message: candidate.message } : {},
+    ...errors && errors.length > 0 ? { errors } : {}
+  };
+}
+function extractTerminalResultFailureReason(output) {
+  const startIndex = output.lastIndexOf('{"kind":"result"');
+  if (startIndex < 0) return null;
+  const parsed = tryParseJsonObjectAt(output, startIndex);
+  const goalGap = parsed?.result?.finalOutcome?.goalGap;
+  if (!goalGap || goalGap.satisfied !== false || !Array.isArray(goalGap.gaps)) return null;
+  const gaps = goalGap.gaps.filter(
+    (gap) => typeof gap?.criterion === "string" && gap.criterion.trim().length > 0
+  );
+  const lead = gaps.find((gap) => gap.severity === "blocking" && gap.status !== "satisfied") ?? gaps[0];
+  return lead ? lead.criterion.trim() : null;
+}
+function extractPlanExecuteDecompositionFailurePayload(output) {
+  const marker = "BUILD_PLANNED_DECOMPOSITION_FAILURE ";
+  const markerIndex = output.lastIndexOf(marker);
+  if (markerIndex < 0) return null;
+  const parsed = tryParseJsonObjectAt(output, markerIndex + marker.length);
+  if (!parsed || typeof parsed !== "object") return null;
+  const candidate = parsed;
+  return {
+    ...typeof candidate.kind === "string" ? { kind: candidate.kind } : {},
+    ...typeof candidate.errorMessage === "string" ? { errorMessage: candidate.errorMessage } : {},
+    ...typeof candidate.failureKind === "string" ? { failureKind: candidate.failureKind } : {},
+    ...typeof candidate.timedOut === "boolean" ? { timedOut: candidate.timedOut } : {},
+    ...typeof candidate.idleTerminated === "boolean" ? { idleTerminated: candidate.idleTerminated } : {},
+    ...typeof candidate.workflowMaterialized === "boolean" ? { workflowMaterialized: candidate.workflowMaterialized } : {}
+  };
+}
+function extractLastNonEmptyStderrLine(stderr) {
+  const lines = stderr.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  const last = lines.at(-1) ?? null;
+  if (!last?.startsWith("{")) return last;
+  const marker = '{"error":"';
+  let structured = null;
+  for (let at = last.indexOf(marker); at >= 0; at = last.indexOf(marker, at + 1)) {
+    const parsed = tryParseJsonObjectAt(last, at);
+    if (typeof parsed?.error !== "string") continue;
+    structured = typeof parsed.message === "string" && parsed.message.trim() ? parsed.message.trim() : parsed.error;
+  }
+  return structured;
+}
+function summarizeUnansweredMustHaveBlockers(payload) {
+  const questions = payload.blockers.map((blocker) => blocker.question.trim()).filter(Boolean);
+  if (questions.length === 0) {
+    return "Blocked by unanswered must-have blockers";
+  }
+  if (questions.length === 1) {
+    return `Blocked by unanswered must-have blocker: ${questions[0]}`;
+  }
+  return `Blocked by ${questions.length} unanswered must-have blockers: ${questions.join(" | ")}`;
+}
+function pendingBlockersFromPayload(payload) {
+  if (!payload) return [];
+  return payload.blockers.map((blocker) => ({
+    ...blocker.id?.trim() ? { id: blocker.id.trim() } : {},
+    question: blocker.question,
+    ...blocker.stageIds && blocker.stageIds.length > 0 ? { stageIds: blocker.stageIds } : {}
+  }));
+}
+function summarizePlanExecuteFailure(payload) {
+  const message = payload.message?.trim();
+  if (message) return message;
+  return payload.errors?.map((entry) => entry.trim()).find((entry) => entry.length > 0) ?? null;
+}
+function summarizePlanExecuteDecompositionFailure(payload) {
+  const message = payload.errorMessage?.trim();
+  if (message) return message;
+  if (payload.timedOut) return "Provider timed out during decomposition";
+  if (payload.idleTerminated) return "Provider was idle-terminated during decomposition";
+  if (payload.failureKind) return `Decomposition failed: ${payload.failureKind}`;
+  return null;
+}
+function childCommandExitCode(result) {
+  if (typeof result.exitCode === "number") return result.exitCode;
+  return result.signal || result.failed ? 1 : 0;
+}
+function stoppedOnVetRevise(output) {
+  const startIndex = output.lastIndexOf('{"error":"plan_vet_failed"');
+  if (startIndex < 0) return false;
+  const parsed = tryParseJsonObjectAt(output, startIndex);
+  return parsed?.recommendation === "revise";
+}
+function vetReviseNextStep(backlogItemId) {
+  return `Revise the item with \`build plan backlog update ${backlogItemId} --body-file <path>\`, then rerun \`build plan backlog execute ${backlogItemId}\`.`;
+}
+function parsePlanExecuteFailure(params) {
+  const parsed = parsePlanExecuteFailureCause(params);
+  if (parsed.status !== "failed" || !params.backlogItemId || !stoppedOnVetRevise(params.output ?? params.stderr)) {
+    return parsed;
+  }
+  return {
+    ...parsed,
+    errorMessage: `${parsed.errorMessage}. ${vetReviseNextStep(params.backlogItemId)}`
+  };
+}
+function parsePlanExecuteFailureCause(params) {
+  const exitCode = params.exitCode ?? 1;
+  const output = params.output ?? params.stderr;
+  const blockerPayload = exitCode === 2 ? extractUnansweredMustHaveBlockerPayload(output) : null;
+  if (blockerPayload) {
+    return {
+      status: "blocked",
+      failedAtStep: null,
+      errorMessage: summarizeUnansweredMustHaveBlockers(blockerPayload),
+      blockerPayload
+    };
+  }
+  const decompositionFailurePayload = extractPlanExecuteDecompositionFailurePayload(output);
+  const decompositionFailureSummary = decompositionFailurePayload ? summarizePlanExecuteDecompositionFailure(decompositionFailurePayload) : null;
+  if (decompositionFailureSummary) {
+    return {
+      status: "failed",
+      failedAtStep: "execute",
+      errorMessage: `planned build failed: ${decompositionFailureSummary}`
+    };
+  }
+  const failurePayload = extractPlanExecuteFailurePayload(output);
+  const failureSummary = failurePayload ? summarizePlanExecuteFailure(failurePayload) : null;
+  if (failureSummary) {
+    return {
+      status: "failed",
+      failedAtStep: "execute",
+      errorMessage: `planned build failed: ${failureSummary}`
+    };
+  }
+  const terminalReason = extractTerminalResultFailureReason(output);
+  if (terminalReason) {
+    return {
+      status: "failed",
+      failedAtStep: "execute",
+      errorMessage: `planned build failed: ${terminalReason}`
+    };
+  }
+  const stderrLine = extractLastNonEmptyStderrLine(params.stderr);
+  return {
+    status: "failed",
+    failedAtStep: "execute",
+    errorMessage: `planned build failed${stderrLine ? `: ${stderrLine}` : ""}`
+  };
+}
+async function collectTrackedTaskIds(params) {
+  if (!params.planArtifactPath) return [];
+  const normalizedPlanArtifactPath = path.posix.normalize(
+    params.planArtifactPath.replace(/\\/g, "/").trim()
+  );
+  if (!normalizedPlanArtifactPath || normalizedPlanArtifactPath === ".") return [];
+  try {
+    const tasks = await listTasksInSprint(params.sprintId);
+    return tasks.filter(
+      (task) => typeof task.planArtifactPath === "string" && path.posix.normalize(task.planArtifactPath.replace(/\\/g, "/").trim()) === normalizedPlanArtifactPath
+    ).map((task) => task.id);
+  } catch {
+    return [];
+  }
+}
+async function updateBacklogExecutionTracking(params) {
+  const manifest = await loadManifest(params.workflowId).catch(() => null);
+  const sprintId = manifest?.sprintId ?? null;
+  const planArtifact = manifest?.planArtifactPath ?? null;
+  const taskIds = sprintId && planArtifact ? await collectTrackedTaskIds({ sprintId, planArtifactPath: planArtifact }) : [];
+  return updateBacklogExecutionProvenance(params.projectRoot, params.backlogItemId, {
+    workflowId: params.workflowId,
+    sprintId,
+    taskIds,
+    planArtifact,
+    status: params.status,
+    lastCompletedStep: params.lastCompletedStep,
+    failedAtStep: params.failedAtStep,
+    errorMessage: params.errorMessage,
+    ...params.pendingBlockers !== void 0 ? { pendingBlockers: params.pendingBlockers } : {},
+    ...params.prNumber !== void 0 ? { prNumber: params.prNumber } : {},
+    ...params.mergeCommit !== void 0 ? { mergeCommit: params.mergeCommit } : {},
+    ...params.archiveSyncPrNumber !== void 0 ? { archiveSyncPrNumber: params.archiveSyncPrNumber } : {}
+  });
+}
+function deriveBacklogExecutionFailureStep(provenance) {
+  if (provenance.status === "blocked") {
+    return "execute";
+  }
+  if (provenance.lastCompletedStep === null && provenance.status === "initialized") {
+    return "initialize";
+  }
+  if (provenance.lastCompletedStep === "execute") {
+    return "create-pr";
+  }
+  if (provenance.status === "executing" || provenance.lastCompletedStep === "prepare-branch") {
+    return "execute";
+  }
+  return "prepare-branch";
+}
+function hasReusableExecutionResult(provenance) {
+  return typeof provenance.workflowId === "string" && provenance.workflowId.trim().length > 0 && provenance.status !== "blocked" && provenance.lastCompletedStep === "execute" && provenance.failedAtStep !== "execute";
+}
+async function recordBacklogExecutionStepFailure(params) {
+  const errorMessage = params.interruptSignal ? `Interrupted by ${params.interruptSignal}` : params.error instanceof Error ? params.error.message : String(params.error);
+  return updateBacklogExecutionProvenance(params.projectRoot, params.backlogItemId, {
+    status: "failed",
+    lastCompletedStep: params.lastCompletedStep,
+    failedAtStep: params.failedAtStep,
+    errorMessage
+  });
+}
+
+// src/cli/commands/next-resume-guidance.ts
+var NOT_GITHUB_HOST_ERROR = /point to a known github host/i;
+async function resolveNextResumeGuidance(params) {
+  try {
+    const repoRoot = resolveCliRepoRoot(params.cwd);
+    const provenance = await loadBacklogExecutionProvenance(params.rootDir, params.itemId, {
+      cleanupTerminalLocks: false
+    });
+    const resumable = provenance !== null && hasReusableExecutionResult(provenance) && !backlogExecutionStatusCarriesDelivery(provenance.status) && !await isBacklogExecutionProvenanceActivelyExecuting(params.rootDir, provenance);
+    if (resumable) {
+      const remote = await detectRemoteConfiguration(repoRoot);
+      const noPr = remote === "none" || NOT_GITHUB_HOST_ERROR.test(provenance.errorMessage ?? "");
+      if (!noPr) return { kind: "resume", noPr };
+      const current = (await execGit(["branch", "--show-current"], { cwd: repoRoot })).stdout.trim();
+      const target = (current && current === provenance.branch ? provenance.sourceBranch ?? "" : current).trim();
+      const role = classifyBranchRole(target);
+      const eligible = role !== "protected" && role !== "detached" && !isDisposableBranchRole(role);
+      return eligible ? { kind: "resume", noPr } : { kind: "resume", noPr, ineligibleApplyBranch: target || "(detached HEAD)" };
+    }
+    const branch = await execGit(
+      ["show-ref", "--verify", "--quiet", `refs/heads/${params.adHocBranch}`],
+      { cwd: repoRoot }
+    );
+    return branch.exitCode === 0 ? { kind: "branch-collision", branch: params.adHocBranch } : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/cli/commands/next.ts
+var UNTRACKED_NOTE = "Untracked: records no lifecycle provenance.";
+var BACKLOG_RUN_BRANCH_ID_MAX_LEN = 80;
+function sanitizeBacklogIdForRunBranch(id) {
+  const sanitized = String(id ?? "").trim().replace(/[^A-Za-z0-9_-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, BACKLOG_RUN_BRANCH_ID_MAX_LEN).replace(/-+$/g, "");
+  return sanitized.length > 0 ? sanitized : "item";
+}
+function backlogAdHocRunBranch(id) {
+  return `run/backlog-${sanitizeBacklogIdForRunBranch(id)}`;
+}
+async function listBacklogExecutionAttention(rootDir) {
+  const [
+    prOpenRecords,
+    deliveredLocalRecords,
+    executingRecords,
+    archiveSyncRecords,
+    mergedRecords,
+    archivedRecords
+  ] = await Promise.all([
+    listBacklogExecutionProvenanceByStatus(rootDir, "pr-open"),
+    listBacklogExecutionProvenanceByStatus(rootDir, "delivered-local"),
+    listBacklogExecutionProvenanceByStatus(rootDir, "executing"),
+    listBacklogExecutionProvenanceByStatus(rootDir, "archive-sync-pending"),
+    listBacklogExecutionProvenanceByStatus(rootDir, "merged"),
+    listBacklogExecutionProvenanceByStatus(rootDir, "archived")
+  ]);
+  const backlogDir = getBucketPathByKind("backlog", rootDir);
+  const activeDeliveredLocalRecords = await Promise.all(
+    deliveredLocalRecords.map(async (record) => {
+      try {
+        await fs.access(path2.join(backlogDir, `${record.backlogItemId}.md`));
+        return record;
+      } catch {
+        return null;
+      }
+    })
+  );
+  const ready = activeDeliveredLocalRecords.flatMap(
+    (record) => record ? [
+      {
+        backlogItemId: record.backlogItemId,
+        kind: "delivered-local"
+      }
+    ] : []
+  );
+  ready.push(
+    ...archiveSyncRecords.map((record) => ({
+      backlogItemId: record.backlogItemId,
+      kind: "archive-sync-pending",
+      archiveSyncPrNumber: record.archiveSyncPrNumber ?? null
+    }))
+  );
+  const runningRecords = await Promise.all(
+    executingRecords.map(async (record) => {
+      try {
+        await fs.access(path2.join(backlogDir, `${record.backlogItemId}.md`));
+        if (!await isBacklogExecutionProvenanceActivelyExecuting(rootDir, record)) {
+          return null;
+        }
+        return {
+          backlogItemId: record.backlogItemId,
+          branch: record.branch,
+          workflowId: record.workflowId
+        };
+      } catch {
+        return null;
+      }
+    })
+  );
+  const running = runningRecords.flatMap((record) => record ? [record] : []);
+  running.sort((a, b) => a.backlogItemId.localeCompare(b.backlogItemId));
+  const remoteTarget = prOpenRecords.length > 0 ? await refreshBacklogFinalizationTarget(rootDir) : void 0;
+  await Promise.all(
+    [...prOpenRecords, ...mergedRecords, ...archivedRecords].map(async (record) => {
+      try {
+        await fs.access(path2.join(backlogDir, `${record.backlogItemId}.md`));
+      } catch {
+        return;
+      }
+      const evidence = await inspectBacklogDeliveryEvidence(rootDir, record, {
+        remoteTarget,
+        // Keep the existing per-open-PR query count. Explicit execute can refresh one receipt.
+        queryPr: record.status === "pr-open"
+      });
+      if (evidence.readyMergeCommit && record.prNumber !== null) {
+        ready.push({
+          backlogItemId: record.backlogItemId,
+          kind: "merged-pr",
+          prNumber: record.prNumber,
+          mergeCommit: evidence.readyMergeCommit
+        });
+      } else if (evidence.state !== "confirmed") {
+        ready.push({
+          backlogItemId: record.backlogItemId,
+          kind: "reconciliation",
+          reason: evidence.reason
+        });
+      }
+    })
+  );
+  ready.sort((a, b) => a.backlogItemId.localeCompare(b.backlogItemId));
+  return { readyToFinalize: ready, running };
+}
+async function loadCurrentSprintActionSummary() {
+  try {
+    const { getCurrentSprint, listTasksInSprint: listTasksInSprint2 } = await import("./sprint-manager-MU2ZUWN2.js");
+    const current = await getCurrentSprint();
+    if (!current) {
+      return null;
+    }
+    const tasks = await listTasksInSprint2(current.yaml.id);
+    const openTaskCount = tasks.filter(
+      (task) => ["todo", "in_progress", "review"].includes(task.status)
+    ).length;
+    return openTaskCount > 0 ? { id: current.yaml.id, openTaskCount } : null;
+  } catch {
+    return null;
+  }
+}
+function shouldLoadNextFinalizeSummaries(options) {
+  return options.json !== true && options.quiet !== true && options.idsOnly !== true;
+}
+function buildMissingBacklogHint(buildDirExists) {
+  return buildDirExists ? 'Run `build plan backlog add "Your first task"` to get started.' : "Run `build init` to set up Build in this project.";
+}
+function createPlanNextCommand() {
+  const plan = new Command("plan").alias("pl");
+  plan.addCommand(createNextCommand());
+  return plan;
+}
+function createNextCommand() {
+  return new Command("next").description(
+    "Show actionable work items from the planning system\n\nExamples:\n  build plan next\n  build plan next --json\n  build plan next --limit 5\n  build plan next --kind debt\n  build plan next --kind all"
+  ).option("--json", "(OPTIONAL) Output as JSON for AI parsing\n    Example: --json").option("-q, --quiet", "(OPTIONAL) Suppress text output when no JSON is requested").option("-v, --verbose", "(OPTIONAL) Show extra context and follow-up commands").option(
+    "--ids-only",
+    "(OPTIONAL) Output compact id/title lines for terminal-friendly piping\n    Example: --ids-only"
+  ).option(
+    "--include-duplicates",
+    "(OPTIONAL) Include items that may be duplicates of archived items\n    Example: --include-duplicates"
+  ).option(
+    "--include-findings",
+    "(OPTIONAL) Include actionable findings and issues from the issue management system\n    Example: --include-findings"
+  ).option(
+    "--include-blocked",
+    "(OPTIONAL) Include backlog items whose blocked-by prerequisites are not yet done\n    (hidden by default; readiness shows only startable work)\n    Example: --include-blocked"
+  ).option("--limit <n>", "(OPTIONAL) Limit number of results\n    Example: --limit 5").option(
+    "--context",
+    "(OPTIONAL) Include body preview and acceptance criteria (opt-in, slower)\n    Example: --context"
+  ).option(
+    "--kind <types>",
+    '(OPTIONAL) Comma-separated entity kinds to include: backlog,debt,parking or "all"\n    Example: --kind debt  or  --kind all'
+  ).action(async (options) => {
+    const output = createCliOutputRenderer();
+    try {
+      const rootDir = getPlanningRoot();
+      await emitPlanningStateWarning(options.json === true);
+      const backlogDir = getBucketPathByKind("backlog", rootDir);
+      const unavailable = checkSharedBucketReadability(resolvePlanningContextForRoot(rootDir));
+      if (unavailable) {
+        output.event(errorEvent("Planning storage unavailable", { detail: unavailable.reason }));
+        throw new ExitCodeError(1);
+      }
+      const parsedKinds = parseKindOption(options.kind);
+      const limit = (() => {
+        if (!options.limit) {
+          return void 0;
+        }
+        const parsed = Number(options.limit);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          throw new Error("--limit must be a positive integer");
+        }
+        return parsed;
+      })();
+      const backlogExists = await fs.stat(backlogDir).then(() => true).catch(() => false);
+      const needsBacklog = parsedKinds.length === 0 || parsedKinds.includes("backlog");
+      if (!backlogExists && !options.includeFindings && needsBacklog && parsedKinds.length === 0) {
+        if (options.json) {
+          console.log(JSON.stringify([], null, 2));
+          return;
+        }
+        const buildDirExists = await fs.stat(path2.join(rootDir, ".build-project")).then(() => true).catch(() => false);
+        output.event(infoEvent("No backlog/ directory found"));
+        output.line(buildMissingBacklogHint(buildDirExists));
+        return;
+      }
+      const loadHumanAttention = shouldLoadNextFinalizeSummaries(options);
+      const [candidates, executionAttention, currentSprint] = await Promise.all([
+        queryNextItems({
+          rootDir,
+          limit,
+          context: options.context,
+          includeFindings: options.includeFindings,
+          includeDuplicates: options.includeDuplicates,
+          includeBlocked: options.includeBlocked,
+          kinds: parsedKinds
+        }),
+        loadHumanAttention ? listBacklogExecutionAttention(rootDir) : Promise.resolve({ readyToFinalize: [], running: [] }),
+        loadHumanAttention ? loadCurrentSprintActionSummary() : Promise.resolve(null)
+      ]);
+      if (options.json) {
+        console.log(JSON.stringify(candidates, null, 2));
+      } else if (options.quiet) {
+        return;
+      } else if (options.idsOnly) {
+        printNextCandidatesIdsOnly(candidates);
+      } else {
+        const topBacklog = candidates.find((c) => c.kind === "backlog" || c.kind === "task");
+        const resume = !options.verbose && topBacklog && !topBacklog.blockedReason && !topBacklog.needsRefinement ? await resolveNextResumeGuidance({
+          rootDir,
+          cwd: process.cwd(),
+          itemId: topBacklog.id,
+          adHocBranch: backlogAdHocRunBranch(topBacklog.id)
+        }) : null;
+        printNextCandidates(candidates, {
+          resume,
+          verbose: options.verbose === true,
+          readyToFinalize: executionAttention.readyToFinalize,
+          running: executionAttention.running,
+          currentSprint
+        });
+        await printInterruptedWorkWarning(output);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      output.event(errorEvent("Failed to query planning system", { detail: errorMessage }));
+      throw new ExitCodeError(1);
+    }
+  });
+}
+var INTERRUPTED_WORK_DEADLINE_MS = 3e3;
+async function printInterruptedWorkWarning(output) {
+  let timer;
+  try {
+    const { resolveCliRepoRoot: resolveCliRepoRoot2 } = await import("./repo-root-YG6MQZDW.js");
+    const { findInterruptedWork, formatInterruptedWorkWarning } = await import("./interrupted-work-E4TLKJLE.js");
+    const report = await Promise.race([
+      findInterruptedWork(resolveCliRepoRoot2(process.cwd())),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), INTERRUPTED_WORK_DEADLINE_MS);
+        timer.unref();
+      })
+    ]);
+    const line = report ? formatInterruptedWorkWarning(report) : void 0;
+    if (line) output.line(line);
+  } catch {
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function printNextCandidates(candidates, options = {}) {
+  const output = createCliOutputRenderer();
+  const running = options.running ?? [];
+  if (running.length > 0) {
+    output.line(`${running.length} backlog execution${running.length === 1 ? "" : "s"} running`);
+    for (const entry of running) {
+      output.line(`  ${entry.backlogItemId}`);
+      if (entry.branch) {
+        output.line(`    Branch: ${entry.branch}`);
+      }
+      if (entry.workflowId) {
+        output.line(`    Inspect: build run flywheel status ${entry.workflowId}`);
+      }
+    }
+    output.line("");
+  }
+  const currentSprint = options.currentSprint;
+  if (currentSprint) {
+    output.line(
+      `Current sprint: ${currentSprint.id} (${currentSprint.openTaskCount} open task${currentSprint.openTaskCount === 1 ? "" : "s"})`
+    );
+    output.line(`  Preview: build run sprint ${currentSprint.id} --preflight`);
+    output.line(`  Execute: build run sprint ${currentSprint.id} --apply`);
+    output.line("");
+  }
+  const readyToFinalize = options.readyToFinalize ?? [];
+  if (readyToFinalize.length > 0) {
+    output.line(
+      `${readyToFinalize.length} backlog item${readyToFinalize.length === 1 ? "" : "s"} needing completion attention`
+    );
+    for (const entry of readyToFinalize) {
+      if (entry.kind === "reconciliation") {
+        output.line(`  ${entry.backlogItemId}  needs reconciliation: ${entry.reason}`);
+        output.line("    Recorded delivery is preserved; inspect before resetting execution.");
+      } else if (entry.kind === "archive-sync-pending") {
+        output.line(
+          `  ${entry.backlogItemId}  archive sync PR #${entry.archiveSyncPrNumber ?? "unknown"}; merge if open, then resume finalization`
+        );
+        output.line("    Resume: build plan backlog finalize --auto");
+      } else if (entry.kind === "delivered-local") {
+        output.line(`  ${entry.backlogItemId}  delivered locally; complete or archive explicitly`);
+        if (options.verbose) {
+          output.verbose(`build plan backlog archive ${entry.backlogItemId} --reason <reason>`);
+        }
+      } else {
+        output.line(`  ${entry.backlogItemId}  PR #${entry.prNumber}`);
+        if (options.verbose) {
+          output.verbose(
+            `build plan backlog finalize ${entry.backlogItemId} --pr ${entry.prNumber} --commit ${entry.mergeCommit}`
+          );
+        }
+      }
+    }
+    output.line("");
+  }
+  if (candidates.length === 0) {
+    if (running.length === 0 && readyToFinalize.length === 0 && !currentSprint) {
+      output.line("No actionable items found.");
+      if (options.verbose) {
+        output.verbose('Add items with: build plan backlog add "Your task"');
+      }
+    }
+    return;
+  }
+  output.line(`${candidates.length} actionable item${candidates.length === 1 ? "" : "s"}`);
+  output.line("");
+  const hasMultipleKinds = candidates.some((c) => c.kind === "debt" || c.kind === "parking");
+  const byPriority = {};
+  for (const candidate of candidates) {
+    let key;
+    if (candidate.kind === "debt") {
+      key = `debt-${candidate.severity ?? "low"}`;
+    } else if (candidate.kind === "parking") {
+      key = "parking";
+    } else {
+      key = candidate.priority || "Unprioritized";
+    }
+    if (!byPriority[key]) byPriority[key] = [];
+    byPriority[key]?.push(candidate);
+  }
+  const priorityLabels = {
+    P0: "P0 Critical",
+    P1: "P1 High",
+    P2: "P2 Medium",
+    P3: "P3 Low",
+    Unprioritized: "Unprioritized",
+    "debt-critical": "Tech Debt Critical",
+    "debt-high": "Tech Debt High",
+    "debt-medium": "Tech Debt Medium",
+    "debt-low": "Tech Debt Low",
+    parking: "Parking Lot"
+  };
+  const displayOrder = [
+    "P0",
+    "P1",
+    "debt-critical",
+    "debt-high",
+    "P2",
+    "P3",
+    "Unprioritized",
+    "debt-medium",
+    "debt-low",
+    "parking"
+  ];
+  for (const groupKey of displayOrder) {
+    const items = byPriority[groupKey];
+    if (!items || items.length === 0) {
+      continue;
+    }
+    output.line(priorityLabels[groupKey] || groupKey);
+    for (const item of items) {
+      const kindLabel = hasMultipleKinds ? item.kind === "finding" ? " [finding]" : item.kind === "issue" ? " [issue]" : item.kind === "debt" ? " [debt]" : item.kind === "parking" ? " [parking]" : " [backlog]" : item.kind === "finding" ? "[finding]" : item.kind === "issue" ? "[issue]" : "";
+      const duplicateBadge = item.isDuplicate ? " [dup?]" : "";
+      const incompleteBadge = item.blockedReason || item.needsRefinement ? " [refine]" : "";
+      const blockedBadge = item.blockedByOpen && item.blockedByOpen.length > 0 ? ` [blocked x${item.blockedByOpen.length}]` : "";
+      output.line(`  ${item.title}${kindLabel}${duplicateBadge}${incompleteBadge}${blockedBadge}`);
+      output.line(`    ${item.id}`);
+      if (item.kind === "debt") {
+        const blockingTag = item.blocking ? " blocking" : "";
+        output.line(
+          `    Severity: ${item.severity ?? "unknown"}${blockingTag}  Effort: ${item.effort ?? "unknown"}`
+        );
+      } else if (item.kind === "parking") {
+        const reasonRaw = item.deferralReason ?? "";
+        const reason = reasonRaw.length > 40 ? `${reasonRaw.slice(0, 40)}...` : reasonRaw;
+        const overdueTag = item.isOverdue ? " overdue" : "";
+        const reconsiderStr = item.reconsiderDate ? `  Reconsider: ${item.reconsiderDate}${overdueTag}` : "";
+        if (reason) output.line(`    Reason: ${reason}${reconsiderStr}`);
+        else if (reconsiderStr) output.line(`   ${reconsiderStr.trimStart()}`);
+      } else {
+        if (item.domain && item.domain !== "general") {
+          output.line(`    Domain: ${item.domain}`);
+        }
+        if (item.complexity !== void 0) {
+          output.line(`    Complexity: ${item.complexity}`);
+        }
+        if (item.duplicateOf) {
+          output.line(`    Possibly duplicate of: ${item.duplicateOf}`);
+        }
+        if (item.blockedReason) {
+          output.line(`    Blocked: ${item.blockedReason}`);
+          const answerHint = item.blockedAnswerHint ?? `build plan backlog execute ${item.id} --answer blockerId=value`;
+          output.line(`    Answer with: ${answerHint}`);
+        }
+        if (item.blockedByOpen && item.blockedByOpen.length > 0) {
+          const blockerList = item.blockedByOpen.map((b) => b.title ? `${b.id} (${b.title})` : b.id).join(", ");
+          output.line(`    Blocked by ${item.blockedByOpen.length} open: ${blockerList}`);
+        }
+        if (item.bodyPreview) {
+          const previewLine = item.bodyPreview.replace(/\s+/g, " ").trim();
+          output.line(`    ${previewLine.slice(0, 80)}${previewLine.length > 80 ? "..." : ""}`);
+        }
+        if (item.acceptanceCriteria && item.acceptanceCriteria.length > 0) {
+          output.line(`    Acceptance criteria: ${item.acceptanceCriteria.length} item(s)`);
+        }
+      }
+      output.line("");
+    }
+  }
+  const topBacklog = candidates.find((c) => c.kind === "backlog" || c.kind === "task");
+  if (!options.verbose && topBacklog) {
+    output.line("---");
+    if (topBacklog.blockedReason || topBacklog.needsRefinement) {
+      output.line(`Next: ${topBacklog.id} \u2014 ${topBacklog.title}`);
+      output.line(`  Refine: build plan backlog refine ${topBacklog.id}`);
+    } else {
+      const adHocBranch = backlogAdHocRunBranch(topBacklog.id);
+      const resume = options.resume;
+      output.line(`Next: ${topBacklog.id} \u2014 ${topBacklog.title}`);
+      if (resume?.kind === "resume") {
+        const flag = resume.noPr ? " --no-open-pr" : "";
+        output.line(`  Resume:    build plan backlog execute ${topBacklog.id}${flag}`);
+        output.line(
+          resume.noPr ? "             Reuses the finished build, applies it locally and archives the item; origin has no GitHub PR path." : "             Reuses the finished build and opens the PR."
+        );
+        if (resume.ineligibleApplyBranch) {
+          output.line(
+            `             Current branch ${resume.ineligibleApplyBranch} cannot take a local apply; first switch to or create a product branch (for example git switch -c fix/<slug>).`
+          );
+        }
+      } else {
+        output.line(`  Canonical: build plan backlog execute ${topBacklog.id}`);
+        output.line(`             ${TRACKED_EXECUTE_NOTE}`);
+        if (resume?.kind === "branch-collision") {
+          output.line(
+            `  Ad hoc:    run branch ${resume.branch} already exists; check it out or delete it,`
+          );
+        } else {
+          output.line(`  Ad hoc:    git checkout -b ${adHocBranch}`);
+        }
+        output.line(`             then build run --backlog-item ${topBacklog.id} --no-push`);
+        output.line(`             ${UNTRACKED_NOTE}`);
+      }
+      output.line(`  Show:      build plan backlog show ${topBacklog.id}`);
+    }
+  }
+  if (options.verbose) {
+    output.verbose("Commands:");
+    output.verbose("  build plan backlog refine <id>");
+    output.verbose("  build plan backlog show <id>");
+    output.verbose("  Canonical: build plan backlog execute <id>");
+    output.verbose(`             ${TRACKED_EXECUTE_NOTE}`);
+    output.verbose("  Ad hoc:    git checkout -b run/backlog-<sanitized-id>");
+    output.verbose("             then build run --backlog-item <id> --no-push");
+    output.verbose(`             ${UNTRACKED_NOTE}`);
+  }
+}
+function formatNextCandidateIdsOnlyLine(candidate) {
+  return `${candidate.id}	${candidate.title}`;
+}
+function printNextCandidatesIdsOnly(candidates) {
+  if (candidates.length === 0) {
+    console.log("No actionable items found.");
+    return;
+  }
+  for (const candidate of candidates) {
+    console.log(formatNextCandidateIdsOnlyLine(candidate));
+  }
+}
+
+export {
+  backlogExecutionBranchName,
+  isBacklogExecutionBranchName,
+  backlogSyncBranchName,
+  backlogExecuteSignalCleanupName,
+  backlogFinalizeSignalCleanupName,
+  backlogExecuteReceiptCopy,
+  finalizeFailureProvenanceUpdate,
+  finalizeInterruptProvenanceUpdate,
+  parsePrNumberFromUrl,
+  extractWorkflowIdFromOutput,
+  extractPlanExecuteFailurePayload,
+  extractPlanExecuteDecompositionFailurePayload,
+  pendingBlockersFromPayload,
+  childCommandExitCode,
+  parsePlanExecuteFailure,
+  updateBacklogExecutionTracking,
+  deriveBacklogExecutionFailureStep,
+  hasReusableExecutionResult,
+  recordBacklogExecutionStepFailure,
+  sanitizeBacklogIdForRunBranch,
+  backlogAdHocRunBranch,
+  shouldLoadNextFinalizeSummaries,
+  buildMissingBacklogHint,
+  createPlanNextCommand,
+  createNextCommand,
+  printNextCandidates,
+  formatNextCandidateIdsOnlyLine,
+  printNextCandidatesIdsOnly
+};
+//# sourceMappingURL=chunk-MTU7VTNN.js.map