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>
This commit is contained in:
2026-06-25 03:22:59 +08:00
parent 4c697904e6
commit 73e9d258d6
24 changed files with 381 additions and 455 deletions
+9 -52
View File
@@ -1,66 +1,23 @@
import Spec.Prelude
/-!
# Permission —— 角色、能力与授权
# Permission —— 协作者角色
ADR-0004:权限走"飞书云文档式"——grant(`resource + principal + role`)与 settings
分离;role 取自封闭的 `read / edit / manage`,且 **read ⊂ edit ⊂ manage** 累积赋能;
强制释放锁是 **admin-only**,在 role 体系之外。本模块把这套结构与"高 role 含低
role 全部能力"的单调性钉死。
ADR-0004:权限走"飞书云文档式"——grant(resource + principal + role)与 settings 分离;
role 取自封闭的 read / edit / manage,且 read ⊂ edit ⊂ manage 累积赋能;强制释放锁是
admin-only,在 role 体系之外。
本模块钉角色三级与累积关系。具体哪些操作归哪级,见 ADR-0004,待业务反馈细化——所以这里
不钉操作枚举,也不钉"哪个能力要求哪个 role"的映射。
-/
namespace Spec.System
/-- 协作者角色(`PINNED` 封闭, ADR-0004 逐字 "roles are read, edit, or manage")。 -/
/-- 协作者角色(ADR-0004:read / edit / manage)。read edit manage,高 role 含低 role
全部能力。强制释放锁不在这套体系里,是 admin-only override,由平台另行判定。 -/
inductive Role where
| read
| edit
| manage
/-- 角色赋能层级(`PINNED` 序, ADR-0004 read⊂edit⊂manage 数值化)。仅服务于
`Role.le` 与能力推导,不对外承诺"层级就是 `Nat`"。 -/
def Role.level : Role Nat
| .read => 0
| .edit => 1
| .manage => 2
/-- 角色偏序:`r₁ ≤ r₂` 即 `r₁` 赋能不强于 `r₂`(`PINNED`, ADR-0004)。 -/
def Role.le (r₁ r₂ : Role) : Prop := r₁.level r₂.level
/-- 受 role 调控的操作能力(各项 `PINNED` 取自 ADR-0004;**枚举完整性 `OPEN`**——
这是 ADR 当前点名的能力,不保证穷尽,新增产品操作时可能扩)。注意 force-release
**不在此列**——它是 admin-only override,见 `RequiresAdmin`。 -/
inductive Capability where
| view
| discussComment
| editArtifact
| triggerAgent
| answerChoiceCard
| manageCollaborators
| projectSettings
| groupBinding
| normalCancel
/-- 某能力所**要求的最低角色**(`PINNED`, ADR-0004 各 role 能力展开)。授权判定
`Role.can` 据此定义,"谁能做什么"只有这一处真相。 -/
def Capability.requiredRole : Capability Role
| .view => .read
| .discussComment | .editArtifact | .triggerAgent | .answerChoiceCard => .edit
| .manageCollaborators | .projectSettings | .groupBinding | .normalCancel => .manage
/-- 角色 `r` **具备**能力 `c`(`PINNED`, ADR-0004)。定义为"`c` 的最低角色 ≤ `r`",
这一处同时编码了 read⊂edit⊂manage 的累积性。 -/
def Role.can (r : Role) (c : Capability) : Prop := c.requiredRole |>.le r
/-- **单调性**:`r₁ ≤ r₂` 且 `r₁` 能做 `c` ⇒ `r₂` 也能(`PINNED` 定理, ADR-0004 累积
赋能的形式化保证)。证明即偏序传递性,得益于 `can` 按"最低角色阈值"定义。 -/
theorem Role.can_mono {r₁ r₂ : Role} {c : Capability}
(h : r₁.le r₂) (hc : r₁.can c) : r₂.can c :=
Nat.le_trans hc h
/-- **强制释放锁**要求 admin,**在 role 体系之外**(`PINNED`, ADR-0004 admin-only
override)。即便 `manage` 也不经 `Role.can` 获得它,故它不是 `Capability` 而是独立
谓词;`isAdmin` 由平台另行判定(本层不建 admin 模型)。 -/
def RequiresAdmin (isAdmin : Prop) : Prop := isAdmin
end Spec.System