跳到主要内容

工程包

⚠️ 占位包：本工程包等 <前置 milestone> 收尾时由前置 milestone gate 强制 trigger 起草。当前 status: pending，正文为模板占位，不应被工程实施 agent 当作可执行内容读取。

承接整改包 II（Step 11 IV-4 + II-3）的工程包模板规范，详见 Step 11 整改包详细方案 Action II-1。

§0 Build-Y 正向产出 / Delivery contract（强制，置顶先填）​

强制章节，先于范围 / 边界 / 约束填写。 承接 ADR-013 codify 哲学换轨 · Build-Y 优先 §3.1：每份工程包必须先回答"本 milestone 要做成什么、产出什么正向能力"，再谈"不做什么、约束什么"。本章节空着或只填禁令时，工程包不予起草通过。

0.1 交付契约（本 milestone 新增什么可用能力）​

正向陈述本 milestone 完成后系统新增的可用能力——句式必须是"FinBayes 能做到 Y / 必须输出 Y / 用户能用 Y"，不是"禁止 X"。

能力 ID新增可用能力（正向陈述）对应用户价值可观测信号（CLI / API / fixture / case runner）
CAP-1<例：FinBayes 能在本地完成初始化并通过 CLI / TUI 调用同一 runtime><用户能在本机跑通一次完整认知链路><command>
............

0.2 三类正向机制（承接正向交付契约定义）​

按 正向交付契约 · 三类正向机制 填写。约束服务于交付契约，不喧宾夺主。

机制本 milestone 的内容
交付契约本切片完成后系统新增了什么可用能力（同 0.1）
实现约束为让能力成立，代码必须遵守哪些结构 / 数据边界（详见 §1）
约束服务于交付契约每条 §1 约束都能回链到 0.1 的某个能力 ID，无悬空禁令

0.3 任务驱动与暴露面（承接 MP-4 / MP-5）​

  • 任务驱动字段组合：本 milestone 落地哪些 task_type、对应必含字段子集，引用 MP-4 任务→字段动态组合契约 与 contracts/tasks-fields-mapping.yaml。不允许扁平 schema 全字段必选。
  • 字段暴露面分层：本 milestone 落地字段的 surface（user_widget / internal_audit / both），引用 MP-5 字段暴露面分层契约 与 contracts/field-surface-mapping.yaml。不允许默认全字段用户面。

§1 范围与边界​

1.1 implement / stub 边界表​

子系统 / 接口M 状态M 状态备注
<子系统名>implement / stub / 未触及implement / stub / 未触及<演化原因>

1.2 与 M<N+1> 的边界​

明示本 milestone 不做 的事（避免 scope 漂移）：

  • ...
  • ...

1.3 与上位事实源对齐​

  • 战略不变量：本 milestone 守护的不变量清单（引用 contracts/ 或战略白皮书 §X）
  • 产品定义：本 milestone 落地的产品要求（引用 product-definition §X）
  • 架构主文件：本 milestone 落地的 §X 章节

§2 接口子集（基于 contracts/code-paths.yaml）​

接口 ID路径M 状态签名
<src/finbayes/...>implement / stub<ts/python signature>

§3 schema（基于 contracts/structured-cognition-result.yaml）​

本 milestone 落地的 Pydantic 字段。引用 contracts/，不重复定义。

3.1 主体 schema​

# src/finbayes/cognition/types.py
# 字段定义见 contracts/structured-cognition-result.yaml

3.5 milestone 子集​

本 milestone 暴露字段子集 + schema_version 字符串。

§4 SQLite DDL（如有）​

-- migrations/000N_<feature>.sql

§5 业务对象（引用 architecture.md §4 + contracts/）​

引用 architecture.md §4 业务对象 + contracts/。不重复字段表。

§6 LLM Provider 接入要求​

本 milestone 是否新增 Provider 层（L1' / L2 / L3 / L4），以及降级要求。

§7 评测维度子集（基于 contracts/evaluation-dimensions.yaml）​

本 milestone 启用的 D 维度子集：D / D / ...

§8 sample fixtures（5-10 条 minimum 可 validate）​

