cs-epic

cs-epic

启动必读

动作前先跑 CodeStable preflight：读 .codestable/attention.md（缺失先 cs-onboard）；不要用 AGENTS.md/CLAUDE.md 等外部入口代替它；细则见 .codestable/reference/execution-conventions.md。

cs-epic 是大需求端到端入口。用户文档统一叫 epic；为兼容历史产物，第一版内部目录、frontmatter 和工具仍使用 roadmap。用户确认 roadmap 和所有子 feature design 后，默认生成 goal 包并尝试通过可见 Task agent goal driver 长程执行；派发失败则打印 /goal 指令让用户粘贴执行。

旧技能 cs-roadmap、cs-roadmap-review、cs-roadmap-impl-goal 长期保留为兼容入口，只传入 requested_stage。

入口意图

本次调用参数：$ARGUMENTS

意图来源按优先级：调用参数 flag > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 $ARGUMENTS）时跳过该来源；调用参数用 --stage planning|review|goal-package 表示阶段意图，其余文本作为大需求描述。旧裸 token（如 review）只作为历史提示词兼容识别；新文档和新调用一律用 --stage。

无参数默认行为：没有 stage / epic 描述时，扫描 .codestable/roadmap/、子 feature design 和 goal 包状态，用状态机恢复；若没有可恢复 epic 且用户原话也没有大需求目标，先问用户要规划哪个 epic。

入口意图不覆盖仓库事实。已有 roadmap review 未通过时先修规划；已有 feature design 未确认时不生成 goal 包。

Spec

csEpic :: EpicInput -> EpicOutcome
csEpic = workflow
data EpicInput
  = Start EpicRequest | Resume RepoFacts | ResumePlanningInput PlanningResume
  | ConfirmRoadmapInput | ConfirmAllChildDesignInput | ApproveLocalReviewInput
  | AuthorizeGoalExecutionInput ConfirmationId ApprovalRef ApprovalRef | RejectGoalExecutionInput
data EpicRequest = EpicRequest
  { requestedStage : Maybe EntryStage, userGoal : Maybe Text -- planning | review | goal-package
  , repoFacts : RepoFacts }                                  -- 优先于 args / 聊天历史
data EntryStage = PlanningEntry | ReviewEntry | GoalPackageEntry
data Stage = Planning | Review | ChildDesignBatch | GoalPackage
data RoadmapReviewState
  = ReviewMissing | ReviewPassed | ReviewChangesRequested
  | ReviewAwaiting AgentRef | ReviewNeedsOwnerApproval Reason
  | ReviewerFailed Reason | ReviewBlocked Reason
data GoalExecutionAuthorization
  = GroupApproved ConfirmationId ApprovalRef ApprovalRef | StrictLegacy104 ApprovalRef ApprovalRef
data EpicGoalRunState                     -- 从 canonical group + goal-state projection 恢复
  = GoalMissing | GoalReadyToDispatch GoalExecutionAuthorization
  | GoalAuthorizationMissing | GoalAuthorizationNeedsRepair WorkflowEvidence | GoalDriverActive DriverInfo
  | GoalComplete GoalExecutionAuthorization
  | GoalHandoffBlocked Reason | GoalUnknown Text
data EpicState = EpicState                -- 从 .codestable/roadmap/{slug}/ 与子 features/ 恢复
  { roadmapStatus       : Missing | Draft | Confirmed  -- frontmatter status: active 归一为 Confirmed
  , roadmapReviewState  : RoadmapReviewState           -- 从 roadmap-review review_state 恢复
  , childrenDesign      : AllPassed | Pending          -- 未 dropped child 均有 design+checklist+passed review
  , allDesignApproved   : Bool
  , goalRunState        : EpicGoalRunState
  , pendingCheckpoint   : Maybe CheckpointReason
  }
data EpicOutcome
  = RoutedTo Stage | Awaiting WaitReason
  | HumanCheckpoint CheckpointReason
  | RepairGoalExecutionAuthorization WorkflowEvidence | DispatchGoalDriver Command
  | GoalHandoff Command | Completed EpicSummary
  | NeedsHuman Reason | Blocked Reason
data WaitReason = RoadmapReviewerRunning AgentRef | GoalDriverRunning DriverInfo | WorkflowWait Text
data CheckpointReason
  = ConfirmRoadmap | ConfirmAllChildDesign | ConfirmGoalExecutionAuthorization Command | ApproveReviewFallback Reason
