refactor(spec): clean prose patterns across all modules

Remove filler/redundant patterns: 钉死/钉, 本模块, likec4 画不出/画得出, 臆造, 散文, 分歧点测试, 纯 plumbing, 恰好, 留白, 宪法第N条, 刻意. No code definitions changed, only doc comments.
2026-07-13 11:26:23 +08:00
parent 3fa6a5a5a5
commit 3ebe4b754d
28 changed files with 116 additions and 139 deletions
@@ -6,7 +6,7 @@ import Spec.Courseware.Export.Render

 产品里"站在 Lean 位置"的 rule-based checker,语义在此沉淀(ADR-0010,经 ADR-0012
 修订)。它对 lesson 提诊断,每条有**分类**(`DiagKind`)与**严重级别**(`Severity`)。
-本模块:钉级别类型(二分);钉 7 类诊断各自的含义与级别,并把"**合法 lesson = 无
+定级别类型(二分);定 7 类诊断各自的含义与级别,并把"**合法 lesson = 无
 error 级诊断**"建成判定(ADR-0005 deferred 的"完整合法判定"的回填);对**模型外设施**
 型诊断(typst 编过否、数据合 schema 否)用**抽象谓词 + `Oracle` 实现边界**表示——契约
 说"存在这条诊断、什么意思、什么级别",真值由实现提供,不在 Lean 内计算(不内嵌 typst
@@ -50,7 +50,7 @@ inductive DiagKind where

 /-- 每类诊断的**严重级别**(`PINNED`, ADR-0010)。六类 `error`(阻断);**唯
 `renderIgnored` 为 `warning`**——ADR-0005 种子规则"缺渲染 ⇒ warning,不阻断导出"。
-钉成全函数使"哪类阻断"成为可引用、可对齐的事实(实现侧 `DiagCode` 级别据此对齐)。 -/
+全函数使"哪类阻断"成为可引用、可对齐的事实(实现侧 `DiagCode` 级别据此对齐)。 -/
 def DiagKind.severity : DiagKind → Severity
  | .partPathMissing    => .error
  | .unknownKind        => .error
@@ -5,8 +5,8 @@ import Spec.Courseware.Check.Diagnostic

 checker 的 `check` 按**固定顺序**跑五个阶段,逐阶段收集诊断;`compile` 阶段有**门控**。
 顺序与门控是契约——它决定用户看到哪些诊断(藏在缺文件背后的语法错,在文件补齐前不
-显示,这是有意的)。每阶段的**算法**不进 Lean(宪法第 5 条深度上限):只钉**阶段、序、
-门控**。阶段对应上游模块:`load`←`cph-model`;`structural`←part 路径/未知 kind;
+显示,这是有意的)。每阶段的**算法**不进 Lean(深度上限:只定**阶段、序、
+门控**)。阶段对应上游模块:`load`←`cph-model`;`structural`←part 路径/未知 kind;
 `schema`←`cph-schema`;`compile`←`cph-typst`(模型外设施);`coverage`←`renderIgnored`。
 -/

@@ -2,7 +2,7 @@
 # Artifact —— export target 的产物(ADR-0009 / 0011)

 ADR-0009:一个 export target 是**一次 build**,产出一个**有类型的产物**。ADR-0011
-钉死:产物是**带字段的 ADT**——"产物到底指什么"(单文件落在哪 / 一棵树产出哪些文件)
+固定:产物是**带字段的 ADT**——"产物到底指什么"(单文件落在哪 / 一棵树产出哪些文件)
 是不好猜的领域语义,必须写进字段 + doc,而非抹成两个空构造子。路径/glob 用 `String`
 承载并由 doc 赋义(它们就是文本),不复刻文件系统类型。
 -/
@@ -4,7 +4,7 @@ import Spec.Courseware.Export.Artifact
 /-!
 # Render —— export target = artifact + 有序 typed steps(ADR-0009 / 0011)

-ADR-0009:export target 是一次 build,产出一个有类型的 `Artifact`。ADR-0011 钉死 build
+ADR-0009:export target 是一次 build,产出一个有类型的 `Artifact`。ADR-0011 固定 build
 的**形状**:一个 target 是 `artifact` + 一串**有序 typed step**。

 - `typstCompile template` —— 把**模板文件**(如 `exports/student.typ`)编译成产物。它是
@@ -20,7 +20,7 @@ ADR-0009:export target 是一次 build,产出一个有类型的 `Artifact`。ADR

 **shell step 的执行语义(ADR-0013)。** `shell` 不再只是占位:它**会被执行**,语义是把
 `run` 交给平台 shell、以**工程根为工作目录**运行,产物由被调外部工具自己写出(框架不装配
-内容)。三条边界是真分歧点,故钉契约:
+内容)。三条边界是真分歧点,故定为契约:
 1. **opt-in by construction** —— 任意命令执行只在用户**显式** build 一个 shell target 时发生,
   绝不在 `check` 里跑。`check` 只校验结构(lesson 是否合法),不执行外部工具、不验其产物。
 2. **失败归属** —— shell step 退出非零是一次 **build-过程失败**,不是 lesson 的合法性缺陷;
