doc-sync

合入前把 Documentation-First 机械化：从 git diff 派生代码 delta，逐项核对该 delta 触发的文档义务是否已同步——CHANGELOG / docs/api/<domain> / CLAUDE.md / ROADMAP；SDK 包改动必须带对应 CHANGELOG + 版本文件对齐（apc/05 §2 S12 · apc/12 doc-sync 行）。

什么时候用：一个改动进合入门前，需要机械核对"该改的文档是不是都改了"，把"改了代码忘了 changelog / 忘了 api doc"这类漏挡在合入前。

铁律：代码 delta 来自真 git diff，不是假设。义务表的每条义务要写清"是 delta 的哪一部分触发的"——义务不是凭空列的清单，是 delta 推出来的。

工具契约（签名以此为准，先核后用）

• apc-doc-sync.ts 是机械门：它只校验"改动的 docs/sdk diff 里提到了 taskId"，是义务的必要非充分条件——它挡不住"改了 sdk 但没改 CHANGELOG"这种缺文件的漏，那要靠下面的义务表逐项核。两者叠加用。

义务表（delta → 必须同步的文档）

按 git diff --name-only 的命中，逐类推导文档义务：

核心不变量（S12 唯一有意义的判据）：改了 SDK 包源码却没改该包 CHANGELOG = gap（缺义务）。这正是 apc/12 的正控/负控——缺 CHANGELOG 必须判缺，同步完整必须放行。

Procedure

1. 派生 delta（真 git diff，不假设）

git diff --name-only > /tmp/delta.txt      # 或 <base>..<head>

把 changed 文件分类：sdk pkg src / endpoint / schema-migration / docs / other。分类是义务推导的输入。

2. 逐类推导义务 + 核 satisfied

对每一类命中，按义务表列一行 { obligation, requiredBecause, satisfied }：

# 例：SDK 包改了没改 CHANGELOG？
# 找 delta 里的 sdk 包源码目录
rg '^sdk/([^/]+/[^/]+)/src/' /tmp/delta.txt -or '$1' | sort -u   # 改了哪些包
# 对每个包，看 CHANGELOG 在不在 changed 集里：
grep -q 'sdk/<pkg>/CHANGELOG.md' /tmp/delta.txt && echo "CHANGELOG ✓" || echo "CHANGELOG ✗ GAP"

satisfied 判据是副作用（该 doc 文件在 changed 集里 / 版本号真对齐），不是"我觉得应该改了"。

3. 跑机械门（叠加，非替代）

npx tsx scripts/apc-doc-sync.ts "$PRISMER_TASK_ID"; echo "gate exit=$?"

exit 1 = 改了 docs/sdk 但 diff 不提 taskId（可追溯性缺失）。机械门过 ≠ 义务全满——义务表的缺文件项要另判。

4. 汇总 gap + 上报

• 有 gap（任一义务 unsatisfied）→ --outcome failed，列出缺哪些。
• 无 gap（义务全满 + 机械门 0）→ --outcome passed。

cloud task verify-criterion "$PRISMER_TASK_ID" "<criterion-id>" --outcome failed \
  --note "gap: sdk/prismer-cloud/typescript/src changed but CHANGELOG not updated"

输出契约（机器判据按这个复算，别自由发挥格式）

本 skill 的验收判据不是「报告里出现了 changelog 这个词」，而是判据自己从 delta 重新推导义务集和 gap 集，再跟你报的比对（structured-criteria.ts 的 doc-sync-obligations），并且把每个声明的 delta 文件读回磁盘。所以报告必须带下面三类可机器解析的行：

DELTA: <path> | class: <sdk-package-source|endpoint-doc|schema-migration|other>
OBLIGATION: <doc path> | required-because: <理由，指回 delta 的哪一部分> | satisfied: yes|no
GAP: <doc path>

判据会判红的情况（任一）：

