c3

C3——一个模型，三个阶段

C3 是架构自身的词汇体系，固化为共享事实；工作只能通过经过审查的变更单元来修改它。

1. 塑造模型，冻结事实。 自顶向下梳理领域——起草工作所需的事实，并在过程中将它们接入模型；精简的画布（各实体在 此处 包含的章节和类型化列）已就位，只有领域需要时才采用自定义事实类型。然后关闭闸门，事实便会冻结：成为共享事实，不再手动编辑。
2. 变更单元推动进展。 工作通过变更单元推进——一份 ADR 加上其补丁文件夹，构成一个原子 Saga：声明意图，工具会确保结果完整一致（成员关系、引用、闸门），并一次性提交全部变更。冻结的事实只能通过此合并来修改。
3. 画布随需求扩展和演进。 当工作超出模型的承载范围时，提升画布（向上攀一阶，只做增量扩展），或变形画布（以非增量方式重塑建模不当的类型），并迁移每条事实以使其符合要求——在一个受闸门控制的原子单元中完成；绝不放宽完整性要求。

构建模型 → 冻结事实 → 变更单元推动工作 → 画布随需求扩展。

CLI 调用

打包后的运行时为 c3x，通过技能目录内的包装脚本 <skill-dir>/bin/c3x.sh 调用。没有 c3 可执行文件。每条命令都必须显式调用包装脚本：

# Template: resolve <skill-dir> to this skill's directory, then replace the command and args.
C3X_MODE=agent bash "<skill-dir>/bin/c3x.sh" check

在一个 shell 中运行多条命令时，可以使用此辅助函数，但它只是 shell 函数，不会安装 c3 命令：

c3local() { C3X_MODE=agent bash "<skill-dir>/bin/c3x.sh" "$@"; }

C3X_MODE=agent → 输出 TOON（令牌数约减少 40%），并在每个结果后附加 help[] 提示——请遵循这些提示。打包后的 CLI 是唯一事实来源；此技能是路由器：对意图分类、加载参考文档、调用包装脚本、遵循输出。它会列出每个闸门，但不讲解任何流程——流程详见参考文档。

意图分类

关键词	操作	参考文档
adopt、init、bootstrap、onboard、“create .c3”	onboard	references/onboard.md
where、explain、how、diagram、trace、“show me”、“what is”、“what handles”	query	references/query.md
audit、validate、“check docs”、“is the doc intact”	audit	references/audit.md
add、change、fix、implement、refactor、remove、design	change	references/change.md
pattern、convention、“create ref”、“update ref”、standardize	ref	references/ref.md
“coding rule”、“coding standard”、“split ref into rule”	rule	references/rule.md
“edit the canvas”、“change the shape”、“what sections does X have”、“add a doc type”、“raise the bar”、“add prd/user-story”	canvas	references/canvas.md
impact、“what breaks”、assess、sweep、“is this safe”	sweep	references/sweep.md
“does the code match”、conformance、“is the doc still true”、“check against code”、drift-vs-external	eval	references/eval.md

分派

1. 对操作进行分类（含糊不清时 → 使用带选项的 AskUserQuestion）。
2. 加载 references/<op>.md。
3. 运行 CLI（并行执行时使用 Task 工具），遵循 help[]。

前置条件 — 只读快速路径。 概念 → 封装器 search；文件/glob → lookup；ID/章节 → read --section。命中后，使用一次 graph <id> --depth 1 获取路由上下文；确认所有者、适用的参考资料、一条因果关联和下一步操作均有证据后即停止。将 route.facts、route.graph、route.anchors、route.lanes、route.drift 和 route.hash 作为检查线索，而非证明或应用关卡。对于所有权/查询会话，证明最多使用四次 C3 调用：search/lookup、一次 graph、所有者章节，以及一条适用规则章节；不要阅读每条引用规则。优先采用精简读取；不要重复成功的读取。仅在未命中、发生漂移、明确要求审计或需要变更时，才使用 list、完整读取、源代码扫描或测试。对于开放式影响分析，保留 2–3 条独立路径，将重复项重定向，阻止缺少定理级证据的结论，并且仅在出现新机制时重新打开；要求提供具体 ID、命令和证据。绝不读取/Glob/编辑 .c3/ 实例（画布定义是用户拥有的例外）；缺少 .c3/ → 引导接入。

共享契约

这些规则在此统一说明，所有引用均指向此处。

