cs-goal

cs-goal

作業の前に CodeStable の preflight を実行します：.codestable/attention.md を読み込みます（存在しない場合は cs-onboard を実行します）。代わりに AGENTS.md／CLAUDE.md などの外部エントリーポイントを使用してはいけません。詳細は .codestable/reference/execution-conventions.md を参照してください。

cs-goal はスコープが明確な goal を扱います：owner が開始点と期待する最終状態を示し、CodeStable はまず簡単な interview／grill を行います。作業に着手する前に開始点レポートを作成し、その後、自律的に実装、検証、反復します。完了前に Task agent に機能受け入れテストを依頼し、iteration レポートを作成する必要があります。レポート本文では .codestable/attention.md に記載されたプロジェクトのレポート言語に従います。言語ポリシーがない場合は、owner が現在の会話で使用している言語を使います。

これは goal のラッパーであり、feature／issue／refactor のルールに取って代わるものではありません。goal が capability boundary を越える場合、バグの根本原因を明らかにする場合、または動作を変えない refactor のガバナンスが必要な場合は、goal の iteration 内で対応する feature／issue／refactor の成果物を作成するか、参照してください。

成果物のテンプレート、state.yaml のスキーマ、レポートのタイトル、復旧ルールについては reference.md を参照してください。

cs-goal は goal driver（単一責任であり、stage を編成する workflow ではありません）です。以下の ## Spec は最初の入口となる契約であり、本文のフェーズ 1／2／3、owner-stop、complete／blocked のルールが方法論の本体です。

Spec

csGoal :: GoalRequest -> GoalOutcome
csGoal req | attentionMissing req = NeedsHuman "route to cs-onboard"
           | otherwise = either NeedsHuman (selectNextAttempt req) (restoreGoalState req.repoFacts >>= applyGoalResume req.resumeInput)
data GoalRequest = GoalRequest
  { ownerGoal  : Maybe Text          -- 有界终点 / 验收 / 预算；缺则先 grill
  , resumeInput : Maybe GoalResume
  , repoFacts  : RepoFacts           -- .codestable/goals/ + state.yaml，优先于聊天历史
  , attention  : Maybe Attention     -- .codestable/attention.md；缺则 route to cs-onboard
  }
data OwnerStopState
  = NoOwnerStop
  | PendingStop CheckpointReason
  | ResolvedStop GoalOwnerDecision
data GoalState = GoalState           -- 从 .codestable/goals/YYYY-MM-DD-{slug}/ 恢复
  { goalDir          : Maybe Path
  , status           : Active | Complete | Blocked   -- state.yaml 为机器 source of truth
  , hasStartReport   : Bool          -- goal.md 起点报告；实现前必须存在
  , currentIteration : Int           -- 最后一个已完成 iteration 编号
  , acceptancePassed : Bool          -- Task agent functional-acceptance verdict = pass
  , acceptanceReport, acceptanceFinalIteration : Maybe Path
  , finalIterationReport, finalAcceptanceReport : Maybe Path
  , blockerSignature : Maybe Text
  , blockerCount     : Int           -- 同一 blocker 连续 iteration 次数
  , ownerStop        : OwnerStopState
  }
data GoalOwnerDecision = ResumeWith GoalDelta | ApproveLocalReviewFallback ApprovalRef | KeepBlocked
data GoalResume = ResolveGoalStop CheckpointReason GoalOwnerDecision
applyGoalResume :: Maybe GoalResume -> GoalState -> Either Reason GoalState
applyGoalResume Nothing s = Right s
applyGoalResume (Just (ResolveGoalStop reason decision)) s
  | s.ownerStop == PendingStop reason && validGoalDecision reason decision s = Right (persistGoalDecision decision s)
  | otherwise = Left InvalidGoalResume
