docs(spec): 重写 spec/ 与根 README 的语言与取舍

按新文风(简洁书面中文)重写 spec/ 全部 Lean doc 注释、spec/README,
并顺根 README。核心:讲清产品逻辑、去伪术语、去 ADR 黑话、DRY。

语言:砍钉死/留痕/实现侧/将就/脑补/刻意等伪术语;短句;不复述文件系统
能看到的东西;typst 考据移出 spec 指向 ADR。

内容取舍(动结构):
- System 层大改:删 can_mono 形式化定理、Capability 9 项枚举与
  requiredRole 映射、RunState 6 构造子;Audit.lean 删除并入 System 顶部。
  Hub 未建的部分一律 prose 占位,只留 Lock 的 owner=run 与 WellFormed。
- 澄清两个"检查":产品 checker(LLM 判不了合法性,checker 真跑工具补这块)
  vs 开发时 spec↔impl 一致性检查(无自动闸门)。Oracle 重新定位为
  "checker 得委托外部工具才能判的事实",不是"Lean 没写形式化"。
- spec/README 补取舍判据 checklist(自顶向下逐步细化、不在 Lean 里验证实现)。
- 根 README 去 DRY:删硬编码版本号、cache 路径细节;宪法第 3 条吸收
  "人/coding assistant 核对"修正;第 5 条与 spec/README 判据去重。

保留:Export/Render 执行语义、Info 的 raw→canonical 设计模式(产品语义,
只顺文风不砍结构);renderIgnoredSeverity(实现对齐依赖)。

lake build 通过(24 jobs)。

Co-Authored-By: Claude <noreply@anthropic.com>

spec/Spec/Courseware/Model/Element.lean

@@ -1,24 +1,23 @@
 import Spec.Courseware.Model.Primitives
 
 /-!
-# Element —— 课程内容的原子单位
+# Element —— 课程内容的最小单位
 
-ADR-0005:element 实例 = 一个 kind 标签 + 符合该 kind schema 的数据。本模块把它编码成
-依赖结构,使"数据必须匹配其 kind"成为类型层面的事实而非运行时校验。
+一个 element = 一个 kind 标签 + 符合该 kind schema 的数据(ADR-0005)。
+用依赖结构编码,使"数据必须匹配 kind"成为类型层面的事实,不是运行时校验。
 -/
 
 namespace Spec.Courseware
 
 variable (P : Primitives)
 
-/-- element 实例(`PINNED`, ADR-0005)。`data : P.ElementData kind` 由 `kind` 决定——
-无法构造数据与 kind 不符的 element,schema 合规由类型系统保证。ADR-0005 的 (a) 类
-字段(逐字稿、重点圈划)落在具体 kind 的 `ElementData` 内,不出现在此通用结构上;
-交互教具等"重型 kind"在此与例题、定理同构,仅 `kind` 不同,重实现在模型之外。 -/
+/-- 一个 element 实例(ADR-0005)。data 的类型由 kind 决定,所以没法造出数据和 kind
+    不符的 element——schema 合规由类型保证。逐字稿、重点圈划这类跟具体 kind 强相关
+    的字段,落在该 kind 的 ElementData 里,不放在这个通用结构上。 -/
 structure Element where
-  /-- 该 element 的 kind。 -/
+  /-- 这个 element 的 kind。 -/
   kind : P.KindId
-  /-- 符合 `kind` schema 的数据(类型随 `kind` 而变)。 -/
+  /-- 符合 kind schema 的数据,类型随 kind 变。 -/
   data : P.ElementData kind
 
 end Spec.Courseware

spec/Spec/Courseware/Model/Info.lean

@@ -1,56 +1,54 @@
 /-!
-# Info —— 课时元信息:canonical 模型 vs 撰写态(authoring surface)
+# Info —— 课时元信息:canonical 模型 vs 撰写态
 
