codestable__codestable/WORKFLOW.md

# CodeStable v2 工作流与项目结构

## 工作流

CodeStable v2 是 8 个独立安装的 thin-harness skill，加一个项目记忆闭环。`cs` 判别用户
此刻要执行、先讨论、咨询还是了解体系：明确行动默认优先同轮直转；先讨论的请求在当前会话
收敛并按授权移交；咨询只给推荐；无诉求时介绍体系。

```text
不确定入口       -> cs
先讨论 / 对齐     -> cs -> cs-feat / cs-issue / cs-epic
仓库接入 / v1 升级 -> cs-onboard
只诊断 / 排查     -> cs-issue（无产品 diff，不进入 change review）
新功能           -> cs-feat -> cs-review（默认；仅文案级微小改动可说明后跳过）
获授权修复 bug / 性能回退 / 行为异常 -> cs-issue -> cs-review（默认；仅单行级微小修复可说明后跳过）
行为等价重构      -> cs-refactor -> cs-review（跨模块大范围、公开 interface 或性能敏感路径；微小整理可说明后跳过）
大需求拆解        -> cs-epic -> cs-feat / cs-issue / cs-refactor
经验与项目记忆    -> 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` 默认直接理解、实现、验证；公开契约、数据、权限、并发或真实方案取舍先经用户确认。
- `cs-issue` 先针对用户实际症状建立可重复的失败信号。只要求诊断时保持零产品改动，结论明确归为
  已证实根因、可证伪假设或证据不足；获授权修复后，沿用同一信号证明红到绿。
- `cs-refactor` 先建立等价性证据，分步改动并持续保持验证为绿。
- 性能回退或异常变慢进入 `cs-issue`；没有既有异常、仅要求行为等价的主动优化仍进入 `cs-refactor`。
- `cs-epic` 用永久 Epic 文档维护批准后的交付契约，用临时 work 游标恢复活动执行；拆解、契约变化和整体验收分别经过 owner gate。
- 需要独立审查时由外层主流程创建 reviewer；reviewer 每轮执行一次 `cs-review`，返回结果前不再创建子 agent。每个独立审查阶段的首轮使用 fresh reviewer；reviewer 独立性要求它独立于实现者，不要求对自身上一轮审查失忆。
- 一个独立审查阶段由单一审查目的界定；design review、change review、contract review 与 Epic final acceptance 是不同阶段。只有为本阶段 findings 所作修复的复审，才属于同一阶段并沿用原 reviewer lineage；审查目的变化时开启新阶段。
- 当前主流程创建 reviewer 前，先发现当前会话可调用的 subagent 创建与管理能力。项目上下文有显式创建方式/model 约束时先遵守。达到审查质量基线后，优先选择与实现者异构的 agent，并显式指定最强稳定 model；创建方式依次使用受管理的结构化委派能力、宿主 subagent、本机有界 agent CLI 回退，不得只扫 PATH。没有合格异构候选时回退同构最强模型。把最终创建方式、agent/model 与回退原因写入 task packet，禁止依赖默认模型。具体后端与 model 约束属于项目上下文，不进入 shipped skill。
- 外层主流程派发前冻结一个明确的审查目标（diff review 优先 staged diff，也可用明确 range/patch；design review 冻结对应文档版本；audit 冻结 commit + 范围标识），reviewer 返回前不移动目标或对应工作树；目标变化则本轮失效。
- `cs-review` 是只读叶子执行器，也承接模块或全仓 audit；修复与复审由外层主流程负责。
- 有 blocking 或未被用户明确接受的 important 时不提交当前候选，也不创建正式里程碑。主流程处理 findings 后修复、重新验证并冻结新的完整目标；仅因 findings 修复产生的复审沿用同一 reviewer 的同一 session，以 follow-up 继续。复审检查完整当前候选与本轮修复增量，逐项报告 `resolved` / `unresolved` / `new findings`，不得只核对旧 finding 或机械打勾。
- 同一审查阶段累计最多 3 个有终态报告的轮次，更换 reviewer 不重置计数。只有原 run/session 失败或不可恢复、能力不满足、目标、范围、设计或核心路径发生重大变化、reviewer 声明无法继续独立判断，或 owner 要求第二意见时才更换 reviewer；更换时重新创建 fresh reviewer。只有审查门槛通过且已有 commit 授权时才形成语义原子里程碑；WIP/checkpoint 只作恢复或隔离基线，不代表通过。
- Epic 同一时间只允许一个 `current_item`；这是串行约束，不是每个子项的人工 gate。连续策略下，普通子项达到语义原子里程碑后自动进入下一项，不得询问“是否继续下一项”或终态返回；逐项暂停必须是 owner 明示策略或真实门槛。
- 健康运行中的 reviewer 与原 run/target 绑定；running，或 Awaiting 携带同一可查询 run identity 且仍为活动态时继续等待，不因后来发现更优创建方式而取消、重复创建或并行补发。只有终止无报告、run identity 不可恢复、能力不满足或目标失效时，本轮才失败且不计审查轮次；外层主流程先诊断再决定有界重试、更换创建方式或上交，不盲目重发。
- `cs-keep` 把高频事实压进 attention，把尚未被更强 owner 承接的经验暂存为 lesson，并推动它们
  毕业到机械 guard、项目文档或 ADR。

普通任务不生成阶段文档。diff、测试输出和交付说明就是证据；只有跨会话、多人交接或用户
要求留痕时，才维护一个 work 文档，完成后删除或按用户要求保留。

## 项目内持续学习

