Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -726,15 +726,15 @@ changes/<change-name>/

### 受 guard 保护的执行计划

full/hotfix 在 DP-4 必须保存 current execution plan 到
Full/legacy Hotfix 在 DP-4 必须保存 current execution plan 到
`<change>/.superpowers/sdd/execution-plan.json`;它不属于 `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 planreview receipt gate。
Inline 始终串行,不会表示并行。Quick、direct Hotfix 与 `tweak`
免除 contract、execution planreview receipt 和 DP gate;它们在边界内验证后持久化 `test_result: pass`

```bash
ssf execution recommend changes/my-change \
Expand Down Expand Up @@ -813,6 +813,6 @@ Checkpoint 是任务级恢复上下文。`result-ready` handoff 在继续受影

从 `workflow-start` 入口开始,不要直接调用 `build-executor`。

推荐流程:`exploring -> specifying -> bridging -> approved-for-build -> execution plan -> executing -> closing`
Full/legacy 推荐流程:`exploring -> specifying -> bridging -> approved-for-build -> execution plan -> executing -> closing`

hotfix 快速路径:`exploring -> bridging -> approved-for-build -> executing`。hotfix 可以跳过完整的 `proposal.md`、`design.md`、`tasks.md`、`specs/`,但仍然必须先生成一份新的最小 `execution-contract.md`,并完成 DP-3 批准后才能开始实现
Quick(≤3 低风险文件/任务)与 direct Hotfix(incident,≤2)走 `exploring -> approved-for-build -> executing`,同轮推荐/接受后直接验证;direct Hotfix 必须复现原症状回归。legacy Hotfix 才走最小契约、DP-3、plan/review 路径
18 changes: 10 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ npx spec-superflow list # 或通过 npx 使用
| `ssf handoff finish <dir> <id>` | 校验 handoff 结果 |
| `ssf handoff resolve <dir> <id> --decision <decision>` | 记录显式 handoff 决策 |
| `ssf execution recommend <dir> ...` | 基于任务量、wave 和工作流列出可用执行方式并给出推荐 |
| `ssf execution plan <dir> ...` | 在用户确认选择后,为 full/hotfix 保存受 guard 保护的执行计划 |
| `ssf execution plan <dir> ...` | 在用户确认选择后,为 Full/legacy Hotfix 保存受 guard 保护的执行计划 |
| `ssf execution show <dir> [--json]` | 查看并校验当前执行计划、wave 与 receipt |
| `ssf execution revise <dir> ...` | 将已有计划保留/升级为 SDD,并生成新 revision;不允许降级 |
| `ssf execution review <dir> ...` | 为一个计划 wave 记录 review receipt |
Expand Down Expand Up @@ -202,15 +202,15 @@ Delta spec 的规范路径是 `specs/<capability>/spec.md`;扁平的 `specs/<c

### 受 guard 保护的执行计划

full/hotfix,DP-4 不是一段任意文本:开始实现前必须保存并校验 current
Full/legacy Hotfix,DP-4 不是一段任意文本:开始实现前必须保存并校验 current
execution plan。它位于 `<change>/.superpowers/sdd/execution-plan.json`,不写入
`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
Quick、direct Hotfix 与 `tweak` 保持轻量例外不要求 contract、execution plan、wave receipt 或 DP;在边界内验证后持久化 `test_result: pass`

```bash
ssf execution recommend changes/my-change \
Expand Down Expand Up @@ -270,7 +270,7 @@ overlay,不会增加第九个状态;其 CLI 与 CodeBuddy/WorkBuddy Markdown

**❌ 不推荐:** 一次性脚本/工具、纯咨询/问答。

> **v0.6.0 起自动模式检测**:hotfix(≤2 文件,最小契约 + DP-3 后执行)和 tweak(≤4 文件,纯配置/文档,直接编辑)让小型变更也能高效使用
> **四级模式**:Quick(≤3 文件/任务低风险代码)、direct Hotfix(incident 且≤2)、Tweak(≤4 配置/文档)直接执行并验证;Full 与 legacy Hotfix 保留规划、契约和 review

---

Expand Down Expand Up @@ -319,11 +319,13 @@ overlay,不会增加第九个状态;其 CLI 与 CodeBuddy/WorkBuddy Markdown
closing CLOSED 成功终态(无 next skill)
```

**关键约束:** 没有 `execution-contract.md` 或未被批准 → 不允许实现;full/hotfix 没有 current execution plan、或任一 wave 缺少 `pass` review receipt → 不允许推进;需求变更 → 强制回退;遇到 bug → 强制走 debugging,不允许"随便试试"
**关键约束:** Full/legacy Hotfix 没有 `execution-contract.md`current execution plan`pass` review receipt → 不允许推进;Quick/direct Hotfix/Tweak 以有效 receipt、边界检查与 `test_result: pass` 放行。任何风险升级转 Full

