wiki-policy-check

wiki-policy-check — 审计业务规则泄漏并验证类型化架构

此技能有两种模式：

模式	使用时机	工作方式
audit	默认模式。用户询问“是否有内容泄漏？”，“审计文档”，或“检查此仓库中是否包含业务规则”。	由提示词驱动：Agent 阅读此仓库中的所有 Markdown，并报告泄漏内容（见下文的 §Steps）。
validate-schema	用户要求验证 wiki 目标中的类型化 Decisions/Rules/Events。或由 wiki-lint 调用（epic #4 Story 05）。或发布新的 ADR/Rule 后。	由脚本驱动：scripts/validate-schema.ts 读取 <wiki>/_schemas/typed-schema.yaml，并根据 ADR-0009 验证 frontmatter 和 events.jsonl 中的各行。

两种模式彼此独立——audit 是最初基于提示词的技能；validate-schema 是程序化扩展（wiki-service 的 epic #4 Story 02）。

模式 1：audit（由提示词驱动）

此技能要贯彻的约定：**技术规则存放在项目仓库中；业务和产品规则存放在中央 wiki 中。**此技能会审计当前仓库中的所有 Markdown，查找越界内容，并报告应迁移的内容。

项目根目录

此技能会读取相对于项目根目录（运行审计的仓库）的路径下的文件，而不是相对于 Agent 当前工作目录的路径。

• 如果从项目内部调用，请使用此技能中显示的相对路径。
• 如果从其他目录调用，请在每个路径前加上 <project-root>/；或者在调用脚本形式时显式传入项目根目录。
• 如果项目根目录不明确，请在运行前通过 harness 的问题工具向用户确认。

提示

遵循项目范围内的 CLAUDE.md / AGENTS.md 约定（“Skill Prompting Conventions”）。对于以下决策点，请使用 harness 的结构化问题工具——AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。

决策点	使用结构化提问的原因	建议选项
模式	影响泄漏内容的呈现方式	仅报告 · 阻止（CI 风格）· 建议迁移
范围（多选）	影响覆盖范围	所有 Markdown · 指定路径 · 仅差异

自由文本提示（不使用结构化工具）：

• 自定义业务规则定义

无暂停模式：如果用户已明确禁用技能执行期间的澄清提问，请将每个结构化提示转换为 Open questions（或同等部分）下的一项，并继续执行，不要阻塞流程。

项目护栏

如果 .wiki-guardrails.yml 存在，则将其视为 wiki 路径、Markdown 允许列表和敏感路径的本地策略来源。不要根据技能推断其他允许列表。如果该文件不存在，请读取 CLAUDE.md/AGENTS.md，并报告缺少护栏配置。

wiki 所在位置

“中央 wiki”的路径因项目而异。运行前，请读取项目的 CLAUDE.md 和/或 AGENTS.md（如果存在，也包括 .agents/rules/），以找到：

1. wiki 位置（例如，子文件夹 wiki/、同级目录 ../knowledge-base/ 或外部 URL）。
2. 项目对业务规则的定义——大多数项目会在“Business rules — policy”部分明确说明。请遵循其界定，尤其注意细微差别（例如，税务产品可能规定“监管算法 = 技术规则，监管范围决策 = 产品规则”；公共网站可能规定“营销文案 = 本地内容，其编码的规则 = wiki”）。

如果项目没有明确说明策略，请使用下方的通用定义，并在审计结果中报告缺少策略。

运行时机

• 在此仓库中经过长时间的文档更新后。
• 在提交包含大量文档的 PR 前。
• 定期运行（大多数项目按月进行即可）。
• 每当用户询问“是否有内容泄漏？”，“审计文档”或类似问题时。

步骤

1. 阅读项目政策（CLAUDE.md、AGENTS.md，以及可选的 .agents/rules/）。提取以下信息：
   • wiki 的路径（子目录或同级目录）。
   • 项目对“这是技术内容”与“这是产品内容”的具体示例（项目特定的细微差别优先于下方通用列表）。