@@ -46,7 +46,7 @@ namespace Spec.Courseware
 variable (P : Primitives)

 /-- 一个 build **step**(`PINNED` typed, ADR-0011;可扩展)。MVP 仅一个 `typstCompile`;
-`steps` 是 list 因为 FileTree / 第三方 build 会需多步。刻意不把模板内部、shell 命令的
+`steps` 是 list 因为 FileTree / 第三方 build 会需多步。不把模板内部、shell 命令的
 解析结构写进来(实现细节, ADR-0011 OPEN)。 -/
 inductive Step where
  /-- 编译模板文件 `template`(相对工程根)成产物;框架注入 manifest。typed 的理由:
@@ -7,7 +7,7 @@ import Spec.Courseware.Model.Info
 /-!
 # Courseware.Model —— 工程文件的内容模型

-留白基元(`Primitives`)、富内容锚点(`RichContent`)、原子单位(`Element`)、单节课
+基元(`Primitives`)、富内容锚点(`RichContent`)、原子单位(`Element`)、单节课
 (`Lesson`)、课时元信息(`Info`:canonical author 为列表 vs `RawInfo` 撰写态)。
 决策出处 ADR-0005 / 0006 / 0008。
 -/
@@ -3,7 +3,7 @@ import Spec.Courseware.Model.Primitives
 /-!
 # Element —— 课程内容的原子单位

-ADR-0005:element 实例 = 一个 kind 标签 + 符合该 kind schema 的数据。本模块把它编码成
+ADR-0005:element 实例 = 一个 kind 标签 + 符合该 kind schema 的数据。把它编码成
 依赖结构,使"数据必须匹配其 kind"成为类型层面的事实而非运行时校验。
 -/

@@ -5,7 +5,7 @@
 基数**是一个真分歧点:一节课可由多人(教研组)署名,故 canonical 模型里 author 是一个
 **有序列表**,不是单值或可选单值。

-另有一条值得钉的模式:on-disk 的**撰写态**(用户实际填写的形态)是**语法糖**——单作者可写
+另一条模式:on-disk 的**撰写态**(用户实际填写的形态)是**语法糖**——单作者可写
 `author = "…"`,多作者写 `author = ["…", "…"]`——但这个"字符串或数组"的二态**只活在加载
 边界**:`RawInfo` 经归一化折叠成 canonical `Info`,其后不再出现。canonical 接收端始终是
 `List String`,raw 形式不泄漏进模型其余部分。这正是 `Info`(canonical)与 `RawInfo`
@@ -24,7 +24,7 @@ inductive RawAuthor where
  | many (names : List String)

 /-- raw 作者归一化为**有序作者列表**(`PINNED`, ADR-0008)。单作者 ⇒ 单元素列表;数组
-⇒ 原样。这条钉死"canonical 接收端始终是 `List String`"。 -/
+⇒ 原样。canonical 接收端始终是 `List String`。 -/
 def RawAuthor.normalize : RawAuthor → List String
  | .one n => [n]
  | .many ns => ns
@@ -1,26 +1,26 @@
 /-!
-# Primitives —— Courseware 契约的留白基元
+# Primitives —— Courseware 契约的基元

 课程工程文件模型(ADR-0005)依赖一组基元:element kind 怎么标识、某 kind 的数据
 schema 是什么、export target 怎么标识。收口成载体 `Primitives`,让模型在其上参数化
 ——契约谈得了 element / lesson / 渲染**之间的关系**,而把每个基元的**内部表示**留给
-实现。注意:某基元语义已 PINNED(如 schema 形态由 ADR-0006 钉死)与其表示进 Lean
+实现。注意:某基元语义已 PINNED(如 schema 形态由 ADR-0006 固定)与其表示进 Lean
 是两回事——JSON Schema / typst 的内部结构属实现细节,不入 Lean,故基元在此仍以抽象
-类型承载。富内容的 prose 母本见 `Courseware.RichContent`。
+类型承载。富内容的母本见 `Courseware.RichContent`。
 -/

 namespace Spec.Courseware

 /-- Courseware 契约基元载体(关系 `PINNED`, ADR-0005;各基元表示留给实现, ADR-0006)。 -/
 structure Primitives where