-`[info]`(标题、作者)大多是 passthrough 元数据(ADR-0008),本不入契约。但**作者的
-基数**是一个真分歧点:一节课可由多人(教研组)署名,故 canonical 模型里 author 是一个
-**有序列表**,不是单值或可选单值。
+`[info]`(标题、作者)大多是 passthrough 元数据(ADR-0008),本不入契约。但作者的
+基数是一个真分歧点:一节课可由多人(教研组)署名,故 canonical 模型里 author 是一个
+有序列表,不是单值或可选单值。
 
-另有一条值得钉的模式:on-disk 的**撰写态**(用户实际填写的形态)是**语法糖**——单作者可写
-`author = "…"`,多作者写 `author = ["…", "…"]`——但这个"字符串或数组"的二态**只活在加载
-边界**:`RawInfo` 经归一化折叠成 canonical `Info`,其后不再出现。canonical 接收端始终是
-`List String`,raw 形式不泄漏进模型其余部分。这正是 `Info`(canonical)与 `RawInfo`
-(撰写态)两个结构存在的理由。
+另有一条值得钉的模式:on-disk 的撰写态(用户实际填写的形态)是语法糖——单作者可写
+`author = "…"`,多作者写 `author = ["…", "…"]`——但这个"字符串或数组"的二态只活在
+加载边界:`RawInfo` 经归一化折叠成 canonical `Info`,其后不再出现。canonical 接收端
+始终是 `List String`,raw 形式不泄漏进模型其余部分。这正是 `Info`(canonical)与
+`RawInfo`(撰写态)两个结构存在的理由。
 -/
 
 namespace Spec.Courseware
 
-/-- 作者的**撰写态形式**(`PINNED` 仅填写便利, ADR-0008)。on-disk 单作者可写裸
-字符串、多作者写数组——填写便利,非语义分歧。此 union **只活在加载边界**,经
-`RawAuthor.normalize` 折叠后不再出现。 -/
+/-- 作者的撰写态形式(ADR-0008)。on-disk 单作者可写裸字符串、多作者写数组——填写便利,
+    非语义分歧。此 union 只活在加载边界,经 `RawAuthor.normalize` 折叠后不再出现。 -/
 inductive RawAuthor where
   /-- 单作者裸字符串 `author = "…"`。 -/
   | one (name : String)
   /-- 多作者数组 `author = ["…", "…"]`。 -/
   | many (names : List String)
 
-/-- raw 作者归一化为**有序作者列表**(`PINNED`, ADR-0008)。单作者 ⇒ 单元素列表;数组
-⇒ 原样。这条钉死"canonical 接收端始终是 `List String`"。 -/
+/-- raw 作者归一化为有序作者列表(ADR-0008)。单作者 ⇒ 单元素列表;数组 ⇒ 原样。
+    这条钉"canonical 接收端始终是 `List String`"。 -/
 def RawAuthor.normalize : RawAuthor → List String
   | .one n => [n]
   | .many ns => ns
 
-/-- 课时元信息的 **canonical 模型**(`PINNED` author 为列表, ADR-0008)。`authors` 是
-**有序列表**:多人署名第一类,空列表 = 未署名。`title` 等其余字段是 passthrough 元数据,
-不在此承诺更多。这是系统其余部分唯一所见的形态——author 在此**已**是列表,不再是
-"字符串或数组"。 -/
+/-- 课时元信息的 canonical 模型(ADR-0008)。`authors` 是有序列表:多人署名第一类,
+    空列表 = 未署名。`title` 等其余字段是 passthrough 元数据,不在此承诺更多。这是系统
+    其余部分唯一所见的形态——author 在此已是列表,不再是"字符串或数组"。 -/
 structure Info where
   /-- 标题(passthrough 元数据)。 -/
   title : String
-  /-- 作者**有序列表**(空 = 未署名)。canonical 始终是列表。 -/
+  /-- 作者有序列表(空 = 未署名)。canonical 始终是列表。 -/
   authors : List String
 