data CheckpointResume
  = PersistRoadmapConfirmed | PersistAllDesignsApproved | DelegatePlanningResume PlanningResume
  | PersistGoalExecutionAuthorization ConfirmationId ApprovalRef ApprovalRef | PersistGoalExecutionRejection
  | RerunReview OwnerApproval | RejectResume Reason
resumeCheckpoint :: EpicInput -> CheckpointResume
resumeCheckpoint ConfirmRoadmapInput                = PersistRoadmapConfirmed
resumeCheckpoint ConfirmAllChildDesignInput         = PersistAllDesignsApproved
resumeCheckpoint (ResumePlanningInput resume)         = DelegatePlanningResume resume
resumeCheckpoint (AuthorizeGoalExecutionInput confirmationId acceptanceRef commitRef) = PersistGoalExecutionAuthorization confirmationId acceptanceRef commitRef
resumeCheckpoint RejectGoalExecutionInput            = PersistGoalExecutionRejection
resumeCheckpoint ApproveLocalReviewInput             = RerunReview ApproveLocalOnly
resumeCheckpoint _                                  = RejectResume InvalidCheckpointResume
resumeMatches :: EpicInput -> CheckpointReason -> Bool
resumeMatches ConfirmRoadmapInput ConfirmRoadmap = True
resumeMatches ConfirmAllChildDesignInput ConfirmAllChildDesign = True
resumeMatches input (ConfirmGoalExecutionAuthorization _) = input is AuthorizeGoalExecutionInput _ _ _ || input == RejectGoalExecutionInput
resumeMatches ApproveLocalReviewInput (ApproveReviewFallback _) = True
resumeMatches _ _ = False
applyCheckpointResume :: EpicInput -> EpicState -> Either Reason EpicState
applyCheckpointResume (Start _) s = Right s
applyCheckpointResume (Resume _) s = Right s
applyCheckpointResume (ResumePlanningInput r) s = persistPlanningResume s <$> resumePlanning (planningState s) r
applyCheckpointResume input s
  | Just reason <- s.pendingCheckpoint, resumeMatches input reason = Right (persistCheckpointResume (resumeCheckpoint input) s)
  | otherwise = Left InvalidCheckpointResume
restoreGoalAuthorization :: GoalArtifacts -> EpicGoalRunState
restoreGoalAuthorization a
  | canonicalAuthorizationRejected a = GoalHandoffBlocked "goal execution authorization rejected"
  | approvedGroupWithMatchingProjection a = GoalReadyToDispatch (GroupApproved a.confirmationId a.acceptanceRef a.commitRef)
  | canonicalGroupApprovedWithNonEmptyId a = GoalAuthorizationNeedsRepair (goalProjectionRepairEvidence a)
  | stateProjectionRejected a = GoalHandoffBlocked "goal execution authorization projection rejected"
  | strictLegacy104Artifact a = GoalReadyToDispatch (StrictLegacy104 a.acceptanceRef a.commitRef)
  | otherwise = GoalAuthorizationMissing
persistGoalExecutionAuthorization :: ConfirmationId -> ApprovalRefs -> EpicState -> EpicState
persistGoalExecutionAuthorization confirmationId refs s = atomicReplaceApprovalReport (approvedGoalExecutionGroup confirmationId) >> syncApprovedGoalProjection confirmationId refs s
repairGoalExecutionAuthorization :: WorkflowEvidence -> EpicState -> EpicState
repairGoalExecutionAuthorization evidence s = repairGoalProjectionWhenGroupApproved "goal-execution" evidence s

