using-ccm — 用 ccm CLI 驱动 board
ccm 是 cc-master 的 board 命令行——board 数据模型 SSOT 的唯一写入关卡。本 skill 是它的操作手册:不是"该编排什么"(那是 master-orchestrator-guide),而是"既然要动 board,怎么用 ccm 动得对"。
它一体两面:面1=ccm 命令怎么敲(命令面在 command-catalog.md);面2=board 模型怎么理解 + 字段什么时候设什么值(领域概念解释 + 字段取值指导在 board-model-guide.md)。心智锚在主文件,两面的深度各进一个 reference。
{{USING_CCM_BOUNDARY}}
何时翻开本 skill
你要对 board 做任何读或写——建板、建立 / 确认 / 修订 Goal Contract、加 / 改任务、起跑 / 完成 / 阻塞、为 subagent 写多维 planning 画像与 cross-harness routing policy、声明 delivery target 与依赖资格、登记 / 探测派发出去的运行时 agent(凡派发皆登记)、查 ready 集 / DAG / 临界路径、记 judgment_call 或 log、开 / 收 cadence iteration、arm watchdog——就用 ccm,用法看这里。本文给的是心智 + 纪律 + 热路径,让你不必逐条 --help 也敲得对;深度按两面分进两个 reference,按问题选读:
- references/command-catalog.md(面1·命令面)—— 全量命令 / flag /
--json 输出形状。「这条命令怎么敲、有哪些 flag」翻它。
- references/board-model-guide.md(面2·模型与取值)—— board 领域概念(task 字段 / status 八态 / executor 五种 / judgment_call / cadence / parent / watchdog)解释 + 字段什么时候设什么值的取值判断(acceptance 怎么写好 / estimate 怎么估 / deps 怎么连 / executor 怎么选)+ 决策树 + footgun 深化。「这个字段填什么、这个概念是什么、这个场景选哪个」翻它。
心智锚 1:ccm 是 board 的写入关卡,不是事后才跑的 lint
每次动 board,首选 ccm 命令,而不是 Write/Edit/sed 直接改 board 的 JSON 文件。ccm 这一道写命令替你做四件手改做不到的事:
- 持锁(
.lock·O_EXCL 原子抢占)——串行化写入,防两个写者撕裂文件。
- 校验不变式——FMT/GRAPH/BIZ 规则在落盘前跑;有 hard error 直接 exit 3 拒绝,坏 board 写不进去。
- 守状态机——非法状态转移(见锚 2)当场挡下。
- 守 attempt 边界——
task start 自动盖 started_at、task done 盖 finished_at;task retry 把旧 attempt 证据(含 current delivery candidate/observations)归档到 log 后清空当前态的 started_at / finished_at / artifact / review_verdict / delivery,并把 verified 复位为布尔 false。手改 status 会漏掉这些联动,board 就此说谎。
手改 JSON 把这四道全绕过。别因为"就改一个字段、Write 更快"在 ccm 可用时绕开它——那一下省的几秒,换来的是绕锁、跳校验、derived 字段失真。
心智锚 2:board 是状态机,status 不是你赋值的字段 ★硬规则
这是本 skill 最容易踩、也最不能踩的一条。task 的 status 不是一个你 --set 赋值的普通字段——它是一台状态机的当前态,只能经生命周期 verb 转移。
- 改 status 只有这几条命令:
task start(→ in_flight)、task done(→ done)、task retry(stale/failed/escalated → ready,开启新 attempt)、task block --on(→ blocked)、task unblock(清 blocked_on·交回 deps 门控)、task set-status <id> <status>(通用转移)。
- 没有
task set;task update 不接 --status;--set tasks[T].status=… 被 🔒 守门拒(exit 3);裸 --set status=done 同样被拒(exit 3)——task verb 的裸 path scope 到本 task,status 命中 🔒 守门,不会静默落 board 顶层。
ready → done 非法:必须先 task start(ready → in_flight)再 task done。直接 done 撞 illegal transition: ready → done(exit 3)。
- native-active projection 是更窄的专属状态机:板启用
ccm/native-attempt/v1 且 latest attempt 为 starting|running|uncertain 时,generic start/done/block/unblock/set-status、task update --handle / 通用 setter、legacy route-bind 和 --force 都不能构造或修复 status/handle;只走 native-attempt-create/bind/cancel/terminal/reconcile。可信 terminal 证据只把 task 投影到 uncertain,父层完成端点验收后仍须满足普通 task done --verified --artifact 不变式。
ready ↔ blocked 由系统按 deps 自动归一:每次 ccm 写命令落盘前引擎跑一趟 reconcileGating——无 blocked_on 且 status∈{ready,blocked} 的 task 按 deps 满足度重定(deps 全满足→ready,否则→blocked)。普通历史板和 declared 板里没有显式 requirement 的边保持 legacy;用 task add|update --review-gate APPROVE 声明的 review gate 必须有当前 attempt 的精确 APPROVE,REQUEST-CHANGES、缺失、空或 null 都 fail closed。显式 delivery requirement 还先要求上游 taskTrulyDone,再按 candidate 或指定 target 的 delivered 资格判定。review 的 status=done 只表示审查工作执行完,不等于批准。手动 set-status <id> ready 会被 deps 否决(deps 未满足下一趟归回 blocked)。有 blocked_on(等 user / 等某 task)= 语义阻塞,豁免自动门控;解除用 task unblock <id>,别用 set-status。手改 board 造出的不一致态由 BIZ-STATUS-DEPS warn 兜。
完整转移表:
| 从 |
合法到 |
ready |
in_flight, blocked |
in_flight |
done, uncertain, escalated, failed, blocked |
blocked |
ready, in_flight |
done |
stale |
uncertain |
done, failed, in_flight |
escalated |
ready |
failed |
ready, escalated |
stale |
ready |
verified 是与 status 正交的布尔(--verified),不是一个 status 值。done 且 verified:true 且 artifact 非空,才是真完成(端点验收过);缺任一项会被 BIZ-DONE-VERIFIED hard gate 拒绝落盘(exit 3)。
对显式 review gate,verified:true 只验收「review 工作与报告已完成」,是否批准由当前 attempt 的 review_verdict 单独表达;只有 APPROVE 满足下游 deps。stale|failed|escalated → ready 开新 attempt 时旧 verdict 自动失效,重跑后必须产出新 verdict。
stale / failed / escalated 要重跑时优先用 task retry <id>。它把旧 attempt 的 started_at、finished_at、artifact、verified、review_verdict、delivery 以 ccm/task-retry/v1 结构归档进 append-only log,再原子复位当前 attempt;合法的通用 set-status <id> ready 也共享同一 reset,不会把旧验收 / delivery 证据带进新一轮。retry 的 lifecycle 目标是 ready,但写入关卡随后仍按同一依赖资格求值归一:只有 deps 全满足(declared edge 已 qualified,legacy edge 按既有 satisfied 规则)的 task 才落 ready,否则最终落 blocked;human/JSON 输出按每个 task 的最终态回显。
Rationalization Table —— status 这条最常见的自我说服
| 你会对自己说 |
现实 |
"status 不过是个字段,改字段的通用 idiom 就是 set --status <值>,赋值就行,不用懂状态机。" |
ccm 故意不给 status 一个通用 field-setter。赋值绕过转移闸、不盖 started_at/finished_at——所以 --set status=… 无论带不带 tasks[] 前缀都被 🔒 守门拒(exit 3)。verb 才是对的路:它校验转移合法 + 盖 derived 字段。 |
"我赶时间,task update --status done 一条搞定,省得 start 再 done 两步。" |
task update 没有 --status flag(exit 2),ready→done 也非法(exit 3)——这条"省一步"两次都会失败,反而更慢。start 再 done 才是真正的两步到位。 |
"ccm 报 illegal transition,我加 --force 推过去得了。" |
--force 只给非 native-active 的真异常态留逃生口、会记 log;重跑 stale/failed/escalated 有 task retry,native-active projection 则在 mutation boundary 明确拒绝 --force。正常完成用它跳过 in_flight,等于亲手制造一个没 started_at 的 "done"——你在伪造审计轨迹。 |
心智锚 3:三档字段 —— 🔒 走专属命令,✎ 默认 --set 但可有专属写口
board 字段分三档(权威定义在 ccm 引擎:enums / 字段元数据 / 不变式 / 状态机——实时真相用 ccm <ns> --help。每字段属哪档 + 怎么取值的操作视图见 references/board-model-guide.md §A;这里只给操作规则):
- 🔒 load-bearing:
id / status / deps / parent,以及 board 级 goal / owner / git / tasks。--set 一律拒(exit 3),只能走专属命令(task add/start/done/retry/block/set-status、task update --add-dep/--rm-dep/--parent、ccm goal set|confirm|amend、board update --branch/...)。新板的 goal 只走 ccm goal;board update --goal 仅兼容没有 goal_contract 的 legacy board。
- ✎ flexible:
title / description / estimate / acceptance / justification / artifact 等。这些才用 --set,且 scoping 跟着命令语境走:task add/task update <id> 里裸 path 作用于该 task(ccm task update T1 --set title="新标题" 就落在 T1 上);板级顶层 ✎ 字段走 board update --set;要跨 task 写才用显式前缀 --set tasks[T2].title=…。长尾对象/数组用 --set-json。写入后非 --json 输出会回显实际落点(如 set tasks[T1].title),落点不对一眼可见。少数带 authority/proof 的 ✎ 字段保留专属写口:delivery_contract、task delivery / dependency_requirements 会拒绝 generic setter,分别走 target、task attest-delivery、dependency 命令。
- 👁 observed:
scheduling.wip_limit、watchdog、wip_limit 等——hook 有则用、缺则降级,走各自具名 flag。
一句话:改 🔒 找专属命令;改普通 task ✎ 用 task update <id> --set field=…(裸 path 即本 task),改普通板级 ✎ 用 board update --set;delivery 合约字段例外走具名 domain verb;拿不准先看对应 --help。
心智锚 4:ccm 是 board 变更的唯一写路径 —— 不降级手改
board 变更只走 ccm,没有 Write/Edit/sed 的降级退路——两道机制把这条钉死:
- ccm 硬前置:
ccm 是主机安装前置;as-master-orchestrator 起板时 bootstrap 硬查 command -v ccm,缺则拒 arm(不建 board、注 directive 提醒用户装 ccm)。故一场已武装的 orchestration 里 ccm 必然在——你不会遇到「ccm 没装、只好手改」。
- board-guard:{{USING_CCM_BOARD_GUARD_GUIDANCE}}
万一 ccm 跑起来这一下不响应(装了但瞬态抽风):暂停 board 变更、先修 ccm——绝不退回手改 JSON 顶上去。运行时 hook(board-lint / usage-pacing)对这种瞬态各自优雅降级(静默不 block),但你自己的 board 写永远等 ccm 恢复,不自己动手。
心智锚 5:planning / routing 是 opt-in board 合同,不是自动派发器
要让一个近期 subagent 节点的复杂度、能力要求、模型候选、充足 / 紧张额度链和 fallback 在 handoff / resume 后仍可重建,用 ccm/task-planning/v1 + ccm/agent-routing/v1 成对记录;精确字段、准备顺序与 dedicated writer 见 references/board-model-guide.md §C.5,命令见 references/command-catalog.md 的 board enable-contract、task set-planning、task set-routing、task route-bind。
这套合同当前只拥有 planning / ledger / activation:set-routing 不选中 candidate、不 spawn,enable-contract 不派发,route-bind 也只消费调用方已经取得的 opaque running-handle claim。显式 ccm worker help/run raw wrapper 已可用,但不会自动写 routing.selected / attempts,也不会自动 route 或 fallback;只用同步 raw wrapper 时,不要为了“记录得更完整”强启一个当前拿不到 running handle 的合同。缺少合同的 legacy board / task 保持原行为。
热路径速查(canonical flows)
# 起步:建 pending 板 → 转写 Goal Contract → 确认交付 DDL → 完整性检查
ccm board init # 永不武装·session_id 留空
ccm goal set --summary "无歧义、可验收的目标" --assurance asserted --brief-file /abs/goal.md
ccm goal deadline set --at 2026-08-01T09:00:00Z --source cli-flag --assurance asserted # 或 confirm-none 确认无 DDL
ccm goal check --json # ok 后才能切 DAG;pending/deadline_pending 先 settle
ccm board show # goal/owner/任务统计/lint 是否净
# 派发一个任务从生到完成(端点验收后才 done)
ccm model-policy show --task implementation-from-spec --json # 四 provider 统一角色/事实/taste;再做 target live qualification
{{USING_CCM_TASK_ADD_EXAMPLE}}
ccm task start T3 # ready → in_flight,盖 started_at
ccm task done T3 --artifact /abs/out.md --verified # in_flight → done,盖 finished_at;两项证据必填
ccm task set-status T3 stale # 上游变更使旧产物失效
ccm task retry T3 # stale → ready;旧证据归档,当前 attempt 原子复位
# review gate:执行完成与批准分开;只有 APPROVE 解锁下游
ccm task add R1 --type review --review-gate APPROVE
ccm task start R1
ccm task done R1 --artifact /abs/review.md --verified --review-verdict REQUEST-CHANGES
# declared delivery:先声明目标与 edge 要求,再为当前 true-done attempt 做本地 proof
ccm target set main --kind git-ref --ref refs/remotes/origin/main
ccm dependency require DOWN UP --level delivered --target main
ccm task attest-delivery UP --target main --method git-commit-contained --candidate-commit <oid>
ccm dependency explain DOWN UP # qualified|unqualified|unknown + 稳定 diagnostics
ccm delivery audit --strict-dry-run # 只预览缺声明边;绝不打开 strict-default、绝不写板
# 阻塞等用户(必带 decision_package,否则 BIZ-AWAITING 硬闸 exit 3)
ccm task block T9 --on user --decision @/abs/decision.json
ccm task block T5 --on T2 # 阻塞在另一个 task 上
# 调度视图
ccm next # 现在能派发什么(readySet)
ccm board graph # 拓扑 / 环 / 临界路径 / makespan
ccm board critical-path # 临界链 + 工期
# 自驱决策记录 / 节奏 / watchdog
ccm jc add "选 X 不选 Y" --category architecture --severity high
ccm cadence open I1 --goal "ship 切片" --deadline 2026-06-05T14:00:00Z --members T0,T1
{{USING_CCM_WATCHDOG_ARM_EXAMPLE}}
全量命令、每个 flag、--json 输出形状 → references/command-catalog.md。
footgun 速查(踩过就记住)
| 现象 |
真相 / 怎么做 |
task update --set status=done 被拒 exit 3 |
task 语境的裸 path scope 到本 task,status 是 🔒。status 永远走 verb(锚 2)。 |
task done 报 illegal transition: ready → done |
先 task start。ready 不能直接 done。 |
| 重跑后 task 还显示旧 artifact / verified |
用 task retry <id> 开新 attempt,不要用字段 setter 拼 reset。合法的 set-status <id> ready 也会走同一原子 reset。 |
native attempt 活跃时 task start/done/set-status/update --handle 或 route-bind --force 被拒 |
这是 BIZ-NATIVE-ATTEMPT-PROJECTION 对专属 writer 的硬闸,--force 也不能绕。只用五个 native-attempt-* verb;terminal 后先独立验收,再从 uncertain 走普通 true-done。 |
--set 的值不知道落哪了 |
看非 --json 输出的 set <path> 回显行:task verb 裸 path=本 task,board update 裸 path=board 顶层,jc add/cadence * 裸 path=board 顶层。 |
task show <id> 返回 data:null 还 exit 0 |
读不存在的 id 不报错——调用方自己判 null。 |
board lint exit 3 但 stdout 是 {"ok":true,...} |
外层信封 ok 恒 true;lint 是否净看 data.ok 与 exit code(3=有 hard error)。 |
block --on user 写进去了却被 lint 挡 |
awaiting-user 节点必须带 decision_package(--decision @file),否则 BIZ-AWAITING 硬闸。 |
board update --goal 在新板被拒 |
Goal Contract 已激活;用 ccm goal amend --summary ... --reason ... --assurance ... 生成新 revision。board update --goal 只服务 legacy board。 |
goal check 返回 pending |
目标还没 settled;澄清后 goal set / goal amend,不要切 DAG 或派发。复杂背景用 --brief-file 落成受管 Goal Brief。 |
goal check 返回 deadline_pending |
目标 settled 但交付 DDL 未 settle(goal_contract.deadline 缺失或仍 pending);先 ccm goal deadline set/confirm(确认截止期)或 ccm goal deadline confirm-none(确认无 DDL),再切 DAG。deadline 只走专属 verb,--set goal_contract.* 被拒。 |
review task 已 done,下游仍 blocked |
若它声明了 --review-gate APPROVE,这是正确行为:检查 review_verdict;只有 task done ... --review-verdict APPROVE 开门,REQUEST-CHANGES/缺 verdict 都不开门。 |
review 上轮已 APPROVE,retry 后下游又 blocked |
verdict 只属于当前 attempt;`stale |
| 上游 true-done,但 declared 下游仍 blocked |
true-done 只证明 candidate-complete,不证明已到指定 target。用 delivery check / dependency explain 看本地 containment、target drift 或 missing-object diagnostic;branch/worktree 存在不是 delivery proof。 |
waiver 让 edge ready,却看到 target_delivered:false |
这是设计语义:waiver 只把这一条 user-authorized、edge-scoped、未过期 requirement 资格化,输出 qualified_by=waiver;它从不伪装 target 已交付。 |
| 想把 declared 一键变 strict-default |
本版本没有这个写口。只有 delivery audit --strict-dry-run / explain 的 ephemeral preview;不得持久化 mode:strict。 |
set-routing 写好了,就以为 ccm 会自动选择 / spawn / fallback |
routing contract 是 opt-in planning/ledger,不是 dispatcher。显式派发仍由 orchestrator 发起;只有拿到真实派发面的 opaque running handle 后才可 route-bind。同步 ccm worker run 不会自动回填 board。 |
| ISO 时间字段被 lint warn |
一律严格 YYYY-MM-DDTHH:MM:SSZ(UTC 定宽),别用本地时区 / 带毫秒。 |
| 多个 active 板时命令报 Ambiguous |
用 --goal <子串> 或 --board <path> 消歧。 |
| open cadence iteration 出 overbooked / critical-path / oversized warn |
这不是 hard gate,但说明本轮节奏不健康。先拆小、移出 scope、删假依赖或重估;不要靠 cadence ship 把超载藏起来。 |
想用 --set-json 手拼 agents 段 / 手改 agent 状态 |
agent 生命周期走专属 verb:agent create/bind/link/terminal/probe——bind 无真实 handle 证据被拒(exit 3)、状态转移有校验、link 幂等、probe 字段由 ccm 落盘;通用 setter 手拼会把这些全绕过。 |
收割完 agent 产出、roster 却还满是 running |
收割 / 端点验收掉 agent 产出后要显式 ccm agent terminal <id> --outcome "..." 收口——「凡派发皆登记」的对称另一半是「凡收割皆收口」。agent probe 只判死活、永不 →terminal;不收口 = 永久 running 僵尸污染 recon 的 in_flight/phantom 判定(agent terminal ≠ task done 只挡正向,不豁免这条反向闭环)。 |
以为批量 agent terminal 要一个个小心防锁竞态 |
顺序 bash 背靠背跑多条 ccm agent terminal(已知 id)无 race——每条各抢一次 O_EXCL board 锁·天然串行。别 & 后台并行 ccm 写(争锁 exit 4)。真正要定序的是单 agent 的 create→bind→link 三连(bind/link 吃 create 返回的 id·靠数据依赖定序),不是「所有 agent 操作都必须逐个」。 |
Exit code 速记
{{USING_CCM_EXIT_CODES}}
Pointers
{{USING_CCM_POINTERS_HOST}}
- references/board-model-guide.md —— 面2·board 模型操作指南:领域概念(task 字段 / status 八态 / executor 五种 / judgment_call / cadence / parent / watchdog)解释 + 字段取值判断(acceptance / estimate / deps / executor 怎么选)+ 决策树 + 全部 FMT/GRAPH/BIZ 校验规则速查(一次写对不撞 exit 3)+ footgun 深化。命令怎么敲看 command-catalog,字段填什么、概念是什么、会撞哪条规则看这本。
- master-orchestrator-guide —— 决策层:该编排什么、怎么拆 DAG、何时阻塞等用户、配额到边界时该停还是该问。本 skill 是它的"手怎么动"。注:board 协议的权威定义在
ccm 引擎(enums / 字段元数据 / 不变式 / 状态机);本 skill 只给操作视图、不复述权威定义。
- authoring-workflows —— 在 workflow 脚本里编排并行时怎么写(那是脚本 DSL,不是 ccm CLI)。
- 实时真相永远以
ccm <namespace> <cmd> --help 为准——本文与 catalog 是地图,--help 是当前领土。
1---2name: using-ccm3description: "{{USING_CCM_DESCRIPTION}}"4---56# using-ccm — 用 ccm CLI 驱动 board78> `ccm` 是 cc-master 的 board 命令行——board 数据模型 SSOT 的**唯一写入关卡**。本 skill 是它的**操作手册**:不是"该编排什么"(那是 master-orchestrator-guide),而是"既然要动 board,怎么用 ccm 动得对"。9> **它一体两面**:面1=**ccm 命令怎么敲**(命令面在 `command-catalog.md`);面2=**board 模型怎么理解 + 字段什么时候设什么值**(领域概念解释 + 字段取值指导在 `board-model-guide.md`)。心智锚在主文件,两面的深度各进一个 reference。10>11> {{USING_CCM_BOUNDARY}}1213---1415<!-- ccm:k:start point:ccm.when-to-open -->16## 何时翻开本 skill1718你要对 board 做**任何**读或写——建板、建立 / 确认 / 修订 Goal Contract、加 / 改任务、起跑 / 完成 / 阻塞、为 subagent 写多维 planning 画像与 cross-harness routing policy、声明 delivery target 与依赖资格、登记 / 探测派发出去的运行时 agent(凡派发皆登记)、查 ready 集 / DAG / 临界路径、记 judgment_call 或 log、开 / 收 cadence iteration、arm watchdog——就用 ccm,用法看这里。本文给的是**心智 + 纪律 + 热路径**,让你不必逐条 `--help` 也敲得对;深度按两面分进两个 reference,按问题选读:1920- **[references/command-catalog.md](references/command-catalog.md)**(面1·命令面)—— 全量命令 / flag / `--json` 输出形状。**「这条命令怎么敲、有哪些 flag」翻它。**21- **[references/board-model-guide.md](references/board-model-guide.md)**(面2·模型与取值)—— board 领域概念(task 字段 / status 八态 / executor 五种 / judgment_call / cadence / parent / watchdog)解释 + 字段**什么时候设什么值**的取值判断(acceptance 怎么写好 / estimate 怎么估 / deps 怎么连 / executor 怎么选)+ 决策树 + footgun 深化。**「这个字段填什么、这个概念是什么、这个场景选哪个」翻它。**2223<!-- ccm:k:end point:ccm.when-to-open -->24---2526<!-- ccm:k:start point:ccm.write-gate -->27## 心智锚 1:ccm 是 board 的写入关卡,不是事后才跑的 lint2829每次动 board,**首选 ccm 命令**,而不是 `Write`/`Edit`/`sed` 直接改 board 的 JSON 文件。ccm 这一道写命令替你做四件手改做不到的事:30311. **持锁**(`.lock`·O_EXCL 原子抢占)——串行化写入,防两个写者撕裂文件。322. **校验不变式**——FMT/GRAPH/BIZ 规则在落盘前跑;有 hard error 直接 exit 3 拒绝,坏 board 写不进去。333. **守状态机**——非法状态转移(见锚 2)当场挡下。344. **守 attempt 边界**——`task start` 自动盖 `started_at`、`task done` 盖 `finished_at`;`task retry` 把旧 attempt 证据(含 current `delivery` candidate/observations)归档到 log 后清空当前态的 `started_at` / `finished_at` / `artifact` / `review_verdict` / `delivery`,并把 `verified` 复位为布尔 `false`。手改 status 会漏掉这些联动,board 就此说谎。3536手改 JSON 把这四道全绕过。**别因为"就改一个字段、Write 更快"在 ccm 可用时绕开它**——那一下省的几秒,换来的是绕锁、跳校验、derived 字段失真。37<!-- ccm:k:end point:ccm.write-gate -->3839---4041<!-- ccm:k:start point:ccm.status-state-machine -->42## 心智锚 2:board 是状态机,status 不是你赋值的字段 ★硬规则4344这是本 skill 最容易踩、也最不能踩的一条。**task 的 `status` 不是一个你 `--set` 赋值的普通字段——它是一台状态机的当前态,只能经生命周期 verb 转移。**4546- 改 status **只有**这几条命令:`task start`(→ in_flight)、`task done`(→ done)、`task retry`(stale/failed/escalated → ready,开启新 attempt)、`task block --on`(→ blocked)、`task unblock`(清 `blocked_on`·交回 deps 门控)、`task set-status <id> <status>`(通用转移)。47- **没有** `task set`;`task update` **不接** `--status`;`--set tasks[T].status=…` 被 🔒 守门拒(exit 3);裸 `--set status=done` 同样被拒(exit 3)——task verb 的裸 path scope 到本 task,`status` 命中 🔒 守门,不会静默落 board 顶层。48- **`ready → done` 非法**:必须先 `task start`(ready → in_flight)再 `task done`。直接 done 撞 `illegal transition: ready → done`(exit 3)。49- **native-active projection 是更窄的专属状态机**:板启用 `ccm/native-attempt/v1` 且 latest attempt 为 `starting|running|uncertain` 时,generic `start/done/block/unblock/set-status`、`task update --handle` / 通用 setter、legacy `route-bind` 和 `--force` 都不能构造或修复 status/handle;只走 `native-attempt-create/bind/cancel/terminal/reconcile`。可信 terminal 证据只把 task 投影到 `uncertain`,父层完成端点验收后仍须满足普通 `task done --verified --artifact` 不变式。50- **`ready ↔ blocked` 由系统按 deps 自动归一**:每次 ccm 写命令落盘前引擎跑一趟 `reconcileGating`——**无 `blocked_on`** 且 status∈{ready,blocked} 的 task 按 deps 满足度重定(deps 全满足→ready,否则→blocked)。普通历史板和 declared 板里没有显式 requirement 的边保持 legacy;用 `task add|update --review-gate APPROVE` 声明的 review gate 必须有当前 attempt 的精确 `APPROVE`,`REQUEST-CHANGES`、缺失、空或 null 都 fail closed。显式 delivery requirement 还先要求上游 `taskTrulyDone`,再按 `candidate` 或指定 target 的 `delivered` 资格判定。review 的 `status=done` 只表示审查工作执行完,不等于批准。**手动 `set-status <id> ready` 会被 deps 否决**(deps 未满足下一趟归回 blocked)。**有 `blocked_on`(等 user / 等某 task)= 语义阻塞,豁免自动门控**;解除用 **`task unblock <id>`**,别用 `set-status`。手改 board 造出的不一致态由 `BIZ-STATUS-DEPS` warn 兜。5152完整转移表:5354| 从 | 合法到 |55|---|---|56| `ready` | in_flight, blocked |57| `in_flight` | done, uncertain, escalated, failed, blocked |58| `blocked` | ready, in_flight |59| `done` | stale |60| `uncertain` | done, failed, in_flight |61| `escalated` | ready |62| `failed` | ready, escalated |63| `stale` | ready |6465> `verified` 是与 status **正交的布尔**(`--verified`),不是一个 status 值。`done` 且 `verified:true` 且 `artifact` 非空,才是真完成(端点验收过);缺任一项会被 `BIZ-DONE-VERIFIED` hard gate 拒绝落盘(exit 3)。66> 对显式 review gate,`verified:true` 只验收「review 工作与报告已完成」,是否批准由**当前 attempt** 的 `review_verdict` 单独表达;只有 `APPROVE` 满足下游 deps。`stale|failed|escalated → ready` 开新 attempt 时旧 verdict 自动失效,重跑后必须产出新 verdict。6768> `stale` / `failed` / `escalated` 要重跑时优先用 `task retry <id>`。它把旧 attempt 的 `started_at`、`finished_at`、`artifact`、`verified`、`review_verdict`、`delivery` 以 `ccm/task-retry/v1` 结构归档进 append-only log,再原子复位当前 attempt;合法的通用 `set-status <id> ready` 也共享同一 reset,不会把旧验收 / delivery 证据带进新一轮。retry 的 lifecycle 目标是 `ready`,但写入关卡随后仍按同一依赖资格求值归一:只有 deps 全满足(declared edge 已 `qualified`,legacy edge 按既有 satisfied 规则)的 task 才落 `ready`,否则最终落 `blocked`;human/JSON 输出按每个 task 的最终态回显。6970### Rationalization Table —— status 这条最常见的自我说服7172| 你会对自己说 | 现实 |73|---|---|74| "status 不过是个字段,改字段的通用 idiom 就是 `set --status <值>`,赋值就行,不用懂状态机。" | ccm **故意**不给 status 一个通用 field-setter。赋值绕过转移闸、不盖 `started_at`/`finished_at`——所以 `--set status=…` 无论带不带 `tasks[]` 前缀都被 🔒 守门拒(exit 3)。verb 才是对的路:它校验转移合法 + 盖 derived 字段。 |75| "我赶时间,`task update --status done` 一条搞定,省得 start 再 done 两步。" | `task update` 没有 `--status` flag(exit 2),`ready→done` 也非法(exit 3)——这条"省一步"两次都会失败,反而更慢。`start` 再 `done` 才是真正的两步到位。 |76| "ccm 报 illegal transition,我加 `--force` 推过去得了。" | `--force` 只给非 native-active 的真异常态留逃生口、会记 log;重跑 stale/failed/escalated 有 `task retry`,native-active projection 则在 mutation boundary 明确拒绝 `--force`。正常完成用它跳过 `in_flight`,等于亲手制造一个没 `started_at` 的 "done"——你在伪造审计轨迹。 |77<!-- ccm:k:end point:ccm.status-state-machine -->7879---8081<!-- ccm:k:start point:ccm.field-tiers -->82## 心智锚 3:三档字段 —— 🔒 走专属命令,✎ 默认 `--set` 但可有专属写口8384board 字段分三档(权威定义在 `ccm` 引擎:enums / 字段元数据 / 不变式 / 状态机——实时真相用 `ccm <ns> --help`。每字段属哪档 + 怎么取值的操作视图见 [references/board-model-guide.md](references/board-model-guide.md) §A;这里只给**操作规则**):8586- **🔒 load-bearing**:`id` / `status` / `deps` / `parent`,以及 board 级 `goal` / `owner` / `git` / `tasks`。**`--set` 一律拒(exit 3)**,只能走专属命令(`task add`/`start`/`done`/`retry`/`block`/`set-status`、`task update --add-dep/--rm-dep/--parent`、`ccm goal set|confirm|amend`、`board update --branch/...`)。新板的 goal 只走 `ccm goal`;`board update --goal` 仅兼容没有 `goal_contract` 的 legacy board。87- **✎ flexible**:`title` / `description` / `estimate` / `acceptance` / `justification` / `artifact` 等。**这些才用 `--set`**,且 scoping 跟着命令语境走:`task add`/`task update <id>` 里**裸 path 作用于该 task**(`ccm task update T1 --set title="新标题"` 就落在 T1 上);板级顶层 ✎ 字段走 `board update --set`;要跨 task 写才用显式前缀 `--set tasks[T2].title=…`。长尾对象/数组用 `--set-json`。写入后非 `--json` 输出会回显实际落点(如 `set tasks[T1].title`),落点不对一眼可见。**少数带 authority/proof 的 ✎ 字段保留专属写口**:`delivery_contract`、task `delivery` / `dependency_requirements` 会拒绝 generic setter,分别走 `target`、`task attest-delivery`、`dependency` 命令。88- **👁 observed**:`scheduling.wip_limit`、`watchdog`、`wip_limit` 等——hook 有则用、缺则降级,走各自具名 flag。8990一句话:**改 🔒 找专属命令;改普通 task ✎ 用 `task update <id> --set field=…`(裸 path 即本 task),改普通板级 ✎ 用 `board update --set`;delivery 合约字段例外走具名 domain verb;拿不准先看对应 `--help`。**91<!-- ccm:k:end point:ccm.field-tiers -->9293---9495<!-- ccm:k:start point:ccm.single-write-path -->96## 心智锚 4:ccm 是 board 变更的唯一写路径 —— 不降级手改9798board 变更**只走 `ccm`**,没有 `Write`/`Edit`/`sed` 的降级退路——两道机制把这条钉死:99100- **ccm 硬前置**:`ccm` 是**主机安装前置**;`as-master-orchestrator` 起板时 bootstrap 硬查 `command -v ccm`,缺则**拒 arm**(不建 board、注 directive 提醒用户装 ccm)。故一场已武装的 orchestration 里 `ccm` **必然在**——你不会遇到「ccm 没装、只好手改」。101- **board-guard**:{{USING_CCM_BOARD_GUARD_GUIDANCE}}102103**万一 `ccm` 跑起来这一下不响应**(装了但瞬态抽风):**暂停 board 变更、先修 `ccm`**——**绝不**退回手改 JSON 顶上去。运行时 hook(board-lint / usage-pacing)对这种瞬态各自优雅降级(静默不 block),但**你自己的 board 写永远等 `ccm` 恢复**,不自己动手。104<!-- ccm:k:end point:ccm.single-write-path -->105106<!-- ccm:k:start point:ccm.planning-opt-in -->107## 心智锚 5:planning / routing 是 opt-in board 合同,不是自动派发器108109要让一个近期 `subagent` 节点的复杂度、能力要求、模型候选、充足 / 紧张额度链和 fallback 在 handoff / resume 后仍可重建,用 `ccm/task-planning/v1` + `ccm/agent-routing/v1` 成对记录;精确字段、准备顺序与 dedicated writer 见 [references/board-model-guide.md](references/board-model-guide.md) §C.5,命令见 [references/command-catalog.md](references/command-catalog.md) 的 `board enable-contract`、`task set-planning`、`task set-routing`、`task route-bind`。110111这套合同当前只拥有 **planning / ledger / activation**:`set-routing` 不选中 candidate、不 spawn,`enable-contract` 不派发,`route-bind` 也只消费调用方已经取得的 opaque running-handle claim。显式 `ccm worker help/run` raw wrapper 已可用,但不会自动写 `routing.selected` / `attempts`,也不会自动 route 或 fallback;只用同步 raw wrapper 时,不要为了“记录得更完整”强启一个当前拿不到 running handle 的合同。缺少合同的 legacy board / task 保持原行为。112<!-- ccm:k:end point:ccm.planning-opt-in -->113114---115116<!-- ccm:k:start point:ccm.hotpath-flows -->117## 热路径速查(canonical flows)118119```bash120# 起步:建 pending 板 → 转写 Goal Contract → 确认交付 DDL → 完整性检查121ccm board init # 永不武装·session_id 留空122ccm goal set --summary "无歧义、可验收的目标" --assurance asserted --brief-file /abs/goal.md123ccm goal deadline set --at 2026-08-01T09:00:00Z --source cli-flag --assurance asserted # 或 confirm-none 确认无 DDL124ccm goal check --json # ok 后才能切 DAG;pending/deadline_pending 先 settle125ccm board show # goal/owner/任务统计/lint 是否净126127# 派发一个任务从生到完成(端点验收后才 done)128ccm model-policy show --task implementation-from-spec --json # 四 provider 统一角色/事实/taste;再做 target live qualification129{{USING_CCM_TASK_ADD_EXAMPLE}}130ccm task start T3 # ready → in_flight,盖 started_at131ccm task done T3 --artifact /abs/out.md --verified # in_flight → done,盖 finished_at;两项证据必填132ccm task set-status T3 stale # 上游变更使旧产物失效133ccm task retry T3 # stale → ready;旧证据归档,当前 attempt 原子复位134135# review gate:执行完成与批准分开;只有 APPROVE 解锁下游136ccm task add R1 --type review --review-gate APPROVE137ccm task start R1138ccm task done R1 --artifact /abs/review.md --verified --review-verdict REQUEST-CHANGES139140# declared delivery:先声明目标与 edge 要求,再为当前 true-done attempt 做本地 proof141ccm target set main --kind git-ref --ref refs/remotes/origin/main142ccm dependency require DOWN UP --level delivered --target main143ccm task attest-delivery UP --target main --method git-commit-contained --candidate-commit <oid>144ccm dependency explain DOWN UP # qualified|unqualified|unknown + 稳定 diagnostics145ccm delivery audit --strict-dry-run # 只预览缺声明边;绝不打开 strict-default、绝不写板146147# 阻塞等用户(必带 decision_package,否则 BIZ-AWAITING 硬闸 exit 3)148ccm task block T9 --on user --decision @/abs/decision.json149ccm task block T5 --on T2 # 阻塞在另一个 task 上150151# 调度视图152ccm next # 现在能派发什么(readySet)153ccm board graph # 拓扑 / 环 / 临界路径 / makespan154ccm board critical-path # 临界链 + 工期155156# 自驱决策记录 / 节奏 / watchdog157ccm jc add "选 X 不选 Y" --category architecture --severity high158ccm cadence open I1 --goal "ship 切片" --deadline 2026-06-05T14:00:00Z --members T0,T1159{{USING_CCM_WATCHDOG_ARM_EXAMPLE}}160```161162全量命令、每个 flag、`--json` 输出形状 → [references/command-catalog.md](references/command-catalog.md)。163<!-- ccm:k:end point:ccm.hotpath-flows -->164165---166167<!-- ccm:k:start point:ccm.footgun-table -->168## footgun 速查(踩过就记住)169170| 现象 | 真相 / 怎么做 |171|---|---|172| `task update --set status=done` 被拒 exit 3 | task 语境的裸 path scope 到本 task,`status` 是 🔒。status 永远走 verb(锚 2)。 |173| `task done` 报 `illegal transition: ready → done` | 先 `task start`。`ready` 不能直接 `done`。 |174| 重跑后 task 还显示旧 artifact / verified | 用 `task retry <id>` 开新 attempt,不要用字段 setter 拼 reset。合法的 `set-status <id> ready` 也会走同一原子 reset。 |175| native attempt 活跃时 `task start/done/set-status/update --handle` 或 `route-bind --force` 被拒 | 这是 `BIZ-NATIVE-ATTEMPT-PROJECTION` 对专属 writer 的硬闸,`--force` 也不能绕。只用五个 `native-attempt-*` verb;terminal 后先独立验收,再从 `uncertain` 走普通 true-done。 |176| `--set` 的值不知道落哪了 | 看非 `--json` 输出的 `set <path>` 回显行:task verb 裸 path=本 task,`board update` 裸 path=board 顶层,`jc add`/`cadence *` 裸 path=board 顶层。 |177| `task show <id>` 返回 `data:null` 还 exit 0 | 读不存在的 id **不报错**——调用方自己判 null。 |178| `board lint` exit 3 但 stdout 是 `{"ok":true,...}` | 外层信封 `ok` 恒 true;**lint 是否净看 `data.ok` 与 exit code**(3=有 hard error)。 |179| `block --on user` 写进去了却被 lint 挡 | awaiting-user 节点**必须**带 `decision_package`(`--decision @file`),否则 BIZ-AWAITING 硬闸。 |180| `board update --goal` 在新板被拒 | Goal Contract 已激活;用 `ccm goal amend --summary ... --reason ... --assurance ...` 生成新 revision。`board update --goal` 只服务 legacy board。 |181| `goal check` 返回 pending | 目标还没 settled;澄清后 `goal set` / `goal amend`,不要切 DAG 或派发。复杂背景用 `--brief-file` 落成受管 Goal Brief。 |182| `goal check` 返回 deadline_pending | 目标 settled 但交付 DDL 未 settle(`goal_contract.deadline` 缺失或仍 pending);先 `ccm goal deadline set/confirm`(确认截止期)或 `ccm goal deadline confirm-none`(确认无 DDL),再切 DAG。deadline 只走专属 verb,`--set goal_contract.*` 被拒。 |183| review task 已 `done`,下游仍 blocked | 若它声明了 `--review-gate APPROVE`,这是正确行为:检查 `review_verdict`;只有 `task done ... --review-verdict APPROVE` 开门,REQUEST-CHANGES/缺 verdict 都不开门。 |184| review 上轮已 `APPROVE`,retry 后下游又 blocked | verdict 只属于当前 attempt;`stale|failed|escalated → ready` 会清旧 verdict。新一轮 `task done` 必须显式给新的 `--review-verdict APPROVE` 才重新开门。 |185| 上游 true-done,但 declared 下游仍 blocked | true-done 只证明 candidate-complete,不证明已到指定 target。用 `delivery check` / `dependency explain` 看本地 containment、target drift 或 missing-object diagnostic;branch/worktree 存在不是 delivery proof。 |186| waiver 让 edge ready,却看到 `target_delivered:false` | 这是设计语义:waiver 只把这一条 user-authorized、edge-scoped、未过期 requirement 资格化,输出 `qualified_by=waiver`;它从不伪装 target 已交付。 |187| 想把 declared 一键变 strict-default | 本版本没有这个写口。只有 `delivery audit --strict-dry-run` / explain 的 ephemeral preview;不得持久化 `mode:strict`。 |188| `set-routing` 写好了,就以为 ccm 会自动选择 / spawn / fallback | routing contract 是 opt-in planning/ledger,不是 dispatcher。显式派发仍由 orchestrator 发起;只有拿到真实派发面的 opaque running handle 后才可 `route-bind`。同步 `ccm worker run` 不会自动回填 board。 |189| ISO 时间字段被 lint warn | 一律严格 `YYYY-MM-DDTHH:MM:SSZ`(UTC 定宽),别用本地时区 / 带毫秒。 |190| 多个 active 板时命令报 Ambiguous | 用 `--goal <子串>` 或 `--board <path>` 消歧。 |191| open cadence iteration 出 overbooked / critical-path / oversized warn | 这不是 hard gate,但说明本轮节奏不健康。先拆小、移出 scope、删假依赖或重估;不要靠 `cadence ship` 把超载藏起来。 |192| 想用 `--set-json` 手拼 `agents` 段 / 手改 agent 状态 | agent 生命周期走专属 verb:`agent create/bind/link/terminal/probe`——bind 无真实 handle 证据被拒(exit 3)、状态转移有校验、link 幂等、probe 字段由 ccm 落盘;通用 setter 手拼会把这些全绕过。 |193| 收割完 agent 产出、roster 却还满是 `running` | 收割 / 端点验收掉 agent 产出后要显式 `ccm agent terminal <id> --outcome "..."` 收口——「凡派发皆登记」的对称另一半是「凡收割皆收口」。`agent probe` 只判死活、**永不 →terminal**;不收口 = 永久 `running` 僵尸污染 recon 的 in_flight/phantom 判定(`agent terminal ≠ task done` 只挡正向,不豁免这条反向闭环)。 |194| 以为批量 `agent terminal` 要一个个小心防锁竞态 | 顺序 bash 背靠背跑多条 `ccm agent terminal`(已知 id)**无 race**——每条各抢一次 O_EXCL board 锁·天然串行。别 `&` 后台并行 ccm 写(争锁 exit 4)。真正要定序的是**单 agent 的 create→bind→link 三连**(bind/link 吃 create 返回的 id·靠数据依赖定序),不是「所有 agent 操作都必须逐个」。 |195<!-- ccm:k:end point:ccm.footgun-table -->196197---198199<!-- ccm:k:start point:ccm.exit-codes -->200## Exit code 速记201202{{USING_CCM_EXIT_CODES}}203<!-- ccm:k:end point:ccm.exit-codes -->204205---206207<!-- ccm:k:start point:ccm.pointers-routing -->208## Pointers209210{{USING_CCM_POINTERS_HOST}}211- [references/board-model-guide.md](references/board-model-guide.md) —— 面2·board 模型操作指南:领域概念(task 字段 / status 八态 / executor 五种 / judgment_call / cadence / parent / watchdog)解释 + 字段取值判断(acceptance / estimate / deps / executor 怎么选)+ 决策树 + **全部 FMT/GRAPH/BIZ 校验规则速查**(一次写对不撞 exit 3)+ footgun 深化。命令怎么敲看 command-catalog,字段填什么、概念是什么、会撞哪条规则看这本。212- **master-orchestrator-guide** —— 决策层:该编排什么、怎么拆 DAG、何时阻塞等用户、配额到边界时该停还是该问。本 skill 是它的"手怎么动"。注:board 协议的权威定义在 `ccm` 引擎(enums / 字段元数据 / 不变式 / 状态机);本 skill 只给操作视图、不复述权威定义。213- **authoring-workflows** —— 在 workflow 脚本里编排并行时怎么写(那是脚本 DSL,不是 ccm CLI)。214- 实时真相永远以 `ccm <namespace> <cmd> --help` 为准——本文与 catalog 是地图,`--help` 是当前领土。215<!-- ccm:k:end point:ccm.pointers-routing -->