validGoalDecision :: CheckpointReason -> GoalOwnerDecision -> GoalState -> Bool
validGoalDecision ReviewAgentUnavailable (ApproveLocalReviewFallback ref) s = inheritedReviewAgentUnavailable s && approvalArtifactApproved s ref "goal-local-review"
validGoalDecision _ (ApproveLocalReviewFallback _) _ = False
validGoalDecision _ _ _ = True
data GoalOutcome
  = Iterating GoalState               -- 自主继续，已写 iteration 报告 + 刷新 state.yaml
  | HumanCheckpoint CheckpointReason  -- strict owner-stop：先写 approval-report.md 再停
  | Completed GoalSummary             -- acceptance + Task agent 验收 + final iteration 齐备
  | Blocked GoalSummary               -- owner 已决定保持 blocked；不重复询问
  | NeedsHuman Reason
data CheckpointReason      -- 全部枚举仅指已运行 goal 的 owner-stop：新 goal 未 grill 前的
                           -- 信息缺口（验收/预算/终点未谈）一律先走阶段 1 grill，不触发 checkpoint
  = AcceptanceConflict     -- 仅指已运行 goal 的验收标准自身冲突/不足以判断完成；
                           -- 验证全绿但未跑终端验收 → 先启动可见 Task agent 验收，也不是本 checkpoint
  | AmbiguousTerminal      -- objective / start / terminal 存在重大歧义
  | ScopeBoundaryChange    -- 会改变 goal 之外的 long-term spec / public contract / capability
  | RepeatedBlocker        -- 同一 blocker 连续三次 iteration
  | BudgetExhausted        -- budget 用尽或接近用尽
  | RiskAcceptanceNeeded   -- 需人类风险接受 / secrets / 破坏性 / 外部购买 / merge / deploy 批准
  | AcceptanceAgentUnavailable -- 终端验收 Task agent 无法启动且按生命周期
                           -- 重试仍失败：写 approval-report 后 owner-stop，不自验收
  | ReviewAgentUnavailable -- 独立 review agent 不可用；仅 inherited 配置可经命名 ApprovalRef 降级
acceptanceArtifactReady :: GoalState -> Bool
acceptanceArtifactReady s = s.acceptancePassed && canonicalFunctionalAcceptance s.acceptanceReport
completionEvidenceReady :: GoalState -> Bool
completionEvidenceReady s = acceptanceArtifactReady s
  && currentIterationReport s == s.finalIterationReport
  && s.acceptanceFinalIteration == s.finalIterationReport
  && s.finalAcceptanceReport == s.acceptanceReport

selectNextAttempt は唯一のルーティング上の真実であり、ライフサイクル全体を網羅します（判断の詳細は「フェーズ 1／2／3」「厳格な Owner Stop」「Complete と Blocked のルール」を参照してください。ここでは分岐の形式と順序を固定します）：

selectNextAttempt :: GoalRequest -> GoalState -> GoalOutcome
selectNextAttempt(req, s)
  | attentionMissing                              -> NeedsHuman "route to cs-onboard"
  | isNothing s.goalDir && boundedGoal(req)       -> Iterating (grill req)          -- 阶段 1：先 grill 收集验收/预算/终点；
                                                                                    -- 新 goal 的信息缺口走 grill，不进任何 checkpoint
  | isNothing s.goalDir                           -> NeedsHuman "grill 无法收敛出有界 goal"
  | not s.hasStartReport && canRebuild(s, req)    -> Iterating (writeStartReport s) -- 阶段 2：从 state / interview 证据重建，实现前必须存在
  | not s.hasStartReport                          -> NeedsHuman "缺起点报告且无法从证据重建"
  | s.status == Complete && completionEvidenceReady s -> Completed (summary s)
  | s.status == Complete                          -> NeedsHuman "complete goal lacks linked acceptance/final-iteration evidence"
  | s.ownerStop is PendingStop reason
                                                   -> HumanCheckpoint reason
  | s.status == Blocked && s.ownerStop is ResolvedStop (ResumeWith delta)
                                                   -> Iterating (resumeGoal s delta)
  | s.status == Blocked && s.ownerStop is ResolvedStop (ApproveLocalReviewFallback ref)
                                                   -> Iterating (resumeWithLocalReview s ref)
  | s.status == Blocked && s.ownerStop is ResolvedStop KeepBlocked
                                                   -> Blocked (summary s)
  | s.status == Blocked                           -> NeedsHuman "blocked goal lacks owner-stop state"
  | ownerStopTriggered(s)                         -> HumanCheckpoint (ownerStopReason s)  -- 含 RepeatedBlocker / Budget / …
  | s.status == Active && completionEvidenceReady s -> Iterating (repairCompleteState s)
  | s.status == Active && acceptanceArtifactReady s -> Iterating (recordFinalIterationAndComplete s)
  | s.status == Active                             -> Iterating (nextMinimalAttempt s)     -- 阶段 3：review / 验收经可见 Task agent