• 声明的 delta 与本次真实 diff 不等（漏报 / 多报），或声明的文件在磁盘上不存在；
• 义务集与判据从 delta 重算的结果不等——漏一条（比如不提该包 CHANGELOG）跟编一条（delta 推不出来的义务）都判红；
• satisfied 与事实不符（义务满足 ⟺ 该 doc 文件本身在 delta 里）；
• required-because 空或过短（去空白 <20 字符）——「凭空清单」正是本 skill 要挡的；
• GAP 集与重算出的 unsatisfied 集不等（漏报 gap / 虚报 gap 都红）。

写 GAP: <path> 是结构化断言，不是修辞——判据只认这些行，不认 "❌"、"missing" 之类的措辞。

产出（副作用 oracle，报告里必须给）

1. delta 分类：git diff --name-only 的真实命中，按类归组。
2. 义务表：每行 {obligation, requiredBecause, satisfied}——requiredBecause 指回 delta 的哪一部分。
3. gap 列表：required 但 unsatisfied 的义务。 4.（挂 task 时）criterion 上报行 + 机械门退出码。

两个承重 oracle：

• 正控：改了 SDK 包源码但没改 CHANGELOG → 必须判 gap（--outcome failed）。
• 负控：文档全同步的改动（CHANGELOG/api doc 都改了）→ 必须放行（--outcome passed），不虚报缺失。

不许：把义务当凭空清单列而不指回 delta；只跑机械门就宣称"文档已同步"（机械门挡不住缺文件）；断言聊天文本而非 changed-file 集/退出码。

诚实边界

• 本 skill 核的是**"该改的文档改了没"（存在性 + 可追溯性）**，不核文档内容是否正确——CHANGELOG 写了一行但内容是错的，机械门和义务表都放行。内容正确性靠人/评审兜。
• 义务表覆盖的是可从 git diff --name-only 机械推导的类别；"架构级行为变化"这类需要语义判断的义务，本 skill 只能提示"delta 涉及 X，考虑是否要更 CLAUDE.md/ROADMAP"，不能机械断定必须改——这一维标注为需人工确认，不硬判 gap。
• apc-doc-sync.ts 机械门只看 taskId 出现性，是可追溯性的下限，不是文档完整性的证明。

PKF 双投影（研发回环 · doc07 §B2 写入点③）

产出时机：义务全满、SPEC/docs/CHANGELOG 的 markdown 真源落 git 之后，把同内容投影成一张 PKF 记忆页（pageType=reference）——markdown 真源仍是 git diff/review/grep 的工程权威，PKF 是补了 typed link 的可召回投影。投影必带 typed link（derived-from/supports/contradicts），否则投影没有增量、白写（doc07 §B1）。这一步是义务核对之后的投影，不改 delta 派生 / 义务核对 / 机械门任何一步。

语法照 pkf-writing skill——本 skill 不再内嵌语法骨架（frontmatter / typed link / 数据块写法都在那边）。写入面不新造：code agent 走 prismer memory write（SS-14 §4.3 appendix；hermes 侧是 native memory_write）。

声明（doc10 §2.5 格式，报告末尾一行）：

PKF: prismer://workspace/<ws>/memory/<path>

写入面不可达时如实声明 PKF: none — 写入面不可达（<哪一条>），绝不允许为了满足规则而假装写了。

回读：声明后必须回读该页（pkf_read / memory read），确认真实存在、正文非空且与 git 真源同内容；typed link 的 prismer:// 目标必须真实存在，无对应页就删该 link 行、宁缺勿造伪目标；先 git 落地再投影，不倒过来。写入自动挂 INDEX 反孤儿锚（SS-14 §4.2），优先 edit 既有投影页而非 dump 新叶（PLACE 治理照走）。

调用回执（APC 平台方运营纪律 · 自动注入，勿手改）

执行本 skill 的第一步，先落一条调用回执：

cloud skill ack doc-sync --task "$PRISMER_TASK_ID"

按退出码分流（这条命令的退出码是承重信息，禁止用 || 兜底、; true、 set +e 或重定向把它抹掉）：

回执只证明本 skill 被调度，不证明执行正确——效果证明由本 skill 自己的 acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。