ai-delivery-workflow 0.7.0 → 0.7.1

package/docs/STATE-CLI-MAINTENANCE.zh-CN.md

@@ -2,7 +2,7 @@
 
 当前生产图是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。`R00-release-request` 至 `R10-release-archive` 继续允许写入。
 
-正式状态写入会先完整暂存权威事件分片、当前视图和 JSONL 事件索引，持久化 prepared journal，再提交各目标并写入 committed marker；同步异常时恢复原文件，进程中断后由下一次受锁 mutation 或 `rebuild` 幂等恢复。`inspect`、`verify`、Bootstrap 诊断与 Workflow Manager 正式状态读取期间获取与 mutation 共用的 formal-state lock；活动 writer、其他 reader 或未恢复 journal 均使读取 fail-closed，避免检查通过后又读到混合 revision。只读调用方不得接管死锁或执行事务恢复。日常 `verify` 不遍历历史分片，只校验当前视图、JSONL 索引、物料和状态不变量；显式 `verify --history` 还检查全部事件分片的连续性、元数据、记录 checksum、schema 2 checksum 链以及最新 replay 结果与全局视图的一致性。`rebuild` 按 revision replay 每个 stream，并按确定顺序重建 JSONL 索引。
+正式状态写入会先完整暂存权威事件分片、当前视图和 JSONL 事件索引，持久化 prepared journal，再提交各目标并写入 committed marker；同步异常时恢复原文件，进程中断后由下一次受锁 mutation 或 `rebuild` 幂等恢复。`inspect`、`verify`、Bootstrap 诊断与 Workflow Manager 正式状态读取期间获取与 mutation 共用的 formal-state lock；只读调用方只对能够解析且确认 `pid` 仍存活的活动 writer 做有限等待，以避免并发读取观察到混合 revision；未知格式锁、失联 writer、其他 reader 或未恢复 journal 均立即 fail-closed。只读调用方不得接管死锁或执行事务恢复。日常 `verify` 不遍历历史分片，只校验当前视图、JSONL 索引、物料和状态不变量；显式 `verify --history` 还检查全部事件分片的连续性、元数据、记录 checksum、schema 2 checksum 链以及最新 replay 结果与全局视图的一致性。`rebuild` 按 revision replay 每个 stream，并按确定顺序重建 JSONL 索引。
 
 ## 1. 权威源码与安装结果
 
@@ -135,7 +135,7 @@ npm run audit:verify
 
 `workflow-state.yaml` 当前 schema 为 2。修改状态实现时必须分别验证 `development_state` 与 `release_state` 的 scope、局部 revision、节点集合、Gate 集合和节点尝试。流程图不能退化为简单“上一编号节点”判断：平台准备允许并行，体验与产品允许带原因重开，后续迭代允许用成功的冻结基线物料满足未受影响的前置条件。
 
-独立 aggregate 的 writer 仍通过共享提交区串行更新 JSONL 和全局视图，但使用各自的 aggregate revision：最多等待可识别的活动事务 30 秒，获取锁后重新读取并可分别成功。同一 aggregate 的 writer 在等待后必须因 revision conflict fail-closed。未知格式锁和只读入口不等待、不恢复，遇到 live lock 或 journal 立即失败。
+独立 aggregate 的 writer 仍通过共享提交区串行更新 JSONL 和全局视图，但使用各自的 aggregate revision：最多等待可识别的活动事务 30 秒，获取锁后重新读取并可分别成功。同一 aggregate 的 writer 在等待后必须因 revision conflict fail-closed。只读入口仅等待可证明仍存活的活动 writer；未知格式锁、失联 writer 和 journal 均不等待、不恢复，立即 fail-closed。
 
 安装诊断不得从项目内可编辑 manifest 推导可信 Skill 集合。固定 Skill 清单、Skill 目录摘要、Hook 摘要和状态运行时摘要以发行包为准；manifest 必须与发行包一致。`doctor` 还必须运行安装后状态 CLI 的 `inspect` 与 `verify`，并校验 JSON 输出语义。
 

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

@@ -4,7 +4,7 @@
 
 ## 可重建视图
 