-/-- 撰写态的 `[info]`(`PINNED` 仅填写便利, ADR-0008)。`author` 用 `RawAuthor`
-(字符串或数组),`author` 缺省即未署名。此结构刻画"为便于填写而存在的 raw 形态",
-**不**是模型其余部分流通的形式——它经 `RawInfo.toInfo` 归一化为 canonical `Info`。 -/
+/-- 撰写态的 `[info]`(ADR-0008)。`author` 用 `RawAuthor`(字符串或数组),缺省即未署名。
+    此结构刻画"为便于填写而存在的 raw 形态",不是模型其余部分流通的形式——它经
+    `RawInfo.toInfo` 归一化为 canonical `Info`。 -/
 structure RawInfo where
   /-- 标题。 -/
   title : String
   /-- 作者 raw 形式(可选;缺省即未署名)。 -/
   author : Option RawAuthor
 
-/-- raw `[info]` 归一化为 canonical `Info`(`PINNED` 加载边界归一化, ADR-0008)。缺省
-author ⇒ 空列表,否则按 `RawAuthor.normalize`。raw 的"字符串或数组"二态在此被消解,
-**不**泄漏进 `Info`——canonical 接收端恒为 `List String`。 -/
+/-- raw `[info]` 归一化为 canonical `Info`(ADR-0008)。缺省 author ⇒ 空列表,否则按
+    `RawAuthor.normalize`。raw 的"字符串或数组"二态在此被消解,不泄漏进 `Info`——
+    canonical 接收端恒为 `List String`。 -/
 def RawInfo.toInfo (r : RawInfo) : Info :=
   { title := r.title
     authors := (r.author.map RawAuthor.normalize).getD [] }

spec/Spec/Courseware/Model/Lesson.lean

@@ -3,14 +3,14 @@ import Spec.Courseware.Model.Element
 /-!
 # Lesson —— 单节课工程文件
 
-ADR-0005:一个工程文件 = 一节课,是 element 实例的**有序序列**。课程/单元不是工程
-文件,而是 lesson 的编排(见 `Spec.Courseware.Course`,OPEN)。
+一个工程文件 = 一节课,是 element 实例的有序序列(ADR-0005)。课程、单元不是工程文件,
+而是 lesson 的编排(见 `Spec.Courseware.Course`,OPEN)。
 -/
 
 namespace Spec.Courseware
 
-/-- 一节课(`PINNED`, ADR-0005)。用 `List` 因为 **element 次序承载教学语义**(先讲
-定义再举例 ≠ 反过来);**不建模时长**——ADR-0005 决定 lesson 是内容编排而非时间轴。 -/
+/-- 一节课(ADR-0005)。用 `List` 因为 element 的次序承载教学语义(先讲定义再举例, ≠ 反过来)。
+    不建模时长——lesson 是内容编排,不是时间轴(ADR-0005)。 -/
 abbrev Lesson (P : Primitives) := List (Element P)
 
 end Spec.Courseware

spec/Spec/Courseware/Model/Primitives.lean

@@ -1,34 +1,26 @@
 /-!
-# Primitives —— Courseware 契约的留白基元
+# 基元
 
-课程工程文件模型(ADR-0005)依赖一组基元:element kind 怎么标识、某 kind 的数据
-schema 是什么、export target 怎么标识。收口成载体 `Primitives`,让模型在其上参数化
-——契约谈得了 element / lesson / 渲染**之间的关系**,而把每个基元的**内部表示**留给
-实现。注意:某基元语义已 PINNED(如 schema 形态由 ADR-0006 钉死)与其表示进 Lean
-是两回事——JSON Schema / typst 的内部结构属实现细节,不入 Lean,故基元在此仍以抽象
-类型承载。富内容的 prose 母本见 `Courseware.RichContent`。
+课程模型要谈"element、lesson、target 之间的关系",但每个基元本身(element kind
+怎么标识、kind 的数据 schema 长什么样、target 怎么标识)的内部表示是实现的事。
+这里把它们收成一组抽象基元,让模型在它们之上参数化。
+
+契约只钉基元之间的关系;基元内部用什么表示,留给实现。
 -/
 
 namespace Spec.Courseware
 
