lee-spec-kit 0.8.1 → 0.8.3

package/dist/index.js

@@ -8,7 +8,7 @@ import path8 from 'path';
 import prompts from 'prompts';
 import chalk from 'chalk';
 import { fileURLToPath } from 'url';
-import { spawn, spawnSync, execFileSync } from 'child_process';
+import { spawn, execFileSync, spawnSync } from 'child_process';
 import os from 'os';
 import { createHash } from 'crypto';
 
@@ -1288,18 +1288,24 @@ Before taking the next workflow step:
 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. 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
+5. If \`workflow-stage --json\` returns \`primaryActionLabel\` and \`actionOptions\`, treat \`primaryActionLabel\` as the default option label and present the exact \`actionOptions[*].reply\` tokens to the user before continuing
+6. Do not start implementation unless \`stage === "implementation"\` and \`implementationAllowed === true\`
+7. Treat stages before implementation as hard gates:
+   - spec approval plus plan / tasks readiness
    - 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
+   - task commit checkpoints after each completed task
+8. In standalone mode, keep the docs repo on its docs branch and do not create feature branches or worktrees there
+9. In standalone mode, use the project repo through its managed feature worktree under the shared workspace \`.worktrees/\` root instead of checking the feature branch out in the main project repo
+10. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
+11. 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
+- If \`workflow-stage --json\` returns labeled \`actionOptions\` at any approval boundary, keep the same option labels and exact \`reply\` tokens in the user prompt and do not improvise different reply formats
+- If \`workflow-stage --json\` reports \`nextAction.category === "task_commit"\`, make the docs commit and project commit for the just-finished task before starting the next task or moving to the next stage
 - 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
@@ -1431,6 +1437,38 @@ function resolveStandaloneProjectRoots(config, component) {
 function resolveGitTopLevelOrNull(cwd) {
   return runGitCapture(["rev-parse", "--show-toplevel"], cwd) || null;
 }
+function normalizeBranchNameForWorktree(branchName) {
+  return branchName.trim().replace(/[\\/]/g, "-");
+}
+function resolveStandaloneManagedWorktreeRoot(config, projectRoot) {
+  if (config.docsRepo !== "standalone") return null;
+  const workspaceRoot = resolveConfiguredStandaloneWorkspaceRoot(config);
+  if (!workspaceRoot) return null;
+  return path8.resolve(
+    workspaceRoot,
+    ".worktrees",
+    path8.basename(path8.resolve(projectRoot))
+  );
+}
+function resolveManagedWorktreePath(config, projectRoot, branchName) {
+  const standaloneRoot = resolveStandaloneManagedWorktreeRoot(config, projectRoot);
+  if (standaloneRoot) {
+    return path8.resolve(
+      standaloneRoot,
+      normalizeBranchNameForWorktree(branchName)
+    );
+  }
+  return path8.resolve(
+    path8.resolve(projectRoot),
+    ".worktrees",
+    normalizeBranchNameForWorktree(branchName)
+  );
+}
+function buildManagedWorktreeEnvLinkCommand(projectRoot, worktreePath) {
+  const sourceEnvPath = path8.resolve(projectRoot, ".env");
+  const targetEnvPath = path8.resolve(worktreePath, ".env");
+  return `if [ -f "${sourceEnvPath}" ] && [ ! -e "${targetEnvPath}" ] && [ ! -L "${targetEnvPath}" ]; then ln -s "${sourceEnvPath}" "${targetEnvPath}"; fi`;
+}
 
 // src/utils/init/options.ts
 function parseStandaloneMultiProjectRootJson(raw) {
@@ -2423,7 +2461,7 @@ async function runInit(options) {
         workflow: {
           preset: workflowMode,
           mode: workflowMode,
-          requireWorktree: false,
+          requireWorktree: docsRepo === "standalone",
           codeDirtyScope: "auto",
           taskCommitGate: "warn",
           auto: {
@@ -2551,7 +2589,7 @@ async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote, ext
       }
     };
     const toGitPath = (input) => input.replace(/\\/g, "/").replace(/^\.\//, "");
-    const toRepoRelativePath = (workdir, relativePath2) => {
+    const toRepoRelativePath2 = (workdir, relativePath2) => {
       if (relativePath2 === ".") return ".";
       try {
         const prefix = runGitOrThrow(["rev-parse", "--show-prefix"], workdir, {
@@ -2582,7 +2620,7 @@ async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote, ext
       return;
     }
     if (relativePath !== "." && isPathIgnored(gitWorkdir, relativePath)) {
-      const repoRelativePath = toRepoRelativePath(gitWorkdir, relativePath);
+      const repoRelativePath = toRepoRelativePath2(gitWorkdir, relativePath);
       console.log(
         chalk.yellow(
           tr(lang, "cli", "init.warn.docsPathIgnoredSkipCommit", {
@@ -3258,7 +3296,9 @@ function hasOwnKey(value, key) {
 }
 function isLegacyGeneratedApprovalConfig(approval) {
   const mode = typeof approval.mode === "string" ? approval.mode : "";
-  if (mode && mode !== "category" && mode !== "steps") return false;
+  if (mode && mode !== "category" && mode !== "steps" && mode !== "builtin") {
+    return false;
+  }
   const overrideKeys = [
     "default",
     "requireCheckSteps",
@@ -3514,7 +3554,16 @@ async function backfillMissingConfigDefaults(cwd, docsDir) {
   const inferredPreset = workflow.mode === "local" ? "local" : "github";
   setIfMissing(workflow, "preset", inferredPreset, "workflow.preset");
   setIfMissing(workflow, "mode", "github", "workflow.mode");
-  setIfMissing(workflow, "requireWorktree", false, "workflow.requireWorktree");
+  setIfMissing(
+    workflow,
+    "requireWorktree",
+    raw.docsRepo === "standalone",
+    "workflow.requireWorktree"
+  );
+  if (raw.docsRepo === "standalone" && workflow.requireWorktree !== true) {
+    workflow.requireWorktree = true;
+    changedPaths.push("workflow.requireWorktree");
+  }
   setIfMissing(workflow, "codeDirtyScope", "auto", "workflow.codeDirtyScope");
   setIfMissing(workflow, "taskCommitGate", "warn", "workflow.taskCommitGate");
   if (!isPlainObject(workflow.auto)) {
@@ -3927,6 +3976,7 @@ function runGhJson(args, cwd, messages) {
     );
   }
 }
+var BRANCH_LABELS = ["Branch", "\uBE0C\uB79C\uCE58"];
 function normalizeComponent(value) {
   const component = (value || "").trim().toLowerCase();
   return component || void 0;
@@ -3959,6 +4009,44 @@ function resolveProjectGitCwd(cwd, config, component) {
   }
   return resolveGitTopLevelOrNull(cwd) || resolveGitTopLevelOrNull(config.docsDir) || cwd;
 }
+function resolveProjectRootFromGitCwd(projectGitCwd) {
+  return resolveGitTopLevelOrNull(projectGitCwd) || path8.resolve(projectGitCwd);
+}
+async function resolveExistingManagedWorktreePath(config, projectGitCwd, slug, folderName, issueNumber, branchName) {
+  const projectRoot = resolveProjectRootFromGitCwd(projectGitCwd);
+  const branchCandidates = [
+    branchName,
+    issueNumber ? `feat/${issueNumber}-${slug}` : null,
+    issueNumber ? `feat/${issueNumber}-${folderName}` : null
+  ].filter((candidate) => !!candidate);
+  const candidates = [...new Set(branchCandidates)].map(
+    (candidate) => resolveManagedWorktreePath(config, projectRoot, candidate)
+  );
+  for (const candidate of candidates) {
+    if (await fs.pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  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 sanitizeMetadataValue(value) {
+  if (!value) return null;
+  const trimmed = value.trim().replace(/^`(.+)`$/, "$1");
+  if (!trimmed || trimmed === "-") return null;
+  return trimmed;
+}
 function toFeaturePathFromDocs(projectType, component, folderName) {
   return projectType === "multi" && component !== "single" ? path8.join("features", component, folderName) : path8.join("features", folderName);
 }
@@ -3971,6 +4059,12 @@ async function extractIssueNumber(featureDir) {
   const parsed = Number(match[1]);
   return Number.isFinite(parsed) ? parsed : void 0;
 }
+async function extractBranchName(featureDir) {
+  const tasksPath = path8.join(featureDir, "tasks.md");
+  if (!await fs.pathExists(tasksPath)) return null;
+  const content = await fs.readFile(tasksPath, "utf-8");
+  return sanitizeMetadataValue(extractFieldValue(content, BRANCH_LABELS));
+}
 async function listResolvedFeatures(cwd, config, component) {
   const refs = await listLeeSpecFeatures(cwd);
   const normalizedComponent = normalizeComponent(component);
@@ -3984,6 +4078,17 @@ async function listResolvedFeatures(cwd, config, component) {
         ref.folderName
       );
       const featureDir = path8.join(config.docsDir, featurePathFromDocs);
+      const issueNumber = await extractIssueNumber(featureDir);
+      const branchName = await extractBranchName(featureDir);
+      const projectGitCwdBase = resolveProjectGitCwd(cwd, config, type);
+      const worktreeProjectGitCwd = config.docsRepo === "standalone" && (issueNumber || branchName) ? await resolveExistingManagedWorktreePath(
+        config,
+        projectGitCwdBase,
+        ref.slug,
+        ref.folderName,
+        issueNumber,
+        branchName
+      ) : null;
       return {
         id: ref.id || ref.folderName.split("-")[0] || "",
         slug: ref.slug,
@@ -3995,9 +4100,9 @@ async function listResolvedFeatures(cwd, config, component) {
         },
         git: {
           docsGitCwd: config.docsDir,
-          projectGitCwd: resolveProjectGitCwd(cwd, config, type)
+          projectGitCwd: worktreeProjectGitCwd || projectGitCwdBase
         },
-        issueNumber: await extractIssueNumber(featureDir)
+        issueNumber
       };
     })
   );
@@ -4237,6 +4342,15 @@ function sanitizeDraftTitleValue(raw) {
   const normalized = value.replace(/`/g, "").replace(/\*\*(.*?)\*\*/g, "$1").replace(/\[(.*?)\]\((.*?)\)/g, "$1").replace(/\s+/g, " ").trim();
   return normalized || void 0;
 }
