frontend-project-context 1.3.0 → 1.6.0

package/docs/22-PHASE-C-TARGET-UPGRADE-PROTOCOL-DESIGN.md

@@ -0,0 +1,398 @@
+# 22 — `1.6.0` Phase C Target Upgrade Protocol 详细设计
+
+> 权威说明：本文是 [19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md](./19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md) 中 Phase C 的可开发合同。如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`implemented-local-verified; release-candidate-authorized`
+>
+> 目标版本：`frontend-project-context@1.6.0`
+>
+> 实现基线：仓库内 `1.5.0` 已完成本地实现并通过 106/106；公开 npm 中已独立核验的最新版本仍为 `1.3.1`。本文不把设计授权解读为实现、Git、真实项目或发布授权。
+
+## 1. 结论
+
+`1.6.0` 只完成 **Target Upgrade Protocol**：在人已选定精确目标版本、Host 已在产品边界外处理依赖与 lockfile 后，新 CLI 用包内机器清单检查旧状态，生成一次只含一个原子工作单元的短生命迁移计划，并在显式 `--write` 下执行产品自有 store/projection 的已编译迁移。每个工作单元后重新评估，直到 Project Context 核心状态可验证。
+
+本版本固定新增：
+
+- 只读 `upgrade-check`；
+- 只读 `upgrade-plan`；
+- 默认 preview、显式 `--write` 的 `upgrade-apply`；
+- Migration Manifest schema 2；
+- Upgrade Assessment、Migration Plan、Upgrade Result Bundle schema 1；
+- capabilities schema 4 与 exchange protocol 4；
+- A-101 至 A-114。
+
+本版本不调用 npm/pnpm/yarn/bun，不读 Git，不联网查 `latest`，不执行项目测试/CI，不修改业务代码，不自动批准、回滚或发布。
+
+## 2. 用户问题
+
+目标项目 pin 住旧版本后，今天的升级依赖人或 Host 阅读 `UPGRADING.md`，再凭对话判断哪些 store、受管入口、projection 或短期协议需要处理。这无法稳定回答：
+
+1. 当前 store/schema/renderer 是否真的可读；
+2. 某个写入是包更新、机械迁移还是语义变更；
+3. 受管字节已被人或另一窗口修改时是否仍可写；
+4. 中途失败或重跑时哪一份状态是真实基线；
+5. 仅更新 package.json/lockfile 后能否声称项目已升级完成。
+
+`1.6.0` 的成功标准是把这些判断变成可重现、可审查、基线过期就停止的机器协议，而不是让工具成为自更新器。
+
+## 3. 分类与边界
+
+本阶段分类为 `optional-adapter-protocol`，依托已有 AI Exchange Boundary、Project Status 和安全写入原语；不新增第八项内核，不修改产品宪法。
+
+| 参与者 | 负责 | 不负责 |
+| --- | --- | --- |
+| 人 | 选定精确目标版本，审查依赖/lockfile 和写计划，决定回滚或继续 | 让 Migration Plan 替代批准 |
+| Host Agent | 在外部更新精确依赖，提供旧版本，保存/删除短期工件，运行项目验收和新窗口复核 | 把自然语言继续执行当作机器授权 |
+| Frontend Project Context | 验证当前字节、兼容矩阵、所有权和计划 digest；执行已编译的产品自有迁移 | 查询/安装新版、Git 操作、业务改写、项目测试或自动回滚 |
+| 包内 manifest | 声明可读基线、内建迁移、consumer 兼容、回滚等级和验收 | 携带脚本、shell、URL、人工批准或任意文件写权 |
+
+## 4. 完整工作流
+
+### 4.1 旧版本外部基线
+
+在更新依赖前，Host 应：
+
+1. 用当前 pin 版本运行 `status` 与 `check`；
+2. 先解决 partial、invalid、pending、drift、stale 或 ownership conflict；
+3. 在 Git 或备份系统中建立可恢复点；
+4. 记录当前精确包版本和进行中的短期 Task/Receipt/Bundle。
+
+这些是 Host 责任；产品不保存 Git 快照，也不伪造“已备份”证明。
+
+### 4.2 外部切换到目标版本
+
+人明确授权后，Host 用项目现有包管理器把依赖和 lockfile 切换到精确 `1.6.0`。产品核心不执行这一步，也不读 lockfile 来推断授权。
+
+### 4.3 新 CLI 评估与有界执行
+
+```text
+project-context upgrade-check --project PATH --from-version VERSION [--json]
+project-context upgrade-plan --project PATH --assessment FILE [--json]
+project-context upgrade-apply --project PATH --plan FILE [--write] [--json]
+```
+
+步骤固定为：
+
+1. `upgrade-check` 输出 Upgrade Assessment；
+2. Host 若需要后续，将 JSON stdout 保存为项目内短期文件；
+3. `upgrade-plan` 验证 assessment 与当前基线，只输出“下一个”工作单元；
+4. 人审查 plan 后，Host 先运行 `upgrade-apply` preview；
+5. 仅在精确写入授权下加 `--write`；
+6. 每个单元后重新运行 check 和 plan，不复用旧 plan；
+7. 核心迁移完成后，Host 运行依赖/lockfile 核对、项目测试/CI 与独立新窗口接管验收；
+8. Host 删除 assessment/plan/result 短期文件。
+
+## 5. CLI 合同
+
+### 5.1 `upgrade-check`
+
+```text
+project-context upgrade-check --project PATH --from-version 1.5.0 [--json]
+```
+
+- 永久只读，不接受 `--write`、`--output`、URL、registry、package-manager、branch 或 restore-point 参数；
+- `--from-version` 必须是 manifest 精确枚举的版本，`1.6.0` 不接受宽泛 SemVer range 或 `latest`；
+- 只读取 Project Context stores、projection lock 声明的受管目标、AI Entry 受管区域和当前包内 manifest；
+- 不扫描业务代码、package.json、lockfile、Git、网络、未声明短期工件或外部备份；
+- 对 `1.3.1`、`1.4.0`、`1.5.0` 无 Upgrade Baseline 命令的历史基线，`from-version` 明确标记为 `host-asserted`；工具仍逐字节验证当前 store/schema/renderer/ownership，不把该参数当作包或 lockfile 证明；
+- uninitialized 返回 `not-applicable`；partial/invalid 失败封闭；attention/conflict 默认阻止，除非目标 manifest 精确声明一个可修复该状态的内建迁移；
+- JSON 输出为 canonical pretty JSON；文本输出只显示源/目标版本、健康、兼容、阻断、回滚等级和 digest。
+
+### 5.2 `upgrade-plan`
+
+```text
+project-context upgrade-plan --project PATH --assessment .project-context/upgrade-assessment.json [--json]
+```
+
+- 永久只读，stdout 是唯一输出；
+- assessment 必须是项目内已存在的普通 JSON 文件，不允许越界或越界 symlink；
+- 先校验 assessment schema/self-digest/manifest digest，再重读当前基线；任一 digest 变化就返回 stale；
+- 每份 plan 恰好包含一个 `nextAction`，不隐含后续步骤授权；
+- 如果无持久迁移，`nextAction.kind` 为 `verify-complete`，仍需 Host 验证依赖、测试和新窗口；
+- 不输出 shell、命令串、包管理器操作或任意代码。
+
+### 5.3 `upgrade-apply`
+
+```text
+project-context upgrade-apply --project PATH --plan .project-context/migration-plan.json [--write] [--json]
+```
+
+- 默认 preview；无 `--write` 时所有项目字节不变；
+- plan 必须是项目内非 store JSON，通过 schema/self-digest/manifest/assessment/current-baseline 全部验证；
+- `--write` 只执行这份 plan 的一个工作单元，不自动执行下一步；
+- 仅允许 manifest 声明且当前运行时已编译的 action/migration ID；未知 ID 在首次写前失败封闭；
+- 所有写入复用现有 path-policy、before digest/CAS、原子替换与条件恢复规则；
+- 任务中途的并发变化必须留在原位，禁止用 plan 中的旧字节覆盖；
+- `verify-complete --write` 不写文件，只生成核心迁移结果；
+- 输出 Upgrade Result Bundle，不写结果历史、不删除 Host 管理的短期文件。
+
+## 6. Migration Manifest schema 2
+
+`1.6.0` 将包根 `migration-manifest.json` 升为 schema 2。它是当前目标包的已验收声明，不是从项目或网络下载的脚本。
+
+顶层精确包含：
+
+```json
+{
+  "schemaVersion": 2,
+  "package": { "name": "frontend-project-context", "version": "1.6.0" },
+  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0"],
+  "stores": {},
+  "renderers": {},
+  "protocols": {},
+  "paths": [],
+  "builtInMigrations": [],
+  "consumerChanges": {},
+  "acceptanceCommands": [],
+  "rollback": {},
+  "externalEffects": {},
+  "manifestDigest": "sha256:..."
+}
+```
+
+固定规则：
+
+- 严格拒绝未知字段、重复版本、SemVer range、未排序集合和非 sha256 digest；
+- `upgradeFrom` 仅声明当前包可直接评估的精确版本；未列出的跨版路径不自动串联推断；
+- `stores` 对 contract/sourceLock/projectionLock/proposal 分别声明 readable/written；
+- `renderers` 分别声明 projection/aiEntry 的 readable/target；
+- `protocols` 声明 exchange、Action Plan、Review Bundle、Task/Stage/Evidence 的 readable/written 和短期工件废弃规则；
+- `paths[]` 为每个 from version 声明分类、有序 migration IDs、是否需人工审查、回滚等级和验收；
+- `builtInMigrations[]` 只允许 `package-only | republish-ai-entry | republish-projection | built-in-store-migration | invalidate-ephemeral-protocol`；
+- 每个迁移必须声明稳定 ID、输入 schema/digest 条件、受管目标类型、是否写入和 rollback class；
+- manifest 不接受任意 path、shell、JavaScript、URL、网络位置或自定义 writer；
+- `manifestDigest` 为排除自身后 canonical JSON SHA-256，并在发布验收中与运行时常量交叉验证。
+
+### 6.1 `1.6.0` 的实际路径
+
+- `1.5.0 → 1.6.0`：package/protocol capability 变更，store 和 renderer 不变，健康基线为 `package-only`；
+- `1.4.0 → 1.6.0`：包含 `1.5.0` evidence consumer change，不迁移未受管的用户证据文件；
+- `1.3.1 → 1.6.0`：继承 projection lock schema 1/2 可读与 AI Entry 写入时的延迟迁移；不因升级自动创建 AI Entry；
+- 三条路径都不修改 Contract/source lock/proposal 语义，不读取或改写业务文件；
+- 如当前 Project Context 已是 clean 且受管 renderer 当前，`1.6.0` 不为了“测试迁移”人为产生 store 写入。
+
+## 7. Upgrade Assessment schema 1
+
+输出固定包含：
+
+- `schemaVersion: 1`、`kind: "upgrade-assessment"`；
+- `product.name`、`fromVersion`、`targetVersion`、`fromVersionEvidence: "host-asserted"`；
+- `manifestSchemaVersion`、`manifestDigest`；
+- `initialization`、`health`、`entryState`、`findingCodes`；
+- contract/sourcesLock/projectionsLock 的当前 snapshot digests；
+- store、renderer、protocol/ephemeral artifact 兼容矩阵；
+- `migrationPath`、`rollbackClass`、`requiresHumanReview`；
+- `state: not-applicable | blocked | ready-for-plan | core-complete`；
+- `boundaries`、`assessmentDigest`。
+
+确定性规则：
+
+- 不包含时间戳、cwd、用户、分支、Git commit、registry 或随机 ID；
+- finding 去重并稳定排序；
+- 不携带 Contract item/source body、业务正文或整份受管文件；
+- `assessmentDigest` 排除自身后计算；同一版本、manifest 与项目字节必须逐字节一致。
+
+## 8. Migration Plan schema 1
+
+Migration Plan 是当前状态的短生命建议，不是授权、Contract、source 或执行记录。
+
+输出固定包含：
+
+- `schemaVersion: 1`、`kind: "target-upgrade-plan"`；
+- from/target version、manifest/assessment digest；
+- 三份 store snapshot 与 next action 所有受管文件 before digest；
+- `nextAction.id`、`kind`、`migrationId`、`targets`、`writes`、`semanticImpact`；
+- `remainingMigrationIds`；
+- `acceptance.core`、`acceptance.hostRequired`；
+- rollback class/reverse migration ID/external restore 说明；
+- `authority: "human-explicit-write-required"`；
+- `planDigest`。
+
+固定不包含 `approved`、`approval`、`reviewer`、`by`、`write: true`、shell 或包管理命令。`semanticImpact` 只能是 `none | managed-rendering | store-structure | protocol-artifact-invalidation`；只要为 `store-structure` 或无自动 reverse migration，就必须 `requiresHumanReview: true`。
+
+### 8.1 单步收敛
+
+一份 plan 恰好只有一个 next action。执行后原 plan 必然因 snapshot 变化而过期，Host 必须重新 check/plan。这个选择用于：
+
+- 把每次授权限制在一个可展示写入单元；
+- 复用已验证的单元原子写入和条件恢复；
+- 让失败、重跑和并发都从真实字节重算；
+- 避免引入持久迁移队列、通用事务引擎或第二份状态真源。
+
+## 9. Upgrade Result Bundle schema 1
+
+`upgrade-apply` 输出：
+
+- schema/kind/product/from/target/manifest/plan digest；
+- `mode: preview | write`、`action`、`written`、受管 target 的 before/after digest；
+- before/after Project Context snapshots；
+- action result 和 stable finding codes；
+- `coreMigration: previewed | applied | blocked | complete`；
+- `hostAcceptance` 固定列出 `dependency-and-lockfile`、`project-tests-or-ci`、`independent-new-window`；
+- `overallUpgrade: host-validation-required`；
+- `resultDigest`。
+
+即使 `coreMigration: complete`，Bundle 也不声称包依赖、CI 或新窗口已验证。这些外部结果由 Host/人记录，本版本不增加可伪造的 `approved` 或 `testsPassed` 输入字段。
+
+Upgrade Result Bundle 与 Evidence Bundle 保持分离：前者是本地迁移结果，后者是可选人工转交的脱敏观察。二者都不是长期真源。
+
+## 10. 兼容与阻断矩阵
+
+| 类型 | `1.6.0` 决策 |
+| --- | --- |
+| healthy `1.5.0` | package-only，生成 complete plan/result，零持久写入 |
+| healthy `1.4.0` | 验证 evidence/exchange consumer change；不改写用户证据文件 |
+| healthy `1.3.1` | 读 projection lock 1/2；保留 AI Entry 延迟迁移规则 |
+| uninitialized | not-applicable；后续使用 setup，不执行 upgrade apply |
+| partial/invalid | blocked；报告缺失/不可读证据，零写入 |
+| pending/drift/stale | blocked；先用旧基线或现有维护原语恢复健康 |
+| AI Entry/projection ownership conflict | blocked；人决定保留或显式重建 |
+| 旧 renderer，ownership 健康 | manifest 明示时才生成单步 republish |
+| 未知 store/schema/renderer/protocol | blocked；不猜测跨版路径 |
+| 进行中 staged task | Host 先关闭/废弃；协议不兼容时必须重生成短期工件 |
+| worktree/多分支 | Host 选一个基准工作树；核心不读分支也不合并 |
+| monorepo/多 context | 根依赖由 Host 统一；每个 `--project` context 独立 check/plan/apply |
+
+## 11. 并发、失败、重跑与回滚
+
+### 11.1 并发
+
+assessment 绑定三份 store snapshots，plan 再绑定 assessment、manifest 和每个写目标的 before digest。在 check、plan、preview 或 write 之间发生的任意相关字节变化都使上游工件过期。
+
+### 11.2 失败与重跑
+
+- 首次写前完成全部 schema、path、ownership、baseline 和 migration ID 验证；
+- 内建单元必须使用已有原子写入；多文件单元必须提供条件恢复并在 fixture 中注入失败；
+- 如恢复前发现文件不再是本次 writer 的 after digest，不覆盖并发变化，返回精确恢复证据；
+- 不保存持久 migration cursor；重跑总是从当前真实字节重新 check/plan；
+- 迁移已完成的状态必须收敛为 `verify-complete`，不重复写入。
+
+### 11.3 回滚
+
+- `package-only`：核心无数据写入；依赖/lockfile 回滚仍由 Host 执行；
+- `reversible-data`：manifest 和运行时必须都存在精确 reverse migration ID，且仍需新的显式写入授权；
+- `forward-only`：写前必须人工审查；只能使用外部 Git/备份恢复，产品不声称自动可降级；
+- 无 reverse migration 时，仅回滚 package.json 与 lockfile 不等于数据已回滚。
+
+## 12. 协议与 capabilities
+
+`1.6.0` 冻结：
+
+- package version `1.6.0`；
+- exchange protocol `4`；
+- capabilities schema `4`；
+- Migration Manifest schema `2`；
+- Upgrade Assessment/Migration Plan/Upgrade Result Bundle schema `1`；
+- Action Plan 与 Review Bundle 仍写 schema `2`，schema 1/2 reader 规则不变；
+- Evidence、Project Status、Assist、Task/Stage schemas 不变；
+- 新命令不增加通用 Action Plan action kind；Migration Plan 是专用、自绑定的写入工件；
+- boundaries 新增 `packageManager: false`、`automaticUpgrade: false`；`applyPlan: false` 仍表示不存在通用 Action Plan executor；
+- `commands` 新增 `upgrade-check | upgrade-plan | upgrade-apply`。
+
+外部 consumer 必须按 capabilities schema/exchange protocol 分支，不得仅比较 package version 猜测功能。
+
+## 13. 错误与退出码
+
+| code | 类别 | 含义 |
+| --- | --- | --- |
+| `upgrade-source-version-unsupported` | invalid | `from-version` 不在精确支持集 |
+| `upgrade-manifest-invalid` | invalid | 包内 manifest schema/digest/运行时声明不一致 |
+| `upgrade-project-state-blocked` | blocked | partial/invalid/attention/conflict 且无精确修复迁移 |
+| `upgrade-store-unsupported` | blocked | 当前 store schema 不可读 |
+| `upgrade-renderer-unsupported` | blocked | 受管 renderer 无兼容或 republish 路径 |
+| `upgrade-protocol-artifact-incompatible` | blocked | 进行中短期工件不能继续使用 |
+| `upgrade-assessment-invalid` | invalid | assessment schema/self-digest 无效 |
+| `upgrade-assessment-stale` | blocked | assessment/manifest/当前 snapshots 已变 |
+| `upgrade-plan-invalid` | invalid | plan schema/self-digest 或 action 无效 |
+| `upgrade-plan-stale` | blocked | plan 绑定的 assessment/manifest/baseline 已变 |
+| `upgrade-migration-unsupported` | blocked | manifest 声明的 migration ID 未在运行时编译 |
+| `upgrade-ownership-conflict` | blocked | 受管文件/区域的现有字节不属于工具 |
+| `upgrade-write-failed` | invalid | 内建写单元失败，返回条件恢复结果 |
+
+有效且 ready/complete 返回 0；有效但 blocked 返回 1；参数、JSON、schema、path 或内部写失败返回 2。任何退出码都不解读为人已授权下一步。
+
+## 14. 实现范围
+
+获得单独实现授权后，允许的主要变更为：
+
+| 文件 | 允许变更 |
+| --- | --- |
+| `src/project-context/upgrade-schema.mjs` | 三份工件的严格验证、确定性和 digest |
+| `src/project-context/upgrade.mjs` | 兼容评估、单步选路、preview/apply 和 result |
+| `src/project-context/migration-manifest.mjs` | schema 2 验证、包内 manifest/runtime registry 交叉核对 |
+| `src/project-context/cli.mjs` | 三个命令的参数 allowlist、输出和退出码 |
+| `src/project-context/capabilities.mjs` / `exchange-schema.mjs` | package/exchange/capabilities 版本与新 schema/边界声明 |
+| `schemas/migration-manifest.schema.json` | schema 2 |
+| `schemas/upgrade-assessment.schema.json` | Upgrade Assessment schema 1 |
+| `schemas/migration-plan.schema.json` | Migration Plan schema 1 |
+| `schemas/upgrade-result-bundle.schema.json` | Upgrade Result Bundle schema 1 |
+| `migration-manifest.json` | `1.3.1/1.4.0/1.5.0 → 1.6.0` 精确路径 |
+| `test/project-context/upgrade.test.mjs` | A-101 至 A-114 |
+| `test/release/acceptance.test.mjs` | 包内 manifest/schema/runtime/docs 一致性 |
+| `README.md`、`UPGRADING.md`、`docs/04`、`docs/05`、`docs/08`、`examples/` | 实现后同步真实公开行为 |
+
+本阶段不修改 Contract/source lock/proposal 的已批准语义，不引入通用脚本执行器、持久 migration queue、数据库、后台进程或包管理器适配层。
+
+## 15. 冻结验收 A-101 至 A-114
+
+- **A-101 Manifest schema 2**：严格字段、self-digest、精确 from 集、有序路径和 runtime migration registry 交叉验证；未知/篡改 manifest 失败封闭。
+- **A-102 历史基线评估**：`1.3.1`、`1.4.0`、`1.5.0` healthy fixture 生成正确兼容矩阵；未列出版本阻止。
+- **A-103 初始化与健康阻断**：uninitialized not-applicable；partial/invalid/pending/drift/stale/conflict 在零写入下给出精确证据。
+- **A-104 Assessment 确定性**：同一输入逐字节一致，self-digest 可校验，不含时间、cwd、Git、项目正文或机器身份。
+- **A-105 单步 Plan**：仅选一个 next action，绑定 assessment/manifest/store/target digests，禁止授权、shell和隐式后续步骤。
+- **A-106 Apply preview 与显式写**：preview 全项目字节不变；`--write` 只执行展示的一个产品自有单元。
+- **A-107 CAS 与并发**：assessment 后、plan 后和写中的基线变化都失败封闭，并发字节不被旧 plan 覆盖。
+- **A-108 所有权与 renderer**：仅对仍属于工具的 AI Entry/projection 生成 republish；人工区域和 conflict 不写。
+- **A-109 失败、恢复与重跑**：注入单/多文件写失败，验证条件恢复、精确阻断和从真实字节重新收敛。
+- **A-110 协议工件兼容**：Action/Review/Evidence/Task/Receipt/Bundle 按 manifest 分类为保留、重生成或废弃，不自动改写短期工件。
+- **A-111 回滚语义**：package-only/reversible-data/forward-only 分离；无 reverse migration 时不声称数据可自动降级。
+- **A-112 monorepo/worktree 边界**：每个 context 独立处理，不扫描分支、不管理根依赖、不合并其他工作树。
+- **A-113 capabilities/protocol**：exchange 4、capabilities 4、manifest 2、三份 schema 1 与包内公开文件一致；Action/Review 仍为 2。
+- **A-114 端到端与永久边界**：隔离 fixture 完成 old → check → plan → preview → apply → recheck → core complete，并由无历史上下文的独立脚本复核；仍无 Provider、Agent Runtime、Git、网络、包安装、项目测试、业务写入、自动批准或回滚。
+
+如每个新编号对应一个顶层测试，实现后总数应不少于 120；只能在实际实现后记录通过数。
+
+## 16. 升级完成的声称边界
+
+Frontend Project Context 最多声称 `coreMigration: complete`。整体升级只有在 Host/人额外确认以下事实后才能对外声称完成：
+
+1. package.json 与 lockfile 已 pin 相同的精确目标版本；
+2. capabilities/status 显示目标版本与可读 schema；
+3. Project Context `clean`，pending/workUnits/findings 已结算；
+4. 受管 AI Entry/projection 当前且 ownership 健康；
+5. 项目必要测试或 CI 已由 Host 执行并通过；
+6. 一个不继承旧对话的新窗口得到同样的 healthy 结论；
+7. assessment/plan/result 和不兼容短期工件已由 Host 清理。
+
+本产品不通过一个可手工填写的 boolean 代替这些外部证据。
+
+## 17. 明确不做
+
+- 不自动查询 latest、安装依赖、更新 package.json/lockfile 或发布包。
+- 不执行 Git status/branch/commit/tag/merge/reset 或创建恢复点。
+- 不读取或修改业务代码、CI 配置、测试、环境变量、凭据或外部系统。
+- 不执行 manifest 内的任意脚本或未编译 migration ID。
+- 不自动覆盖 ownership conflict、接受 source drift、批准 Contract item 或改写语义。
+- 不把 Assessment、Plan 或 Result Bundle 持久为第二真源。
+- 不引入通用事务引擎、migration daemon、升级队列或中心控制面。
+- 不把 `coreMigration: complete` 解读为项目测试、新窗口或业务发布已完成。
+- 不实现 Phase D 其余 Host 适配器或真实项目升级。
+- Target Upgrade Protocol 自身不发布包；Host 只能在获得独立发布授权后执行候选打包、Git 与 npm 发布流程。
+
+## 18. 授权、实现与发布 Gate
+
+以下权限互相独立：
+
+1. 用户于 `2026-09-11` 以“按 docs/22 实现 1.6.0”单独授权本地实现；
+2. 该授权已用于修改源码、schema、测试、package version、migration manifest 和实现事实文档，完成后即消耗；
+3. 在真实目标项目中升级依赖、写 store/projection、执行测试或新窗口验收需要独立范围授权；
+4. Git commit/tag/push、候选打包、网络和 npm 发布需要新的明确授权。
+
+用户于 `2026-09-11` 已给予第 4 项授权，范围限于 `1.6.0` 发布候选整理、Git commit/tag/push、公开 npm 发布与 registry 独立复验；不包含真实目标项目升级或新产品能力。
+
+## 19. 停止点
+
+本文已冻结 `1.6.0` 的用户问题、产品边界、CLI、manifest 与三份工件 schema、单步收敛、兼容矩阵、并发/失败/回滚、协议版本、文件范围与 A-101 至 A-114。
+
+用户于 `2026-09-11` 明确授权“按 docs/22 实现 1.6.0”；该实现权限已用于源码、schema、测试、package version、manifest 与实现事实文档。A-101 至 A-114 与全部既有回归现已 120/120 通过。当前应停止：Git commit/tag/push、候选打包、网络、npm 发布、真实目标项目升级与 Host 验收均未授权。