### 快速路径(hotfix / tweak
### 快速路径(Quick / Hotfix / Tweak

- **hotfix** — ≤2 文件、无新模块时,走 `exploring -> bridging -> approved-for-build -> executing`。可跳过 `proposal.md`、`design.md`、`tasks.md`、`specs/` 等完整规划工件,但仍必须先生成一份新的最小 `execution-contract.md`,并完成 DP-3 批准后才能进入实现
- **Quick** — ≤3 文件/任务、低风险代码:同轮推荐/接受,`exploring -> approved-for-build -> executing`,跑定向验证。
- **direct Hotfix** — incident 且≤2 文件/任务:同一路径,必须验证原症状回归。
- **legacy Hotfix** — 既有或无 direct receipt:保留最小契约、DP-3、plan/review。
- **tweak** — ≤4 文件、纯配置/文档修改时,跳过规划+桥接,直接编辑

---
Expand Down Expand Up @@ -386,7 +388,7 @@ ssf config --resolve-model mechanical
<details>
<summary><strong>SDD (Subagent-Driven Development) 怎么工作的?</strong></summary>

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 仍是串行。进度台账防止会话压缩后丢失进度。
Full/legacy Hotfix 先由 `ssf execution recommend` 根据任务量和 wave 策略列出 Inline、Batch Inline、SDD 并推荐一种;Agent 展示候选项和理由,用户以 `--confirm` 确认后才保存 plan。Quick/direct Hotfix/Tweak 不创建 plan 或 review receipt,而是报告边界内的验证并写入 `test_result: pass`。Batch Inline 仍是串行。进度台账防止会话压缩后丢失进度。

</details>

Expand Down
16 changes: 9 additions & 7 deletions docs/README_en.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ AI coding sessions fail in one of two ways:

**❌ Skip:** One-off scripts, pure Q&A conversations.

> **v0.6.0+ auto mode detection:** hotfix (≤2 files, minimal contract + DP-3 before execution) and tweak (≤4 files, config/docs only, skips planning + bridging) make lightweight changes efficient too.
> **Four workflow modes:** Quick (≤3 low-risk code files/tasks), direct Hotfix (incident, ≤2), and Tweak (≤4 config/docs files) execute with bounded verification; Full and legacy Hotfix retain planning, contract, and review controls.

---

Expand Down Expand Up @@ -240,11 +240,11 @@ You: "add authorization to the API"
closing CLOSED successful terminal state (no next skill)
```

**Hard constraints:** No `execution-contract.md` or no approval → implementation blocked. Requirements change mid-execution → forced rollback. Bug encountered → must enter debugging state, no ad-hoc fixes.
**Hard constraints:** Full and legacy Hotfix require an approved `execution-contract.md`; Quick, direct Hotfix, and Tweak instead stay within their accepted boundary and persist `test_result: pass`. Requirements change mid-execution → forced rollback. Bug encountered → must enter debugging state, no ad-hoc fixes.

### Guarded execution plans

For full/hotfix, DP-4 is a persisted, current execution plan at
For Full/legacy 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`. Run `ssf execution recommend`
first: it lists `inline`, `batch-inline`, and `sdd` from task count and wave
Expand All @@ -254,7 +254,7 @@ user records a choice with `--confirm`; `plan` and `revise` require a receipt ma
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.
Quick, direct Hotfix, and Tweak are exempt from contract, execution-plan, and review-receipt gates; they persist `test_result: pass` after bounded verification.

```bash
ssf execution recommend changes/my-change \
Expand Down Expand Up @@ -289,9 +289,11 @@ Recovery, switching, and manual save form a control-plane overlay, not a ninth
workflow state; their CLI and CodeBuddy/WorkBuddy Markdown adapters keep the
same guards.

### Fast Paths (hotfix / tweak)
### Fast Paths (Quick / Hotfix / Tweak)

- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation
- **Quick** — ≤3 low-risk code files/tasks → same-turn recommendation and direct acceptance, then targeted verification.
- **direct Hotfix** — incident, ≤2 files/tasks → direct path plus original-symptom regression.
- **legacy Hotfix** — no direct receipt → minimal contract, DP-3, execution plan, and review remain required.
- **tweak** — ≤4 files, config/docs only → skip planning + bridging, direct edit

---
Expand Down Expand Up @@ -354,7 +356,7 @@ 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, `ssf execution recommend` first presents Inline, Batch Inline,
For Full/legacy 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
Expand Down
9 changes: 4 additions & 5 deletions docs/artifact-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Defines:
- review gates and their review receipts
- escalation rules

For full/hotfix, `ssf execution recommend` lists applicable execution modes and
For Full/legacy 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
Expand All @@ -67,8 +67,7 @@ waves. The user confirms the selected mode with `--confirm`; a non-recommended m
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`
required for every wave before dependent work or closing proceeds. Quick, direct Hotfix, and Tweak are exempt from execution-plan and review-receipt gates and persist `test_result: pass` after bounded verification. `ssf execution revise`
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.
Expand Down Expand Up @@ -98,11 +97,11 @@ the same CLI guards; other platforms are not promised identical slash names.

## Guardrail

Implementation starts only after:
For Full/legacy Hotfix, 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 a user-confirmed mode and
- Full/legacy 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
9 changes: 5 additions & 4 deletions docs/decision-points.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,10 @@

- **编号**:DP-0
- **名称**:设计前确认
- **触发条件**:`workflow-start` 检测到 change 目录不存在、规划工件不存在或不完整、`dp_0_confirmed` 尚未确认,或 legacy change 的 workflow 为 `auto`/空时;该门禁覆盖 full 以及直接进入 hotfix/tweak 的 fast paths,不只发生在路由到 `spec-writer` 之前
- **触发条件**:Full 或 legacy change 在 planning 前触发;Quick、direct Hotfix、Tweak 不等待 DP-0,先记录可验证 recommendation/direct receipt 后执行。
- **所需输入**:变更名称与意图、已知约束(命名风格、兼容性、受影响平台)、是否包含相关优化、用户沟通偏好;以及最少路径事实(任务数、文件数、是否仅配置/文档、是否涉及 schema/API、新模块和不确定性)
- **路径选择协议**:`workflow-start` 先读取 `ssf workflow show`;仅在 `missing_facts` 列出的字段缺失时提问,再运行 `ssf workflow recommend`。它必须向用户展示 Observed、Available、Recommended、Why 四项信息,推荐本身不改变状态也不写入 workflow。用户明确选择 `full`、`hotfix` 或 `tweak` 后,才可用 `ssf workflow select --confirm` 持久化;选择非推荐路径还必须显式传入 `--acknowledge-recommendation`。
- **路径选择协议**:低风险 Quick 与 incident Hotfix 同轮展示 recommendation 后可运行 `ssf workflow accept --source direct-request`;其余路径使用 `show`、补齐 missing facts、`recommend` 和 `select --confirm`。direct receipt 代替短路径 DP。
- **短路径收口**:Quick、direct Hotfix、Tweak 以边界内验证摘要和 `test_result: pass` 收口,不写 DP-6 或 DP-7。
- **确认顺序**:可先解析 `artifact_language`,随后必须完成路径 receipt 读取、最少事实补全、建议展示和用户选择;路径摘要与其他 DP-0 决定合并确认后,才可设置 `dp_0_confirmed=true`。
- **预期输出**:完整、防篡改的路径选择 receipt 固定保存在 change overlay 的 `.superpowers/sdd/workflow-selection.json`,用于恢复和审计;`.spec-superflow.yaml` 的 `dp_0_*` 只保存确认结果与幂等的 `workflow_path`/推荐对齐摘要,并保留既有 `scope` 和 `artifact_language`。空目录的 legacy artifact inference 可以返回 `full` 以兼容旧 API,但绝不能替代入口的用户选择。
- **关联 skill**:`spec-superflow:workflow-start`
Expand All @@ -35,7 +36,7 @@

- **编号**:DP-3
- **名称**:契约批准
- **触发条件**:contract-builder 完成 `execution-contract.md` 的生成后,用户必须明确批准该契约方可进入执行阶段(硬门禁,不可跳过)
- **触发条件**:仅 Full 或 legacy Hotfix 的 contract-builder 生成契约后触发;Quick/direct Hotfix/Tweak 不适用。
- **所需输入**:`execution-contract.md` 全文,包含执行批次、任务依赖、验收标准、回滚策略
- **预期输出**:用户明确批准(approve)执行契约,或提出修改要求;未获批准前 build-executor 不得启动
- **关联 skill**:`spec-superflow:contract-builder`
Expand All @@ -44,7 +45,7 @@

- **编号**:DP-4
- **名称**:执行模式选择
- **触发条件**:build-executor 启动执行前,用户需要选择本次执行的开发模式
- **触发条件**:仅 Full 或 legacy Hotfix 在 build-executor 启动前选择执行模式;Quick/direct Hotfix/Tweak 不适用。
- **所需输入**:已批准的 `execution-contract.md`、项目测试基础设施现状,以及 `ssf execution recommend` 提供的执行模式证据与建议
- **预期输出**:用户明确选择 `Inline`、`Batch Inline` 或 `SDD` 执行模式,build-executor 据此创建受确认的执行计划。DP-4 不重新选择 DP-0 已确认的 `full`、`hotfix` 或 `tweak` 路径。
- **关联 skill**:`spec-superflow:build-executor`
Expand Down
Loading
Loading