restoreEpicStage :: EpicState -> EpicRequest -> EpicOutcome
restoreEpicStage(s, request)
  | ambiguousTarget(s, request)                             -> NeedsHuman "which epic?"
  | noRecoverableEpic s && isNothing request.userGoal      -> NeedsHuman "which epic?"
  | s.roadmapStatus == Missing                              -> RoutedTo Planning      -- 大需求未拆解
  | s.roadmapReviewState == ReviewChangesRequested          -> RoutedTo Planning
  | s.roadmapReviewState is ReviewAwaiting agent            -> Awaiting (RoadmapReviewerRunning agent)
  | s.roadmapReviewState is ReviewNeedsOwnerApproval reason -> HumanCheckpoint (ApproveReviewFallback reason)
  | s.roadmapReviewState is ReviewerFailed reason           -> Blocked reason
  | s.roadmapReviewState is ReviewBlocked reason            -> Blocked reason
  | s.roadmapStatus == Draft && s.roadmapReviewState == ReviewMissing -> RoutedTo Review
  | s.roadmapReviewState == ReviewPassed && s.roadmapStatus /= Confirmed
      -> HumanCheckpoint ConfirmRoadmap        -- roadmap review passed 但用户未确认：停下让用户确认 epic 规划
  | s.roadmapStatus == Confirmed && s.roadmapReviewState /= ReviewPassed
      -> Blocked "confirmed roadmap lacks passed review"
  | s.roadmapStatus == Confirmed && s.childrenDesign == Pending
      -> RoutedTo ChildDesignBatch             -- 逐项进 cs-feat（epic_child_batch: true）；design 保持 `draft`，不逐个让用户确认
                                               -- 仍有子 feature 未完成 design-review 就继续下一个，不停用户
  | s.childrenDesign == AllPassed && not s.allDesignApproved
      -> HumanCheckpoint ConfirmAllChildDesign -- 停下让用户统一确认所有 design，确认后逐份标 approved
  | s.allDesignApproved && s.goalRunState == GoalMissing     -> RoutedTo GoalPackage
  | s.goalRunState is GoalComplete _                         -> Completed EpicSummary
  | s.goalRunState is GoalHandoffBlocked reason              -> GoalHandoff (handoffCommand reason)
  | s.goalRunState is GoalDriverActive driver                -> Awaiting (GoalDriverRunning driver)
  | s.goalRunState is GoalAuthorizationNeedsRepair evidence   -> RepairGoalExecutionAuthorization evidence
  | s.goalRunState == GoalAuthorizationMissing                -> HumanCheckpoint (ConfirmGoalExecutionAuthorization (goalCommand s))
  | s.goalRunState is GoalReadyToDispatch _                  -> DispatchGoalDriver "/goal"
  | s.goalRunState is GoalUnknown raw                        -> Blocked ("unknown goal-state: " <> raw)
  | otherwise                                                -> Blocked InvalidEpicState

restoreEpicStage 是唯一路由真相：扫 roadmap 与子 features 恢复 EpicState；restoreGoalAuthorization 只允许 canonical group approved 且 confirmation/ref projection 匹配，或没有新 marker 的严格 1.0.4 legacy artifact，构造 GoalReadyToDispatch，state-first 不得放行。任一 group / named decision rejected 归一为 handoff；group 已 approved 但 projection 未同步时归一为 GoalAuthorizationNeedsRepair，自动修复且不再次询问；其余缺失或不可验证才归一为 GoalAuthorizationMissing。DelegatePlanningResume 先精确恢复 planning checkpoint。用户确认同一条 /goal 后，先 atomic replace canonical approval report 形成 durable commit point，再幂等同步 goal-state。两份证据都可验证才派发。子 design 是连续 batch loop，在统一确认前不得 final answer；stage protocol 见后文。

cs-epic 不在主线程直接执行长程 goal；只能通过可见 Task agent goal driver 派发。没有可见 driver 或派发失败时，回退为用户手动粘贴 /goal。

Workflow

主执行主线（每次调用按序走；planning/review/goal 的厚规则见对应 protocol，本节只定顺序与边界）：

workflow :: EpicInput -> EpicOutcome
workflow = preflight >=> parseEntryIntent >=> restoreEpicState >=> applyCheckpointResume
       >=> restoreEpicStage >=> loadStageProtocol >=> executeStage >=> exitRecoverable

preflight        -- 读 .codestable/attention.md；缺失 -> route to cs-onboard；不得用 AGENTS.md/CLAUDE.md 代替
parseEntryIntent -- flag > compat-preset > utterance；repoFacts override requestedStage；空参不推断 stage
restoreEpicStage -- 扫 .codestable/roadmap/ + 子 features/ + goal 包恢复 EpicState，选 next stage（见 Spec）
loadStageProtocol -- 「Reference 加载」映射；进 stage 才加载该 stage 一个 protocol，禁止 eager 读全部 references
executeStage     -- ChildDesignBatch 走连续 batch loop（下节为唯一权威）；
                 -- 全部 child passed 后 HumanCheckpoint 统一确认所有 design，确认后逐份标 approved；
                 -- DispatchGoalDriver 先尝试可见 driver，失败才输出 GoalHandoff