package/docs/README.md

@@ -64,22 +64,38 @@
 
 14. [18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md](./18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
 
-    记录 `1.3.0` 可选附带协议的冻结设计与本地实现：由宿主提供任务、分支路径信号和阶段 receipt，产品只读编译当前 Stage 的预算 Context Bundle，并在合并前报告 baseline、path、Contract item 和生命周期冲突；A-64 至 A-73 及完整 79 项回归已通过，发布未授权。
+    记录 `1.3.0` 可选附带协议的冻结设计与历史发布结果，以及 `1.3.1` Receipt/Bundle 绑定与 consumer pins 合并修复的实现、82/82 验收和公共 npm 独立验证结果。
+
+15. [19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md](./19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md)
+
+    收敛 `1.3.1` 发布后的总体设计基线：新窗口 AI 接管、`setup` 后 Host Agent 闭环、项目健康收尾、长期真源触发条件、人工转交的证据反馈、机器可读的目标项目升级协议和分期路线。该文档不授权实现或发布。
+
+16. [20-PHASE-A-AI-TAKEOVER-AND-HEALTH-CLOSURE-DESIGN.md](./20-PHASE-A-AI-TAKEOVER-AND-HEALTH-CLOSURE-DESIGN.md)
+
+    冻结 `1.4.0` Phase A 与最小 Phase D 的合同并记录本地实现结果：只读 Project Status、区域型 AI Entry、既有 `AGENTS.md` 共存、projection lock schema 2 延迟迁移、Exchange Protocol 2、最小 migration manifest、Host Agent 接管/收尾流程与 A-77 至 A-90；当前 96/96 通过，未发布、未做真实 Host 验证。
+
+17. [21-PHASE-B-EVIDENCE-FEEDBACK-PROTOCOL-DESIGN.md](./21-PHASE-B-EVIDENCE-FEEDBACK-PROTOCOL-DESIGN.md)
+
+    冻结并记录 `1.5.0` Phase B 本地实现：只读 `evidence`、Evidence Input/Bundle schema 1、默认人工复核的脱敏与转交边界、中心分类模板、Exchange Protocol 3、capabilities schema 3 与 A-91 至 A-100；当前 106/106 通过，真实项目、Git 与发布未授权。
+
+18. [22-PHASE-C-TARGET-UPGRADE-PROTOCOL-DESIGN.md](./22-PHASE-C-TARGET-UPGRADE-PROTOCOL-DESIGN.md)
+
+    冻结并记录 `1.6.0` Phase C 本地实现：只读 `upgrade-check/upgrade-plan`、默认 preview/显式写入的 `upgrade-apply`、Migration Manifest schema 2、三份升级工件 schema 1、单步 digest/CAS 收敛、兼容/回滚矩阵与 A-101 至 A-114；当前 120/120 通过，已授权进入公开 npm 发布候选流程，真实目标项目验收仍未授权。
 
 ## 历史证据
 
-15. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
-16. [07-REAL-TASK-EVIDENCE.md](./07-REAL-TASK-EVIDENCE.md)
+19. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
+20. [07-REAL-TASK-EVIDENCE.md](./07-REAL-TASK-EVIDENCE.md)
 
 历史文档只解释为什么不再建设任务执行 Harness。它们不是程序需求、工作流或授权来源。
 
 ## Beta 证据
 
-17. [09-B0-DTG-TMC-MOBILE.md](./09-B0-DTG-TMC-MOBILE.md)
+21. [09-B0-DTG-TMC-MOBILE.md](./09-B0-DTG-TMC-MOBILE.md)
 
    记录首次真实项目只读接入、通用修补和同项目回归。报告中的历史“下一步”不再产生新需求。
 
-18. [10-B0-DTG-TMC-PC.md](./10-B0-DTG-TMC-PC.md)
+22. [10-B0-DTG-TMC-PC.md](./10-B0-DTG-TMC-PC.md)
 
    记录第二个真实项目只读接入和跨项目对比：核心链路与首轮通用修补再次通过。产品宪法已经停止继续寻找项目和扩充技术发现白名单。