diff --git a/.codestable/attention.md b/.codestable/attention.md index 85300ec..4dc4683 100644 --- a/.codestable/attention.md +++ b/.codestable/attention.md @@ -24,4 +24,4 @@ CodeStable 所有落盘产出的正文用**中文**：plan / design、plan revie ### 其他 -- 本仓库所有 CodeStable review gate（含 design review、code review 和修复后复审）统一使用 Paseo `provider=claude`、`model=claude-fable-5`、`thinkingOptionId=high`；不可用时停下报告，不静默降级 +- 调用 `cs-review`（含本仓库所有 CodeStable design review、code review 和修复后复审）时，发起者优先通过 Paseo 创建 fresh reviewer subagent，并与当前主 agent 异构：主 agent 为 Codex 时，首选 `provider=claude`、`model=claude-fable-5`、`thinkingOptionId=high`，不可用则回退 `provider=claude`、`model=claude-opus-5`；主 agent 为 Claude 时，使用 `provider=codex`、`model=gpt-5.6-sol`。指定路径均不可用时停下报告，不静默改用其他 reviewer diff --git a/AGENTS.md b/AGENTS.md index fecb13a..f77fb82 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,8 +20,9 @@ ## Epic 生命周期 -- 永久 Epic 文档是目标、范围、非目标、验收、已批准子项、关键决策、最终交付、整体验收、遗留风险和长期状态的唯一 owner；`.codestable/work/epic-{slug}.md` 只是临时执行游标，只写永久文档指针、批准 revision、phase、子项进度、下一步、阻塞和证据，不复制稳定契约或最终结论。 +- 永久 Epic 文档是目标、范围、非目标、验收、已批准子项、关键决策、最终交付、整体验收、遗留风险和长期状态的唯一 owner；`.codestable/work/epic-{slug}.md` 只是临时执行游标，只写永久文档指针、批准 revision、phase、子项进度、下一步、阻塞、`item_progression`、`milestone_commit`、`remote_publish` 和证据，不复制稳定契约或最终结论。 - 保留三道 owner gate：fresh design review 后确认拆解；目标、边界、验收、子项定义或重大风险变化时重新 review 并确认；全部子项完成后由 fresh reviewer 对最新 owner 已批准的验收标准做 final acceptance review，再由 owner 最终接受。 +- 普通子项完成不是 owner gate：`continuous` 策略下串行自动推进下一项，不询问是否继续或终态返回；只有显式 `per-item` 策略、owning-skill 门槛、真实阻塞、新权限或最终验收才暂停。 - Epic 进入 `accepted`、`superseded` 或 `cancelled` 终态后保留永久文档，幂等清理临时 Epic/子项 work；不恢复 `cs-goal` 入口、goal package、`state.yaml`、逐轮 iteration 报告或 legacy runtime gate。 ## 验证 diff --git a/CLAUDE.md b/CLAUDE.md index e3e6403..d47271c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,8 +22,9 @@ ## Epic 生命周期 -- 永久 Epic 文档是目标、范围、非目标、验收、已批准子项、关键决策、最终交付、整体验收、遗留风险和长期状态的唯一 owner；`.codestable/work/epic-{slug}.md` 只是临时执行游标，只写永久文档指针、批准 revision、phase、子项进度、下一步、阻塞和证据，不复制稳定契约或最终结论。 +- 永久 Epic 文档是目标、范围、非目标、验收、已批准子项、关键决策、最终交付、整体验收、遗留风险和长期状态的唯一 owner；`.codestable/work/epic-{slug}.md` 只是临时执行游标，只写永久文档指针、批准 revision、phase、子项进度、下一步、阻塞、`item_progression`、`milestone_commit`、`remote_publish` 和证据，不复制稳定契约或最终结论。 - 保留三道 owner gate：fresh design review 后确认拆解；目标、边界、验收、子项定义或重大风险变化时重新 review 并确认；全部子项完成后由 fresh reviewer 对最新 owner 已批准的验收标准做 final acceptance review，再由 owner 最终接受。 +- 普通子项完成不是 owner gate：`continuous` 策略下串行自动推进下一项，不询问是否继续或终态返回；只有显式 `per-item` 策略、owning-skill 门槛、真实阻塞、新权限或最终验收才暂停。 - Epic 进入 `accepted`、`superseded` 或 `cancelled` 终态后保留永久文档，幂等清理临时 Epic/子项 work；不恢复 `cs-goal` 入口、goal package、`state.yaml`、逐轮 iteration 报告或 legacy runtime gate。 ## v1 兼容边界 diff --git a/README.en.md b/README.en.md index 49f2934..903c6c6 100644 --- a/README.en.md +++ b/README.en.md @@ -101,7 +101,7 @@ For daily use, when you don't know which skill fits, call the root entry: /cs ``` -`cs` classifies whether you want execution, advice, or an overview. Action requests dispatch to the target skill in the current run; advice requests only recommend. Ambiguous requests get one focused question. +`cs` classifies whether you want execution, discussion first, advice, or an overview. Action requests dispatch in the current turn. Requests to discuss first converge in the current session and hand off in the same turn. Discussion creates no work cursor or cross-session state; the owning skill graduates stable conclusions into existing project docs, ADRs, permanent Epics, attention, or lessons. --- @@ -161,7 +161,7 @@ Thin rules do not mean no boundaries. What remains are **hard gates**, each deci | **Feature delivery** | `cs-feat` | High-risk designs are persisted to a work doc; the outer workflow creates a reviewer before user confirmation — never auto-approved; test-first when a setup exists; completion requires verifiable evidence | | **Issue fixing** | `cs-issue` | No root-cause guessing without a check that clearly turns red; the red check must turn green before claiming the fix | | **Refactoring** | `cs-refactor` | Equivalence evidence exists before code changes; stop and report the moment behavior would change | -| **Epic delivery** | `cs-epic` | A permanent Epic doc keeps the full picture and a temporary work cursor keeps execution state; decomposition, scope changes, and final acceptance after fresh-reviewer validation pass three owner gates | +| **Epic delivery** | `cs-epic` | A permanent Epic doc keeps the full picture and a temporary work cursor keeps execution state; confirmed items advance serially and continuously between the three owner gates | | **Independent review** | `cs-review` | Read-only leaf executor that returns one review without spawning agents; the outer workflow owns fixes and at most three review rounds | Engineering judgment does not occupy the always-loaded context: module depth, implementation economy, and debug escalation live in **on-demand references**, read only when the scene calls for them — the thin harness owns reliability, the thick context owns quality. @@ -176,10 +176,10 @@ The capture principle: **everything in its place, no archive hall**: | `lessons/` | One file per pitfall, technique, or research result; traceable evidence required, dedupe-and-merge first | | Project docs / ADRs | The canonical owner of current facts and structural decisions — CodeStable builds no parallel truth | | Permanent Epic docs | Long-lived goals, scope, approved items, key decisions, delivery index, and holistic acceptance | -| `work/` | Active cross-session tasks; Epic work is only a temporary cursor to the permanent doc, approved revision, and execution progress | +| `work/` | Active cross-session tasks; Epic work is only a temporary cursor to the permanent doc, approved revision, execution progress, and progression/commit/remote-publication policies | | git / PR | Execution history | -An Epic reuses an existing Epic, RFC, or initiative home when one exists; otherwise `.codestable/epics/` is created only on first need, and `cs-onboard` does not precreate it. The owner confirms decomposition after independent design review; changes to goals, scope, non-goals, acceptance, items, or major risks require owner reconfirmation; after all items complete, a fresh reviewer performs holistic terminal acceptance against the latest owner-approved criteria before the owner accepts. Terminal handling completes and graduates the permanent archive before deleting the Epic work cursor; the permanent Epic doc is never deleted as temporary output. +An Epic reuses an existing Epic, RFC, or initiative home when one exists; otherwise `.codestable/epics/` is created only on first need, and `cs-onboard` does not precreate it. The owner confirms decomposition after independent design review; changes to goals, scope, non-goals, acceptance, items, or major risks require owner reconfirmation; after all items complete, a fresh reviewer performs holistic terminal acceptance against the latest owner-approved criteria before the owner accepts. The first confirmation also records progression, milestone-commit, and remote-publication policies. Under the continuous policy, ordinary items advance serially and continuously; only an explicit per-item policy or a real gate pauses execution. Terminal handling completes and graduates the permanent archive before deleting the Epic work cursor; the permanent Epic doc is never deleted as temporary output. The nine v1 historical knowledge directories — `roadmap/`, `features/`, `issues/`, `refactors/`, `goals/`, `compound/`, `audits/`, `brainstorms/`, and `feedback/` — are searched read-only by task keywords with source citations. Do not generate into, rewrite in place, bulk-migrate, or write back to them. New conclusions go to permanent Epics, project docs, ADRs, or `lessons/`. @@ -197,7 +197,7 @@ Ordinary completed work docs **graduate before deletion**: the final report must | Group | Skill | Purpose | |---|---|---| -| Navigation | `cs` | Clear action requests dispatch to the target skill in the same turn; advice gets a recommendation only; the overview writes no files | +| Navigation | `cs` | Clear action requests dispatch in the same turn; requests to discuss first converge in the current session and hand off in the same turn; advice only recommends; the overview writes no files | | Onboard | `cs-onboard` | Create the minimal project-memory skeleton for a repository | | Feature | `cs-feat` | Implement new capability with process strength proportional to risk | | Issue | `cs-issue` | Fix bugs or broken behavior with red-to-green evidence | diff --git a/README.md b/README.md index 59d7234..6f68055 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ npx skills@latest add codestable/CodeStable/plugins/codestable --skill '*' -g /cs ``` -`cs` 会先判断你要执行、咨询还是了解体系：行动请求同轮直转，咨询请求只给建议；信息不足时只问一个聚焦问题。 +`cs` 会先判断你要执行、先讨论、咨询还是了解体系：行动请求同轮直转；先讨论的请求在当前会话收敛后同轮移交；咨询请求只给建议。讨论不创建 work 游标或跨会话状态，稳定结论由 owning skill 进入项目已有文档、ADR、永久 Epic、attention 或 lessons。 --- @@ -162,7 +162,7 @@ CodeStable 走的是**另一个方向**： | **特性引入** | `cs-feat` | 高风险设计先落盘 work 文档，由外层主流程创建 reviewer 做独立 review 后再交人确认，不 auto-approve；测试设施可用时测试先行；完成必须附可核验证据 | | **问题修复** | `cs-issue` | 没有能明确变红的验证不许猜根因；修复完成时变红的验证必须变绿 | | **代码重构** | `cs-refactor` | 先有能自证行为等价的验证再动代码；发现要改行为立即停下转向 | -| **大需求** | `cs-epic` | 永久 Epic 文档保存全景，临时 work 游标保存执行状态；拆解、范围性变化、fresh reviewer 整体验收后最终接受分别经过三道 owner gate | +| **大需求** | `cs-epic` | 永久 Epic 文档保存全景，临时 work 游标保存执行状态；三道 owner gate 之间串行连续推进已确认子项，不逐项询问是否继续 | | **独立审查** | `cs-review` | 只读叶子执行器，单轮返回发现，不创建子 agent；blocking 未解决不得通过，修复与最多 3 轮复审由外层主流程负责 | 工程判断力不占常驻上下文：模块深度、实现经济性、debug 升级路径这些"怎么做好"的判据放在**按需加载的 references** 里，进入对应场景才读——thin harness 管可靠，thick context 管质量。 @@ -177,10 +177,10 @@ CodeStable 走的是**另一个方向**： | `lessons/` | 一条一文件的坑、技巧、调研结论；写入必须有可追溯证据，先查重合并 | | 项目文档 / ADR | 当前事实与结构性决策的 canonical owner——CodeStable 不建平行真相 | | 永久 Epic 文档 | 长期保存目标、范围、已批准子项、关键决策、交付索引与整体验收 | -| `work/` | 进行中的跨会话任务；Epic work 只作指向永久文档、批准 revision 与执行进度的临时游标 | +| `work/` | 进行中的跨会话任务；Epic work 只作指向永久文档、批准 revision、执行进度与推进/提交/远端同步策略的临时游标 | | git / PR | 执行历史 | -Epic 优先沿用项目已有的 Epic、RFC 或 initiative 归宿，否则首次需要时才创建 `.codestable/epics/`；`cs-onboard` 不预建空目录。拆解经独立 design review 后由 owner 确认；目标、范围、非目标、验收、子项或重大风险变化时 owner 重新确认；全部子项完成后，由 fresh reviewer 按最新 owner 已批准的标准做终态整体验收，再由 owner 最终接受。终态先补齐永久档案并完成毕业，再删除 Epic work 游标，永久 Epic 文档不删除。 +Epic 优先沿用项目已有的 Epic、RFC 或 initiative 归宿，否则首次需要时才创建 `.codestable/epics/`；`cs-onboard` 不预建空目录。拆解经独立 design review 后由 owner 确认；目标、范围、非目标、验收、子项或重大风险变化时 owner 重新确认；全部子项完成后，由 fresh reviewer 按最新 owner 已批准的标准做终态整体验收，再由 owner 最终接受。首次确认同时记录推进、里程碑 commit 与远端同步策略；连续策略在普通子项完成后串行连续推进，只有显式逐项策略或真实门槛才暂停。终态先补齐永久档案并完成毕业，再删除 Epic work 游标，永久 Epic 文档不删除。 v1 的 `roadmap/`、`features/`、`issues/`、`refactors/`、`goals/`、`compound/`、`audits/`、`brainstorms/` 与 `feedback/` 九个历史知识目录只按任务关键词只读检索并引用来源；不生成、不原地改写、不批量迁移，也不写回。新结论进入永久 Epic、项目文档、ADR 或 `lessons/`。 @@ -198,7 +198,7 @@ v1 的 `roadmap/`、`features/`、`issues/`、`refactors/`、`goals/`、`compoun | 分组 | 技能 | 用途 | |---|---|---| -| 导航 | `cs` | 明确行动诉求同轮直转对应入口；咨询只推荐；导览不写文件 | +| 导航 | `cs` | 明确行动同轮直转；先讨论的请求在当前会话收敛后同轮移交；咨询只推荐；导览不写文件 | | 接入 | `cs-onboard` | 为仓库创建最小项目记忆骨架 | | 功能 | `cs-feat` | 实现新功能或功能改造，流程强度与风险相称 | | 问题 | `cs-issue` | 用红到绿证据修复 bug 或既有行为异常 | diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md index ee5295f..bab05b6 100644 --- a/SKILL_CATALOG.en.md +++ b/SKILL_CATALOG.en.md @@ -7,22 +7,24 @@ skill files or a centralized onboard runtime. | Group | Skill | Responsibility | |---|---|---| -| Navigation | `cs` | Clear action requests dispatch to the target skill in the same turn; advice gets a recommendation only; the overview writes no files | +| Navigation | `cs` | Clear actions dispatch in the same turn. Requests to discuss first converge in the current session and hand off in the same turn; advice only recommends; the overview writes no files | | Onboarding | `cs-onboard` | Create minimal project memory and explain a lossless v1 upgrade | | Feature | `cs-feat` | Implement new capability; scale design confirmation and independent review with risk | | Issue | `cs-issue` | Fix bugs or broken existing behavior with red-to-green evidence | | Refactor | `cs-refactor` | Change structure or performance under verifiable behavioral equivalence | -| Epic | `cs-epic` | Decompose, confirm, and drive multiple deliverable items through a permanent Epic doc and temporary work execution cursor | +| Epic | `cs-epic` | Decompose, confirm, and advance multiple deliverable items serially and continuously through a permanent Epic doc and temporary work cursor | | Review | `cs-review` | Read-only leaf executor for one change, design, module, or repository review | | Memory | `cs-keep` | Store evidence-backed frequent facts or reusable lessons in project memory | `cs-code-review` ships as the single compatibility alias of `cs-review` (the carried-over v1 name; forwarding only, no independent rules). +Discussion exists only in the current session and creates no work cursor or transcript; stable assets graduate through the owning skill into their canonical homes, while unresolved discussion has no cross-session recovery promise. + ## Project Knowledge and Epic Boundary -New projects still precreate only `.codestable/attention.md`, `lessons/`, and `work/`. An Epic reuses an existing project home or creates `.codestable/epics/` only on first need: the permanent doc keeps goals, scope, approved items, decisions, delivery index, and terminal acceptance, while `work/epic-{slug}.md` is only a temporary cursor for the approved revision and execution progress; terminal handling deletes the cursor but retains the permanent archive. +New projects still precreate only `.codestable/attention.md`, `lessons/`, and `work/`. An Epic reuses an existing project home or creates `.codestable/epics/` only on first need: the permanent doc keeps goals, scope, approved items, decisions, delivery index, and terminal acceptance, while `work/epic-{slug}.md` is only a temporary cursor for the approved revision, execution progress, and `item_progression` / `milestone_commit` / `remote_publish` policies; terminal handling deletes the cursor but retains the permanent archive. -Epics retain three owner gates: the owner confirms decomposition after independent design review; reconfirms changes to goals, scope, non-goals, acceptance, items, or major risks; and finally accepts only after all items complete and a fresh reviewer performs holistic terminal acceptance against the latest owner-approved criteria. +Epics retain three owner gates: the owner confirms decomposition after independent design review; reconfirms changes to goals, scope, non-goals, acceptance, items, or major risks; and finally accepts only after all items complete and a fresh reviewer performs holistic terminal acceptance against the latest owner-approved criteria. The continuous policy adds no artificial gate at an ordinary item boundary. The nine v1 historical knowledge directories — `roadmap/`, `features/`, `issues/`, `refactors/`, `goals/`, `compound/`, `audits/`, `brainstorms/`, and `feedback/` — are searched and cited read-only by task keywords. Do not generate into, rewrite in place, bulk-migrate, or write back to them. @@ -41,7 +43,7 @@ package. | `cs-refactor-ff` | Use `cs-refactor` | | `cs-audit` | Use the audit mode of `cs-review` | | `cs-goal`, `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | Use `cs-epic` for large initiatives; do not restore the goal package, `state.yaml`, per-iteration reports, or runtime gates | -| `cs-brainstorm`, `cs-domain`, `cs-req` | Clarify within `cs-feat` / `cs-epic`; update project docs or ADRs directly | +| `cs-brainstorm`, `cs-domain`, `cs-req` | Align in the current session through `cs`, then hand off in the same turn to `cs-feat`, `cs-issue`, or `cs-epic`; the owning skill graduates stable assets into canonical project docs, ADRs, or a permanent Epic | | `cs-docs`, `cs-docs-neat`, `cs-doc-api`, `cs-doc-tutorial` | Update docs as part of the owning development task, or request a standalone documentation edit directly | | `cs-note` | Use `cs-keep` | | `cs-feedback` | Store project lessons with `cs-keep`; submit product feedback through the repository issue process | diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md index 6b4001a..3373a81 100644 --- a/SKILL_CATALOG.md +++ b/SKILL_CATALOG.md @@ -7,22 +7,24 @@ runtime。 | 分组 | Skill | 责任 | |---|---|---| -| 导航 | `cs` | 明确行动诉求同轮直转对应入口；咨询只推荐；导览不写文件 | +| 导航 | `cs` | 明确行动同轮直转；先讨论的请求在当前会话收敛后同轮移交；咨询只推荐；导览不写文件 | | 接入 | `cs-onboard` | 创建最小项目记忆骨架；无损说明 v1 升级边界 | | 功能 | `cs-feat` | 实现新功能；按风险决定是否先确认设计或做独立 review | | 问题 | `cs-issue` | 用红到绿的验证修复 bug 或既有行为异常 | | 重构 | `cs-refactor` | 在可核验的行为等价约束下调整结构或性能 | -| 大需求 | `cs-epic` | 用永久 Epic 文档与临时 work 执行游标拆解、确认并长程推进多个可交付子项 | +| 大需求 | `cs-epic` | 用永久 Epic 文档与临时 work 游标拆解、确认并串行连续推进多个可交付子项 | | 审查 | `cs-review` | 只读叶子执行器；单轮审查，不创建子 agent | | 记忆 | `cs-keep` | 将有证据的高频事实或可复用经验写入项目记忆 | `cs-code-review` 作为 `cs-review` 的唯一兼容别名随包交付（v1 沿用名，只转发、不含独立规则）。 +讨论本身只存在于当前会话，不创建 work 游标或 transcript；稳定资产由 owning skill 按 canonical 归宿毕业，未收敛讨论不承诺跨会话恢复。 + ## 项目知识与 Epic 边界 -新项目仍只预建 `.codestable/attention.md`、`lessons/` 与 `work/`。Epic 优先沿用项目已有归宿，否则首次需要时才创建 `.codestable/epics/`：永久文档保存目标、范围、已批准子项、决策、交付索引与终态验收，`work/epic-{slug}.md` 只作批准 revision 与执行进度的临时游标，终态删除游标但保留永久档案。 +新项目仍只预建 `.codestable/attention.md`、`lessons/` 与 `work/`。Epic 优先沿用项目已有归宿，否则首次需要时才创建 `.codestable/epics/`：永久文档保存目标、范围、已批准子项、决策、交付索引与终态验收，`work/epic-{slug}.md` 只作批准 revision、执行进度与 `item_progression` / `milestone_commit` / `remote_publish` 策略的临时游标，终态删除游标但保留永久档案。 -Epic 保留三道 owner gate：独立 design review 后确认拆解；目标、范围、非目标、验收、子项或重大风险变化时重新确认；全部子项完成并由 fresh reviewer 按最新 owner 已批准标准做终态整体验收后，由 owner 最终接受。 +Epic 保留三道 owner gate：独立 design review 后确认拆解；目标、范围、非目标、验收、子项或重大风险变化时重新确认；全部子项完成并由 fresh reviewer 按最新 owner 已批准标准做终态整体验收后，由 owner 最终接受。连续策略在普通子项边界不新增人工 gate。 v1 的 `roadmap/`、`features/`、`issues/`、`refactors/`、`goals/`、`compound/`、`audits/`、`brainstorms/` 与 `feedback/` 九个历史知识目录只按任务关键词只读检索和引用，不生成、不原地改写、不批量迁移，也不写回。 @@ -40,7 +42,7 @@ v1 的 `roadmap/`、`features/`、`issues/`、`refactors/`、`goals/`、`compoun | `cs-refactor-ff` | 进入 `cs-refactor` | | `cs-audit` | 使用 `cs-review` 的 audit 模式 | | `cs-goal`, `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | 大需求进入 `cs-epic`；不恢复 goal package、`state.yaml`、逐轮报告或 runtime gate | -| `cs-brainstorm`, `cs-domain`, `cs-req` | 功能或大需求在 `cs-feat` / `cs-epic` 内澄清；项目事实直接更新到项目文档或 ADR | +| `cs-brainstorm`, `cs-domain`, `cs-req` | 先由 `cs` 在当前会话对齐；收敛后同轮进入 `cs-feat` / `cs-issue` / `cs-epic`，稳定资产由 owning skill 进入 canonical 项目文档、ADR 或永久 Epic | | `cs-docs`, `cs-docs-neat`, `cs-doc-api`, `cs-doc-tutorial` | 在对应开发任务中同步文档，或直接提出独立文档请求 | | `cs-note` | 进入 `cs-keep` | | `cs-feedback` | 项目经验进入 `cs-keep`；产品反馈按仓库 issue 流程提交 | diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md index 9a39f14..8c4cb2a 100644 --- a/WORKFLOW.en.md +++ b/WORKFLOW.en.md @@ -3,12 +3,14 @@ ## Workflow CodeStable v2 consists of eight independently installed thin-harness skills and a project-memory -loop. `cs` classifies what the user wants right now: clear action requests dispatch to the target -skill in the same turn and continue executing; advice requests get a recommendation only; with no -request it presents the overview. +loop. `cs` classifies whether the user wants execution, discussion first, advice, or an overview. +Explicit action dispatches in the same turn by default; a discussion-first request converges in the +current session and hands off under existing authorization; advice only recommends, and a request +without a task gets an overview. ```text unsure which entry -> cs +discuss / align first -> cs -> cs-feat / cs-issue / cs-epic onboard / v1 upgrade -> cs-onboard new capability -> cs-feat ---------\ bug / broken behavior -> cs-issue ----------> cs-review (high risk or on demand) @@ -17,6 +19,29 @@ large initiative -> cs-epic -> cs-feat / cs-issue / cs-refactor lessons and memory -> cs-keep ``` +### In-session discussion and handoff + +- Explicit action dispatches in the same turn by default. Only when the user explicitly asks to discuss first + does that request override the default. Discuss may also start when repository facts still cannot identify the + action type or owning skill and a product decision would materially change whether the flow documents or edits + code. Once the owning skill is known, its own intake refines goals, boundaries, and acceptance. +- Discussion exists only in the current session. The agent investigates facts available from the repository, + asks one real owner decision at a time, and tests shared language with concrete scenarios and boundaries. + It does not create a discussion work cursor or transcript. Unresolved discussion is not recoverable across sessions. +- When handoff-ready, the in-memory packet carries the target entry, original request, goal or expected behavior, + scope, non-goals, acceptance, verified repository facts and sources, owner decisions, unresolved risks, and + asset pointers. With existing execution authorization, it hands off in the same turn to `cs-feat`, `cs-issue`, + or `cs-epic` and must not ask whether to continue. Discussion itself creates no authorization. The handoff does + not expand authorization or replace the owning skill's review, verification, or owner gates. +- Raw questions, answers, unresolved discussion, and candidate branches are not persisted. Stable terms graduate + to the project's existing canonical terminology home. A structural choice becomes an ADR only when it is hard + to reverse, surprising without context, and the result of a real trade-off. The owning skill graduates task + contracts, permanent Epics, attention, and lessons under existing rules; no parallel truth is invented. When no + canonical home exists, ask the owner to choose one. +- Outside the three confirmed handoff targets, outcomes use `cs`'s existing Execute / Advise rules and receive no + duplicate-confirmation privilege. When only discussion is authorized, `cs` returns the confirmed conclusions + and recommends `cs-keep` or the owning skill for asset graduation. + Execution strength follows risk: - `cs-feat` normally understands, implements, and verifies directly. Public contracts, data, @@ -46,9 +71,10 @@ Execution strength follows risk: current candidate or create a formal milestone. After fixes, verify, freeze a new target, and use a fresh reviewer. A formal semantic milestone requires the review gate plus existing commit authorization; a WIP/checkpoint exists only for recovery or an isolated baseline and does not mean approval. -- An Epic advances one confirmed item at a time. Start the next item only after the current one reaches - its milestone. Without commit authorization, deliver the checkpoint for an owner decision instead - of accumulating multiple items in one diff. +- An Epic allows only one `current_item` at a time. This is a serialization constraint, not a per-item owner gate. + Under the continuous policy, an ordinary item milestone advances automatically; it must not ask whether + to continue to the next item or return as a terminal result. Per-item pauses require an explicit owner policy + or a real gate. - A healthy running reviewer remains bound to its run and target. When Awaiting carries the same queryable run identity and remains active, keep waiting; discovering a better creation method later does not justify cancellation, duplicate creation, or parallel @@ -72,10 +98,10 @@ An Epic separates durable product intent from temporary execution state and keep points, key decisions, final delivery index, overall acceptance, residual risks, and durable `status`. - The **temporary execution cursor** at `.codestable/work/epic-{slug}.md` stores only the permanent document pointer, `approved_revision`, execution `phase`, current item ID, per-ID progress, next action, - `blocked_by`, temporary decisions, and evidence/commit pointers. It must not duplicate goals, - acceptance criteria, item definitions, or final conclusions. After owner confirmation, the full - permanent-document SHA-256 fixes the approved revision. The active permanent document stays frozen; - routine progress changes only the cursor. + `blocked_by`, `item_progression`, `milestone_commit`, `remote_publish`, temporary decisions, and + evidence/commit pointers. It must not duplicate goals, acceptance criteria, item definitions, or final + conclusions. After owner confirmation, the full permanent-document SHA-256 fixes the approved revision. + The active permanent document stays frozen; routine progress and execution policies change only the cursor. An Epic retains three owner gates: @@ -89,6 +115,26 @@ An Epic retains three owner gates: outer workflow creates a fresh reviewer for a final acceptance review against the latest owner-approved criteria. Passing that gate does not replace the owner's final acceptance. +The first gate determines item progression, milestone commit, and remote publication policies once. Approving +the decomposition does not itself grant version-control authorization. Store those policies in the work cursor +and reuse them on recovery; only missing or invalid values pause once for repair. An owner-explicit policy change +updates only the cursor, not the approved hash. `milestone_commit: manual` requires +`item_progression: per-item` and `remote_publish: manual`; `remote_publish: each-milestone` requires +`milestone_commit: authorized`. + +With `item_progression: continuous`, after a non-final item completes, choose the first incomplete item in +permanent-document order whose dependencies are satisfied and continue in the same entrusted workflow. An +ordinary item completion is not an owner gate; the workflow must not ask whether to continue to the next item +or return that completion as terminal. With `per-item`, pause under the recorded per-item checkpoint policy. +Owning-skill gates, important findings requiring owner acceptance, real blockers, new authorization, and the +final owner gate may still pause execution. + +With `remote_publish: each-milestone`, publish after every semantic commit using the branch/remote policy +already selected by the project, host, or owner. With `final`, publish once after integration verification and +the final acceptance review pass, before requesting the owner's final acceptance. With `manual`, the agent does +not publish remotely. An unspecified branch/remote or a publication failure records a blocker and pauses; the +agent neither chooses a policy nor continues silently. + After owner acceptance, complete the permanent Epic's final scope, key decisions, delivery index, acceptance evidence, and residual risks; then set `accepted`, remove its work pointer, and delete the Epic and child-item cursors. Never delete the permanent Epic document. Finish `superseded` and `cancelled` diff --git a/WORKFLOW.md b/WORKFLOW.md index 81ea7a4..4ed8359 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -3,10 +3,12 @@ ## 工作流 CodeStable v2 是 8 个独立安装的 thin-harness skill，加一个项目记忆闭环。`cs` 判别用户 -此刻要什么：明确行动诉求**同轮直转**对应 skill 并继续执行；咨询只给推荐；无诉求时介绍体系。 +此刻要执行、先讨论、咨询还是了解体系：明确行动默认优先同轮直转；先讨论的请求在当前会话 +收敛并按授权移交；咨询只给推荐；无诉求时介绍体系。 ```text 不确定入口 -> cs +先讨论 / 对齐 -> cs -> cs-feat / cs-issue / cs-epic 仓库接入 / v1 升级 -> cs-onboard 新功能 -> cs-feat ---------\ bug / 行为异常 -> cs-issue ----------> cs-review（高风险或按需） @@ -15,6 +17,24 @@ bug / 行为异常 -> cs-issue ----------> cs-review（高风险或按需） 经验与项目记忆 -> cs-keep ``` +### 会话内讨论与 handoff + +- 明确行动默认优先同轮直转；用户显式要求先讨论时才覆盖该默认。调查仓库事实后仍无法安全判断 + 行动类型或 owning skill，且产品决策会实质改变建档或改代码路径时，也可进入 Discuss；owning + skill 已可判定时，目标、边界与验收细化交给该 skill，不在入口层增加 gate。 +- 讨论只存在于当前会话：仓库可核实的事实由 agent 自行调查，一次只问一个真正需要 owner 决定的 + 问题，并用精确术语、具体场景和边界案例检验理解。它不创建 discussion work 游标或 transcript； + 未收敛讨论不跨会话恢复。 +- handoff-ready 时，packet 保存目标入口、原始诉求、目标或期望行为、范围、非目标、验收、已核实 + 仓库事实及来源、owner 决策、未决风险与资产指针。已有执行授权时同轮移交给 `cs-feat`、 + `cs-issue` 或 `cs-epic`，不再询问“是否继续”；讨论过程本身不产生授权，handoff 不扩大授权， + 也不替代 owning skill 的 review、验证或 owner gate。 +- 原始问答、未决讨论和候选分支不落盘。稳定术语进入项目已有 canonical 术语归宿，结构性取舍仅在 + 难逆转、缺少上下文会令人意外且存在真实取舍时进入 ADR；任务契约、永久 Epic、attention 与 + lessons 由 owning skill 按既有规则毕业。没有 canonical 归宿时请 owner 选择，不新建平行真相。 +- 三个已确认出口之外的结果按 `cs` 既有 Execute / Advise 规则同轮直转或推荐，不获得 handoff 的 + 不重复确认特权。只授权讨论时，`cs` 返回已确认结论并推荐由 `cs-keep` 或 owning skill 完成毕业。 + 执行强度与风险相称： - `cs-feat` 默认直接理解、实现、验证；公开契约、数据、权限、并发或真实方案取舍先经用户确认。 @@ -26,7 +46,7 @@ bug / 行为异常 -> cs-issue ----------> cs-review（高风险或按需） - 外层主流程派发前冻结一个明确的审查目标（diff review 优先 staged diff，也可用明确 range/patch；design review 冻结对应文档版本；audit 冻结 commit + 范围标识），reviewer 返回前不移动目标或对应工作树；目标变化则本轮失效。 - `cs-review` 是只读叶子执行器，也承接模块或全仓 audit；修复与复审由外层主流程负责。 - 有 blocking 或未被用户明确接受的 important 时不提交当前候选，也不创建正式里程碑；修复后重新验证、冻结目标并创建 fresh reviewer。只有审查门槛通过且已有 commit 授权时才形成语义原子里程碑；WIP/checkpoint 只作恢复或隔离基线，不代表通过。 -- Epic 每次只推进一个已确认子项；子项达到里程碑后再进入下一个。未获 commit 授权时先交付 checkpoint 等用户决定，不把多个子项堆进同一 diff。 +- Epic 同一时间只允许一个 `current_item`；这是串行约束，不是每个子项的人工 gate。连续策略下，普通子项达到语义原子里程碑后自动进入下一项，不得询问“是否继续下一项”或终态返回；逐项暂停必须是 owner 明示策略或真实门槛。 - 健康运行中的 reviewer 与原 run/target 绑定；running，或 Awaiting 携带同一可查询 run identity 且仍为活动态时继续等待，不因后来发现更优创建方式而取消、重复创建或并行补发。只有终止无报告、run identity 不可恢复、能力不满足或目标失效时，本轮才失败且不计审查轮次；外层主流程先诊断再决定有界重试、更换创建方式或上交，不盲目重发。 - `cs-keep` 把高频事实压进 attention，把可复用经验写成 lesson。 @@ -43,8 +63,9 @@ Epic 把长期产品意图与短期执行状态分成两层，并且只保留一 关键决策、最终交付索引、整体验收、遗留风险和长期 `status`。 - **临时执行游标** `.codestable/work/epic-{slug}.md` 只保存永久文档指针、 `approved_revision`、执行 `phase`、当前子项 ID、各 ID 进度、下一步、`blocked_by`、临时 - 决策以及证据/commit 指针；不得复制目标、验收、子项定义或最终结论。owner 确认后以永久 - 文档完整 SHA-256 固定批准 revision；active 期间永久文档冻结，日常进度只更新游标。 + 决策、`item_progression`、`milestone_commit`、`remote_publish` 以及证据/commit 指针；不得复制 + 目标、验收、子项定义或最终结论。owner 确认后以永久文档完整 SHA-256 固定批准 revision； + active 期间永久文档冻结，日常进度与执行策略只更新游标。 Epic 保留三道 owner gate： @@ -55,6 +76,22 @@ Epic 保留三道 owner gate： 3. 全部子项完成并通过集成验证后，游标进入 acceptance；当前主流程创建 fresh reviewer， 对最新 owner 已批准的验收标准做 final acceptance review，门槛通过后仍由 owner 最终接受。 +首次 gate 一次性确定子项推进、里程碑 commit 与远端同步策略；拆解确认本身不等于版本控制授权。 +策略写入 work 游标并在恢复时直接沿用，缺失或非法才暂停一次补记；owner 显式改变策略只更新游标， +不改变批准 hash。`milestone_commit: manual` 只能搭配 `item_progression: per-item`， +且只能搭配 `remote_publish: manual`；`remote_publish: each-milestone` 只能搭配 +`milestone_commit: authorized`。 + +`item_progression: continuous` 时，非最终子项完成后按永久文档顺序选择第一个依赖已满足的未完成 +子项，并在同一受托主流程继续。普通子项完成不是 owner gate；不得询问“是否继续下一项”，也 +不得把它作为终态返回。`per-item` 时按已记录的逐项 checkpoint 策略暂停。子项 owning skill 自身的 +门槛、需要 owner 明确接受的 important findings、真实阻塞、新增权限与最终 owner gate 仍可暂停。 + +`remote_publish: each-milestone` 在每个语义原子 commit 后按项目、宿主或 owner 已确定的 +branch/remote 策略发布；`final` 在集成验证与 final acceptance review 通过后、请求 owner 最终接受前 +发布一次；`manual` 时 agent 不执行远端发布。branch/remote 未明确或发布失败时写入阻塞并暂停， +agent 不自行选择或静默继续。 + owner 接受后，先补齐永久 Epic 的最终范围、关键决策、交付索引、验收证据和遗留风险，再置为 `accepted`，移除 work 指针并删除 Epic/所属子项游标；永久 Epic 文档不得删除。`superseded` 或 `cancelled` 也按终态幂等收尾，不恢复执行或创建重复 Epic。不恢复 `cs-goal` 入口、goal package、 diff --git a/docs/adr/005-project-knowledge-and-epic-lifecycle.md b/docs/adr/005-project-knowledge-and-epic-lifecycle.md index c57cada..e9cd3d9 100644 --- a/docs/adr/005-project-knowledge-and-epic-lifecycle.md +++ b/docs/adr/005-project-knowledge-and-epic-lifecycle.md @@ -38,24 +38,40 @@ Epic 同时需要长期可读的产品意图和短期可变的执行状态。把 - 每个 Epic 分成两层且只保留一个事实 owner：永久 Epic 文档承载起点、目标、范围、非目标、 验收标准、带稳定 ID/依赖/验收要点的已批准子项、关键决策、最终交付索引、整体验收、遗留 风险和长期 `status`；`work/epic-{slug}.md` 只保存永久文档指针、`approved_revision`、执行 - `phase`、当前子项 ID、各 ID 的进度、下一步、阻塞、临时决策记录以及证据或 commit 指针， - 不复制子项定义、目标、验收或最终结论。 + `phase`、当前子项 ID、各 ID 的进度、下一步、阻塞、`item_progression`、`milestone_commit`、 + `remote_publish`、临时决策记录以及证据或 commit 指针，不复制子项定义、目标、验收或最终结论。 - 永久文档 `status` 只允许 `proposed -> active -> accepted`；owner 放弃时可从任一非终态转为 `cancelled`，被后继 Epic 取代时可转为 `superseded`。work 的 `phase` 只允许 `planning -> executing -> acceptance`；阻塞只写 `blocked_by`，解除后仍处于原 phase，不另造状态。 -- `approved_revision` 在 planning 时为 `pending`。owner 确认 proposed 文档后，主流程机械地把 - 永久文档置为 `active`，以 `shasum -a 256 ` 得到完整文件 SHA-256，只写入 work - 游标并把 phase 推进为 executing；确认前不得写入候选 hash。active 期间永久文档保持冻结， +- `approved_revision` 在 planning 时为 `pending`。拆解确认本身不等于版本控制授权；首次 owner + gate 同时一次性确定 `item_progression: continuous | per-item`、 + `milestone_commit: authorized | manual` 与 `remote_publish: each-milestone | final | manual`。 + `milestone_commit: manual` 只能搭配 `item_progression: per-item` 和 `remote_publish: manual`， + `remote_publish: each-milestone` 只能搭配 `milestone_commit: authorized`；进入 executing 前不得保留 + `pending` 或非法组合。 + owner 确认 proposed 文档和策略后，主流程机械地把永久文档置为 `active`，以 + `shasum -a 256 ` 得到完整文件 SHA-256，只写入 work 游标并把 phase 推进为 executing； + 确认前不得写入候选 hash。active 期间永久文档保持冻结， 日常进度和临时决策只写 work；目标、范围、非目标、验收、子项定义或重大风险变化时更新 永久文档，按与首次激活相同的 review、owner 确认和中断规则替换该 hash。确认前不得写候选 hash；任一激活步骤中断且无法恢复 owner 确认证据时重新确认，不把 `pending` 或候选值当批准。 - 恢复执行以仓库事实为准：先定位 work 游标，读取其 Epic 指针、phase 与批准 hash，并核对 - active 永久文档的当前 SHA-256；游标、永久文档或仓库事实不一致时先修复或请求上下文， - 不从聊天历史猜状态。 + active 永久文档的当前 SHA-256 和三个执行策略字段；有效字段直接沿用，不重新询问是否继续。 + 旧游标缺字段或组合非法时暂停一次请 owner 补记/修正；owner 中途改变策略只更新 work 游标， + 不改变永久文档或批准 hash，agent 不得从历史操作推断授权。 - Epic 保留三个 owner gate：拆解经独立 design review 后确认目标、边界、验收与子项；目标、 范围、非目标、验收、子项增删/定义或重大风险变化时重新确认；全部子项完成并由 fresh reviewer 对最新 owner 已批准的验收标准做整体验收后，由 owner 最终接受。边界内的日常技术 选择和不改变依赖/验收的子项顺序微调不新增人工 gate。 +- 本 ADR 经实际 Epic 执行反馈补充连续推进语义：同一时间只有一个 `current_item` 是 + 串行约束，不是每个子项的人工 gate。`item_progression: continuous` 时，非最终子项成为语义原子里程碑后， + 按永久文档顺序自动选择第一个依赖已满足的未完成子项并在同一受托主流程继续；普通子项完成 + 不得成为终态返回或“是否继续下一项”的人工 checkpoint。逐项暂停只来自 owner 明示的 + `per-item` 策略、既有 owner/owning-skill gate、真实阻塞、新增权限或需 owner 接受的 findings。 +- 远端发布不接管项目的 branch/remote 策略：`each-milestone` 在每个语义原子 commit 后按项目、 + 宿主或 owner 已确定的策略发布，`final` 在集成验证与 final acceptance review 通过后、请求 owner + 最终接受前发布一次，`manual` 由 owner 自行处理。branch/remote 未明确或发布失败时写入阻塞并暂停， + agent 不自行选择或静默继续。 - Epic 被接受后先写齐最终范围、关键决策、交付索引、验收证据、遗留风险与毕业清单，再用一次 终态更新把永久文档置为 `accepted` 并移除临时 `work` 指针。稳定产品契约、结构性决策和经验 分别毕业到 requirement、ADR 与 lesson；随后删除 Epic work 游标和所属子项 work，永久 Epic diff --git a/plugins/codestable/skills/cs-epic/SKILL.md b/plugins/codestable/skills/cs-epic/SKILL.md index e4f7f33..7b460c8 100644 --- a/plugins/codestable/skills/cs-epic/SKILL.md +++ b/plugins/codestable/skills/cs-epic/SKILL.md @@ -13,7 +13,9 @@ argument-hint: "[大需求描述]" - 有 `.codestable/attention.md` 就先读。 - 按任务关键词在存在的 `.codestable/lessons/`、项目文档以及 v1 只读知识目录 `.codestable/roadmap/`、`.codestable/features/`、`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、`.codestable/audits/`、`.codestable/brainstorms/`、`.codestable/feedback/` 中 grep；命中要报告来源路径。上述 v1 目录只读，不得继续生成、原地改写或批量迁移；新结论毕业到永久 Epic、项目文档、ADR 或 lesson。 - `.codestable/requirements/` 仅在 `.codestable/attention.md` 明确记录为 canonical requirement 位置时才可维护；owner 首次指定时先把该项目事实写入 attention。未记录时只读，不存在时不新建 `.codestable/requirements/`；新项目沿用项目自身文档结构，归宿未定的稳定契约先留在永久 Epic。 -- 有匹配的 `.codestable/work/epic-{slug}.md` 时先恢复：读取其永久 Epic 指针、`phase` 和 `approved_revision`，核对 active 永久文档的当前 SHA-256。仓库事实优先于聊天历史；不一致时先修复或请求上下文，不创建重复 Epic。 +- 有匹配的 `.codestable/work/epic-{slug}.md` 时先恢复：读取其永久 Epic 指针、`phase`、`approved_revision`、`item_progression`、`milestone_commit` 与 `remote_publish`，核对 active 永久文档的当前 SHA-256。仓库事实优先于聊天历史；hash、策略字段或仓库事实不一致时先修复或请求上下文，不创建重复 Epic。 +- 同一会话由 `cs` 交入且带已确认 handoff 时，直接消费目标入口、原始诉求、目标或期望行为、范围/非目标、验收、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选；packet 精确范围内已确认的事项不重复询问。handoff 只证明当前会话共识，不扩大实现、commit、发布或写入授权，也不替代本 skill 的 review、验证与确认门槛；字段缺失、仓库事实冲突、出现会改变结果的新风险、缺少会改变方向的事实或超出已确认边界时再按本 skill 规则确认。 +- handoff 只用于起草 proposed 永久 Epic 文档，不替代 fresh design review、批准 hash 或第一道 owner gate。 - 澄清需求：只问会改变拆解方向的问题（目标边界、优先级、验收口径），一次最多 3 个，形成共识即停。 ## 双层 Epic 文档 @@ -21,7 +23,7 @@ argument-hint: "[大需求描述]" Epic 天然跨会话，但稳定上下文和活动状态不得混写： - **永久 Epic 文档**：项目已有明确 Epic、RFC 或 initiative 归宿时沿用；否则首次创建时按需建立 `.codestable/epics/{slug}.md`，`cs-onboard` 不预建该目录。它是起点、目标、范围、非目标、验收标准、带稳定 ID/依赖/验收要点的子项契约、关键决策、最终交付索引、整体验收、遗留风险与长期 `status` 的唯一 owner。 -- **执行游标**：`.codestable/work/epic-{slug}.md` 只保存永久文档指针、`approved_revision`、执行 `phase`、当前子项 ID、各 ID 进度、下一步、`blocked_by`、临时决策及证据/commit 指针；不得复制目标、验收、子项定义或最终结论。 +- **执行游标**：`.codestable/work/epic-{slug}.md` 只保存永久文档指针、`approved_revision`、执行 `phase`、当前子项 ID、各 ID 进度、下一步、`blocked_by`、`item_progression`、`milestone_commit`、`remote_publish`、临时决策及证据/commit 指针；不得复制目标、验收、子项定义或最终结论。 永久文档最小结构： @@ -51,13 +53,18 @@ approved_revision: pending current_item: ITEM-1 next_action: review and confirm the proposed Epic blocked_by: null +item_progression: pending +milestone_commit: pending +remote_publish: pending --- ## 子项进度 - [ ] ITEM-1 ## 临时决策与证据 ``` -永久 `status` 只允许 `proposed -> active -> accepted`，owner 放弃或用后继 Epic 取代时转 `cancelled` / `superseded`；work `phase` 只允许 `planning -> executing -> acceptance`，阻塞只写 `blocked_by`。owner 确认 proposed 文档后，主流程机械置 `active`，用 `shasum -a 256 ` 计算完整文件 SHA-256，只写入 work 的 `approved_revision` 并进入 executing；确认前保持 `pending`。active 期间永久文档冻结，日常进度与临时决策只写 work；目标、范围、非目标、验收、子项定义或重大风险变化时，按相同规则更新永久文档、重新 review/确认并替换 hash。 +永久 `status` 只允许 `proposed -> active -> accepted`，owner 放弃或用后继 Epic 取代时转 `cancelled` / `superseded`；work `phase` 只允许 `planning -> executing -> acceptance`，阻塞只写 `blocked_by`。拆解确认本身不等于版本控制授权；首次 owner gate 同时一次性确定 `item_progression: continuous | per-item`、`milestone_commit: authorized | manual` 与 `remote_publish: each-milestone | final | manual`，说明选择 `manual` commit 会逐项暂停，并写入 work 游标。`milestone_commit: manual` 只能搭配 `item_progression: per-item`；`milestone_commit: manual` 只能搭配 `remote_publish: manual`；`remote_publish: each-milestone` 只能搭配 `milestone_commit: authorized`。`authorized + per-item` 是合法的显式逐项暂停策略。进入 executing 前不得保留 `pending` 或非法组合。 + +owner 确认 proposed 文档与上述策略后，主流程机械置 `active`，用 `shasum -a 256 ` 计算完整文件 SHA-256，只写入 work 的 `approved_revision` 并进入 executing；确认前保持 `pending`。active 期间永久文档冻结，日常进度与临时决策只写 work；目标、范围、非目标、验收、子项定义或重大风险变化时，按相同规则更新永久文档、重新 review/确认并替换 hash。版本控制策略变化只按 owner 的显式表达更新游标字段，不修改永久文档或批准 hash，也不得从历史操作推断授权。Epic 内的已有 commit 授权只指 `milestone_commit: authorized`；其他值或仅有会话历史均不算。旧游标缺字段或组合非法时暂停一次补记/修正。 子项设计就近优先：简要设计属于永久文档的子项契约；高风险细节可独立落 `work/feat-{slug}.md`，frontmatter 标 `epic: {epic-slug}`，work 游标只记录路径和进度。子项增删、依赖或验收变化属于契约变化；不改变依赖/验收的顺序微调只更新游标。 @@ -69,7 +76,11 @@ blocked_by: null - 审查前冻结一个明确目标（diff review 优先 staged diff，也可用明确 range/patch；design review 冻结对应文档版本；audit 冻结 commit + 范围标识），把目标标识写入 task packet；reviewer 返回前不改目标或对应工作树。有 blocking 或未被用户明确接受的 important 时不提交当前候选，也不得创建正式里程碑 commit；处理后重跑验证、重新冻结审查目标并创建 fresh reviewer。 - 仅在跨会话恢复、agent 交接或隔离 reviewer 需要不可变基线时，且已有 commit 授权，才可在私有工作分支创建明确标记的 WIP/checkpoint commit；它不代表 review 通过或任务完成，交付前按仓库策略 fixup/squash。 - 本 skill 的确认与验证门槛均满足、blocking 清零且其余 important 已处理或被用户明确接受后，已有 commit 授权时才创建语义原子的正式里程碑 commit；未获授权则只报告可提交状态，不自行提交。 -- 每次只推进一个已确认子项。子项通过其 owning skill 的验证与审查后，已获 commit 授权时把代码、证据和 work 游标更新收成一个语义原子里程碑，再进入下一子项；未获 commit 授权时先向用户交付可提交 checkpoint，不把多个子项堆进同一 diff。 +- 同一时间只允许一个 `current_item`；这是串行约束，不是每个子项的人工 gate。`active` 且批准 hash 有效表示可执行已批准子项，恢复后沿用游标策略，不重新询问是否继续。 +- 子项通过其 owning skill 的验证与审查后，按 `milestone_commit` 把代码、证据和 work 游标更新收成一个语义原子里程碑，不把多个子项堆进同一 diff。`item_progression: continuous` 时，非最终子项完成后自动选择永久文档顺序中第一个依赖已满足的未完成子项，更新 `current_item` / `next_action`，并在同一受托主流程中继续执行；仍有未完成子项但无可运行候选时按阻塞暂停。不得询问“是否继续下一项”，不得把普通子项完成当作终态返回。 +- `item_progression: per-item` 时，完成当前里程碑后按已记录的逐项 checkpoint 策略暂停；它是 owner 在首次 gate 或后续显式变更中选择的行为，不得伪装成默认连续模式。`milestone_commit: manual` 时只交付可提交 checkpoint，不自行 commit。 +- `remote_publish: each-milestone` 时，每个语义原子 commit 后按项目、宿主或 owner 已确定的 branch/remote 策略发布；`final` 时，在集成验证与 final acceptance review 通过后、请求 owner 最终接受前发布一次；`manual` 时 agent 不执行远端发布。branch/remote 未明确时暂停请求上下文，不自行选择；发布失败时写入 `blocked_by` 并暂停，不静默继续。 +- Epic 编排只在以下情况新增暂停：契约或重大风险变化、无法自行解除的阻塞/产品决策、新增权限、需要 owner 明确接受的 important findings、review 超限仍有分歧、旧游标策略缺失或非法、用户明确要求暂停，以及全部子项完成后的最终 owner gate。子项 owning skill 自身的确认门槛照常生效；已批准子项契约覆盖同一决策时不得重复确认，新出现且会改变结果的风险仍按 owning skill 或 Epic 重确认处理。 - reviewer 创建后绑定该运行并记录 run identity：目标有效、能力仍满足，且 reviewer 状态为 running，或 `Awaiting` 携带可查询的同一 run identity 且查询仍为活动态时为健康；状态健康时等待终态报告，不因后来发现更优创建方式而取消、重复创建或并行补发。仅在运行明确失败或终止无报告、idle / `Awaiting` 且无可恢复 run identity、能力不满足或目标失效时，本轮失败且不计轮次；不得盲目重发，先检查 task packet 与 agent 状态，再决定一次有界重试、更换创建方式或交用户。 - 每个子项按其类型的纪律执行（cs-feat / cs-issue / cs-refactor 的门槛照常生效），完成即更新 work 游标的 ID 进度、证据和 commit 指针；文档与事实不一致时以仓库事实为准并修正文档。 - 全部子项完成后把 phase 置为 acceptance，运行集成验证，并由当前主流程创建 fresh reviewer，对最新 owner 已批准的验收标准做 `cs-review` audit/acceptance review。主流程处理 findings，门槛通过后给出各子项结果、验证证据与遗留项，**不代替用户做整体验收**，停下等 owner 最终接受。 diff --git a/plugins/codestable/skills/cs-feat/SKILL.md b/plugins/codestable/skills/cs-feat/SKILL.md index 82d7d73..fbd6d43 100644 --- a/plugins/codestable/skills/cs-feat/SKILL.md +++ b/plugins/codestable/skills/cs-feat/SKILL.md @@ -13,6 +13,7 @@ argument-hint: "[功能描述]" - 有 `.codestable/attention.md` 就先读。 - 按功能关键词检索 `.codestable/lessons/`、项目文档，以及存在的 v1 只读知识目录：`.codestable/roadmap/`、`.codestable/features/`、`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、`.codestable/audits/`、`.codestable/brainstorms/`、`.codestable/feedback/`；命中要报告来源路径。上述 v1 目录不得继续生成、原地改写或批量迁移，新结论按归属进入 v2 Epic、项目文档、ADR 或 lesson。 - 既有 `.codestable/requirements/` 只有在 `.codestable/attention.md` 明确记录其为 canonical requirement 位置时才可维护；owner 在当前任务首次指定时，先把该项目事实写入 attention。没有显式记录时只读检索，不存在时不新建 `.codestable/requirements/`。 +- 同一会话由 `cs` 交入且带已确认 handoff 时，直接消费目标入口、原始诉求、目标或期望行为、范围/非目标、验收、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选；packet 精确范围内已确认的事项不重复询问。handoff 只证明当前会话共识，不扩大实现、commit、发布或写入授权，也不替代本 skill 的 review、验证与确认门槛；字段缺失、仓库事实冲突、出现会改变结果的新风险、缺少会改变方向的事实或超出已确认边界时再按本 skill 规则确认。 - 写代码前先看相邻实现，写得像这个项目原本的代码。 - 动手前先定归属：这能力属于哪里、沿用现有词汇叫什么——不丢进最近的文件、不起新同义词。结构与取舍拿不准时读 `references/code-design.md` 与 `references/economy.md`（最小充分 ≠ 最小 diff；有界简化必须记上限、触发与方向）。 - 对照检查：目标、现场上下文、边界与取舍、证据要求、验收标准。缺少会改变实现方向的事实时先问，一次最多 3 个问题，形成可执行共识即停；不问不影响方向的细节。 diff --git a/plugins/codestable/skills/cs-issue/SKILL.md b/plugins/codestable/skills/cs-issue/SKILL.md index 306ef80..c779982 100644 --- a/plugins/codestable/skills/cs-issue/SKILL.md +++ b/plugins/codestable/skills/cs-issue/SKILL.md @@ -12,6 +12,7 @@ argument-hint: "[问题描述]" - 有 `.codestable/attention.md` 就先读。 - 按错误信息与相关模块关键词检索 `.codestable/lessons/`、项目文档，以及存在的 v1 只读知识目录：`.codestable/roadmap/`、`.codestable/features/`、`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、`.codestable/audits/`、`.codestable/brainstorms/`、`.codestable/feedback/`；这个坑可能踩过，命中要报告来源路径。上述 v1 目录不得继续生成、原地改写或批量迁移，新结论按归属进入 v2 Epic、项目文档、ADR 或 lesson。 +- 同一会话由 `cs` 交入且带已确认 handoff 时，直接消费目标入口、原始诉求、目标或期望行为、范围/非目标、验收、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选；packet 精确范围内已确认的事项不重复询问。handoff 只证明当前会话共识，不扩大实现、commit、发布或写入授权，也不替代本 skill 的 review、验证与确认门槛；字段缺失、仓库事实冲突、出现会改变结果的新风险、缺少会改变方向的事实或超出已确认边界时再按本 skill 规则确认。 - 对照检查：目标（期望行为）、现场（复现条件与环境）、边界（哪些不能动）、验收（怎么算修好）。缺少会改变修复方向的事实时先问用户，一次最多 3 个问题，形成共识即停。 - 诉求其实是新增能力而不是坏掉的行为时，转 `cs-feat`，不在 issue 里偷做。 diff --git a/plugins/codestable/skills/cs/SKILL.md b/plugins/codestable/skills/cs/SKILL.md index d71a852..45660a6 100644 --- a/plugins/codestable/skills/cs/SKILL.md +++ b/plugins/codestable/skills/cs/SKILL.md @@ -1,21 +1,32 @@ --- name: cs -description: CodeStable 入口。触发：用户调用 cs、想了解体系、问该用哪个 skill，或带着诉求未选入口。明确行动诉求同轮直转对应 skill。 +description: CodeStable 入口。触发：用户调用 cs、想先讨论或对齐、想了解体系、问该用哪个 skill，或带着诉求未选入口。明确行动同轮直转；先讨论的请求收敛后同轮移交。 argument-hint: "[诉求]" --- # cs -判断用户此刻要什么：要么直接开始干，要么给推荐，要么介绍体系。**明确的行动诉求不停下等确认。** +判断用户此刻要执行、先讨论、咨询还是了解体系。**明确行动默认直接执行，不先加讨论 gate。** ## 判别与行为 | 用户输入 | 行为 | |---|---| | 明确行动诉求（修这个 bug、实现 X、重构 Y、审一下、记住这个…） | **同轮直转**：报一句"按 `cs-xxx` 处理：{一句理由}"，随即在当前回合按该 skill 的纪律继续执行，不要求用户重新调用或再次确认 | +| 用户显式要求先讨论，或调查仓库事实后仍无法安全判断行动类型 / owning skill，且产品决策会实质改变建档或改代码路径 | 在当前会话对齐；用户没有要求先讨论且 owning skill 已可判定时，直接转入，不在入口层细化目标或验收 | | 咨询（该用哪个 / 流程怎么走 / 你建议怎么做） | 只推荐入口并说明理由，不启动执行 | | 只说 cs、想了解体系、无具体诉求 | 输出体系速读 | -| 诉求含糊到无法判断行动类型，且选错会实质改变后续（会不会建档、会不会改代码） | 只问一个聚焦问题，不默认重流程 | +| 诉求含糊但一个分类问题即可判断 | 先调查可核实事实，只问一个聚焦问题，不默认重流程 | + +## 会话内讨论与 handoff + +- Execute 默认优先级最高；明确行动仍同轮直转。用户显式要求先讨论时才覆盖该默认；owning skill 已可判定时，目标与验收细化留给该 skill。 +- 讨论只存在于当前会话。仓库可核实的事实由 agent 自行调查；一次只问一个真正需要 owner 决定的问题，给出建议与理由，并用精确术语、具体场景和边界案例检验理解。 +- handoff-ready 时形成内存 packet：目标入口、原始诉求、目标或期望行为、范围、非目标、验收口径、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选。 +- 已有执行授权时同轮移交给三个已确认出口 `cs-feat` / `cs-issue` / `cs-epic`，不再询问“是否继续”；只授权讨论时返回已确认结论，并推荐由 `cs-keep` 或对应 owning skill 完成资产毕业。 +- 讨论过程本身不产生授权；handoff 不扩大实现、commit、发布或写入授权，也不替代目标 skill 的硬门槛。收敛到其他入口时按既有 Execute / Advise 规则处理，不附带 handoff 的不重复确认契约。 +- 不创建 `.codestable/work/discussion-*`、transcript 或新状态；未收敛讨论不跨会话恢复，原始问答、未决讨论和候选分支不落盘。 +- 稳定术语交给项目已有 canonical 术语归宿；难逆转、缺少上下文会令人意外且源于真实取舍的决定才进入 ADR；任务契约、永久 Epic 文档、`attention.md` 与 `lessons/` 由 owning skill 按各自规则毕业。 ## 入口表 diff --git a/tests/test_skill_contracts.py b/tests/test_skill_contracts.py index 4e18507..8e7cae9 100644 --- a/tests/test_skill_contracts.py +++ b/tests/test_skill_contracts.py @@ -26,7 +26,13 @@ LEGACY_KNOWLEDGE_DIRS = { } THIN_SKILL_SAFETY_INVARIANTS = { - "cs": ("同轮直转", "只推荐入口", "不写任何文件"), + "cs": ( + "同轮直转", + "只推荐入口", + "导览与推荐本身不写任何文件", + "讨论只存在于当前会话", + "不创建 `.codestable/work/discussion-*`", + ), "cs-review": ( "只读", "叶子执行器", @@ -131,6 +137,65 @@ def test_thin_skills_keep_explicit_safety_invariants() -> None: assert "派发独立 subagent reviewer" not in review_prompt +def test_cs_discusses_in_session_then_hands_off_same_turn() -> None: + _, cs = _read_skill(SKILLS / "cs/SKILL.md") + for anchor in ( + "用户显式要求先讨论", + "默认优先级最高", + "产品决策会实质改变建档或改代码路径", + "讨论只存在于当前会话", + "仓库可核实的事实由 agent 自行调查", + "一次只问一个真正需要 owner 决定的问题", + "目标入口、原始诉求、目标或期望行为、范围、非目标、验收口径", + "已核实仓库事实及来源", + "owner 已确认的术语与决策", + "已有执行授权时同轮移交", + "不再询问“是否继续”", + "讨论过程本身不产生授权", + "不创建 `.codestable/work/discussion-*`", + "未收敛讨论不跨会话恢复", + "三个已确认出口", + "不附带 handoff 的不重复确认契约", + "原始问答、未决讨论和候选分支不落盘", + "canonical 术语归宿", + "难逆转、缺少上下文会令人意外且源于真实取舍", + "永久 Epic 文档", + "`attention.md`", + "`lessons/`", + ): + assert anchor in cs + + work = ROOT / ".codestable/work" + assert not any(path.name.startswith("discussion-") for path in work.glob("*.md")) + assert not (SKILLS / "cs-align").exists() + + +def test_confirmed_cs_handoff_avoids_duplicate_intake_without_expanding_authority() -> None: + handoff_owners = ("cs-feat", "cs-issue", "cs-epic") + for skill_name in handoff_owners: + _, owner = _read_skill(SKILLS / skill_name / "SKILL.md") + for anchor in ( + "同一会话由 `cs` 交入且带已确认 handoff", + "packet 精确范围内已确认的事项不重复询问", + "owner 已确认的术语与决策", + "canonical 资产指针或资产候选", + "仓库事实冲突", + "会改变结果的新风险", + "缺少会改变方向的事实", + "超出已确认边界", + "不扩大实现、commit、发布或写入授权", + "不替代本 skill 的 review、验证与确认门槛", + ): + assert anchor in owner, skill_name + + _, epic = _read_skill(SKILLS / "cs-epic/SKILL.md") + assert "handoff 只用于起草 proposed 永久 Epic 文档" in epic + assert "不替代 fresh design review、批准 hash 或第一道 owner gate" in epic + + _, refactor = _read_skill(SKILLS / "cs-refactor/SKILL.md") + assert "同一会话由 `cs` 交入且带已确认 handoff" not in refactor + + def test_task_skills_retrieve_legacy_knowledge_read_only() -> None: for skill_name in TASK_SKILLS: _, body = _read_skill(SKILLS / skill_name / "SKILL.md") @@ -267,9 +332,41 @@ def test_review_snapshots_and_milestone_commits_are_not_conflated() -> None: assert "不代表 review 通过" in caller, skill_name _, epic = _read_skill(SKILLS / "cs-epic/SKILL.md") - assert "每次只推进一个已确认子项" in epic + assert "同一时间只允许一个 `current_item`" in epic assert "不把多个子项堆进同一 diff" in epic - assert "未获 commit 授权" in epic + assert "milestone_commit" in epic + + +def test_epic_continues_without_a_per_item_owner_gate() -> None: + _, epic = _read_skill(SKILLS / "cs-epic/SKILL.md") + for anchor in ( + "串行约束，不是每个子项的人工 gate", + "永久文档顺序中第一个依赖已满足的未完成子项", + "在同一受托主流程中继续执行", + "不得询问“是否继续下一项”", + "不得把普通子项完成当作终态返回", + "拆解确认本身不等于版本控制授权", + "按已记录的逐项 checkpoint 策略暂停", + "需要 owner 明确接受的 important findings", + "子项 owning skill 自身的确认门槛", + "进入 executing 前不得保留 `pending` 或非法组合", + "恢复后沿用游标策略，不重新询问是否继续", + "旧游标缺字段或组合非法时暂停一次补记/修正", + "每个语义原子 commit 后按项目、宿主或 owner 已确定的 branch/remote 策略发布", + "在集成验证与 final acceptance review 通过后、请求 owner 最终接受前发布一次", + "agent 不执行远端发布", + "发布失败时写入 `blocked_by` 并暂停", + "Epic 内的已有 commit 授权只指 `milestone_commit: authorized`", + ): + assert anchor in epic + + for field in ("item_progression", "milestone_commit", "remote_publish"): + assert field in epic + assert "`milestone_commit: manual` 只能搭配 `item_progression: per-item`" in epic + assert "`milestone_commit: manual` 只能搭配 `remote_publish: manual`" in epic + assert "`remote_publish: each-milestone` 只能搭配 `milestone_commit: authorized`" in epic + assert "`authorized + per-item` 是合法的显式逐项暂停策略" in epic + assert "每次只推进一个已确认子项" not in epic def test_epic_separates_durable_record_from_execution_cursor() -> None: @@ -307,6 +404,9 @@ def test_epic_separates_durable_record_from_execution_cursor() -> None: "当前子项", "下一步", "blocked_by", + "item_progression", + "milestone_commit", + "remote_publish", "临时决策", "证据", "commit 指针", diff --git a/tests/test_v2_architecture_contract.py b/tests/test_v2_architecture_contract.py index 33e302b..d1934f4 100644 --- a/tests/test_v2_architecture_contract.py +++ b/tests/test_v2_architecture_contract.py @@ -32,6 +32,7 @@ def test_v2_runtime_ownership_supersedes_v1_distribution() -> None: assert _frontmatter(adr5)["status"] == "Accepted" adr4_text = adr4.read_text(encoding="utf-8") adr5_text = adr5.read_text(encoding="utf-8") + adr5_flat = " ".join(adr5_text.split()) assert "supersedes: [\"001\"]" in adr4_text assert "supersedes: [\"004\"]" in adr5_text assert "八个主 skill" in adr5_text @@ -41,6 +42,9 @@ def test_v2_runtime_ownership_supersedes_v1_distribution() -> None: assert "不得继续生成、原地改写、批量迁移" in adr5_text assert "`.codestable/attention.md` 明确记录其为 canonical" in adr5_text assert "不默认创建 `.codestable/requirements/`" in adr5_text + assert "串行约束，不是每个子项的人工 gate" in adr5_flat + for field in ("item_progression", "milestone_commit", "remote_publish"): + assert field in adr5_text assert "不恢复 `cs-goal` 入口" in adr5_text assert "`state.yaml`" in adr5_text assert "逐轮 iteration 报告" in adr5_text @@ -55,6 +59,7 @@ def test_v2_runtime_ownership_supersedes_v1_distribution() -> None: assert anchor in entry_file assert "只读" in entry_file assert "legacy" in entry_file + assert "普通子项完成不是 owner gate" in entry_file def test_active_adrs_do_not_enforce_deleted_v1_tests_or_assets() -> None: diff --git a/tests/test_v2_documentation_contract.py b/tests/test_v2_documentation_contract.py index f9510b7..09c847a 100644 --- a/tests/test_v2_documentation_contract.py +++ b/tests/test_v2_documentation_contract.py @@ -186,6 +186,51 @@ def test_review_docs_publish_single_level_agent_orchestration() -> None: assert "independent subagent perspective" not in public +def test_cs_session_discussion_and_handoff_contract_is_bilingual() -> None: + zh_workflow = " ".join(_read("WORKFLOW.md").split()) + en_workflow = " ".join(_read("WORKFLOW.en.md").split()) + + for anchor in ( + "明确行动默认优先同轮直转", + "用户显式要求先讨论", + "讨论只存在于当前会话", + "不创建 discussion work 游标", + "未收敛讨论不跨会话恢复", + "已有执行授权时同轮移交", + "不再询问“是否继续”", + "handoff 不扩大授权", + "原始问答、未决讨论和候选分支不落盘", + "三个已确认出口之外", + ): + assert anchor in zh_workflow + + for anchor in ( + "Explicit action dispatches in the same turn by default", + "the user explicitly asks to discuss first", + "Discussion exists only in the current session", + "does not create a discussion work cursor", + "Unresolved discussion is not recoverable across sessions", + "existing execution authorization", + "must not ask whether to continue", + "The handoff does not expand authorization", + "Raw questions, answers, unresolved discussion, and candidate branches are not persisted", + "When no canonical home exists, ask the owner to choose one", + "Outside the three confirmed handoff targets", + ): + assert anchor in en_workflow + + zh_readme = _read("README.md") + en_readme = _read("README.en.md") + zh_catalog = _read("SKILL_CATALOG.md") + en_catalog = _read("SKILL_CATALOG.en.md") + assert "先讨论的请求在当前会话收敛后同轮移交" in zh_readme + assert "先讨论的请求在当前会话收敛后同轮移交" in zh_catalog + assert "Requests to discuss first converge in the current session and hand off in the same turn" in en_readme + assert "Requests to discuss first converge in the current session and hand off in the same turn" in en_catalog + assert "稳定资产由 owning skill 按 canonical 归宿毕业" in zh_catalog + assert "stable assets graduate through the owning skill into their canonical homes" in en_catalog + + def test_epic_and_legacy_knowledge_contracts_are_bilingual() -> None: zh_workflow = " ".join(_read("WORKFLOW.md").split()) en_workflow = " ".join(_read("WORKFLOW.en.md").split()) @@ -220,6 +265,10 @@ def test_epic_and_legacy_knowledge_contracts_are_bilingual() -> None: "Epic 保留三道 owner gate", "最新 owner 已批准的验收标准", "owner 最终接受", + "串行约束，不是每个子项的人工 gate", + "不得询问“是否继续下一项”", + "不得把它作为终态返回", + "`item_progression`", "不恢复 `cs-goal` 入口", ): assert anchor in zh_workflow @@ -238,6 +287,10 @@ def test_epic_and_legacy_knowledge_contracts_are_bilingual() -> None: "An Epic retains three owner gates", "latest owner-approved criteria", "owner's final acceptance", + "serialization constraint, not a per-item owner gate", + "must not ask whether to continue to the next item", + "return that completion as terminal", + "`item_progression`", "Do not restore the `cs-goal` entry", ): assert anchor in en_workflow @@ -255,8 +308,14 @@ def test_epic_and_legacy_knowledge_contracts_are_bilingual() -> None: assert "nine v1 historical knowledge directories" in en_readme assert "每个 skill 动手前按任务关键词检索" not in zh_readme assert "every skill searches" not in en_readme + assert "默认连续策略" not in zh_workflow + assert "默认连续策略" not in zh_readme for task_skill in ("cs-feat", "cs-issue", "cs-refactor", "cs-epic"): assert task_skill in zh_readme assert task_skill in en_readme assert "永久 Epic 文档" in zh_catalog assert "permanent Epic doc" in en_catalog + for document in (zh_readme, zh_catalog): + assert "串行连续推进" in document + for document in (en_readme, en_catalog): + assert "serially and continuously" in document