-/-- Courseware 契约基元载体(关系 `PINNED`, ADR-0005;各基元表示留给实现, ADR-0006)。 -/
+/-- 课程模型的一组抽象基元:关系已定,内部表示留给实现(ADR-0005、ADR-0006)。 -/
 structure Primitives where
-  /-- element kind 标识(`PINNED` **开放宇宙**, ADR-0005;表示 `OPEN`)。刻意用抽象
-      类型而非 `inductive`:ADR-0005 决定 kind 是开放可扩展宇宙(stdlib + 第三方),
-      封闭枚举会违背它——此处开放是**已决策的**(区别于 `RunState` 的"尚未封闭")。 -/
+  /-- element kind 的标识。kind 是开放宇宙:stdlib 加第三方都可加,不是封闭枚举
+      (ADR-0005)。表示方式留给实现。 -/
   KindId : Type
-  /-- 某 kind 的合法数据类型(`PINNED` 依赖关系, ADR-0005;schema 形态 `PINNED`
-      ADR-0006,表示仍抽象)。以 kind 为索引:`ElementData k` 即"符合 `k` schema 的
-      数据"。schema 形态(声明式 JSON Schema + `content` 叶子 = typst 源)是 ADR-0006
-      钉死的,但属 JSON/typst 内部结构、实现细节,不进 Lean;契约只锚定"数据符合
-      kind schema"这条关系,故此处仍是抽象类型。 -/
+  /-- 某 kind 的合法数据类型,以 kind 为索引:`ElementData k` 就是"符合 k 的 schema
+      的数据"。schema 用声明式 JSON Schema,带 content 叶子(ADR-0006);JSON Schema
+      的内部结构是实现细节,不进契约,契约只钉"数据要符合 kind 的 schema"这条关系。 -/
   ElementData : KindId → Type
-  /-- export target 标识(`PINNED` 角色, ADR-0005;表示 `OPEN`)。一个 target 是一次
-      build,产出对 lesson 的一种投影(讲义/教案/PPT/平台 archive…),见 `Render`。 -/
+  /-- export target 的标识。一个 target 是一次 build,产出对 lesson 的一种投影
+      (讲义、教案、PPT、平台归档等),见 Render。 -/
   TargetId : Type
 
--- 注:原 `RenderRule : Type` 已随 ADR-0011 移除。渲染的"how"不再是契约层 per-target
--- 载荷,而由 `Render.TargetSpec.steps` 里 `typstCompile` step 引用的**模板文件**承载;
--- 契约只保留覆盖声明 `TargetSpec.covers`(该 target 渲染哪些 kind),供种子诊断用。
-
 end Spec.Courseware

spec/Spec/Courseware/Model/RichContent.lean

@@ -1,44 +1,41 @@
 /-!
-# RichContent —— 富内容(ADR-0006 的 prose 母本)
+# 富内容
 
-ADR-0006:element schema 的"叶子"可以是 `content` 类型,其值是一段**源文本**,
-按其 **format** 决定语义(ADR-0015)。两种 format:
-- **typst** —— 一段 typst 源,语义取该源作为 module 求值后的 body content(讲义/教案面)。
-- **markdown** —— 一段**原样**的 markdown + KaTeX 源,**不经 typst 求值**(slides 大纲面 / 逐字稿口播面;
-  ADR-0015)。直接以 markdown 撰写**绕开** typst→markdown 的公式转换难题(ADR-0014 R2):公式一开始就是
-  KaTeX 源(`$…$`),没有"把 typst 公式转成 md"这一步。
+element schema 的叶子可以是 content 类型:一段源文本,按 format 决定语义
+(ADR-0006、ADR-0015)。
 