# tests/m<N>/fixtures/samples/<sample_id>.yaml
sample_id: ...
task: ...
expected_capabilities:
  - assertion: "<断言>"
    pytest_check: "<不依赖 str() 等内置函数的结构化扫描表达式>"

§9 凭证治理 fixture（5 类 negative test）​

承接 ADR-010 凭证过滤位置。复用 m0-walking-skeleton §9 patterns，本 milestone 是否新增类别。

§10 凭证正则基线​

引用 m0-walking-skeleton §10 patterns（M0 已定）。本 milestone 是否扩展。

§11 验收 checklist​

11.1 自动验收​

ID检查命令 / 断言
AUTO-1<自动断言 1><command>
.........

11.2 人工验收 5 条 checklist​

ID检查评分人
MANUAL-1<人工 checklist 1>工作流维护者（人类）+ Claude 主控辅助
.........

整改包 III 要求：每个 milestone 至少 1 个 PR gate 由人类工作流维护者亲自走（不只签字）。

§12 Archon 工作流契约引用​

引用 .archon/workflows/milestone-M<N>.yaml（必须存在）。

§13 风险与降级​

承接 architecture.md §13 + §24 风险登记。本 milestone 新增 / 缓解的风险。

§14 测试目录树​

tests/
  m<N>/
    fixtures/
      samples/
    test_<feature>.py
    test_<feature>_acceptance.py

§14.5 contract test​

def test_all_pydantic_models_have_schema_version():
    ...
def test_milestone_subset_compatibility():
    ...

§15 ADR 引用清单（namespace prefixed）​

承接整改包 IV-1 audit_cross_section_consistency Rule 4：所有 ADR 引用必须带 <workstream>/ 前缀。

  • arch-rewrite/ADR-001 工程范式（accepted）
  • arch-rewrite/ADR-003 工程实施栈与协作（accepted，含 fresh-eyes 二阶 + AI 三方互审协议）
  • arch-rewrite/ADR-008 LLM Provider 接口（accepted）
  • arch-rewrite/ADR-010 凭证过滤位置（accepted）
  • arch-rewrite/ADR-013 codify 哲学换轨 Build-Y 优先（accepted，§0 强制正向产出章节的事实源）
  • arch-rewrite/MP-4 任务→字段动态组合契约（signed，§0.3 任务驱动字段组合）
  • arch-rewrite/MP-5 字段暴露面分层契约（signed，§0.3 字段暴露面分层）
  • whitepaper-rewrite/ADR-008 supplement 机制层输出契约扩展（accepted）
  • <本 milestone 新增引用的 ADR，带 namespace>

§16 演化路径​

时机本文档变化
M<N+1> 启动...
M<N+2> 启动...

§17 关联资产​

  • 上位整改方案：Step 11 整改包 II 详细方案
  • 主架构对应章节：architecture.md § / §
  • 上一 milestone 工程包：<m-...>.md
  • 下一 milestone 工程包：<m<N+1>-...>.md（待启动）

使用说明（模板维护者，不进实际工程包）​

本模板基于 M0 walking skeleton 工程包 提炼。新 milestone 工程包起草流程：

  1. 复制本模板到 engineering-packs/m<N>-<feature>.md
  2. 修改 frontmatter：status: draft、milestone: M<N>、blocking: <实际启动条件>
  3. 按 §1-§17 顺序填充实质内容
  4. 删除本"使用说明"段
  5. 加入 engineering-packs/README.md 已起草清单
  6. 跑 npm run verify:kb + npm run audit:cross-section
  7. 走 ADR-003 三方互审协议（P1 级）

最小工作量预估（基于 M0 实测 2052 行 / 91K chars）：1-2 周（含三方互审 + 用户回查）。

变更记录​

日期变更
2026-05-29新增 §0 Build-Y 正向产出 / Delivery contract 强制置顶章节（承接 ADR-013 §3.1）；§0.2 链回 goal-execution 三类正向机制；§0.3 承接 MP-4 / MP-5；schema_sources 补 tasks-fields-mapping / field-surface-mapping；§15 ADR 引用清单补 ADR-013 / MP-4 / MP-5