exitRecoverable  -- artifact 已落盘 / next stage 明确 / checkpoint reason 明确，任一即可让下次调用从 repoFacts 恢复

文件放哪儿

.codestable/roadmap/{slug}/
├── {slug}-roadmap.md
├── {slug}-items.yaml
├── {slug}-roadmap-review.md
├── goal-plan.md
├── goal-state.yaml
├── goal-protocol*.md
├── goal-audit.md
└── goal-features/

普通子 feature 仍放 .codestable/features/YYYY-MM-DD-{feature-slug}/。

Child design batch loop

roadmap 已确认后，子 feature design 阶段是一个连续 batch loop，不是单次子任务：

childDesignBatch :: Slug -> Loop
childDesignBatch slug = loop
  where
    loop = do
      -- 每轮开始、每个 child design-review 后、以及准备 final answer 前都先跑 hook：
      next <- run "python3 <cs-onboard skill 目录>/tools/codestable-workflow-next.py epic \
                  \--roadmap .codestable/roadmap/{slug} --json"
      case next.status of
        continue      -> step next.next_action >> loop
        goal_package  -> step next.next_action >> loop
        dispatch_goal -> step next.next_action >> loop
        user_gate | next.next_action == "all-feature-designs-confirmation"
                      -> stopAt (HumanCheckpoint ConfirmAllChildDesign)
        user_gate | next.next_action == "authorize-epic-goal-execution"
                      -> stopAt (HumanCheckpoint (ConfirmGoalExecutionAuthorization (goalCommand slug)))
        user_gate     -> stopAt (Blocked UnexpectedWorkflowUserGate)
        awaiting      -> stopAt (Awaiting (WorkflowWait next.next_action))
        handoff       -> stopAt (GoalHandoff next.next_action)
        blocked       -> stopAt (Blocked next.reason)
        _             -> stopAt (Blocked InvalidWorkflowNext)
      -- hook 输出 must_continue: true 或 final_answer_allowed: false 时只能来自前三个继续态；不得 final answer
      -- repair-epic-goal-execution-authorization 只消费已 approved 的 durable confirmation evidence，
      -- 幂等同步 goal-state 后继续 loop；不得再次请求 owner，也不得修改 approval commit point。
      -- 每轮先扫 {slug}-items.yaml：按 DAG 取下一个 design-ready 且缺 design、checklist
      -- 或 passed design-review 的 item，调用 cs-feat（epic_child_batch: true）推进；design-ready
      -- 允许依赖 done / dropped / design-review passed，但实现前仍要求依赖严格 done

• 完成某一个 child 的 design + design-review passed 只是内部进度；不得 final answer、不得要求用户确认该 child、不得进入实现。
• 只有 items.yaml 里所有未 dropped child 都已有 design + checklist + passed design-review，才允许触发"所有 design 统一确认"的人工 checkpoint。
• 若下一条 child 可继续推进，本轮必须继续调用 cs-feat，而不是用"下一步继续处理下一个 child"作为结束汇报。
• child batch 只放宽 design admission；不得把 dropped 或仅 design-review passed 的依赖当成 implementation-ready。
• 若 preflight 刚完成 runtime 同步，从仓库事实恢复 batch loop，不靠对话记忆。

Reference 加载

stageProtocol :: Stage -> Protocol
stageProtocol Planning         = "references/planning/protocol.md"   -- 必要时 reference.md、support/codebase-design.md
stageProtocol Review           = "references/review/protocol.md"     -- gate 纪律见下
stageProtocol GoalPackage      = "references/goal/protocol.md"       -- 并复制 support/protocol*.md 和 support/goal-command-template.md
stageProtocol ChildDesignBatch = skill "cs-feat" (epic_child_batch: true)
  -- 子 feature 通过 cs-feat 主入口推进，不直接调用旧阶段技能；
  -- 内部上下文让单 feature 人工 checkpoint 推迟到 cs-epic 的批量确认

-- goal driver 派发规则见 .codestable/reference/agent-conventions.md 的 Goal driver 一节