- 四个 task skill 在任务内静默观察。lesson 只做一次有界、最低成本的定向核实，不为此运行大范围
  测试或反复复现；仍不足时跳过，不阻塞正常任务。只有当前事实成立，且真实改变计划或验证，或
  明确排除一个具体且合理的错误路径时，才报告为
  `经验命中：{path}（{status}）；核验：{fact}；影响：{plan_or_check}`；纯关键词碰撞不算复用。
- 晶化候选只存在于当前会话内。普通任务最多展示一条最高价值候选，无强信号就不显示；
  Epic 子项不新增暂停，每项最多把一条去重候选写入既有游标证据区，最终毕业清单统一处理。
- lesson 生命周期为 observed / validated / retired。新条目从 observed 开始，只有独立后续任务中
  的有效命中和成功验证才能进入 validated，并须记录实际行为变化与本次通过的验收证据；事实反证、
  scope 失效或已有更强 owner 时进入 retired。
- read-repair 只允许已有命中条目的窄状态维护；稳定 validated 命中不写文件。
  新 lesson 仍需显式授权，规则/scope 改写、晋升、删除和跨项目分享也不能从任务执行授权中推断。
- 机械 guard 优先：能在当前任务范围内落成测试、checker、lint、类型或 helper 的错误，不再写重复
  lesson。经验最终进入一个 canonical owner；不保存 transcript、逐次命中日志或后台 telemetry。

## Epic 生命周期

Epic 把长期产品意图与短期执行状态分成两层，并且只保留一个事实 owner：

- **永久 Epic 文档**优先沿用项目既有 Epic、RFC 或 initiative 归宿；没有明确归宿时，首次
  创建才按需建立 `.codestable/epics/{slug}.md`，`cs-onboard` 不预建 `.codestable/epics/`。
  它唯一拥有起点、目标、范围、非目标、验收标准、带稳定 ID/依赖/验收要点的已批准子项、
  关键决策、最终交付索引、整体验收、遗留风险和长期 `status`。
- **临时执行游标** `.codestable/work/epic-{slug}.md` 只保存永久文档指针、
  `approved_revision`、执行 `phase`、当前子项 ID、各 ID 进度、下一步、`blocked_by`、临时
  决策、`item_progression`、`milestone_commit`、`remote_publish` 以及证据/commit 指针；不得复制
  目标、验收、子项定义或最终结论。owner 确认后以永久文档完整 SHA-256 固定批准 revision；
  active 期间永久文档冻结，日常进度与执行策略只更新游标。

Epic 保留三道 owner gate：

1. proposed 拆解先由当前主流程创建 fresh reviewer 做 design review；处理 findings 后按同一 lineage 复审，owner
   确认目标、边界、验收和子项契约，才进入执行。
2. 永久文档已批准后的执行中，目标、范围、非目标、验收、子项增删/定义或重大风险变化时，更新
   永久文档；契约变化形成新的 contract review 审查阶段，由 fresh reviewer 审查并由 owner 确认。
   边界内技术选择和不改变
   依赖/验收的顺序微调不增加 gate。
3. 全部子项完成并通过集成验证后，游标进入 acceptance；final acceptance 是独立审查阶段，
   当前主流程另建 fresh reviewer 开始新的 lineage，不沿用子项、design review 或 contract review 的 lineage，对最新
   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、
`state.yaml`、逐轮 iteration 报告或 legacy runtime gate。

## 项目记忆

`/cs-onboard` 为新项目创建最小骨架：

```text
.codestable/
├── attention.md    # 每次会话需要的少量项目事实，最多 25 条
├── lessons/        # 一条经验一个 Markdown 文件，按关键词检索
└── work/           # 活动中的跨会话任务，文件名带类型前缀 feat-/issue-/refactor-/epic-，完成即清
```

skill 专属 context 与 helper 分别由 owning skill 的 `references/` 和 `scripts/` 提供。项目
事实放在上述目录、按需创建的永久 Epic 归宿或项目既有文档与 ADR 中。skill 不读取 sibling
skill 文件，也不依赖集中式 onboard runtime；worktree、branch 和 agent backend 策略由宿主
或 owner 决定。

## v1 升级边界

v2 不迁移或清理 v1 项目的历史目录。`.codestable/roadmap/`、`.codestable/features/`、
`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、
`.codestable/audits/`、`.codestable/brainstorms/` 与 `.codestable/feedback/` 是只读历史知识源：
四个 owning task skills（`cs-feat`、`cs-issue`、`cs-refactor`、`cs-epic`）按任务关键词覆盖
全部九目录并引用命中路径；其他 skill 只检索自身契约明确点名的历史源，例如 `cs-keep` 只读
查重 `compound/`。所有 v1 历史源均不得继续生成、原地改写或批量迁移。

既有 `.codestable/requirements/` 只有在 `.codestable/attention.md` 明确记录其为 canonical
requirement 位置时才可维护；owner 首次指定时先把该项目事实写入 attention。没有显式记录就
按只读历史知识处理，也不默认创建该目录。新项目沿用自身文档结构；没有 canonical 归宿时先请
owner 选择并记录到 attention，稳定契约在确定前保留于永久 Epic。`reference/`、`tools/`、
`gates/`、`hooks/` 与 `runtime-manifest.json` 只作 legacy compatibility，v2 不执行旧 runtime。

v1.0.4 的 32 个 skill 在 v2 收敛为 8 个；其余 24 个入口已退役且不随 v2 安装。完整映射见
[SKILL_CATALOG.md](./SKILL_CATALOG.md)。