2. 列出此仓库中的所有 .md 文件，排除：
   • node_modules/**、.git/**、dist/**、build/**、.next/**、.wrangler/**、.astro/**、.cache/**
   • 自动生成的输出（Playwright test-results/、锁文件、生成的类型）。
3. 完整阅读每个文件——泄漏内容可能藏在以技术文档为主的文件中。不能只浏览。
4. 对每个文件的内容进行分类：
   • 纯技术内容 → 不需要处理。
   • 纯业务内容（任何面向客户的内容、定价、政策、变现、用户旅程、合规或产品决策）→ 标记以便迁移。
   • 混合内容 → 明确指出其中的业务内容块并标记，而不是将整个文件都标记。
5. 通常意味着内容泄漏的通用信号（项目政策可以补充或覆盖）：
   • 定价 / 变现：货币提及（“R$”、“$”、“€”）、百分比费率、“月费”、“抽成率”、“订阅等级”、“免费 / Pro 方案”、“固定月费”。
   • 面向客户的政策：“取消”、“退款”、“未到场”、“礼遇积分”、“保修”、“使用条款”、“服务级别协议”。
   • 用户旅程 / 用户画像：目标客户描述、标杆客户提及、作为产品定位而非示例标签使用的 ICP 语言。
   • 合规立场：“LGPD”、“GDPR”、“CCPA”、“同意”、“隐私政策”、“数据保留”、“匿名化”、“被遗忘权”、责任声明。
   • 范围决策：“我们将支持 X，但不支持 Y”、分阶段推出的表述、对标杆客户的承诺。
   • 外部集成的理由：何时使用、为何使用、对计费的影响（技术性的“如何集成”仍归此处；“是否应该使用”则属于产品内容）。
   • 未解决的产品问题：任何向负责人提问的内容、搁置的决策、关于功能的“以后再决定”标记。
6. 与 wiki 交叉核对：对每个标记项，检查第 1 步确定的 wiki 位置，确认是否已有规范版本。
   • 如果有 → 建议操作为“添加交叉引用 + 在此处删除”（不要重复）。
   • 如果没有 → 建议操作为“通过 /wiki-ingest 迁移”（在 wiki 仓库 / wiki 文件夹中运行，而不是在此仓库中运行）。
7. 输出一份报告。不要修改文件。
8. 应用更改前先征求同意。此技能仅生成报告；由用户决定迁移哪些内容。

输出格式

## Wiki Policy Check — <YYYY-MM-DD>

### Findings (<n>)

| File | Excerpt | Type | Suggested action | Confidence |
|---|---|---|---|---|
| <path>:<line> | "<short quote>" | business | migrate to <wiki>/business/<page>.md | high |
| ... | ... | mixed | cross-ref + delete | medium |

### Files audited and clean (<n>)
- <list>

### Notes
- Auto-generated content skipped: <count> files
- Already covered by the wiki: <count> findings (cross-ref recommended)
- Project policy gaps observed: <list any policy text that was missing or unclear>

规则

• 只读：此技能不会修改文件。用户运行 /wiki-ingest（在 wiki 仓库或 wiki 文件夹中）来实际迁移。
• 项目策略优先于通用策略：如果项目自己的 CLAUDE.md 声明了某项细节（例如“税务算法在此处保持技术性内容”），即使上方的通用信号列表会将内容标记出来，也应遵循该细节。
• 默认标记：如果不确定某项内容是否属于业务规则，就将其标记出来，由负责人决定。
• 不要重复：如果 wiki 中已有某项规则，建议的操作是“交叉引用 + 在此处删除”，而不是“再次迁移”。
• 不要标记通用技术栈提及：技术名称（“React”、“TanStack Start”、“Drizzle”、“Better Auth”、“Convex”、“Cloudflare Workers”）属于技术内容，应予以保留。只有当这些名称与产品描述捆绑出现时才标记，例如“我们使用 X，因为我们的客户 Y”；需要移除的是产品描述，而不是技术内容。
• 营销文案的特殊情况：如果项目发布了公开网站，文案本身应保留在那里（它必须呈现出来），但文案所表达的规则属于 wiki，文案应引用该规则，而不是重述规则。
• 跳过自动生成的内容（构建产物、锁文件、生成的类型、测试结果）。
• 摘录要具体：引用实际原文，而不是改述。用户需要看到准确措辞才能做出决定。

---

模式 2：validate-schema（脚本驱动）

根据中央类型化架构 <wiki>/_schemas/typed-schema.yaml，验证 Decisions（<wiki>/<project>/decisions/ADR-*.md）、Rules（<wiki>/<project>/rules/RULE-*.md）的 frontmatter，以及 Events（<wiki>/<project>/history/events.jsonl）中的行。

架构规范见 ADR-0009 (wiki-service)，规范架构文件位于 wiki-content 仓库中的 wiki/_schemas/typed-schema.yaml。

适用场景

• 通过 PR 向 wiki-content 发布新的 ADR 或 Rule 后（冒烟测试）。
• 定期针对整个 wiki-content 运行（回归检查）。
• 由 wiki-lint 技能（Epic #4 Story 05）在 warning 或 block 模式下调用。
• 在 CI 门禁中手动验证（未来）。

调用方式

# Default: JSON output, exit 0 if all valid, exit 1 if invalid
bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts --wiki-path /path/to/wiki

# Human-readable output
bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts --wiki-path /path/to/wiki --format table

# Custom schema path (e.g. for tests)
bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts --wiki-path /path/to/wiki --schema-path /path/to/typed-schema.yaml

标志

标志	默认值	说明
--wiki-path <path>	（必填）	wiki 目标的根目录（例如 /tmp/wc-clone/wiki）。会在其下匹配 */decisions/、*/rules/、*/history/。
--format json|table	json	json 用于机器可读格式（可供 jq 处理）；table 用于人工检查。
--schema-path <path>	<wiki>/_schemas/typed-schema.yaml	覆盖架构文件位置（主要用于测试）。
--help / -h	—	打印用法说明。