Operation

主な実行フロー（呼び出しごとに順番に進めます。必要に応じて段階的にリファレンスを読み込み、起動時にすべてを読むことはしません）：

1. preflight — .codestable/attention.md を読み込みます（存在しない場合 → cs-onboard）＋このスキルの reference.md を読み込みます。system-overview.md が存在する場合は読み込みます。それ以外は必要に応じて読み込みます：goal の成果物／approval-report を作成する前に goal-conventions.md／approval-conventions.md を読み込みます。Task agent の review／受け入れテストの前に agent-conventions.md を読み込みます。
2. restoreGoalState — .codestable/goals/ を検索し、該当する active goal を探します（日付プレフィックスが今日でなくても対象です）。state.yaml（active | complete | blocked）が機械向けの source of truth で、Markdown は人向けです。復旧時の優先順位は state.yaml > 最新の iteration の frontmatter > 本文です。state.yaml に明確な値があれば、レポート本文から推測しません。goal が既存の領域を指している場合は、.codestable/compound/ と関連する feature／issue／refactor のドキュメントを検索します。
3. selectNextAttempt — 上記の guard に従って選択します：grill／開始点レポートの再構築／自律的な反復／checkpoint／完了。
4. execute — フェーズ 1／2／3 のルールに従って実行します。review と最終受け入れテストは、近くで確認できる Task agent を介して行い、自分でレビューや受け入れテストをしてはいけません。
5. record — iteration レポートを作成します（番号を増やし、上書きしません）＋state.yaml を更新します。
6. exit — 復旧可能な終了状態である complete | blocked | active のいずれかで終了します（Exit を参照）。

使用場面

owner がスコープの明確な目標を示した場合は cs-goal を使用します：この不具合のある状態を直してテストをすべて通す、受け入れ結果を達成する、complete または blocked になるまで自律的に反復する、「まず私に質問してから実装してほしい」、「技術的な選択より、結果を重視する」。

次の用途には使用しないでください：実装目標のない純粋な design／roadmap／議論の依頼、owner がまだ最終状態を決めていないオープンエンドな brainstorm、AI に完了まで推進することを求めない状態確認や audit。

フェーズ 1：Grill による認識合わせ

新しい goal を作成する前に、必ず grill を行います。interview／grill は一度限りの会話ではなく、goal の正式な開始点として扱います。簡潔に進め、owner レベルの情報に焦点を当てます。

焦点を絞った質問を最大 3～5 問行います。各ラウンドでは 1 つの質問を、実質的に異なる 2～4 個の選択肢とともに提示します。回答によって goal の境界が変わる場合を除き、実装の詳細は尋ねないでください。

grill の回答によって、スコープ、進め方、予算、リスク、停止方針について owner の承認が必要で、選択肢の説明も必要な場合は、先に .codestable/goals/YYYY-MM-DD-{slug}/approval-report.md を作成します。簡単な確認事項は chat 上で済ませてかまいません。意思決定の checkpoint にはレポートが必要です。

収集する情報は次のものに限ります：

• objective。
• starting point。
• acceptance／done のシグナル。
• non-goals。
• すでに提示されている budget または停止に関する希望。
• この goal 固有の strict owner-stop conditions。