review gate 必需独立 Task agent reviewer：主 agent 本地审查不得定稿、不得给 passed；roadmap 修订后的每一轮重审同样适用，降级须 approval-report + 用户明确授权（细则见 protocol）。子 feature design-review 经 cs-feat 同受此约束。

人工 checkpoint

触发时机以 Spec 的 restoreEpicStage 为唯一权威；本节只定义停下后的行为：

onCheckpoint :: CheckpointReason -> Action
onCheckpoint ConfirmRoadmap        = 停等用户确认 epic 规划            -- roadmap/epic planning review passed 后
onCheckpoint ConfirmAllChildDesign = 停等用户统一确认所有 design，确认后逐份标 approved
onCheckpoint (ConfirmGoalExecutionAuthorization command) = 展示 command 及 acceptance/scoped-commit 范围；写两项 pending decision，停等 owner 一次确认
onCheckpoint (ApproveReviewFallback reason) = 停等 owner 决定是否批准 local-only review；记录 reason

所有 onCheckpoint 都先把完整 reason 写入 canonical approval-report.md pending decision，再停等输入；无法恢复出同一 pending reason 时，任何 resume 都 fail-closed。Goal 启动确认批准时，生成一个 ConfirmationId，先原子写入 approval_groups.goal-execution 与两项 approved named decision，再幂等同步 goal-state 的相同 id、两份不同 ref 和 ready 状态；不得先写 goal-state，不得只批准一项，也不得再次询问。checkpoint 的 Non-Automatic Actions 必须明确：不会自动执行 remote push、merge、publish、release、deploy、promotion 或 production cutover，这些仍需各自授权。拒绝则把 goal execution 持久化为 handoff，且不得派发。

不要在第一个或任一单独子 feature design-review passed 后停下来要求用户确认执行；那是 cs-feat 普通单 feature 行为，在 cs-epic 子流程里必须延后到所有子 feature 都完成 design-review 后统一处理。 driver 不可见、派发失败或返回 CS_ROADMAP_GOAL_HANDOFF 时走 GoalHandoff，不是 HumanCheckpoint / NeedsHuman 的第二种写法。

Failure Behavior

needsHuman :: Situation -> Bool
needsHuman s = noRecoverableEpic s
            || ambiguousEpicTarget s
            || stageConflictsRepoFacts s

isBlocked :: Situation -> Bool
isBlocked s = invalidArtifactState s    -- 例如 active roadmap 没有 passed review
           || unknownGoalState s
           || reviewerFailed s

报告：当前 roadmap 目录、阻塞原因、下一步用户动作、已写文件、是否可安全重试。可安全回退为 fenced /goal 的 driver 不可用不算 NeedsHuman，统一返回 GoalHandoff。

Output Contract

data ExitPolicy = ContinueRun | StopRecoverable

exitPolicy :: EpicOutcome -> ExitPolicy
exitPolicy (RoutedTo _)           = ContinueRun
exitPolicy (DispatchGoalDriver _) = ContinueRun
exitPolicy (Awaiting _)           = StopRecoverable
exitPolicy (HumanCheckpoint _)    = StopRecoverable
exitPolicy (GoalHandoff _)        = StopRecoverable
exitPolicy (NeedsHuman _)         = StopRecoverable
exitPolicy (Blocked _)            = StopRecoverable
exitPolicy (Completed _)          = StopRecoverable

退出或交接时必须报告：roadmap 目录、恢复出的 goalRunState、child batch 进度、本轮写入文件、下一动作或 checkpoint、已运行验证。DispatchGoalDriver 不得直接退化成 /goal：先按 agent conventions 尝试可见 driver，只有不可用或派发失败才输出 GoalHandoff。

退出条件

mayExit :: State -> Bool
mayExit s = workflowNext(s).final_answer_allowed        -- codestable-workflow-next.py 返回 final_answer_allowed: false 时当前 run 不能退出
         && batchLoopSettled s   -- child design batch loop 只在全部 child design-review passed、遇到 blocking / pending / 授权问题、或用户明确要求停止时才可结束
         && stateRecoverable s   -- 规划、审查、子 feature design 和 goal 包状态能从仓库事实恢复

历史 roadmap 命名只作为内部兼容说明出现；用户主路径称为 epic。需要同步文档或记忆时提示 cs-docs-neat。