@@ -0,0 +1,48 @@
+---
+'@objectstack/spec': minor
+'@objectstack/cli': minor
+---
+
+feat(spec): `spec-changes.json` ships a per-release section, verified against both tarballs (#17080)
+
+Clause-②: yes (widening) — one new OPTIONAL section on a published artifact plus one new
+`os validate --json` key. Nothing previously present is renamed, retired or reshaped: the
+`aggregate` and `perMajor` records and every existing key keep their spelling and meaning.
+Contract-review tier.
+
+`spec-changes.json` (ADR-0087 D4) is keyed to the **protocol major**, while this repo's
+launch-window convention ships BREAKING entries as **minors**. A consumer crossing one minor
+therefore reads a file whose finest question is "16 → 17" — answered long ago — with
+`added: 0, removed: 0`, which reads as *nothing changed*. Measured on the published tarballs:
+between `@objectstack/spec@17.3.0` and `17.4.0` the export surface gained **225** exports and
+lost **51**, and the shipped manifest reported zero of each.
+
+**What ships now.** The published artifact carries a `release` section — `fromVersion` →
+`toVersion` at package-version resolution, with `added` / `removed` (the exports that arrived
+and left, each named `"<entry>: <name> (<kind>)"`) and `converted` / `migrated` (the ADR-0087
+D2/D3 entries first registered in that release):
+
+```bash
+jq '.release | {fromVersion, toVersion, added: (.added | length), removed: (.removed | length)}' \
+  node_modules/@objectstack/spec/spec-changes.json
+os validate --json | jq .specReleaseChanges      # the same data, via the CLI
+```
+
+**The committed copy is unchanged and stays deterministic.** The section is a function of a
+previously *published* tarball, so it is generated at publish time only; `check:spec-changes`
+keeps the registry-only projection in the tree exactly as it was.
+
+**A wrong change file is worse than none, so it is gated.** Before anything reaches npm the
+release lane recomputes the delta from the two tarballs — the previously published one and the
+one about to be published — and refuses to publish when the section disagrees, naming the
+disagreeing exports and the direction of each disagreement. A release whose data would mislead
+does not ship.
+
+**Absence stays distinguishable from zero.** When the previous tarball carries no export
+snapshot the section is omitted rather than emitted empty, and `specReleaseChanges` is `null`
+in exactly that case: a consumer must never read "could not be computed" as "nothing changed",
+which is the defect this closes.
+
+New public exports on `@objectstack/spec`: `SpecReleaseChangesSchema`,
+`SpecReleaseSurfaceSchema`, `composeReleaseChanges`, and the types `SpecReleaseChanges`,
+`SpecReleaseSurface`, `PreviousReleaseRegistries`, `ReleaseSurfaceDiff`.
@@ -14,7 +14,7 @@ model: opus
 
 你是 ObjectStack 开发 agent,由 PM 派发,恰好带一张 GitHub issue。
 交付物两件:该 issue 实现完毕并推成 draft PR,加下方的 JSON 报告。
-报告交付两次,GitHub 优先:先作 issue 评论,首行是字面纯文本 `os-dev-report`。
+报告交付两次,GitHub 优先:同一段 JSON 先作 issue 评论,首行单独一行是纯文本 `os-dev-report`。
 ⛔ 不用 HTML 注释写标记。再作为终报消息:PM 机械解析它,终报消息就是 JSON 本身。
 仓库根的 AGENTS.md 有约束力,第一次编辑前先读它。
 本文件只承载规则、查表数据与钩子无法机械强制的条款;教训写成自含规则,⛔ 不引卡号。
@@ -283,10 +283,10 @@ model: opus
 - 写 `#<n> is not addressed here`、`out of scope: #<n>` 或 `#<n> remains open`。
 - 卡片关系只在 PR 正文声明一次:commit ⛔ 不带卡片 trailer,其 trailer pair 一律 model-free。
 - 标题与散文用英文(见 AGENTS.md);引用的中文裁决保持原文不译,改写引文就是改写裁决。
-- 受管面(见 AGENTS.md)PR 正文带 `## 维护者速读(草稿)` 节,中文、业务角度,席位意见留空。
+- 受管路径全在 `.claude/skills/pm-dispatch/references/` 者为事实层,席位复审即记录;余为规则层。
+- 规则层 PR 正文带 `## 维护者速读(草稿)` 节,中文、业务角度,席位意见留空;事实层不欠。
 - 五段固定:改了什么/为什么改/风险与代价(含回滚)/席位意见/你要做的;席位定稿成评论。
 - 正文以 session-URL 形式的署名页脚收尾(见字节与 sanitizer 纪律节)。
-- `needs:contract-review` 归席位,⛔ 不挂不摘不等;报 PR 上有无与 `--pair PR-NUMBER` 退出码作读数。
 - 触 `skills/**`(对外发布的技能包)的 diff:PR 正文报两个读数,并默认拒绝小功能大扩写。
 - 两个读数缺一不可:被改文件的整文件 before/after,与整包 before/after(全部 SKILL.md 之和)。
 - 行数为准,姊妹门禁定义 token 计数后同报 token。
@@ -298,12 +298,13 @@ model: opus
 - `skip-changeset` 唯一判据:没有已发布的东西移动;已发布 = 各包 `files[]` 实际发运的内容。
 - 快速通道:`docs/adr/**` · `.claude/**` · `scripts/pm/**` · 仓根配置 · 私有包 · 注释,不发布。
 - 其余实测:构建后 grep `files[]` 所列路径找符号,带正控;符号零命中、正控命中 ⇒ 不发布。
-- 本仓库:标签是真实机制,打标签是你的步骤、不是 CI 的,PR 一开出就打。
+- 本仓库:标签是真实机制,打标签是你的默认步骤,PR 一开出就打;派发词可收窄或禁写。
+- 范围 = 派发词点名的标签 + 上文判据下的 `skip-changeset`;禁写或交集为空 ⇒ 零写并报告。
+- `needs:contract-review` 归席位,⛔ 不挂不摘不等;报 PR 上有无与 `--pair PR-NUMBER` 退出码作读数。
 - 写入首选加法端点(REST `POST .../issues/<n>/labels`,不碰已有标签);可达性按会话探,先探后用。
 - 被拒 ⇒ 报端点与状态码、席位代挂,⛔ 不报 `blocked`、不走 MCP;写后必做对比式读回。
-- 读回 diff 现集对 union(读集, 目标):union 有而回读缺 = 被剥的并发标签,重挂并写进报告。
-- 读回只检测剥除防不了,门语义标签被剥恰成绿灯;加法写同样必要不充分。
-- size-labeler 的整组 PUT 会抹掉正确的加法写;收尾一律读回、清单进报告;标签没了就重挂。
+- 读回 diff 现集对 union(读集, 目标),缺者 = 被剥的标签,重挂,清单进报告;收尾再读一次。
+- 读回只检测剥除防不了(size-labeler 整组 PUT),门标签被剥恰成绿灯;加法写同样必要不充分。
 - 关此步骤的是读回不是写入;读回只验写落了,验不出有门在读:幻影门标签读回照样成功。
 - objectui:同名标签对象在,零 workflow/脚本读它、豁免不了任何东西,pin 测试钉着。
 - 那边用空 frontmatter 的 changeset 声明,门禁判定行是权威;⛔ 永不在 objectui 施加该标签。
@@ -317,7 +318,6 @@ model: opus
 
 ## 干净收尾 —— 报告是你的终局动作
 
-- 终报消息之前,把同一段 JSON 发成 issue 评论,首行单独一行、就是字面纯文本 `os-dev-report`。
 - 全文 ⛔ 不出现 HTML 注释:sanitizer 落库后吃短尖括号片段,连反引号里的也吃。
 - 被吃掉标记的评论对 PM 扫描不可见;HTML 注释形不是等价写法,是坏写法。
 - 凡要上 GitHub 的文本,尖括号形状片段一律改占位词拼写(`FIELD`、`IDENT.MEMBER` 一类)。
 
@@ -162,6 +162,8 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报
 - ⛔ 不用共享检出的工作树核验 main,它的 HEAD 由别的 agent 摆布。
 - 零命中须配同主体必中词,否则该零作废;同主体 = 同语料/路径形/包界/引法/失效形态。
 - 同仪器的控制词双零是仪器坏,⛔ 不读作缺席:换法重画再报;哑火仪器与干净结果同值。
+- 控制通过 ≠ 问题问对:零命中须写仪器可达半径与一个必在半径外的已知目标。
+- 半径按形态写(内容/文件名/声明/字段);所求在半径外 ⇒ 零非读数,换看得见它的仪器。
 - 他人据以行动的读数须带单位并答什么本来会让它不是这个值;递 dev 的恒标线索非答案。
 - ⛔ 自用即弃的探针不欠此税;「不是这个值」的答案取逐字工件或具名反例。
 - 仓不可达 ⛔ 不当查过了干净:在 issue 上贴出给对应座位的现成命令,等读数回贴再派。
@@ -171,13 +173,11 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报
 - 自设定时器的文本以先重读状态开头,只写关键判据(若 X 则 Y),其余指针化。
 - 定时器文本 ⛔ 不写结论、不含未经重读即可执行的祈使句。
 - 放行认门禁 job 的结论(`completed: success`),⛔ 不认聚合读数。
-- advisory 门禁红着进 main 是共享损伤,任何车道发现都立即止血并立单。
-- main-red 的跳队例外与事故锚卡约定见 `references/landing-operations.md` B 节。
+- advisory 门禁红着进 main 是共享损伤,任何车道发现都立即止血并立单,见 landing-operations B。
 - dev 自己死了不等于维护者中止:子代理消失是正常死法,走死认领回收。
 - 维护者中止只认原话或宿主回报 stopped by the user,⛔ 不据推断立无重启条件的门。
-- 立卡者不查重,只附 3–5 个查重词;分诊按词查自有列表,零命中须控制词背书。
 - 共享基础设施修复入队前按症状复查 main,不按 issue 号。
-- 真撞上重复,先比数值与作用域再决定关哪个。
+- 立卡者不查重、只附 3–5 查重词;真撞上重复,先比数值与作用域再决定关哪个。
 - sweep 晋级与立卡的前提要对此刻的 main;dev 带证据的零实现停手是好产出,不当返工计。
 - 裁决明令的动作实施中测出对向事实 ⇒ 照字面执行,被打断行为的 pin 反转为拒绝 pin。
 - 对向事实下 ⛔ 同 PR 不做任何 promote/回退;pin 是反转不是删除。
@@ -363,9 +363,9 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报
 - 父单已有子结构的:父单队列标签即可,分诊逐个展开路由、补 `Blocked-by:` 排序。
 - 父单是协调节点,永不派发。
 - 每张留一条英文审计评论(`Triage: lands in …; rationale: …`),可选带 `Size/model suggestion:` 行。
-- 跨仓查重(shadow 检查):跟跨仓引用 + 关键词搜各姊妹仓。
-- shadow 命中在飞 ⇒ `Blocked-by:` 不派;open 未认领 ⇒ 先收敛成一个派发入口。
-- shadow 命中已完成 ⇒ 卡可能过期。
+- 查重/shadow 检查先按文件/机制查本仓与姊妹仓 open 卡(含 `pm:dispatched`),再跟引用与关键词。
+- 同文件同缺陷 = 同一发现,不分车道:证据搬到先卡,后卡关 `duplicate_of`,⛔ 不并排派发。
+- 其余在飞 ⇒ `Blocked-by:` 不派;open 未认领 ⇒ 先并成一个派发入口;已完成 ⇒ 卡可能过期。
 - 生产者在哪是常设分诊问题:declared ≠ enforced 形状的卡先问谁在写这个字段。
 - 派发前按生产者的答案改卡的范围与域标签。
 - 发现分诊轮:`finding` 恒 = 待首次定级、定级即离标;hold 重验只在 `Restart-when:` 命中时发生。
 
@@ -1,6 +1,5 @@
 # PM 核心条款(人读摘要)
-每行一条有约束力的规则,按 PM 语料自身的章节分组,供人工复核。
-细节参数、事实表与操作配方仍以 SKILL.md 与同目录其它 references 为准;本文不新增规则。
+每行一条规则,按 SKILL.md 章节分组;细节以 SKILL.md 与其它 references 为准,⛔ 不新增规则。
 ## 红线
 - PM 不写任何文件;⛔ 永不合自己的、红的或未复核的 PR,合并只经合并队列发生。
 - 版本发布必须人工,发现未经人工的发布痕迹按事故立案,⛔ 不代跑补救性发布。
@@ -43,6 +42,7 @@
 - 判据取命令输出,⛔ 不取 API 字段字面值、不取本地工作树、不取看着相邻的日志。
 - 核验 main 用 fetch 后的 `origin/main`,⛔ 不用共享检出树;仓不可达 ⛔ 不当查过且干净。
 - 零命中须配同主体必中词,否则该零作废;同仪器的控制词双零是仪器坏,⛔ 不读作缺席。
+- 控制通过 ≠ 问题问对:零命中须写仪器可达半径与半径外已知目标,半径外的零非读数。
 - 他人据以行动的读数须带单位并答什么本来会让它不是这个值;递 dev 的恒标线索非答案。
 - 板面、树与队列读数一律自带 UTC 取数时刻,无时间戳的读数按未取处理。
 - 失效修法按序取:先删掉容许出错的构造,再让正确形态成为唯一拼写,最后才加检查。
 
@@ -943,6 +943,18 @@ jobs:
       - name: A declared gate population reaches the tree
         run: pnpm check:declared-population-live
 
+      # ADR-0087 D4's per-release correctness gate (#17080). The REAL run needs
+      # two published tarballs and npm, so it lives in the release lane and
+      # cannot run on a PR; what runs here is its `--self-test`, which is
+      # therefore the only thing standing between an edit to that gate and the
+      # next release trusting it. Its batteries drive the same `verifyRelease()`
+      # the release lane calls, over synthetic tarball trees: a section matching
+      # both artifacts, one omitting a real export, one inventing an export, a
+      # from/to version pointing at another release, and the two absences that
+      # are legitimate. Fixture-only, no spawns; well under a second.
+      - name: Per-release spec-changes gate self-test
+        run: pnpm check:release-spec-changes
+
       # PM bare-root worklist self-test (#10840). The step above proves the
       # dispatch derivation still WORKS; this one proves the recorded triage of
       # the gates that derivation structurally cannot see is still true of the
 
@@ -913,11 +913,19 @@ jobs:
       - name: Backfill spec-changes.json on the GitHub Release (ADR-0087 D4)
         # Ordering is load-bearing: `gh release upload` needs the Release the
         # step above creates.
+        #
+        # `--prepare` regenerates the manifest against the previously published
+        # tarball exactly as the publish lane does, so the asset this repair
+        # uploads carries the same per-release section the npm artifact does.
+        # It cannot repair the npm artifact itself — that tarball is immutable —
+        # and this lane never publishes one.
         if: steps.audit.outputs.releases-missing == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           RELEASE_VERSION: ${{ steps.audit.outputs.version }}
-        run: bash scripts/release-spec-changes.sh
+        run: |
+          bash scripts/release-spec-changes.sh --prepare
+          bash scripts/release-spec-changes.sh --attach
 
   # ══════════════════════════════════════════════════════════════════════════
   # HUMAN LANE — the ONLY job in this repository that publishes.
@@ -1222,6 +1230,35 @@ jobs:
 
           echo "::warning::hotcrm@${HOTCRM_REF} is incompatible with the about-to-publish @objectstack/spec. ADVISORY ONLY — the publish continues. HOTCRM_REF is pre-v17; ship a migrated hotcrm release, bump it, and set BLOCKING=1 in .github/workflows/release.yml to re-arm this gate."
 
+      # ──────────────────────────────────────────────────────────────────────
+      # ADR-0087 D4 — the per-release section, and the gate that proves it.
+      #
+      # Both steps run BEFORE `changeset publish`, and that ordering is the
+      # whole design. The section has to be in the tree when the tarball is
+      # packed (a consumer's tooling reads `node_modules`, not a Release page),
+      # and a delta that disagrees with the artifacts must stop the release
+      # while stopping it is still free — after `changeset publish` the tarball
+      # is immutable and the only remaining repair is another version.
+      #
+      # `--no-git-checks` is what `changeset publish` passes to `pnpm publish`
+      # (its own source), so the working-tree edit `--prepare` makes does not
+      # block the publish. The committed copy is untouched: it stays the
+      # registry-only projection `check:spec-changes` gates on every PR.
+      # ──────────────────────────────────────────────────────────────────────
+      - name: Generate the per-release spec-changes section (ADR-0087 D4)
+        env:
+          RELEASE_VERSION: ${{ steps.guards.outputs.version }}
+        run: bash scripts/release-spec-changes.sh --prepare
+
+      - name: Correctness gate — the delta must match both tarballs
+        # ⛔ A failure here fails the release, by design (#17080): a wrong change
+        # file is worse than none, because a consumer stops looking once it has
+        # one. The gate names the disagreeing exports and the direction of each
+        # disagreement, so a held release arrives with its own diagnosis.
+        env:
+          RELEASE_VERSION: ${{ steps.guards.outputs.version }}
+        run: bash scripts/release-spec-changes.sh --verify
+
       # ──────────────────────────────────────────────────────────────────────
       # The publish itself. `pnpm run release` = build + build-console +
       # scripts/release-publish.sh, which is `changeset publish` followed by ONE
@@ -1312,7 +1349,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           RELEASE_VERSION: ${{ steps.guards.outputs.version }}
-        run: bash scripts/release-spec-changes.sh
+        # Uploads the file the two steps above generated and verified — the
+        # Release asset and the npm artifact are the same bytes by construction,
+        # not by two runs agreeing.
+        run: bash scripts/release-spec-changes.sh --attach
 
   # ══════════════════════════════════════════════════════════════════════════
   # Runtime image — fed by either lane. Building an image for a version that is
 
@@ -129,3 +129,7 @@ examples/app-crm/storage/
 .claude/worktrees/
 # an agent worktree is git plumbing, never repo content: a `.git` FILE reading `gitdir:` plus a whole second checkout
 .worktrees/
+
+# The release lane's scratch space: the previously published tarball it unpacks
+# and the artifact it packs to verify the ADR-0087 D4 per-release section.
+.release-spec-changes/
@@ -459,7 +459,7 @@ Even inside your own worktree, operate defensively:
 2. **One feature branch + one PR per task.** Branch off `main`. **Never commit task work
    straight to `main`.** Name the branch after the issue it fixes: `claude/issue-<n>-<slug>`.
    The issue number is what makes in-flight work *discoverable* — `git ls-remote --heads
-   origin | grep issue-<n>` is a one-command pre-check, and the Duplicate Fix Guard
+   origin | grep -E 'issue-<n>(-|$)'` is a one-command pre-check, and the Duplicate Fix Guard
    workflow warns on fix PRs whose branch names no declared issue. A hit is a hint, not a
    claim — most heads carry no PR: ⛔ never skip a card on one, the `Claim:` comment decides.