-关键约束(均 ADR-0006,源自 typst 源码事实):**typst** format 的富内容**不可无主**——typst 的源必须有
-`FileId`,否则 span 脱锚、相对 import 报"cannot access file system from here"。故每段 typst 富内容是 World 里
-的一等文件,坐落在一个**虚拟路径**上;相对 import 限本工程路径结构内 + `@package`(不跨工程)。markdown format
-的富内容不参与 typst 求值,但同样由一个虚拟路径定位(供 markdown 装配 step 按序读取,见 `Export/Render`)。
+两种 format:
 
-本模块只立 prose 锚点 + 最小抽象签名:typst 的 `Content`/`Module` 内部结构、JSON Schema 形状、format 的
-具体判别属实现细节,不进 Lean,只承诺"富内容由一个虚拟路径定位"+"叶子带 format"这两条关系。
+- typst:一段 typst 源,求值后得到讲义/教案用的内容。
+- markdown:一段 markdown + KaTeX 源,原样保留,不经 typst 求值(slides 大纲、
+  逐字稿口播)。直接用 markdown 写,公式一开始就是 KaTeX(`$…$`),绕开了
+  typst→markdown 的公式转换这个难题(ADR-0014)。
+
+约束:typst 内容必须挂在一个虚拟路径上(原因见 ADR-0006 的考据)。markdown 内容
+不经 typst 求值,但同样用虚拟路径定位,供 markdown 装配按序读取。
+
+本模块只钉两条关系:富内容由一个虚拟路径定位、叶子带 format。typst 的 Content/Module
+内部结构、JSON Schema 形状、format 怎么判别,都是实现细节,不进契约。
 -/
 
 namespace Spec.Courseware
 
-/-- 富内容在工程文件路径结构中的**虚拟路径**(`OPEN` 表示, ADR-0006)。把一段富内容
-定位为 World 里的一等文件(span 可解析、相对 import 可锚定)。落盘后即真实相对路径
-(ADR-0007),不在本层承诺,故 opaque。 -/
+/-- 富内容在工程文件里的虚拟路径(ADR-0006)。落盘后是真实相对路径(ADR-0007),
+    这层不承诺,所以 opaque。 -/
 opaque VPath : Type
 
-/-- 富内容的 **format**(`PINNED`, ADR-0015)。`content` 叶子带 format:typst 叶子被 typst 求值;
-markdown 叶子原样保留(markdown+KaTeX 源,不经求值)。 -/
+/-- 富内容的 format(ADR-0015)。 -/
 inductive ContentFormat where
-  /-- typst 源:求值为 typst `Content`(讲义/教案面)。 -/
+  /-- typst 源:求值后得到讲义/教案用的内容。 -/
   | typst
-  /-- markdown + KaTeX 源:原样保留,不经 typst 求值(slides 大纲面 / 逐字稿口播面;ADR-0015)。 -/
+  /-- markdown + KaTeX 源:原样保留,不经 typst 求值(slides、逐字稿)。 -/
   | markdown
 
-/-- 对一段富内容的**引用**:它坐落在某个虚拟路径上(`PINNED` 关系, ADR-0006),并带一个
-**format**(`PINNED`, ADR-0015)。刻意**不**建模源文本、不建模求值出的 `Content`(那是实现侧的事);
-只钉"富内容经由一个 `VPath` 定位 + 带 format",作为 `Primitives.ElementData` 里 `content` 叶子的语义锚点。 -/
+/-- 对一段富内容的引用:它挂在一个虚拟路径上(ADR-0006),带一个 format(ADR-0015)。
+    不建模源文本,也不建模求值出的内容——那是实现的事;这里只钉"富内容由虚拟路径定位
+    + 带 format",作为 ElementData 里 content 叶子的语义锚点。 -/
 structure RichContentRef where
-  /-- 该富内容所在的虚拟路径(ADR-0006;落盘后为真实相对路径, ADR-0007)。 -/
   vpath : VPath
-  /-- 该富内容的 format(ADR-0015)。 -/
   format : ContentFormat
 
 end Spec.Courseware