xinetzone/SpecWeave / .agents/skills/artifact-consistency-audit
artifact-consistency-audit
Verified当用户要求核验、复检或体检某份产物与其源文档、上游清单或规范之间的一致性时使用——触发词:'检查…的修复细节'、'复验'、'体检'、'核验一致性'、'覆盖率核对'、'引用是否忠实'、'有无遗漏'、'修补后复验'、'对照源文档检查'。必须提供五步核验法(基准重读→覆盖率机械比对→引用逐字回验→交叉引用可达→分级发现清单),产出 P0-P3 分级发现与结论,默认只报告不修改。不要用目视翻查代替机械比对——本Skill封装双向集合比对、逐字回验、修补自身回验三条纪律,专防漏检与'修补引入新事实风险'。
产物一致性核验 Skill
⚠️ 本Skill是门面层(L1)。L0 见 ONBOARDING.md;链接存在性检查委托
check-links.py,不重复实现。
1. Skill ID
artifact-consistency-audit(对外名称:产物一致性核验 / Artifact Consistency Audit)
2. 功能描述
核验「派生产物 ↔ 源文档/上游清单/规范」的一致性,回答四个问题:有没有漏?引用忠不忠实?指向对不对?体例一致吗?
| 步 | 名称 | 产出 |
|---|---|---|
| S1 | 基准重读 | 从磁盘重读双方原文(禁用记忆与会话摘要) |
| S2 | 覆盖率机械比对 | 双向集合比对结论(源 N 条 ↔ 产物 M 条,含幽灵项/缺失项) |
| S3 | 引用逐字回验 | 每条引文与源文对照结论(含引号、限定词、层级) |
| S4 | 交叉引用可达 | 章节号/文件名/锚点指向核验结论 |
| S5 | 分级发现清单 | P0–P3 发现 + 结论 + 可选修复建议 |
为什么必须机械比对而不能目视? 目视核验的漏检率随产物规模非线性上升,且漏检不可自知——你以为看完了。正则提取 ID 集合并做双向集合比对,把「有没有漏」从判断问题降级为计算问题,结论可复算、可复核。
为什么基准必须从磁盘重读? 会话摘要与上下文压缩会截断或过期,被核验文本若取自摘要,核验的是记忆而非事实。基准只能是磁盘原文。
3. 何时使用本技能
| 层级 | 触发词 | 行为 |
|---|---|---|
| T2(强·直接执行) | "核验一致性"、"复验修复细节"、"体检"、"检查有无遗漏"、"对照源文档检查" | 直接进入五步核验法 |
| T1(中·确认后执行) | "覆盖率核对"、"引用是否忠实"、"修补后复验"、"体例一致吗" | 确认核验范围后执行 |
| T0(弱·仅提示) | "一致性"、"核验"、"检查一下" | 先确认被核验对象与基准,再决定是否进入本流程 |
适用:派生产物(报告/清单/摘要/视图)与其源文档的一致性;修补提交后的复验;跨文件体例一致性。
不适用:链接存在性单点检查(用 link-check-cmd)、代码重复检查(用 check-duplication-cmd)、提交前流水线(用 ci-check-cmd)、从零评审一份无基准的文档。
4. 方案选择决策
被核验对象是什么?
├─ 单份产物 ↔ 单份源文档(覆盖率 + 忠实度)? → 方案 A:标准五步(S1→S5)
├─ 刚做完修补,需复验修补本身? → 方案 B:修补后复验(S1→S5 + S3 强化"修补自身回验")
├─ 一组产物 ↔ 多个源/规范(跨文件体例)? → 方案 C:全量集审计(先建基准台账,再逐对核验)
└─ 仅想确认某引用是否可达/存在? → 不适用本Skill,转 link-check-cmd
5. 核心步骤
S1 基准重读(零记忆)
- 用 Read/Grep 从磁盘重读双方原文:被核验产物 + 其声明的源(源文档、上游清单、规范条款)
- 记录双方路径与行号;若产物声明了"唯一事实来源",把它作为比对基准
S2 覆盖率机械比对(双向)
- 对源与产物分别用正则提取结构化标识(编号 ID、条目标题、表行),得到两个集合
- 双向比对:源有产物无 = 缺失;产物有源无 = 幽灵项;两侧计数须与文档自称的数字自洽
- 禁止抽样;全量提取
S3 引用逐字回验
- 逐条把产物中的引文(引号内文本、F 编号引用、口径短语)与源文对照,检查:逐字一致 / 限定词未夸大 / 层级未拔高
- 修补自身回验(方案 B 必做):本次修补新引入的引用同样要回验其是否真被源支撑——修补本身可能引入新的事实风险
为什么修补后要回验修补自身? 修补的动因是"某处缺引用",补引用时的直觉是"这条应该支持"——恰是最容易想当然的一步。补引后必须回源核对原文标注,才能判定修补无风险。
S4 交叉引用可达
- 核验章节号引用("§五"是否真指该内容)、文件引用、锚点引用
- 链接目标存在性委托
python .agents/scripts/check-links.py --path <目录>,本Skill不重复实现 - 溯源完整性可用
check-source-traceability.py(source 字段 → 派生产物反向索引)
S5 分级发现清单与结论
| 级别 | 判据 |
|---|---|
| P0 | 结论性错误(引用与源矛盾、覆盖缺失导致结论不成立) |
| P1 | 重大遗漏(关键条目缺失、引用指向错误章节) |
| P2 | 承诺未兑现(声明的"链接处"不存在、声明的口径与实际不符) |
| P3 | 体例/引用形式不一致(纯文本引用 vs 链接、编号未随附) |
- 输出结构:检查范围与方法 → 逐项核验证据 → 发现清单 → 结论
- 默认只报告不修改;修复须另获授权,且修复后回到 S1 复验
为什么发现要分级而不是列流水账? 未分级的清单把"引用形式不一致"和"结论不成立"并列,读者无法决定是否放行。分级把清单变成决策依据。
6. 质量门
- G1:S1 基准全部来自磁盘原文,无一条取自记忆或摘要
- G2:S2 为双向集合比对且全量,无抽样
- G3:每条发现均附磁盘证据(文件 + 行号 + 原文片段)
- G4:结论级别与发现级别一致(无 P0/P1 时不得使用"完全正确"等绝对表述)
7. 安全检查清单
- 只读承诺:核验全程零写入(等价 dry-run);如需修复,先取得授权再单独执行
- 幂等:重复执行同一核验,结论一致(时间/提交号类锚点除外)
- 不擅改:发现缺陷只报告,不顺手修(修复范围须由用户批准)
- 不越界:链接存在性转
link-check-cmd,代码重复转check-duplication-cmd - 同轴证据:结论锚定与宣称同轴的证据(宣称"内容一致"就用内容比对,不用"文件存在"代替)
- 合并后存活:核验对象若在版本控制中,确认目标提交仍为当前 HEAD 祖先
8. 执行日志(CMD-LOG)
按 CMD-LOG规范 输出:
cmd=artifact-consistency-audit,session 前缀sc-YYYYMMDD-<topic>- 事件:
AUDIT_STARTED、BASELINE_RELOADED、COVERAGE_COMPARED、CITATION_VERIFIED、FINDINGS_REPORTED - 覆盖率比对结果(N↔M)必须落日志,作为可复算证据
9. Gotchas(陷阱与反直觉行为)
- 用记忆当基准:最隐蔽的失效模式——摘要里的"已完成"会被当作事实核验,得出全绿假象
- 只看产物不看源:单向比对查不出幽灵项;必须双向
- 只核验被修补处:修补会引入新引用,新引用也要回验(方案 B 的意义)
- 逻辑轴冒充物理轴:以"文件存在""目录大小为零"推断"内容正确""已清理",两轴之间隔着未建模的环节
- 发现即动手:核验与修复是两次授权;混在一起会让核验结论失去独立性
- 抽样代替全量:抽样在小规模产物上省不了多少,却会漏掉唯一那处缺失
10. 关键参考
| 参考 | 用途 |
|---|---|
| link-check-cmd | 链接存在性检查与自动修复(本Skill的 S4 委托对象) |
| check-duplication-cmd | 代码重复检查(边界外) |
| ci-check-cmd | 提交前流水线编排(边界外) |
| sovereign-rollout-cmd | 核验后若需向主权区落盘修复,走其四阶段闭环 |
11. Changelog
- v1.0.0 (2026-09-23): 初始版本。萃取自 sc-20260923 会话三次实战核验(AI 协作排除条款检查 / D1-D4 修补后复验 / TODO 完整性体检),三条纪律(双向集合比对、逐字回验、修补自身回验)均经真实缺陷命中验证。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |