From 8b973a9912726abeeac3d023162a5ae25ed8fd66 Mon Sep 17 00:00:00 2001 From: dafang Date: Thu, 2 Jul 2026 21:32:24 +0800 Subject: [PATCH] docs(codestable): align goal mode handoff semantics --- ...ll-entry-simplification-refactor-design.md | 8 +++++ README.en.md | 8 ++--- README.md | 8 ++--- .../cs-epic/references/goal/protocol.md | 2 ++ .../cs-feat/references/acceptance/protocol.md | 2 +- .../cs-feat/references/goal/protocol.md | 28 +++++++++++++++ .../references/implementation/protocol.md | 4 ++- .../implementation/support/reference.md | 10 +++--- .../references/execution-conventions.md | 10 ++++-- tests/test_skill_entry_simplification.py | 34 +++++++++++++++++++ 10 files changed, 98 insertions(+), 16 deletions(-) diff --git a/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md index 8e76b5b..f866586 100644 --- a/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md +++ b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md @@ -168,3 +168,11 @@ Thick stage details should live in reference files, not in the main `SKILL.md`. - Old stage skill names remain present. - Thick workflow rules exist under main entry references. - Tests cover the migration invariants above. + +## 10. Amendments (2026-07-02) + +Long-range execution supersedes parts of decisions 17 and 21: + +1. `cs-feat` keeps one human checkpoint at the design gate. After the user approves the design, it generates a single-feature goal package and runs implementation, code review, QA, and acceptance long-range; ordinary stage blockers are fixed inside the goal loop, and only goal handoff conditions stop for the user. +2. `cs-epic` and `cs-feat` first try to dispatch a **visible Task agent goal driver** (Paseo subagent preferred, then host-native Task/Agent with user-visible run id/status/logs/cancel). Dispatch preconditions include the driver being able to launch independent Task agent reviewers in its own runtime. If no visible or capable driver exists, they print the fenced `/goal` command for the user to paste; they never run the long-range loop silently in the main thread (`cs-epic`) and never auto-execute slash commands. +3. Per-feature user-wait checkpoints convert to written reports/state/evidence in goal mode; design-gate confirmations, contract/scope changes, blocked independent reviewers, and repeated failures still hand off to the user. diff --git a/README.en.md b/README.en.md index 02dc37a..2637865 100644 --- a/README.en.md +++ b/README.en.md @@ -161,8 +161,8 @@ CodeStable models real coding work as a set of **entities** and **flows**. | Flow | Recommended main entry | Notes | |------|------------|------| -| **Feature delivery** | `cs-feat` | End-to-end design → design review → implementation → `cs-code-review` → QA → acceptance | -| **Epic delivery** | `cs-epic` | Plan a large demand, review it, design child features, prepare a goal package, then print `/goal` | +| **Feature delivery** | `cs-feat` | End-to-end design → design review → user gate → long-range goal run of implementation → `cs-code-review` → QA → acceptance | +| **Epic delivery** | `cs-epic` | Plan a large demand, review it, design child features, prepare a goal package, then dispatch a visible goal driver (print `/goal` as fallback) | | **Goal achievement** | `cs-goal` | Bounded start/end → interview/grill + start report → autonomous implement/validate/iterate → subagent functional acceptance | | **Issue fixing** | `cs-issue` | End-to-end report → analyze → fix → `cs-code-review` | | **Refactoring** | `cs-refactor` | Behavior-preserving cleanup; standard or fastforward mode, followed by `cs-code-review` | @@ -230,8 +230,8 @@ cs How to read it: - `cs` only triages to main entries; it no longer routes users to stage skills. -- `cs-feat`, `cs-issue`, and `cs-refactor` resume from repository facts and stop at human checkpoints. -- `cs-epic` prepares planning and goal packages; v1 still writes `.codestable/roadmap/`. +- `cs-feat`, `cs-issue`, and `cs-refactor` resume from repository facts. `cs-issue` and `cs-refactor` stop at review, blocking, or user-confirmation checkpoints; `cs-feat` stops only at the design gate, then runs impl, review, QA, and accept long-range via a visible goal driver. +- `cs-epic` prepares planning and goal packages, then dispatches a visible goal driver; v1 still writes `.codestable/roadmap/`. - `cs-code-review` is the cross-cutting gate; `cs-docs-neat` handles hygiene; `cs-docs` writes outward docs. - Old stage skills are long-term compatibility entries for historical users. diff --git a/README.md b/README.md index 9d35974..475582c 100644 --- a/README.md +++ b/README.md @@ -162,8 +162,8 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 | 流程 | 推荐主入口 | 说明 | |------|------------|------| -| **特性引入** | `cs-feat` | 一个入口端到端推进 design → design-review → implementation → `cs-code-review` → QA → acceptance | -| **大需求端到端** | `cs-epic` | 大需求规划 → 规划审查 → 用户确认 → 子 feature design/review → goal 执行包 → 输出 `/goal` 指令 | +| **特性引入** | `cs-feat` | 一个入口端到端推进 design → design-review → 用户确认 → goal 包长程执行 implementation → `cs-code-review` → QA → acceptance | +| **大需求端到端** | `cs-epic` | 大需求规划 → 规划审查 → 用户确认 → 子 feature design/review → goal 执行包 → 派发可见 goal driver（失败则输出 `/goal` 指令） | | **目标达成** | `cs-goal` | 限定起点/终点 → grill 写起点报告 → 自主实现/验证/迭代 → subagent 功能验收 | | **问题修改** | `cs-issue` | 一个入口端到端推进 report → analyze → fix → `cs-code-review` | | **代码重构** | `cs-refactor` | 行为等价重构；内部判定标准模式或 fastforward mode，完成后进入 `cs-code-review` | @@ -232,8 +232,8 @@ cs **怎么读这张图：** - `cs` 只做轻量分诊到主入口，不再把用户导向阶段技能。 -- `cs-feat` / `cs-issue` / `cs-refactor` 是连续编排入口，会按仓库事实恢复阶段，并在 design、review、QA、accept 等 checkpoint 停下等用户确认。 -- `cs-epic` 负责大需求规划和 goal 执行包；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。 +- `cs-feat` / `cs-issue` / `cs-refactor` 是连续编排入口，按仓库事实恢复阶段。`cs-issue` / `cs-refactor` 在 review、blocking 或用户确认 checkpoint 停下；`cs-feat` 只在 design gate 停下，用户确认后经可见 goal driver 长程完成 impl、review、QA、accept。 +- `cs-epic` 负责大需求规划和 goal 执行包，用户确认后派发可见 goal driver 长程执行；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。 - `cs-code-review` 是横切 gate；`cs-docs-neat` 是阶段收尾整理器；`cs-docs` 只写对外指南和 API 参考。 - 旧阶段技能是长期兼容入口，历史用户可以继续调用，但新文档和新提示词应使用主入口。 diff --git a/plugins/codestable/skills/cs-epic/references/goal/protocol.md b/plugins/codestable/skills/cs-epic/references/goal/protocol.md index d86341a..635e54a 100644 --- a/plugins/codestable/skills/cs-epic/references/goal/protocol.md +++ b/plugins/codestable/skills/cs-epic/references/goal/protocol.md @@ -139,6 +139,8 @@ features: `current_feature_index` 是 **0-based**，指向 `features` 数组中下一个要处理的元素；第一个 feature 必须是 `0`。每个 feature accepted 后必须 scoped-commit 且确认工作树干净，再加 1。展示给用户的 `Feature: N/总数` 仍使用 1-based。roadmap item 若在执行前被标 `dropped`，不要写入 `goal-state.features`；已进入 `goal-state.features` 的条目必须走到 `accepted` 或回退修复。 +与单 feature goal 不同，epic goal 用 `current_feature_index` 表示跨 feature 进度，并用每个 `features[].status` 表示单个 feature 状态；单 feature 内部的 implementation / review / QA / acceptance 细粒度阶段仍由对应 feature 产物和 `goal-protocol-feature-loop.md` 核验，不在 epic 顶层 state 里再复制一套 `stage` 字段。 + ### `goal-protocol*.md` 从 `support/protocol.md`、`protocol-feature-loop.md`、`protocol-gates.md`、`protocol-audit.md` 复制到 roadmap 目录，并把 `{roadmap-slug}` / `{roadmap-path}` / `{roadmap-file}` / `{items-file}` 替换为本次实际值。不要替换 `` 这类运行时占位；它们必须保留给 goal 会话在每个 feature 边界填写。 diff --git a/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md b/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md index 3e44859..e0b55cc 100644 --- a/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md +++ b/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md @@ -49,7 +49,7 @@ 6. **验证证据来源**——独立 `cs-feat` QA 阶段 不是 standalone accept 的硬前置；但验收必须有同等强度的验证证据： - 已有 `{slug}-qa.md`：读取并复核。frontmatter 必须 `doc_type=feature-qa`、`status=passed`；failed / blocked → 退回 `cs-feat` implementation 阶段 qa-fix；status 不是 passed → 不进入验收。 - 没有 `{slug}-qa.md`：不要强制切去跑 `cs-feat` QA 阶段。在本次 accept 里建立 `Inline Verification Matrix`，对照 design 第 3 节、checklist checks、review Test And QA Focus / residual risk 和项目测试入口，现场运行验证，并把证据写入 acceptance 第 3 节和第 10 节最终审计。这个模式等价于“accept-inline QA”，但不额外生成 QA 报告。 - - Goal 模式例外：`cs-epic` goal 阶段 协议明确要求逐 feature 生成 QA 报告；在 goal 模式缺 `{slug}-qa.md` 时按 goal protocol 停止，不走 accept-inline。 + - Goal 模式例外：`cs-feat` / `cs-epic` 的 goal 协议都明确要求生成 QA 报告；goal 模式缺 `{slug}-qa.md` 时按 goal protocol 停止，不走 accept-inline。 7. **核心证据复核**——不管证据来自 QA 报告还是 accept-inline，都按同一标准复核： - 功能性或 mixed feature：design 第 3 节、checklist checks、review QA focus 中的核心功能路径必须有运行证据。若核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行，acceptance 必须写 `status=blocked`。下一步按原因选择：代码/测试缺口 → `cs-feat` implementation 阶段 qa-fix 后重跑 review 和 accept-inline；环境缺口 → 先补环境；用户希望独立 QA 报告 → 跑 `cs-feat` QA 阶段。 - 非功能性 feature：不要求 e2e / browser / API，但必须写明为什么不需要端到端运行，并提供静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试等替代证据。缺说明或证据不足时继续补证据，不直接通过。 diff --git a/plugins/codestable/skills/cs-feat/references/goal/protocol.md b/plugins/codestable/skills/cs-feat/references/goal/protocol.md index d9d54b2..d6a124c 100644 --- a/plugins/codestable/skills/cs-feat/references/goal/protocol.md +++ b/plugins/codestable/skills/cs-feat/references/goal/protocol.md @@ -57,6 +57,22 @@ qa: ".codestable/features/YYYY-MM-DD-{slug}/{slug}-qa.md" acceptance: ".codestable/features/YYYY-MM-DD-{slug}/{slug}-acceptance.md" ``` +合法状态机： + +| stage | status | 何时写入 | 下一步 | +|---|---|---|---| +| implementation | ready-to-dispatch | goal 包生成后 | 派发 driver 或打印 `/goal` | +| implementation | running | driver 开始实现时 | 完成 checklist steps | +| review | ready | implementation gates 通过，evidence 已生成 | 运行 `cs-code-review` | +| review | fixing | review 有 blocking，进入 review-fix | 修完回 `review: ready` | +| qa | ready | review passed | 运行 `cs-feat` QA | +| qa | fixing | QA failed / blocked，进入 qa-fix | 修完回 `review: ready`，重跑 review 和 QA | +| acceptance | ready | QA passed | 运行 `cs-feat` acceptance | +| complete | passed | acceptance passed 且无 handoff | 打印 `CS_FEATURE_GOAL_COMPLETE` | +| handoff | blocked | 命中 handoff 条件 | 打印 `CS_FEATURE_GOAL_HANDOFF` | + +每次 stage / status 变化都要立即写回 `goal-state.yaml`。driver 中断后，后续 agent 先读 `goal-state.yaml`，再按仓库事实核验对应产物是否存在且状态匹配；不一致时以仓库事实为准并修正 state。 + `goal-protocol.md` 必须写明执行 loop： 1. 读取 design、checklist、goal-plan、goal-state。 @@ -67,6 +83,18 @@ acceptance: ".codestable/features/YYYY-MM-DD-{slug}/{slug}-acceptance.md" 6. QA passed 后进入 `cs-feat` acceptance，更新 checklist checks 和必要长期文档。 7. 全部通过后打印 `CS_FEATURE_GOAL_COMPLETE`。 +`goal-protocol.md` 还必须写明： + +- Goal 模式接管：普通流程中各阶段停等用户确认的 checkpoint，在 goal 模式下改为写入报告、状态和证据记录；只有命中 handoff 条件才停。 +- 每个阶段 gate 通过后按上表更新 `goal-state.yaml` 的 `stage` / `status`，保证 driver 中断后可按仓库事实重派续跑。 +- handoff 输出格式： + +```text +CS_FEATURE_GOAL_HANDOFF +Reason: <具体阻塞> +Next: <建议动作> +``` + handoff 条件： - 需要改变 approved design、feature 范围、公开契约或 roadmap item。 diff --git a/plugins/codestable/skills/cs-feat/references/implementation/protocol.md b/plugins/codestable/skills/cs-feat/references/implementation/protocol.md index 387e7f2..10e43f1 100644 --- a/plugins/codestable/skills/cs-feat/references/implementation/protocol.md +++ b/plugins/codestable/skills/cs-feat/references/implementation/protocol.md @@ -256,6 +256,8 @@ qa-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复 所有步骤完成后，按 `support/reference.md` 的"实现完成汇报"模板输出并停等用户 review。模板必须列出真实 `git status`、按步骤归类的改动、方案外触碰、新概念、step 证据、清洁度、交付物、知识候选、最后一轮本地审计和验收场景自检。 +Goal 模式例外（本轮按 feature / roadmap 目录下 `goal-protocol.md` 长程执行）：汇报照常落盘留档，但不停等用户 review，直接按 goal 协议进入 before_review gates 和 `cs-code-review`；只有命中 goal handoff 条件才停下交还用户。 + --- ## 测试用例怎么落 @@ -269,7 +271,7 @@ qa-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复 完整 checklist 见 `support/reference.md`。主文件保留硬门摘要： - [ ] 所有 steps 的 status 都 `done`，且每步有退出信号证据。 -- [ ] 完成汇报已输出，用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑对应 gate）。 +- [ ] 完成汇报已输出，用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑对应 gate；goal 模式为汇报落盘留档后按 goal 协议继续）。 - [ ] 没有未处理的"需要叫停"信号、方案外改动或清洁度缺口。 - [ ] 开始前做过基线预检；完成前做过最后一轮本地审计。 - [ ] 第 3 节关键场景每条都有证据 / 测试覆盖（fastforward 对照第 2 节）。 diff --git a/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md b/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md index ac1357c..77a8636 100644 --- a/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md +++ b/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md @@ -2,7 +2,7 @@ ## 写完后输出统一汇报 -所有步骤完成后用下面模板汇报，**停下来等用户 review**。 +所有步骤完成后用下面模板汇报。普通模式下**停下来等用户 review**；Goal 模式下把汇报写入报告 / 状态 / 证据记录后继续进入 before_review gates 和 `cs-code-review`，不等用户。 固定模板的意义：含糊汇报等于把验证责任推回用户。固定模板逼你把改了哪些文件、是否触碰方案外、是否引入新概念一一说清楚。 @@ -51,7 +51,7 @@ **Fastforward design**：对照第 2 节验收标准逐条核对 ``` -汇报后停等 review。 +普通模式汇报后停等 review。Goal 模式汇报后不停等用户，除非命中 goal handoff 条件。 ## 测试用例怎么落 @@ -68,7 +68,7 @@ coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` ## 退出条件 - [ ] 所有 steps 的 status 都 `done` -- [ ] 完成汇报已输出，用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑 `cs-code-review`） +- [ ] 完成汇报已输出；普通模式用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑 `cs-code-review`）；Goal 模式已把汇报写入报告 / 状态 / 证据记录并按 goal 协议继续 - [ ] 没有未处理的"需要叫停"信号 - [ ] 每个 step 都有退出信号证据；失败按诊断 / 窄范围修复说明 / 交还机制处理过 - [ ] 开始前做过基线预检，既有红灯已归因或已和用户对齐 @@ -82,7 +82,9 @@ coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` ## 退出后 -告诉用户："所有步骤完成，方案 doc 已同步。下一步阶段 2.5 代码审查，进入 cs-code-review。" +普通模式告诉用户："所有步骤完成，方案 doc 已同步。下一步阶段 2.5 代码审查，进入 cs-code-review。" + +Goal 模式不要停在这句汇报；按 goal 协议更新 `goal-state.yaml` 后进入 before_review gates 和 `cs-code-review`。如果需要改变 approved design、feature 范围、公开契约或 roadmap item，打印 `CS_FEATURE_GOAL_HANDOFF` / `CS_ROADMAP_GOAL_HANDOFF` 并交还用户。 如果本轮是 review-fix，告诉用户："review blocking 已按范围修复。下一步重跑 cs-code-review；复审通过后再进入 `cs-feat` QA 阶段。" diff --git a/plugins/codestable/skills/cs-onboard/references/execution-conventions.md b/plugins/codestable/skills/cs-onboard/references/execution-conventions.md index 6da341c..f8075e8 100644 --- a/plugins/codestable/skills/cs-onboard/references/execution-conventions.md +++ b/plugins/codestable/skills/cs-onboard/references/execution-conventions.md @@ -112,8 +112,14 @@ acceptance，并把证据写回仓库。 1. **Paseo subagent**：首选。Paseo 有 agent id、activity、status、permission 和 cancel 表面，用户能看见并接管长程执行。 -2. **宿主原生 Task/Agent**：仅当宿主暴露用户可见的 run id / 状态 / 日志 / 取消或最终 - transcript 时可用。主 agent 必须能告诉用户如何查看这个 driver。 +2. **宿主原生 Task/Agent**：只有同时满足下面两条才可用： + - 宿主显式暴露用户可见的 run id / 状态 / 日志 / 取消或最终 transcript，且主 agent + 能告诉用户如何查看。 + - 宿主显式支持 driver 在其运行环境内再启动独立 Task agent reviewer；review gate + 必须能跑，不能靠 driver 自审。 + + 任一条不能确认时，不要猜测可用；不要用原生子 agent 当 driver，直接回退打印 `/goal`， + 避免 driver 在第一个 review gate 就 handoff。 3. **不可见或派发失败**：不要静默后台运行。打印 fenced `/goal` 指令，让用户粘贴到新的 agent 会话执行，并说明没有自动 driver 在跑。 diff --git a/tests/test_skill_entry_simplification.py b/tests/test_skill_entry_simplification.py index 26ee261..e6d1d6f 100644 --- a/tests/test_skill_entry_simplification.py +++ b/tests/test_skill_entry_simplification.py @@ -223,6 +223,40 @@ def test_feat_and_epic_document_goal_driver_dispatch() -> None: assert "fenced `/goal`" in epic_goal +def test_goal_mode_overrides_stage_user_waits() -> None: + impl = (SKILLS / "cs-feat/references/implementation/protocol.md").read_text(encoding="utf-8") + impl_reference = (SKILLS / "cs-feat/references/implementation/support/reference.md").read_text(encoding="utf-8") + accept = (SKILLS / "cs-feat/references/acceptance/protocol.md").read_text(encoding="utf-8") + conventions = (SKILLS / "cs-onboard/references/execution-conventions.md").read_text(encoding="utf-8") + feat_goal = (SKILLS / "cs-feat/references/goal/protocol.md").read_text(encoding="utf-8") + epic_goal_support = (SKILLS / "cs-epic/references/goal/support/protocol.md").read_text(encoding="utf-8") + epic_goal = (SKILLS / "cs-epic/references/goal/protocol.md").read_text(encoding="utf-8") + readme = (ROOT / "README.md").read_text(encoding="utf-8") + readme_en = (ROOT / "README.en.md").read_text(encoding="utf-8") + + # implementation 的"停等用户 review"必须有 goal 模式例外，否则 driver 长程会被打断。 + assert "Goal 模式例外" in impl + assert "Goal 模式汇报后不停等用户" in impl_reference + assert "按 goal 协议更新 `goal-state.yaml`" in impl_reference + # acceptance 的 goal 例外要同时覆盖单 feature goal 和 epic goal。 + assert "`cs-feat` / `cs-epic` 的 goal 协议" in accept + # 原生子 agent 当 driver 前必须确认它还能启动独立 reviewer；不能就回退打印 /goal。 + assert "只有同时满足下面两条才可用" in conventions + assert "不能靠 driver 自审" in conventions + # 单 feature goal 包必须带接管条款和 handoff 标记，与 epic goal 包对齐。 + assert "合法状态机" in feat_goal + assert "| review | fixing |" in feat_goal + assert "| handoff | blocked |" in feat_goal + assert "Goal 模式接管" in feat_goal + assert "CS_FEATURE_GOAL_HANDOFF" in feat_goal + assert "goal 模式下改为写入报告" in epic_goal_support + assert "CS_ROADMAP_GOAL_HANDOFF" in epic_goal_support + assert "与单 feature goal 不同" in epic_goal + # README 不应暗示 issue/refactor 有标准 QA checkpoint。 + assert "review、blocking 或用户确认 checkpoint" in readme + assert "review, blocking, or user-confirmation checkpoints" in readme_en + + def test_compatibility_entries_do_not_declare_argument_hint() -> None: for skill in COMPATIBILITY_ENTRIES: text = (SKILLS / skill / "SKILL.md").read_text(encoding="utf-8")