feat: recommend execution modes at DP-4

CHANGELOG.md

@@ -6,9 +6,9 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
-### Fixed
+### Changed
 
-- **#45 — Guarded execution control plane**: full/hotfix now default to SDD through a persisted execution plan at `<change>/.superpowers/sdd/execution-plan.json`; inline and Batch Inline require an explicit override, named waves record dependencies and strategy, and closing requires current `pass` review receipts for every wave.
+- **#45 — Execution-mode recommendation**: DP-4 now runs `ssf execution recommend` to list Inline, Batch Inline, and SDD from task and wave evidence, with a recommendation. Every persisted plan at `<change>/.superpowers/sdd/execution-plan.json` requires explicit `--confirm`; a non-recommended selection records `--acknowledge-recommendation` instead of treating Inline as an override. Named waves, dependencies, and review receipts remain mandatory.
 
 ## [0.9.0] - 2026-07-11
 

INSTALL.md

@@ -688,17 +688,27 @@ changes/<change-name>/
 
 full/hotfix 在 DP-4 必须保存 current execution plan 到
 `<change>/.superpowers/sdd/execution-plan.json`；它不属于 `execution-contract.md`。
-SDD 是 default。只有用户明确选择 explicit override，才可改为 `inline` 或
-`batch-inline`；Batch Inline 始终串行，不会自动成为默认模式或表示并行。`tweak`
+先运行 `ssf execution recommend`：它按任务量和 wave 策略列出 `inline`、
+`batch-inline`、`sdd` 并给出推荐，并保存当前 wave 的推荐凭据到
+`<change>/.superpowers/sdd/execution-recommendation.json`。Agent 展示候选项和理由后，
+`plan` 与 `revise` 必须消费匹配当前 artifact、contract 和 wave 的凭据；用户用 `--confirm`
+确认；若选择非推荐方式，必须用 `--acknowledge-recommendation` 记录风险确认。Batch
+Inline 始终串行，不会表示并行。`tweak`
 免除 execution plan 与 review receipt gate。
 
 ```bash
-ssf execution plan changes/my-change --mode sdd --reason "independent work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution plan changes/my-change --mode sdd --confirm --reason "independent work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 ssf execution show changes/my-change --json
 # 可将已有 inline/batch-inline 计划升级为 sdd，或重规划已有 sdd 的 wave/依赖；不能降级。
-ssf execution revise changes/my-change --mode sdd --reason "need parallel work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution revise changes/my-change --mode sdd --confirm --reason "need parallel work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 ssf execution review changes/my-change --wave foundation --base <sha> --head <sha> \

README.md

@@ -143,7 +143,8 @@ npx spec-superflow list          # 或通过 npx 使用
 | `ssf handoff list <dir>` | 列出 handoff 生命周期状态 |
 | `ssf handoff finish <dir> <id>` | 校验 handoff 结果 |
 | `ssf handoff resolve <dir> <id> --decision <decision>` | 记录显式 handoff 决策 |
-| `ssf execution plan <dir> ...` | 为 full/hotfix 在 `<change>/.superpowers/sdd/execution-plan.json` 记录受 guard 保护的执行计划（SDD 默认） |
+| `ssf execution recommend <dir> ...` | 基于任务量、wave 和工作流列出可用执行方式并给出推荐 |
+| `ssf execution plan <dir> ...` | 在用户确认选择后，为 full/hotfix 保存受 guard 保护的执行计划 |
 | `ssf execution show <dir> [--json]` | 查看并校验当前执行计划、wave 与 receipt |
 | `ssf execution revise <dir> ...` | 将已有计划保留/升级为 SDD，并生成新 revision；不允许降级 |
 | `ssf execution review <dir> ...` | 为一个计划 wave 记录 review receipt |
@@ -191,18 +192,28 @@ Delta spec 的规范路径是 `specs/<capability>/spec.md`；扁平的 `specs/<c
 
 对 full/hotfix，DP-4 不是一段任意文本：开始实现前必须保存并校验 current
 execution plan。它位于 `<change>/.superpowers/sdd/execution-plan.json`，不写入