-正式状态 mutation 会生成 `.workflow/control/events/<stream>/<revision>-<event-id>.yaml` 权威事件分片，并与 `workflow-state.yaml` 或 `artifact-registry.yaml` 当前视图及 `state-events.jsonl` 索引作为一组提交。workflow 与 artifact mutation 都使用 schema 2 增量事务：事件只保存顶层元数据和受影响的 scope 或物料，不再嵌入完整视图；scope start 同时固化项目身份。带已登记 evidence 的 transition/Gate 会在同一事务中同时生成 workflow delta 和 artifact handoff delta，并向 registry 顶层 `handoffs` 追加独立关系；已登记 artifact revision 的字段保持不变。提交前会在 `.workflow/delivery/runtime/formal-state-locks/` 写入恢复 journal；`inspect`、`verify`、Bootstrap 诊断及 Workflow Manager 正式状态读取期间持有同一把 formal-state lock，遇到并发 mutation 或未恢复 journal 时 fail-closed，不会返回混合 revision。mutation writer 最多等待可识别的活动提交 30 秒，获取锁后重新读取并校验自己的 aggregate revision。下一次 mutation 或 `rebuild` 根据 commit marker 回滚 prepared 事务或清理 committed 事务。视图丢失或损坏时执行：
+正式状态 mutation 会生成 `.workflow/control/events/<stream>/<revision>-<event-id>.yaml` 权威事件分片，并与 `workflow-state.yaml` 或 `artifact-registry.yaml` 当前视图及 `state-events.jsonl` 索引作为一组提交。workflow 与 artifact mutation 都使用 schema 2 增量事务：事件只保存顶层元数据和受影响的 scope 或物料，不再嵌入完整视图；scope start 同时固化项目身份。带已登记 evidence 的 transition/Gate 会在同一事务中同时生成 workflow delta 和 artifact handoff delta，并向 registry 顶层 `handoffs` 追加独立关系；已登记 artifact revision 的字段保持不变。提交前会在 `.workflow/delivery/runtime/formal-state-locks/` 写入恢复 journal；`inspect`、`verify`、Bootstrap 诊断及 Workflow Manager 正式状态读取期间持有同一把 formal-state lock，仅对可解析且确认 writer `pid` 仍存活的活动 mutation 做有界等待，不会返回混合 revision。未知格式锁、失联 writer、其他 reader 或未恢复 journal 均立即 fail-closed。mutation writer 最多等待可识别的活动提交 30 秒，获取锁后重新读取并校验自己的 aggregate revision。下一次 mutation 或 `rebuild` 根据 commit marker 回滚 prepared 事务或清理 committed 事务。视图丢失或损坏时执行：
 
 ```powershell
 node .workflow/tools/state/state.mjs rebuild

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

@@ -1,13 +1,13 @@
 # 工作流与工作流管理器阶段现状
 
-更新时间：2026-08-22
+更新时间：2026-08-23
 
 本文是继续设计、实现或审核 Workflow Manager 时的阶段入口。它区分已经进入正式工作流源码的能力、已经接受但尚未实现的产品决策、仅在隔离原型中验证的交互，以及仍未完成的事项。领域术语以根目录 `CONTEXT.md` 为准，不以本文替代 ADR、正式状态契约或 Issue。
 
 ## 1. 当前基线
 
 - 当前仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装了工作流的业务项目。
-- 当前正式源码候选版本为 `0.6.0`（待完成发布 Gate）；上一版 `0.5.1` 的提交、Git tag、npm 包身份及 Workflow Manager 的历史 `0.4.0` 候选身份、校验和和生命周期证据仍记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`，这些历史记录不可改写。候选包和展开验证工作区保留在被忽略的 `.tmp/`。
+- 当前维护基线的包版本为 `0.7.1`，本轮维护提交按 PATCH 版本完成发行闭环；对应发行提交、Git tag `v0.7.1` 和 npm 包身份由发布预检与发布后验证固定。`0.4.0`、`0.5.0`、`0.5.1`、`0.6.0` 和 `0.7.0` 的提交、Git tag、npm 包身份及校验和/生命周期证据均属于历史记录，仍保存在 `audit/` 中且不可改写；候选包和展开验证工作区保留在被忽略的 `.tmp/`。
 - 正式维护源码位于 `bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/`。
 - Workflow Manager 设计原型位于 `prototypes/workflow-manager/`，业务项目原型夹具位于 `prototypes/order-ops-business/`。两者是可版本化设计资产，不进入发行包，也不等于正式前端已经实现；运行时依赖、构建产物和一次性验证工作区仍放在 `.tmp/`。
 