owner から十分な情報が提示されている場合は、まず要約してから続行します。

フェーズ 2：Goal の作成または復旧

goal のライフサイクルディレクトリ：

.codestable/goals/YYYY-MM-DD-{slug}/
├── state.yaml
├── goal.md
├── functional-acceptance.md
└── iterations/

ディレクトリ名には goal の作成日を使用し、feature／issue／refactor のディレクトリ命名スタイルに合わせます。state.yaml の goal フィールドには、業務上の slug のみを保持します。

functional-acceptance.md は最終受け入れテストの gate でのみ作成し、goal の開始時には空のファイルを作成しません。

goal.md は interview／grill から生成する永続的な開始点レポートであり、実装前に存在している必要があります。内容には objective、starting point、acceptance criteria、non-goals、owner の決定事項、未解決の前提、next action を含めます。簡潔に保ち、goal の境界または状態が変化した場合にのみ更新します。

デフォルトではサフィックスなしの canonical レポートパスを使用します。.codestable/attention.md で追加の言語別コピーが明示的に必要とされている場合に限り、goal.{lang}.md、functional-acceptance.{lang}.md、iterations/{nnn}.{lang}.md などのサフィックス付きコピーを追加します。デフォルトではこれらのバリエーションは必要ありません。

復旧と再構築のルールについては、## Operation のステップ 2 と selectNextAttempt の guards を参照してください。一致する active goal がすでにある場合は、常にそれを復旧し、重複するディレクトリを作成しません。

阶段 3：自主迭代

一次 iteration 是一次连贯的实现 / 验证尝试，不是一条命令。

选实现方案（缩范围、fake / mock / 正则 / 占位、实现深度）时，先做 .codestable/reference/solution-depth-conventions.md 的方案深度 pre-pass：goal 自主迭代最易滑向"够跑就行"，按场景论证深度，采用降级 / 替身时在 iteration 报告显式写候选、理由和转正条件，不因省事默认最小。

当 state: active 时循环：

1. 从 state.yaml 选择最小有用的下一次尝试。
2. 按既有 CodeStable 约束实现；spec-governance 和 commit 规则适用时同样遵守。 涉及 review gate（cs-code-review）时，按 .codestable/reference/agent-conventions.md 通过附近可见 Task agent 启动独立 reviewer 审查本轮 diff，并复用共享 selectTaskAgent Review / reviewGate。显式 pin 的配置不可用时 owner-stop，不能降级；继承配置下 agent 不可用时先写 pending goal-local-review 命名决策，只有 ApproveLocalReviewFallback ApprovalRef 机械核验通过才可 local review。不在 goal driver 主线程静默自审。
3. 用 fresh 命令或证据验证。
4. 修改 state.yaml.current_iteration 前，根据 state.yaml.current_iteration 和已有 iterations/{nnn}*.md 文件推导下一个三位数 iteration 编号；不要覆盖旧报告。
5. 为已完成尝试更新 state.yaml，留下 current_iteration: {n}。
6. 写该次完成 iteration 的 canonical 报告：iterations/{nnn}.md。只有 .codestable/attention.md 要求时才添加语言后缀副本。
7. 除非触发 owner-stop 条件，否则自主继续。

不要每条命令后都写报告；报告是 iteration 摘要。不要仅凭普通测试证据把 goal 标成完成； 必须先运行终端功能验收 gate。

终端功能验收

把 state.yaml.status 改为 complete 前：

1. 用 fresh evidence 跑正常验证。
2. 按 .codestable/reference/agent-conventions.md 的 Task agent 选择规则启动附近 可见 Task agent（按 agent-conventions「启动 mode」用 plan / read-only 等价 mode 只读 启动，一步到位不要先默认 mode 再重起），对记录的 owner acceptance criteria 和实际产品 / 产物行为做功能验收。
3. 把结果写入 functional-acceptance.md，包括 reviewer、scope、acceptance checks、 functional evidence、verdict、residual risks；只有真实未完成动作写 Follow-Up，已完成交付写 Delivery Record。
4. 结果被写入并引用后，按 Task agent 生命周期关闭该验收 agent；关闭失败只记录 warning。
5. 在 final iteration 中引用功能验收报告。

