feat(skills): 强化维护证据与高效摘要协议

skills/gitlink-cli-contract-guard/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: gitlink-cli-contract-guard
-version: 1.0.0
 description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命令契约，重点检查 flags 与默认值、命令层级与帮助文本、`--format json` 输出结构、错误提示与编码质量、README/示例命令和实际行为是否漂移。用于用户需要判断某个 PR 或本地改动会不会破坏旧用法、引入不兼容输出、造成帮助文档失真，或在合并前补做兼容性审查时。"
 metadata:
   requires:
@@ -20,6 +19,8 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
 
 本 Skill 只输出 `CG-` 契约问题；不把新增字段本身判为破坏性变化，也不替代代码质量、队列治理或集成门禁结论。
 
+针对 workflow v2 字段，必须验证 `--as-of`、`--stale-after-hours` 的默认值与非法输入错误；验证 `ci_summary`、`age_hours`、`waiting_on` 等字段在 JSON 中保持类型稳定且可选。旧调用不传新开关时应保持原行为，Markdown 的 SLA/CI 摘要不得泄漏到 JSON，且中文输出必须通过 UTF-8 与替换字符检查。
+
 # gitlink-cli-contract-guard
 
 **CRITICAL - 如果需要拉取 GitLink 上的 PR 元数据、diff 或评论，先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**

skills/gitlink-maintainer-radar/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: gitlink-maintainer-radar
-version: 1.0.0
 description: "维护者雷达：面向 GitLink 仓库维护者，联合扫描 open Pull Request、open Issue、消息提醒、review 分配和等待时长，识别响应超时、review 负载失衡、负责人长期停滞等协作瓶颈，生成按优先级排序的处置清单、催办建议和责任调整建议。用于用户需要值班巡检待办、判断哪些事项被晾着了、找出 reviewer 瓶颈、发现有负责人但无进展的条目，或生成维护者今日工作面板时。"
 metadata:
   requires:
@@ -19,6 +18,8 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
 
 本 Skill 只负责 SLA、Reviewer 负载、责任停滞和今日待办；`risk_changed` 是提醒信号，不直接宣称代码存在漏洞或阻断合并。
 
+队列项优先消费 `age_hours`、`waiting_hours`、`stale`、`review_state`、`reviewer_count` 和 `waiting_on`。同一 PR 的超 SLA、review 负载和责任停滞合并为一个 `MR-` 动作；`waiting_on=author` 才生成作者跟进，状态为空时只报告“责任未知”，不得误催 reviewer。`changes` 中的稳定项只保留计数，首屏最多列出 5 个动作。
+
 # gitlink-maintainer-radar
 
 **CRITICAL - 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，按其中的认证、全局参数和安全规则执行。**

skills/gitlink-pr-assessor/SKILL.md

@@ -12,6 +12,10 @@ description: "开源社区 Pull Request 队列评估与执行验证：面向 ope
 **CRITICAL — 不要在用户当前工作树上冒险覆盖代码。执行验证优先使用独立 worktree、临时目录或已明确指定的 PR 检出目录。**
 **CRITICAL — 在 Windows PowerShell 中生成或保存中文报告前，先切换到 UTF-8 输出链路；否则报告中的中文可能被写成 `?`。**
 
+## 增量证据的处理规则
+
+当审查上下文包含 `ci_summary` 时，只把 `matched` 构建纳入当前 PR 的声明验证；`match_mode=none` 或 `unavailable` 时将 CI 标为“证据不足”，不会因仓库其他分支失败而误报。队列快照中的 `stale`、`waiting_on` 和 `changes` 只用于解释维护优先级，不替代代码质量或安全结论。首屏最多保留 5 个动作，详细 diff、命令输出和未匹配构建放入证据附录。
+
 > 这个 Skill 是“评估引擎”，不是常驻监听进程。要实现社区里 open PR 自动审查，必须由 webhook、定时任务或 Agent runner 负责触发它。
 
 ### Windows 编码前置

skills/gitlink-pr-integrator/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: gitlink-pr-integrator
-version: 1.0.0
 description: 评估 GitLink Pull Request 是否已经具备集成到主线的条件，输出合并态验证、与其他 open PR 的冲突风险、集成影响面、发布与回移建议以及合并后动作清单。用于维护者需要决定某个 PR 是否可以进入 merge queue、为一批待合并 PR 排顺序、在合并前验证 rebase 或 merge 后是否仍能构建测试通过，或为自动化队列生成集成就绪报告时。
 metadata:
   requires:
@@ -18,6 +17,8 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
 
 本 Skill 只负责合并态、构建、测试、契约和发布影响，不代替代码审查。已有队列快照时可读取前置 PR #427 的 `changes`，但它只能辅助排序，不能跳过本地验证。
 
+CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能作为回退；`matched=0` 时 CI 为 `not_run`，不能给出 `ready_to_merge`。只要匹配构建中存在 `failed`，集成结论至少为 `action_required`；`unmatched` 构建只进入限制说明。队列的 `waiting_on` 仅用于安排下一动作，不改变合并门禁。
+
 # gitlink-pr-integrator
 
 **CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**

skills/gitlink-pr-topology/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: gitlink-pr-topology
-version: 1.0.0
 description: "开源社区 PR 队列关系图谱：面向一个仓库的多条 open Pull Request，识别它们之间的依赖链、功能重叠、替代/超越关系、冲突热点、可打包评审分组和建议处理顺序。用于维护者需要批量梳理 open PR 为什么互相卡住、哪几条其实在做同一件事、哪一条实现更完整、哪些 PR 应该先合并或先关闭，以及如何把复杂队列整理成可执行决策时。"
 metadata:
   requires:
@@ -19,6 +18,8 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
 
 本 Skill 只输出 `TP-` 关系、证据、置信度和处理顺序，不把队列变化直接解释为代码缺陷，也不替代 `gitlink-code-review` 和 `gitlink-pr-integrator` 的结论。
 
+队列差异应先按 `new`、`resolved` 和排名/优先级变化缩小候选集，再对候选 PR 比较文件、命令入口和输出字段。`stale` 或 `waiting_on` 是维护协作信号，不构成功能继承或重叠证据；只有存在文件、API、分支或正文证据时，才能输出 `depends_on`、`overlaps` 或 `supersedes`。
+
 # gitlink-pr-topology
 
 **CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**

skills/gitlink-shared/SKILL.md

@@ -10,6 +10,8 @@ metadata:
 
 五个维护 Skill 的证据复用和职责边界见 [`references/maintenance-evidence-workflow.md`](references/maintenance-evidence-workflow.md)。前置 PR #426 提供单 PR 证据包，前置 PR #427 提供队列快照差异；二者只提供只读基础数据，不合并五个 Skill 的职责。
 