@@ -156,17 +156,17 @@ Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 W
 
 当前正式浏览器测试遍历全部 19 个 Page，验证 P12 筛选、P13 Scene/Ctrl+V/保存、P14/P15 深链、P14 -> P13 Source Inspection Snapshot、P08 双 Tab/计划节点、P02 列头以及 `1280x720`、`1440x900` 无横向溢出或关键面板重叠；应用控制台无 error/warn。Manager 定向套件 97/97 通过，最终 `index.html` 引用的哈希资源已登记到 Git 索引。
 
-### 4.1 `0.4.0` 候选验证
+### 4.1 历史 `0.4.0` 候选验证
 
 - 当前 P0/P1/P2 候选包的精确路径、SHA-256、文件数和生命周期报告由维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 固定登记。审计记录不在 npm 包范围内，因此不会导致候选包自引用；实际 tarball 和展开验证工作区仍保留在 `.tmp/`。
 - 隔离新安装的 Doctor 除可选 CodeGraph 提示外全部通过；安装后 Manager 的主页、健康检查、`workflow-manager.v1` Schema、19 个 Page、七节点投影、25 个可发现受控动作和 r33 Prototype 投影均已实测。
 
-### 4.2 v2 Prototype catalog Candidate Assurance
+### 4.2 历史 v2 Prototype catalog Candidate Assurance
 
 - 新安装交付把 v2 Prototype Revision 的运行时、Manager、Agent Interface、Experience Skill 和全部必需 catalog 模板列为包表面。`doctor` 在包表面缺失时立即失败，不再继续计算会因缺失运行时而崩溃的受管资产摘要。
 - 新的生产路径只接受 `prototype-revision-catalog.v2`。Experience Skill、Project Template、安装后的 Manager 与 Candidate Assurance 都从同一 Revision/checksum 读取事实；缺少任一必需 catalog 时由 CLI、HTTP 和 UI 确定性拒绝。
 - `verification/workflow-manager.test.mjs` 的隔离 Candidate Assurance 用当前工作树实际执行 `npm pack`，在 `.tmp/` 的独立 consumer 安装 tarball，并由安装后的 `ai-delivery init` 与 `doctor` 建立项目。它用多 Logical Terminal 的 v2 fixture 证明安装后的 Manager CLI、HTTP 和 P07/P11-P17 浏览器 UI 读取同一 Prototype Revision 身份和 checksum：每个 Web UI 请求和返回都显式为 `TERM-WEB`，P12 的 `TERM-ADMIN` 路由实际显示 Admin 目标而不回退到 Web。Component Candidate 通过 P11 提交 `candidate -> under-review`、已安装 CLI 提交 `under-review -> registered`、HTTP 提交 `registered -> modified`；每次 apply 均产生 Receipt/Event，CLI 与 HTTP 均重放同一幂等键。初始 CLI/HTTP 计划仍返回相同 plan/successor；删除 v2 `components` catalog 后，三种入口返回相同受控拒绝。测试覆盖 `1280x720` 与 `1440x900` 桌面视口，且有效 Revision 路径没有浏览器 console error/warn。
-- 可重建证据和边界记录在 `audit/WORKFLOW-MANAGER-V2-CANDIDATE-ASSURANCE.md`。它不替代 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 的历史候选身份；`0.5.0` 发布时的源码已通过完整 `release:check`、npm 2FA Gate 并发布。生成的 tarball、consumer、缓存和浏览器临时文件都留在被忽略的 `.tmp/` 并在测试结束后删除。
+- 可重建证据和边界记录在 `audit/WORKFLOW-MANAGER-V2-CANDIDATE-ASSURANCE.md`。它不替代 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 的历史候选身份；其中记录的 `0.5.0` 发布闭环属于历史证据，不代表当前 HEAD 已执行发布。生成的 tarball、consumer、缓存和浏览器临时文件都留在被忽略的 `.tmp/` 并在测试结束后删除。
 
 ## 5. 开放事项
 