功能验收是面向产品的证据。它可以包括黑盒使用、产物检查、UI / API workflow 检查、 fixture 输出复核，或其他和 owner 相关的证明。单测、lint 和 build 是有用证据，但单独 不足以完成 goal。

如果 Task agent 无法启动或未获授权，先按 Task agent 生命周期处理容量失败重试；仍失败时写 approval-report.md 并 owner-stop。不要自验收 goal 为 complete。

严格 Owner Stop

只有触发 owner-stop 才停下来问 owner；触发条件以 Spec 的 CheckpointReason 枚举及其注释为唯一权威（含 ReviewAgentUnavailable / AcceptanceAgentUnavailable），本节不另列清单。

普通技术选择、测试失败、实现备选和局部 refactor 由 AI 负责，除非跨过以上 stop 条件。

Failure Behavior

cs-goal 停下的三种形态：

• NeedsHuman：无法启动 goal driver。.codestable/attention.md 缺失（→ cs-onboard）； owner 未给终点且 grill 也无法收敛出有界 goal；已有 active goal 但缺起点报告且无法从 state 与 interview 证据重建。
• HumanCheckpoint：driver 触发 strict owner-stop（见「严格 Owner Stop」枚举的 CheckpointReason）。停前先写 .codestable/goals/YYYY-MM-DD-{slug}/approval-report.md， 除非最新 iteration 报告已含完整决策上下文、选项、推荐、权衡、证据、后果和下一步。
• Blocked：owner 已回答并选择保持 blocked，或明确不继续；记录后返回终态摘要，不重复同一 checkpoint。owner 选择 ResumeWith 时应用 GoalDelta；批准命名 local-review fallback 时持久化 ApprovalRef；两者都先把 status 改回 active 并清除 pending owner-stop，再继续 iteration。

三种情况都要报告：当前 goal 目录、state.yaml.status、阻塞或 checkpoint 原因、需要的 owner 决策或下一步动作、已写文件（起点报告 / 最新 iteration / approval-report），以及是否 可安全重试或继续。不要在 acceptance 未过时假装完成，也不要自验收 goal 为 complete。

Complete 与 Blocked 规则

只有 acceptance signal 已满足、Task agent 功能验收报告记录 passing verdict、final iteration 已落盘，且两份报告按 canonical 路径双向引用并与 currentIteration 对齐时，才能标记 complete。

只有同一个 blocker 至少连续三次 iteration 重复，或 owner-stop 规则说明 AI 无法安全继续时， 才能标记 blocked。记录 blocker_signature、blocker_count、证据和需要的 owner 决策。问 owner 决策前，先在 goal 目录写 approval-report.md，除非最新 iteration 报告已经 包含完整决策上下文、选项、推荐、权衡、证据、后果和下一步。

如果 budget 在验收前结束，带审批上下文停下，不要假装完成。

Exit

goal run 以下列状态之一退出：

• complete：acceptance evidence、Task agent 功能验收和 final iteration 均已写入。
• blocked：blocker 证据和 owner 问题已记录。
• active：iteration 报告和 next action 已记录，但当前回合或 budget 不足以继续。

最终回复要短；goal 完成时指向 goal.md、最新 iteration 报告和 functional-acceptance.md。

Guardrails

• 不让 owner 选择日常技术细节。
• 不让报告正文覆盖 state.yaml。
• 不为同一 objective 创建重复 active goal。
• 有实质工作后不跳过 iteration 报告。
• 不仅凭测试标记完成，也不伪造 Task agent 验收。
• strict owner-stop 触发后不继续迭代。
• 每个 Markdown 产物必须少于 300 行；过长就拆分。