|
| 1 | +--- |
| 2 | +{ |
| 3 | + "schema": "shadow-dev/v1", |
| 4 | + "name": "20261012-chore-cli-pin-v160", |
| 5 | + "type": "chore", |
| 6 | + "scope": "distribution", |
| 7 | + "status": "published", |
| 8 | + "baseBranch": "main", |
| 9 | + "branch": "chore/20261012-chore-cli-pin-v160", |
| 10 | + "files": [ |
| 11 | + "package.json", |
| 12 | + "shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md" |
| 13 | + ], |
| 14 | + "github": { |
| 15 | + "repository": "stack-wuh/shadow-dev-workflow", |
| 16 | + "issue": 61, |
| 17 | + "issueUrl": "https://github.com/stack-wuh/shadow-dev-workflow/issues/61", |
| 18 | + "pullRequest": 62, |
| 19 | + "pullRequestUrl": "https://github.com/stack-wuh/shadow-dev-workflow/pull/62" |
| 20 | + }, |
| 21 | + "review": { |
| 22 | + "conclusion": "passed", |
| 23 | + "verifiedCommit": "53fd228b82afa6fbe5cacf19a6daa6601e19a41b", |
| 24 | + "verifiedAt": "2026-10-12T11:26:28.839Z" |
| 25 | + }, |
| 26 | + "workflow": { |
| 27 | + "operation": null, |
| 28 | + "checkpoint": "pr:62", |
| 29 | + "planHash": "3a1dce3ab2d822ed9c6d1b723c930bc787fa4c5413a1b5f8513870940bb58bb0", |
| 30 | + "updatedAt": null, |
| 31 | + "lastError": null, |
| 32 | + "issuePlan": { |
| 33 | + "title": "[chore] cliVersion pin v1.5.0 → v1.6.0（对齐 PR 必填门与 --body-file 能力）", |
| 34 | + "titleRaw": "[chore] cliVersion pin v1.5.0 → v1.6.0（对齐 PR 必填门与 --body-file 能力）", |
| 35 | + "supplement": "", |
| 36 | + "body": "## 动机\n插件的 `norms/pr-message.md`（已随 #60 合并）规定了「`release/publish plan` 必须显式传 `--title` 与 `--body`/`--body-file`」，而这两个能力（硬门 `PR_PARAMS_REQUIRED`、`--body-file` 参数）是 shadow-dev-cli 的 `fix(release)` #56 与 `chore(scripts)` 引入、由 **v1.6.0** 首次对外交付。当前产物仍 pin `v1.5.0`，等于规范要求宿主用旧 CLI 去传一个旧 CLI 不认的参数。\n\n## 引用规范\n- `knowledge/distribution-capability-contract.md`\n - 当前结论: 能力不齐即 `ARTIFACT_INCOMPATIBLE`，判定发生在任何落盘之前；pin 是能力契约不是版本装饰\n - 适用 scope: `package.json.cliVersion`、`requiresCommands`\n\n## 决策\n- 只 bump pin，不 bump 产物版本：混在一起会让 tag 指向的 tree 与实际发布内容分裂（发版版本权威由 publish 阶段独占）。\n- **合并时序硬约束（非协商）**：本 PR 必须在 shadow-dev-cli 的 `v1.6.0` tag 与 GitHub Release **落地之后**才能合。提前合并会让按 release 轨解析的宿主拿到一个指向不存在版本的 pin。\n- 备选「等下次发版一起 bump」被否：规范已进 main，pin 与规范之间的空窗越长，宿主越容易按新规范传参却撞上旧 CLI 的未知参数。\n\n## 任务\n- [ ] task-1 — `package.json` — `cliVersion` bump 到 v1.6.0，且不动 `requiresCommands` 与三份 manifest 的 `version`\n- [ ] task-2 — 门与观察点 — `check:requires`/`check:version` 绿，pin 与 #60 规范所需能力逐条对照\n\n完整 brief：shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md\n\n<!-- shadow-dev:issue-metadata {\"name\":\"20261012-chore-cli-pin-v160\",\"type\":\"chore\",\"scope\":\"distribution\",\"status\":\"proposed\",\"branch\":null,\"baseBranch\":\"main\",\"briefPath\":\"shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md\",\"cliVersion\":\"1.6.0\",\"prUrl\":null,\"issueNumber\":null} -->\n", |
| 37 | + "labels": [ |
| 38 | + "chore" |
| 39 | + ] |
| 40 | + }, |
| 41 | + "release": { |
| 42 | + "files": [ |
| 43 | + "package.json", |
| 44 | + "shadow-docs/INDEX.md", |
| 45 | + "shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md" |
| 46 | + ], |
| 47 | + "message": "chore(distribution): cliVersion pin v1.5.0 → v1.6.0，对齐 PR 必填门与 --body-file 能力", |
| 48 | + "title": "chore(distribution): cliVersion pin v1.5.0 → v1.6.0，对齐 PR 必填门与 --body-file 能力", |
| 49 | + "body": "## 变更\n- `package.json`：`cliVersion` `v1.5.0` → `v1.6.0`。仅此一个字段；`version`（7.0.2）与 `requiresCommands`（29 条）不动。\n\n## 影响\n- 行为/触发面变化：产物声明的最低 CLI 能力抬到 v1.6.0 —— 即 `norms/pr-message.md`（已随 #60 合并）要求的 `release/publish plan` 必填 `--title`/`--body`、以及 `--body-file` 参数，在 v1.6.0 才存在。此前 pin 停在 v1.5.0，等于规范要求宿主用不认这些参数的旧 CLI 去传参。\n- 明确不受影响的范围：`requiresCommands` 判定集不变（本次无新增命令键），能力不齐仍是 `ARTIFACT_INCOMPATIBLE` 在任何落盘之前判红；三份 manifest 的 `version` 不变，发版 bump 属 `shadow-dev-publish` 独占。\n- **合并时序硬约束**：必须在 CLI 的 `v1.6.0` tag 与 GitHub Release 落地之后才能合。实测 `git tag` 当前**尚无 v1.6.0**，所以本 PR 现在不能合。\n- 回滚方式：revert 即把 pin 退回 v1.5.0，无其它副作用。\n\n## 验证\n- 命令与结果：`check:requires` → `✓ skills ⊆ requiresCommands ⊆ CLI 命令目录`；`check:version` → `✓ 三处 manifest 版本同源: 7.0.2`（证明没误碰发版版本）。\n- 能力对照（取自 shadow-dev-cli main）：`--body-file` 在命令目录出现 2 次；`PR_PARAMS_REQUIRED` 存在：true；`lib/domains/release.mjs` 调用 `prParams(`：true；CLI `package.json.version = 1.6.0`，与本 pin 目标一致。\n- 时序证据：`git tag` 无 `v1.6.0` → 本 PR 保持 open 待发版，非疏漏。\n- 未覆盖项（明说）：未跑 `workflow plan --release v1.6.0` 验证 release 轨解析（tag 不存在时按设计应 `RELEASE_NOT_FOUND`，要发版后才能验）；最终判定交 Actions 三平台矩阵。\n\n## 关联\n- Closes #61\n- 依赖：CLI tag `v1.6.0`（由 https://github.com/stack-wuh/shadow-dev-cli/pull/61 的 main 承载，待打 tag）\n- brief: shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md" |
| 50 | + }, |
| 51 | + "commit": { |
| 52 | + "files": [ |
| 53 | + "shadow-docs/changes/20261012-chore-cli-pin-v160/brief.md" |
| 54 | + ], |
| 55 | + "message": "chore(distribution): 结果段回填 quality-gate 的 404 实测依据（pin 前置条件显形）" |
| 56 | + } |
| 57 | + }, |
| 58 | + "knowledge": { |
| 59 | + "action": "无需变更", |
| 60 | + "target": "knowledge/distribution-capability-contract.md", |
| 61 | + "reason": "pin 与能力的对应关系已由该卡承载，本次只是把取值往前推一个 CLI 版本，无新增长期事实" |
| 62 | + } |
| 63 | +} |
| 64 | +--- |
| 65 | + |
| 66 | +# 20261012-chore-cli-pin-v160 |
| 67 | + |
| 68 | +## 复杂度评级 |
| 69 | +- **评级:** S |
| 70 | +- **理由:** 单一声明式字段 bump（`package.json.cliVersion`），不改代码与命令面；风险在合并时序而非内容。 |
| 71 | +- **期望验证深度:** code-read |
| 72 | + |
| 73 | +## 领域模型 |
| 74 | +- **限界上下文:** `distribution` — 产物与 CLI 的能力契约对齐。上游 `shadow-dev-cli`（新门 `PR_PARAMS_REQUIRED` 与 `--body-file` 自 v1.6.0 起提供）；下游三宿主。 |
| 75 | +- **被触及既有不变量:** `cliVersion` 随能力变化单独走变更，不与发版 bump 混交（`norms`/`knowledge` 既有约定）。 |
| 76 | + |
| 77 | +## 引用规范 |
| 78 | +- `knowledge/distribution-capability-contract.md` |
| 79 | + - 当前结论: 能力不齐即 `ARTIFACT_INCOMPATIBLE`，判定发生在任何落盘之前；pin 是能力契约不是版本装饰 |
| 80 | + - 适用 scope: `package.json.cliVersion`、`requiresCommands` |
| 81 | + |
| 82 | +## 动机 |
| 83 | + |
| 84 | +插件的 `norms/pr-message.md`（已随 #60 合并）规定了「`release/publish plan` 必须显式传 `--title` 与 `--body`/`--body-file`」，而这两个能力（硬门 `PR_PARAMS_REQUIRED`、`--body-file` 参数）是 shadow-dev-cli 的 `fix(release)` #56 与 `chore(scripts)` 引入、由 **v1.6.0** 首次对外交付。当前产物仍 pin `v1.5.0`，等于规范要求宿主用旧 CLI 去传一个旧 CLI 不认的参数。 |
| 85 | + |
| 86 | +## 覆盖范围 |
| 87 | + |
| 88 | +- `package.json`：`cliVersion` `v1.5.0` → `v1.6.0`（仅此一个字段；三份 manifest 的 `version` 不动，那属发版载体）。 |
| 89 | +- `requiresCommands` 不变：本次没有新增命令键，能力判定集不受影响。 |
| 90 | + |
| 91 | +## 决策 |
| 92 | + |
| 93 | +- 只 bump pin，不 bump 产物版本：混在一起会让 tag 指向的 tree 与实际发布内容分裂（发版版本权威由 publish 阶段独占）。 |
| 94 | +- **合并时序硬约束（非协商）**：本 PR 必须在 shadow-dev-cli 的 `v1.6.0` tag 与 GitHub Release **落地之后**才能合。提前合并会让按 release 轨解析的宿主拿到一个指向不存在版本的 pin。 |
| 95 | +- 备选「等下次发版一起 bump」被否：规范已进 main，pin 与规范之间的空窗越长，宿主越容易按新规范传参却撞上旧 CLI 的未知参数。 |
| 96 | + |
| 97 | +## 任务 |
| 98 | + |
| 99 | +- [x] task-1 — `package.json` — `cliVersion` bump 到 v1.6.0，且不动 `requiresCommands` 与三份 manifest 的 `version` |
| 100 | +- [x] task-2 — 门与观察点 — `check:requires`/`check:version` 绿，pin 与 #60 规范所需能力逐条对照 |
| 101 | + |
| 102 | +## 结果 |
| 103 | + |
| 104 | +评级 S：声明字段 bump，取证为 pin 与能力的逐条对照 + 门绿。 |
| 105 | + |
| 106 | +- pin 落值：`package.json.cliVersion = v1.6.0`；同文件 `version` 仍 7.0.2、`requiresCommands` 仍 29 条未动（`check:requires` → `✓ skills ⊆ requiresCommands ⊆ CLI 命令目录`；`check:version` → `✓ 三处 manifest 版本同源: 7.0.2`）。 |
| 107 | +- 能力对照（取自 shadow-dev-cli 的 main，非发布产物）：`--body-file` 在命令目录出现 2 次；`PR_PARAMS_REQUIRED` 存在于 `lib/input.mjs` 或 `lib/i18n.mjs`：true；`lib/domains/release.mjs` 调用 `prParams(`：true；CLI `package.json.version = 1.6.0`（与本次 pin 目标一致）。 |
| 108 | +- **时序观察点（已被机器证实）**：本 PR 的 Actions `quality-gate` 在六个矩阵上同一步失败——步骤名 `Install pinned shadow-dev CLI`，日志尾部 `curl: (22) The requested URL returned error: 404`（run 38242986751）。原因正是 pin 指向的 `v1.6.0` 尚未打 tag：门在装不存在的版本。**这不是代码回归，是本 PR 的合并前置条件显形**——打 tag 后复跑即绿。 |
| 109 | +- 未覆盖项：未在本机跑 `workflow plan --release v1.6.0` 验证 release 轨解析（tag 不存在时它按设计应报 `RELEASE_NOT_FOUND`，验证要等发版后）；Actions 三平台矩阵为最终判定处。 |
0 commit comments