lee-spec-kit 0.5.0 → 0.5.2

package/dist/index.js

@@ -128,10 +128,12 @@ var I18N = {
       "context.tipShowAll": "\uC804\uCCB4 \uBCF4\uAE30",
       "context.tipShowDone": "\uC644\uB8CC\uB9CC \uBCF4\uAE30",
       "context.checkRequired": "[\uD655\uC778 \uD544\uC694] ",
-      "context.checkPolicyHint": "\u2139\uFE0F  \uC0AC\uC6A9\uC790 \uD655\uC778 \uADDC\uCE59: /docs/agents/agents.md \uCC38\uACE0 (git push/merge/merge commit \uD3EC\uD568) \u2014 [\uD655\uC778 \uD544\uC694]\uAC00 \uC788\uC73C\uBA74 \uC0AC\uC6A9\uC790\uC5D0\uAC8C `<\uB77C\uBCA8>` \uB610\uB294 `<\uB77C\uBCA8> OK` (\uC608: `A`, `A OK`) \uC751\uB2F5\uC744 \uBC1B\uC740 \uB4A4 \uC9C4\uD589 (config: approval\uB85C \uC870\uC815 \uAC00\uB2A5)",
+      "context.checkPolicyHint": "\u2139\uFE0F  \uC0AC\uC6A9\uC790 \uD655\uC778 \uC815\uCC45 \uC548\uB0B4(\uD604\uC7AC Next Action \uC544\uB2D8): /docs/agents/agents.md \uCC38\uACE0 (git push/merge/merge commit \uD3EC\uD568). [\uD655\uC778 \uD544\uC694]\uAC00 \uC788\uC73C\uBA74 \uC0AC\uC6A9\uC790\uC5D0\uAC8C `<\uB77C\uBCA8>` \uB610\uB294 `<\uB77C\uBCA8> OK` (\uC608: `A`, `A OK`) \uC751\uB2F5\uC744 \uBC1B\uC740 \uB4A4 \uC9C4\uD589 (config: approval\uB85C \uC870\uC815 \uAC00\uB2A5)",
       "context.actionOptionHint": "\uC2B9\uC778 \uC751\uB2F5 \uD615\uC2DD: `<\uB77C\uBCA8>` \uB610\uB294 `<\uB77C\uBCA8> OK` (\uC608: `A`, `A OK`)",
+      "context.actionExplainHint": "\uC2B9\uC778 \uC694\uCCAD \uC804, \uAC01 \uB77C\uBCA8\uC774 \uBB34\uC5C7\uC744 \uC2E4\uD589/\uBCC0\uACBD\uD558\uB294\uC9C0 \uD55C \uC904 \uC694\uC57D\uACFC \uD568\uAED8 \uC124\uBA85\uD558\uC138\uC694.",
       "context.tipDocsCommitRules": "\uCEE4\uBC0B \uBA54\uC2DC\uC9C0 \uADDC\uCE59: /docs/agents/git-workflow.md \uCC38\uACE0",
       "context.list.docsCommitNeeded": "\uBB38\uC11C \uCEE4\uBC0B \uD544\uC694",
+      "context.list.projectCommitNeeded": "\uD504\uB85C\uC81D\uD2B8 \uCF54\uB4DC \uCEE4\uBC0B \uD544\uC694",
       "context.list.issueNumberNeeded": "\uC774\uC288 \uBC88\uD638 \uAE30\uB85D \uD544\uC694",
       "context.list.addPrMetadata": "PR \uBA54\uD0C0\uB370\uC774\uD130(PR/PR \uC0C1\uD0DC) \uCD94\uAC00",
       "context.list.recordPrLink": "PR \uB9C1\uD06C \uAE30\uB85D",
@@ -222,6 +224,8 @@ var I18N = {
       issueCreateAndWrite: "GitHub Issue\uB97C \uC0DD\uC131\uD55C \uB4A4, spec.md/tasks.md\uC758 \uC774\uC288 \uBC88\uD638\uB97C \uCC44\uC6B0\uACE0 \uBB38\uC11C \uCEE4\uBC0B\uC744 \uC900\uBE44\uD558\uC138\uC694. (skills/create-issue.md \uCC38\uACE0)",
       docsCommitIssueUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(#{issueNumber}): {folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"',
       docsCommitUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs: {folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"',
+      projectCommitIssueUpdate: 'cd "{projectGitCwd}" && git add -A && git commit -m "feat(#{issueNumber}): {folderName} \uAD6C\uD604 \uC5C5\uB370\uC774\uD2B8"',
+      projectCommitUpdate: 'cd "{projectGitCwd}" && git add -A && git commit -m "feat: {folderName} \uAD6C\uD604 \uC5C5\uB370\uC774\uD2B8"',
       standaloneNeedsProjectRoot: "standalone \uBAA8\uB4DC\uC5D0\uC11C\uB294 projectRoot \uC124\uC815\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. (npx lee-spec-kit config --project-root ...)",
       createBranch: 'cd "{projectGitCwd}" && git checkout -b feat/{issueNumber}-{slug}',
       tasksAllDoneButNoChecklist: '\uBAA8\uB4E0 \uD0DC\uC2A4\uD06C\uAC00 DONE\uC774\uC9C0\uB9CC \uC644\uB8CC \uC870\uAC74 \uCCB4\uD06C\uB9AC\uC2A4\uD2B8 \uC139\uC158\uC744 \uCC3E\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. tasks.md\uC758 "\uC644\uB8CC \uC870\uAC74" \uC139\uC158\uC744 \uCD94\uAC00/\uD655\uC778\uD558\uC138\uC694.',
@@ -242,11 +246,13 @@ var I18N = {
       docsGitUnavailable: "docs \uB808\uD3EC\uC758 git \uC0C1\uD0DC\uB97C \uD655\uC778\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. (\uB808\uD3EC \uC704\uCE58 / git init \uD655\uC778)",
       docsPathIgnored: "\uD604\uC7AC Feature \uBB38\uC11C \uACBD\uB85C\uAC00 git ignore \uB300\uC0C1\uC785\uB2C8\uB2E4: {path} (docs \uCEE4\uBC0B \uAC10\uC9C0\uAC00 \uC81C\uD55C\uB420 \uC218 \uC788\uC2B5\uB2C8\uB2E4.)",
       docsUncommittedChanges: "\uBB38\uC11C \uBCC0\uACBD\uC0AC\uD56D\uC774 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. (\uCD94\uAC00 \uBB38\uC11C \uCEE4\uBC0B \uD544\uC694) \uCEE4\uBC0B \uBA54\uC2DC\uC9C0 \uADDC\uCE59: /docs/agents/git-workflow.md \uCC38\uACE0",
+      projectUncommittedChanges: "\uD504\uB85C\uC81D\uD2B8 \uCF54\uB4DC \uBCC0\uACBD\uC0AC\uD56D\uC774 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. (\uCD94\uAC00 \uCF54\uB4DC \uCEE4\uBC0B \uD544\uC694)",
       legacyTasksDocStatusField: "\uAD6C\uBC84\uC804 tasks.md \uD3EC\uB9F7\uC785\uB2C8\uB2E4. `\uBB38\uC11C \uC0C1\uD0DC` \uD544\uB4DC(Review/Approved)\uB97C \uCD94\uAC00\uD574 \uD0DC\uC2A4\uD06C \uC2B9\uC778 \uB2E8\uACC4\uB97C \uD65C\uC131\uD654\uD558\uC138\uC694.",
       legacyTasksPrFields: "\uAD6C\uBC84\uC804 tasks.md \uD3EC\uB9F7\uC785\uB2C8\uB2E4. PR \uB2E8\uACC4 \uC804\uC5D0 `PR` \uBC0F `PR \uC0C1\uD0DC` \uD544\uB4DC\uB97C \uCD94\uAC00\uD558\uC138\uC694.",
       workflowSpecNotApproved: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC spec.md \uC0C1\uD0DC\uAC00 Approved\uAC00 \uC544\uB2D9\uB2C8\uB2E4. (spec.md\uC758 \uC0C1\uD0DC\uB97C Approved\uB85C \uC5C5\uB370\uC774\uD2B8\uD558\uC138\uC694.)",
       workflowPlanNotApproved: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC plan.md \uC0C1\uD0DC\uAC00 Approved\uAC00 \uC544\uB2D9\uB2C8\uB2E4. (plan.md\uC758 \uC0C1\uD0DC\uB97C Approved\uB85C \uC5C5\uB370\uC774\uD2B8\uD558\uC138\uC694.)",
       workflowIssueMissing: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC \uC774\uC288 \uBC88\uD638\uAC00 \uBE44\uC5B4\uC788\uC2B5\uB2C8\uB2E4. (spec.md/tasks.md\uC758 \uC774\uC288 \uBC88\uD638\uB97C \uCC44\uC6B0\uC138\uC694.)",
+      workflowProjectUncommittedChanges: "\uC644\uB8CC \uC870\uAC74 \uC774\uC804\uC5D0 \uD504\uB85C\uC81D\uD2B8 \uCF54\uB4DC \uBCC0\uACBD\uC0AC\uD56D\uC744 \uCEE4\uBC0B\uD574\uC57C \uD569\uB2C8\uB2E4. (\uD504\uB85C\uC81D\uD2B8 \uC6CC\uD06C\uD2B8\uB9AC \uBBF8\uCEE4\uBC0B \uBCC0\uACBD \uC874\uC7AC)",
       workflowPrLinkMissing: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC PR \uB9C1\uD06C\uAC00 \uBE44\uC5B4\uC788\uC2B5\uB2C8\uB2E4. (tasks.md\uC758 PR \uD544\uB4DC\uB97C \uCC44\uC6B0\uC138\uC694.)",
       workflowPrStatusMissing: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC PR \uC0C1\uD0DC\uAC00 \uBE44\uC5B4\uC788\uC2B5\uB2C8\uB2E4. (tasks.md\uC758 PR \uC0C1\uD0DC\uB97C Review/Approved \uC911 \uD558\uB098\uB85C \uC124\uC815\uD558\uC138\uC694.)",
       workflowPrStatusNotApproved: "\uC644\uB8CC \uC0C1\uD0DC\uC774\uC9C0\uB9CC PR \uC0C1\uD0DC\uAC00 Approved\uAC00 \uC544\uB2D9\uB2C8\uB2E4. (merge \uD6C4 PR \uC0C1\uD0DC\uB97C Approved\uB85C \uC5C5\uB370\uC774\uD2B8\uD558\uC138\uC694.)"
@@ -319,10 +325,12 @@ var I18N = {
       "context.tipShowAll": "Show all",
       "context.tipShowDone": "Show done only",
       "context.checkRequired": "[CHECK required] ",
-      "context.checkPolicyHint": "\u2139\uFE0F  User check policy: see /docs/agents/agents.md (includes git push/merge and merge commits) \u2014 if you see [CHECK required], wait for `<label>` or `<label> OK` (e.g. `A`, `A OK`) before proceeding (config: approval can override)",
+      "context.checkPolicyHint": "\u2139\uFE0F  User check policy notice (not the current next action): see /docs/agents/agents.md (includes git push/merge and merge commits). If you see [CHECK required], wait for `<label>` or `<label> OK` (e.g. `A`, `A OK`) before proceeding (config: approval can override)",
       "context.actionOptionHint": "Approval reply format: `<label>` or `<label> OK` (e.g. `A`, `A OK`)",
+      "context.actionExplainHint": "Before requesting approval, explain what each label will run/change with a one-line summary.",
       "context.tipDocsCommitRules": "Commit message rules: /docs/agents/git-workflow.md",
       "context.list.docsCommitNeeded": "Commit docs changes",
+      "context.list.projectCommitNeeded": "Commit project code changes",
       "context.list.issueNumberNeeded": "Fill issue number in docs",
       "context.list.addPrMetadata": "Add PR metadata (PR/PR Status)",
       "context.list.recordPrLink": "Record PR link",
@@ -413,6 +421,8 @@ var I18N = {
       issueCreateAndWrite: "Create a GitHub Issue, fill the issue number in spec.md/tasks.md, then prepare a docs commit. (See skills/create-issue.md)",
       docsCommitIssueUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(#{issueNumber}): {folderName} docs update"',
       docsCommitUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs: {folderName} docs update"',
+      projectCommitIssueUpdate: 'cd "{projectGitCwd}" && git add -A && git commit -m "feat(#{issueNumber}): {folderName} implementation update"',
+      projectCommitUpdate: 'cd "{projectGitCwd}" && git add -A && git commit -m "feat: {folderName} implementation update"',
       standaloneNeedsProjectRoot: "Standalone mode requires projectRoot. (npx lee-spec-kit config --project-root ...)",
       createBranch: 'cd "{projectGitCwd}" && git checkout -b feat/{issueNumber}-{slug}',
       tasksAllDoneButNoChecklist: 'All tasks are DONE, but no completion checklist section was found. Add/verify the "Completion Criteria" section in tasks.md.',
@@ -433,11 +443,13 @@ var I18N = {
       docsGitUnavailable: "Cannot read git status for the docs repo. (Check repo location / git init.)",
       docsPathIgnored: "Current feature docs path is ignored by git: {path} (docs commit detection may be limited).",
       docsUncommittedChanges: "Docs changes are not committed. (Additional docs commit needed.) Commit message rules: /docs/agents/git-workflow.md",
+      projectUncommittedChanges: "Project code changes are not committed. (Additional code commit needed.)",
       legacyTasksDocStatusField: "Legacy tasks.md format detected. Add a `Doc Status` field (Review/Approved) to enable tasks approval.",
       legacyTasksPrFields: "Legacy tasks.md format detected. Add `PR` and `PR Status` fields before PR steps.",
       workflowSpecNotApproved: "Implementation is done but spec.md Status is not Approved. (Update spec.md Status to Approved.)",
       workflowPlanNotApproved: "Implementation is done but plan.md Status is not Approved. (Update plan.md Status to Approved.)",
       workflowIssueMissing: "Implementation is done but Issue Number is missing. (Fill Issue Number in spec.md/tasks.md.)",
+      workflowProjectUncommittedChanges: "Commit project code changes before completing workflow. (Project worktree has uncommitted changes.)",
       workflowPrLinkMissing: "Implementation is done but PR link is missing. (Fill the PR field in tasks.md.)",
       workflowPrStatusMissing: "Implementation is done but PR Status is missing. (Set PR Status to Review/Approved in tasks.md.)",
       workflowPrStatusNotApproved: "Implementation is done but PR Status is not Approved. (After merge, update PR Status to Approved in tasks.md.)"
@@ -1628,7 +1640,7 @@ Store ${component} feature specs here.
         lang,
         createdAt: getLocalDateString(),
         docsRepo,
-        workflow: { mode: workflowMode },
+        workflow: { mode: workflowMode, codeDirtyScope: "auto" },
         pr: {
           screenshots: { upload: false }
         },
@@ -1858,13 +1870,39 @@ async function getConfig(cwd) {
 
 // src/commands/feature.ts
 function featureCommand(program2) {
-  program2.command("feature <name>").description("Create a new feature folder").option("-r, --repo <repo>", "Component name (multi only)").option("--component <component>", "Component name (multi only)").option("--id <id>", "Feature ID (default: auto)").option("-d, --desc <description>", "Feature description for spec.md").option("--non-interactive", "Fail instead of prompting for input").action(async (name, options) => {
+  program2.command("feature <name>").description("Create a new feature folder").option("-r, --repo <repo>", "Component name (multi only)").option("--component <component>", "Component name (multi only)").option("--id <id>", "Feature ID (default: auto)").option("-d, --desc <description>", "Feature description for spec.md").option("--non-interactive", "Fail instead of prompting for input").option("--json", "Output in JSON format for agents").action(async (name, options) => {
     try {
-      await runFeature(name, options);
+      const result = await runFeature(name, options);
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              status: "ok",
+              reasonCode: "FEATURE_CREATED",
+              featureId: result.featureId,
+              featureName: result.featureName,
+              component: result.component,
+              featurePath: result.featurePath,
+              featurePathFromDocs: result.featurePathFromDocs
+            },
+            null,
+            2
+          )
+        );
+      }
     } catch (error) {
       if (error instanceof Error && error.message === "canceled") {
         const config2 = await getConfig(process.cwd());
         const lang2 = config2?.lang ?? DEFAULT_LANG;
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              status: "canceled",
+              reasonCode: "CANCELED"
+            })
+          );
+          process.exit(0);
+        }
         console.log(chalk6.yellow(`
 ${tr(lang2, "cli", "common.canceled")}`));
         process.exit(0);
@@ -1873,6 +1911,17 @@ ${tr(lang2, "cli", "common.canceled")}`));
       const lang = config?.lang ?? DEFAULT_LANG;
       const cliError = toCliError(error);
       const suggestions = getCliErrorSuggestions(cliError.code, lang);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+        process.exit(1);
+      }
       console.error(
         chalk6.red(tr(lang, "cli", "common.errorLabel")),
         chalk6.red(`[${cliError.code}] ${cliError.message}`)
@@ -1944,7 +1993,7 @@ async function runFeature(name, options) {
     assertAllowedComponent(component, configuredComponents);
   }
   const docsLockPath = getDocsLockPath(docsDir);
-  await withFileLock(
+  return withFileLock(
     docsLockPath,
     async () => {
       let featureId;
@@ -1980,6 +2029,8 @@ async function runFeature(name, options) {
         // ko placeholders
         "{\uAE30\uB2A5\uBA85}": name,
         "{\uBC88\uD638}": idNumber,
+        "{\uACB0\uC815 \uC81C\uBAA9}": `${name} \uACB0\uC815`,
+        "{YYYY-MM-DD}": getLocalDateString(),
         "YYYY-MM-DD": getLocalDateString(),
         "{be|fe}": component || "",
         "{\uC774\uC288\uBC88\uD638}": "",
@@ -1987,6 +2038,7 @@ async function runFeature(name, options) {
         // en placeholders
         "{feature-name}": name,
         "{number}": idNumber,
+        "{Decision Title}": `${name} design decision`,
         "{issue-number}": "",
         "{{projectName}}-{be|fe}": repoName
       };
@@ -2002,14 +2054,23 @@ async function runFeature(name, options) {
       if (config.workflow?.mode === "local") {
         await applyLocalWorkflowTemplateToFeatureDir(featureDir, lang);
       }
-      console.log();
-      console.log(chalk6.green(tr(lang, "cli", "feature.created", { path: featureDir })));
-      console.log();
-      console.log(chalk6.blue(tr(lang, "cli", "feature.nextStepsTitle")));
-      console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps1", { path: featureDir })));
-      console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps2")));
-      console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps3")));
-      console.log();
+      if (!options.json) {
+        console.log();
+        console.log(chalk6.green(tr(lang, "cli", "feature.created", { path: featureDir })));
+        console.log();
+        console.log(chalk6.blue(tr(lang, "cli", "feature.nextStepsTitle")));
+        console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps1", { path: featureDir })));
+        console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps2")));
+        console.log(chalk6.gray(tr(lang, "cli", "feature.nextSteps3")));
+        console.log();
+      }
+      return {
+        featureId,
+        featureName: name,
+        component: projectType === "multi" ? component : void 0,
+        featurePath: featureDir,
+        featurePathFromDocs: path13.relative(docsDir, featureDir)
+      };
     },
     { owner: "feature" }
   );
@@ -2112,6 +2173,15 @@ function resolveWorkflowPolicy(workflow) {
   }
   return policy;
 }
+function resolveCodeDirtyScopePolicy(workflow, projectType) {
+  const raw = workflow?.codeDirtyScope;
+  if (!raw) return "repo";
+  if (raw === "repo") return "repo";
+  if (raw === "component") {
+    return projectType === "multi" ? "component" : "repo";
+  }
+  return projectType === "multi" ? "component" : "repo";
+}
 
 // src/utils/context/steps.ts
 function isCompletionChecklistDone(feature) {
@@ -2127,7 +2197,7 @@ function isPrMetadataConfigured(feature) {
   return feature.docs.prFieldExists && feature.docs.prStatusFieldExists;
 }
 function isFeatureDone(feature, workflowPolicy) {
-  return feature.specStatus === "Approved" && feature.planStatus === "Approved" && feature.docs.tasksExists && feature.tasks.total > 0 && feature.tasks.total === feature.tasks.done && isCompletionChecklistDone(feature) && isTasksDocApproved(feature) && (!workflowPolicy.requireIssue || !!feature.issueNumber) && (!workflowPolicy.requirePr || isPrMetadataConfigured(feature) && !!feature.pr.link) && (!workflowPolicy.requireReview || feature.pr.status === "Approved");
+  return feature.specStatus === "Approved" && feature.planStatus === "Approved" && !feature.git.docsHasUncommittedChanges && !feature.git.projectHasUncommittedChanges && feature.docs.tasksExists && feature.tasks.total > 0 && feature.tasks.total === feature.tasks.done && isCompletionChecklistDone(feature) && isTasksDocApproved(feature) && (!workflowPolicy.requireIssue || !!feature.issueNumber) && (!workflowPolicy.requirePr || isPrMetadataConfigured(feature) && !!feature.pr.link) && (!workflowPolicy.requireReview || feature.pr.status === "Approved");
 }
 function getStepDefinitions(lang, workflow) {
   const workflowPolicy = resolveWorkflowPolicy(workflow);
@@ -2460,29 +2530,59 @@ function getStepDefinitions(lang, workflow) {
       step: 11,
       name: tr(lang, "steps", "docsCommitSync"),
       checklist: {
-        done: (f) => !f.git.docsHasUncommittedChanges
+        done: (f) => !f.git.docsHasUncommittedChanges && !f.git.projectHasUncommittedChanges
       },
       current: {
-        when: (f) => isImplementationDone(f) && f.git.docsHasUncommittedChanges,
-        actions: (f) => [
-          {
-            type: "command",
-            category: "docs_commit",
-            requiresUserCheck: true,
-            scope: "docs",
-            cwd: f.git.docsGitCwd,
-            cmd: f.issueNumber ? tr(lang, "messages", "docsCommitIssueUpdate", {
-              docsGitCwd: f.git.docsGitCwd,
-              featurePath: f.docs.featurePathFromDocs,
-              issueNumber: f.issueNumber,
-              folderName: f.folderName
-            }) : tr(lang, "messages", "docsCommitUpdate", {
-              docsGitCwd: f.git.docsGitCwd,
-              featurePath: f.docs.featurePathFromDocs,
-              folderName: f.folderName
-            })
+        when: (f) => isImplementationDone(f) && (f.git.docsHasUncommittedChanges || f.git.projectHasUncommittedChanges),
+        actions: (f) => {
+          if (f.git.docsHasUncommittedChanges) {
+            return [
+              {
+                type: "command",
+                category: "docs_commit",
+                requiresUserCheck: true,
+                scope: "docs",
+                cwd: f.git.docsGitCwd,
+                cmd: f.issueNumber ? tr(lang, "messages", "docsCommitIssueUpdate", {
+                  docsGitCwd: f.git.docsGitCwd,
+                  featurePath: f.docs.featurePathFromDocs,
+                  issueNumber: f.issueNumber,
+                  folderName: f.folderName
+                }) : tr(lang, "messages", "docsCommitUpdate", {
+                  docsGitCwd: f.git.docsGitCwd,
+                  featurePath: f.docs.featurePathFromDocs,
+                  folderName: f.folderName
+                })
+              }
+            ];
           }
-        ]
+          if (!f.git.projectGitCwd) {
+            return [
+              {
+                type: "instruction",
+                category: "task_execute",
+                message: tr(lang, "messages", "standaloneNeedsProjectRoot")
+              }
+            ];
+          }
+          return [
+            {
+              type: "command",
+              category: "task_execute",
+              requiresUserCheck: true,
+              scope: "project",
+              cwd: f.git.projectGitCwd,
+              cmd: f.issueNumber ? tr(lang, "messages", "projectCommitIssueUpdate", {
+                projectGitCwd: f.git.projectGitCwd,
+                issueNumber: f.issueNumber,
+                folderName: f.folderName
+              }) : tr(lang, "messages", "projectCommitUpdate", {
+                projectGitCwd: f.git.projectGitCwd,
+                folderName: f.folderName
+              })
+            }
+          ];
+        }
       }
     },
     {
@@ -2805,6 +2905,60 @@ function parsePrLink(value) {
   if (trimmed.includes("{") || trimmed.includes("}")) return void 0;
   return trimmed;
 }
+function normalizeGitPath(value) {
+  return value.split(path13.sep).join("/");
+}
+function resolveProjectStatusPaths(projectGitCwd, docsDir) {
+  const relativeDocsDir = path13.relative(projectGitCwd, docsDir);
+  if (!relativeDocsDir) return [];
+  if (path13.isAbsolute(relativeDocsDir)) return [];
+  if (relativeDocsDir === ".." || relativeDocsDir.startsWith(`..${path13.sep}`)) {
+    return [];
+  }
+  const normalizedDocsDir = normalizeGitPath(relativeDocsDir).replace(/\/+$/, "");
+  if (!normalizedDocsDir) return [];
+  return [".", `:(exclude)${normalizedDocsDir}/**`];
+}
+function uniqueNormalizedPaths(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const value of values) {
+    const normalized = normalizeGitPath(value).replace(/^\.\/+/, "").replace(/\/+$/, "");
+    if (!normalized || normalized === "." || normalized === "..") continue;
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+async function resolveComponentStatusPaths(projectGitCwd, component, workflow) {
+  const configured = workflow?.componentPaths?.[component];
+  const configuredCandidates = Array.isArray(configured) ? configured.map((value) => String(value).trim()).filter(Boolean) : [];
+  const candidates = configuredCandidates.length > 0 ? configuredCandidates : [
+    component,
+    `apps/${component}`,
+    `packages/${component}`,
+    `services/${component}`,
+    `modules/${component}`
+  ];
+  const normalizedCandidates = uniqueNormalizedPaths(
+    candidates.map((candidate) => {
+      if (!candidate) return "";
+      if (!path13.isAbsolute(candidate)) return candidate;
+      const relative = path13.relative(projectGitCwd, candidate);
+      if (!relative) return "";
+      if (relative === ".." || relative.startsWith(`..${path13.sep}`)) return "";
+      return relative;
+    }).filter(Boolean)
+  );
+  const existing = [];
+  for (const candidate of normalizedCandidates) {
+    if (await fs2.pathExists(path13.join(projectGitCwd, candidate))) {
+      existing.push(candidate);
+    }
+  }
+  return existing;
+}
 function parseTasks(content) {
   const summary = { total: 0, todo: 0, doing: 0, done: 0 };
   let activeTask;
@@ -2937,6 +3091,25 @@ async function parseFeature(featurePath, type, context, options) {
   );
   const docsStatus = getGitStatusPorcelain(context.docsGitCwd, [relativeFeaturePathFromDocs]);
   const docsHasUncommittedChanges = docsStatus === void 0 ? true : docsStatus.trim().length > 0;
+  const dirtyScopePolicy = resolveCodeDirtyScopePolicy(options.workflow, options.projectType);
+  let projectStatusPaths = [];
+  if (context.projectGitCwd) {
+    if (dirtyScopePolicy === "component" && type !== "single") {
+      const componentStatusPaths = await resolveComponentStatusPaths(
+        context.projectGitCwd,
+        type,
+        options.workflow
+      );
+      projectStatusPaths = componentStatusPaths.length > 0 ? componentStatusPaths : resolveProjectStatusPaths(context.projectGitCwd, context.docsDir);
+    } else {
+      projectStatusPaths = resolveProjectStatusPaths(
+        context.projectGitCwd,
+        context.docsDir
+      );
+    }
+  }
+  const projectStatus = context.projectGitCwd ? getGitStatusPorcelain(context.projectGitCwd, projectStatusPaths) : void 0;
+  const projectHasUncommittedChanges = projectStatus === void 0 ? false : projectStatus.trim().length > 0;
   const docsLastCommit = getLastCommitForPath(
     context.docsGitCwd,
     relativeFeaturePathFromDocs
@@ -2961,9 +3134,12 @@ async function parseFeature(featurePath, type, context, options) {
   if (docsEverCommitted && docsHasUncommittedChanges) {
     warnings.push(tr(lang, "warnings", "docsUncommittedChanges"));
   }
+  if (projectHasUncommittedChanges) {
+    warnings.push(tr(lang, "warnings", "projectUncommittedChanges"));
+  }
   const tasksDocApproved = !tasksDocStatusFieldExists || tasksDocStatus === "Approved";
   const implementationDone = tasksExists && tasksSummary.total > 0 && tasksSummary.total === tasksSummary.done && isCompletionChecklistDone2({ completionChecklist }) && tasksDocApproved;
-  const workflowDone = implementationDone && specStatus === "Approved" && planStatus === "Approved" && (!workflowPolicy.requireIssue || !!issueNumber) && (!workflowPolicy.requirePr || isPrMetadataConfigured2({ docs: { prFieldExists, prStatusFieldExists } }) && !!prLink) && (!workflowPolicy.requireReview || prStatus === "Approved");
+  const workflowDone = implementationDone && !docsHasUncommittedChanges && !projectHasUncommittedChanges && specStatus === "Approved" && planStatus === "Approved" && (!workflowPolicy.requireIssue || !!issueNumber) && (!workflowPolicy.requirePr || isPrMetadataConfigured2({ docs: { prFieldExists, prStatusFieldExists } }) && !!prLink) && (!workflowPolicy.requireReview || prStatus === "Approved");
   if (implementationDone && !workflowDone) {
     if (specStatus !== "Approved") {
       warnings.push(tr(lang, "warnings", "workflowSpecNotApproved"));
@@ -2974,6 +3150,9 @@ async function parseFeature(featurePath, type, context, options) {
     if (workflowPolicy.requireIssue && !issueNumber) {
       warnings.push(tr(lang, "warnings", "workflowIssueMissing"));
     }
+    if (projectHasUncommittedChanges) {
+      warnings.push(tr(lang, "warnings", "workflowProjectUncommittedChanges"));
+    }
     if (workflowPolicy.requirePr && prFieldExists && prStatusFieldExists) {
       if (!prLink) warnings.push(tr(lang, "warnings", "workflowPrLinkMissing"));
       if (workflowPolicy.requireReview) {
@@ -3012,6 +3191,7 @@ async function parseFeature(featurePath, type, context, options) {
       onExpectedBranch,
       docsEverCommitted,
       docsHasUncommittedChanges,
+      projectHasUncommittedChanges,
       docsPathIgnored: docsPathIgnored === true
     },
     docs: {
@@ -3075,7 +3255,8 @@ async function scanFeatures(config) {
               lang: config.lang,
               stepDefinitions,
               approval: config.approval,
-              workflow: config.workflow
+              workflow: config.workflow,
+              projectType: config.projectType
             }
           )
         );
@@ -3107,7 +3288,8 @@ async function scanFeatures(config) {
               lang: config.lang,
               stepDefinitions,
               approval: config.approval,
-              workflow: config.workflow
+              workflow: config.workflow,
+              projectType: config.projectType
             }
           )
         );
@@ -3326,7 +3508,8 @@ async function runUpdate(options) {
     async () => {
       const templatesDir = getTemplatesDir();
       const sourceDir = path13.join(templatesDir, lang, toTemplateProjectType(projectType));
-      const forceOverwrite = !!options.force || await isDocsWorktreeCleanOrThrow(docsDir, lang);
+      const docsLockPath = getDocsLockPath(docsDir);
+      const forceOverwrite = !!options.force || await isDocsWorktreeCleanOrThrow(docsDir, lang, [docsLockPath]);
       const hasExplicitSelection = !!(options.agents || options.skills || options.templates);
       const updateAgents = options.agents || options.skills || !hasExplicitSelection;
       const updateTemplates = options.templates || !hasExplicitSelection;
@@ -3483,22 +3666,56 @@ function getGitTopLevel2(cwd) {
     return null;
   }
 }
-function getDocsPorcelainStatus(docsDir) {
+function normalizeGitPath2(input) {
+  return input.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+function stripOuterQuotes(input) {
+  const trimmed = input.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+    return trimmed.slice(1, -1).replace(/\\"/g, '"');
+  }
+  return trimmed;
+}
+function extractPorcelainPaths(line) {
+  if (line.length < 4) return [];
+  const body = line.slice(3).trim();
+  if (!body) return [];
+  if (body.includes(" -> ")) {
+    return body.split(" -> ").map((part) => normalizeGitPath2(stripOuterQuotes(part)));
+  }
+  return [normalizeGitPath2(stripOuterQuotes(body))];
+}
+function getDocsPorcelainStatus(docsDir, ignoredAbsPaths = []) {
   const top = getGitTopLevel2(docsDir);
   if (!top) return null;
   const rel = path13.relative(top, docsDir) || ".";
   try {
-    return execFileSync("git", ["status", "--porcelain=v1", "--", rel], {
+    const output = execFileSync("git", ["status", "--porcelain=v1", "--", rel], {
       cwd: top,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     });
+    if (ignoredAbsPaths.length === 0) {
+      return output;
+    }
+    const ignoredRelPaths = new Set(
+      ignoredAbsPaths.map(
+        (absPath) => normalizeGitPath2(path13.relative(top, absPath) || ".")
+      )
+    );
+    const filtered = output.split("\n").filter((line) => {
+      if (!line.trim()) return false;
+      const touchedPaths = extractPorcelainPaths(line);
+      if (touchedPaths.length === 0) return true;
+      return touchedPaths.some((p) => !ignoredRelPaths.has(p));
+    }).join("\n");
+    return filtered;
   } catch {
     return null;
   }
 }
-async function isDocsWorktreeCleanOrThrow(docsDir, lang) {
-  const status = getDocsPorcelainStatus(docsDir);
+async function isDocsWorktreeCleanOrThrow(docsDir, lang, ignoredAbsPaths = []) {
+  const status = getDocsPorcelainStatus(docsDir, ignoredAbsPaths);
   if (status === null) {
     throw createCliError(
       "PRECONDITION_FAILED",
@@ -3652,6 +3869,22 @@ async function runConfig(options) {
     { owner: "config" }
   );
 }
+var REMOTE_ACTION_CATEGORIES = /* @__PURE__ */ new Set([
+  "issue_create",
+  "pr_create",
+  "pr_status_update",
+  "code_review"
+]);
+var LOCAL_ACTION_CATEGORIES = /* @__PURE__ */ new Set([
+  "docs_commit",
+  "branch_create",
+  "task_execute"
+]);
+var REMOTE_COMMAND_PATTERN = /\b(?:git\s+push|git\s+merge|gh\s+(?:issue|pr)\b)/i;
+function resolveComponentOption(options) {
+  const component = (options.component || options.repo || "").trim().toLowerCase();
+  return component || void 0;
+}
 function getActionLabel(index) {
   let n = index + 1;
   let label = "";
@@ -3662,11 +3895,67 @@ function getActionLabel(index) {
   }
   return label;
 }
+function resolveActionOperationType(action) {
+  if (action.operationType) return action.operationType;
+  if (action.type === "command") {
+    if (REMOTE_COMMAND_PATTERN.test(action.cmd)) return "remote";
+    return "local";
+  }
+  if (action.category && REMOTE_ACTION_CATEGORIES.has(action.category)) {
+    return "remote";
+  }
+  if (action.category && LOCAL_ACTION_CATEGORIES.has(action.category)) {
+    return "local";
+  }
+  return "manual";
+}
+function annotateActionOperationType(action) {
+  return {
+    ...action,
+    operationType: resolveActionOperationType(action)
+  };
+}
+function annotateActions(actions) {
+  return actions.map((action) => annotateActionOperationType(action));
+}
+function getActionSummary(action) {
+  if (action.category === "docs_commit") return "Commit docs updates";
+  if (action.category === "issue_create") return "Create and record issue";
+  if (action.category === "branch_create") return "Create feature branch";
+  if (action.category === "pr_create") return "Create PR and record link";
+  if (action.category === "pr_status_update") return "Update PR status";
+  if (action.category === "code_review") return "Process code review feedback";
+  if (action.category === "task_execute") return "Proceed with task execution";
+  if (action.category === "feature_done") return "Feature is complete";
+  if (action.category === "spec_approve") return "Request spec approval";
+  if (action.category === "plan_approve") return "Request plan approval";
+  if (action.category === "tasks_approve") return "Request tasks approval";
+  if (action.category === "pr_metadata_migrate") return "Update tasks.md to latest PR fields";
+  if (action.category === "fallback") return "Re-check context and rerun";
+  if (action.type === "command") {
+    return action.scope === "docs" ? "Run docs command" : "Run project command";
+  }
+  return action.message;
+}
+function formatActionSummary(action) {
+  if (action.type === "command") {
+    return `(${action.scope}) ${action.cmd}`;
+  }
+  return action.message;
+}
 function toActionOptions(actions) {
-  return actions.map((action, index) => ({
-    label: getActionLabel(index),
-    action
-  }));
+  return actions.map((action, index) => {
+    const label = getActionLabel(index);
+    const summary = getActionSummary(action);
+    const detail = formatActionSummary(action);
+    return {
+      label,
+      summary,
+      detail,
+      approvalPrompt: `${label}: ${summary}`,
+      action
+    };
+  });
 }
 function buildActionSnapshot(actionOptions) {
   return actionOptions.map(({ label, action }) => {
@@ -3678,6 +3967,7 @@ function buildActionSnapshot(actionOptions) {
         cwd: action.cwd,
         cmd: action.cmd,
         category: action.category,
+        operationType: action.operationType,
         requiresUserCheck: !!action.requiresUserCheck
       };
     }
@@ -3686,6 +3976,7 @@ function buildActionSnapshot(actionOptions) {
       type: action.type,
       message: action.message,
       category: action.category,
+      operationType: action.operationType,
       requiresUserCheck: !!action.requiresUserCheck
     };
   });
@@ -3700,20 +3991,21 @@ function getContextVersion(feature, actionOptions) {
   });
   return createHash("sha256").update(payload).digest("hex").slice(0, 12);
 }
-function parseApprovalLabel(input) {
-  const match = input.trim().match(/^([A-Z]+)(?:\s+OK)?$/i);
-  if (!match) return null;
-  return match[1].toUpperCase();
-}
-function listLabels(actionOptions) {
-  if (actionOptions.length === 0) return "-";
-  return actionOptions.map((o) => o.label).join(", ");
+function matchesFeatureSelector(f, selector) {
+  const s = selector.trim();
+  if (!s) return false;
+  if (f.folderName.toLowerCase() === s.toLowerCase()) return true;
+  if (f.slug.toLowerCase() === s.toLowerCase()) return true;
+  if (f.id && f.id.toLowerCase() === s.toLowerCase()) return true;
+  return false;
 }
-function formatActionSummary(action) {
-  if (action.type === "command") {
-    return `(${action.scope}) ${action.cmd}`;
-  }
-  return action.message;
+function detectFromBranch(branchName, features) {
+  const match = branchName.match(/^feat\/\d+-(.+)$/);
+  if (!match) return [];
+  const detected = match[1];
+  return features.filter(
+    (f) => f.slug.toLowerCase() === detected.toLowerCase() || f.folderName.toLowerCase() === detected.toLowerCase()
+  );
 }
 function toSelectionStatus(features, selectionMode, openFeatures, targetFeatures) {
   const isNoOpen = selectionMode === "open" && features.length > 0 && openFeatures.length === 0;
@@ -3730,15 +4022,9 @@ function toReasonCode(status) {
   if (status === "multiple_active") return "MULTIPLE_ACTIVE_FEATURES";
   return "NO_MATCHED_FEATURES";
 }
-async function resolveContextState(config, featureName, options) {
-  if (!config) {
-    throw createCliError(
-      "CONFIG_NOT_FOUND",
-      tr(DEFAULT_LANG, "cli", "common.configNotFound")
-    );
-  }
+async function resolveContextSelection(config, featureName, options) {
   const { features, branches, warnings } = await scanFeatures(config);
-  const selectedComponent = (options.component || options.repo || "").trim().toLowerCase();
+  const selectedComponent = resolveComponentOption(options);
   const scopedFeatures = selectedComponent ? features.filter((f) => f.type === selectedComponent) : features;
   const doneFeatures = scopedFeatures.filter((f) => f.completion.workflowDone);
   const openFeatures = scopedFeatures.filter((f) => !f.completion.workflowDone);
@@ -3750,6 +4036,7 @@ async function resolveContextState(config, featureName, options) {
   );
   let targetFeatures = [];
   let selectionMode = "explicit";
+  let selectionFallback = "none";
   if (featureName) {
     targetFeatures = scopedFeatures.filter(
       (f) => matchesFeatureSelector(f, featureName)
@@ -3782,15 +4069,19 @@ async function resolveContextState(config, featureName, options) {
     }
     if (targetFeatures.length > 0) {
       selectionMode = "branch";
+      selectionFallback = "none";
     } else if (options.all) {
       targetFeatures = scopedFeatures;
       selectionMode = "all";
+      selectionFallback = "all_features";
     } else if (options.done) {
       targetFeatures = doneFeatures;
       selectionMode = "done";
+      selectionFallback = "done_features";
     } else {
       targetFeatures = openFeatures;
       selectionMode = "open";
+      selectionFallback = "open_features";
     }
   }
   const status = toSelectionStatus(
@@ -3800,7 +4091,7 @@ async function resolveContextState(config, featureName, options) {
     targetFeatures
   );
   const matchedFeature = targetFeatures.length === 1 ? targetFeatures[0] : null;
-  const actions = matchedFeature?.actions ?? [];
+  const actions = annotateActions(matchedFeature?.actions ?? []);
   const actionOptions = toActionOptions(actions);
   const contextVersion = getContextVersion(matchedFeature, actionOptions);
   return {
@@ -3812,6 +4103,7 @@ async function resolveContextState(config, featureName, options) {
     inProgressFeatures,
     readyToCloseFeatures,
     selectionMode,
+    selectionFallback,
     targetFeatures,
     status,
     matchedFeature,
@@ -3820,6 +4112,32 @@ async function resolveContextState(config, featureName, options) {
     contextVersion
   };
 }
+
+// src/commands/context.ts
+async function resolveContextState(config, featureName, options) {
+  if (!config) {
+    throw createCliError(
+      "CONFIG_NOT_FOUND",
+      tr(DEFAULT_LANG, "cli", "common.configNotFound")
+    );
+  }
+  return resolveContextSelection(config, featureName, options);
+}
+function parseApprovalLabel(input) {
+  const match = input.trim().match(/^([A-Z]+)(?:\s+OK)?$/i);
+  if (!match) return null;
+  return match[1].toUpperCase();
+}
+function listLabels(actionOptions) {
+  if (actionOptions.length === 0) return "-";
+  return actionOptions.map((o) => o.label).join(", ");
+}
+function formatActionSummary2(action) {
+  if (action.type === "command") {
+    return `(${action.scope}) ${action.cmd}`;
+  }
+  return action.message;
+}
 function executeCommandAction(cmd, jsonMode, cwd) {
   const shellPath = process.env.SHELL || (process.platform === "win32" ? process.env.ComSpec || "cmd.exe" : "/bin/sh");
   if (jsonMode) {
@@ -3878,27 +4196,14 @@ function contextCommand(program2) {
     }
   );
 }
-function matchesFeatureSelector(f, selector) {
-  const s = selector.trim();
-  if (!s) return false;
-  if (f.folderName.toLowerCase() === s.toLowerCase()) return true;
-  if (f.slug.toLowerCase() === s.toLowerCase()) return true;
-  if (f.id && f.id.toLowerCase() === s.toLowerCase()) return true;
-  return false;
-}
-function detectFromBranch(branchName, features) {
-  const match = branchName.match(/^feat\/\d+-(.+)$/);
-  if (!match) return [];
-  const detected = match[1];
-  return features.filter(
-    (f) => f.slug.toLowerCase() === detected.toLowerCase() || f.folderName.toLowerCase() === detected.toLowerCase()
-  );
-}
 function getListLabel(f, stepsMap, lang, workflowPolicy) {
   if (f.completion.implementationDone && !f.completion.workflowDone) {
     if (f.git.docsHasUncommittedChanges) {
       return tr(lang, "cli", "context.list.docsCommitNeeded");
     }
+    if (f.git.projectHasUncommittedChanges) {
+      return tr(lang, "cli", "context.list.projectCommitNeeded");
+    }
     if (workflowPolicy.requireIssue && !f.issueNumber) {
       return tr(lang, "cli", "context.list.issueNumberNeeded");
     }
@@ -3984,10 +4289,12 @@ async function runContext(featureName, options) {
     return;
   }
   if (options.json) {
+    const primaryAction = state.actionOptions[0] ?? null;
     const result = {
       status: state.status,
       reasonCode: toReasonCode(state.status),
       selectionMode: state.selectionMode,
+      selectionFallback: state.selectionFallback,
       branches: state.branches,
       warnings: state.warnings,
       matchedFeature: state.matchedFeature,
@@ -3999,19 +4306,37 @@ async function runContext(featureName, options) {
       readyToCloseCandidates: state.selectionMode === "open" ? state.readyToCloseFeatures : [],
       actions: state.actions,
       actionOptions: state.actionOptions,
+      primaryActionLabel: primaryAction?.label ?? null,
+      primaryActionType: primaryAction?.action.type ?? null,
+      primaryActionCategory: primaryAction?.action.category ?? null,
+      primaryActionOperationType: primaryAction?.action.operationType ?? null,
       workflowPolicy,
       checkPolicy: {
         docPath: "/docs/agents/agents.md",
         hint: tr(lang, "cli", "context.checkPolicyHint"),
+        policyOnly: true,
         token: "<LABEL>",
         acceptedTokens: ["<LABEL>", "<LABEL> OK"],
         tokenPattern: "^([A-Z]+)(?:\\s+OK)?$",
         validLabels: state.actionOptions.map((o) => o.label),
+        requireExplanationBeforeApproval: true,
+        requiredExplanationFields: ["actionOptions[].summary", "actionOptions[].approvalPrompt"],
+        recommendation: "Before asking for approval, explain each label with summary and then ask for `<LABEL>` or `<LABEL> OK`.",
         oneApprovalPerAction: true,
         requireFreshContext: true,
         contextVersion: state.contextVersion,
         config: config.approval ?? { mode: "builtin" }
       },
+      approvalRequest: {
+        guidance: "Present each label with summary (e.g. `A: <summary>`) before asking for approval.",
+        options: state.actionOptions.map((o) => ({
+          label: o.label,
+          summary: o.summary,
+          approvalPrompt: o.approvalPrompt,
+          requiresUserCheck: !!o.action.requiresUserCheck,
+          operationType: o.action.operationType
+        }))
+      },
       prPolicy: {
         screenshots: {
           upload: config.pr?.screenshots?.upload ?? false
@@ -4217,7 +4542,7 @@ async function runContext(featureName, options) {
     console.log();
     return;
   }
-  const actionOptions = toActionOptions(f.actions);
+  const actionOptions = state.actionOptions;
   console.log(chalk6.green(chalk6.bold("\u{1F449} Next Options (Atomic):")));
   let hasDocsCommand = false;
   actionOptions.forEach(({ label, action }) => {
@@ -4235,6 +4560,7 @@ async function runContext(featureName, options) {
   }
   if (hasCheckAction) {
     console.log(chalk6.gray(`   \u21B3 ${tr(lang, "cli", "context.actionOptionHint")}`));
+    console.log(chalk6.gray(`   \u21B3 ${tr(lang, "cli", "context.actionExplainHint")}`));
   }
   console.log();
 }
@@ -4302,7 +4628,7 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
     }
     console.log();
     console.log(chalk6.green(`\u2705 Approved option: ${parsedLabel}`));
-    console.log(chalk6.gray(`   - Action: ${formatActionSummary(selectedAction)}`));
+    console.log(chalk6.gray(`   - Action: ${formatActionSummary2(selectedAction)}`));
     if (selectedAction.type === "command") {
       console.log(chalk6.gray("   - Run with: --execute"));
     } else {
@@ -4559,8 +4885,7 @@ async function applyDoctorFixes(config, cwd, features, dryRun) {
     const files = [
       "spec.md",
       "plan.md",
-      "tasks.md",
-      "decisions.md"
+      "tasks.md"
     ];
     for (const file of files) {
       const fullPath = path13.join(f.path, file);
@@ -4629,7 +4954,7 @@ async function checkDocsStructure(config, cwd) {
   }
   return issues;
 }
-async function checkFeatures(config, cwd, features) {
+async function checkFeatures(config, cwd, features, decisionsPlaceholderMode) {
   const issues = [];
   if (features.length === 0) {
     issues.push({
@@ -4647,7 +4972,7 @@ async function checkFeatures(config, cwd, features) {
     idMap.get(id).push(rel);
     const isInitialTemplateState = f.docs.specExists && f.docs.planExists && f.docs.tasksExists && !f.specStatus && !f.planStatus && f.tasks.total === 0 && (!f.docs.tasksDocStatusFieldExists || !f.tasksDocStatus || f.tasksDocStatus === "Draft");
     if (!isInitialTemplateState) {
-      const featureDocs = ["spec.md", "plan.md", "tasks.md", "decisions.md"];
+      const featureDocs = ["spec.md", "plan.md", "tasks.md"];
       for (const file of featureDocs) {
         const p = path13.join(f.path, file);
         if (!await fs2.pathExists(p)) continue;
@@ -4663,6 +4988,23 @@ async function checkFeatures(config, cwd, features) {
           path: formatPath(cwd, p)
         });
       }
+      if (decisionsPlaceholderMode !== "off") {
+        const decisionsPath = path13.join(f.path, "decisions.md");
+        if (await fs2.pathExists(decisionsPath)) {
+          const content = await fs2.readFile(decisionsPath, "utf-8");
+          const placeholders = detectPlaceholders(content);
+          if (placeholders.length > 0) {
+            issues.push({
+              level: decisionsPlaceholderMode,
+              code: "placeholder_left_decisions",
+              message: tr(config.lang, "cli", "doctor.issue.placeholdersLeft", {
+                placeholders: placeholders.join(", ")
+              }),
+              path: formatPath(cwd, decisionsPath)
+            });
+          }
+        }
+      }
     }
     if (!f.docs.specExists) {
       issues.push({
@@ -4741,7 +5083,11 @@ function hasFixableIssues(issues) {
   return issues.some((issue) => FIXABLE_ISSUE_CODES.has(issue.code));
 }
 function doctorCommand(program2) {
-  program2.command("doctor").description("Validate docs structure and feature metadata").option("--json", "Output in JSON format for agents").option("--fix", "Automatically apply safe fixes for common docs issues").option("--dry-run", "Show potential fixes without writing files (requires --fix)").option("-s, --strict", "Exit with non-zero code when issues are found").action(async (options) => {
+  program2.command("doctor").description("Validate docs structure and feature metadata").option("--json", "Output in JSON format for agents").option("--fix", "Automatically apply safe fixes for common docs issues").option("--dry-run", "Show potential fixes without writing files (requires --fix)").option(
+    "--decisions-placeholders <mode>",
+    "decisions.md placeholder severity: off | info | warn (default: info)",
+    "info"
+  ).option("-s, --strict", "Exit with non-zero code when issues are found").action(async (options) => {
     try {
       const cwd = process.cwd();
       const config = await getConfig(cwd);
@@ -4757,6 +5103,14 @@ function doctorCommand(program2) {
           "`--dry-run` requires `--fix`."
         );
       }
+      const rawDecisionsMode = (options.decisionsPlaceholders || "info").trim().toLowerCase();
+      if (rawDecisionsMode !== "off" && rawDecisionsMode !== "info" && rawDecisionsMode !== "warn") {
+        throw createCliError(
+          "INVALID_ARGUMENT",
+          "`--decisions-placeholders` must be one of: off, info, warn."
+        );
+      }
+      const decisionsPlaceholderMode = rawDecisionsMode;
       const { docsDir, projectType, lang } = config;
       let scan = await scanFeatures(config);
       let features = scan.features;
@@ -4764,7 +5118,14 @@ function doctorCommand(program2) {
       let warnings = scan.warnings;
       let issues = [];
       issues.push(...await checkDocsStructure({ docsDir, projectType, lang }, cwd));
-      issues.push(...await checkFeatures({ docsDir, projectType, lang }, cwd, features));
+      issues.push(
+        ...await checkFeatures(
+          { docsDir, projectType, lang },
+          cwd,
+          features,
+          decisionsPlaceholderMode
+        )
+      );
       let fixResult = null;
       if (options.fix) {
         if (hasFixableIssues(issues)) {
@@ -4789,25 +5150,35 @@ function doctorCommand(program2) {
           warnings = scan.warnings;
           issues = [];
           issues.push(...await checkDocsStructure({ docsDir, projectType, lang }, cwd));
-          issues.push(...await checkFeatures({ docsDir, projectType, lang }, cwd, features));
+          issues.push(
+            ...await checkFeatures(
+              { docsDir, projectType, lang },
+              cwd,
+              features,
+              decisionsPlaceholderMode
+            )
+          );
         }
       }
-      const hasIssues = issues.length > 0;
+      const nonInfoIssues = issues.filter((i) => i.level !== "info");
+      const hasIssues = nonInfoIssues.length > 0;
       const hasErrors = issues.some((i) => i.level === "error");
+      const hasWarns = issues.some((i) => i.level === "warn");
       const exitCode = options.strict && hasIssues ? 1 : 0;
       if (options.json) {
         console.log(
           JSON.stringify(
             {
-              status: hasErrors ? "error" : hasIssues ? "warn" : "ok",
+              status: hasErrors ? "error" : hasWarns ? "warn" : "ok",
               meta: { docsDir, projectType, lang },
               branches,
               warnings,
               counts: {
                 features: features.length,
-                issues: issues.length,
+                issues: nonInfoIssues.length,
                 errors: issues.filter((i) => i.level === "error").length,
-                warnings: issues.filter((i) => i.level === "warn").length
+                warnings: issues.filter((i) => i.level === "warn").length,
+                infos: issues.filter((i) => i.level === "info").length
               },
               fixes: fixResult ? {
                 enabled: fixResult.enabled,
@@ -4844,13 +5215,18 @@ function doctorCommand(program2) {
         }
         console.log();
       }
-      if (!hasIssues) {
+      const errors = issues.filter((i) => i.level === "error");
+      const warns = issues.filter((i) => i.level === "warn");
+      const infos = issues.filter((i) => i.level === "info");
+      if (!hasIssues && infos.length === 0) {
         console.log(chalk6.green(tr(lang, "cli", "doctor.noIssues")));
         console.log();
         process.exit(0);
       }
-      const errors = issues.filter((i) => i.level === "error");
-      const warns = issues.filter((i) => i.level === "warn");
+      if (!hasIssues && infos.length > 0) {
+        console.log(chalk6.green(tr(lang, "cli", "doctor.noIssues")));
+        console.log();
+      }
       if (errors.length > 0) {
         console.log(
           chalk6.red(
@@ -4875,6 +5251,13 @@ function doctorCommand(program2) {
         );
         console.log();
       }
+      if (infos.length > 0) {
+        console.log(chalk6.blue(`\u2139\uFE0F  Info (${infos.length})`));
+        infos.forEach(
+          (i) => console.log(chalk6.blue(`  - ${i.message}${i.path ? ` (${i.path})` : ""}`))
+        );
+        console.log();
+      }
       console.log(
         chalk6.gray(
           tr(lang, "cli", "doctor.tipJson", {
@@ -4913,182 +5296,13 @@ function doctorCommand(program2) {
     }
   });
 }
-function resolveComponentOption(options) {
-  const component = (options.component || options.repo || "").trim().toLowerCase();
-  return component || void 0;
-}
-function getActionLabel2(index) {
-  let n = index + 1;
-  let label = "";
-  while (n > 0) {
-    const rem = (n - 1) % 26;
-    label = String.fromCharCode(65 + rem) + label;
-    n = Math.floor((n - 1) / 26);
-  }
-  return label;
-}
-function toActionOptions2(actions) {
-  return actions.map((action, index) => ({
-    label: getActionLabel2(index),
-    action
-  }));
-}
-function buildActionSnapshot2(actionOptions) {
-  return actionOptions.map(({ label, action }) => {
-    if (action.type === "command") {
-      return {
-        label,
-        type: action.type,
-        scope: action.scope,
-        cwd: action.cwd,
-        cmd: action.cmd,
-        category: action.category,
-        requiresUserCheck: !!action.requiresUserCheck
-      };
-    }
-    return {
-      label,
-      type: action.type,
-      message: action.message,
-      category: action.category,
-      requiresUserCheck: !!action.requiresUserCheck
-    };
-  });
-}
-function getContextVersion2(feature, actionOptions) {
-  if (!feature) return null;
-  const payload = JSON.stringify({
-    id: feature.id || "",
-    folderName: feature.folderName,
-    currentStep: feature.currentStep,
-    actionSnapshot: buildActionSnapshot2(actionOptions)
-  });
-  return createHash("sha256").update(payload).digest("hex").slice(0, 12);
-}
-function matchesFeatureSelector2(f, selector) {
-  const s = selector.trim();
-  if (!s) return false;
-  if (f.folderName.toLowerCase() === s.toLowerCase()) return true;
-  if (f.slug.toLowerCase() === s.toLowerCase()) return true;
-  if (f.id && f.id.toLowerCase() === s.toLowerCase()) return true;
-  return false;
-}
-function detectFromBranch2(branchName, features) {
-  const match = branchName.match(/^feat\/\d+-(.+)$/);
-  if (!match) return [];
-  const detected = match[1];
-  return features.filter(
-    (f) => f.slug.toLowerCase() === detected.toLowerCase() || f.folderName.toLowerCase() === detected.toLowerCase()
-  );
-}
-function toSelectionStatus2(features, selectionMode, openFeatures, targetFeatures) {
-  const isNoOpen = selectionMode === "open" && features.length > 0 && openFeatures.length === 0;
-  if (features.length === 0) return "no_features";
-  if (isNoOpen) return "no_open";
-  if (targetFeatures.length === 1) return "single_matched";
-  if (targetFeatures.length > 1) return "multiple_active";
-  return "no_match";
-}
-function toReasonCode2(status) {
-  if (status === "no_features") return "NO_FEATURES";
-  if (status === "no_open") return "NO_OPEN_FEATURES";
-  if (status === "single_matched") return "SINGLE_MATCHED";
-  if (status === "multiple_active") return "MULTIPLE_ACTIVE_FEATURES";
-  return "NO_MATCHED_FEATURES";
-}
-async function resolveContextSelection(config, featureName, options) {
-  const { features, branches, warnings } = await scanFeatures(config);
-  const selectedComponent = resolveComponentOption(options);
-  const scopedFeatures = selectedComponent ? features.filter((f) => f.type === selectedComponent) : features;
-  const doneFeatures = scopedFeatures.filter((f) => f.completion.workflowDone);
-  const openFeatures = scopedFeatures.filter((f) => !f.completion.workflowDone);
-  const inProgressFeatures = openFeatures.filter(
-    (f) => !f.completion.implementationDone
-  );
-  const readyToCloseFeatures = openFeatures.filter(
-    (f) => f.completion.implementationDone
-  );
-  let targetFeatures = [];
-  let selectionMode = "explicit";
-  if (featureName) {
-    targetFeatures = scopedFeatures.filter(
-      (f) => matchesFeatureSelector2(f, featureName)
-    );
-    selectionMode = "explicit";
-  } else {
-    if (config.projectType === "single") {
-      const branchName = branches.project.single || "";
-      targetFeatures = detectFromBranch2(branchName, scopedFeatures);
-    } else if (selectedComponent) {
-      const branchName = branches.project[selectedComponent] || "";
-      targetFeatures = detectFromBranch2(
-        branchName,
-        scopedFeatures
-      );
-    } else {
-      const matches = [];
-      const componentKeys = [...new Set(scopedFeatures.map((f) => f.type))].filter((key) => key !== "single");
-      for (const component of componentKeys) {
-        const branchName = branches.project[component] || "";
-        if (!branchName) continue;
-        matches.push(
-          ...detectFromBranch2(
-            branchName,
-            scopedFeatures.filter((f) => f.type === component)
-          )
-        );
-      }
-      targetFeatures = matches;
-    }
-    if (targetFeatures.length > 0) {
-      selectionMode = "branch";
-    } else if (options.all) {
-      targetFeatures = scopedFeatures;
-      selectionMode = "all";
-    } else if (options.done) {
-      targetFeatures = doneFeatures;
-      selectionMode = "done";
-    } else {
-      targetFeatures = openFeatures;
-      selectionMode = "open";
-    }
-  }
-  const status = toSelectionStatus2(
-    scopedFeatures,
-    selectionMode,
-    openFeatures,
-    targetFeatures
-  );
-  const matchedFeature = targetFeatures.length === 1 ? targetFeatures[0] : null;
-  const actions = matchedFeature?.actions ?? [];
-  const actionOptions = toActionOptions2(actions);
-  const contextVersion = getContextVersion2(matchedFeature, actionOptions);
-  return {
-    features: scopedFeatures,
-    branches,
-    warnings,
-    doneFeatures,
-    openFeatures,
-    inProgressFeatures,
-    readyToCloseFeatures,
-    selectionMode,
-    targetFeatures,
-    status,
-    matchedFeature,
-    actions,
-    actionOptions,
-    contextVersion
-  };
-}
-
-// src/commands/view.ts
-function resolveComponentOption2(options) {
-  if (options.repo && options.component && options.repo.trim().toLowerCase() !== options.component.trim().toLowerCase()) {
-    throw createCliError(
-      "INVALID_ARGUMENT",
-      "`--repo` and `--component` must reference the same value when both are provided."
-    );
-  }
+function resolveComponentOption2(options) {
+  if (options.repo && options.component && options.repo.trim().toLowerCase() !== options.component.trim().toLowerCase()) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      "`--repo` and `--component` must reference the same value when both are provided."
+    );
+  }
   const component = (options.component || options.repo || "").trim().toLowerCase();
   return component || void 0;
 }
@@ -5139,8 +5353,9 @@ async function runView(featureName, options) {
   if (options.json) {
     const payload = {
       status: state.status,
-      reasonCode: toReasonCode2(state.status),
+      reasonCode: toReasonCode(state.status),
       selectionMode: state.selectionMode,
+      selectionFallback: state.selectionFallback,
       counts: {
         features: state.features.length,
         open: state.openFeatures.length,
@@ -5187,7 +5402,7 @@ async function runView(featureName, options) {
   }
   if (!state.matchedFeature) {
     console.log();
-    console.log(chalk6.blue(`Selection: ${state.status} (${toReasonCode2(state.status)})`));
+    console.log(chalk6.blue(`Selection: ${state.status} (${toReasonCode(state.status)})`));
     const rows = state.targetFeatures.length > 0 ? state.targetFeatures : state.features;
     for (const f2 of rows) {
       const statusText = f2.completion.workflowDone ? chalk6.green("WORKFLOW_DONE") : f2.completion.implementationDone ? chalk6.cyan("DONE") : chalk6.yellow("IN_PROGRESS");
@@ -5375,16 +5590,18 @@ async function runFlow(featureName, options) {
       context: {
         before: {
           status: before.status,
-          reasonCode: toReasonCode2(before.status),
+          reasonCode: toReasonCode(before.status),
           selectionMode: before.selectionMode,
+          selectionFallback: before.selectionFallback,
           matchedFeature: before.matchedFeature,
           actionOptions: before.actionOptions,
           contextVersion: before.contextVersion
         },
         after: {
           status: after.status,
-          reasonCode: toReasonCode2(after.status),
+          reasonCode: toReasonCode(after.status),
           selectionMode: after.selectionMode,
+          selectionFallback: after.selectionFallback,
           matchedFeature: after.matchedFeature,
           actionOptions: after.actionOptions,
           contextVersion: after.contextVersion
@@ -5403,7 +5620,7 @@ async function runFlow(featureName, options) {
   console.log(chalk6.bold("\u{1F501} Flow Summary"));
   console.log(
     chalk6.gray(
-      `- Before: ${before.status} (${toReasonCode2(before.status)}) / After: ${after.status} (${toReasonCode2(after.status)})`
+      `- Before: ${before.status} (${toReasonCode(before.status)}) / After: ${after.status} (${toReasonCode(after.status)})`
     )
   );
   if (approvalResult && typeof approvalResult === "object") {
@@ -5439,6 +5656,626 @@ async function runFlow(featureName, options) {
   console.log(chalk6.gray("Tip: add --approve <LABEL> [--execute] to run the selected atomic action."));
   console.log();
 }
+function resolveComponentOption4(options) {
+  if (options.repo && options.component && options.repo.trim().toLowerCase() !== options.component.trim().toLowerCase()) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      "`--repo` and `--component` must reference the same value when both are provided."
+    );
+  }
+  const component = (options.component || options.repo || "").trim().toLowerCase();
+  return component || void 0;
+}
+function parseLabels(raw) {
+  const labels = (raw || "enhancement").split(",").map((part) => part.trim()).filter(Boolean);
+  if (labels.length === 0) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      "At least one label is required. Use `--labels enhancement`."
+    );
+  }
+  return [...new Set(labels)];
+}
+function runProcess(bin, args, cwd) {
+  const result = spawnSync(bin, args, {
+    cwd,
+    encoding: "utf-8",
+    env: {
+      ...process.env,
+      LEE_SPEC_KIT_NO_UPDATE_CHECK: "1",
+      LEE_SPEC_KIT_NO_BANNER: "1"
+    }
+  });
+  return {
+    code: result.status ?? 1,
+    stdout: result.stdout || "",
+    stderr: result.stderr || ""
+  };
+}
+function runProcessOrThrow(bin, args, cwd, failureMessage) {
+  const result = runProcess(bin, args, cwd);
+  if (result.code !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw createCliError(
+      "EXECUTION_FAILED",
+      `${failureMessage}${detail ? `: ${detail}` : ""}`
+    );
+  }
+  return result;
+}
+function runGhJson(args, cwd) {
+  const result = runProcessOrThrow("gh", args, cwd, "GitHub CLI command failed");
+  const text = result.stdout.trim();
+  if (!text) {
+    throw createCliError("EXECUTION_FAILED", "GitHub CLI returned empty JSON output.");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw createCliError(
+      "EXECUTION_FAILED",
+      `GitHub CLI returned invalid JSON: ${text.slice(0, 160)}`
+    );
+  }
+}
+function ensureSections(body, sections, kind) {
+  const missing = sections.filter((section) => {
+    const re = new RegExp(`^##\\s+${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
+    return !re.test(body);
+  });
+  if (missing.length > 0) {
+    throw createCliError(
+      "PRECONDITION_FAILED",
+      `${kind} body is missing required sections: ${missing.join(", ")}`
+    );
+  }
+}
+function ensureDocsExist(docsDir, relativePaths) {
+  const missing = relativePaths.filter(
+    (relativePath) => !fs2.existsSync(path13.join(docsDir, relativePath))
+  );
+  if (missing.length > 0) {
+    throw createCliError(
+      "PRECONDITION_FAILED",
+      `Related document paths do not exist: ${missing.join(", ")}`
+    );
+  }
+}
+function toBodyFilePath(raw, fallbackName) {
+  const selected = raw?.trim() || path13.join(os.tmpdir(), fallbackName);
+  return path13.resolve(selected);
+}
+async function resolveFeatureOrThrow(featureName, options) {
+  const config = await getConfig(process.cwd());
+  if (!config) {
+    throw createCliError(
+      "CONFIG_NOT_FOUND",
+      tr(DEFAULT_LANG, "cli", "common.configNotFound")
+    );
+  }
+  const state = await resolveContextSelection(config, featureName, options);
+  if (!state.matchedFeature) {
+    if (state.status === "no_features") {
+      throw createCliError("PRECONDITION_FAILED", "No features found.");
+    }
+    if (state.status === "multiple_active") {
+      throw createCliError(
+        "CONTEXT_SELECTION_REQUIRED",
+        "Multiple features matched. Specify feature name (slug | F001 | F001-slug)."
+      );
+    }
+    throw createCliError(
+      "CONTEXT_SELECTION_REQUIRED",
+      "Failed to auto-select a feature. Specify feature name explicitly."
+    );
+  }
+  return { config, feature: state.matchedFeature };
+}
+function getFeatureDocPaths(feature) {
+  const featurePathFromDocs = feature.docs.featurePathFromDocs;
+  return {
+    featurePathFromDocs,
+    specPath: `${featurePathFromDocs}/spec.md`,
+    planPath: `${featurePathFromDocs}/plan.md`,
+    tasksPath: `${featurePathFromDocs}/tasks.md`
+  };
+}
+function buildIssueBody(feature, labels, paths) {
+  return `## Overview
+
+Implement feature \`${feature.folderName}\`.
+
+## Goals
+
+- Finalize feature scope and implementation outcome
+- Keep spec/plan/tasks aligned with delivery
+
+## Completion Criteria
+
+- [ ] Scope and approach are documented clearly
+- [ ] Tasks are complete and verifiable
+- [ ] Related docs are synchronized
+
+## Related Documents
+
+- **Spec**: \`${paths.specPath}\`
+- **Plan**: \`${paths.planPath}\`
+- **Tasks**: \`${paths.tasksPath}\`
+
+## Labels
+
+${labels.map((label) => `- \`${label}\``).join("\n")}
+`;
+}
+function buildPrBody(feature, paths) {
+  const closes = feature.issueNumber ? `
+Closes #${feature.issueNumber}
+` : "\n";
+  return `## Overview
+
+Implement and document feature \`${feature.folderName}\`.
+
+## Changes
+
+- Deliver implementation for the feature scope
+- Update docs to match implementation and workflow state
+- Keep PR metadata synchronized in tasks.md
+
+## Tests
+
+### Tests Run
+
+- [x] \`<test command>\` \u2014 PASS
+
+## Related Documents
+
+- **Spec**: \`${paths.specPath}\`
+- **Tasks**: \`${paths.tasksPath}\`${closes}`;
+}
+function replaceListField(content, keys, value) {
+  for (const key of keys) {
+    const re = new RegExp(
+      `^(\\s*-\\s*\\*\\*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\*\\*\\s*:\\s*).*$`,
+      "m"
+    );
+    if (!re.test(content)) continue;
+    const next = content.replace(re, `$1${value}`);
+    return { content: next, changed: next !== content, found: true };
+  }
+  return { content, changed: false, found: false };
+}
+function insertFieldInGithubIssueSection(content, key, value) {
+  const lines = content.split("\n");
+  const headingIndex = lines.findIndex(
+    (line) => /^\s*##\s+(GitHub Issue|로컬 추적 정보|Local Tracking)\s*$/.test(line)
+  );
+  if (headingIndex < 0) return { content, changed: false };
+  let end = lines.length;
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    if (/^\s*##\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  lines.splice(end, 0, `- **${key}**: ${value}`);
+  return { content: lines.join("\n"), changed: true };
+}
+function syncTasksPrMetadata(tasksPath, prUrl, nextStatus) {
+  if (!fs2.existsSync(tasksPath)) {
+    throw createCliError("DOCS_NOT_FOUND", `tasks.md not found: ${tasksPath}`);
+  }
+  const original = fs2.readFileSync(tasksPath, "utf-8");
+  let next = original;
+  let changed = false;
+  const prReplaced = replaceListField(next, ["PR", "Pull Request"], prUrl);
+  next = prReplaced.content;
+  changed = changed || prReplaced.changed;
+  if (!prReplaced.found) {
+    const inserted = insertFieldInGithubIssueSection(next, "PR", prUrl);
+    next = inserted.content;
+    changed = changed || inserted.changed;
+  }
+  const statusReplaced = replaceListField(
+    next,
+    ["PR Status", "PR \uC0C1\uD0DC"],
+    nextStatus
+  );
+  next = statusReplaced.content;
+  changed = changed || statusReplaced.changed;
+  if (!statusReplaced.found) {
+    const inserted = insertFieldInGithubIssueSection(next, "PR Status", nextStatus);
+    next = inserted.content;
+    changed = changed || inserted.changed;
+  }
+  if (changed) {
+    fs2.writeFileSync(tasksPath, next, "utf-8");
+  }
+  return { changed, path: tasksPath };
+}
+function gitCurrentBranch(cwd) {
+  const result = runProcessOrThrow(
+    "git",
+    ["rev-parse", "--abbrev-ref", "HEAD"],
+    cwd,
+    "Failed to detect current git branch"
+  );
+  return result.stdout.trim();
+}
+function ensureCleanWorktree(cwd) {
+  const result = runProcessOrThrow(
+    "git",
+    ["status", "--porcelain=v1"],
+    cwd,
+    "Failed to inspect git worktree"
+  );
+  if (result.stdout.trim().length > 0) {
+    throw createCliError(
+      "PRECONDITION_FAILED",
+      "Git worktree is not clean. Commit or stash changes before merge retry sync."
+    );
+  }
+}
+function commitAndPushPath(cwd, absPath, message) {
+  const relativePath = path13.relative(cwd, absPath) || absPath;
+  const status = runProcessOrThrow(
+    "git",
+    ["status", "--porcelain=v1", "--", relativePath],
+    cwd,
+    "Failed to inspect git file status"
+  );
+  if (status.stdout.trim().length === 0) return;
+  runProcessOrThrow("git", ["add", "--", relativePath], cwd, "Failed to stage file");
+  runProcessOrThrow("git", ["commit", "-m", message], cwd, "Failed to commit synced metadata");
+  const branch = gitCurrentBranch(cwd);
+  runProcessOrThrow(
+    "git",
+    ["push", "-u", "origin", branch],
+    cwd,
+    "Failed to push synced metadata commit"
+  );
+}
+function shouldRefreshHeadBranch(stderr, stdout) {
+  const text = `${stderr}
+${stdout}`;
+  return /out of date|not possible to fast-forward|must be up to date|not up to date/i.test(
+    text
+  );
+}
+function refreshPrHeadBranch(prRef, cwd) {
+  ensureCleanWorktree(cwd);
+  const meta = runGhJson(
+    ["pr", "view", prRef, "--json", "url,headRefName,baseRefName"],
+    cwd
+  );
+  const originalBranch = gitCurrentBranch(cwd);
+  runProcessOrThrow(
+    "git",
+    ["fetch", "origin", meta.baseRefName, meta.headRefName],
+    cwd,
+    "Failed to fetch PR branches"
+  );
+  const hasLocalHead = runProcess(
+    "git",
+    ["show-ref", "--verify", "--quiet", `refs/heads/${meta.headRefName}`],
+    cwd
+  ).code === 0;
+  if (hasLocalHead) {
+    runProcessOrThrow(
+      "git",
+      ["checkout", meta.headRefName],
+      cwd,
+      "Failed to checkout PR head branch"
+    );
+  } else {
+    runProcessOrThrow(
+      "git",
+      ["checkout", "-B", meta.headRefName, `origin/${meta.headRefName}`],
+      cwd,
+      "Failed to create local PR head branch"
+    );
+  }
+  runProcessOrThrow(
+    "git",
+    ["rebase", `origin/${meta.baseRefName}`],
+    cwd,
+    "Failed to rebase PR head branch"
+  );
+  runProcessOrThrow(
+    "git",
+    ["push", "--force-with-lease", "origin", meta.headRefName],
+    cwd,
+    "Failed to push rebased PR head branch"
+  );
+  if (originalBranch !== meta.headRefName) {
+    runProcessOrThrow(
+      "git",
+      ["checkout", originalBranch],
+      cwd,
+      "Failed to restore previous branch after PR refresh"
+    );
+  }
+}
+function mergePrWithRetry(prRef, cwd, retryCount) {
+  const attempts = Number.isFinite(retryCount) ? Math.max(1, retryCount) : 3;
+  let lastError = "";
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const merged = runProcess(
+      "gh",
+      ["pr", "merge", prRef, "--squash", "--delete-branch"],
+      cwd
+    );
+    if (merged.code === 0) {
+      return { merged: true, attempts: attempt };
+    }
+    lastError = (merged.stderr || merged.stdout || "").trim();
+    if (shouldRefreshHeadBranch(merged.stderr, merged.stdout)) {
+      refreshPrHeadBranch(prRef, cwd);
+      continue;
+    }
+  }
+  throw createCliError(
+    "EXECUTION_FAILED",
+    `Failed to merge PR after retry attempts.${lastError ? ` Last error: ${lastError}` : ""}`
+  );
+}
+function toRetryCount(raw) {
+  if (!raw) return 3;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw createCliError("INVALID_ARGUMENT", "`--retry` must be a positive integer.");
+  }
+  return parsed;
+}
+function githubCommand(program2) {
+  const github = program2.command("github").description("GitHub workflow helpers (issue/pr templates, validation, merge retry)");
+  github.command("issue [feature-name]").description("Generate/create GitHub issue body from feature docs with validation").option("--json", "Output in JSON format for agents").option("--repo <repo>", "Component name for multi projects").option("--component <component>", "Component name for multi projects").option("--title <title>", "Issue title").option("--labels <labels>", "Comma-separated labels (default: enhancement)").option("--body-file <path>", "Issue body file output path").option("--assignee <assignee>", "Issue assignee (default: @me)").option("--create", "Create issue via gh CLI").action(async (featureName, options) => {
+    try {
+      const selectedComponent = resolveComponentOption4(options);
+      const { config, feature } = await resolveFeatureOrThrow(featureName, {
+        component: selectedComponent
+      });
+      const labels = parseLabels(options.labels);
+      const paths = getFeatureDocPaths(feature);
+      ensureDocsExist(config.docsDir, [paths.specPath, paths.planPath, paths.tasksPath]);
+      const title = options.title?.trim() || `${feature.slug} (${feature.folderName} documentation update)`;
+      const body = buildIssueBody(feature, labels, paths);
+      ensureSections(body, ["Overview", "Goals", "Completion Criteria", "Related Documents", "Labels"], "Issue");
+      const bodyFile = toBodyFilePath(
+        options.bodyFile,
+        `lee-spec-kit.issue.${feature.folderName}.md`
+      );
+      await fs2.ensureDir(path13.dirname(bodyFile));
+      await fs2.writeFile(bodyFile, body, "utf-8");
+      let issueUrl;
+      if (options.create) {
+        const args = [
+          "issue",
+          "create",
+          "--title",
+          title,
+          "--body-file",
+          bodyFile,
+          "--assignee",
+          options.assignee?.trim() || "@me"
+        ];
+        for (const label of labels) {
+          args.push("--label", label);
+        }
+        const created = runProcessOrThrow(
+          "gh",
+          args,
+          process.cwd(),
+          "Failed to create GitHub issue"
+        );
+        issueUrl = created.stdout.trim() || void 0;
+      }
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              status: "ok",
+              reasonCode: options.create ? "ISSUE_CREATED" : "ISSUE_TEMPLATE_GENERATED",
+              feature: feature.folderName,
+              component: feature.type,
+              title,
+              labels,
+              bodyFile,
+              issueUrl
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      console.log();
+      console.log(chalk6.bold("\u{1F9FE} GitHub Issue Helper"));
+      console.log(chalk6.gray(`- Feature: ${feature.folderName}`));
+      console.log(chalk6.gray(`- Body file: ${bodyFile}`));
+      console.log(chalk6.gray(`- Labels: ${labels.join(", ")}`));
+      if (issueUrl) {
+        console.log(chalk6.green(`\u2705 Created: ${issueUrl}`));
+      } else {
+        console.log(chalk6.blue("Template generated. Add --create to open the issue automatically."));
+      }
+      console.log();
+    } catch (error) {
+      const config = await getConfig(process.cwd());
+      const lang = config?.lang ?? DEFAULT_LANG;
+      const cliError = toCliError(error);
+      const suggestions = getCliErrorSuggestions(cliError.code, lang);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+      } else {
+        console.error(
+          chalk6.red(tr(lang, "cli", "common.errorLabel")),
+          chalk6.red(`[${cliError.code}] ${cliError.message}`)
+        );
+        printCliErrorSuggestions(suggestions, lang);
+      }
+      process.exit(1);
+    }
+  });
+  github.command("pr [feature-name]").description(
+    "Generate/create GitHub PR body with validation, tasks PR sync, and merge retry"
+  ).option("--json", "Output in JSON format for agents").option("--repo <repo>", "Component name for multi projects").option("--component <component>", "Component name for multi projects").option("--title <title>", "PR title").option("--labels <labels>", "Comma-separated labels (default: enhancement)").option("--body-file <path>", "PR body file output path").option("--assignee <assignee>", "PR assignee (default: @me)").option("--base <branch>", "PR base branch (default: main)", "main").option("--create", "Create PR via gh CLI").option("--pr <ref>", "Existing PR URL/number (used by --merge)").option("--merge", "Merge PR with retry and head-branch refresh").option("--retry <count>", "Retry count for merge (default: 3)").option("--no-sync-tasks", "Do not sync PR URL/PR status into tasks.md").option("--commit-sync", "Commit and push tasks.md metadata sync automatically").action(async (featureName, options) => {
+    try {
+      const selectedComponent = resolveComponentOption4(options);
+      const { config, feature } = await resolveFeatureOrThrow(featureName, {
+        component: selectedComponent
+      });
+      const labels = parseLabels(options.labels);
+      const paths = getFeatureDocPaths(feature);
+      ensureDocsExist(config.docsDir, [paths.specPath, paths.tasksPath]);
+      const defaultTitle = feature.issueNumber ? `feat(#${feature.issueNumber}): ${feature.slug} (implementation update)` : `feat: ${feature.slug} (implementation update)`;
+      const title = options.title?.trim() || defaultTitle;
+      const body = buildPrBody(feature, paths);
+      ensureSections(body, ["Overview", "Changes", "Tests", "Related Documents"], "PR");
+      const bodyFile = toBodyFilePath(
+        options.bodyFile,
+        `lee-spec-kit.pr.${feature.folderName}.md`
+      );
+      await fs2.ensureDir(path13.dirname(bodyFile));
+      await fs2.writeFile(bodyFile, body, "utf-8");
+      const retryCount = toRetryCount(options.retry);
+      let prUrl = options.pr?.trim() || "";
+      let mergedAttempts;
+      let syncChanged = false;
+      if (options.create) {
+        const args = [
+          "pr",
+          "create",
+          "--title",
+          title,
+          "--body-file",
+          bodyFile,
+          "--base",
+          options.base || "main",
+          "--assignee",
+          options.assignee?.trim() || "@me"
+        ];
+        for (const label of labels) {
+          args.push("--label", label);
+        }
+        const created = runProcessOrThrow(
+          "gh",
+          args,
+          process.cwd(),
+          "Failed to create GitHub PR"
+        );
+        prUrl = created.stdout.trim();
+      }
+      if (!prUrl && options.merge) {
+        throw createCliError(
+          "INVALID_ARGUMENT",
+          "`--merge` requires `--create` or `--pr <url|number>`."
+        );
+      }
+      if (prUrl && options.syncTasks !== false) {
+        const synced = syncTasksPrMetadata(
+          path13.join(config.docsDir, paths.tasksPath),
+          prUrl,
+          "Review"
+        );
+        syncChanged = synced.changed;
+        const shouldCommitSync = !!options.commitSync || !!options.merge;
+        if (syncChanged && shouldCommitSync) {
+          const issueSuffix = feature.issueNumber ? `#${feature.issueNumber}` : feature.folderName;
+          commitAndPushPath(
+            process.cwd(),
+            synced.path,
+            `docs(${issueSuffix}): sync PR metadata for ${feature.folderName}`
+          );
+        }
+      }
+      if (options.merge) {
+        const merged = mergePrWithRetry(prUrl, process.cwd(), retryCount);
+        mergedAttempts = merged.attempts;
+        const baseBranch = options.base || "main";
+        runProcessOrThrow(
+          "git",
+          ["checkout", baseBranch],
+          process.cwd(),
+          `Failed to checkout ${baseBranch} after merge`
+        );
+        runProcessOrThrow(
+          "git",
+          ["pull", "--rebase", "origin", baseBranch],
+          process.cwd(),
+          `Failed to update ${baseBranch} after merge`
+        );
+      }
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              status: "ok",
+              reasonCode: options.merge ? "PR_CREATED_SYNCED_MERGED" : options.create ? "PR_CREATED_SYNCED" : "PR_TEMPLATE_GENERATED",
+              feature: feature.folderName,
+              component: feature.type,
+              title,
+              labels,
+              bodyFile,
+              prUrl: prUrl || void 0,
+              syncChanged,
+              merged: !!options.merge,
+              mergeAttempts: mergedAttempts
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      console.log();
+      console.log(chalk6.bold("\u{1F500} GitHub PR Helper"));
+      console.log(chalk6.gray(`- Feature: ${feature.folderName}`));
+      console.log(chalk6.gray(`- Body file: ${bodyFile}`));
+      console.log(chalk6.gray(`- Labels: ${labels.join(", ")}`));
+      if (prUrl) {
+        console.log(chalk6.gray(`- PR: ${prUrl}`));
+      }
+      if (syncChanged) {
+        console.log(chalk6.green("\u2705 tasks.md PR metadata synced."));
+      }
+      if (options.merge) {
+        console.log(chalk6.green(`\u2705 PR merged (attempts: ${mergedAttempts ?? 1}).`));
+      } else if (!options.create) {
+        console.log(chalk6.blue("Template generated. Add --create to open the PR automatically."));
+      }
+      console.log();
+    } catch (error) {
+      const config = await getConfig(process.cwd());
+      const lang = config?.lang ?? DEFAULT_LANG;
+      const cliError = toCliError(error);
+      const suggestions = getCliErrorSuggestions(cliError.code, lang);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+      } else {
+        console.error(
+          chalk6.red(tr(lang, "cli", "common.errorLabel")),
+          chalk6.red(`[${cliError.code}] ${cliError.message}`)
+        );
+        printCliErrorSuggestions(suggestions, lang);
+      }
+      process.exit(1);
+    }
+  });
+}
 function isBannerDisabled() {
   const v = (process.env.LEE_SPEC_KIT_NO_BANNER || "").trim();
   return v === "1";
@@ -5607,4 +6444,5 @@ contextCommand(program);
 doctorCommand(program);
 viewCommand(program);
 flowCommand(program);
+githubCommand(program);
 await program.parseAsync();