lee-spec-kit 0.7.0 → 0.7.1

package/README.en.md

@@ -281,6 +281,7 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 - `--ticket` is required for `--execute` only when the selected action has `requiresUserCheck=true`.
 - It is short-lived (5 minutes by default) and cannot be reused after one execution.
 - When you `--execute` a handoff-only command (`pre_pr_review_run`, `code_review_run`), the result is `approved_handoff_prepared` with `nextMainState` instead of the normal `approved_executed`.
+- Treat `approved_handoff_prepared` as delegated-work-required: continue the delegated review/fix loop immediately, do not re-approve the same label, and refresh `context` only after the required evidence/state update.
 
 `context --json-compact` is the default recommended format, providing a minimal hot-path contract for agents.  
 Use `context --json` only when full-detail debugging fields are required.

package/dist/index.js

@@ -627,7 +627,7 @@ var koMessages = {
   prLegacyAsk: "tasks.md\uC5D0 PR/PR \uC0C1\uD0DC \uD544\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. \uD15C\uD50C\uB9BF\uC744 \uCD5C\uC2E0 \uD3EC\uB9F7\uC73C\uB85C \uC5C5\uB370\uC774\uD2B8\uD560\uAE4C\uC694? (\uD655\uC778 \uD544\uC694)",
   prePrReviewFieldMissing: "tasks.md\uC5D0 `PR \uC804 \uB9AC\uBDF0` \uD544\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. `- **PR \uC804 \uB9AC\uBDF0**: Pending | Running | Done` \uD56D\uBAA9\uC744 \uCD94\uAC00\uD558\uACE0 \uB2E4\uC2DC context\uB97C \uC2E4\uD589\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
   prePrReviewRun: "\uCF54\uB4DC \uB9AC\uBDF0 \uC5D0\uC774\uC804\uD2B8\uB97C \uC2E4\uD589\uD574 `spec.md`/`plan.md`/`tasks.md` \uB300\uBE44 \uAD6C\uD604 \uC801\uD569\uC131\uC744 \uAC80\uD1A0\uD558\uACE0, `Summary`/`Feature Intent Summary`/`Implementation Fit`/`Missing Cases`/`Spec Alignment Checked`/`Finding Count`/`Blocking Findings`/`Findings`/`Residual Risks`\uAC00 \uD3EC\uD568\uB41C `review-trace.json`\uC744 \uC0DD\uC131\uD55C \uB4A4 `pre-pr-review`\uB85C \uB9AC\uBDF0 \uACB0\uACFC\uB97C \uAE30\uB85D\uD558\uC138\uC694. `pre-pr-review-run` \uC790\uCCB4\uB294 evidence\uB97C \uC0DD\uC131\uD558\uAC70\uB098 \uC0C1\uD0DC\uB97C \uBC14\uB85C \uB118\uAE30\uC9C0 \uC54A\uC73C\uBA70, \uD604\uC7AC evidence \uC815\uCC45\uC774 \uACBD\uB85C\uB97C \uC694\uAD6C\uD560 \uB54C\uB9CC `--evidence review-trace.json`\uC744 \uD568\uAED8 \uC0AC\uC6A9\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
-  prePrReviewRunning: "Pre-PR \uB9AC\uBDF0 handoff\uAC00 \uC774\uBBF8 \uC9C4\uD589 \uC911\uC785\uB2C8\uB2E4. delegated review\uB97C \uB9C8\uCE58\uACE0 `review-trace.json`\uC744 \uB9CC\uB4E0 \uB4A4 `pre-pr-review`\uB85C \uACB0\uACFC\uB97C \uAE30\uB85D\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
+  prePrReviewRunning: "Pre-PR \uB9AC\uBDF0 handoff\uAC00 \uC774\uBBF8 \uC900\uBE44\uB418\uC5C8\uC2B5\uB2C8\uB2E4. \uAE30\uC874 delegated review\uB97C \uC7AC\uC0AC\uC6A9\uD558\uAC70\uB098 \uC774\uC5B4\uC11C \uC218\uD589\uD574 `review-trace.json`\uC744 \uB9CC\uB4E0 \uB4A4 `pre-pr-review`\uB85C \uACB0\uACFC\uB97C \uAE30\uB85D\uD558\uC138\uC694. \uAC19\uC740 \uB77C\uBCA8\uC744 \uB2E4\uC2DC \uC2B9\uC778 \uB8E8\uD504\uB85C \uC5F4\uC9C0 \uB9C8\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
   prePrReviewEvidenceMissing: "tasks.md\uC758 `PR \uC804 \uB9AC\uBDF0 Evidence`\uAC00 \uBE44\uC5B4\uC788\uAC70\uB098 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. \uC2E4\uC81C \uD30C\uC77C \uACBD\uB85C\uC640 `Pre-PR Review Log`(\uB610\uB294 `PR \uC804 \uB9AC\uBDF0 \uB85C\uADF8`)\uC5D0 placeholder\uAC00 \uC544\uB2CC `Summary`/`Feature Intent Summary`/`Implementation Fit`/`Missing Cases`/`Spec Alignment Checked`/`Finding Count`/`Blocking Findings`/`Decision`/`Findings`(\uB610\uB294 \uBA85\uC2DC\uC801 `0 findings`)/`Residual Risks`\uB97C \uAE30\uB85D\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
   prePrReviewDecisionMissing: "tasks.md\uC758 `PR \uC804 \uB9AC\uBDF0 Decision`\uC774 \uBE44\uC5B4\uC788\uAC70\uB098 \uACB0\uC815 \uD615\uC2DD\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. `\uACB0\uC815: ...`(\uB610\uB294 `decision: ...`) \uD615\uC2DD\uC73C\uB85C \uAE30\uB85D\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
   prePrReviewFixRequired: "\uD604\uC7AC `PR \uC804 \uB9AC\uBDF0 Decision`\uC774 `{decision}`\uC785\uB2C8\uB2E4. PR \uC0DD\uC131 \uB2E8\uACC4\uB85C \uC774\uB3D9\uD558\uAE30 \uC804\uC5D0 pre-PR \uC9C0\uC801\uC0AC\uD56D\uC744 \uCF54\uB4DC\uC5D0 \uBC18\uC601\uD558\uC138\uC694. (\uD655\uC778 \uD544\uC694)",
@@ -1183,7 +1183,7 @@ var enMessages = {
   prLegacyAsk: "tasks.md is missing PR/PR Status fields. Update to the latest template format? (CHECK required)",
   prePrReviewFieldMissing: "tasks.md is missing the `Pre-PR Review` field. Add `- **Pre-PR Review**: Pending | Running | Done` and run context again. (CHECK required)",
   prePrReviewRun: "Run the code review agent, compare the implementation against `spec.md`/`plan.md`/`tasks.md`, and generate `review-trace.json` with `Summary`, `Feature Intent Summary`, `Implementation Fit`, `Missing Cases`, `Spec Alignment Checked`, `Finding Count`, `Blocking Findings`, `Findings`, and `Residual Risks`. Then record findings with `pre-pr-review`; `pre-pr-review-run` itself does not generate evidence or advance state, and you should use `--evidence review-trace.json` only when the active evidence policy requires a path. (CHECK required)",
-  prePrReviewRunning: "Pre-PR review handoff is already in progress. Finish the delegated review, generate `review-trace.json`, then record the result with `pre-pr-review`. (CHECK required)",
+  prePrReviewRunning: "Pre-PR review handoff is already prepared. Reuse or resume the delegated review, generate `review-trace.json`, then record the result with `pre-pr-review`. Do not re-approve the same label. (CHECK required)",
   prePrReviewEvidenceMissing: "tasks.md `Pre-PR Evidence` is empty/invalid. Point to a real file and include a `Pre-PR Review Log` section with non-placeholder `Summary`, `Feature Intent Summary`, `Implementation Fit`, `Missing Cases`, `Spec Alignment Checked`, `Finding Count`, `Blocking Findings`, `Decision`, `Findings` (or explicit `0 findings`), and `Residual Risks`. (CHECK required)",
   prePrReviewDecisionMissing: "tasks.md `Pre-PR Decision` is empty/placeholder or missing decision format. Record it as `decision: ...` (or `\uACB0\uC815: ...`). (CHECK required)",
   prePrReviewFixRequired: "Current `Pre-PR Decision` is `{decision}`. Apply the requested fixes from pre-PR findings before moving to PR creation. (CHECK required)",
@@ -1990,6 +1990,7 @@ In approval-waiting state:
 3. Do not paraphrase or omit these lines.
 4. Prefer \`approvalRequest.userFacingLines\` as the source for user-facing approval text.
 5. Prefer \`matchedFeature.currentSubstateOwner\` plus \`agentOrchestration.subAgentHandoff\` as the delegation SSOT. Treat \`currentActionShouldDelegate\` as a compatibility mirror for older consumers.
+6. When \`matchedFeature.currentSubstateOwner="subagent"\` and \`agentOrchestration.subAgentHandoff.required=true\` with \`mode="command"\`, call \`spawn_agent\` first and do not execute the delegated command directly from the main agent. If the delegated command is handoff-only, continue the delegated work immediately and do not re-open the same approval label.
 
 In non-approval state (progress updates, analysis, tool execution logs, unrelated Q&A):
 
@@ -2004,23 +2005,35 @@ If approval is still pending after answering an unrelated question:
   - \`actionOptions[*].approvalPrompt\` (label meaning included), and
   - \`approvalRequest.finalPrompt\` (format line).
 - Never output \`finalPrompt\` alone without the matching \`A: ...\` prompt.`;
-function renderManagedBlock(lang, docsRepo) {
+function renderManagedSegment(lang, docsRepo) {
   return `${LEE_SPEC_KIT_AGENTS_BEGIN}
 ${CANONICAL_LEE_SPEC_KIT_AGENTS_TEXT}
-${LEE_SPEC_KIT_AGENTS_END}
+${LEE_SPEC_KIT_AGENTS_END}`;
+}
+function renderManagedBlock(lang, docsRepo) {
+  return `${renderManagedSegment()}
 
 `;
 }
 async function upsertLeeSpecKitAgentsMd(filePath, options) {
   const block = renderManagedBlock(options.lang, options.docsRepo);
+  const segment = renderManagedSegment(options.lang, options.docsRepo);
   const exists = await fs.pathExists(filePath);
   if (!exists) {
     await fs.writeFile(filePath, block, "utf-8");
     return { changed: true, action: "created" };
   }
   const current = await fs.readFile(filePath, "utf-8");
-  if (current.includes(LEE_SPEC_KIT_AGENTS_BEGIN)) {
-    return { changed: false, action: "noop" };
+  const beginIndex = current.indexOf(LEE_SPEC_KIT_AGENTS_BEGIN);
+  const endIndex = current.indexOf(LEE_SPEC_KIT_AGENTS_END);
+  if (beginIndex !== -1 && endIndex !== -1 && beginIndex <= endIndex) {
+    const replaceEnd = endIndex + LEE_SPEC_KIT_AGENTS_END.length;
+    const next2 = `${current.slice(0, beginIndex)}${segment}${current.slice(replaceEnd)}`;
+    if (next2 === current) {
+      return { changed: false, action: "noop" };
+    }
+    await fs.writeFile(filePath, next2, "utf-8");
+    return { changed: true, action: "updated" };
   }
   let next = current;
   if (next.length > 0 && !next.endsWith("\n")) next += "\n";
@@ -7491,7 +7504,7 @@ async function getFeatureNameFromSpec(fsAdapter, featureDir, fallbackSlug, fallb
   return fallbackSlug || fallbackFolderName;
 }
 function updateCommand(program2) {
-  program2.command("update").description("Update docs templates to the latest version").option("--agents", "Update agents/ folder only").option("--skills", "Cleanup legacy agents/skills copies (CLI-managed)").option("--templates", "Cleanup legacy feature-base copies (CLI-managed)").option(
+  program2.command("update").description("Update docs templates to the latest version").option("--agents", "Update agents/ folder only").option("--agents-md", "Sync project-scoped AGENTS.md entrypoint").option("--skills", "Cleanup legacy agents/skills copies (CLI-managed)").option("--templates", "Cleanup legacy feature-base copies (CLI-managed)").option(
     "-f, --force",
     "Force overwrite even if docs has uncommitted changes"
   ).action(async (options) => {
@@ -7534,8 +7547,9 @@ async function runUpdate(options) {
       const docsLockPath = getDocsLockPath(docsDir);
       const forceOverwrite = !!options.force || await isDocsWorktreeCleanOrThrow(docsDir, lang, [docsLockPath]);
       const configBackfill = await backfillMissingConfigDefaults(docsDir);
-      const hasExplicitSelection = !!(options.agents || options.skills || options.templates);
+      const hasExplicitSelection = !!(options.agents || options.agentsMd || options.skills || options.templates);
       const updateAgents = options.agents || options.skills || !hasExplicitSelection;
+      const updateAgentsMd = options.agentsMd || !hasExplicitSelection;
       const updateTemplates = options.templates || !hasExplicitSelection;
       const agentsMode = options.skills && !options.agents ? "skills" : "all";
       console.log(chalk8.blue(tr(lang, "cli", "update.start")));
@@ -7591,6 +7605,18 @@ async function runUpdate(options) {
           );
         }
       }
+      if (updateAgentsMd) {
+        const agentsMdTargets = await collectAgentsMdTargets(cwd, config);
+        for (const target of agentsMdTargets) {
+          const result = await upsertLeeSpecKitAgentsMd(target, {
+            lang,
+            docsRepo: config.docsRepo ?? "embedded"
+          });
+          if (result.changed) {
+            updatedCount += 1;
+          }
+        }
+      }
       if (updateTemplates) {
         console.log(chalk8.blue(tr(lang, "cli", "update.updatingFeatureBase")));
         console.log(chalk8.gray(tr(lang, "cli", "update.engineManagedFeatureBaseBuiltin")));
@@ -7625,6 +7651,42 @@ async function runUpdate(options) {
     { owner: "update" }
   );
 }
+function getGitTopLevelOrNull2(cwd) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const value = String(out || "").trim();
+    return value ? value : null;
+  } catch {
+    return null;
+  }
+}
+async function collectAgentsMdTargets(cwd, config) {
+  if (!config) return [];
+  const targets = /* @__PURE__ */ new Set();
+  const docsRepo = config.docsRepo ?? "embedded";
+  if (docsRepo === "embedded") {
+    const repoRoot = getGitTopLevelOrNull2(cwd) || getGitTopLevelOrNull2(config.docsDir) || path12.resolve(config.docsDir, "..");
+    targets.add(path12.join(repoRoot, "AGENTS.md"));
+    return [...targets];
+  }
+  targets.add(path12.join(config.docsDir, "AGENTS.md"));
+  const baseDir = getGitTopLevelOrNull2(cwd) || getGitTopLevelOrNull2(config.docsDir) || process.cwd();
+  const rawRoots = typeof config.projectRoot === "string" ? [config.projectRoot] : config.projectRoot && typeof config.projectRoot === "object" ? Object.values(config.projectRoot) : [];
+  for (const rawRoot of rawRoots) {
+    const value = String(rawRoot || "").trim();
+    if (!value) continue;
+    const resolved = path12.resolve(baseDir, value);
+    if (!await fs.pathExists(resolved)) continue;
+    const stat = await fs.stat(resolved);
+    if (!stat.isDirectory()) continue;
+    targets.add(path12.join(resolved, "AGENTS.md"));
+  }
+  return [...targets];
+}
 function isPlainObject(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -8749,6 +8811,73 @@ function buildApprovalCommand(state, featureName, selectedComponent, execute) {
   }
   return `npx lee-spec-kit context ${featureRef}${componentArg} --approve <LABEL>`;
 }
+function buildFeatureComponentArgs(feature) {
+  return feature.type && feature.type !== "single" ? ["--component", feature.type] : [];
+}
+function buildPrePrRecordCommand(feature, decision) {
+  const args = [
+    "pre-pr-review",
+    feature.folderName,
+    ...buildFeatureComponentArgs(feature),
+    "--evidence",
+    "review-trace.json",
+    "--decision",
+    decision
+  ];
+  return `npx lee-spec-kit ${args.join(" ")}`;
+}
+function buildDelegatedActionContract(state) {
+  const feature = state.matchedFeature;
+  const substateId = feature?.currentSubstateId;
+  if (!feature || !substateId) return null;
+  if (substateId === "pre_pr_review_run" || substateId === "pre_pr_review_running") {
+    return {
+      required: true,
+      mode: "command",
+      category: "pre_pr_review_run",
+      currentSubstateId: substateId,
+      delegatedWorkRequired: true,
+      handoffOnly: true,
+      advancesWorkflow: false,
+      doNotReapproveSameLabel: substateId === "pre_pr_review_running",
+      nextMainState: "pre_pr_review_running",
+      reuseKey: `pre-pr:${feature.folderName}`,
+      evidenceFile: "review-trace.json",
+      nextStepRequirement: "generate_review_trace_then_record",
+      recordCommands: {
+        changesRequested: buildPrePrRecordCommand(
+          feature,
+          "changes_requested"
+        ),
+        approve: buildPrePrRecordCommand(feature, "approve")
+      },
+      guidance: substateId === "pre_pr_review_running" ? "A pre-PR review handoff is already prepared. Reuse or resume the delegated review, generate review-trace.json, then record the result with pre-pr-review. Do not re-approve the same label." : "After approval, spawn_agent first and hand off the delegated pre-PR review. Handoff-only execution only prepares the review session; continue the delegated review immediately after approval."
+    };
+  }
+  if (substateId === "code_review_run" || substateId === "code_review_running") {
+    return {
+      required: true,
+      mode: "command",
+      category: "code_review_run",
+      currentSubstateId: substateId,
+      delegatedWorkRequired: true,
+      handoffOnly: true,
+      advancesWorkflow: false,
+      doNotReapproveSameLabel: substateId === "code_review_running",
+      nextMainState: "code_review_running",
+      reuseKey: `code-review:${feature.folderName}`,
+      guidance: substateId === "code_review_running" ? "A PR review handoff is already prepared. Reuse or resume the delegated review-fix work, then refresh PR Review Evidence and PR Review Decision before continuing. Do not re-approve the same label." : "After approval, spawn_agent first and hand off the delegated PR review-fix work. Handoff-only execution only prepares the delegated session; continue the delegated work immediately after approval."
+    };
+  }
+  return null;
+}
+function buildDelegatedApprovalGuidance(handoffRequired, handoffMode) {
+  const base = "Before asking for approval, show only `actionOptions[].approvalPrompt` lines and `approvalRequest.finalPrompt` to the user. Keep `requiredDocs`, `checkPolicy`, and raw execution commands as internal guidance. For commit actions, include scope (`docs`/`project`) and commit message in the visible prompt. User replies should include the label token (e.g. `A`, `A OK`, `A proceed`, `A \uC9C4\uD589\uD574`).";
+  const delegatedCommand = handoffRequired && handoffMode === "command" ? ' When `matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="command"`, call spawn_agent first and do not execute the delegated command directly from the main agent. If the delegated command is handoff-only, `--execute` only prepares the handoff; continue the delegated work immediately and do not re-approve the same label.' : "";
+  const nonDelegated = " For non-delegated command actions, prefer one-shot `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute` to avoid session mismatch after context compression/reset. Use ticket-based `context --execute --ticket` only when explicitly needed.";
+  const orchestration = ' Use main-agent orchestration: keep short steps in main agent. Prefer `matchedFeature.currentSubstateOwner` + `agentOrchestration.subAgentHandoff` as the delegation SSOT; `currentActionShouldDelegate` is a compatibility mirror. Delegate auto-run only when `agentOrchestration.subAgentHandoff.required=true` with `mode="auto_run"`.';
+  return `${base}${delegatedCommand}${nonDelegated}${orchestration}`;
+}
 function buildFinalApprovalPrompt(lang, actionOptions) {
   if (actionOptions.length === 0) return "";
   const labels = listLabels(actionOptions);
@@ -9358,6 +9487,28 @@ function getCommandExecutionLockPath(action, config) {
   }
   return getProjectExecutionLockPath(action.cwd);
 }
+function buildApprovedHandoffMetadata(action, featureRef) {
+  if (action.category === "pre_pr_review_run") {
+    return {
+      delegatedWorkRequired: true,
+      doNotReapproveSameLabel: true,
+      reuseKey: `pre-pr:${featureRef}`,
+      nextStepRequirement: "generate_review_trace_then_record",
+      evidenceFile: "review-trace.json"
+    };
+  }
+  if (action.category === "code_review_run") {
+    return {
+      delegatedWorkRequired: true,
+      doNotReapproveSameLabel: true,
+      reuseKey: `code-review:${featureRef}`
+    };
+  }
+  return {
+    delegatedWorkRequired: true,
+    doNotReapproveSameLabel: true
+  };
+}
 async function runApprovedOption(state, config, lang, featureName, selectionOptions, options) {
   const approval = options.approve || "";
   const ticketToken = (options.ticket || "").trim();
@@ -9588,6 +9739,10 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
     );
     if (jsonMode) {
       if (executionMetadata?.handoffOnly && !executionMetadata.advancesWorkflow) {
+        const handoffMetadata = buildApprovedHandoffMetadata(
+          selectedAction,
+          freshState.matchedFeature?.folderName ?? featureRef
+        );
         console.log(
           JSON.stringify(
             {
@@ -9602,6 +9757,7 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
               handoffOnly: true,
               advancesWorkflow: false,
               nextMainState: executionMetadata.nextMainState,
+              ...handoffMetadata,
               stdout: execResult.stdout?.trim() || void 0,
               stderr: execResult.stderr?.trim() || void 0
             },
@@ -9782,6 +9938,11 @@ async function runContext(featureName, options) {
     state.matchedFeature?.folderName || null,
     state.matchedFeature?.currentSubstateOwner
   );
+  const delegatedAction = buildDelegatedActionContract(state);
+  const approvalGuidance = buildDelegatedApprovalGuidance(
+    agentOrchestration.subAgentHandoff.required,
+    agentOrchestration.subAgentHandoff.mode
+  );
   if (options.approve || options.execute) {
     await runApprovedOption(
       state,
@@ -9840,6 +10001,7 @@ async function runContext(featureName, options) {
         agentOrchestration: {
           subAgentHandoff: agentOrchestration.subAgentHandoff
         },
+        delegatedAction,
         autoRun: {
           available: autoRunPlan.available,
           policyEligible: autoRunPlan.policyEligible,
@@ -9975,13 +10137,14 @@ async function runContext(featureName, options) {
           "actionOptions[].detail",
           "actionOptions[].approvalPrompt"
         ] : [],
-        recommendation: 'Before asking for approval, show only `actionOptions[].approvalPrompt` lines and `approvalRequest.finalPrompt` to the user. Keep `requiredDocs`, `checkPolicy`, and raw execution commands as internal guidance. For commit actions, include scope (`docs`/`project`) and commit message in the visible prompt. User replies should include the label token (e.g. `A`, `A OK`, `A proceed`, `A \uC9C4\uD589\uD574`). For command execution, prefer one-shot `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute` to avoid session mismatch after context compression/reset. Use ticket-based `context --execute --ticket` only when explicitly needed. Use main-agent orchestration: keep short steps in main agent. Prefer `matchedFeature.currentSubstateOwner` + `agentOrchestration.subAgentHandoff` as the delegation SSOT; `currentActionShouldDelegate` is a compatibility mirror. Delegate auto-run only when `agentOrchestration.subAgentHandoff.required=true` with `mode="auto_run"`.',
+        recommendation: approvalGuidance,
         oneApprovalPerAction: approvalRequired,
         requireFreshContext: true,
         contextVersion: state.contextVersion,
         config: config.approval ?? { mode: "builtin" }
       },
       agentOrchestration,
+      delegatedAction,
       autoRun: {
         available: autoRunPlan.available,
         policyEligible: autoRunPlan.policyEligible,
@@ -9995,7 +10158,10 @@ async function runContext(featureName, options) {
         guidance: 'Use auto-run only when `autoRun.available=true`. If `autoRun.policyEligible=true` but `autoRun.executableNow=false`, resolve `autoRun.manualBoundary` first. Do not treat `autoRun.available` alone as a delegation trigger; use `agentOrchestration.subAgentHandoff.required` + `mode="auto_run"` for actual delegation. Stop and request approval when `approvalRequest.required=true` or when auto mode reaches configured gate categories.'
       },
       approvalRequest: {
-        guidance: 'User-facing output must include only approval prompts (`A: ...`) and `finalPrompt`. Do not expose `requiredDocs`, `checkPolicy`, or raw `cmd` unless explicitly requested. For approved command actions, prefer one-shot `flow --approve <LABEL> --execute`. Keep short steps in main agent. Prefer `matchedFeature.currentSubstateOwner` + `agentOrchestration.subAgentHandoff` as the delegation SSOT; `currentActionShouldDelegate` is a compatibility mirror. Delegate auto-run only when `agentOrchestration.subAgentHandoff.required=true` with `mode="auto_run"`.',
+        guidance: approvalGuidance.replace(
+          "Before asking for approval, show only `actionOptions[].approvalPrompt` lines and `approvalRequest.finalPrompt` to the user.",
+          "User-facing output must include only approval prompts (`A: ...`) and `finalPrompt`."
+        ),
         required: approvalRequired,
         finalPrompt: finalApprovalPrompt,
         userFacingLines: approvalUserFacingLines,
@@ -11403,6 +11569,7 @@ function toCompactFlowContextSnapshot(state) {
     actionOptions: state.actionOptions.map(
       (option) => toCompactFlowActionOption(option)
     ),
+    delegatedAction: buildDelegatedActionContract(state),
     primaryActionLabel: primaryAction?.label ?? null,
     primaryActionType: primaryAction?.action.type ?? null,
     primaryActionCategory: primaryAction?.action.category ?? null,
@@ -16183,6 +16350,7 @@ async function runPrePrReviewRun(featureName, options) {
           suggestedParallelism: 1,
           fallbackToMainAgentWhenQuotaExceeded: true,
           nextStepRequirement: "generate_review_trace_then_record",
+          delegatedWorkRequired: true,
           nextMainState: "pre_pr_review_running",
           evidenceFile: "review-trace.json",
           tasksUpdated,
@@ -16220,6 +16388,9 @@ async function runPrePrReviewRun(featureName, options) {
   console.log(`Suggested parallelism: 1`);
   console.log(`Next main state: pre_pr_review_running`);
   console.log(`Evidence file: review-trace.json`);
+  console.log(
+    config.lang === "ko" ? "Next required: delegated review\uB97C \uC774\uC5B4\uC11C \uC218\uD589\uD558\uACE0 review-trace.json\uC744 \uB9CC\uB4E0 \uB4A4 pre-pr-review\uB85C \uAE30\uB85D" : "Next required: continue the delegated review, generate review-trace.json, then record the result with pre-pr-review"
+  );
   if (tasksUpdated) {
     console.log(`tasks.md updated: ${tasksPath}`);
     console.log(