-`execution-contract.md`。SDD 是 default；只有用户给出 explicit override 时，才能选择
-`inline` 或 `batch-inline`。后者始终是串行模式，绝不自动成为默认或冒充并行。
+`execution-contract.md`。先运行 `ssf execution recommend`，它会根据任务量和 wave
+策略列出 `inline`、`batch-inline`、`sdd`，并给出可审计的推荐理由，同时把当前 wave 的
+推荐凭据保存为 `<change>/.superpowers/sdd/execution-recommendation.json`；Agent 必须将这些
+候选项和推荐展示给用户。`plan` 或 `revise` 只接受匹配当前 artifact、contract 和 wave 的
+凭据。用户用 `--confirm` 明确确认选择；若选择与推荐不同，必须额外
+传入 `--acknowledge-recommendation` 记录已知风险。Batch Inline 始终串行，绝不冒充并行。
 `tweak` 保持轻量例外，不要求 execution plan 或 wave receipt。
 
 ```bash
-ssf execution plan changes/my-change --mode sdd --reason "independent work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution plan changes/my-change --mode sdd --confirm --reason "independent work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 ssf execution show changes/my-change --json
 # 将已有 inline/batch-inline 计划升级为 sdd，或重规划已有 sdd 计划；不能降级。
 # 每次修订都会生成新 revision 并清除旧 review receipt。
-ssf execution revise changes/my-change --mode sdd --reason "need parallel work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution revise changes/my-change --mode sdd --confirm --reason "need parallel work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 # 每个 wave 都先写入非空 review report，再记录 receipt。
@@ -361,7 +372,7 @@ ssf config --resolve-model mechanical
 <details>
 <summary><strong>SDD (Subagent-Driven Development) 怎么工作的？</strong></summary>
 
-full/hotfix 默认 SDD：先在 `<change>/.superpowers/sdd/execution-plan.json` 保存带依赖和策略的 execution plan，再按可执行 wave 派实施子代理；每个 wave 先有 review report，再写 `pass`/`fail` review receipt。只有用户 explicit override 才能选择 inline 或 Batch Inline；Batch Inline 仍是串行。进度台账防止会话压缩后丢失进度。
+full/hotfix 先由 `ssf execution recommend` 根据任务量和 wave 策略列出 Inline、Batch Inline、SDD 并推荐一种；Agent 展示候选项和理由，用户以 `--confirm` 确认后才保存 plan。若选择非推荐方式，`--acknowledge-recommendation` 会记录风险确认。SDD 按可执行 wave 派实施子代理；每个 wave 先有 review report，再写 `pass`/`fail` review receipt。Batch Inline 仍是串行。进度台账防止会话压缩后丢失进度。
 
 </details>
 

docs/README_en.md

@@ -234,19 +234,30 @@ You: "add authorization to the API"
 
 For full/hotfix, DP-4 is a persisted, current execution plan at
 `<change>/.superpowers/sdd/execution-plan.json`, rather than an arbitrary text
-field or content stored in `execution-contract.md`. SDD is the default.
-`inline` and `batch-inline` require an explicit user override; Batch Inline
-remains serial and is never an automatic default or a claim of parallel work.
+field or content stored in `execution-contract.md`. Run `ssf execution recommend`
+first: it lists `inline`, `batch-inline`, and `sdd` from task count and wave
+strategy, with auditable reasons, and saves a recommendation receipt at
+`<change>/.superpowers/sdd/execution-recommendation.json`. The agent presents that recommendation and the
+user records a choice with `--confirm`; `plan` and `revise` require a receipt matching the current
+artifacts, contract, and waves. A non-recommended choice also requires
+`--acknowledge-recommendation`. Batch Inline remains serial and never claims
+parallel work.
 `tweak` is exempt from this execution-plan and review-receipt gate.
 
 ```bash
-ssf execution plan changes/my-change --mode sdd --reason "independent work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution plan changes/my-change --mode sdd --confirm --reason "independent work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 ssf execution show changes/my-change --json
 # Retains/upgrades an existing plan as sdd; it can replan waves and dependencies,
 # creates a new revision, and clears old review receipts. Downgrades are rejected.
-ssf execution revise changes/my-change --mode sdd --reason "need parallel work" \
+ssf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+ssf execution revise changes/my-change --mode sdd --confirm --reason "need parallel work" \
   --wave foundation:parallel:1.1,1.2 \
   --wave integration:serial:2.1:foundation
 ssf execution review changes/my-change --wave foundation --base <sha> --head <sha> \
@@ -330,12 +341,14 @@ Content-level detection, not timestamps: proposal scope changed, approved spec b
 <details>
 <summary><strong>How does SDD (Subagent-Driven Development) work?</strong></summary>
 
-For full/hotfix, the default SDD loop persists an execution plan at
-`<change>/.superpowers/sdd/execution-plan.json` with named waves, dependencies,
-and strategies before dispatching implementers. Each wave gets a review report
-and a `pass`/`fail` review receipt. Inline and Batch Inline require an explicit
-user override; Batch Inline remains serial. The progress ledger prevents
-session-compression loss.
+For full/hotfix, `ssf execution recommend` first presents Inline, Batch Inline,
+and SDD with evidence from the change, then recommends one. The user confirms a
+selection with `--confirm`; a different selection requires
+`--acknowledge-recommendation`. The saved execution plan at
+`<change>/.superpowers/sdd/execution-plan.json` names waves, dependencies, and
+strategies before dispatching implementers. Each wave gets a review report and a
+`pass`/`fail` receipt. Batch Inline remains serial, and the progress ledger
+prevents session-compression loss.
 
 </details>
 