+function isPlaceholderWorkflowDraftTitle(raw, feature) {
+  const normalized = sanitizeDraftTitleValue(raw);
+  if (!normalized) return true;
+  const lowered = normalized.trim().toLowerCase();
+  const placeholders = new Set(
+    [feature.slug, feature.folderName].map((value) => (value || "").trim().toLowerCase()).filter(Boolean)
+  );
+  return placeholders.has(lowered);
+}
 function parseWorkflowDraftStatus(raw) {
   const value = (raw || "").trim();
   if (!value) return void 0;
@@ -4944,8 +5058,36 @@ function isOverviewMetadataLine(line, lang) {
   return keys.some((key) => cleaned.startsWith(`${key}:`));
 }
 function truncateIssueTitleSummary(input, maxLength = 72) {
-  if (input.length <= maxLength) return input;
-  return `${input.slice(0, maxLength - 3).trimEnd()}...`;
+  const normalized = input.trim().replace(/\s+/g, " ");
+  if (normalized.length <= maxLength) return normalized;
+  const stripTrailingPunctuation = (value) => value.trim().replace(/[.!?。]+$/u, "").trim();
+  const rewriteVerboseEnding = (value) => stripTrailingPunctuation(value).replace(/공통화하고/gu, "\uACF5\uD1B5\uD654\uC640").replace(/줄인다$/u, "\uAC10\uC18C").replace(/강화한다$/u, "\uAC15\uD654").replace(/개선한다$/u, "\uAC1C\uC120").replace(/복구한다$/u, "\uBCF5\uAD6C").replace(/정리한다$/u, "\uC815\uB9AC").replace(/도입한다$/u, "\uB3C4\uC785").replace(/구현한다$/u, "\uAD6C\uD604");
+  const addCandidate = (bucket, seen2, value) => {
+    const cleaned = stripTrailingPunctuation(value);
+    if (!cleaned || seen2.has(cleaned)) return;
+    seen2.add(cleaned);
+    bucket.push(cleaned);
+  };
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  addCandidate(candidates, seen, normalized);
+  const commaStripped = normalized.replace(/^[^,，]+[,，]\s*/u, "");
+  addCandidate(candidates, seen, commaStripped);
+  const purposeLeadStripped = normalized.replace(/^.+?(?:하도록|하기 위해),\s*/u, "");
+  addCandidate(candidates, seen, purposeLeadStripped);
+  for (const base of [...candidates]) {
+    addCandidate(candidates, seen, rewriteVerboseEnding(base));
+  }
+  for (const base of [...candidates]) {
+    for (const part of base.split(/[,:;，；]/u)) {
+      addCandidate(candidates, seen, part);
+    }
+  }
+  const fitting = candidates.filter((candidate) => candidate.length <= maxLength);
+  if (fitting.length > 0) {
+    return fitting.sort((left, right) => right.length - left.length)[0];
+  }
+  return stripTrailingPunctuation(normalized.slice(0, maxLength));
 }
 function resolveIssueTitleSummary(overview, feature, lang) {
   const candidates = overview.split("\n").map((line) => normalizeIssueTitleSummaryLine(line)).filter((line) => !!line).filter((line) => !isOverviewMetadataLine(line, lang));
@@ -5392,7 +5534,7 @@ function syncTasksIssueMetadata(tasksPath, issueNumber, lang) {
   }
   return { changed, path: tasksPath };
 }
-function syncIssueDraftMetadata(issueDocPath, issueNumber) {
+function syncIssueDraftMetadata(issueDocPath, issueNumber, title) {
   if (!fs.existsSync(issueDocPath)) {
     return { changed: false, path: issueDocPath };
   }
@@ -5412,6 +5554,16 @@ function syncIssueDraftMetadata(issueDocPath, issueNumber) {
     next = inserted.content;
     changed = changed || inserted.changed;
   }
+  const normalizedTitle = sanitizeDraftTitleValue(title);
+  if (normalizedTitle) {
+    const titleReplaced = replaceListField(
+      next,
+      ["Title", "\uC81C\uBAA9"],
+      normalizedTitle
+    );
+    next = titleReplaced.content;
+    changed = changed || titleReplaced.changed;
+  }
   if (changed) {
     fs.writeFileSync(issueDocPath, next, "utf-8");
   }
@@ -5456,7 +5608,7 @@ function syncTasksPrMetadata(tasksPath, prUrl, nextStatus, lang) {
   }
   return { changed, path: tasksPath };
 }
-function syncPrDraftMetadata(prDocPath, prUrl, nextStatus) {
+function syncPrDraftMetadata(prDocPath, prUrl, nextStatus, title) {
   if (!fs.existsSync(prDocPath)) {
     return { changed: false, path: prDocPath };
   }
@@ -5483,6 +5635,17 @@ function syncPrDraftMetadata(prDocPath, prUrl, nextStatus) {
     next = inserted.content;
     changed = changed || inserted.changed;
   }
+  const normalizedTitle = sanitizeDraftTitleValue(title);
+  if (normalizedTitle) {
+    const titleReplaced = replaceListField(next, ["Title", "\uC81C\uBAA9"], normalizedTitle);
+    next = titleReplaced.content;
+    changed = changed || titleReplaced.changed;
+    if (!titleReplaced.found) {
+      const inserted = insertFieldInMetadataSection(next, "Title", normalizedTitle);
+      next = inserted.content;
+      changed = changed || inserted.changed;
+    }
+  }
   if (changed) {
     fs.writeFileSync(prDocPath, next, "utf-8");
   }
@@ -5777,7 +5940,10 @@ function githubCommand(program2) {
           await fs.writeFile(sanitizedBodyFile, body, "utf-8");
           bodyFile = sanitizedBodyFile;
         }
-        const title = options.title?.trim() || (preparedBody.source === "workflow-ready" ? preparedBody.draftMetadata?.title : void 0) || defaultTitle;
+        const title = options.title?.trim() || (preparedBody.source === "workflow-ready" && !isPlaceholderWorkflowDraftTitle(
+          preparedBody.draftMetadata?.title,
+          feature
+        ) ? preparedBody.draftMetadata?.title : void 0) || defaultTitle;
         const labels = parseLabels(
           optionLabels || (preparedBody.source === "workflow-ready" ? preparedBody.draftMetadata?.labels : void 0),
           config.lang
@@ -5828,7 +5994,8 @@ function githubCommand(program2) {
             );
             const draftSynced = syncIssueDraftMetadata(
               path8.join(config.docsDir, paths.issuePath),
-              syncedIssueNumber
+              syncedIssueNumber,
+              title
             );
             syncChanged = synced.changed || draftSynced.changed;
           }
@@ -6013,7 +6180,8 @@ function githubCommand(program2) {
           await fs.writeFile(sanitizedBodyFile, body, "utf-8");
           bodyFile = sanitizedBodyFile;
         }
-        const title = options.title?.trim() || (preparedBody.source === "workflow-ready" ? preparedBody.draftMetadata?.title : void 0) || defaultTitle;
+        const requestedTitle = options.title?.trim() || (preparedBody.source === "workflow-ready" ? preparedBody.draftMetadata?.title : void 0) || "";
+        let title = requestedTitle || defaultTitle;
         const labels = parseLabels(
           optionLabels || (preparedBody.source === "workflow-ready" ? preparedBody.draftMetadata?.labels : void 0),
           config.lang
@@ -6023,7 +6191,6 @@ function githubCommand(program2) {
         let prUrl = options.pr?.trim() || "";
         let mergedAttempts;
         let mergeAlreadyMerged;
-        const postMergeWarnings = [];
         let syncChanged = false;
         const pushDocsSync = shouldPushDocsSync(config);
         if (options.create) {
@@ -6036,11 +6203,18 @@ function githubCommand(program2) {
             feature.issueNumber ? String(feature.issueNumber) : void 0,
             config.lang
           );
+          title = closingIssueNumber && closingIssueNumber.trim() ? defaultTitle : requestedTitle || defaultTitle;
           assertRemoteIssueExists(
             closingIssueNumber,
             projectGitCwd,
             config.lang
           );
+          if (closingIssueNumber && options.title?.trim() && options.title.trim() !== defaultTitle) {
+            throw createCliError(
+              "PRECONDITION_FAILED",
+              `PR title must follow the existing convention: "${defaultTitle}".`
+            );
+          }
           const normalizedBody = ensureIssueClosingLine(
             body,
             closingIssueNumber
@@ -6116,7 +6290,8 @@ function githubCommand(program2) {
           const syncedDraft = syncPrDraftMetadata(
             path8.join(config.docsDir, paths.prPath),
             prUrl,
-            "Review"
+            "Review",
+            title
           );
           syncChanged = syncedTasks.changed || syncedDraft.changed;
           const shouldCommitSync = !!options.commitSync || !!options.merge;
@@ -6186,34 +6361,6 @@ function githubCommand(program2) {
               );
             }
           }
-          const mergeBaseBranch = (merged.baseRefName || baseBranch || "main").trim();
-          const checkoutResult = runProcess(
-            "git",
-            ["checkout", mergeBaseBranch],
-            projectGitCwd
-          );
-          if (checkoutResult.code !== 0) {
-            postMergeWarnings.push(
-              tg(config.lang, "postMergeCheckoutWarning", {
-                base: mergeBaseBranch,
-                detail: (checkoutResult.stderr || checkoutResult.stdout || "").trim()
-              })
-            );
-          } else {
-            const pullResult = runProcess(
-              "git",
-              ["pull", "--rebase", "origin", mergeBaseBranch],
-              projectGitCwd
-            );
-            if (pullResult.code !== 0) {
-              postMergeWarnings.push(
-                tg(config.lang, "postMergePullWarning", {
-                  base: mergeBaseBranch,
-                  detail: (pullResult.stderr || pullResult.stdout || "").trim()
-                })
-              );
-            }
-          }
         }
         if (options.json) {
           console.log(
@@ -6235,8 +6382,7 @@ function githubCommand(program2) {
                 syncChanged,
                 merged: !!options.merge,
                 mergeAttempts: mergedAttempts,
-                mergeAlreadyMerged,
-                postMergeWarnings: postMergeWarnings.length > 0 ? postMergeWarnings : void 0
+                mergeAlreadyMerged
               },
               null,
               2
@@ -6284,9 +6430,6 @@ function githubCommand(program2) {
               chalk.yellow(tg(config.lang, "prAlreadyMergedNotice"))
             );
           }
-          for (const warning of postMergeWarnings) {
-            console.log(chalk.yellow(`\u26A0\uFE0F  ${warning}`));
-          }
         } else if (!options.create) {
           console.log(
             chalk.blue(tg(config.lang, "prTemplateGenerated"))
@@ -6781,7 +6924,7 @@ function registerCodexHooksIntegration(parent) {
         removeLeeSpecKitCodexHooks,
         resolveCodexHooksRepoRoot,
         upsertLeeSpecKitCodexHooks
-      } = await import('./hooks-4S33YUIB.js');
+      } = await import('./hooks-B5UIIZYN.js');
       const repoRoot = config.docsRepo === "standalone" ? resolveConfiguredStandaloneWorkspaceRoot(config) : resolveCodexHooksRepoRoot(process.cwd());
       if (!repoRoot) {
         throw createCliError(
@@ -6816,9 +6959,27 @@ function integrationsCommand(program2) {
   registerCodexIntegration(integrations);
   registerCodexHooksIntegration(integrations);
 }
+var LEGACY_STEP_BY_ACTION = {
+  spec_write: 2,
+  spec_approve: 3,
+  plan_write: 4,
+  plan_approve: 5,
+  tasks_write: 6,
+  tasks_approve: 6,
+  issue_prepare: 8,
+  issue_create: 8,
+  branch_create: 9,
+  task_execute: 10,
+  implementation_approve: 10,
+  pre_pr_review: 12,
+  pr_prepare: 13,
+  pr_create: 13,
+  code_review: 14,
+  pr_merge: 14
+};
 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 BRANCH_LABELS2 = ["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"];
@@ -6831,6 +6992,7 @@ function resolveWorkflowRequirements(config) {
   return {
     requireIssue: workflow.requireIssue ?? !isLocalWorkflow,
     requireBranch: workflow.requireBranch ?? true,
+    requireWorktree: config.docsRepo === "standalone" ? true : workflow.requireWorktree ?? false,
     requirePr: workflow.requirePr ?? !isLocalWorkflow,
     requireReview: workflow.requireReview ?? !isLocalWorkflow,
     requireMerge: workflow.requireMerge ?? !isLocalWorkflow,
@@ -6844,7 +7006,7 @@ function parseApprovalStatus(raw) {
   if (value === "approved") return "approved";
   return null;
 }
-function extractFieldValue(content, labels) {
+function extractFieldValue2(content, labels) {
   for (const label of Array.isArray(labels) ? labels : [labels]) {
     const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const match = content.match(
@@ -6876,12 +7038,12 @@ function withoutFencedCodeBlocks(content) {
   return lines;
 }
 function parseTasksDoc(content) {
-  const issueRaw = extractFieldValue(content, ISSUE_LABELS);
+  const issueRaw = extractFieldValue2(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 branchRaw = extractFieldValue2(content, BRANCH_LABELS2);
+  const prRaw = extractFieldValue2(content, PR_LABELS);
+  const prePrDecision = extractFieldValue2(content, PRE_PR_DECISION_LABELS);
   const tasks = [];
   const nonCodeLines = withoutFencedCodeBlocks(content);
   for (const line of nonCodeLines) {
@@ -6907,13 +7069,13 @@ function parseTasksDoc(content) {
     ) && parseMarkdownCheckbox(line) === true
   );
   const prStatus = (() => {
-    const value = (extractFieldValue(content, PR_STATUS_LABELS) || "").trim().toLowerCase();
+    const value = (extractFieldValue2(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();
+    const value = (extractFieldValue2(content, PRE_PR_REVIEW_LABELS) || "").trim().toLowerCase();
     if (value === "pending") return "pending";
     if (value === "running") return "running";
     if (value === "done") return "done";
@@ -6926,17 +7088,17 @@ function parseTasksDoc(content) {
   })();
   return {
     docStatus: parseApprovalStatus(
-      extractFieldValue(content, DOC_STATUS_LABELS) || void 0
+      extractFieldValue2(content, DOC_STATUS_LABELS) || void 0
     ),
     issueNumber,
-    branch: sanitizeMetadataValue(branchRaw),
-    prLink: sanitizeMetadataValue(prRaw),
+    branch: sanitizeMetadataValue2(branchRaw),
+    prLink: sanitizeMetadataValue2(prRaw),
     prStatus,
     prePrReviewStatus,
-    prePrEvidence: sanitizeMetadataValue(
-      extractFieldValue(content, PRE_PR_EVIDENCE_LABELS)
+    prePrEvidence: sanitizeMetadataValue2(
+      extractFieldValue2(content, PRE_PR_EVIDENCE_LABELS)
     ),
-    prePrDecision: sanitizeMetadataValue(prePrDecision),
+    prePrDecision: sanitizeMetadataValue2(prePrDecision),
     prePrDecisionOutcome,
     tasks,
     completion: {
@@ -6946,20 +7108,245 @@ function parseTasksDoc(content) {
     }
   };
 }
-function sanitizeMetadataValue(value) {
+function sanitizeMetadataValue2(value) {
   if (!value) return null;
   const trimmed = value.trim().replace(/^`(.+)`$/, "$1");
   if (!trimmed || trimmed === "-") return null;
   return trimmed;
 }
+function normalizeCommitTopicText(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function normalizeTaskTopic(value) {
+  return normalizeCommitTopicText(value).replace(/^T-[A-Za-z0-9-]+\s+/, "");
+}
+function normalizeCommitSubjectForGate(value) {
+  return normalizeCommitTopicText(value).replace(/^[a-z]+(?:\([^)]*\))?!?:\s*/i, "").toLowerCase();
+}
+function toTaskKey(rawTitle) {
+  const trimmed = normalizeCommitTopicText(rawTitle);
+  if (!trimmed) return "";
+  const idMatch = trimmed.match(/^(T-[A-Za-z0-9-]+)/i);
+  if (idMatch) return idMatch[1].toUpperCase();
+  return normalizeTaskTopic(trimmed).toLowerCase();
+}
+function normalizeGitRelativePath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+function toRepoRelativePath(cwd, relativePathFromCwd) {
+  const prefix = (runGitCapture(["rev-parse", "--show-prefix"], cwd) || "").trim().replace(/\/+$/, "");
+  if (!prefix) return normalizeGitRelativePath(relativePathFromCwd);
+  return normalizeGitRelativePath(`${prefix}/${relativePathFromCwd}`);
+}
+function parseDoneTransitionsFromDiff(diff) {
+  const removedByTask = /* @__PURE__ */ new Map();
+  const addedByTask = /* @__PURE__ */ new Map();
+  const parseTaskDiffLine = (line) => {
+    const match = line.match(
+      /^\s*-\s*\[(TODO|DOING|DONE|REVIEW)\](?:\[[^\]]+\])*\s+(.+?)\s*$/i
+    );
+    if (!match) return null;
+    const key = toTaskKey(match[2]);
+    if (!key) return null;
+    return {
+      key,
+      status: match[1].toUpperCase()
+    };
+  };
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("---") || line.startsWith("+++")) continue;
+    if (line.startsWith("-")) {
+      const parsed = parseTaskDiffLine(line.slice(1));
+      if (!parsed) continue;
+      const existing = removedByTask.get(parsed.key) || /* @__PURE__ */ new Set();
+      existing.add(parsed.status);
+      removedByTask.set(parsed.key, existing);
+      continue;
+    }
+    if (line.startsWith("+")) {
+      const parsed = parseTaskDiffLine(line.slice(1));
+      if (!parsed) continue;
+      const existing = addedByTask.get(parsed.key) || /* @__PURE__ */ new Set();
+      existing.add(parsed.status);
+      addedByTask.set(parsed.key, existing);
+    }
+  }
+  let doneTransitions = 0;
+  for (const [taskKey, addedStatuses] of addedByTask.entries()) {
+    if (!addedStatuses.has("DONE")) continue;
+    const removedStatuses = removedByTask.get(taskKey);
+    if (!removedStatuses) continue;
+    if (removedStatuses.has("TODO") || removedStatuses.has("DOING") || removedStatuses.has("REVIEW")) {
+      doneTransitions += 1;
+    }
+  }
+  return doneTransitions;
+}
+function parseDoneTaskTopicCounts(content) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const line of withoutFencedCodeBlocks(content)) {
+    const match = line.match(
+      /^\s*-\s*\[(DONE)\](?:\[[^\]]+\])*\s+(.+?)\s*$/i
+    );
+    if (!match) continue;
+    const topic = normalizeTaskTopic(match[2] || "");
+    if (!topic) continue;
+    counts.set(topic, (counts.get(topic) || 0) + 1);
+  }
+  return counts;
+}
+function countDoneTransitionsInLatestTasksCommit(feature) {
+  const docsGitCwd = feature.git.docsGitCwd;
+  const tasksRelativePathFromDocs = normalizeGitRelativePath(
+    path8.join(feature.docs.featurePathFromDocs, "tasks.md")
+  );
+  const latestTasksCommit = (runGitCapture(
+    ["rev-list", "-n", "1", "HEAD", "--", tasksRelativePathFromDocs],
+    docsGitCwd
+  ) || "").trim();
+  if (!latestTasksCommit) return void 0;
+  const repoTasksPath = toRepoRelativePath(docsGitCwd, tasksRelativePathFromDocs);
+  const currentContent = runGitCapture(
+    ["show", `${latestTasksCommit}:${repoTasksPath}`],
+    docsGitCwd
+  );
+  if (currentContent === void 0) return void 0;
+  const previousContent = runGitCapture(["show", `${latestTasksCommit}^:${repoTasksPath}`], docsGitCwd) || "";
+  const currentDone = parseDoneTaskTopicCounts(currentContent);
+  const previousDone = parseDoneTaskTopicCounts(previousContent);
+  let doneTransitions = 0;
+  for (const [topic, currentCount] of currentDone.entries()) {
+    const previousCount = previousDone.get(topic) || 0;
+    if (currentCount > previousCount) {
+      doneTransitions += currentCount - previousCount;
+    }
+  }
+  return doneTransitions;
+}
+function countPendingDoneTransitions(feature) {
+  const docsGitCwd = feature.git.docsGitCwd;
+  const tasksRelativePath = normalizeGitRelativePath(
+    path8.join(feature.docs.featurePathFromDocs, "tasks.md")
+  );
+  const diff = runGitCapture(
+    ["diff", "--unified=0", "--no-color", "HEAD", "--", tasksRelativePath],
+    docsGitCwd
+  ) || "";
+  if (!diff.trim()) return 0;
+  return parseDoneTransitionsFromDiff(diff);
+}
+function getLastDoneTask(tasks) {
+  for (let index = tasks.tasks.length - 1; index >= 0; index -= 1) {
+    if (tasks.tasks[index].status === "DONE") return tasks.tasks[index];
+  }
+  return null;
+}
+function hasOpenTask(tasks) {
+  return tasks.tasks.some(
+    (task) => task.status === "DOING" || task.status === "REVIEW"
+  );
+}
+function hasUncommittedChanges(gitCwd) {
+  if (!gitCwd) return false;
+  const status = runGitCapture(
+    ["status", "--porcelain", "--untracked-files=no"],
+    gitCwd
+  ) || "";
+  return status.trim().length > 0;
+}
+function resolveTaskCommitGatePolicy(config) {
+  const raw = config.workflow?.taskCommitGate;
+  return raw === "off" || raw === "strict" ? raw : "warn";
+}
+function checkTaskCommitGate(feature, effectiveProjectGitCwd, lastDoneTask) {
+  const doneTransitions = countDoneTransitionsInLatestTasksCommit(feature);
+  if (doneTransitions === 0) {
+    return { pass: true, doneTransitions };
+  }
+  if (typeof doneTransitions === "number" && doneTransitions > 1) {
+    return {
+      pass: false,
+      reason: "DONE_TRANSITIONS_COUNT",
+      doneTransitions
+    };
+  }
+  const lastDoneTopic = normalizeTaskTopic(lastDoneTask?.title || "");
+  if (!effectiveProjectGitCwd || !lastDoneTopic) {
+    return { pass: true };
+  }
+  const args = ["log", "-n", "1", "--pretty=%s", "--", "."];
+  const relativeDocsDir = path8.relative(
+    effectiveProjectGitCwd,
+    feature.git.docsGitCwd
+  );
+  const normalizedDocsDir = normalizeGitRelativePath(relativeDocsDir);
+  if (normalizedDocsDir && normalizedDocsDir !== "." && normalizedDocsDir !== ".." && !normalizedDocsDir.startsWith("../")) {
+    args.push(`:(exclude)${normalizedDocsDir}/**`);
+  }
+  const latestProjectSubject = runGitCapture(args, effectiveProjectGitCwd);
+  if (latestProjectSubject === void 0) {
+    return { pass: false, reason: "PROJECT_LOG_UNAVAILABLE" };
+  }
+  const normalizedSubject = normalizeCommitSubjectForGate(latestProjectSubject);
+  if (!normalizedSubject) {
+    return { pass: false, reason: "NO_PROJECT_COMMIT" };
+  }
+  if (!normalizedSubject.includes(normalizeTaskTopic(lastDoneTopic).toLowerCase())) {
+    return { pass: false, reason: "MISMATCH_LAST_DONE" };
+  }
+  return { pass: true };
+}
+function describeTaskCommitGateFailure(check) {
+  switch (check.reason) {
+    case "DONE_TRANSITIONS_COUNT":
+      return `latest tasks.md commit includes ${check.doneTransitions || 0} DONE transitions`;
+    case "NO_PROJECT_COMMIT":
+      return "no recent project code commit was found for the just-finished task";
+    case "PROJECT_LOG_UNAVAILABLE":
+      return "the latest project commit subject could not be inspected";
+    case "MISMATCH_LAST_DONE":
+    default:
+      return "the latest project commit subject does not match the just-finished task";
+  }
+}
+function resolveProjectCommitTopic(feature, tasks) {
+  const activeTask = tasks.tasks.find(
+    (task) => task.status === "DOING" || task.status === "REVIEW"
+  );
+  const raw = activeTask?.title || getLastDoneTask(tasks)?.title || nextTodoTask(tasks)?.title || feature.folderName;
+  const withoutTaskId = normalizeCommitTopicText(raw || "").replace(
+    /^T-[A-Za-z0-9-]+\s+/,
+    ""
+  );
+  return withoutTaskId || feature.folderName;
+}
+function buildTaskCommitSummary(input) {
+  const { feature, tasks, effectiveProjectGitCwd, docsDirty, projectDirty, gateFailureReason } = input;
+  const docsMessage = tasks.issueNumber ? `git -C "${feature.git.docsGitCwd}" add "${feature.docs.featurePathFromDocs}" && git -C "${feature.git.docsGitCwd}" commit -m "docs(#${tasks.issueNumber}): ${feature.folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"` : `git -C "${feature.git.docsGitCwd}" add "${feature.docs.featurePathFromDocs}" && git -C "${feature.git.docsGitCwd}" commit -m "docs: ${feature.folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"`;
+  const projectMessage = tasks.issueNumber ? `Stage only the files touched by the just-finished task in "${effectiveProjectGitCwd}", then commit with: git -C "${effectiveProjectGitCwd}" commit -m "feat(#${tasks.issueNumber}): ${resolveProjectCommitTopic(feature, tasks)}"` : `Stage only the files touched by the just-finished task in "${effectiveProjectGitCwd}", then commit with: git -C "${effectiveProjectGitCwd}" commit -m "feat(${feature.folderName}): ${resolveProjectCommitTopic(feature, tasks)}"`;
+  const lines = ["Finish the task-level commit checkpoint before continuing."];
+  if (gateFailureReason) {
+    lines.push(`Current gate failure: ${gateFailureReason}`);
+  }
+  if (docsDirty) {
+    lines.push(`Docs commit: ${docsMessage}`);
+  }
+  if (projectDirty) {
+    lines.push(`Project commit: ${projectMessage}`);
+  }
+  if (!docsDirty && !projectDirty) {
+    lines.push(`Re-check the last task commits. Docs commit should contain exactly one DONE transition, and the latest project commit should match "${normalizeTaskTopic(getLastDoneTask(tasks)?.title || "")}".`);
+  }
+  return lines.join("\n");
+}
 function parseWorkflowDraftMetadataExtended(content) {
   const metadata = parseWorkflowDraftMetadata(content);
-  const prStatusRaw = extractFieldValue(content, PR_STATUS_LABELS);
+  const prStatusRaw = extractFieldValue2(content, PR_STATUS_LABELS);
   const normalizedPrStatus = (prStatusRaw || "").trim().toLowerCase();
   return {
     ...metadata,
-    issueRef: sanitizeMetadataValue(extractFieldValue(content, ISSUE_LABELS)),
-    prRef: sanitizeMetadataValue(extractFieldValue(content, PR_LABELS)),
+    issueRef: sanitizeMetadataValue2(extractFieldValue2(content, ISSUE_LABELS)),
+    prRef: sanitizeMetadataValue2(extractFieldValue2(content, PR_LABELS)),
     prStatus: normalizedPrStatus === "review" ? "review" : normalizedPrStatus === "approved" ? "approved" : null
   };
 }
@@ -6978,8 +7365,164 @@ function resolveExpectedBranch(feature, tasks) {
   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 resolveProjectRootFromGitCwd2(projectGitCwd) {
+  return runGitCapture(["rev-parse", "--show-toplevel"], projectGitCwd) || path8.resolve(projectGitCwd);
+}
+function resolveProjectRootGitCwd(config, feature) {
+  if (config.docsRepo === "standalone") {
+    const roots = resolveStandaloneProjectRoots(
+      config,
+      feature.type === "single" ? void 0 : feature.type
+    );
+    if (roots.length > 0) {
+      return roots[0];
+    }
+  }
+  return resolveProjectRootFromGitCwd2(feature.git.projectGitCwd);
+}
+function getExpectedWorktreePath(config, projectGitCwd, branchName) {
+  const projectRoot = resolveProjectRootFromGitCwd2(projectGitCwd);
+  return resolveManagedWorktreePath(config, projectRoot, branchName);
+}
+async function resolveExistingExpectedWorktreePath(config, projectGitCwd, branchName) {
+  const candidate = getExpectedWorktreePath(config, projectGitCwd, branchName);
+  return await fs.pathExists(candidate) ? candidate : null;
+}
+function buildManagedWorktreeCreateCommand(config, projectGitCwd, branchName) {
+  const projectRoot = resolveProjectRootFromGitCwd2(projectGitCwd);
+  const worktreePath = getExpectedWorktreePath(config, projectGitCwd, branchName);
+  const worktreeParent = path8.dirname(worktreePath);
+  const envLinkCommand = buildManagedWorktreeEnvLinkCommand(projectRoot, worktreePath);
+  return `mkdir -p "${worktreeParent}" && (git -C "${projectRoot}" worktree add "${worktreePath}" "${branchName}" || git -C "${projectRoot}" worktree add -b "${branchName}" "${worktreePath}") && ${envLinkCommand}`;
+}
+function resolveRemotePrMergeMeta(prRef, projectGitCwd) {
+  if (!prRef) return null;
+  const result = runProcess(
+    "gh",
+    ["pr", "view", prRef, "--json", "headRefName,baseRefName"],
+    projectGitCwd
+  );
+  if (result.code !== 0) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(String(result.stdout || "{}"));
+    return {
+      headRefName: sanitizeMetadataValue2(String(parsed.headRefName || "")),
+      baseRefName: sanitizeMetadataValue2(String(parsed.baseRefName || ""))
+    };
+  } catch {
+    return null;
+  }
+}
+function localBranchExists(cwd, branchName) {
+  if (!branchName) return false;
+  return runProcess(
+    "git",
+    ["show-ref", "--verify", "--quiet", `refs/heads/${branchName}`],
+    cwd
+  ).code === 0;
+}
+function remoteBranchExists(cwd, branchName) {
+  if (!branchName) return false;
+  return runProcess(
+    "git",
+    ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${branchName}`],
+    cwd
+  ).code === 0;
+}
+function resolvePostMergeCleanupState(config, feature, tasks) {
+  const projectRootGitCwd = resolveProjectRootGitCwd(config, feature);
+  const prMeta = resolveRemotePrMergeMeta(tasks.prLink, projectRootGitCwd);
+  const baseBranch = (prMeta?.baseRefName || "main").trim() || "main";
+  const headBranch = (prMeta?.headRefName || resolveExpectedBranch(feature, tasks))?.trim() || null;
+  const hasOriginRemote = runProcess(
+    "git",
+    ["remote", "get-url", "origin"],
+    projectRootGitCwd
+  ).code === 0;
+  if (hasOriginRemote) {
+    runProcess("git", ["fetch", "--prune", "origin"], projectRootGitCwd);
+  }
+  const currentBranch = runGitCapture(["branch", "--show-current"], projectRootGitCwd) || runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], projectRootGitCwd) || "";
+  const localBaseSha = runGitCapture(["rev-parse", baseBranch], projectRootGitCwd) || "";
+  const remoteBaseSha = hasOriginRemote ? runGitCapture(["rev-parse", `origin/${baseBranch}`], projectRootGitCwd) || "" : "";
+  const worktreePath = config.docsRepo === "standalone" && headBranch ? resolveManagedWorktreePath(config, projectRootGitCwd, headBranch) : null;
+  const managedWorktreeExists = !!worktreePath && fs.existsSync(worktreePath);
+  const localFeatureBranchExists = localBranchExists(projectRootGitCwd, headBranch);
+  const remoteFeatureBranchExists = hasOriginRemote && remoteBranchExists(projectRootGitCwd, headBranch);
+  const localBaseCheckedOut = currentBranch === baseBranch;
+  const baseSyncedWithOrigin = !hasOriginRemote || localBaseSha.length > 0 && remoteBaseSha.length > 0 && localBaseSha === remoteBaseSha;
+  return {
+    complete: localBaseCheckedOut && baseSyncedWithOrigin && !localFeatureBranchExists && !remoteFeatureBranchExists && !managedWorktreeExists,
+    projectRootGitCwd,
+    baseBranch,
+    headBranch,
+    worktreePath,
+    hasOriginRemote,
+    localBaseCheckedOut,
+    baseSyncedWithOrigin,
+    localFeatureBranchExists,
+    remoteFeatureBranchExists,
+    managedWorktreeExists
+  };
+}
+function buildPostMergeCleanupCommand(state) {
+  const commandParts = [];
+  if (state.hasOriginRemote) {
+    commandParts.push(
+      `git -C "${state.projectRootGitCwd}" fetch --prune origin`
+    );
+  }
+  commandParts.push(
+    `git -C "${state.projectRootGitCwd}" checkout "${state.baseBranch}"`
+  );
+  if (state.hasOriginRemote) {
+    commandParts.push(
+      `git -C "${state.projectRootGitCwd}" pull --ff-only origin "${state.baseBranch}"`
+    );
+  }
+  if (state.worktreePath) {
+    commandParts.push(
+      `if [ -d "${state.worktreePath}" ]; then git -C "${state.projectRootGitCwd}" worktree remove "${state.worktreePath}"; fi`
+    );
+  }
+  if (state.headBranch) {
+    commandParts.push(
+      `if git -C "${state.projectRootGitCwd}" show-ref --verify --quiet "refs/heads/${state.headBranch}"; then git -C "${state.projectRootGitCwd}" branch -D "${state.headBranch}"; fi`
+    );
+    if (state.hasOriginRemote) {
+      commandParts.push(
+        `if git -C "${state.projectRootGitCwd}" show-ref --verify --quiet "refs/remotes/origin/${state.headBranch}"; then git -C "${state.projectRootGitCwd}" push origin --delete "${state.headBranch}"; fi`
+      );
+      commandParts.push(
+        `git -C "${state.projectRootGitCwd}" fetch --prune origin`
+      );
+    }
+  }
+  return commandParts.join(" && ");
+}
+function buildPostMergeCleanupSummary(state) {
+  const remaining = [];
+  if (!state.localBaseCheckedOut) {
+    remaining.push(`check out ${state.baseBranch}`);
+  }
+  if (!state.baseSyncedWithOrigin) {
+    remaining.push(`sync ${state.baseBranch} with origin/${state.baseBranch}`);
+  }
+  if (state.managedWorktreeExists) {
+    remaining.push("remove the managed feature worktree");
+  }
+  if (state.localFeatureBranchExists) {
+    remaining.push("delete the local feature branch");
+  }
+  if (state.remoteFeatureBranchExists) {
+    remaining.push("delete the remote feature branch");
+  }
+  if (remaining.length === 0) {
+    return "Finish the post-merge cleanup before closing the feature.";
+  }
+  return `Finish the post-merge cleanup before closing the feature: ${remaining.join(", ")}.`;
 }
 function nextTodoTask(tasks) {
   return tasks.tasks.find((task) => task.status === "DOING") || tasks.tasks.find((task) => task.status === "TODO") || null;
@@ -7016,6 +7559,292 @@ function buildAction(category, summary, approvalRequired, command = null) {
     command
   };
 }
+function buildStageOption(label, reply, category, summary, command = null) {
+  return {
+    label,
+    reply,
+    category,
+    summary,
+    command
+  };
+}
+function normalizeApprovalToken(value) {
+  return (value ?? "").trim().toLowerCase();
+}
+function resolveActionApprovalRequired(config, category, builtinRequiresUserCheck) {
+  const approval = config.approval?.mode === "builtin" ? createDefaultApprovalConfig() : config.approval ?? createDefaultApprovalConfig();
+  const mode = approval.mode ?? "category";
+  if (mode === "steps") {
+    const requiredSteps = new Set(
+      (approval.requireCheckSteps ?? []).map((value) => typeof value === "number" ? value : Number(value)).filter((value) => Number.isFinite(value))
+    );
+    const legacyStep = LEGACY_STEP_BY_ACTION[category];
+    return typeof legacyStep === "number" ? requiredSteps.has(legacyStep) : builtinRequiresUserCheck;
+  }
+  const requiredCategories = new Set(
+    (approval.requireCheckCategories ?? []).map((value) => normalizeApprovalToken(value)).filter(Boolean)
+  );
+  const skippedCategories = new Set(
+    (approval.skipCheckCategories ?? []).map((value) => normalizeApprovalToken(value)).filter(Boolean)
+  );
+  const defaultPolicy = approval.default ?? createDefaultApprovalConfig().default ?? "skip";
+  const normalizedCategory = normalizeApprovalToken(category);
+  const explicitlyRequired = requiredCategories.has("*") || requiredCategories.has(normalizedCategory);
+  if (explicitlyRequired) return true;
+  if (skippedCategories.has("*") || skippedCategories.has(normalizedCategory)) {
+    return false;
+  }
+  if (defaultPolicy === "require") return true;
+  if (defaultPolicy === "skip") return false;
+  return builtinRequiresUserCheck;
+}
+function resolveRemotePrReviewState(prRef, feature) {
+  if (!prRef) return "unknown";
+  const result = runProcess(
+    "gh",
+    [
+      "pr",
+      "view",
+      prRef,
+      "--json",
+      "reviewDecision,state,mergedAt,mergeStateStatus,isDraft,headRefOid,latestReviews,comments,statusCheckRollup"
+    ],
+    feature.git.projectGitCwd
+  );
+  if (result.code !== 0) {
+    return "unknown";
+  }
+  try {
+    const parsed = JSON.parse(String(result.stdout || "{}"));
+    const reviewDecision = String(parsed.reviewDecision || "").trim().toUpperCase();
+    const state = String(parsed.state || "").trim().toUpperCase();
+    const mergeStateStatus = String(parsed.mergeStateStatus || "").trim().toUpperCase();
+    const isDraft = parsed.isDraft === true;
+    const headRefOid = String(parsed.headRefOid || "").trim().toLowerCase();
+    const mergedAt = typeof parsed.mergedAt === "string" ? parsed.mergedAt.trim() : "";
+    const codeRabbitThreadState = reviewDecision.length === 0 ? resolveCodeRabbitReviewThreadsState(prRef, feature) : "unknown";
+    const codeRabbitCheckSucceeded = hasSuccessfulCodeRabbitStatusCheck(
+      parsed.statusCheckRollup
+    );
+    if (state === "MERGED" || mergedAt.length > 0) {
+      return "merged";
+    }
+    if (isDraft) {
+      return "draft";
+    }
+    if (reviewDecision === "CHANGES_REQUESTED") {
+      return "changes_requested";
+    }
+    if (reviewDecision === "APPROVED") {
+      return mergeStateStatus === "CLEAN" || mergeStateStatus === "HAS_HOOKS" ? "approved" : "merge_blocked";
+    }
+    if (reviewDecision.length === 0 && codeRabbitThreadState === "open") {
+      return "changes_requested";
+    }
+    if (reviewDecision.length === 0 && hasLatestHeadRateLimitSignal(parsed, headRefOid)) {
+      return "review_rate_limited";
+    }
+    if (reviewDecision.length === 0 && hasStaleLatestCommitReviewSignal(parsed, headRefOid) && !(codeRabbitThreadState === "resolved" && codeRabbitCheckSucceeded)) {
+      return "review_pending_latest_commit";
+    }
+    if (reviewDecision.length === 0 && hasCodeRabbitActionableReview(parsed.latestReviews)) {
+      if (codeRabbitThreadState === "resolved" && codeRabbitCheckSucceeded) {
+        return mergeStateStatus === "CLEAN" || mergeStateStatus === "HAS_HOOKS" ? "approved" : "merge_blocked";
+      }
+      return "changes_requested";
+    }
+    if (reviewDecision.length === 0 && codeRabbitThreadState === "resolved" && codeRabbitCheckSucceeded) {
+      return mergeStateStatus === "CLEAN" || mergeStateStatus === "HAS_HOOKS" ? "approved" : "merge_blocked";
+    }
+    if (reviewDecision === "REVIEW_REQUIRED" || reviewDecision.length === 0) {
+      return "waiting_review";
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function resolveCurrentReviewState(tasks, prDraft, remoteReviewState) {
+  if (remoteReviewState === "merged") {
+    return "merged";
+  }
+  if (remoteReviewState === "draft") {
+    return "draft";
+  }
+  if (remoteReviewState === "merge_blocked") {
+    return "merge_blocked";
+  }
+  if (remoteReviewState === "changes_requested") {
+    return "changes_requested";
+  }
+  if (remoteReviewState === "review_rate_limited") {
+    return "review_rate_limited";
+  }
+  if (remoteReviewState === "review_pending_latest_commit") {
+    return "review_pending_latest_commit";
+  }
+  if (remoteReviewState === "waiting_review") {
+    return "waiting_review";
+  }
+  if (remoteReviewState === "approved") {
+    return "approved";
+  }
+  if (remoteReviewState === "unknown") {
+    return "unknown";
+  }
+  if (tasks.prStatus === "approved" || prDraft.prStatus === "approved") {
+    return "approved";
+  }
+  return "unknown";
+}
+function buildCodeReviewActionOptions(reviewState) {
+  if (reviewState === "merged") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_sync_approved",
+        "Sync the already-merged PR state into tasks.md and pr.md before closing the feature."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Stop here and leave the merged-state sync for later."
+      )
+    ];
+  }
+  if (reviewState === "approved") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_sync_approved",
+        "Sync the approved PR review state into tasks.md and pr.md, then continue to the merge gate."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Hold the merge boundary for now and leave the PR open."
+      )
+    ];
+  }
+  if (reviewState === "draft" || reviewState === "merge_blocked") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_wait",
+        "Inspect the current PR state, resolve the draft/merge blocker, and sync the review fields before proceeding."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Stop here and keep the PR open until the blocker is resolved."
+      )
+    ];
+  }
+  if (reviewState === "changes_requested") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_fix",
+        "Address the requested review changes, update review evidence/decision, and continue the feature."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Stop here and wait before taking another review-fix pass."
+      )
+    ];
+  }
+  if (reviewState === "review_rate_limited") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_wait",
+        "Re-check the PR review state after the CodeRabbit rate limit window resets, then sync tasks.md when a fresh review arrives."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Stop here and wait for the review rate limit window to clear."
+      )
+    ];
+  }
+  if (reviewState === "review_pending_latest_commit") {
+    return [
+      buildStageOption(
+        "A",
+        "A",
+        "review_wait",
+        "Re-check the PR review state after a reviewer processes the latest commit, then sync tasks.md when fresh review feedback arrives."
+      ),
+      buildStageOption(
+        "B",
+        "B",
+        "hold",
+        "Stop here and wait for a fresh review on the latest commit."
+      )
+    ];
+  }
+  return [
+    buildStageOption(
+      "A",
+      "A",
+      "review_wait",
+      "Check the PR review state again and sync tasks.md when reviewer feedback or approval arrives."
+    ),
+    buildStageOption(
+      "B",
+      "B",
+      "hold",
+      "Stop here and wait for external reviewer feedback."
+    )
+  ];
+}
+function buildMergeActionOptions(command) {
+  return [
+    buildStageOption(
+      "A",
+      "A OK",
+      "pr_merge",
+      "Merge the PR now and sync the merged state back into tasks.md.",
+      command
+    ),
+    buildStageOption(
+      "B",
+      "B",
+      "hold",
+      "Keep the PR open and do not merge yet."
+    )
+  ];
+}
+function buildApprovalActionOptions(params) {
+  const remoteCommand = params.remoteCommand?.trim() || null;
+  if (remoteCommand && remoteCommand.includes("--confirm OK")) {
+    return [
+      buildStageOption(
+        "A",
+        "A OK",
+        "remote_execute",
+        params.approveSummary,
+        remoteCommand
+      ),
+      buildStageOption("B", "B", "hold", params.holdSummary)
+    ];
+  }
+  return [
+    buildStageOption("A", "A", "approve_continue", params.approveSummary),
+    buildStageOption("B", "B", "request_changes", params.holdSummary)
+  ];
+}
 function resolveFeatureSelectionError(selection) {
   const reasonCode = selection.status === "no_features" ? "NO_FEATURES" : "FEATURE_SELECTION_REQUIRED";
   return {
@@ -7051,6 +7880,7 @@ async function collectWorkflowStage(cwd, selector, component) {
   }
   const feature = selection.matchedFeature;
   const requirements = resolveWorkflowRequirements(config);
+  const taskCommitGatePolicy = resolveTaskCommitGatePolicy(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));
@@ -7058,16 +7888,27 @@ async function collectWorkflowStage(cwd, selector, component) {
   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
+    extractFieldValue2(specContent || "", ["Status", "\uC0C1\uD0DC"]) || void 0
   );
   const planStatus = parseApprovalStatus(
-    extractFieldValue(planContent || "", ["Status", "\uC0C1\uD0DC"]) || void 0
+    extractFieldValue2(planContent || "", ["Status", "\uC0C1\uD0DC"]) || void 0
   );
   const tasks = parseTasksDoc(tasksContent || "");
   const issueDraft = parseWorkflowDraftMetadataExtended(issueContent || "");
   const prDraft = parseWorkflowDraftMetadataExtended(prContent || "");
+  const remoteReviewState = requirements.requireReview && tasks.prLink ? resolveRemotePrReviewState(tasks.prLink, feature) : "unknown";
+  const currentReviewState = resolveCurrentReviewState(
+    tasks,
+    prDraft,
+    remoteReviewState
+  );
   if (specStatus !== "approved") {
-    const approvalRequired = specStatus === "review";
+    const isReviewStage = specStatus === "review";
+    const approvalRequired = isReviewStage ? resolveActionApprovalRequired(config, "spec_approve", true) : false;
+    const actionOptions = approvalRequired ? buildApprovalActionOptions({
+      approveSummary: "Approve spec.md and continue to the plan stage.",
+      holdSummary: "Request spec changes before continuing."
+    }) : void 0;
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7075,17 +7916,24 @@ async function collectWorkflowStage(cwd, selector, component) {
       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.",
+        isReviewStage ? "spec_approve" : "spec_write",
+        isReviewStage ? approvalRequired ? "Get user approval and update spec.md status to Approved." : "Promote spec.md from Review to Approved and continue automatically." : "Write or refine spec.md until it is ready for approval.",
         approvalRequired
       ),
       approvalRequired,
       implementationAllowed: false,
+      primaryActionLabel: actionOptions ? "A" : void 0,
+      actionOptions,
       blockedReasonCode: "SPEC_NOT_APPROVED"
     };
   }
   if (planStatus !== "approved") {
-    const approvalRequired = planStatus === "review";
+    const isReviewStage = planStatus === "review";
+    const approvalRequired = isReviewStage ? resolveActionApprovalRequired(config, "plan_approve", true) : false;
+    const actionOptions = approvalRequired ? buildApprovalActionOptions({
+      approveSummary: "Approve plan.md and continue to the tasks stage.",
+      holdSummary: "Request plan changes before continuing."
+    }) : void 0;
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7093,17 +7941,24 @@ async function collectWorkflowStage(cwd, selector, component) {
       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.",
+        isReviewStage ? "plan_approve" : "plan_write",
+        isReviewStage ? approvalRequired ? "Get user approval and update plan.md status to Approved." : "Promote plan.md from Review to Approved and continue automatically." : "Write or refine plan.md until it is ready for approval.",
         approvalRequired
       ),
       approvalRequired,
       implementationAllowed: false,
+      primaryActionLabel: actionOptions ? "A" : void 0,
+      actionOptions,
       blockedReasonCode: "PLAN_NOT_APPROVED"
     };
   }
   if (tasks.tasks.length === 0 || tasks.docStatus !== "approved") {
-    const approvalRequired = tasks.docStatus === "review";
+    const isReviewStage = tasks.docStatus === "review";
+    const approvalRequired = isReviewStage ? resolveActionApprovalRequired(config, "tasks_approve", true) : false;
+    const actionOptions = approvalRequired ? buildApprovalActionOptions({
+      approveSummary: "Approve tasks.md and continue to issue preparation.",
+      holdSummary: "Request task-list changes before continuing."
+    }) : void 0;
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7111,12 +7966,14 @@ async function collectWorkflowStage(cwd, selector, component) {
       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.",
+        isReviewStage ? "tasks_approve" : "tasks_write",
+        isReviewStage ? approvalRequired ? "Get user approval and update tasks.md Doc Status to Approved." : "Promote tasks.md Doc Status from Review to Approved and continue automatically." : "Add and refine tasks until tasks.md is execution-ready and Approved.",
         approvalRequired
       ),
       approvalRequired,
       implementationAllowed: false,
+      primaryActionLabel: actionOptions ? "A" : void 0,
+      actionOptions,
       blockedReasonCode: "TASKS_NOT_READY"
     };
   }
@@ -7124,6 +7981,13 @@ async function collectWorkflowStage(cwd, selector, component) {
     const issueReady = issueDraft.status === "ready";
     const issueCreated = tasks.issueNumber !== null && issueExistsRemotely(tasks.issueNumber, feature);
     if (!issueCreated || !issueReady) {
+      const issueCreateApprovalRequired = issueReady && !issueCreated;
+      const issueCreateCommand = `npx lee-spec-kit github issue ${buildFeatureArgs(feature)} --create --confirm OK`;
+      const issueCreateOptions = issueCreateApprovalRequired ? buildApprovalActionOptions({
+        approveSummary: "Create the GitHub issue now and sync the issue number back into tasks.md.",
+        holdSummary: "Keep the issue in Ready state but do not create it yet.",
+        remoteCommand: issueCreateCommand
+      }) : void 0;
       return {
         status: "ok",
         reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7133,23 +7997,40 @@ async function collectWorkflowStage(cwd, selector, component) {
         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`
+          issueCreateApprovalRequired,
+          issueCreateCommand
         ) : buildAction(
           "issue_prepare",
           "Prepare issue.md and set its Status to Ready before issue creation.",
           false
         ),
-        approvalRequired: issueReady && !issueCreated,
+        approvalRequired: issueCreateApprovalRequired,
         implementationAllowed: false,
+        primaryActionLabel: issueCreateOptions ? "A" : void 0,
+        actionOptions: issueCreateOptions,
         blockedReasonCode: "ISSUE_NOT_CREATED"
       };
     }
   }
+  let effectiveProjectGitCwd = feature.git.projectGitCwd;
+  if (requirements.requireWorktree) {
+    const expectedBranch = resolveExpectedBranch(feature, tasks);
+    if (expectedBranch) {
+      const existingWorktreePath = await resolveExistingExpectedWorktreePath(
+        config,
+        feature.git.projectGitCwd,
+        expectedBranch
+      );
+      if (existingWorktreePath) {
+        effectiveProjectGitCwd = existingWorktreePath;
+      }
+    }
+  }
   if (requirements.requireBranch && !allTasksDone(tasks)) {
     const expectedBranch = resolveExpectedBranch(feature, tasks);
-    const currentBranch = getCurrentProjectBranch(feature);
+    const currentBranch = runGitCapture(["branch", "--show-current"], effectiveProjectGitCwd) || runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], effectiveProjectGitCwd) || null;
     if (expectedBranch && currentBranch !== expectedBranch) {
+      const branchCommand = requirements.requireWorktree ? buildManagedWorktreeCreateCommand(config, feature.git.projectGitCwd, expectedBranch) : `git checkout -b ${expectedBranch}`;
       return {
         status: "ok",
         reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7158,9 +8039,9 @@ async function collectWorkflowStage(cwd, selector, component) {
         stage: "branch",
         nextAction: buildAction(
           "branch_create",
-          `Switch the project repo to ${expectedBranch} before implementation starts.`,
+          requirements.requireWorktree ? `Create or reuse the managed worktree for ${expectedBranch} before implementation starts.` : `Switch the project repo to ${expectedBranch} before implementation starts.`,
           false,
-          `git checkout -b ${expectedBranch}`
+          branchCommand
         ),
         approvalRequired: false,
         implementationAllowed: false,
@@ -7168,8 +8049,66 @@ async function collectWorkflowStage(cwd, selector, component) {
       };
     }
   }
+  const activeTaskOpen = hasOpenTask(tasks);
+  const lastDoneTask = getLastDoneTask(tasks);
+  const docsDirty = hasUncommittedChanges(feature.git.docsGitCwd);
+  const projectDirty = hasUncommittedChanges(effectiveProjectGitCwd);
+  const pendingDoneTransitions = countPendingDoneTransitions(feature) || 0;
+  const taskCommitCheckpointRequired = !activeTaskOpen && !!lastDoneTask && (projectDirty || pendingDoneTransitions > 0);
+  if (taskCommitCheckpointRequired) {
+    const pendingReason = pendingDoneTransitions > 1 ? `working tree currently contains ${pendingDoneTransitions} uncommitted DONE transitions` : null;
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "task_commit",
+      nextAction: buildAction(
+        "task_commit",
+        buildTaskCommitSummary({
+          feature,
+          tasks,
+          effectiveProjectGitCwd,
+          docsDirty,
+          projectDirty,
+          gateFailureReason: pendingReason
+        }),
+        false
+      ),
+      approvalRequired: false,
+      implementationAllowed: false,
+      blockedReasonCode: "TASK_COMMIT_REQUIRED"
+    };
+  }
+  const committedTaskGate = taskCommitGatePolicy !== "off" && lastDoneTask ? checkTaskCommitGate(feature, effectiveProjectGitCwd, lastDoneTask) : { pass: true };
   if (!allTasksDone(tasks)) {
     const currentTask = nextTodoTask(tasks);
+    if (taskCommitGatePolicy === "strict" && !committedTaskGate.pass) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "task_commit",
+        nextAction: buildAction(
+          "task_commit",
+          buildTaskCommitSummary({
+            feature,
+            tasks,
+            effectiveProjectGitCwd,
+            docsDirty,
+            projectDirty,
+            gateFailureReason: describeTaskCommitGateFailure(committedTaskGate)
+          }),
+          false
+        ),
+        approvalRequired: false,
+        implementationAllowed: false,
+        blockedReasonCode: "TASK_COMMIT_REQUIRED"
+      };
+    }
+    const commitWarning = taskCommitGatePolicy === "warn" && !committedTaskGate.pass ? `
+Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)}` : "";
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7178,7 +8117,7 @@ async function collectWorkflowStage(cwd, selector, component) {
       stage: "implementation",
       nextAction: buildAction(
         "task_execute",
-        currentTask ? `Continue the next implementation task: ${currentTask.title}` : "Continue the active implementation task.",
+        currentTask ? `Continue the next implementation task: ${currentTask.title}${commitWarning}` : "Continue the active implementation task.",
         false
       ),
       approvalRequired: false,
@@ -7187,6 +8126,39 @@ async function collectWorkflowStage(cwd, selector, component) {
     };
   }
   if (!tasks.completion.allTasksChecked || !tasks.completion.testsChecked || !tasks.completion.finalOutcomeChecked) {
+    if (taskCommitGatePolicy === "strict" && !committedTaskGate.pass) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "task_commit",
+        nextAction: buildAction(
+          "task_commit",
+          buildTaskCommitSummary({
+            feature,
+            tasks,
+            effectiveProjectGitCwd,
+            docsDirty,
+            projectDirty,
+            gateFailureReason: describeTaskCommitGateFailure(committedTaskGate)
+          }),
+          false
+        ),
+        approvalRequired: false,
+        implementationAllowed: false,
+        blockedReasonCode: "TASK_COMMIT_REQUIRED"
+      };
+    }
+    const approvalRequired = resolveActionApprovalRequired(
+      config,
+      "implementation_approve",
+      true
+    );
+    const actionOptions = approvalRequired ? buildApprovalActionOptions({
+      approveSummary: "Approve the completed implementation and continue to the pre-PR or PR preparation stage.",
+      holdSummary: "Request implementation changes before the workflow continues."
+    }) : void 0;
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7196,10 +8168,12 @@ async function collectWorkflowStage(cwd, selector, component) {
       nextAction: buildAction(
         "implementation_approve",
         "Share the completed implementation, get user approval, and record the completion checkpoint in tasks.md.",
-        true
+        approvalRequired
       ),
-      approvalRequired: true,
+      approvalRequired,
       implementationAllowed: false,
+      primaryActionLabel: actionOptions ? "A" : void 0,
+      actionOptions,
       blockedReasonCode: "IMPLEMENTATION_APPROVAL_REQUIRED"
     };
   }
@@ -7224,6 +8198,13 @@ async function collectWorkflowStage(cwd, selector, component) {
     const prReady = prDraft.status === "ready";
     const prCreated = !!tasks.prLink && prExistsRemotely(tasks.prLink, feature);
     if (!prCreated || !prReady) {
+      const prCreateApprovalRequired = prReady && !prCreated;
+      const prCreateCommand = `npx lee-spec-kit github pr ${buildFeatureArgs(feature)} --create --confirm OK`;
+      const prCreateOptions = prCreateApprovalRequired ? buildApprovalActionOptions({
+        approveSummary: "Create the GitHub PR now and sync the PR metadata back into tasks.md.",
+        holdSummary: "Keep the PR in Ready state but do not create it yet.",
+        remoteCommand: prCreateCommand
+      }) : void 0;
       return {
         status: "ok",
         reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7233,20 +8214,63 @@ async function collectWorkflowStage(cwd, selector, component) {
         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`
+          prCreateApprovalRequired,
+          prCreateCommand
         ) : buildAction(
           "pr_prepare",
           "Prepare pr.md and set its Status to Ready before PR creation.",
           false
         ),
-        approvalRequired: prReady && !prCreated,
+        approvalRequired: prCreateApprovalRequired,
         implementationAllowed: false,
+        primaryActionLabel: prCreateOptions ? "A" : void 0,
+        actionOptions: prCreateOptions,
         blockedReasonCode: "PR_NOT_CREATED"
       };
     }
   }
-  if (requirements.requireReview && (tasks.prStatus !== "approved" || prDraft.prStatus !== "approved")) {
+  const reviewApprovedInDocs = tasks.prStatus === "approved" && prDraft.prStatus === "approved";
+  if (requirements.requireReview && currentReviewState === "merged" && reviewApprovedInDocs) {
+    const cleanupState = resolvePostMergeCleanupState(config, feature, tasks);
+    if (!cleanupState.complete) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "cleanup",
+        nextAction: buildAction(
+          "merge_cleanup",
+          buildPostMergeCleanupSummary(cleanupState),
+          false,
+          buildPostMergeCleanupCommand(cleanupState)
+        ),
+        approvalRequired: false,
+        implementationAllowed: false,
+        reviewState: "merged",
+        blockedReasonCode: "POST_MERGE_CLEANUP_REQUIRED"
+      };
+    }
+    return {
+      status: "ok",
+      reasonCode: "WORKFLOW_STAGE_RESOLVED",
+      docsDir: config.docsDir,
+      featureRef: buildFeatureRef(feature),
+      stage: "done",
+      nextAction: null,
+      approvalRequired: false,
+      implementationAllowed: false,
+      reviewState: "merged",
+      primaryActionLabel: null,
+      actionOptions: [],
+      blockedReasonCode: null
+    };
+  }
+  if (requirements.requireReview && (!reviewApprovedInDocs || currentReviewState !== "approved")) {
+    const reviewFixAllowed = currentReviewState === "changes_requested";
+    const reviewApprovalRequired = !reviewFixAllowed;
+    const reviewActionOptions = reviewApprovalRequired ? buildCodeReviewActionOptions(currentReviewState) : void 0;
+    const reviewSummary = currentReviewState === "approved" ? "Record the approved PR review state in tasks.md and pr.md before proceeding to merge." : currentReviewState === "merged" ? "Sync the already-merged PR state into tasks.md and pr.md before marking the workflow as complete." : currentReviewState === "changes_requested" ? "Address the requested review changes and update the PR review evidence/decision before continuing." : currentReviewState === "review_pending_latest_commit" ? "Wait for a fresh review on the latest PR commit before taking the next review action." : currentReviewState === "review_rate_limited" ? "Wait for the current CodeRabbit review rate limit to clear, then re-check the latest PR review state before continuing." : currentReviewState === "draft" ? "Resolve the draft PR state before continuing to the merge boundary." : currentReviewState === "merge_blocked" ? "Resolve the current PR merge blocker before continuing to merge." : "Wait for PR review or inspect the current review state before taking the next review action.";
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7255,15 +8279,19 @@ async function collectWorkflowStage(cwd, selector, component) {
       stage: "code_review",
       nextAction: buildAction(
         "code_review",
-        "Complete PR review and record the final approved review state in tasks.md.",
-        false
+        reviewSummary,
+        reviewApprovalRequired
       ),
-      approvalRequired: false,
-      implementationAllowed: false,
+      approvalRequired: reviewApprovalRequired,
+      implementationAllowed: reviewFixAllowed,
+      reviewState: currentReviewState,
+      primaryActionLabel: reviewActionOptions ? "A" : void 0,
+      actionOptions: reviewActionOptions,
       blockedReasonCode: "PR_REVIEW_NOT_APPROVED"
     };
   }
   if (requirements.requireMerge) {
+    const mergeCommand = `npx lee-spec-kit github pr ${buildFeatureArgs(feature)} --merge --confirm OK`;
     return {
       status: "ok",
       reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -7274,10 +8302,13 @@ async function collectWorkflowStage(cwd, selector, component) {
         "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`
+        mergeCommand
       ),
       approvalRequired: true,
       implementationAllowed: false,
+      reviewState: "approved",
+      primaryActionLabel: "A",
+      actionOptions: buildMergeActionOptions(mergeCommand),
       blockedReasonCode: null
     };
   }
@@ -7293,6 +8324,237 @@ async function collectWorkflowStage(cwd, selector, component) {
     blockedReasonCode: null
   };
 }
+function hasLatestHeadRateLimitSignal(parsed, headRefOid) {
+  const latestRateLimitCommentAt = findLatestCodeRabbitRateLimitCommentAt(
+    parsed.comments,
+    headRefOid
+  );
+  if (!latestRateLimitCommentAt) {
+    return false;
+  }
+  const latestReviewAt = findLatestCodeRabbitReviewAt(parsed.latestReviews);
+  return !latestReviewAt || latestReviewAt <= latestRateLimitCommentAt;
+}
+function hasStaleLatestCommitReviewSignal(parsed, headRefOid) {
+  if (!headRefOid) {
+    return false;
+  }
+  const latestReviewHead = findLatestCodeRabbitReviewedHead(parsed.latestReviews);
+  if (!latestReviewHead) {
+    return false;
+  }
+  return !matchesCommitReference(headRefOid, latestReviewHead);
+}
+function resolveCodeRabbitReviewThreadsState(prRef, feature) {
+  const coordinates = parseGithubPullRequestRef(prRef);
+  if (!coordinates) {
+    return "unknown";
+  }
+  const result = runProcess(
+    "gh",
+    [
+      "api",
+      "graphql",
+      "-f",
+      `owner=${coordinates.owner}`,
+      "-f",
+      `name=${coordinates.name}`,
+      "-F",
+      `number=${coordinates.number}`,
+      "-f",
+      "query=query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { headRefOid reviewThreads(first:100) { nodes { isResolved isOutdated comments(first:20) { nodes { author { login } body } } } } } } }"
+    ],
+    feature.git.projectGitCwd
+  );
+  if (result.code !== 0) {
+    return "unknown";
+  }
+  try {
+    const parsed = JSON.parse(String(result.stdout || "{}"));
+    const nodes = extractNestedArray(parsed, [
+      "data",
+      "repository",
+      "pullRequest",
+      "reviewThreads",
+      "nodes"
+    ]);
+    if (!nodes) {
+      return "unknown";
+    }
+    const codeRabbitThreads = nodes.filter(isCodeRabbitReviewThread);
+    if (codeRabbitThreads.length === 0) {
+      return "none";
+    }
+    return codeRabbitThreads.some((thread) => !isReviewThreadResolved(thread)) ? "open" : "resolved";
+  } catch {
+    return "unknown";
+  }
+}
+function parseGithubPullRequestRef(prRef) {
+  const value = prRef?.trim();
+  if (!value) {
+    return null;
+  }
+  const urlMatch = value.match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:[/?#].*)?$/i
+  );
+  if (!urlMatch?.[1] || !urlMatch[2] || !urlMatch[3]) {
+    return null;
+  }
+  return {
+    owner: urlMatch[1],
+    name: urlMatch[2],
+    number: Number(urlMatch[3])
+  };
+}
+function hasSuccessfulCodeRabbitStatusCheck(statusChecksValue) {
+  if (!Array.isArray(statusChecksValue)) {
+    return false;
+  }
+  return statusChecksValue.some((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    const record = entry;
+    const label = [
+      record.context,
+      record.name,
+      extractNestedString(record, ["app", "name"]),
+      extractNestedString(record, ["checkSuite", "app", "name"])
+    ].filter((value) => typeof value === "string" && value.trim().length > 0).join(" ").toLowerCase();
+    if (!label.includes("coderabbit")) return false;
+    const state = String(record.state || record.conclusion || "").trim().toUpperCase();
+    return state === "SUCCESS";
+  });
+}
+function isCodeRabbitReviewThread(threadValue) {
+  const comments = extractNestedArray(threadValue, ["comments", "nodes"]);
+  if (!comments) {
+    return false;
+  }
+  return comments.some(
+    (comment) => extractNestedString(comment, ["author", "login"]).toLowerCase().startsWith("coderabbitai")
+  );
+}
+function isReviewThreadResolved(threadValue) {
+  if (!threadValue || typeof threadValue !== "object") {
+    return false;
+  }
+  const record = threadValue;
+  return record.isResolved === true || record.isOutdated === true;
+}
+function hasCodeRabbitActionableReview(reviewsValue) {
+  if (!Array.isArray(reviewsValue)) {
+    return false;
+  }
+  return reviewsValue.some((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    const authorLogin = extractNestedString(entry, ["author", "login"]).toLowerCase();
+    if (authorLogin !== "coderabbitai") return false;
+    const state = String(entry.state || "").trim().toUpperCase();
+    if (state === "CHANGES_REQUESTED") return true;
+    if (state !== "COMMENTED") return false;
+    const body = String(entry.body || "");
+    const actionableMatch = body.match(/Actionable comments posted:\s*(\d+)/i);
+    return actionableMatch ? Number(actionableMatch[1]) > 0 : false;
+  });
+}
+function extractNestedArray(value, pathSegments) {
+  let current = value;
+  for (const segment of pathSegments) {
+    if (!current || typeof current !== "object") {
+      return null;
+    }
+    current = current[segment];
+  }
+  return Array.isArray(current) ? current : null;
+}
+function findLatestCodeRabbitRateLimitCommentAt(commentsValue, headRefOid) {
+  if (!Array.isArray(commentsValue)) {
+    return null;
+  }
+  let latest = null;
+  for (const entry of commentsValue) {
+    if (!entry || typeof entry !== "object") continue;
+    const authorLogin = extractNestedString(entry, ["author", "login"]).toLowerCase();
+    if (authorLogin !== "coderabbitai") continue;
+    const body = String(entry.body || "");
+    if (!isCodeRabbitRateLimitBody(body, headRefOid)) continue;
+    const createdAt = String(entry.createdAt || "").trim();
+    if (!createdAt) continue;
+    if (!latest || createdAt > latest) {
+      latest = createdAt;
+    }
+  }
+  return latest;
+}
+function findLatestCodeRabbitReviewAt(reviewsValue) {
+  if (!Array.isArray(reviewsValue)) {
+    return null;
+  }
+  let latest = null;
+  for (const entry of reviewsValue) {
+    if (!entry || typeof entry !== "object") continue;
+    const authorLogin = extractNestedString(entry, ["author", "login"]).toLowerCase();
+    if (authorLogin !== "coderabbitai") continue;
+    const submittedAt = String(entry.submittedAt || "").trim();
+    if (!submittedAt) continue;
+    if (!latest || submittedAt > latest) {
+      latest = submittedAt;
+    }
+  }
+  return latest;
+}
+function findLatestCodeRabbitReviewedHead(reviewsValue) {
+  if (!Array.isArray(reviewsValue)) {
+    return null;
+  }
+  let latestReview = null;
+  for (const entry of reviewsValue) {
+    if (!entry || typeof entry !== "object") continue;
+    const authorLogin = extractNestedString(entry, ["author", "login"]).toLowerCase();
+    if (authorLogin !== "coderabbitai") continue;
+    const submittedAt = String(entry.submittedAt || "").trim();
+    if (!submittedAt) continue;
+    const body = String(entry.body || "");
+    const reviewedHead = extractReviewedHeadFromReviewBody(body);
+    if (!latestReview || submittedAt > latestReview.submittedAt) {
+      latestReview = { submittedAt, reviewedHead };
+    }
+  }
+  return latestReview?.reviewedHead ?? null;
+}
+function isCodeRabbitRateLimitBody(body, headRefOid) {
+  const normalized = body.toLowerCase();
+  if (!normalized.includes("rate limited by coderabbit.ai") && !normalized.includes("rate limit exceeded")) {
+    return false;
+  }
+  if (!headRefOid) {
+    return true;
+  }
+  const shortHead = headRefOid.slice(0, 7);
+  return normalized.includes(headRefOid) || normalized.includes(shortHead);
+}
+function extractReviewedHeadFromReviewBody(body) {
+  const match = body.match(/between\s+[0-9a-f]{7,40}\s+and\s+([0-9a-f]{7,40})/i);
+  if (!match) {
+    return null;
+  }
+  return match[1].trim().toLowerCase();
+}
+function matchesCommitReference(headRefOid, reviewedHead) {
+  const normalizedHead = headRefOid.trim().toLowerCase();
+  const normalizedReviewedHead = reviewedHead.trim().toLowerCase();
+  return normalizedHead === normalizedReviewedHead || normalizedHead.startsWith(normalizedReviewedHead) || normalizedReviewedHead.startsWith(normalizedHead);
+}
+function extractNestedString(value, pathSegments) {
+  let current = value;
+  for (const segment of pathSegments) {
+    if (!current || typeof current !== "object") {
+      return "";
+    }
+    current = current[segment];
+  }
+  return typeof current === "string" ? current.trim() : "";
+}
 
 // src/commands/workflow-stage.ts
 function workflowStageCommand(program2) {
@@ -7754,13 +9016,35 @@ var DEFAULT_MANAGED_DOC_FILES = [
   ".gitignore"
 ];
 
+// src/utils/commit-conventions.ts
+var PROJECT_COMMIT_PREFIX_PATTERN = /^(feat|fix|refactor|test|chore)\(#(\d+)\):\s+\S.+$/i;
+var DOCS_COMMIT_PREFIX_PATTERN = /^docs\(#(\d+)\):\s+\S.+$/i;
+function matchesProjectCommitConvention(message, issueNumber) {
+  const normalized = String(message || "").trim();
+  if (!normalized) return false;
+  const match = normalized.match(PROJECT_COMMIT_PREFIX_PATTERN);
+  if (!match) return false;
+  return Number(match[2]) === issueNumber;
+}
+function matchesDocsCommitConvention(message, issueNumber) {
+  const normalized = String(message || "").trim();
+  if (!normalized) return false;
+  const match = normalized.match(DOCS_COMMIT_PREFIX_PATTERN);
+  if (!match) return false;
+  return Number(match[1]) === issueNumber;
+}
+
 // src/commands/commit-audit.ts
 var CANONICAL_FEATURE_DOC_PATTERN = /^features\/(?:[^/]+\/)?F\d{3,}[^/]*\/(spec|plan|tasks|decisions|issue|pr)\.md$/i;
 var FEATURE_DOC_CANDIDATE_PATTERN = /^features\/(?:[^/]+\/)?F\d{3,}[^/]*\/(.+)$/i;
 function commitAuditCommand(program2) {
-  program2.command("commit-audit").description("Validate staged docs paths before commit").option("--json", "Output JSON for hooks and agents").option("--git-root <path>", "Override the git root used for staged-path inspection").action(async (options) => {
+  program2.command("commit-audit").description("Validate staged docs paths before commit").option("--json", "Output JSON for hooks and agents").option("--git-root <path>", "Override the git root used for staged-path inspection").option("--message <message>", "Validate a commit subject against the current workflow convention").action(async (options) => {
     try {
-      const payload = await collectCommitAudit(process.cwd(), options.gitRoot);
+      const payload = await collectCommitAudit(
+        process.cwd(),
+        options.gitRoot,
+        options.message
+      );
       if (options.json) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -7795,7 +9079,7 @@ function commitAuditCommand(program2) {
     }
   });
 }
-async function collectCommitAudit(cwd, gitRootOverride) {
+async function collectCommitAudit(cwd, gitRootOverride, commitMessage) {
   const config = await getConfig(cwd);
   if (!config) {
     throw createCliError("CONFIG_NOT_FOUND", "Config file not found. Run `init` first.");
@@ -7836,6 +9120,16 @@ async function collectCommitAudit(cwd, gitRootOverride) {
     stagedEntries,
     config.allowedDocsEntries
   );
+  const commitMessageViolation = await collectCommitMessageViolation(
+    cwd,
+    config,
+    repoRoot,
+    stagedEntries,
+    commitMessage
+  );
+  if (commitMessageViolation) {
+    violations.push(commitMessageViolation);
+  }
   if (violations.length === 0) {
     return {
       status: "ok",
@@ -7880,6 +9174,9 @@ function collectAllowedCommitRepoRoots(config, cwd) {
       if (projectRepoRoot) {
         allowed.add(path8.resolve(projectRepoRoot));
       }
+      for (const worktreeRepoRoot of collectManagedWorktreeRepoRoots(config, projectRoot)) {
+        allowed.add(path8.resolve(worktreeRepoRoot));
+      }
     }
     return allowed;
   }
@@ -7889,6 +9186,28 @@ function collectAllowedCommitRepoRoots(config, cwd) {
   }
   return allowed;
 }
+function collectManagedWorktreeRepoRoots(config, projectRoot) {
+  const managedRoot = resolveStandaloneManagedWorktreeRoot(config, projectRoot);
+  if (!managedRoot) {
+    return [];
+  }
+  const output = runGitCapture(["worktree", "list", "--porcelain"], projectRoot) || "";
+  const roots = /* @__PURE__ */ new Set();
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+    if (!line.startsWith("worktree ")) continue;
+    const worktreePath = path8.resolve(line.slice("worktree ".length).trim());
+    if (isSameOrWithin2(path8.resolve(managedRoot), worktreePath)) {
+      roots.add(worktreePath);
+    }
+  }
+  return [...roots];
+}
+function isSameOrWithin2(parentDir, candidateDir) {
+  const resolvedParent = path8.resolve(parentDir);
+  const resolvedCandidate = path8.resolve(candidateDir);
+  return resolvedParent === resolvedCandidate || resolvedCandidate.startsWith(`${resolvedParent}${path8.sep}`);
+}
 function parseStagedPaths(output) {
   const staged = /* @__PURE__ */ new Map();
   for (const rawLine of output.split("\n")) {
@@ -7967,6 +9286,9 @@ function collectCommitViolations(repoRoot, docsDir, stagedEntries, allowed) {
 function resolveReasonCode(violations) {
   const kinds = new Set(violations.map((entry) => entry.kind));
   if (kinds.size > 1) return "DOCS_COMMIT_POLICY_VIOLATION";
+  if (kinds.has("commit_message_policy")) {
+    return "COMMIT_MESSAGE_POLICY_VIOLATION";
+  }
   if (kinds.has("unsupported_git_target")) return "UNSUPPORTED_GIT_TARGET";
   if (kinds.has("unmanaged_docs_entry")) return "UNMANAGED_DOCS_COMMIT";
   if (kinds.has("canonical_feature_doc_deletion")) {
@@ -7974,6 +9296,36 @@ function resolveReasonCode(violations) {
   }
   return "NON_CANONICAL_FEATURE_DOC_COMMIT";
 }
+async function collectCommitMessageViolation(cwd, config, repoRoot, stagedEntries, commitMessage) {
+  const normalizedMessage = String(commitMessage || "").trim();
+  if (!normalizedMessage) {
+    return null;
+  }
+  const selection = await resolveFeatureSelection(cwd);
+  if (selection.status !== "selected" || !selection.matchedFeature?.issueNumber) {
+    return null;
+  }
+  const issueNumber = selection.matchedFeature.issueNumber;
+  const docsRepoRoot = runGitCapture(["rev-parse", "--show-toplevel"], config.docsDir);
+  const normalizedRepoRoot = path8.resolve(repoRoot);
+  const normalizedDocsRepoRoot = docsRepoRoot ? path8.resolve(docsRepoRoot) : null;
+  const docsOnlyCommit = stagedEntries.length > 0 && stagedEntries.every((entry) => {
+    const absolutePath = path8.resolve(repoRoot, entry.path);
+    const relativeToDocs = normalizeSlashes3(path8.relative(config.docsDir, absolutePath));
+    return !!relativeToDocs && relativeToDocs !== "" && !relativeToDocs.startsWith("..");
+  });
+  const isDocsCommit = !!normalizedDocsRepoRoot && normalizedDocsRepoRoot === normalizedRepoRoot && (config.docsRepo === "standalone" || docsOnlyCommit);
+  const valid = isDocsCommit ? matchesDocsCommitConvention(normalizedMessage, issueNumber) : matchesProjectCommitConvention(normalizedMessage, issueNumber);
+  if (valid) {
+    return null;
+  }
+  const expected = isDocsCommit ? `docs(#${issueNumber}): ...` : `type(#${issueNumber}): ... (feat/fix/refactor/test/chore)`;
+  return {
+    path: "(commit message)",
+    kind: "commit_message_policy",
+    detail: `Commit subject must follow the issue-scoped convention for this feature. Expected ${expected}, received "${normalizedMessage}".`
+  };
+}
 function normalizeEntryName(value) {
   return value.trim().toLowerCase();
 }