harness：熵治理纳入 Swift 与文档链接（目标态设计阶段二 P8）

README.md

@@ -49,7 +49,7 @@ Key capabilities:
 
 ## Quick start
 
-A prebuilt Agent-Notification.dmg is available on the [Releases](../../releases) page (double-click and drag into Applications). To build from source, from the repository root:
+A prebuilt Agent-Notification.dmg is available on the [Releases](https://github.com/SnowsonZ/Agent-Notification/releases) page (double-click and drag into Applications). To build from source, from the repository root:
 
 ```sh
 python3 -m venv scratch/iterm-probe-venv

README.zh-CN.md

@@ -49,7 +49,7 @@ Agent Notification 是运行于 macOS 的本地会话收件箱：汇总 Codex、
 
 ## 快速上手
 
-已打包版本从 [Releases](../../releases) 下载 Agent-Notification.dmg（双击拖入「应用程序」即装）；从源码构建则克隆仓库后，在项目根目录执行：
+已打包版本从 [Releases](https://github.com/SnowsonZ/Agent-Notification/releases) 下载 Agent-Notification.dmg（双击拖入「应用程序」即装）；从源码构建则克隆仓库后，在项目根目录执行：
 
 ```sh
 python3 -m venv scratch/iterm-probe-venv

docs/plans/backlog.md

@@ -33,7 +33,6 @@
 | B18 | 下次实质修订调研报告时，在 Claude 编辑源补 METR 样本与时间视界版本、`pass^k` 在异质任务上的限定、自动合并下「无修改合并率」的口径，再重新导出快照 | 随报告下次修订 | 评审方 | Codex 复评「调研文章」部分 |
 | B23 | 停机演练：按规范 §8 停机 → R0 测试 PR 不被自动合并 → 恢复 → 重跑后被自动合并，结果记入规范 §6（步骤已在 P2 写入） | 进入无人值守前一次，之后每季度 | 用户演练，评审方记录 | 全链路审计 G4、1.5，设计第十七节 |
 | B27 | R2+ PR 增加独立上下文评审（另一个设计评审方按评审模板），先在 3 个 PR 上试行，再与用户判断对照校准 | 中；流程成本 | 评审方执行，用户决定是否长期保留 | 全链路审计 G5、2.4 |
-| B29 | 质量棘轮纳入 Swift 复杂度；加轻量的文档链接与状态新鲜度检查 | 小到中 | 评审方 | 全链路审计 G8、G10、3.2 |
 
 ## 3. 持续进行或暂缓
 
@@ -71,3 +70,4 @@
 | B3 | R1 自动合并后的抽样审计，改为机制：K3 按 PR 编号哈希三抽一，合并后自动开 audit 议题（`policy.py`、auto-merge） | 2026-09-28，PR #50（目标态设计阶段一 P2） |
 | B14 | R1 保持自动合并并加强判定（2026-09-28 决定 2）：签名不变、无新依赖与迁移、不超规模由 `r1_checks.py` 核对，变异不降由 build 的 harness job 核对，已有测试与黄金快照零改动沿用 risk.py | 2026-09-28，PR #50（目标态设计阶段一 P2） |
 | B22 | 任务书验收挂规格编号或写明不挂的原因（`harness/taskbook.py`，复用 `acceptance.py` 解析）；计划并入任务书「步骤与提交顺序」，删去「R2+ 先交计划」，计划模板归档 | 2026-09-28，PR #49（目标态设计阶段一 P1） |
+| B29 | 质量棘轮纳入 Swift（`quality.py`：超长文件、超长函数、嵌套过深函数只降不升）；`docs_check.py` 拦断链、报告陈旧状态，进 verify 默认档与完整档 | 2026-09-28，PR #62（目标态设计阶段二 P8） |

docs/plans/session-inbox.md

@@ -67,7 +67,7 @@ Stop 是停止阶段信号，其他 hook 可要求继续，因此不是任务成
 
 ### Pi / iTerm2
 
-本机包 `@earendil-works/pi-coding-agent` 0.85.1。[随包扩展文档](/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md)明确包含 session_start、sessionManager.getSessionId()、agent_end 和 agent_settled。优先 agent_settled，因为其语义包含没有待重试、压缩、后续轮次；仍须结合错误/中断状态，不能直接叫成功。
+本机包 `@earendil-works/pi-coding-agent` 0.85.1。随包扩展文档（包内 `docs/extensions.md`）明确包含 session_start、sessionManager.getSessionId()、agent_end 和 agent_settled。优先 agent_settled，因为其语义包含没有待重试、压缩、后续轮次；仍须结合错误/中断状态，不能直接叫成功。
 
 用原生 extension 上报事件，并登记当前 iTerm 会话；恢复/切换 Pi session 时更新映射。扩展目录和装载方式以当前版本实测为准。
 

docs/review/2026-09-27-harness-audit.md

@@ -50,7 +50,7 @@
 
 | 节点 | 当前实现 | 差距 | 可实现性 |
 |---|---|---|---|
-| 6.1 研究→计划→实现，人审前两步 | 规范要求 R2 及以上先按[计划模板](../templates/plan.md)写计划交评审 | **G9**：计划模板从未使用，仓库里没有一份计划；任务 003、004 为 R3 也没有计划。实际由任务书承担计划（任务 004 写死了三个提交的顺序），效果尚可 | 建议并入任务书而非强制单独计划（小） |
+| 6.1 研究→计划→实现，人审前两步 | 规范要求 R2 及以上先按[计划模板](../templates/archive/plan.md)写计划交评审 | **G9**：计划模板从未使用，仓库里没有一份计划；任务 003、004 为 R3 也没有计划。实际由任务书承担计划（任务 004 写死了三个提交的顺序），效果尚可 | 建议并入任务书而非强制单独计划（小） |
 | 6.2 一次只做一件事 | 一个任务一个 PR；PR 中位 66 行 | 无 | — |
 | 6.3 任务粒度 | 任务均在一次执行方运行内完成 | 运行时长没有记录 | 随度量处理 |
 | 6.4 确定性编排 + 智能体节点 | CI、风险判定、证据、自动合并全为确定性脚本；Agent 只做实现与评审 | 派发本身是手工命令，没有脚本 | 随 G1/G3 解决 |

docs/specs/delivery-harness.md

@@ -8,14 +8,15 @@ harness 只依赖 Python 标准库，放在仓库顶层 `harness/`，不进发
 
 | 命令 | 作用 | 谁在何时运行 |
 |---|---|---|
-| `bin/verify` | 工具版本、git 守卫、lint、仓库卫生、Python 测试、Swift 测试（仅 macOS） | 所有人；pre-push 自动运行 |
+| `bin/verify` | 工具版本、git 守卫、lint、仓库卫生、质量棘轮、文档链接、Python 测试、Swift 测试（仅 macOS） | 所有人；pre-push 自动运行 |
 | `bin/verify --quick` | 工具版本、lint、仓库卫生、验收映射、任务书准入 | pre-commit 自动运行 |
 | `bin/verify --full` | 默认档 + 事故回放 | macOS CI（`--strict --full`）；改动测试或产品逻辑后 |
 | `bin/verify --strict` | 被跳过的检查算失败 | macOS CI |
 | `python3 harness/acceptance.py [--manual]` | 规格验收编号 ↔ 测试映射检查；列出人工验收清单 | verify 各档；写 PR 的人工验收部分时 |
 | `python3 harness/taskbook.py [任务书 --on-main]` | 任务书准入：YAML 头部（类别、风险、设计方、规模、架构级、规格编号、预算、回滚）、类别与风险相容、验收每行挂规格编号、中大任务的必备章节、按「步骤与提交顺序」所列文件交叉核对；`--on-main` 另要求任务书已合并到 main（派发前） | verify 各档；派发前 |
 | `python3 harness/review_pack.py --base origin/main` | 评审证据包：风险等级、修复证据、verify、涉及的验收编号 | 评审方评审前 |
-| `python3 harness/quality.py [--update]` | 熵治理棘轮：复杂度超标函数数、超长文件数只降不升 | verify 默认档；每周 quality workflow |
+| `python3 harness/quality.py [--update]` | 熵治理棘轮：Python 复杂度超标函数数、超长文件数只降不升；Swift（`native/`，轻量解析）超过 500 行的文件数、函数体超过 60 行的函数数、大括号嵌套超过 6 层的函数数只降不升 | verify 默认档；每周 quality workflow |
+| `python3 harness/docs_check.py` | 文档熵治理：已跟踪的 README*.md、AGENTS.md、docs/、harness/README.md 中相对链接指向的文件必须存在（外链、纯锚点不查，`文件#锚点` 只查文件），断链即失败；「状态：」写着待执行、进行中、草案等且超过 30 天未提交的文档只报告 | verify 默认档与完整档 |
 | `python3 harness/metrics.py --base origin/main [--github]` | 交付度量：修复数、声称已修、修复带回放比例、新增测试、CI 轮次，并列 v0.8.0 基线 | CI harness job；试跑记录 |
 | `python3 harness/replay.py [--list]` | 把历史缺陷注入工作区副本，对应测试必须失败；列出基线覆盖 | `verify --full` |
 | `python3 harness/mutate.py [--check / --update]` | 定向变异测试，得分与 `harness/mutation-baseline.json` 比较（只升不降） | 每周 quality workflow；补测试后 |
@@ -158,6 +159,7 @@ Agent 层按角色接入：
 | 派发脚本（P4） | 单测（`tests/test_harness_dispatch.py`，假执行方与假 GitHub、真实临时 git 远端）：成功路径写运行记录、开 PR、主目录无改动、槽位归还；执行方环境无 GitHub 令牌；认领冲突与任务书不在 main 上时不运行执行方；超时、卡死、打转、澄清、停机各自升级；CI 失败带摘要重试、超预算打 `budget-exceeded`；槽位互斥与过期锁回收；守卫取自 origin/main，main 上的守卫失效时停止派发；Pi 参数与事件解析。2026-09-28 真实 Pi 实测 `-na -e` 的守卫加载与拦截 。2026-09-28 真实 K2 任务端到端（B21）：任务书 T005（PR #56，R0、K0）由 auto-merge 自动合并；`bin/dispatch` 派发 Pi（glm-5.3-flash）一轮完成、无重试、无守卫拒绝，执行约 12.6 分钟，派发脚本在执行方之外 verify 通过，运行记录与提示词随推送入库，PR #57 描述含运行记录摘要，CI 通过后按 R0、K2 自动合并（合并路由四条均写明理由）；主目录前后 git status 无改动；合并后在 main 独立重跑变异，`热力金额分级` 21/21，基线由 90% 升到 100%。发现槽位按启动目录命名（从设计方 worktree 启动得到 `…-sync-slot-1`），已改为按主工作目录命名 | ✅ 单测、守卫实测、真实任务端到端 |
 | CI 侧复核（P5） | 单测（`tests/test_harness_run_check.py`）：派发产生的 PR 通过；设计方分支不适用；带 `Task:` 的任意分支适用；缺记录、提交缺 `Task:`、记录 exit 非 ok、缺字段、task 或分支不符、提示词被改各被标出；以序号最大的记录为准；CI 轮次超预算或读不到时标出，同一提交的重跑不算新轮次；合并路由在缺记录与超预算时转用户、合格时自动合并。T005 的真实运行记录（PR #57）按同一口径合格 | ✅ 单测；首个经合并路由第 5 条判定的真实任务 PR 待下次派发 |
 | 周报与台账（P6） | 单测（`tests/test_harness_weekly.py`，GitHub 替身）：报告含 14.1 全部指标，缺数据标「样本不足」；PR、运行记录与议题算出的各项与手算一致；注入的突增数据在顶部标红，第一期不标、0→2 不标；历史往返跳过当周；试跑记录含历史任务与派发任务；发布时先建后改同一议题；创建标签不带 --force。2026-09-28 用真实数据预演一次（不发布） | ✅ 单测与真实数据预演；首次发布待合并后手动触发 quality |
+| 熵治理（P8） | 单测（`tests/test_harness_entropy.py`）：字符串（含多行、原始、转义）与注释（含嵌套块注释）里的大括号不计入；协议要求不算函数；人为加长的 Swift 函数（`test_lengthened_swift_function_fails_ratchet`）、加深嵌套与加长文件使棘轮失败，缩减通过；断链（相对、引用式、以 / 开头）被拦，外链、邮件、纯锚点、行内代码与代码块不误报，`文件#锚点` 缺文件仍拦；陈旧的未完成状态只报告不失败，近期的与正文顺带提到的不报。Swift 基线（2026-09-28，332 个函数）：`swift_files_over_500` 2、`swift_long_functions` 9、`swift_deep_functions` 13。首跑本仓库修正 4 处断链，陈旧状态无 | ✅ 单测；CI 以本 PR 为准 |
 | 验收映射 | 6 份规格 69 条编号：可自动化 54 条中 53 条有测试、1 条登记缺口，19 条进入人工清单；检查器在 verify 各档运行 | ✅ |
 | Swift 回放 | macOS CI `--strict --full`（run 36152060546）通过，Swift 注入在 strict 下不可跳过 | ✅ |
 | zcode 自检、质量棘轮、交付度量 | 本地实跑；zcode 自检与 CI 中的度量步骤随本 PR 首次在 CI 运行 | ⚠️ 待本 PR 的 CI |

harness/README.md

@@ -33,7 +33,7 @@
 | 5. 小批量、可回滚 | 一个任务一个 PR，按 R0–R3 分级；回滚方式写进任务书 |
 | 6. 状态外置、上下文从简 | 任务书（机器可读的 YAML 头部）与模板（`docs/templates/`）、[待办清单](../docs/plans/backlog.md)、决定记录；中断后从文件恢复 |
 | 7. 自治度按「任务类别 × 风险」 | `policy.py` 按 `autonomy.toml` 的类别自治等级与误差预算路由：满足条件的 R0/R1 由 App 批准后自动合并，超预算自动停该类，其余请用户评审；停机用 Disable workflow（规范 §8） |
-| 8. 每次失败都沉淀为 harness 改进 | 缺陷编号全局唯一，修复带 `Defect:` 与回归测试；`replay_cases.py` 事故回放集；变异与质量基线只升不降；每周周报与错误分析把异常沉淀为待办 |
+| 8. 每次失败都沉淀为 harness 改进 | 缺陷编号全局唯一，修复带 `Defect:` 与回归测试；`replay_cases.py` 事故回放集；变异与质量基线只升不降（质量含 Swift），文档断链由 `docs_check.py` 拦下；每周周报与错误分析把异常沉淀为待办 |
 
 ## 组成
 
@@ -48,7 +48,8 @@
 | `base_tests.py`、`base_tests_runner.py` | 已有测试按 base 版本在新代码上运行，防止执行方改测试迁就代码 |
 | `replay.py`、`replay_cases.py` | 事故回放：把历史缺陷注入代码副本，对应检查必须失败 |
 | `mutate.py`、`mutation-baseline.json` | 关键函数的变异测试，得分只升不降 |
-| `quality.py`、`quality-baseline.json` | 熵治理：复杂度与体量只降不升 |
+| `quality.py`、`quality-baseline.json` | 熵治理：Python 复杂度（ruff C901）与体量、Swift 超长文件、超长函数与嵌套过深函数（标准库轻量解析）只降不升 |
+| `docs_check.py` | 文档熵治理：已跟踪 Markdown 的相对链接断链即失败；未完成状态超过 30 天未更新的文档只报告 |
 | `hygiene.py` | 禁止提交的路径、超大文件、凭据、本机真实路径 |
 | `risk.py`、`r1_checks.py` | 按改动路径判定 R0–R3；任务书按头部类别判定，模板与待办清单为 R2；声明 R1 时另核对签名不变、无新依赖与迁移、不超规模 |
 | `policy.py`、`autonomy.toml` | 合并路由：风险、类别自治等级、误差预算、规模、任务 PR 的运行记录逐条判定并写理由；K3 三抽一抽审；放权只改 `autonomy.toml`（R3） |