@@ -189,7 +189,7 @@ Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 W
 
 1. P0/P1/P2 及 Prototype 治理 01–07 已完成；实现提交为 `ae70304`，后续 v2 Candidate Assurance 收尾提交为 `db8abfb`，候选验证与 11 个 Gitee Issue 收尾均已完成。
 2. 后续变更继续沿当前 `.workflow/`、schema 2 与 v2 Prototype Revision 契约推进。
-3. r33 晋级改变了当前源码候选内容，历史 `0.4.0` r8 候选证据仍不可变且不能复用；该变更已在 `0.5.0` 中完成发布闭环。后续发布仍需从干净且同步的 `main` 重新生成候选，并通过 `release:check`、账号/2FA 与人工发布 Gate。
+3. r33 晋级改变了当时的源码候选内容，历史 `0.4.0` r8 候选证据仍不可变且不能复用；该变更当时已在 `0.5.0` 中完成发布闭环。本轮 `0.7.1` 维护提交已通过 `release:check`、账号/2FA 和发布后验证；后续发布仍需从干净且同步的 `main` 重新生成候选。
 
 ## 6. 继续工作时必须读取的来源
 

package/lib/delivery-state.mjs

@@ -330,6 +330,7 @@ function pauseForLockRetry() {
 function withLock(files, stream, action, lockOptions = {}) {
   const recover = lockOptions.recover !== false;
   const waitForActive = lockOptions.waitForActive === true;
+  let waitNotified = false;
   const maximumAttempts = waitForActive ? Number.POSITIVE_INFINITY : 3;
   const waitDeadline = waitForActive
     ? Date.now() + (lockOptions.waitTimeoutMs ?? ACTIVE_LOCK_WAIT_TIMEOUT_MS)
@@ -351,10 +352,20 @@ function withLock(files, stream, action, lockOptions = {}) {
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       if (recover && removeAbandonedLock(lockFile)) continue;
-      if (waitForActive && isWaitableFormalLock(lockFile) && Date.now() < waitDeadline) {
+      if (waitForActive
+        && isWaitableFormalLock(lockFile, { allowInitializing: stream !== "formal-state-read" })
+        && Date.now() < waitDeadline) {
+        if (!waitNotified && typeof lockOptions.onWait === "function") {
+          waitNotified = true;
+          lockOptions.onWait({ lockFile, stream });
+        }
         pauseForLockRetry();
         continue;
       }
+      // A live writer can release the lock between the failed open and metadata
+      // inspection. Retry that narrow race; an existing malformed/orphaned lock
+      // still falls through to the fail-closed error below.
+      if (waitForActive && !fs.existsSync(lockFile) && Date.now() < waitDeadline) continue;
       throw new Error(`Formal state is locked while updating: ${stream}`);
     }
   }
@@ -371,19 +382,28 @@ function withLock(files, stream, action, lockOptions = {}) {
   }
 }
 
-function isWaitableFormalLock(lockFile) {
+function isWaitableFormalLock(lockFile, { allowInitializing = false } = {}) {
   try {
     const content = fs.readFileSync(lockFile, "utf8");
     try {
       const owner = JSON.parse(content);
-      return typeof owner.stream === "string" && owner.stream.length > 0;
+      if (typeof owner.stream !== "string" || owner.stream.length === 0
+        || owner.stream === "formal-state-read"
+        || !Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+      try {
+        process.kill(owner.pid, 0);
+        return true;
+      } catch (error) {
+        return error.code === "EPERM";
+      }
     } catch {
+      if (!allowInitializing) return false;
       const ageMs = Date.now() - fs.statSync(lockFile).mtimeMs;
       return ageMs >= 0 && ageMs < LOCK_METADATA_INITIALIZATION_TIMEOUT_MS;
     }
   } catch (error) {
     // The owner may release the lock between our failed open and metadata read.
-    return error.code === "ENOENT";
+    return false;
   }
 }
 
@@ -935,8 +955,12 @@ function assertNoPendingTransaction(files) {
   }
 }
 
-function withReadableFormalState(files, action) {
-  return withLock(files, "formal-state-read", action, { recover: false });
+function withReadableFormalState(files, action, lockOptions = {}) {
+  return withLock(files, "formal-state-read", action, {
+    recover: false,
+    waitForActive: true,
+    onWait: lockOptions.onWait,
+  });
 }
 
 function withZeroWriteFormalState(files, action) {
@@ -2533,7 +2557,10 @@ function transitionWorkflow(files, flags, options) {
     });
     if (completionReceipt) result.completion_receipt = completionReceipt;
     return result;
-  }, { waitForActive: flags.has("--expected-scope-revision") });
+  }, {
+    waitForActive: flags.has("--expected-scope-revision"),
+    onWait: options.onLockWait,
+  });
 }
 
 function registeredEvidence(files, evidence, options, node = null) {
@@ -3208,6 +3235,7 @@ export function executeDeliveryStateCommand(argv, options = {}) {
           history: flags.has("--history"),
           sinceAnchor: flags.has("--since-anchor"),
         }),