+可直接照着 [`examples/maintenance-evidence-v2.md`](examples/maintenance-evidence-v2.md) 演示一次固定时间点的队列扫描、单 PR CI 证据关联和五个 Skill 的最短交接路径。
+
 # gitlink-cli 共享规则
 
 维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)，五个维护 Skill 的核心职责、允许重叠范围和交接见 [`references/skill-scope-and-handoff.md`](references/skill-scope-and-handoff.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。

skills/gitlink-shared/examples/maintenance-evidence-v2.md

@@ -0,0 +1,51 @@
+# 维护证据 v2 使用示例
+
+这个示例展示一次扫描如何被五个 Skill 复用，而不是让每个 Skill 重复请求接口或输出整份原始数据。
+
+## 1. 固定证据时间点
+
+```powershell
+$asOf = "2026-07-20T12:00:00Z"
+gitlink-cli workflow +review-queue `
+  --owner Gitlink --repo gitlink-cli `
+  --as-of $asOf --stale-after-hours 72 `
+  --format json > queue-current.json
+```
+
+如果要比较上一轮，把 `queue-current.json` 作为下一轮的 `--previous` 输入。队列首屏只保留新增、优先级变化、风险变化和超 SLA 项，稳定项保留数量。
+
+## 2. 获取单条 PR 证据
+
+```powershell
+gitlink-cli workflow +review-context `
+  --owner Gitlink --repo gitlink-cli --number 123 `
+  --include-commits=true --include-ci=true `
+  --format json > pr-123-context.json
+```
+
+审查 `ci_summary` 时遵循以下判定：
+
+- `match_mode=sha`：优先级最高，只统计当前 PR head SHA 对应的构建。
+- `match_mode=branch`：仅在没有可用 SHA 匹配时接受，并在报告中降低置信度。
+- `matched=0` 或 `match_mode=none/unavailable`：CI 为 `not_run`，不能写成通过。
+- `unmatched`：只表示本次列表中未关联的构建，不是失败数。
+
+## 3. 五个 Skill 的最短交接
+
+| Skill | 首先读取 | 产生的动作 |
+|---|---|---|
+| `gitlink-pr-assessor` | `files`、`reviews`、`ci_summary`、`notes` | `CR-` 代码、测试和安全发现 |
+| `gitlink-pr-integrator` | `ci_summary`、本地验证、`changes` | `IN-` 集成门禁 |
+| `gitlink-pr-topology` | `changes`、候选 PR 的文件和分支 | `TP-` 依赖与重叠关系 |
+| `gitlink-maintainer-radar` | `waiting_hours`、`stale`、`waiting_on`、reviewer 数量 | `MR-` 今日待办 |
+| `gitlink-cli-contract-guard` | `--help`、可选 JSON 字段、错误输出 | `CG-` 契约问题 |
+
+组合报告只在首屏展示最多 5 个动作，原始响应、完整 diff、未匹配构建和未执行项放入附录。任何 Skill 单独运行时，都必须把未纳入的其他维度标为“未检查”。
+
+## 4. 最小自检
+
+```powershell
+$json = Get-Content -Raw -Encoding utf8 .\pr-123-context.json | ConvertFrom-Json
+if ($null -eq $json.sections) { throw "missing sections" }
+if ($json.ci_summary.match_mode -in @("none", "unavailable")) { Write-Output "CI not_run/partial" }
+```

skills/gitlink-shared/references/maintenance-evidence-workflow.md

@@ -15,6 +15,10 @@ gitlink-cli workflow +review-context \
 
 证据包包含仓库信息、PR 详情、变更文件、Reviews、提交记录和 CI 构建结果。所有集合都有上限；某个探针失败时检查 `notes` 和 `sections`，不能把缺失数据写成“通过”。已有调用不传新增开关时保持原行为。
 
+### CI 关联规则
+
+当结果包含 `ci_summary` 时，优先使用 `match_mode=sha` 的提交匹配；只有 PR 没有可用 head SHA 或 SHA 无匹配时，才接受 `match_mode=branch`。`passed`、`failed`、`pending` 和 `unknown` 只统计已匹配构建，`unmatched` 不能被当作失败或通过。`match_mode=none`、`unavailable` 或 `sections` 缺少 `ci_builds` 时，相关结论必须标为 `not_run`/`partial`。
+
 ## 队列变化快照
 
 前置 PR #427 合并后，先保存 JSON 基线，再在下一轮比较：
@@ -30,6 +34,10 @@ gitlink-cli workflow +review-queue \
 
 `changes` 只表达队列事实：`new`、`resolved`、`priority_changed`、`risk_changed` 和 `unchanged`。它不替代代码审查、集成门禁或维护者判断。无 PR 编号的本地输入只能按规范化标题匹配，报告必须降低置信度。
 
+### 等待与责任字段
+
+使用 `--as-of <RFC3339>` 固定报告时点，使用 `--stale-after-hours <hours>` 设置仓库 SLA。队列项的 `age_hours`、`waiting_hours`、`stale`、`review_state`、`reviewers`、`reviewer_count` 和 `waiting_on` 用于生成维护动作；`waiting_on` 只有在 review 状态明确时才归属 `author`、`reviewer` 或 `maintainer`，未知状态必须保留为空。
+
 ## 五个 Skill 的消费边界
 
 | Skill | 使用单 PR 证据 | 使用队列变化 | 最终只负责什么 |
@@ -46,4 +54,4 @@ gitlink-cli workflow +review-queue \
 2. 单独运行某个 Skill 时只读取它需要的字段，并把其他维度标记为未纳入本次检查。
 3. 组合运行时允许共享事实和安全信号，但发现编号必须保留各自前缀：`CR-`、`IN-`、`TP-`、`MR-`、`CG-`。
 4. 同一事实可以被多个 Skill 引用，但只能由负责该维度的 Skill 生成最终动作；例如 CI 失败可以被代码审查引用，却只能由集成 Skill 决定是否形成合并阻断。
-5. 任何探针失败或快照缺失都输出 `not_run`/`partial`，不能用默认值填充成功结论。
+5. 任何探针失败、CI 未匹配或快照缺失都输出 `not_run`/`partial`，不能用默认值填充成功结论。

skills/gitlink-shared/references/maintenance-report-contract.md

@@ -10,6 +10,12 @@
 2. **今日动作**：最多 5 项，按优先级排序；每项必须包含对象、责任方、下一动作和证据引用。
 3. **证据附录**：完整发现、命令输出摘要、文件/行号、时间戳和未验证项。
 
+## 增量信号的首屏规则
+
+- CI 首屏显示“匹配数/总数、匹配方式、失败数、未匹配数”；没有 SHA 或分支匹配时显示“未关联”，不能把仓库其他构建的失败计入当前 PR。
+- 队列首屏显示“新增、已解决、优先级变化、风险变化、超 SLA 数量”；稳定项只保留计数。
+- 每项动作最多引用一个主证据和一个责任方，更多原始字段放到 JSON 或附录，避免维护者重复阅读。
+
 不要在首屏输出原始 API 响应、完整 diff、所有通知或所有 PR 两两比较结果。需要保留时放入附录或 JSON。
 
 ## 统一决策字段