forked from bai/curriculum-project-hub
sjfhsjfh
c684d25d50
Spec母本噪音清理 + 一处 spec↔impl 对齐 + 一处契约自洽修正。 Part A — spec doc 瘦身:每条 doc 收到"语义点 + 标签 + ADR ref + 承载性 why", 把跨文件复读的方法论(element-kind 开放性对比、likec4 画不出、分歧点测试)上移到 module header。OPEN 框架保持清晰(RunState/Capability 完整性仍明示须 surface)。 Part B — Courseware/ 由 10 文件平铺重组为 Model/ Export/ Check/ Open/ 四子命名空间 (namespace Spec.Courseware 不变,零引用改动)+ 四个子 aggregator。lake build 绿(24 jobs)。 Part C — 渲染覆盖落为数据(ADR-0011 对齐):去掉 cph-check 里硬编码的 COVERED_TARGETS,改读 TargetConfig.covers。cph-model 新增 covers: Option<Vec<String>> (None=未声明,由 cph-check 默认为全部 known kinds;显式 [] 表示不覆盖任何 kind)。 新增 3 个覆盖行为测试。 ADR-0012 — DanglingReference 退役(诊断 7→6 类):其两种情形(未解析 @ref、越界/缺失 相对 import)都是 typst 编译期失败,归 typstCompile。同步移除 Oracle.refsResolve (被 compiles 蕴含),Legal 少一个合取项。impl 删去从未被发射的 DiagCode::DanglingReference, 闭合 named-but-unemitted 的 spec↔impl 缝。ADR-0010 加修订指针。 OPEN 点(RunState/Capability 完整性、QuestionBank、Course)按既定纪律保持 OPEN,本次 只改善其框架措辞,不决策。 验证:spec lake build 绿;cargo test 全绿(含新增覆盖测试);clippy 静默; TH-141 check 0 errors/0 warnings 无回归。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
spec —— Lean 语义母本
这是本 monorepo 的契约:产品各部件语义的上游参照,用 Lean 编写。它的定位与约束见仓库根 README.md 的"宪法"5 条——本文件只讲怎么往这份契约里写东西。
现状
刚初始化的 Lean 工程(lake init),目前只有占位内容(Spec/Basic.lean)。实质领域内容(System 平台层、Courseware 产品层)将逐个概念加入,每个都遵循下面的规范。
构建
cd spec
lake build
工具链锁定在 lean-toolchain(leanprover/lean4:v4.31.0)。无外部依赖——Mathlib / Batteries 等留待第一个真正需要它的定理出现时再引入(依赖碰到再加)。
写作规范
双半契约:prose + type
每个 top-level 声明必须带 /-- … -/ doc 注释,用自然语言陈述其语义意图。两半缺一不可:
- prose 半给人读——说清"这在领域里是什么、为什么"。
- type 半给机器读、给 type checker 把关——保证结构无洞。
agent 不得用预训练先验脑补本领域(领域很新,无先验);prose 是 agent 理解语义的唯一权威来源。
标签分类法
在 doc 注释里用以下标签标注每条语义的状态:
PINNED—— 已解决的分歧点,契约在此处权威,双方据此对齐。OPEN—— 故意未规定。双方均不得假设其解;实现遇到时必须 surface 出来讨论,而不是擅自决定。ADR-NNNN—— 链接到根docs/adr/下的对应决策记录(如ADR-0002),交代该语义的决策出处。
分歧点测试(写之前先过一遍)
新增任何概念前,先问:"不写明,开发者与 agent 会不会各自做出不同假设?"
- 会 → 它是分歧点,入契约。
- 不会(显然的东西 / 纯 plumbing / 普通 CRUD 字段)→ 不入。
详见根 README 宪法第 5 条。
不用 sorry
无法陈述清楚的东西,用 OPEN 在 prose 里标注,而不是用 sorry 留一个假装成立的定理。sorry 会让 lake build 仍然变绿,却在契约里埋一个谎——这与"契约自包含、无洞"直接冲突。
命名
- 模块 / 命名空间:PascalCase,对应分层,如
Spec.System.Run、Spec.Courseware.Validity。 - 类型:PascalCase。
- 谓词 /
Prop:用意图清晰的命名,如Legal…、ValidTransition、Can…。 - 文件粒度:原则上"一个带独立不变式的概念一个文件"。