退出代码

代码	含义
0	所有文档均有效；没有重复 ID；没有孤立引用。
1	至少存在以下一种情况：架构无效、ID 重复、存在孤立引用。
2	执行错误（架构文件缺失、glob 匹配失败等）。

输出（JSON 架构）

{
  "schema_version": "1.0.0",
  "summary": { "valid": 3, "invalid": 1, "duplicate_ids": 0, "orphan_refs": 1 },
  "validations": {
    "decisions": [
      { "path": "<project>/decisions/ADR-0001.md", "valid": true, "id": "ADR-0001", "project": "<project>" },
      { "path": "...", "valid": false, "errors": [{ "field": "status", "message": "must have required property 'status'" }], ... }
    ],
    "rules": [...],
    "events": [{ "path": "...events.jsonl", "line": 2, "valid": true, "kind": "etl-run" }]
  },
  "duplicate_ids": [
    { "project": "<project>", "id": "ADR-0001", "paths": ["path1.md", "path2.md"] }
  ],
  "orphan_refs": [
    { "in": "<path>", "ref": "ADR-9999", "reason": "ADR-9999 not found in same project (<project>)" }
  ]
}

规则

• 对 Decisions 和 Rules 使用 additionalProperties: false（严格校验）；对 Events 使用 additionalProperties: true（兼容旧版 ETL 事件）。
• 交叉引用按项目验证（依据 ADR-0009 Decision #6）。supersedes: ADR-NNNN 仅针对同一项目中的 ADR 进行验证；会跳过跨项目引用。
• 重复 ID 按项目和类型分别检查（smart-city/ADR-0001 与 front-manager/ADR-0001 可以共存；smart-city/decisions/ 中的两个 ADR-0001 会冲突）。
• 架构中的日期和时间戳使用 pattern 正则表达式（而不是 format: date），依据 ADR-0009 Decision #11 —— ajv-cli 严格模式在没有 ajv-formats 插件时无法识别 format。
• 通过 js-yaml 的 JSON_SCHEMA 引擎将 YAML frontmatter 日期解析为字符串（默认的 DEFAULT_SCHEMA 会将 2026-05-22 强制转换为 Date 对象）。

测试

cd ~/.claude/skills/wiki-policy-check
bun test scripts/validate-schema.test.ts
# → 8 pass, 0 fail

8 个单元测试涵盖：有效的 ADR、无效的 ADR（缺少状态）、重复 ID、孤立引用、有效的 Rule、有效的 Event（多种类型）、无效的 Event（缺少 ts）、汇总统计。测试夹具位于 scripts/fixtures/wiki/。

边界

• 此脚本为只读，不会修改 wiki 文件。
• 此技能为全局技能（位于任何单个项目之外）。此脚本可移植，仅需 bun 和 package.json 中的依赖。
• 若要以审计模式检查业务规则泄漏（该技能的原始用途），请使用上文的模式 1。