ai-delivery-workflow 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # AI Delivery Workflow
 
-本仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装后的业务工作区，也不按双仓项目进行初始化。`bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/` 都是工作流实现或直接物料；`.tmp/` 统一保存可丢弃的本地运行物料。
+本仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装后的业务工作区，也不按双仓项目进行初始化。`bin/`、`lib/`、`skills/`、`docs/`、`verification/`、`audit/` 和 `prototypes/` 都是工作流实现或直接物料；`.tmp/` 统一保存可丢弃的本地运行物料。
 
 本仓库发布的工作流在安装到业务项目后，固定采用“工作流控制仓库 + 嵌套代码仓库”的双仓工作区：工作流仓库跟踪 `.workflow/` 和共享 checkpoint，独立的 `code/` Git 仓库跟踪应用源码、测试、分支和 Tag。详见 [双仓工作区说明](docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
 
@@ -130,7 +130,7 @@ npx ai-delivery-workflow@latest upgrade .
 
 本工作流维护仓库把长期资产分为源码、永久验证源码和审计物料。安装器、状态 CLI、Hook、Skill、Workflow Manager 等通用自动化验证统一位于 `verification/` 并纳入 Git；可重建的全流程交付证据与历史快照位于 `audit/` 并纳入 Git，但不会被 `init` 安装到业务项目。
 
-所有测试工作区、缓存、日志、报告、临时 Git 仓库、npm cache、打包产物、认证辅助文件和绑定单次演练的脚本统一放入 `.tmp/`。根 `.gitignore` 整体忽略 `/.tmp/`，其中任何内容都不得作为权威源码或审计证据。`audit/` 候选包、部署副本和历史快照内嵌的应用测试属于审计物料，可保留原路径；执行这些校验的维护入口位于 `verification/`。
+已确认、需要重复启动或作为审核参考的设计原型及其伴随业务夹具统一放在 `prototypes/` 并纳入 Git；它们是设计资产，不等于正式产品前端，也不随安装器部署到业务项目。所有测试工作区、缓存、日志、报告、临时 Git 仓库、npm cache、打包产物、认证辅助文件和绑定单次演练的脚本统一放入 `.tmp/`。根 `.gitignore` 整体忽略 `/.tmp/`，其中任何内容都不得作为权威源码或审计证据。`audit/` 候选包、部署副本和历史快照内嵌的应用测试属于审计物料，可保留原路径；执行这些校验的维护入口位于 `verification/`。
 
 ```bash
 npm test

package/bin/release-check.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { withNpmAccessToken } from "../lib/npm-auth.mjs";
 import { normalizeNpmPackageResult } from "../lib/npm-package-result.mjs";
 
 function parseArguments(argv) {
@@ -45,6 +46,7 @@ function windowsNpmCli(name) {
 }
 
 function command(root, program, args, options = {}) {
+  const usesNpmConfig = new Set(["npm", "npx"]).has(program);
   if (process.platform === "win32" && new Set(["npm", "npx"]).has(program)) {
     const cli = windowsNpmCli(program);
     if (!cli) return { ok: false, status: null, stdout: "", stderr: `cannot locate ${program} CLI` };
@@ -56,7 +58,7 @@ function command(root, program, args, options = {}) {
     encoding: "utf8",
     windowsHide: true,
     timeout: options.timeout || 10 * 60 * 1000,
-    env: options.env || process.env,
+    env: usesNpmConfig ? withNpmAccessToken(options.env || process.env) : options.env || process.env,
   });
   return {
     ok: result.status === 0 && !result.error,
@@ -71,7 +73,11 @@ function readJson(file) {
 }
 
 function safeDetail(value) {
-  return String(value || "").slice(-2000);
+  const detail = String(value || "");
+  const token = typeof process.env.NPM_ACCESS_TOKEN === "string"
+    ? process.env.NPM_ACCESS_TOKEN.trim()
+    : "";
+  return (token ? detail.replaceAll(token, "[redacted]") : detail).slice(-2000);
 }
 
 function createRecorder(checks) {

package/docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md

@@ -88,6 +88,8 @@ node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs publish -
 
 每个代码引用至少记录：`repo_id`、`code_commit`、可选 `code_tag`、`source_path` 和 SHA-256。
 
+`product_id` 是产品累计研发线的稳定身份，在项目首次 bootstrap 的身份基线中确定；它不是代码仓 `repo_id`、版本号或 release ID。该产品首次开始计划版本时，从当时的代码 `main` 创建一次 `line/<product-id>`。随后每个版本从最新 line 开始，版本收尾才将 line 快进到 immutable `version-ready` Tag；不得在每次迭代或发布时再从 `main` 新拉 line。
+
 ## 5. 版本收尾与发布身份
 
 版本收尾顺序不可调整：
@@ -100,6 +102,17 @@ node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs publish -
 
 `release-ready` 身份由代码 Tag、工作流 Tag 和 Manifest SHA-256 三者组成。发布闭包同时检查代码 ancestry、两个 Tag、Manifest checksum、连续版本关系和 `repo_id`。任一项缺失或漂移都阻止发布。
 
+发布采用 main-first 集成，不从 target Tag 直接签出 release 分支：
+
+1. 用户提出 R00 请求时，记录代码 `main` 的精确 commit 为 `expected_main`；
+2. R01/R02 确认该 commit 仍是 `main` 并完成连续闭包校验；增量发布要求它是选中目标 `version-ready` Tag 的祖先，同版本重发要求 Tag 已是该 commit 的祖先或相等；
+3. R04 从 `expected_main` 创建 `release/<release-id>-<slug>`；增量发布只用 `--no-ff` 合入一个目标 immutable `version-ready` Tag，合并提交是唯一候选身份；同版本重发不新增合并，候选就是 `expected_main`；
+4. R05 至 R08 只验证、审批和部署该精确候选，冻结的 release Tag 也绑定该提交；
+5. R09 成功后才将代码 `main` 从 `expected_main` 快进到这个已部署候选。若 main 发生漂移，旧候选为 `stale`，必须以新请求和新快照重建；
+6. 活动候选上的 `release-fix/<release-id>/<defect-id>` 在生产验证成功后、R10 归档前通过 `release-git.mjs sync-release-fix` 携带 R09 `--production-verification`、全量 schema 2 产品线级 `--candidate-inventory`、新的 `--successor-candidate-inventory` 和 `--expected-line` 受控同步到 `line/<product-id>`。库存根部固定 `scope: product-line`、`product_id`、`line_branch` 与 active candidate；每个候选固定自己的 `release_id`、commit 和 status，根部没有 release ID。输入库存不可改写，脚本只在不同的 successor 路径写入派生后的不可变库存。同步回执必须记录 operation、R09/前代与 successor 库存的证据路径和 SHA-256、source ref/commit、verified release commit、line 的旧/新 head、合并策略、带 release ID 的派生 stale candidate IDs/status updates 和 `applied` 或幂等 `idempotent` 状态。
+
+中间版本 Tag 仅用于闭包和物料追溯，不能重复合入 release 分支。历史 version-ready Tag、版本 Manifest、workflow-ready Tag 和 release Tag 都保持不可变；失败、回滚或阻塞发布不会推进 `main` 或 `line`。
+
 `workflow-state.yaml` 是累计研发和生产身份的权威审计视图。schema 2 分别使用 `development_state` 和 `release_state` 保存两条可并行轨道，发布不得重置累计研发状态。版本收尾在完成节点和登记 `release-ready` 物料后执行 `version-closed`；发布归档在完成 R10 和登记 `released` 物料后执行 `release-archived`。不得直接修改这些字段，也不得从代码分支当前位置反推生产事实。
 
 多版本发布必须逐一校验相邻版本的代码提交和工作流提交 ancestry，不能只证明当前生产提交可到达最终目标。版本任务的跨 clone 归档位于 `.workflow/control/archives/versions/<version-id>/`；归档后活动 task/checkpoint 分片被移除，普通恢复不会重新加载历史版本。

package/docs/FILE-REFERENCE.zh-CN.md

@@ -26,6 +26,7 @@
 | 发行源码 | npm 包实际发布并用于安装目标项目的 `bin/`、`lib/`、`skills/` 和 `docs/`。 |
 | 永久验证 | 根配置和 `verification/` 中的通用测试与审计校验器，用于维护本发行仓库。 |
 | 审计物料 | `audit/` 中 TaskLite 历史 V1 证据与当前契约 ITER-V2 物料，纳入 Git，但不会安装到目标项目。 |
+| 可版本化设计原型 | `prototypes/` 中已确认的 Workflow Manager 原型及其业务页面夹具，纳入 Git，但不进入 npm 包或安装目标。 |
 | 临时物料 | `.tmp/` 中的测试工作区、缓存、日志、报告、临时仓库、打包文件和单次场景脚本，整体忽略且可丢弃。 |
 
 ## 2. 根目录
@@ -44,6 +45,7 @@
 | `docs/` | 完整项目手册、Workflow Manager 使用/维护指南和本文。 | 是 |
 | `verification/` | 工作流仓库的通用自动化测试、专项验证器和长期测试辅助程序，纳入 Git，不进入 npm 包。 | 否 |
 | `audit/` | TaskLite 全流程审计物料；其中内嵌测试属于候选包、部署副本或历史快照，不随 `init` 安装。 | 否 |
+| `prototypes/` | 已确认、可重复启动的设计原型及其伴随业务夹具；纳入 Git，不等于正式产品前端。 | 否 |
 | `.tmp/` | 全部临时运行物料，整体忽略，可随时删除。 | 否 |
 
 ## 3. CLI 与实现库
@@ -422,15 +424,15 @@
 | 路径 | 作用 |
 | --- | --- |
 | `skills/ai-delivery-close-version/` | 关闭已验证计划版本，生成版本 Manifest、血缘、version-ready Tag 与累计研发线推进记录，并在 release-ready 时归档任务。 |
-| `skills/ai-delivery-orchestrate-release/` | 只在用户明确发布时编排 R00 至 R10，管理发布请求和截止版本选择。 |
-| `skills/ai-delivery-assemble-release/` | 使用 `scripts/plan-release.mjs` 计算连续闭包并校验 Git/Tag，输出版本纳入表、物料索引、Git 计划和发布候选模板。 |
+| `skills/ai-delivery-orchestrate-release/` | 只在用户明确发布时编排 R00 至 R10，固定请求时 main 快照、目标版本选择、精确候选晋级和 release-fix 回写；R10 使用产品线级候选库存及不可变 successor。 |
+| `skills/ai-delivery-assemble-release/` | 使用 `scripts/plan-release.mjs` 计算连续闭包并校验 Git/Tag，输出版本纳入表、main-first Git 计划和发布候选模板。 |
 
 ### 12.1 `ai-delivery-prepare-release`
 
 | 文件 | 作用 |
 | --- | --- |
-| `skills/ai-delivery-prepare-release/SKILL.md` | 在 R06 冻结一个已验证发布候选，核对完整变更、实际交付物和回滚能力；生产审批独立位于 R07。 |
-| `references/release-contract.md` | release ID、候选 digest、Tag、交付清单、配置、迁移、验证、回滚和审批契约。 |
+| `skills/ai-delivery-prepare-release/SKILL.md` | 在 R06 冻结一个已验证的 main-first 发布候选，核对完整变更、实际交付物、精确晋级前提和回滚能力；生产审批独立位于 R07。 |
+| `references/release-contract.md` | release ID、main 基线、source Tag/commit、候选 digest/Tag、交付清单、配置、迁移、验证、回滚、line 回写和审批契约。 |
 | `assets/release-template/release-manifest.yaml` | 不可变发布清单模板。 |
 | `assets/release-template/delivery-items.csv` | 镜像、应用、配置、数据、基础设施、文档和运维项的实际交付清单模板。 |
 
@@ -447,7 +449,7 @@
 | --- | --- |
 | `skills/ai-delivery-verify-production/SKILL.md` | 每次部署或回滚后独立验证技术与业务信号，决定 released、失败或回滚。 |
 | `references/production-verification-contract.md` | 生产制品身份、烟雾/业务信号、决策、预授权回滚和归档准入契约。 |
-| `assets/production-verification-template/production-verification.md` | 生产验证报告模板。 |
+| `assets/production-verification-template/production-verification.md`、`production-verification.json` | 人读生产验证报告与强制机器可读 R09 决策模板。 |
 
 ## 13. 治理 skills
 
@@ -462,8 +464,9 @@
 
 | 文件 | 作用 |
 | --- | --- |
-| `skills/ai-delivery-manage-git/SKILL.md` | 管理 protected main、迭代分支、工作包分支/worktree、hotfix、release Tag 和串行生产转换。 |
-| `references/git-policy.md` | 分支命名、合并、Tag、候选保留、清理和“镜像回滚而非回滚分支”规范。 |
+| `skills/ai-delivery-manage-git/SKILL.md` | 管理 protected main、累计研发线、工作包分支/worktree、hotfix、main-first release、release-fix 回写和串行生产转换。 |
+| `scripts/release-git.mjs` | 受控创建 main-first 候选、精确晋级 main、将成功 release-fix 同步到 line，并输出绑定 schema-2 产品线候选库存前代/不可变 successor 的 JSON receipt。 |
+| `references/git-policy.md` | 分支命名、合并、Tag、候选保留、main 快照、schema-2 产品线候选库存、release-fix 回写、清理和“镜像回滚而非回滚分支”规范。 |
 
 ### 13.3 `ai-delivery-manage-standards`
 
@@ -552,7 +555,7 @@
 | `.workflow/architecture/` | 可跨迭代复用的架构基线。 |
 | `.workflow/experience/` | 可跨迭代复用的体验基线和原型管理基线。 |
 | `.workflow/iterations/<iteration-id>/<node-id>/` | 迭代内每个流程节点的默认文档输出目录。 |
-| `.workflow/releases/<release-id>/<release-node>/` | 独立发布 R00 至 R10 的默认文档输出目录。 |
+| `.workflow/releases/<release-id>/<release-node>/` | 独立发布 R00 至 R10 的默认文档输出目录；R10 的 release-fix 物料引用 schema-2 产品线候选库存及其不可变 successor。 |
 | `.workflow/delivery/runtime/active-task.json` | 当前工作流工作区的唯一活动任务指针，任务关闭后删除；外部代码 worktree 通过 `--state-root` 或环境变量关联。 |
 
 ## 16. 本地和生成目录

package/docs/NPM-RELEASE-MANAGEMENT.zh-CN.md

@@ -40,7 +40,7 @@ git diff --check
 - 包名、版本、文件数量和制品摘要符合预期；
 - `bin.ai-delivery` 为 `bin/ai-delivery.mjs`，文件以 Node shebang 开头；
 - `bin/`、`lib/`、`skills/` 和 `docs/` 均进入制品；
-- `.tmp/`、`verification/`、`audit/`、凭据和本地日志不进入 npm 包。
+- `prototypes/`、`.tmp/`、`verification/`、`audit/`、凭据和本地日志不进入 npm 包。
 
 版本号使用以下命令同步到两个清单文件：
 
@@ -65,6 +65,7 @@ Git Tag 和 npm 版本必须指向同一发行内容。不得删除远程 Tag
 
 - 发布前执行 `npm whoami --registry=https://registry.npmjs.org/`，确认账号正确。
 - 交互发布必须启用 `auth-and-writes` 2FA，并使用 npm 的一次性网页认证或 OTP。
+- 本地或自动化预检可通过 `NPM_ACCESS_TOKEN` 提供令牌；维护脚本只把它映射到官方 registry 的 npm 子进程环境，不写入 `.npmrc`、仓库或审计物料。令牌无效或过期时仍必须重新登录或更换令牌。
 - 密码、OTP、恢复码和 npm token 不得写入仓库、`.tmp/` 审计物料、命令日志或对话文档。
 - CI 只能使用最小权限、限定包、可过期的 granular access token；只有发布任务需要时才允许 bypass 2FA，并存入 CI secret store。
 - `publishConfig.registry` 必须固定为 `https://registry.npmjs.org/`，避免把正式包发布到本地镜像。

package/docs/PROJECT-MANUAL.zh-CN.md

@@ -96,7 +96,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
 
 维护仓库的通用、长期验证源码统一位于根 `verification/` 并纳入 Git。业务项目的应用自动化测试位于代码仓库 `<code_repository.path>`，沿用该仓库已有框架、命名和原生测试目录，不得写入 `.workflow/`。
 
-`audit/` 候选包、部署副本和历史审计快照中内嵌的测试文件属于审计物料，可保留原路径；验证这些物料的维护入口位于根 `verification/`。本维护仓库的一切临时仓库、日志、缓存、报告、认证辅助文件和单次场景脚本统一放入被忽略的 `.tmp/`。
+`prototypes/` 保存已确认、可重复启动的设计原型及其伴随夹具；它们纳入维护仓库版本控制，但不等于正式产品前端，也不随安装器部署。`audit/` 候选包、部署副本和历史审计快照中内嵌的测试文件属于审计物料，可保留原路径；验证这些物料的维护入口位于根 `verification/`。本维护仓库的一切临时仓库、日志、缓存、报告、认证辅助文件和单次场景脚本统一放入被忽略的 `.tmp/`。
 
 ## 4. 工作流组成
 
@@ -108,6 +108,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
 | 安装与引导库 | `lib/` | 合并项目配置、识别项目状态、生成存量代码上下文。 |
 | 项目 skills | `skills/ai-delivery-*` | 定义各研发节点的输入、过程、输出、Gate 和失败路由。 |
 | 审计与验证 | `audit/`、`verification/` | 保留历史 V1 执行证据，以 ITER-V2 验证当前契约，并用通用测试验证安装、引导和原型交接；两者均不随 `init` 安装。 |
+| 可版本化设计原型 | `prototypes/` | 保存 Workflow Manager 原型及其业务页面夹具；纳入 Git，不进入 npm 包或安装目标。 |
 | 临时运行物料 | `.tmp/` | 保存测试工作区、缓存、日志、报告、临时 Git 仓库、打包文件和单次场景脚本，整体忽略且可随时删除。 |
 
 安装到业务项目后，主要目录如下：
@@ -549,10 +550,13 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 
 | Git 对象 | 作用 |
 | --- | --- |
-| `main` | 受保护、可发布的集成基线。 |
-| 迭代分支 | 汇总一个迭代版本的已审查工作包。 |
+| `main` | 受保护的生产成功历史，只在生产验证通过后精确快进到已部署候选。 |
+| `line/<product-id>` | 产品的累计研发线，可领先于 `main`；首个计划版本开始时从当时的 `main` 创建，之后版本都从它开始。 |
+| `version/<version-id>-<slug>` | 汇总一个计划版本的已审查工作包。 |
 | 工作包分支 / worktree | 隔离单个技术任务，缩小 AI 上下文和冲突范围。 |
 | hotfix 分支 | 修复已存在的生产行为问题。 |
+| `release/<release-id>-<slug>` | 从 R00 固定的 `main` 快照创建；增量发布精确合入一个目标 `version-ready` Tag，同版本重发复用该快照而不新增合并。 |
+| `release-fix/<release-id>/<defect-id>` | 从活动发布候选创建的隔离纠正分支，成功发布后受控回写到产品研发线。 |
 | 不可变 release Tag | 绑定已冻结发布版本。 |
 
 原则：
@@ -561,13 +565,15 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 - 同一任务的多个 worktree 指向同一个主 `state_root`；
 - 候选失败、发布记录、Tag 和部署记录都保留，不覆盖历史；
 - 生产转换串行化，同一时间只推进一个生产发布；
+- `product-id` 是在首次 bootstrap 的项目身份基线中冻结的稳定产品线标识，不是 release、版本或仓库显示名称。只在该产品首次进入计划版本时从当前 `main` 创建一次 `line/<product-id>`；后续版本不得重新从 `main` 拉线。新建 line 仅允许显式产品拆分或新的稳定产品身份；
+- R00 记录的 `main` commit 是发布候选的不可变基线。它移动或某个候选遗漏已成功发布的 release-fix 时，候选为 `stale`，必须重建；
 - Git 分支不承担生产回滚。
 
 生产回滚使用上一个稳定镜像 digest 或发布清单中声明的等价不可变制品。回滚是一次新的部署状态转换，必须有执行和验证记录。没有历史稳定镜像时，发布准备必须明确替代策略，如停止服务并移除首版部署，不能虚构镜像回滚能力。
 
 ## 12. 发布、上线交付清单和生产部署
 
-每次生产部署只对应一个迭代版本。发布准备必须列出本次所有实际变更，包括但不限于：
+每次生产部署对应一个不可变 release candidate 和一个目标版本；该目标可以代表连续累计版本闭包。发布准备必须列出本次所有实际变更，包括但不限于：
 
 - 产品需求、功能、故事和验收标准；
 - 终端、页面、原型和交互状态；
@@ -594,6 +600,20 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 
 生产部署始终是独立节点。候选测试通过不等于已部署，部署完成也不等于已发布；只有生产验证输出 `released`，迭代才可关闭和归档。
 
+独立发布的 Git 顺序固定为：
+
+```text
+R00 记录请求时 main 的精确 commit
+-> R01/R02 校验该快照未漂移、连续版本闭包和目标 version-ready Tag
+-> R04 从该 main 快照创建 release 分支，增量发布以 --no-ff 精确合入一个目标 Tag，同版本重发不新增合并
+-> R05-R07 对该合并提交验证、冻结 release Tag 和审批
+-> R08 部署该精确候选
+-> R09 验证成功后将 main 精确快进到已部署候选
+-> R10 将已成功发布的 release-fix 受控同步到 line，并归档
+```
+
+中间版本 Tag 只提供闭包和物料追溯，不重复合入 release 分支。`main` 在候选准备、验证、审批或部署前发生变化时，不得更新旧候选的基线，保留证据并以新的 R00 请求重建。`release-fix/*` 只能从活动候选创建；成功生产验证后必须在 R10 前通过受控操作合入 `line/<product-id>`，写入 `applied` 或幂等 `idempotent` receipt，并把未包含该修复的 release-ready 候选标为 `stale`。版本 Tag、版本 Manifest 和 release Tag 均不可重写。
+
 ## 13. Checkpoint、Hook 和中断恢复
 
 ### 13.1 两类受控状态
@@ -854,6 +874,8 @@ R00 发布请求
 
 例如生产在 `VER-02`、目标为 `VER-05`，本次新增范围是 `VER-03..VER-05`。目标等于生产版本时允许重新发布，但必须使用新 release ID 并完整重做环境快照、验证和审批。目标早于生产版本时拒绝发布，恢复旧版本必须部署旧镜像 digest。
 
+R00 同时固定当时 `main` 的 commit。R04 通过 `release-git.mjs create-candidate` 携带 `--expected-main`、精确 `--source-tag/--source-commit`、`--receipt` 和 `--apply` 从该 commit 创建 `release/<release-id>-<slug>`。增量发布只以 `--no-ff` 合入目标 `version-ready/<version-id>/rN` Tag，得到唯一候选合并提交；同版本重发要求该 Tag 已在快照历史中，候选就是快照且不新增合并。R09 成功时先生成机器可读 `production-verification.json`（固定 `operation: production-verification-decision`、release ID、R00 基线、已验证和已部署候选），再通过 `release-git.mjs promote` 携带 `--production-verification` 把 `main` 从该原始快照快进到同一个已部署提交。若 `main` 已变化、候选提交不一致，或目标 Tag 不满足相应的增量/同版本 ancestry，停止并新建发布请求，不能拿当前分支头继续。发布修复在成功验证后、R10 归档前准备 schema 2 产品线级 `candidate-inventory.json`：根部固定 `scope: product-line`、`product_id`、`line_branch` 和 active candidate，每个候选固定自己的 `release_id`、ID、commit/status，根部不得定义 release ID。用 `release-git.mjs sync-release-fix` 携带 `--production-verification`、前代 `--candidate-inventory`、不同路径的 `--successor-candidate-inventory` 和 `--expected-line` 同步进 `line/<product-id>`；输入库存不改写，脚本把跨产品线派生的 stale 更新写入 successor，并在回执中绑定两份库存。stale 候选由脚本派生并写入带 release ID 的 `candidate_status_updates`，不接受调用方传入 stale 列表。已经存在于 line 时仍写入显式 `idempotent` receipt，且只能复用字节完全一致的 successor；任何遗漏修复的可选候选不能继续发布。
+
 版本收尾和发布归档都必须通过正式状态 CLI 固化事实。`version-closed` 在 `06-version-closeout` 完成并登记 `release-ready` 物料后更新 `latest_line_version_id`；它不会触发发布。`release-archived` 在 R10 完成并登记 `released` 物料后更新 `production_version_id` 和 `production_release_id`。R09 只能提供已验证身份，不能直接写入生产事实。以上三个字段以 `.workflow/delivery/workflow-state.yaml` 为权威来源，`project.yaml` 仅保留项目描述和旧项目兼容字段。
 
 版本任务归档写入 `.workflow/control/archives/versions/<version-id>/`，保存版本 Manifest、任务快照和共享 checkpoint。只有可携带归档完整写入后，脚本才移除 `.workflow/control/tasks/` 与 `.workflow/control/checkpoints/` 中该版本的活动分片。普通恢复以及 `--include-closed` 都只扫描活动集合；历史详情必须通过显式审计读取归档。`.workflow/delivery/runtime/archive/` 仅是可丢弃的本地详细副本。
@@ -906,7 +928,7 @@ R00 发布请求
 
 ## 19. 本仓库开发与验证
 
-本工作流维护仓库的通用自动化测试、专项验证器和长期测试辅助程序必须位于根 `verification/` 并纳入 Git；`audit/` 保存可审阅流程物料和历史快照，不保存维护测试入口；一切可丢弃运行物写入整体忽略的 `.tmp/`。这些维护仓库目录不写入安装目标模板，也不替业务代码仓库决定测试目录或版本控制策略。
+本工作流维护仓库的通用自动化测试、专项验证器和长期测试辅助程序必须位于根 `verification/` 并纳入 Git；`audit/` 保存可审阅流程物料和历史快照，不保存维护测试入口；`prototypes/` 保存可版本化设计原型；一切可丢弃运行物写入整体忽略的 `.tmp/`。这些维护仓库目录不写入安装目标模板，也不替业务代码仓库决定测试目录或版本控制策略。
 
 安装依赖：
 

package/docs/STATE-CLI-USER-GUIDE.zh-CN.md

@@ -259,4 +259,4 @@ node .workflow/tools/state/state.mjs gate decide \
 
 `node-completed` 只接受成功状态物料，并检查当前尝试的必需 Gate：`GATE-A`、`GATE-B`、`UX-VS`、`UX-UI` 和 `PRODUCTION-APPROVAL`。只有确实无视觉交互的体验范围可以依据产品终端证据把活动 UX Gate 决定为 `not-required`；Gate A、Gate B 和生产审批必须为 `approved`。历史 `12-release-preparation` 至 `16-version-archive` 只允许登记和读取审计物料，新的 transition 和 Gate 命令会拒绝这些节点。
 
-每个节点交接、生产审批和部署前运行日常 `verify`；版本收尾和发布归档还必须运行 `verify --history`。新研发流程使用 `06-version-closeout` 和 `release-ready`；完成该节点后通过 `version-closed` 记录累计研发版本，但不得创建任何 R 节点。独立发布使用 `R00-release-request` 至 `R10-release-archive`；启动 R00 时必须提供节点为 R00、状态成功且 `artifact_type: release-request` 的显式用户请求物料。R09 只产生生产验证结论，R10 完成并登记 `released` 归档物料后，才通过 `release-archived` 正式回写生产版本和 release ID。发布选择只能引用精确不可变 `version-ready` Tag 和已登记版本物料，生产审批只发生在 R07，并绑定精确 release ID、包 checksum、镜像 digest、配置、迁移、环境和回滚镜像；任一项变化均创建新发布候选并重新审批。
+每个节点交接、生产审批和部署前运行日常 `verify`；版本收尾和发布归档还必须运行 `verify --history`。新研发流程使用 `06-version-closeout` 和 `release-ready`；完成该节点后通过 `version-closed` 记录累计研发版本，但不得创建任何 R 节点。独立发布使用 `R00-release-request` 至 `R10-release-archive`；启动 R00 时必须提供节点为 R00、状态成功且 `artifact_type: release-request` 的显式用户请求物料，并固定请求时 `main` 的 `expected_main`。R04 必须以 `release-git.mjs create-candidate` 的 `--expected-main`、精确 `--source-tag/--source-commit`、`--receipt` 和 `--apply` 从该快照创建 release 分支。增量发布只以 `--no-ff` 合入一个精确不可变 `version-ready` Tag；同版本重发在目标 Tag 已包含于快照时不新增合并，候选就是该快照。候选、审批和部署都绑定该精确候选提交。R09 成功结论先写入带 `operation: production-verification-decision` 的机器 JSON，再通过 `release-git.mjs promote --production-verification <R09-json>` 触发受控的精确 `main` 快进；R10 在归档前准备 schema 2 的产品线级 `candidate-inventory.json`，其根部固定 `scope: product-line`、`product_id`、`line_branch` 和 active candidate，每项候选保留自己的 `release_id`、commit/status。以 `sync-release-fix --expected-line --production-verification <R09-json> --candidate-inventory <predecessor-R10-json> --successor-candidate-inventory <new-R10-json> --receipt --apply` 受控同步每个成功的 release-fix 到 `line/<product-id>`；脚本只写入新的不可变 successor 库存，在回执中绑定前代/后代库存，并派生、登记带 release ID 的 `stale_candidate_ids` 与 `candidate_status_updates`。main 漂移、候选不一致或遗漏已成功 fix 都使候选 stale。R10 完成并登记 `released` 归档物料后，才通过 `release-archived` 正式回写生产版本和 release ID。生产审批只发生在 R07，并绑定精确 release ID、main 基线、source Tag/commit、候选 commit/Tag、包 checksum、镜像 digest、配置、迁移、环境和回滚镜像；任一项变化均创建新发布候选并重新审批。

package/docs/adr/0006-product-line-candidate-inventory.md

@@ -0,0 +1,20 @@
+---
+status: accepted
+---
+
+# Product-line candidate inventory and release-fix synchronization
+
+Release candidates are a product-line concern, not a private list attached to one release directory. R10 therefore freezes a schema-2 candidate inventory scoped by `product_id` and `line_branch`; each candidate retains the `release_id` that created it. The inventory has no root `release_id`, so one line can be audited across successive releases and redeploys.
+
+## Decision
+
+`release-git.mjs sync-release-fix` accepts an immutable predecessor inventory and, with `--apply`, a distinct `--successor-candidate-inventory` path. It validates the R09 `released` decision, the active and verified candidates, the expected line head, and the product-line identity before changing a Git ref. Selectable candidates anywhere in that inventory that do not contain the verified fix are derived as `stale`; callers cannot provide that list. The operation merges the exact fix commit into `line/<product-id>`, writes the successor inventory, and records both inventory evidence bindings plus the derived updates in its receipt. When the active candidate becomes stale, the successor points at the verified candidate.
+
+The predecessor is never rewritten. A retry is idempotent only when the line already contains the fix and the existing successor is byte-identical to the controlled output. Failed deployment, rollback, or an unresolved human decision leaves `main`, `line`, and all immutable inventories unchanged.
+
+## Consequences
+
+- Candidate status history is durable and can be followed through predecessor/successor checksums rather than inferred from branch heads.
+- A release-fix can invalidate candidates from earlier releases on the same product line without erasing their release identities; already `stale` or `released` candidates are not rewritten.
+- R10 callers must allocate a new successor path and register its receipt before archive completion.
+- Consumers of the old release-scoped schema must migrate to schema 2; the protected operation rejects a root `release_id` or a missing candidate-level `release_id`.

package/docs/agents/domain.md

@@ -1,12 +1,37 @@
 # Domain Docs
 
+工程技能探索本仓库时应遵循以下领域文档规则。
+
+## 探索前读取
+
+- 根目录 `CONTEXT.md`；如果存在 `CONTEXT-MAP.md`，则按其指向读取相关上下文
+- 与目标区域相关的 `docs/adr/`
+
+文件不存在时直接继续，不预先建议创建；`/domain-modeling` 会在术语或决策真正确定时按需创建。
+
+## 文件布局
+
 本仓库采用 single-context 布局：
 
-- 领域术语：根目录 `CONTEXT.md`
-- 架构决策：根目录 `docs/adr/`
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-<decision>.md
+│   └── 0002-<decision>.md
+└── src/
+```
+
+## 使用术语表
+
+Issue 标题、重构提案、假设和测试名称中的领域概念，应使用 `CONTEXT.md` 定义的术语。不要使用术语表明确排除的同义词。
+
+如果所需概念不在术语表中，应记录为领域建模缺口，而不是自行引入新名称。
+
+## 标记 ADR 冲突
+
+如果输出与现有 ADR 冲突，必须明确指出，例如：
 
-探索代码前读取存在的 `CONTEXT.md`，并读取与目标区域有关的 ADR。
-文件不存在时直接继续，不主动创建；由领域建模流程按需生成。
+> 与 ADR-0007 冲突，但值得重新讨论，因为……
 
-输出中的领域概念使用 `CONTEXT.md` 定义的术语，避免引入被明确
-排除的同义词。若输出与现有 ADR 冲突，必须明确指出冲突及理由。
+不得静默覆盖既有 ADR。

package/docs/agents/issue-tracker.md

@@ -1,27 +1,26 @@
-# Issue Tracker
+# Issue tracker: Local Markdown
 
-本仓库使用 Gitee Issues 跟踪任务：
+本仓库的 Issue 和规格使用 `.scratch/` 下的 Markdown 文件记录。
 
-- 仓库：`hzr1348/work-flow`
-- API：`https://gitee.com/api/v5`
-- Swagger：`https://gitee.com/api/v5/swagger`
-- PR 不作为任务请求入口。
+## 约定
 
-## Authentication
+- 一个功能使用一个目录：`.scratch/<feature-slug>/`
+- 规格文件：`.scratch/<feature-slug>/spec.md`
+- 实现任务按文件拆分：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`，从 `01` 编号
+- 每个任务文件顶部附近使用 `Status:` 行记录 triage 状态
+- 评论和对话记录追加在文件底部的 `## Comments` 标题下
 
-令牌只从环境变量 `GITEE_TOKEN` 读取，请求头使用：
+## 技能要求发布到 Issue tracker 时
 
-`Authorization: token <PAT>`
+在 `.scratch/<feature-slug>/` 下创建文件；目录不存在时一并创建。
 
-令牌不得写入 URL、输出、日志、脚本或仓库文件。
+## 技能要求获取任务时
 
-## Execution
+直接读取引用的文件路径；用户通常会提供路径或任务编号。
 
-每个新会话首次访问时，先调用 `GET /user`。预期账号为
-`hzr1348`，用户 ID 为 `17347733`；身份不符时停止。
+## Wayfinding 操作
 
-写操作必须先读取并确认目标，获得当前请求授权后执行，再重新读取
-目标验证结果。Swagger 页面只用于查阅，实际请求使用 API endpoint。
-
-Gitee MCP 返回 `401 Access token is wrong type` 时使用 REST API。
-网络沙箱阻止请求时，为目标 Gitee API 请求申请网络权限。
+- Map：`.scratch/<effort>/map.md`
+- 子任务：`.scratch/<effort>/issues/NN-<slug>.md`
+- 阻塞关系：在任务顶部使用 `Blocked by: NN, NN`
+- Frontier：按编号优先选择开放、未阻塞且未认领的任务

package/docs/agents/triage-labels.md

@@ -1,11 +1,11 @@
 # Triage Labels
 
-| Canonical role    | Gitee label      | Meaning            |
-| ----------------- | ----------------- | ------------------ |
-| `needs-triage`    | `needs-triage`    | 等待维护者评估     |
-| `needs-info`      | `needs-info`      | 等待补充信息       |
+| Canonical role | Label | Meaning |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 等待维护者评估 |
+| `needs-info` | `needs-info` | 等待补充信息 |
 | `ready-for-agent` | `ready-for-agent` | 可交给自主代理执行 |
-| `ready-for-human` | `ready-for-human` | 需要人工实现       |
-| `wontfix`         | `wontfix`         | 不会处理           |
+| `ready-for-human` | `ready-for-human` | 需要人工实现 |
+| `wontfix` | `wontfix` | 不会处理 |
 
-技能提到 canonical role 时，使用表中对应的 Gitee label。
+技能提到 canonical role 时，使用表中对应的 Label。

package/docs/agents/workflow-manager-current-state.md

@@ -9,7 +9,7 @@
 - 当前仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装了工作流的业务项目。
 - 当前实施分支为 `codex/workflow-manager-foundation`；Workflow Manager 实现在 `ae70304`，外部 Issue 收尾在 `e727af1`。`0.4.0` 的最终候选身份、校验和及生命周期证据记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`；该记录不随安装包分发，候选包和展开验证工作区保留在被忽略的 `.tmp/`。工作树仍包含用户维护的文档和参考资料变更。
 - 正式维护源码位于 `bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/`。
-- Workflow Manager 设计原型位于 `.tmp/workflow-manager-prototype/`，属于可重建临时物料，不进入发行包，也不等于正式前端已经实现。
+- Workflow Manager 设计原型位于 `prototypes/workflow-manager/`，业务项目原型夹具位于 `prototypes/order-ops-business/`。两者是可版本化设计资产，不进入发行包，也不等于正式前端已经实现；运行时依赖、构建产物和一次性验证工作区仍放在 `.tmp/`。
 
 ## 2. 已进入正式工作流源码
 
@@ -202,4 +202,4 @@ Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 W
 - Workflow Manager 与 AI 接口：`docs/adr/0003-workflow-manager-governed-control-surface.md`
 - 视觉规范：`docs/adr/0004-operational-carbon-visual-standard.md`
 - 项目原型页面化：`docs/adr/0005-prototype-management-as-routed-pages.md`
-- 当前临时原型说明：`.tmp/workflow-manager-prototype/README.md`
+- 当前原型说明：`prototypes/workflow-manager/README.md`

package/lib/npm-auth.mjs

@@ -0,0 +1,16 @@
+const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+const OFFICIAL_NPM_TOKEN_ENV_KEY = "npm_config_//registry.npmjs.org/:_authToken";
+
+export function withNpmAccessToken(environment = process.env) {
+  const token = typeof environment.NPM_ACCESS_TOKEN === "string"
+    ? environment.NPM_ACCESS_TOKEN.trim()
+    : "";
+  if (!token) return environment;
+
+  return {
+    ...environment,
+    [OFFICIAL_NPM_TOKEN_ENV_KEY]: token,
+  };
+}
+
+export { OFFICIAL_NPM_REGISTRY, OFFICIAL_NPM_TOKEN_ENV_KEY };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {

package/skills/ai-delivery-assemble-release/SKILL.md

@@ -9,19 +9,21 @@ Produce a deterministic release selection and auditable material package. Do not
 
 ## Select The Version Closure
 
-1. Build a JSON lineage input from registered version-closeout manifests. Include exactly one predecessor, status, candidate ID/commit, code Tag, workflow commit, workflow Tag, manifest path, and checksum per version.
-2. Run `node scripts/plan-release.mjs --lineage <file> --release-id <id> --target <version> --requested-by <actor> --rationale <text> --workspace <workspace-root>`.
-3. Preserve the JSON result as the source for `R01-version-selection`. Do not use `--skip-git` outside isolated contract tests.
-4. Block on missing predecessors, branching, cycles, disconnected lineage, stale/ineligible versions, wrong `repo_id`, missing code or workflow Tags, workflow manifest checksum drift, backward targets, or any failed adjacent code/workflow ancestry edge. Checking only production-to-target reachability is insufficient.
+1. Read the immutable R00 release request first. It must name the production branch and record the exact request-time `main` snapshot commit (`expected_main`); it is the release base for this release ID.
+2. Build a JSON lineage input from registered version-closeout manifests. Include exactly one predecessor, status, candidate ID/commit, code Tag, workflow commit, workflow Tag, manifest path, and checksum per version.
+3. Run `node scripts/plan-release.mjs --lineage <file> --release-id <id> --target <version> --requested-by <actor> --rationale <text> --workspace <workspace-root>`. Its captured `release_base` must equal the R00 snapshot. Do not use `--skip-git` outside isolated contract tests.
+4. Preserve the JSON result as the source for `R01-version-selection`. The target's `version-ready/<version-id>/rN` value is an immutable Tag, never a branch.
+5. Block on missing predecessors, branching, cycles, disconnected lineage, stale/ineligible versions, wrong `repo_id`, missing code or workflow Tags, workflow manifest checksum drift, backward targets, a changed production branch, or any failed adjacent code/workflow ancestry edge. For an incremental release, the release base must be an ancestor of the target Tag; for a same-version redeploy, the target Tag must already be an ancestor of or equal to the release base. Checking only production-to-target reachability is insufficient.
 
 ## Aggregate Materials
 
 1. Copy the assets into `.workflow/releases/<release-id>/R03-material-aggregation/` and `R04-release-candidate/`.
 2. Add every actual requirement, product, architecture, prototype, source, image, configuration, migration, infrastructure, test, security, risk, operations, rollback, and observability item to `release-material-index.csv`. Code entries require `repo_id`, `code_commit`, optional `code_tag`, `source_path`, source version, original workflow path, and SHA-256.
-3. Record every selected version and immutable identity in `version-inclusion.csv`. Intermediate versions provide traceability; build the release branch from only the exact target tag.
-4. Create `release/<release-id>-<slug>` at the target tag. Apply release-only fixes through `release-fix/<release-id>/<defect-id>`, create a new candidate, and repeat affected verification.
-5. Freeze `release-candidate-manifest.yaml` with the branch commit, image digest, material index checksum, environment/configuration snapshot requirements, and rollback image.
+3. Record every selected version and immutable identity in `version-inclusion.csv`. Intermediate versions provide traceability only; do not merge their Tags into the release branch.
+4. At R04 invoke `$ai-delivery-manage-git`'s controlled `scripts/release-git.mjs create-candidate` operation with `--release-id`, `--release-branch`, R00 `--expected-main`, exactly one `--source-tag` and its immutable `--source-commit`, plus `--receipt <path> --apply`. For an incremental release it creates `release/<release-id>-<slug>` at that snapshot and merges that one Tag with `--no-ff`; for a same-version redeploy whose target is already reachable from the snapshot, it records the snapshot itself as the candidate with no new merge. It returns the only authoritative candidate receipt. Omitting `--apply` is a zero-write plan. Do not substitute a movable line/version branch head, cherry-picks, or repeated Tag merges.
+5. Apply a release-only correction from the active candidate through `release-fix/<release-id>/<defect-id>`. A fix produces a new exact candidate identity and repeats all affected verification; it never rewrites historical version-ready Tags or manifests.
+6. Freeze `release-candidate-manifest.yaml` with the request-time `main` base, exact source Tag/commit, integration commit, branch commit, image digest, material index checksum, environment/configuration snapshot requirements, rollback image, and any release-fix identities.
 
-Same-version redeploy reuses immutable application identities but regenerates the release-scoped indexes, snapshots, verification, approval, deployment, and archive evidence.
+Same-version redeploy reuses immutable application identities but regenerates the release-scoped indexes, snapshots, verification, approval, deployment, and archive evidence. A release-fix still advances the product-line candidate inventory through a distinct immutable successor; it never rewrites the predecessor inventory.
 
 Read [release-assembly-contract.md](references/release-assembly-contract.md) before aggregation.

package/skills/ai-delivery-assemble-release/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Assemble Release"
-  short_description: "Validate version lineage and aggregate release materials"
+interface:
+  display_name: "Assemble Release"
+  short_description: "Validate version lineage and aggregate release materials"
   default_prompt: "Use $ai-delivery-assemble-release to validate both repositories, calculate the version closure, and assemble its candidate."

package/skills/ai-delivery-assemble-release/assets/release-candidate-manifest.yaml

@@ -1,14 +1,25 @@
-schema_version: 2
+schema_version: 3
 release_id: "REL-0001"
 release_candidate_id: "RC-0001"
 mode: "incremental"
 target_version: "VER-0005"
-source_tag: "version-ready/VER-0005/r1"
+release_branch: "release/REL-0001-short-slug"
+release_base:
+  production_branch: "main"
+  commit: "<git-sha>"
+  captured_at: "<RFC3339>"
+release_merge:
+  strategy: "no-ff-single-version-ready-tag"
+  merge_created: true # False when a same-version target is already in the release base.
+  source_tag: "version-ready/VER-0005/r1"
+  source_commit: "<git-sha>"
+  commit: "<git-sha>" # Null when merge_created is false.
+  candidate_receipt_ref: ".workflow/releases/REL-0001/R04-release-candidate/candidate-receipt.json"
 repository:
   repo_id: "app"
   source_path: "code"
-  code_commit: "<git-sha>"
-  code_tag: "version-ready/VER-0005/r1"
+  code_commit: "<git-sha>" # Exact candidate commit: incremental merge result or same-version release base, never a mutable branch head.
+  code_tag: "release/REL-0001/r1"
 workflow_identity:
   workflow_commit: "<workflow-git-sha>"
   workflow_tag: "workflow-ready/VER-0005/r1"
@@ -19,4 +30,5 @@ material_index_sha256: "<sha256>"
 configuration_baseline_sha256: "<sha256>"
 migration_set_sha256: "<sha256>"
 rollback_image_digest: "sha256:<previous-digest>"
+release_fixes: []
 status: "immutable"