lee-spec-kit 0.8.0 → 0.8.1

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { hasLeeSpecKitCodexBootstrap } from './chunk-RYSDBL6X.js';
+import { hasLeeSpecKitCodexBootstrap } from './chunk-LYFRLOFQ.js';
 import { runGitCapture, runGitOrThrow } from './chunk-GR7JQBWF.js';
 import { __dirname as __dirname$1 } from './chunk-7V7RMGEU.js';
 import { program } from 'commander';
@@ -1282,17 +1282,24 @@ On session start or after context compression/reset:
 3. Read any unread \`requiredDocs[*].command\` from that output
 4. Cache built-in docs per session and only re-read them when the user explicitly asks for a policy refresh, \`npx lee-spec-kit update\` changed the policy, or the session restarted
 
-Before implementing or editing:
+Before taking the next workflow step:
 
 1. Confirm the active feature from the request, docs tree, issue/PR context, or the most recently active feature folder
 2. Read the active feature docs as the SSOT: \`spec.md\`, \`plan.md\`, \`tasks.md\`, and \`decisions.md\`
 3. When relevant, also read \`issue.md\` and \`pr.md\`
-4. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
-5. When docs are synced to code, refresh an explicit marker like \`<!-- lee-spec-kit:workflow-sync 2026-04-16T12:34:56.789Z -->\` in the active feature docs (prefer \`tasks.md\` or \`decisions.md\`) so \`workflow-audit\` can prove the sync happened after the latest code change
+4. Run \`npx lee-spec-kit workflow-stage <feature-ref> --json\` and follow only the returned \`nextAction\`
+5. Do not start implementation unless \`stage === "implementation"\` and \`implementationAllowed === true\`
+6. Treat stages before implementation as hard gates:
+   - spec / plan / tasks approvals
+   - issue preparation / issue creation
+   - branch creation
+7. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
+8. When docs are synced to code, refresh an explicit marker like \`<!-- lee-spec-kit:workflow-sync 2026-04-16T12:34:56.789Z -->\` in the active feature docs (prefer \`tasks.md\` or \`decisions.md\`) so \`workflow-audit\` can prove the sync happened after the latest code change
 
 Approval and remote actions:
 
 - Ask the user for approval only at documented workflow approval boundaries or before remote/destructive actions
+- If \`workflow-stage --json\` reports \`approvalRequired === true\`, stop at that boundary and ask the user before proceeding
 - Before \`git commit\`, prefer \`npx lee-spec-kit commit-audit --json\` when hooks or manual checks need commit-time docs path enforcement
 - Before remote GitHub actions, share the plan or artifact being sent
 - Respect repo policy from docs and config first; hooks only enforce guardrails and continuation checks
@@ -2476,16 +2483,10 @@ async function runInit(options) {
               "Standalone workspace root could not be resolved. Re-run init from the shared workspace root above the docs directory."
             );
           }
-          await upsertLeeSpecKitAgentsMd(path8.join(targetDir, "AGENTS.md"), {
+          await upsertLeeSpecKitAgentsMd(path8.join(standaloneWorkspaceRoot, "AGENTS.md"), {
             lang,
             docsRepo
           });
-          if (standaloneWorkspaceRoot !== path8.resolve(targetDir)) {
-            await upsertLeeSpecKitAgentsMd(path8.join(standaloneWorkspaceRoot, "AGENTS.md"), {
-              lang,
-              docsRepo
-            });
-          }
         }
       } catch {
       }
@@ -3438,7 +3439,6 @@ async function collectAgentsMdTargets(cwd, config) {
     targets.add(path8.join(repoRoot, "AGENTS.md"));
     return [...targets];
   }
-  targets.add(path8.join(config.docsDir, "AGENTS.md"));
   const workspaceRoot = resolveConfiguredStandaloneWorkspaceRoot(config);
   if (!workspaceRoot) {
     throw createCliError(
@@ -3446,9 +3446,7 @@ async function collectAgentsMdTargets(cwd, config) {
       "Standalone workspaceRoot is missing or invalid. Run `npx lee-spec-kit update --agents-md` from the shared workspace root to migrate this project."
     );
   }
-  if (workspaceRoot !== path8.resolve(config.docsDir)) {
-    targets.add(path8.join(workspaceRoot, "AGENTS.md"));
-  }
+  targets.add(path8.join(workspaceRoot, "AGENTS.md"));
   return [...targets];
 }
 function isPlainObject(value) {
@@ -6738,7 +6736,7 @@ function registerCodexIntegration(parent) {
         getCodexConfigPath,
         removeLeeSpecKitCodexBootstrap,
         upsertLeeSpecKitCodexBootstrap
-      } = await import('./bootstrap-ZIJP7O72.js');
+      } = await import('./bootstrap-G37N6RGB.js');
       const filePath = getCodexConfigPath();
       if (options.remove) {
         const result2 = await removeLeeSpecKitCodexBootstrap(filePath);
@@ -6783,7 +6781,7 @@ function registerCodexHooksIntegration(parent) {
         removeLeeSpecKitCodexHooks,
         resolveCodexHooksRepoRoot,
         upsertLeeSpecKitCodexHooks
-      } = await import('./hooks-IP6FICAV.js');
+      } = await import('./hooks-4S33YUIB.js');
       const repoRoot = config.docsRepo === "standalone" ? resolveConfiguredStandaloneWorkspaceRoot(config) : resolveCodexHooksRepoRoot(process.cwd());
       if (!repoRoot) {
         throw createCliError(
@@ -6818,6 +6816,529 @@ function integrationsCommand(program2) {
   registerCodexIntegration(integrations);
   registerCodexHooksIntegration(integrations);
 }
+var DOC_STATUS_LABELS = ["Doc Status", "\uBB38\uC11C \uC0C1\uD0DC"];
+var ISSUE_LABELS = ["Issue", "Issue Number", "\uC774\uC288", "\uC774\uC288 \uBC88\uD638"];
+var BRANCH_LABELS = ["Branch", "\uBE0C\uB79C\uCE58"];
+var PR_LABELS = ["PR", "Pull Request"];
+var PR_STATUS_LABELS = ["PR Status", "PR \uC0C1\uD0DC"];
+var PRE_PR_REVIEW_LABELS = ["Pre-PR Review", "PR \uC804 \uB9AC\uBDF0"];
+var PRE_PR_EVIDENCE_LABELS = ["Pre-PR Evidence", "PR \uC804 \uB9AC\uBDF0 Evidence"];
+var PRE_PR_DECISION_LABELS = ["Pre-PR Decision", "PR \uC804 \uB9AC\uBDF0 Decision"];
+function resolveWorkflowRequirements(config) {
+  const workflow = config.workflow || {};
+  const workflowMode = workflow.mode || workflow.preset || "github";
+  const isLocalWorkflow = workflowMode === "local";
+  return {
+    requireIssue: workflow.requireIssue ?? !isLocalWorkflow,
+    requireBranch: workflow.requireBranch ?? true,
+    requirePr: workflow.requirePr ?? !isLocalWorkflow,
+    requireReview: workflow.requireReview ?? !isLocalWorkflow,
+    requireMerge: workflow.requireMerge ?? !isLocalWorkflow,
+    prePrReviewEnabled: workflow.prePrReview?.enabled ?? !isLocalWorkflow
+  };
+}
+function parseApprovalStatus(raw) {
+  const value = (raw || "").trim().toLowerCase();
+  if (value === "draft") return "draft";
+  if (value === "review") return "review";
+  if (value === "approved") return "approved";
+  return null;
+}
+function extractFieldValue(content, labels) {
+  for (const label of Array.isArray(labels) ? labels : [labels]) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = content.match(
+      new RegExp(`^\\s*-\\s*\\*\\*${escaped}\\*\\*:\\s*(.*?)\\s*$`, "mi")
+    );
+    if (!match) continue;
+    const value = match[1].trim();
+    if (value) return value;
+  }
+  return null;
+}
+function parseMarkdownCheckbox(line) {
+  const match = line.match(/^\s*-\s*\[([ xX])\]\s+/);
+  if (!match) return null;
+  return match[1].toLowerCase() === "x";
+}
+function withoutFencedCodeBlocks(content) {
+  const lines = [];
+  let inFence = false;
+  for (const line of content.split("\n")) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence) {
+      lines.push(line);
+    }
+  }
+  return lines;
+}
+function parseTasksDoc(content) {
+  const issueRaw = extractFieldValue(content, ISSUE_LABELS);
+  const issueNumberMatch = issueRaw?.match(/^#(\d+)$/);
+  const issueNumber = issueNumberMatch ? Number(issueNumberMatch[1]) : null;
+  const branchRaw = extractFieldValue(content, BRANCH_LABELS);
+  const prRaw = extractFieldValue(content, PR_LABELS);
+  const prePrDecision = extractFieldValue(content, PRE_PR_DECISION_LABELS);
+  const tasks = [];
+  const nonCodeLines = withoutFencedCodeBlocks(content);
+  for (const line of nonCodeLines) {
+    const match = line.match(
+      /^\s*-\s*\[(TODO|DOING|DONE|REVIEW)\](?:\[[^\]]+\])*\s+(.+?)\s*$/i
+    );
+    if (!match) continue;
+    tasks.push({
+      raw: line,
+      status: match[1].toUpperCase(),
+      title: match[2].trim()
+    });
+  }
+  const allTasksChecked = nonCodeLines.some(
+    (line) => /(All tasks are|모든 태스크가)/i.test(line) && parseMarkdownCheckbox(line) === true
+  );
+  const testsChecked = nonCodeLines.some(
+    (line) => /(Tests executed and passing|테스트 실행 및 통과)/i.test(line) && parseMarkdownCheckbox(line) === true
+  );
+  const finalOutcomeChecked = nonCodeLines.some(
+    (line) => /(Final outcome shared and any required user confirmation recorded|Final user approval|최종 결과를 공유했고, 필요한 사용자 확인을 문서화된 workflow checkpoint 기준으로 기록함)/i.test(
+      line
+    ) && parseMarkdownCheckbox(line) === true
+  );
+  const prStatus = (() => {
+    const value = (extractFieldValue(content, PR_STATUS_LABELS) || "").trim().toLowerCase();
+    if (value === "review") return "review";
+    if (value === "approved") return "approved";
+    return null;
+  })();
+  const prePrReviewStatus = (() => {
+    const value = (extractFieldValue(content, PRE_PR_REVIEW_LABELS) || "").trim().toLowerCase();
+    if (value === "pending") return "pending";
+    if (value === "running") return "running";
+    if (value === "done") return "done";
+    return null;
+  })();
+  const prePrDecisionOutcome = (() => {
+    const value = (prePrDecision || "").trim().toLowerCase();
+    const match = value.match(/\b(approve|changes_requested|blocked)\b/);
+    return match?.[1] || null;
+  })();
+  return {
+    docStatus: parseApprovalStatus(
+      extractFieldValue(content, DOC_STATUS_LABELS) || void 0
+    ),
+    issueNumber,
+    branch: sanitizeMetadataValue(branchRaw),
+    prLink: sanitizeMetadataValue(prRaw),
+    prStatus,
+    prePrReviewStatus,
+    prePrEvidence: sanitizeMetadataValue(
+      extractFieldValue(content, PRE_PR_EVIDENCE_LABELS)
+    ),
+    prePrDecision: sanitizeMetadataValue(prePrDecision),
+    prePrDecisionOutcome,
+    tasks,
+    completion: {
+      allTasksChecked,
+      testsChecked,
+      finalOutcomeChecked
+    }
+  };
+}
+function sanitizeMetadataValue(value) {
+  if (!value) return null;
+  const trimmed = value.trim().replace(/^`(.+)`$/, "$1");
+  if (!trimmed || trimmed === "-") return null;
+  return trimmed;
+}
+function parseWorkflowDraftMetadataExtended(content) {
+  const metadata = parseWorkflowDraftMetadata(content);
+  const prStatusRaw = extractFieldValue(content, PR_STATUS_LABELS);
+  const normalizedPrStatus = (prStatusRaw || "").trim().toLowerCase();
+  return {
+    ...metadata,
+    issueRef: sanitizeMetadataValue(extractFieldValue(content, ISSUE_LABELS)),
+    prRef: sanitizeMetadataValue(extractFieldValue(content, PR_LABELS)),
+    prStatus: normalizedPrStatus === "review" ? "review" : normalizedPrStatus === "approved" ? "approved" : null
+  };
+}
+async function readFileIfExists(filePath) {
+  if (!await fs.pathExists(filePath)) return null;
+  return fs.readFile(filePath, "utf-8");
+}
+function buildFeatureRef(feature) {
+  return feature.folderName;
+}
+function buildFeatureArgs(feature) {
+  return feature.type && feature.type !== "single" ? `${buildFeatureRef(feature)} --component ${feature.type}` : buildFeatureRef(feature);
+}
+function resolveExpectedBranch(feature, tasks) {
+  if (tasks.branch) return tasks.branch;
+  if (!tasks.issueNumber) return null;
+  return `feat/${tasks.issueNumber}-${feature.slug}`;
+}
+function getCurrentProjectBranch(feature) {
+  return runGitCapture(["branch", "--show-current"], feature.git.projectGitCwd) || runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], feature.git.projectGitCwd) || null;
+}
+function nextTodoTask(tasks) {
+  return tasks.tasks.find((task) => task.status === "DOING") || tasks.tasks.find((task) => task.status === "TODO") || null;
+}
+function allTasksDone(tasks) {
+  return tasks.tasks.length > 0 && tasks.tasks.every((task) => task.status === "DONE");
+}
+function prePrSatisfied(tasks) {
+  return tasks.prePrReviewStatus === "done" && !!tasks.prePrEvidence && !!tasks.prePrDecision && tasks.prePrDecisionOutcome === "approve";
+}
+function issueExistsRemotely(issueNumber, feature) {
+  if (!issueNumber) return false;
+  const result = runProcess(
+    "gh",
+    ["issue", "view", String(issueNumber), "--json", "number"],
+    feature.git.projectGitCwd
+  );
+  return result.code === 0;
+}
+function prExistsRemotely(prRef, feature) {
+  if (!prRef) return false;
+  const result = runProcess(
+    "gh",
+    ["pr", "view", prRef, "--json", "url"],
+    feature.git.projectGitCwd
+  );
+  return result.code === 0;
+}
+function buildAction(category, summary, approvalRequired, command = null) {
+  return {
+    category,
+    summary,
+    approvalRequired,
+    command
+  };
+}
+function resolveFeatureSelectionError(selection) {
+  const reasonCode = selection.status === "no_features" ? "NO_FEATURES" : "FEATURE_SELECTION_REQUIRED";
+  return {
+    status: "error",
+    reasonCode,
+    docsDir: selection.config.docsDir,
+    featureRef: null,
+    stage: null,
+    nextAction: null,
+    approvalRequired: false,
+    implementationAllowed: false,
+    blockedReasonCode: null
+  };
+}
+async function collectWorkflowStage(cwd, selector, component) {
+  const config = await getConfig(cwd);
+  if (!config) {
+    return {
+      status: "error",
+      reasonCode: "CONFIG_NOT_FOUND",
+      docsDir: null,
+      featureRef: null,
+      stage: null,
+      nextAction: null,
+      approvalRequired: false,
+      implementationAllowed: false,
+      blockedReasonCode: null
+    };
+  }
+  const selection = await resolveFeatureSelection(cwd, selector, component);
+  if (selection.status !== "selected" || !selection.matchedFeature) {
+    return resolveFeatureSelectionError(selection);
+  }
+  const feature = selection.matchedFeature;
+  const requirements = resolveWorkflowRequirements(config);
+  const paths = getFeatureDocPaths(feature);
+  const specContent = await readFileIfExists(path8.join(config.docsDir, paths.specPath));
+  const planContent = await readFileIfExists(path8.join(config.docsDir, paths.planPath));
+  const tasksContent = await readFileIfExists(path8.join(config.docsDir, paths.tasksPath));
+  const issueContent = await readFileIfExists(path8.join(config.docsDir, paths.issuePath));
+  const prContent = await readFileIfExists(path8.join(config.docsDir, paths.prPath));
+  const specStatus = parseApprovalStatus(
+    extractFieldValue(specContent || "", ["Status", "\uC0C1\uD0DC"]) || void 0
+  );
+  const planStatus = parseApprovalStatus(
+    extractFieldValue(planContent || "", ["Status", "\uC0C1\uD0DC"]) || void 0
+  );
+  const tasks = parseTasksDoc(tasksContent || "");
+  const issueDraft = parseWorkflowDraftMetadataExtended(issueContent || "");
+  const prDraft = parseWorkflowDraftMetadataExtended(prContent || "");
+  if (specStatus !== "approved") {
+    const approvalRequired = specStatus === "review";
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "spec",
+      nextAction: buildAction(
+        approvalRequired ? "spec_approve" : "spec_write",
+        approvalRequired ? "Get user approval and update spec.md status to Approved." : "Write or refine spec.md until it is ready for approval.",
+        approvalRequired
+      ),
+      approvalRequired,
+      implementationAllowed: false,
+      blockedReasonCode: "SPEC_NOT_APPROVED"
+    };
+  }
+  if (planStatus !== "approved") {
+    const approvalRequired = planStatus === "review";
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "plan",
+      nextAction: buildAction(
+        approvalRequired ? "plan_approve" : "plan_write",
+        approvalRequired ? "Get user approval and update plan.md status to Approved." : "Write or refine plan.md until it is ready for approval.",
+        approvalRequired
+      ),
+      approvalRequired,
+      implementationAllowed: false,
+      blockedReasonCode: "PLAN_NOT_APPROVED"
+    };
+  }
+  if (tasks.tasks.length === 0 || tasks.docStatus !== "approved") {
+    const approvalRequired = tasks.docStatus === "review";
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "tasks",
+      nextAction: buildAction(
+        approvalRequired ? "tasks_approve" : "tasks_write",
+        approvalRequired ? "Get user approval and update tasks.md Doc Status to Approved." : "Add and refine tasks until tasks.md is execution-ready and Approved.",
+        approvalRequired
+      ),
+      approvalRequired,
+      implementationAllowed: false,
+      blockedReasonCode: "TASKS_NOT_READY"
+    };
+  }
+  if (requirements.requireIssue) {
+    const issueReady = issueDraft.status === "ready";
+    const issueCreated = tasks.issueNumber !== null && issueExistsRemotely(tasks.issueNumber, feature);
+    if (!issueCreated || !issueReady) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "issue",
+        nextAction: issueReady && !issueCreated ? buildAction(
+          "issue_create",
+          "Create the GitHub issue from issue.md and sync the issue number into tasks.md.",
+          true,
+          `npx lee-spec-kit github issue ${buildFeatureArgs(feature)} --create --confirm OK`
+        ) : buildAction(
+          "issue_prepare",
+          "Prepare issue.md and set its Status to Ready before issue creation.",
+          false
+        ),
+        approvalRequired: issueReady && !issueCreated,
+        implementationAllowed: false,
+        blockedReasonCode: "ISSUE_NOT_CREATED"
+      };
+    }
+  }
+  if (requirements.requireBranch && !allTasksDone(tasks)) {
+    const expectedBranch = resolveExpectedBranch(feature, tasks);
+    const currentBranch = getCurrentProjectBranch(feature);
+    if (expectedBranch && currentBranch !== expectedBranch) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "branch",
+        nextAction: buildAction(
+          "branch_create",
+          `Switch the project repo to ${expectedBranch} before implementation starts.`,
+          false,
+          `git checkout -b ${expectedBranch}`
+        ),
+        approvalRequired: false,
+        implementationAllowed: false,
+        blockedReasonCode: "BRANCH_NOT_READY"
+      };
+    }
+  }
+  if (!allTasksDone(tasks)) {
+    const currentTask = nextTodoTask(tasks);
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "implementation",
+      nextAction: buildAction(
+        "task_execute",
+        currentTask ? `Continue the next implementation task: ${currentTask.title}` : "Continue the active implementation task.",
+        false
+      ),
+      approvalRequired: false,
+      implementationAllowed: true,
+      blockedReasonCode: null
+    };
+  }
+  if (!tasks.completion.allTasksChecked || !tasks.completion.testsChecked || !tasks.completion.finalOutcomeChecked) {
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "implementation_approve",
+      nextAction: buildAction(
+        "implementation_approve",
+        "Share the completed implementation, get user approval, and record the completion checkpoint in tasks.md.",
+        true
+      ),
+      approvalRequired: true,
+      implementationAllowed: false,
+      blockedReasonCode: "IMPLEMENTATION_APPROVAL_REQUIRED"
+    };
+  }
+  if (requirements.prePrReviewEnabled && !prePrSatisfied(tasks)) {
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "pre_pr_review",
+      nextAction: buildAction(
+        "pre_pr_review",
+        "Run and record the Pre-PR review until tasks.md shows an approve decision with evidence.",
+        false
+      ),
+      approvalRequired: false,
+      implementationAllowed: false,
+      blockedReasonCode: "PRE_PR_REVIEW_NOT_APPROVED"
+    };
+  }
+  if (requirements.requirePr) {
+    const prReady = prDraft.status === "ready";
+    const prCreated = !!tasks.prLink && prExistsRemotely(tasks.prLink, feature);
+    if (!prCreated || !prReady) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "pr",
+        nextAction: prReady && !prCreated ? buildAction(
+          "pr_create",
+          "Create the GitHub PR from pr.md and sync the PR metadata into tasks.md.",
+          true,
+          `npx lee-spec-kit github pr ${buildFeatureArgs(feature)} --create --confirm OK`
+        ) : buildAction(
+          "pr_prepare",
+          "Prepare pr.md and set its Status to Ready before PR creation.",
+          false
+        ),
+        approvalRequired: prReady && !prCreated,
+        implementationAllowed: false,
+        blockedReasonCode: "PR_NOT_CREATED"
+      };
+    }
+  }
+  if (requirements.requireReview && (tasks.prStatus !== "approved" || prDraft.prStatus !== "approved")) {
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "code_review",
+      nextAction: buildAction(
+        "code_review",
+        "Complete PR review and record the final approved review state in tasks.md.",
+        false
+      ),
+      approvalRequired: false,
+      implementationAllowed: false,
+      blockedReasonCode: "PR_REVIEW_NOT_APPROVED"
+    };
+  }
+  if (requirements.requireMerge) {
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "merge",
+      nextAction: buildAction(
+        "pr_merge",
+        "Merge the PR and sync the merged state back into tasks.md.",
+        true,
+        `npx lee-spec-kit github pr ${buildFeatureArgs(feature)} --merge --confirm OK`
+      ),
+      approvalRequired: true,
+      implementationAllowed: false,
+      blockedReasonCode: null
+    };
+  }
+  return {
+    status: "ok",
+    reasonCode: "WORKFLOW_STAGE_RESOLVED",
+    docsDir: config.docsDir,
+    featureRef: buildFeatureRef(feature),
+    stage: "done",
+    nextAction: null,
+    approvalRequired: false,
+    implementationAllowed: false,
+    blockedReasonCode: null
+  };
+}
+
+// src/commands/workflow-stage.ts
+function workflowStageCommand(program2) {
+  program2.command("workflow-stage [feature-name]").description("Resolve the current high-level workflow stage for the active feature").option("--json", "Output JSON for agents and hooks").option("--component <component>", "Component name for multi projects").action(async (featureName, options) => {
+    try {
+      const payload = await collectWorkflowStage(
+        process.cwd(),
+        featureName,
+        options.component
+      );
+      if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (payload.status !== "ok") {
+        console.log(`${payload.status}: ${payload.reasonCode}`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(`stage: ${payload.stage}`);
+      if (payload.nextAction) {
+        console.log(`next: ${payload.nextAction.category}`);
+      }
+    } catch (error) {
+      const cliError = toCliError(error);
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              status: "error",
+              reasonCode: cliError.code,
+              error: cliError.message
+            },
+            null,
+            2
+          )
+        );
+        process.exitCode = 1;
+        return;
+      }
+      process.stderr.write(`[${cliError.code}] ${cliError.message}
+`);
+      process.exitCode = 1;
+    }
+  });
+}
 var FEATURE_DOC_FILE_PATTERN = /^features\/(?:[^/]+\/)?F\d{3,}[^/]*\/(spec|plan|tasks|decisions|issue|pr)\.md$/i;
 var CODE_FILE_PATTERN = /(^|\/)(Dockerfile|Makefile)$|\.(c|cc|cjs|cpp|cs|css|cts|go|h|hpp|html|java|js|json|jsx|kt|mjs|mts|php|py|rb|rs|scss|sh|sql|swift|ts|tsx|vue|yaml|yml|zsh)$/i;
 var WORKFLOW_SYNC_MARKER_PATTERN = /<!--\s*lee-spec-kit:workflow-sync\s+([0-9]{4}-[0-9]{2}-[0-9]{2}T[^ ]+?)\s*-->/gi;
@@ -7384,10 +7905,10 @@ function parseStagedPaths(output) {
     staged.set(`path:${normalizeSlashes3(parts[1])}`, `${status}:path`);
   }
   return [...staged.entries()].map(([encodedPath, encodedStatus]) => {
-    const [role, path25] = encodedPath.split(":", 2);
+    const [role, path26] = encodedPath.split(":", 2);
     const [status, entryRole] = encodedStatus.split(":", 2);
     return {
-      path: path25,
+      path: path26,
       status,
       role: entryRole || role || "path"
     };
@@ -7632,6 +8153,7 @@ function configureRootCommandSurface() {
     ["docs", "Workflow Policy Commands:"],
     ["detect", "Workflow Policy Commands:"],
     ["github", "Workflow Policy Commands:"],
+    ["workflow-stage", "Workflow Policy Commands:"],
     ["integrations", "Codex Integration Commands:"],
     ["commit-audit", "Codex Integration Commands:"],
     ["workflow-audit", "Codex Integration Commands:"]
@@ -7658,6 +8180,7 @@ configCommand(program);
 githubCommand(program);
 docsCommand(program);
 detectCommand(program);
+workflowStageCommand(program);
 integrationsCommand(program);
 workflowAuditCommand(program);
 commitAuditCommand(program);