冻结事实。 事实是指画布未声明任何 status: 集的实体：system、container、component、ref、rule、pm-requirement、user-story。事实一旦带有正文，就会被冻结：对其执行包装器的 write、set 和 delete 操作都会被拒绝（守卫根据第一个参数判断；未知类型会被视为冻结）。拒绝信息会指出唯一合法路径：“ 是事实——事实处于冻结状态，只能通过变更单元进行更改。” 事实只能通过在变更单元中编写补丁并运行包装器的 change apply 操作来更改。

*不受冻结限制的情况：*包装器的 add 操作（创建新事实不受守卫限制）、首次 write（为从未带过正文的事实编写正文）、编辑变更文档（adr/prd/atomic-design-change——它们声明了 status:），以及编辑画布定义（由用户拥有）。事实与代码的绑定完全不受冻结限制：它位于 .c3/eval/<fact>.yaml（code: 字段）中——这是普通的可编辑文件，可随代码移动自由调整指向；它本身不是冻结事实，因此无需豁免（references/eval.md）。

成员关系由构建自动生成。 每次父级关系发生变化（通过包装器执行 add、change apply 或 check --fix）时，工具都会根据子级的 parent: 链接生成父级的成员关系表。将此行留给工具处理——切勿手动编写或编辑。（设置 parent:；该行便会自动出现。）父级关系不是图边：parent: 会设置子级的 parent_id 和自动生成的成员关系行；这与连线边（uses、引用、edge<> 列）是彼此独立的维度，包装器的 graph 操作会显示这些边。重新指定父级会更新 parent_id 和两个父级的成员关系；不会影响连线。

事实始终必须完整满足其所在级别的契约。 画布是一个级别——代表某一复杂度等级的完整契约，并非需要随时间逐步填充的目标。全新初始化的画布刻意保持精简（第 1 级）；复杂项目所需的更深入章节属于更高级别，而不是画布中的空缺。完整性要求绝不放宽。要扩展，提升一个级别：提升画布，然后将所有受影响的事实完整迁移到新契约；完整性规则禁止事实跨越两个级别。若结构本身有误——即建模错误，而不只是精简——则应变更结构：对画布进行非增量式重塑（演进单元：canvas 范围的补丁），在一个受门控的原子单元中将每个实例迁移到新结构，同样遵守不得跨级别的规则（references/change.md §变更模型结构）。

ADR 状态集： [open, accepted, done, superseded]。（包装器的 add adr 操作会将状态设为 proposed——这是 open 的旧称；当 After 引用解析为最新内容时，accepted 会自动锁定为 done。）终态变更文档（done/superseded）是内容冻结的历史记录，不受包装器 check 操作检查。默认情况下，list/check 会排除 ADR；使用 --include-adr 将其纳入。

命令表

打包的 CLI 就是目录 — 使用 <cmd> --help 调用本地包装器；其输出具有权威性。变更单元门禁栈（承载关键流程）位于 references/change.md。

命令	用途
list	拓扑及计数 + 覆盖情况（--flat、--compact）
check	根据事实图谱验证事实，并检查一致性（--fix、--only、--include-adr）。事实与代码的一致性不在此检查 — 请运行包装器中独立且可关闭的 eval 操作
eval	检查冻结事实的声明是否符合其所约束的非受控外部对象（.c3/eval/<fact>.yaml 中的 code: 绑定）。这是一次性的 CI 周期性判定，绝不是门禁（references/eval.md）
repair	从规范 .c3/ 重建临时缓存并重新封存（在切换分支 / 选择性合并后）
search <query>	概念 → 按语义 + 关键词 + 图信号查找实体；有可用线索时提供路径提示
lookup <file-or-glob>	文件 / glob → 组件 + 引用
read <id>	实体内容（--full；--section <name> --cite 会输出补丁基准锚点）
graph <id>	关系图及路径维度（facts、graph、anchors、lanes、drift、hash）；--depth、--direction forward|reverse、--format mermaid、--unit <adr-id> 可预览暂存补丁
add <type> <slug>	创建事实（正文通过 stdin 或 --file 提供；使用 --container、--feature）。这是无保护的创建路径
canvas <list|read|add|write>	管理图谱定义（用户拥有的结构，位于 .c3/canvases/）
schema <type>	渲染图谱的章节 / 列 / REJECT-IF（以拒绝契约开头）
write <id> / set <id> <field> <val> / delete <id>	直接编辑 — 拒绝对冻结事实执行（参见契约）。仅适用于变更文档和图谱正文
change <new|view|status|accept|apply|rebase|scaffold>	变更单元流程 — 修改事实的唯一方式。apply 会原子地运行门禁栈；rebase 会为发生漂移的补丁输出漂移包；scaffold 会暂存阶梯式升级。参见 references/change.md

缺少打包操作？→ 停止并告知用户。不要使用文件工具变通处理。