架构路由：从意图到层、能力与外部项目¶
本页把「一个架构需求该落在哪里」收敛成可机械复用的决策顺序与路由表。它服务于新智能体在不通读源码的前提下，快速得到可验证答案：该需求是否属于 Foundation、应落在 Contracts/Harness/Kit/Profile 哪一层、用哪个稳定入口、什么语义仍由调用方拥有、何时应转交外部项目。
决策顺序¶
按编号依次判断，命中即停：
- 是否含领域语义、业务状态机或审计 oracle？ 若是，留在消费者；Foundation 只接业务中立机制。
- 是否是结构、协议、稳定错误码或对象 Schema？ 落 Contracts（契约权威）。
- 是否是跨技能族可复用的 Node 机制？ 落 Harness（Contracts 机制协议的 Node 实现）。
- 是否是工程阶段的 scaffold/adopt-plan/projection/check，或具体 host Profile 注入？ 落 Kit / Profile。
- 是否涉及发布远端状态？ 转 release-skill。
- 是否涉及任务、重试、返工、验收或自迭代？ 转 loop-agent。
- 是否涉及制品关系、context、packet 或 version-lock？ 转 artifact-graph。
- 是否只有一个消费者，或尚未证明跨两个真实消费者重复？ 默认留在消费者，不扩张 Foundation。
第 8 步是扩张闸门。任何新增组件都必须说明：删除它会让两个以上真实消费者重复实现，并经独立 fixture 验证。否则留在消费者侧。
路由表¶
下表给出常见架构意图的首选能力与禁止误用。每条首选能力都可在 capability-catalog.json 按 id 查到入口、副作用与失败语义。
| 架构意图 | 首选能力 | 禁止误用 |
|---|---|---|
| 验证 Foundation 合同对象 | Contracts / Harness validation（foundation.contracts.object-validation、foundation.harness.contract-validation） |
不取代消费者业务 Schema |
| 安全文件访问和原子写 | Harness path / atomic API（foundation.harness.path-containment、foundation.harness.atomic-write） |
不把文件选择业务规则放入 Harness |
| 生成确定性人类报告 | Harness report 或 Kit report 子动作（foundation.harness.report、foundation.kit.report） |
不从开放业务 outputs 自由编报告 |
| 持久事件和派生 snapshot | Harness state-store（foundation.harness.state-store） |
不在 Foundation 定义 workflow 状态机 |
| 新项目骨架 | Kit scaffold（foundation.kit.scaffold） |
不覆盖非空存量仓 |
| 存量采用盘点 | Kit adopt-plan（foundation.kit.adopt-plan） |
不写文件、不自动迁移 |
| 受管投影 | Kit projection + Profile（foundation.kit.projection） |
不覆盖 handwritten 文件 |
| 工程诊断 | Kit check（foundation.kit.check） |
不自动修复 |
| 发布 | release-skill | Foundation 不拥有远端写入 |
| 任务/重试/返工 | loop-agent | Foundation 不拥有业务状态机 |
| 制品关系/版本锁 | artifact-graph | Foundation 不拥有制品图 |
分层定位速查¶
依赖方向固定为 Contracts → Harness → Engineering Kit；Profile 横向声明，公共核心不反向依赖具体 Profile。
- Contracts：结构、协议、错误码、协议名登记；18 类顶层对象、9 条 mandatory rule。
- Harness：Contracts 的 Node 薄机制运行时；只实现业务中立机制，不拥有语义。
- Engineering Kit：四个工程命令（scaffold、adopt-plan、projection、check）及其只读/受限写入边界。
- Profile：宿主与项目形态差异的声明式 SPI；只实现稳定 SPI，不注入业务语义。
- 外部项目：release-skill（发布）、loop-agent（任务生命周期）、artifact-graph（制品关系）、独立审计消费者（领域语义）。
典型误路由与纠正¶
- 误把领域 Schema 路由到 Foundation：领域 Schema 由消费者拥有，Foundation 只提供通用校验机制（
foundation.contracts.object-validation）。 - 误把 workflow 状态机路由到 Foundation：state-store 只提供事件日志与快照底座，reducer 转移与终态由调用方拥有（
foundation.unsupported.business-state-machine）。 - 误把发布写入路由到 Foundation：远端写入归 release-skill，Foundation 不含任何 publish/remote-write 入口（
foundation.unsupported.remote-publish）。 - 误把审计 oracle 路由到 Foundation：审计表面只做确定性序列化，领域结论属外部审阅（
foundation.unsupported.domain-audit-semantics）。
路由判断的诚实边界：结构检查只证明字节/结构一致性（仓内可证）；普通正文语义与最终接受/拒绝结论属于外部独立审阅，不在目标仓内维护第二份门禁。