+        { onWait: options.onLockWait },
       );
     } else if (command === "snapshot" && positional[1] === "create") {
       result = createFormalSnapshot(files, flags, options);
@@ -3234,7 +3262,7 @@ export function executeDeliveryStateCommand(argv, options = {}) {
           scope_manifest: currentScopeManifest(workflowState.development_state),
           derived_node_states: deriveNodeStates(files, workflowState, artifactRegistry, options),
         };
-      });
+      }, { onWait: options.onLockWait });
     } else {
       throw new Error(
         "Use inspect, verify, rebuild, snapshot create, artifact register/prune, scope freeze/amend/warn, "

package/lib/project-installer.mjs

@@ -243,8 +243,13 @@ function managedFilesEqual(left, right) {
 
 function directoryDigest(root) {
   const hash = crypto.createHash("sha256");
-  for (const file of filesUnder(root)) {
-    const relative = path.relative(root, file).replaceAll("\\", "/");
+  const entries = filesUnder(root)
+    .map((file) => ({
+      file,
+      relative: path.relative(root, file).replaceAll("\\", "/"),
+    }))
+    .sort((left, right) => left.relative.localeCompare(right.relative));
+  for (const { file, relative } of entries) {
     hash.update(relative);
     hash.update("\0");
     hash.update(normalizedManagedContent(file));
@@ -292,8 +297,14 @@ function exactPathDigest(target) {
 
 function sourceSetDigest(sources) {
   const hash = crypto.createHash("sha256");
-  for (const item of [...sources].sort((left, right) => left.relative.localeCompare(right.relative))) {
-    hash.update(item.relative.replaceAll("\\", "/"));
+  const entries = [...sources]
+    .map((item) => ({
+      item,
+      relative: item.relative.replaceAll("\\", "/"),
+    }))
+    .sort((left, right) => left.relative.localeCompare(right.relative));
+  for (const { item, relative } of entries) {
+    hash.update(relative);
     hash.update("\0");
     hash.update(normalizedManagedContent(item.source));
     hash.update("\0");

package/lib/workspace.mjs

@@ -113,7 +113,10 @@ function initializeWorkflowRepository(workspaceRoot, branch, remote, heads, acti
     const current = gitBranch(workspaceRoot);
     if (current !== branch) {
       if (gitHasCommit(workspaceRoot)) {
-        throw new Error(`Existing workflow repository must already use ${branch}; automatic branch changes are not supported.`);
+        throw new Error(
+          `Existing workflow repository must already use ${branch}; automatic branch changes are not supported. `
+          + `Create or switch to the required branch with 'git switch -c ${branch}' and rerun init.`,
+        );
       }
       if (!dryRun) runGit(workspaceRoot, ["symbolic-ref", "HEAD", `refs/heads/${branch}`]);
     }

package/package.json

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