docs(codestable): align goal mode handoff semantics

.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.

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 |
+| **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 print `/goal` |
+| **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-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; v1 still writes `.codestable/roadmap/`.
+- `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.
 

README.md

@@ -162,8 +162,8 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成
 
 | 流程 | 推荐主入口 | 说明 |
 |------|------------|------|
-| **特性引入** | `cs-feat` | 一个入口端到端推进 design → design-review → implementation → `cs-code-review` → QA → acceptance |
+| **特性引入** | `cs-feat` | 一个入口端到端推进 design → design-review → 用户确认 → goal 包长程执行 implementation → `cs-code-review` → QA → acceptance |
-| **大需求端到端** | `cs-epic` | 大需求规划 → 规划审查 → 用户确认 → 子 feature design/review → goal 执行包 → 输出 `/goal` 指令 |
+| **大需求端到端** | `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-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 执行包；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。
+- `cs-epic` 负责大需求规划和 goal 执行包，用户确认后派发可见 goal driver 长程执行；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。
 - `cs-code-review` 是横切 gate；`cs-docs-neat` 是阶段收尾整理器；`cs-docs` 只写对外指南和 API 参考。
 - 旧阶段技能是长期兼容入口，历史用户可以继续调用，但新文档和新提示词应使用主入口。
 

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}` 替换为本次实际值。不要替换 `<feature-slug>` 这类运行时占位；它们必须保留给 goal 会话在每个 feature 边界填写。

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/快照/类型/构建/目标测试等替代证据。缺说明或证据不足时继续补证据，不直接通过。

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。

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 节）。

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 阶段。"
 

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 / 状态 / 日志 / 取消或最终
+2. **宿主原生 Task/Agent**：只有同时满足下面两条才可用：
-   transcript 时可用。主 agent 必须能告诉用户如何查看这个 driver。
+   - 宿主显式暴露用户可见的 run id / 状态 / 日志 / 取消或最终 transcript，且主 agent
+     能告诉用户如何查看。
+   - 宿主显式支持 driver 在其运行环境内再启动独立 Task agent reviewer；review gate
+     必须能跑，不能靠 driver 自审。
+
+   任一条不能确认时，不要猜测可用；不要用原生子 agent 当 driver，直接回退打印 `/goal`，
+   避免 driver 在第一个 review gate 就 handoff。
 3. **不可见或派发失败**：不要静默后台运行。打印 fenced `/goal` 指令，让用户粘贴到新的
    agent 会话执行，并说明没有自动 driver 在跑。
 

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")