docs/artifact-contract.md

@@ -57,15 +57,20 @@ Defines:
 - review gates and their review receipts
 - escalation rules
 
-For full/hotfix, SDD is the default execution mode. `inline` and
-`batch-inline` require an explicit user override; Batch Inline remains serial
-and is never an automatic default. After approval, `ssf execution plan` writes
+For full/hotfix, `ssf execution recommend` lists applicable execution modes and
+recommends one from task count and wave strategy, and persists a recommendation
+receipt at `<change>/.superpowers/sdd/execution-recommendation.json`. `plan`
+and `revise` require the receipt to match the current artifacts, contract, and
+waves. The user confirms the selected mode with `--confirm`; a non-recommended mode additionally requires
+`--acknowledge-recommendation`. Batch Inline remains serial. After approval,
+`ssf execution plan` writes
 the persisted execution plan to `<change>/.superpowers/sdd/execution-plan.json`.
 That JSON records each wave's dependencies and parallel/serial strategy; it is
 not stored in `execution-contract.md`. A current `pass` review receipt is
 required for every wave before dependent work or closing proceeds. `tweak` is
 exempt from execution-plan and review-receipt gates. `ssf execution revise`
-retains or upgrades an existing plan as `sdd`, creates a new revision, and
+retains or upgrades an existing plan as `sdd`, requires fresh confirmation,
+creates a new revision, and
 clears prior review receipts; it never permits a downgrade. #47 slash commands for recovery,
 switching, and manual save are not implemented, so `/ssf:*` commands must not
 be claimed.
@@ -86,6 +91,6 @@ Implementation starts only after:
 - planning artifacts exist
 - `execution-contract.md` exists
 - the user approves the execution contract
-- full/hotfix have a current `ssf execution plan` with SDD as the default or an
-  explicit override
+- full/hotfix have a current `ssf execution plan` with a user-confirmed mode and
+  persisted recommendation evidence
 - every completed wave records a current `pass` review receipt before closing

docs/state-machine.md

@@ -43,18 +43,24 @@
 
 For full/hotfix, DP-4 is the persisted execution plan created by `ssf execution
 plan` at `<change>/.superpowers/sdd/execution-plan.json`, not an arbitrary
-state value or content stored in `execution-contract.md`. SDD is the default. `inline` and
-`batch-inline` require an explicit user override; Batch Inline remains serial
-and is never an automatic default or a substitute for parallel execution.
+state value or content stored in `execution-contract.md`. Before planning, run
+`ssf execution recommend`; it lists applicable `inline`, `batch-inline`, and
+`sdd` modes with evidence and one recommendation, and persists a receipt at
+`<change>/.superpowers/sdd/execution-recommendation.json`. `plan` and `revise`
+accept only a receipt whose artifacts, contract, and waves still match. The user must record the
+selected mode with `--confirm`; a non-recommended selection also requires
+`--acknowledge-recommendation`. Batch Inline remains serial and is never a
+substitute for parallel execution.
 `tweak` is exempt from execution-plan and review-receipt requirements.
 
 The plan names ordered execution waves, dependencies, and parallel/serial
 strategy. `ssf execution show <change-dir> --json` reports which current waves
 are eligible. Each completed wave must have a current
 `pass` review receipt, recorded with `ssf execution review`, before a dependent
 wave or `closing` can proceed. `ssf execution revise` retains or upgrades an
-existing plan as `sdd`; that new revision invalidates old review receipts and
-does not permit a downgrade. #47 recovery/switch/save
+existing plan as `sdd`; that new revision requires a fresh confirmation (and
+acknowledgement when it differs from the new recommendation), invalidates old
+review receipts, and does not permit a downgrade. #47 recovery/switch/save
 slash commands are not implemented; do not assume `/ssf:*` commands exist.
 
 ### `debugging`

scripts/install-cursor.mjs

@@ -149,7 +149,7 @@ alwaysApply: true
 - DP-1：需求确认
 - DP-2：工件审查
 - DP-3：是否批准 execution contract？
-- DP-4：full/hotfix 默认 SDD；Inline / Batch Inline 只允许用户明确 override
+- DP-4：先运行 ssf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
 - DP-5：调试升级
 - DP-6：验证失败
 - DP-7：是否收口归档？

scripts/install-zcode.mjs

@@ -149,7 +149,7 @@ alwaysApply: true
 - DP-1：需求确认
 - DP-2：工件审查
 - DP-3：是否批准 execution contract？
-- DP-4：full/hotfix 默认 SDD；Inline / Batch Inline 只允许用户明确 override
+- DP-4：先运行 ssf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
 - DP-5：调试升级
 - DP-6：验证失败
 - DP-7：是否收口归档？