ai-delivery-workflow 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Delivery Workflow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# AI Delivery Workflow
+
+本仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装后的业务工作区，也不按双仓项目进行初始化。`bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/` 都是工作流实现或直接物料；`.tmp/` 统一保存可丢弃的本地运行物料。
+
+本仓库发布的工作流在安装到业务项目后，固定采用“工作流控制仓库 + 嵌套代码仓库”的双仓工作区：工作流仓库跟踪 `.workflow/` 和共享 checkpoint，独立的 `code/` Git 仓库跟踪应用源码、测试、分支和 Tag。详见 [双仓工作区说明](docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
+
+一套只安装到当前项目的 AI 全流程研发 Skills、Hook、产物契约和 checkpoint 机制。研发版本可以持续递进并归档为 `release-ready`；生产发布由用户独立触发并选择累计截止版本。
+
+体验设计采用分阶段可运行原型：先交付可实际操作的低保真原型并通过人工 `UX-LF`，再确认视觉系统和 UI 框架（`UX-VS`），最后交付可运行正式 UI（`UX-UI`）。每次调整立即记录；全部候选确认后统一与产品需求双向核对。下游只消费 `ui-handoff.yaml` 和结构化 `experience_change_id`，不从截图或视觉差异猜测新增、修改与停用内容。
+
+## 文档
+
+- [维护仓库 AI 边界](AGENTS.md)
+- [完整中文项目手册](docs/PROJECT-MANUAL.zh-CN.md)
+- [双仓工作区使用与维护说明](docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md)
+- [逐文件参考](docs/FILE-REFERENCE.zh-CN.md)
+- [工作流物料查看器使用指南](docs/VIEWER-USER-GUIDE.zh-CN.md)
+- [工作流物料查看器维护指南](docs/VIEWER-MAINTENANCE.zh-CN.md)
+- [正式状态 CLI 使用指南](docs/STATE-CLI-USER-GUIDE.zh-CN.md)
+- [正式状态 CLI 维护指南](docs/STATE-CLI-MAINTENANCE.zh-CN.md)
+- [审计物料：历史 V1、当前契约 V2 与五版本发布列车示例](audit/README.md)
+- [审计物料逐文件用途](audit/FILE-GUIDE.zh-CN.md)
+- [永久验证源码说明](verification/README.zh-CN.md)
+
+## 快速开始
+
+在目标项目根目录安装，不修改用户全局 Codex 或 agent skill 目录：
+
+```bash
+npx ai-delivery-workflow@latest init <workspace> --code-path code --code-id app
+npx ai-delivery-workflow@latest doctor <workspace>
+```
+
+安装器会把 25 个 Skills 写入 `.agents/skills/`，把项目 Hook 合并到 `.codex/config.toml`，安装本地 Hook 记录器，并创建 `.workflow/iterations/`、`.workflow/releases/` 与项目级自进化控制环。所有研发流程文档默认写入 `.workflow/`；源码、自动化测试源码、仓库配置、镜像和二进制制品保留在各自原位置。安装器会保留既有项目配置，并在受管文件冲突时停止。
+
+安装器会在需要跨 Git clone 保留的空工作流目录中写入 `.gitkeep`，包括产品、架构、体验、迭代、发布及共享控制分片目录。删除这些占位文件会导致空目录不进入 Git，重新克隆后的 `doctor` 将判定核心结构缺失。
+
+安装器还会内置 Bootstrap 与正式状态 CLI。任务状态只能由 `task-state.mjs` 修改；正式流程、物料和 Gate 状态只能由项目内状态脚本修改：
+
+```bash
+node .workflow/tools/bootstrap/bootstrap.mjs inspect
+node .workflow/tools/state/state.mjs inspect
+node .workflow/tools/state/state.mjs verify
+```
+
+安装器会合并根 `.gitattributes`，把工作流受控文本固定为 LF，避免 Windows checkout 改变正式物料字节并触发 checksum 误报；该规则不进入嵌套代码仓。
+
+日常使用无需记忆这些命令。用户在项目根目录对 AI 说“开始”“继续”“下一步”或直接描述需求即可；AI 根据项目内 `AGENTS.md` 和 Skills 自主调用 Bootstrap、Checkpoint、专业节点与发布流程，用户只负责业务回答和人工 Gate。中断任务通过 `next_action_owner` 区分 AI、用户和外部责任方；等待用户或外部输入时只读恢复，不得重复增加 attempt、revision、evidence 或 checkpoint。
+
+正式状态 schema 2 将研发与发布拆成 `development_state` 和 `release_state`。研发使用 `iteration-started`，用户明确发起发布后使用 `release-started`；两者分别维护 scope、节点、Gate 和局部 revision，可并行推进且互不重置。状态 CLI 同时强制节点依赖、成功证据和当前节点尝试的必需 Gate。
+
+版本归档的可携带权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档成功后，对应任务和 checkpoint 会从活动集合移出，后续 `recover` 不再加载它们。`doctor` 使用发行包固定的 25 个 Skill 与受管 Hook、Bootstrap、状态和 Evolution 运行时摘要进行完整性检查，并实际执行只读 `inspect/verify` 冒烟验证；查看器仍是可选工具。
+
+安装后的工作流通过 `$ai-delivery-evolve-workflow` 在安全点记录反馈、聚合重复信号、试运行项目级扩展并按指标自动启用或回退。扩展只存在于 `.workflow/extensions/`，不能修改受管核心、正式状态、人工 Gate 或已批准规范。完整用法见[自进化使用指南](docs/EVOLUTION-USER-GUIDE.zh-CN.md)。
+
+禁止直接编辑正式状态 YAML、审计 JSONL 或 runtime 任务状态。命令失败时应处理 revision 冲突或输入问题，不得手工绕过。
+
+累计研发版本、当前生产版本和当前生产 release ID 的权威来源是 `.workflow/delivery/workflow-state.yaml` 中经审计事件写入的 `latest_line_version_id`、`production_version_id` 和 `production_release_id`。版本收尾使用 `version-closed`，发布归档使用 `release-archived`；`project.yaml` 中的同名旧字段只作兼容回退。
+
+安装完成后直接启动项目内的工作流物料查看器：
+
+```powershell
+.\.workflow\tools\viewer\start.cmd
+```
+
+查看器默认打开 `http://127.0.0.1:4173`，实时扫描当前项目 `.workflow/`，分别展示研发和发布轨道、生产版本、累计研发版本、发布范围、物料关系、checksum 与文档预览。它不修改正式产物。
+查看器是 `.workflow/tools/` 下的可选只读工具；删除 `.workflow/tools/viewer/` 不影响状态 CLI、Checkpoint、恢复、研发或发布，再次执行 `init` 可重装查看器。
+
+研发完成不会自动上线。用户需要发布时明确选择截止版本：
+
+```text
+请发布至 VER-0005。
+```
+
+系统会计算当前生产版本之后到 `VER-0005` 的连续版本范围。同版本重新发布也会生成新 release ID，并重新进行环境快照、验证和生产审批。
+
+只读检查陌生项目：
+
+```bash
+npx ai-delivery-workflow@latest inspect .
+```
+
+识别并初始化空项目或存量代码项目，或者把中断工作流路由到 checkpoint 恢复：
+
+```bash
+npx ai-delivery-workflow@latest bootstrap .
+```
+
+预览或明确替换冲突的受管文件：
+
+```bash
+npx ai-delivery-workflow@latest init . --dry-run
+npx ai-delivery-workflow@latest init . --force
+```
+
+`--force` 会先备份到 `.workflow/delivery/runtime/backups/`。初始化完成后请新建 Codex 任务，使项目级 skills 和 Hook 信任状态重新加载。
+
+旧项目如仍使用根目录 `delivery/` 和 `standards/`，需先迁移为 `.workflow/delivery/` 和 `.workflow/standards/`，同步更新产物引用与 checksum 后再执行 `init`。安装器不会在新旧两套状态之间自动选择权威来源。
+
+## 仓库内容边界
+
+本工作流维护仓库把长期资产分为源码、永久验证源码和审计物料。安装器、状态 CLI、Hook、Skill、查看器等通用自动化验证统一位于 `verification/` 并纳入 Git；可重建的全流程交付证据与历史快照位于 `audit/` 并纳入 Git，但不会被 `init` 安装到业务项目。
+
+所有测试工作区、缓存、日志、报告、临时 Git 仓库、npm cache、打包产物、认证辅助文件和绑定单次演练的脚本统一放入 `.tmp/`。根 `.gitignore` 整体忽略 `/.tmp/`，其中任何内容都不得作为权威源码或审计证据。`audit/` 候选包、部署副本和历史快照内嵌的应用测试属于审计物料，可保留原路径；执行这些校验的维护入口位于 `verification/`。
+
+```bash
+npm test
+npm run skills:validate
+npm run audit:verify
+```
+
+`npm run skills:validate` 使用项目已有的 Node.js `yaml` 依赖校验全部 25 个 Skill，无需 Python 或 `PyYAML`。它检查 `SKILL.md` frontmatter、目录名称、`agents/openai.yaml` 界面元数据，以及项目手册和文件参考中的 Skill 覆盖关系；任一错误都会返回非零退出码。该校验只属于本维护仓库，不会安装到业务项目。

package/bin/ai-delivery.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { executeDeliveryStateCommand } from "../lib/delivery-state.mjs";
+import { dispatchEvolutionHookEvent, executeEvolutionCommand } from "../lib/evolution.mjs";
+import { doctorProject, initProject } from "../lib/project-installer.mjs";
+import { bootstrapProject, inspectProjectState } from "../lib/project-bootstrap.mjs";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+function usage() {
+  return `ai-delivery ${packageJson.version}
+
+Usage:
+  ai-delivery init [workspace-directory] [--workspace-id id] [--code-path code] [--code-id app] [--code-remote <url>] [--workflow-remote <url>] [--shared-remote <url>] [--dry-run] [--force]
+  ai-delivery inspect [workspace-directory]
+  ai-delivery bootstrap [workspace-directory] [--dry-run] [--force]
+  ai-delivery doctor [workspace-directory]
+  ai-delivery state <state-command> [options]
+  ai-delivery evolve <evolution-command> [options]
+  ai-delivery --version
+
+Commands:
+  init     Create a workflow repository and bind or create one nested code repository
+  inspect  Detect workspace, code repository, workflow, and runtime state without writes
+  bootstrap  Initialize missing workflow context or route recovery safely
+  doctor   Validate the current project-scoped installation
+  state    Inspect, verify, and mutate formal workflow state through the guarded CLI
+  evolve   Record feedback and govern project-local workflow extensions
+
+Options:
+  --dry-run  Show planned changes without writing files
+  --force    Back up and replace conflicting managed files
+  --code-path  Nested code repository directory (default: code)
+  --code-id    Stable code repository identifier (default: app)
+  --code-remote  Clone this remote when the code directory does not exist
+  --workflow-remote  Configure the workflow repository origin
+  --shared-remote  Configure both independent repositories with the same origin
+  --workspace-id  Stable ID used by workflow/<workspace-id>
+`;
+}
+
+function parseArgs(argv) {
+  const flags = new Set();
+  const options = new Map();
+  const positional = [];
+  const booleanOptions = new Set(["--dry-run", "--force", "--help", "--version"]);
+  const valueOptions = new Set([
+    "--code-path", "--code-id", "--code-remote", "--workflow-remote", "--shared-remote", "--workspace-id",
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (booleanOptions.has(value)) {
+      flags.add(value);
+    } else if (valueOptions.has(value)) {
+      const optionValue = argv[index + 1];
+      if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing value for ${value}`);
+      options.set(value, optionValue);
+      index += 1;
+    } else if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    } else {
+      positional.push(value);
+    }
+  }
+  return { flags, options, positional };
+}
+
+try {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "state" || rawArgs[0] === "evolve") {
+    const execute = rawArgs[0] === "state" ? executeDeliveryStateCommand : executeEvolutionCommand;
+    const yaml = {
+      parse: parseYaml,
+      stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
+    };
+    const result = execute(rawArgs.slice(1), {
+      yaml,
+      onLifecycleEvent: rawArgs[0] === "state"
+        ? (event) => dispatchEvolutionHookEvent(event.scope.project_root, event, { yaml })
+        : undefined,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (rawArgs[0] === "evolve" && result?.ok === false) process.exitCode = 1;
+  } else {
+    const { flags, options, positional } = parseArgs(rawArgs);
+    if (flags.has("--help") || positional[0] === "help") {
+    process.stdout.write(usage());
+    } else if (flags.has("--version")) {
+      process.stdout.write(`${packageJson.version}\n`);
+    } else {
+      const command = positional[0] || "init";
+      const target = path.resolve(positional[1] || process.cwd());
+      if (command === "init") {
+        const report = initProject(packageRoot, target, {
+          dryRun: flags.has("--dry-run"),
+          force: flags.has("--force"),
+          packageVersion: packageJson.version,
+          codePath: options.get("--code-path"),
+          codeId: options.get("--code-id"),
+          codeRemote: options.get("--code-remote") || null,
+          workflowRemote: options.get("--workflow-remote") || null,
+          sharedRemote: options.get("--shared-remote") || null,
+          workspaceId: options.get("--workspace-id") || null,
+        });
+        process.stdout.write(`${report.summary}\n`);
+        for (const item of report.actions) process.stdout.write(`- ${item}\n`);
+      } else if (command === "inspect") {
+        const report = inspectProjectState(target);
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "bootstrap") {
+        const report = bootstrapProject(packageRoot, target, {
+          dryRun: flags.has("--dry-run"),
+          force: flags.has("--force"),
+          packageVersion: packageJson.version,
+          initProject,
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "doctor") {
+        const report = doctorProject(target);
+        for (const check of report.checks) {
+          const outcome = check.ok ? "PASS" : check.required === false ? "WARN" : "FAIL";
+          process.stdout.write(`${outcome} ${check.message}\n`);
+        }
+        if (!report.ok) process.exitCode = 1;
+      } else {
+        throw new Error(`Unknown command: ${command}\n\n${usage()}`);
+      }
+    }
+  }
+} catch (error) {
+  process.stderr.write(`ai-delivery: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/bin/validate-skills.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { validateSkillRepository } from "../lib/skill-validator.mjs";
+
+const report = validateSkillRepository(process.cwd());
+if (report.valid) {
+  console.log(`Skill validation passed: ${report.skillCount}/${report.skillCount}`);
+} else {
+  console.error(`Skill validation failed with ${report.errors.length} error(s):`);
+  for (const error of report.errors) console.error(`- ${error}`);
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,125 @@
+# 双仓工作区使用与维护说明
+
+## 1. 目录与职责
+
+AI Delivery 固定使用两个彼此独立的 Git 仓库：
+
+```text
+workspace/
+├─ .git/                         # 工作流 Git
+├─ .agents/                      # 25 个项目级 Skills
+├─ .codex/                       # 项目 Hook 配置
+├─ .workflow/config/workspace.yaml   # 双仓唯一绑定配置
+├─ .workflow/                    # 流程物料、共享任务与 checkpoint
+├─ .gitignore                    # 精确忽略 /code/
+├─ .gitattributes               # 固定工作流受控文本为 LF
+└─ code/
+   ├─ .git/                      # 代码 Git
+   ├─ src/
+   └─ test/
+```
+
+工作流仓库的 `workflow/<workspace-id>` 是已经共享的流程事实分支，不表示生产代码。代码仓库的 `main` 才表示生产验证成功的应用历史。代码目录不是 Git submodule：根仓库通过精确的 `/code/` 忽略规则完全不跟踪它，代码仓库也不跟踪父目录。
+
+## 2. 初始化
+
+创建新工作区和空代码仓库：
+
+```powershell
+node bin/ai-delivery.mjs init C:\work\tasklite --code-path code --code-id tasklite-app
+node bin/ai-delivery.mjs doctor C:\work\tasklite
+```
+
+从已有 remote 创建代码仓库：
+
+```powershell
+node bin/ai-delivery.mjs init C:\work\tasklite --code-path code --code-id tasklite-app --code-remote <url>
+```
+
+两个独立本地 Git 使用同一个远程仓库、不同分支命名空间时：
+
+```powershell
+node bin/ai-delivery.mjs init C:\work\tasklite --workspace-id tasklite --code-path code --code-id tasklite-app --shared-remote <url>
+```
+
+工作流仓库使用 `workflow/tasklite`，代码仓库使用 `main` 及各研发、发布分支；两者虽然 origin 相同，但 Git 根和提交历史职责独立。
+
+升级仍含 `.ai-delivery/` 的旧项目时，`init` 会先把旧目录完整备份到 `.workflow/delivery/runtime/backups/<timestamp>/legacy-ai-delivery/`，再迁移配置、状态 CLI、Hook 和查看器。只有新核心文件验证完成后才删除旧目录；失败时保留旧目录和备份。迁移成功后 `.workflow/config/workspace.yaml` 是唯一权威配置，不再双写或回退读取旧路径。
+
+如果 `code/` 已是独立 Git 仓库，初始化器会绑定它。以下情况会拒绝：非空但不是 Git 的代码目录、绝对路径或多层路径、越界路径、符号链接、与工作流仓库相同的 Git 根。
+
+`.workflow/config/workspace.yaml` 是代码仓库位置和 `repo_id` 的唯一来源。不要在 Skill、脚本或文档中另行猜测代码根目录。
+
+已有项目再次执行 `init` 时，未显式提供 `--code-path` 或 `--code-id` 必须沿用该文件中的现有值；只有用户显式传入对应参数时才允许改变稳定代码仓身份。
+
+## 3. 状态分层
+
+Git 跟踪、可由其他工作区接管的状态：
+
+```text
+.workflow/control/
+  tasks/<task-id>.yaml
+  checkpoints/<task-id>/<checkpoint-id>.yaml
+  artifacts/
+  gates/
+  versions/
+  releases/
+```
+
+本机临时状态位于 `.workflow/delivery/runtime/`，只保存 PID、心跳、临时锁、原始 Hook 事件和未共享上下文。每次任务状态变化都要通过 `task-state.mjs` 更新共享分片；高频心跳只写 runtime。
+
+本机 runtime 被删除后，`agent` 责任态由 `recover` 从最新共享任务与 checkpoint 重建；`user/external` 等待态保持只读，收到输入后由 `activate` 原子重建并转交。本机和共享 `shared_revision` 或语义 checksum 不一致时必须停止处理冲突，不能按最后写入者覆盖。
+
+Git 不跟踪空目录。安装器会在 `.workflow/product/`、`architecture/`、`experience/`、`iterations/`、`releases/` 和 `.workflow/control/` 各分片目录中创建 `.gitkeep`。这些文件确保工作流分支被重新克隆后仍保留 Doctor 所需结构；不得把它们当作无用测试产物删除。
+
+只提交一个任务范围：
+
+```powershell
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs publish --task-id TASK-001
+```
+
+该命令发现无关脏文件时拒绝提交。默认不推送，只有用户明确要求时才使用 `--push`。
+
+## 4. 两套 Git 的操作边界
+
+只在代码仓库存在：`main`、`line/*`、`version/*`、`work/*`、`release/*`、`release-fix/*`、`hotfix/*`、`version-ready/*` 和 release Tag。
+
+只在工作流仓库存在：`.workflow/` 中的需求、架构、原型、测试、审批、部署和回滚记录，共享任务分片和 checkpoint，以及 `workflow-ready/<version-id>/rN`。
+
+每个代码引用至少记录：`repo_id`、`code_commit`、可选 `code_tag`、`source_path` 和 SHA-256。
+
+## 5. 版本收尾与发布身份
+
+版本收尾顺序不可调整：
+
+1. 在代码仓库验证候选；
+2. 创建代码 `version-ready/<version-id>/rN`；
+3. 生成最终版本 Manifest；
+4. 提交版本工作流物料；
+5. 在该提交创建工作流 `workflow-ready/<version-id>/rN`。
+
+`release-ready` 身份由代码 Tag、工作流 Tag 和 Manifest SHA-256 三者组成。发布闭包同时检查代码 ancestry、两个 Tag、Manifest checksum、连续版本关系和 `repo_id`。任一项缺失或漂移都阻止发布。
+
+`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 分片被移除，普通恢复不会重新加载历史版本。
+
+同版本重发复用原版本三方身份，但必须创建新 release ID，并重新生成环境快照、发布索引、验证和审批。生产回滚只部署历史镜像 digest，不创建 rollback 分支，不改写任一 Git 历史。
+
+## 6. 检查与查看
+
+```powershell
+node <workspace>/.workflow/tools/bootstrap/bootstrap.mjs inspect
+node bin/ai-delivery.mjs doctor <workspace>
+node bin/ai-delivery.mjs state verify --project <workspace>
+```
+
+安装后，用户只需在项目根对 AI 说“开始”“继续”“下一步”或直接描述需求；AI 自主调用项目内 Bootstrap、Checkpoint 和后续 Skills。项目内 `inspect` 同时报告工作流 Git 和代码 Git 的 branch、head、dirty paths、upstream 同步状态，以及共享任务/checkpoint 恢复建议。查看器展示两套 Git、未提交或未推送警告、研发和发布双轨，以及代码 Tag、工作流 Tag、Manifest checksum 的追踪关系。
+
+## 7. 全流程样本
+
+```powershell
+node audit/generate-dual-repo.mjs
+```
+
+真实 Git 元数据位于被根 `.gitignore` 排除的 `.tmp/dual-repo-e2e/`。可审阅快照位于 `audit/DUAL-REPO-FULL-FLOW/`，不包含任何 `.git` 目录，也不会被安装到业务项目。

package/docs/EVOLUTION-MAINTENANCE.zh-CN.md

@@ -0,0 +1,75 @@
+# 项目级工作流自进化维护指南
+
+## 1. 权威源码
+
+| 位置 | 职责 |
+| --- | --- |
+| `lib/evolution.mjs` | 状态机、风险、checksum、trial、Hook 调度和导出实现 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/evolution/evolve.mjs` | 安装后自包含 wrapper |
+| `skills/ai-delivery-evolve-workflow/` | AI 交互、证据门槛和治理契约 |
+| `lib/project-installer.mjs` | 运行时复制、manifest schema 5、升级和 doctor |
+| `verification/evolution.test.mjs` | 公共 CLI 行为测试 |
+
+不要修改临时安装项目中的 `.workflow/tools/evolution/` 后再复制回维护仓库。`lib/evolution.mjs` 是行为权威，安装副本由 `init` 生成。
+
+## 2. 安装模型
+
+安装器把 wrapper 和 `lib/evolution.mjs` 复制为：
+
+```text
+.workflow/tools/evolution/evolve.mjs
+.workflow/tools/evolution/evolution-runtime.mjs
+```
+
+它复用 `.workflow/tools/state/vendor/yaml/`，不修改业务项目 `package.json`。安装清单 schema 5 保存 Evolution CLI 路径、Hook 协议版本和运行时 SHA-256。schema 4 项目重新执行 `init` 时升级受管运行时，同时保留既有工作流物料。
+
+## 3. 数据一致性
+
+- 所有治理状态转换必须经过 `executeEvolutionCommand`。
+- 写入采用临时文件加原子 rename。
+- 扩展版本复制到 `.workflow/extensions/<id>/versions/<version>/` 后不可原地修改。
+- 批准绑定扩展 checksum；内容变化必须注册新版本。
+- runtime 事件按 `idempotency_key` 去重，正式反馈按同一来源幂等。
+- 扩展损坏只隔离扩展，不使核心研发、Checkpoint 和发布运行时不可用。
+
+## 4. 风险引擎
+
+风险顺序固定为 `low < medium < high`。requested risk 只能被派生风险抬升；未登记的 capability 默认按 `high` 处理。新增 capability 时必须同步：
+
+1. `HIGH_CAPABILITIES` 或 `MEDIUM_CAPABILITIES`；
+2. Skill 契约和用户指南；
+3. 风险抬升测试；
+4. 查看器展示需要的新状态。
+
+`block` 或 `.mjs` entrypoint 永远派生为 high。Node 18 没有可依赖的强安全沙箱，因此不要在文档或代码中宣称脚本被完全隔离。
+
+## 5. Hook 协议
+
+Hook schema 1 要求 `event_id`、`idempotency_key`、`event_type`、时间、scope 和脱敏 payload。结果只允许 `pass`、`warn`、`block`；`block` 仅允许声明在 `before` 事件。Hook 输出必须经过 `normalizeHookOutcome` 的类型、数量、长度和脱敏处理后才能返回或写入正式审计物料。
+
+`skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs` 是安装源；项目模板内同名文件是审阅副本，两者必须保持一致。Checkpoint 的 `task-state.mjs` 和正式状态 CLI 会主动发出业务协议事件；Codex 原生生命周期事件只记录 heartbeat。带 `schema_version: 1` 和 `event_type` 的 Evolution 事件才会进入扩展调度。
+
+## 6. 查看器
+
+查看器只解析 `.workflow/evolution/index.yaml` 和 Git 跟踪的 evolution 文件。不得扫描 `.workflow/delivery/runtime/evolution/`，不得新增写 API。修改自进化摘要时同步验证桌面和移动端布局。
+
+## 7. 验证
+
+定向验证：
+
+```bash
+node --test verification/evolution.test.mjs
+node --test verification/project-installer.test.mjs
+node --test verification/workflow-viewer.test.mjs
+npm run skills:validate
+```
+
+交付前执行：
+
+```bash
+npm test
+npm run audit:verify
+npm run pack:check
+```
+
+还应在隔离项目执行 `init`、项目内 `evolve inspect/verify`、`doctor`，删除查看器和扩展后复核核心工作流仍可运行。

package/docs/EVOLUTION-USER-GUIDE.zh-CN.md

@@ -0,0 +1,160 @@
+# 项目级工作流自进化使用指南
+
+## 1. 能力边界
+
+自进化控制环记录工作流使用中的明确意见和客观问题，在任务、版本或显式 review 安全点评估证据，通过项目级扩展改善后续执行。它不是第三条研发状态机，也不能修改安装器管理的 Skill、正式状态 CLI、Hook、人工 Gate 或已批准项目规范。
+
+删除 `.workflow/extensions/` 不会破坏核心研发、Checkpoint 或发布流程。`doctor` 会报告扩展问题，但核心检查仍可运行。
+
+## 2. 文件位置
+
+```text
+.workflow/evolution/                 # 纳入工作流 Git
+  feedback/                          # 脱敏反馈
+  proposals/                         # 提案
+  experiments/                       # trial 与 Hook 结果
+  decisions/                         # 启停、批准、回退和冲突证据
+  promotion/                         # 仅本地生成的脱敏导出包
+.workflow/extensions/                # 已注册的不可变扩展版本
+.workflow/delivery/runtime/evolution/ # 被忽略的事件、pending 和 staging
+```
+
+`.workflow/evolution/index.yaml` 是治理索引，只能由 Evolution CLI 修改。
+
+公共命令如下：
+
+| 命令 | 作用 |
+| --- | --- |
+| `feedback record` | 记录脱敏反馈或客观信号 |
+| `inspect` | 读取治理索引 |
+| `evaluate` | 在安全点计算提案资格或记录 trial 指标 |
+| `propose --spec <file>` | 校验提案证据并登记提案 |
+| `register --proposal-id <id> --source <dir>` | 校验、复制并 checksum 一个扩展版本 |
+| `approve` / `reject` | 记录明确人工批准或拒绝 |
+| `enable` / `disable` / `rollback` | 启动 trial、稳定启用、禁用或回退 |
+| `verify` | 校验 schema、manifest、扩展和批准 checksum |
+| `export` | 生成仅限本地的脱敏 promotion bundle |
+
+## 3. 反馈
+
+当用户明确表达“以后应当”“这里不合理”“建议调整”等改进意图时，AI 自动记录反馈并返回 `FDB-*`。反馈只保存分类、摘要、影响、来源事件、关联任务或版本、脱敏片段和 SHA-256。
+
+```bash
+node .workflow/tools/evolution/evolve.mjs feedback record \
+  --category workflow-usability \
+  --summary "状态更新应统一通过脚本" \
+  --impact "避免状态文件错乱" \
+  --source-kind user \
+  --source-event-id TURN-001 \
+  --signal-key state-mutation-bypass \
+  --idempotency-key feedback-turn-001 \
+  --explicit-user
+```
+
+禁止保存完整对话、密钥、敏感配置和 chain-of-thought。单次 AI 推测使用 `ai-observation`，不能单独形成提案。
+
+## 4. 证据门槛与安全点
+
+以下情况可以进入提案：
+
+- 用户明确建议；
+- 一次明确 Gate 阻断或版本失败；
+- 同类客观问题出现三个不同事件；
+- 同类客观问题影响两个不同任务。
+
+只在以下安全点评估：
+
+```bash
+node .workflow/tools/evolution/evolve.mjs evaluate --safe-point task
+node .workflow/tools/evolution/evolve.mjs evaluate --safe-point version --iteration-id VER-05
+node .workflow/tools/evolution/evolve.mjs evaluate --safe-point review
+```
+
+评估产生的扩展从下一任务或下一版本生效，不改变执行中的任务。
+
+## 5. 风险与批准
+
+| 风险 | 能力 | 自动权限 |
+| --- | --- | --- |
+| `low` | 提示、清单、展示、非阻断声明式检查 | 验证后可自动 trial，最多 `warn` |
+| `medium` | 路由、模板、工作包、物料生成或校验行为 | 必须人工批准 |
+| `high` | `block`、Node 脚本、Git、部署、安全、权限、环境或外部系统 | 必须人工批准 |
+
+AI 可以建议风险，CLI 只能把风险提高。批准必须先形成一条明确用户确认回执，再绑定扩展 ID、版本、SHA-256 和来源事件：
+
+```bash
+node .workflow/tools/evolution/evolve.mjs feedback record \
+  --category extension-approval \
+  --summary "批准已审阅的阻断扩展" \
+  --impact "允许该版本进入试运行" \
+  --source-kind user \
+  --source-event-id TURN-APPROVE-001 \
+  --signal-key approve-ext-gate-check \
+  --explicit-user \
+  --confirmation-subject EXT-GATE-CHECK@1.0.0 \
+  --confirmation-checksum <sha256>
+
+node .workflow/tools/evolution/evolve.mjs approve \
+  --extension-id EXT-GATE-CHECK \
+  --version 1.0.0 \
+  --checksum <sha256> \
+  --confirmation-feedback-id FDB-0004
+
+node .workflow/tools/evolution/evolve.mjs enable \
+  --extension-id EXT-GATE-CHECK \
+  --version 1.0.0 \
+  --checksum <sha256> \
+  --safe-point review
+```
+
+`enable` 和 trial 评估必须声明 `task`、`version` 或 `review` 安全点；存在活动任务标记时 CLI 会拒绝生效。扩展只能按 `proposed -> trial -> active` 前进，已禁用、回退、替代或过期的版本不能复活，内容调整必须注册新版本。仅把文件放入 `.workflow/extensions/` 不会执行。
+
+## 6. Trial 与回退
+
+每个提案必须包含假设、基线、指标、范围和回退条件。默认观察窗口是三次适用执行或一个完整迭代，以先到者为准。
+
+```bash
+node .workflow/tools/evolution/evolve.mjs evaluate \
+  --safe-point task \
+  --extension-id EXT-DOC-WARN \
+  --version 1.0.0 \
+  --metric-result improved \
+  --event-id TASK-RESULT-003
+```
+
+低风险 trial 达标后自动进入 `active`。`worsened` 或 `failure` 会自动进入 `rolled-back`。中高风险即使 trial 达标，也必须明确批准后才能稳定启用。
+
+生命周期为：
+
+```text
+observed → proposed → trial → active
+                       ├→ rejected
+                       ├→ disabled
+                       ├→ rolled-back
+                       ├→ superseded
+                       └→ expired
+```
+
+系统不会按日期或版本数量自动过期提案。`expired` 只表示用户明确关闭或适用对象已客观消失。
+
+## 7. Hook
+
+Hook 输入和输出使用 schema 1 JSON。Checkpoint 任务脚本与正式状态 CLI 会自动产生任务、节点、Gate、物料、版本和发布的 `before`、`after`、`failed`，另支持 `feedback-recorded`、`evaluation-due` 和 `extension-state-changed`。
+
+`block` 只允许用于 `before`，避免状态写入后再阻断。自动 trial 的错误或超时以 `warn` 继续；已批准阻断 Hook 失败时停止本次转换并隔离扩展。Hook 输出会先做类型、数量、长度和脱敏检查，再返回或写入审计物料。Node 18 下的导入检查、最小环境变量、路径校验和超时不是安全沙箱；可执行 Hook 始终按高风险处理。
+
+## 8. 检查、禁用和导出
+
+```bash
+node .workflow/tools/evolution/evolve.mjs inspect
+node .workflow/tools/evolution/evolve.mjs verify
+node .workflow/tools/evolution/evolve.mjs disable --extension-id EXT-001 --version 1.0.0 --checksum <sha256> --reason "与项目规范冲突"
+node .workflow/tools/evolution/evolve.mjs rollback --extension-id EXT-001 --version 1.0.0 --checksum <sha256> --reason "指标恶化"
+node .workflow/tools/evolution/evolve.mjs export --extension-id EXT-001 --version 1.0.0
+```
+
+`export` 只在 `.workflow/evolution/promotion/` 生成脱敏、本地 bundle，不会上传或发送到维护仓库、其他项目或外部服务。
+
+## 9. 查看器
+
+查看器的“自进化控制环”区域展示反馈、待处理提案、trial、active、高风险生效、回退和 Hook 结果数量。所有治理物料仍可在物料表中筛选和预览。查看器没有批准、启用、回退或导出接口。