-  /-- element kind 标识(`PINNED` **开放宇宙**, ADR-0005;表示 `OPEN`)。刻意用抽象
+  /-- element kind 标识(`PINNED` **开放宇宙**, ADR-0005;表示 `OPEN`)。用抽象
      类型而非 `inductive`:ADR-0005 决定 kind 是开放可扩展宇宙(stdlib + 第三方),
      封闭枚举会违背它——此处开放是**已决策的**(区别于 `RunState` 的"尚未封闭")。 -/
  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;契约只锚定"数据符合
+      数据"。schema 形态(声明式 JSON Schema + `content` 叶子 = typst 源)由 ADR-0006
+      固定,但属 JSON/typst 内部结构、实现细节,不进 Lean;契约只锚定"数据符合
      kind schema"这条关系,故此处仍是抽象类型。 -/
  ElementData : KindId → Type
  /-- export target 标识(`PINNED` 角色, ADR-0005;表示 `OPEN`)。一个 target 是一次
@@ -1,5 +1,5 @@
 /-!
-# RichContent —— 富内容(ADR-0006 的 prose 母本)
+# RichContent —— 富内容(ADR-0006 的母本)

 ADR-0006:element schema 的"叶子"可以是 `content` 类型,其值是一段**源文本**,
 按其 **format** 决定语义(ADR-0015)。两种 format:
@@ -13,7 +13,7 @@ ADR-0006:element schema 的"叶子"可以是 `content` 类型,其值是一段**
 的一等文件,坐落在一个**虚拟路径**上;相对 import 限本工程路径结构内 + `@package`(不跨工程)。markdown format
 的富内容不参与 typst 求值,但同样由一个虚拟路径定位(供 markdown 装配 step 按序读取,见 `Export/Render`)。

-本模块只立 prose 锚点 + 最小抽象签名:typst 的 `Content`/`Module` 内部结构、JSON Schema 形状、format 的
+只立锚点 + 最小抽象签名:typst 的 `Content`/`Module` 内部结构、JSON Schema 形状、format 的
 具体判别属实现细节,不进 Lean,只承诺"富内容由一个虚拟路径定位"+"叶子带 format"这两条关系。
 -/

@@ -33,8 +33,8 @@ inductive ContentFormat where
  | markdown

 /-- 对一段富内容的**引用**:它坐落在某个虚拟路径上(`PINNED` 关系, ADR-0006),并带一个
-**format**(`PINNED`, ADR-0015)。刻意**不**建模源文本、不建模求值出的 `Content`(那是实现侧的事);
-只钉"富内容经由一个 `VPath` 定位 + 带 format",作为 `Primitives.ElementData` 里 `content` 叶子的语义锚点。 -/
+**format**(`PINNED`, ADR-0015)。不建模源文本、不建模求值出的 `Content`(那是实现侧的事);
+"富内容经由一个 `VPath` 定位 + 带 format",作为 `Primitives.ElementData` 里 `content` 叶子的语义锚点。 -/
 structure RichContentRef where
  /-- 该富内容所在的虚拟路径(ADR-0006;落盘后为真实相对路径, ADR-0007)。 -/
  vpath : VPath
@@ -2,8 +2,8 @@ import Spec.Courseware.Open.QuestionBank
 import Spec.Courseware.Open.Course

 /-!
-# Courseware.Open —— 留白骨架(核心关系 OPEN)
+# Courseware.Open —— OPEN 骨架(核心关系)

 题库与 element 的关系(`QuestionBank`)、课程编排规则(`Course`)。两者均为已 surface
-但未决策的分歧点,按宪法第 2 条不臆造,待专门 ADR 落定。
+但未决策的 OPEN 分歧点,待专门 ADR 落定。
 -/
@@ -5,6 +5,6 @@ ADR-0005:工程文件的粒度是**单节课**;course / 单元**不是**工程
 **编排**。但"编排"的具体规则未决策:有序列表还是带层级(单元 → 课)的树?lesson 被
 引用还是被包含?跨 lesson 有无约束(目标覆盖、前后置)?这些都是 `OPEN`。

-按宪法第 2 条本模块**不臆造**编排结构——不建 `Course := List Lesson`(那会偷偷承诺
+此处不替它选解——不建 `Course := List Lesson`(那会偷偷承诺
 "扁平有序、无层级")。只在此 surface:课程编排待专门 ADR。本文件当前不引入任何承诺性声明。
 -/
@@ -5,6 +5,6 @@
 典型的可复用单元,lesson 会引用它。但**题库与 element 的关系尚未决策**,且用户明确
 指出"纯引用可能不够"——element 内联题目数据 / lesson 持指向题库条目的引用 / 两者并存?

-这是一个 `OPEN` 分歧点。按宪法第 2 条本模块**不替它选解**——不建 `QuestionRef` 也不建
+这是一个 `OPEN` 分歧点。此处不替它选解——不建 `QuestionRef` 也不建
 内联结构,只在此 surface。待专门 ADR 落定后再填。本文件当前不引入任何承诺性声明。
 -/