ai-delivery-workflow 0.2.2

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

@@ -0,0 +1,503 @@
+# AI Delivery Workflow 文件参考
+
+> 当前双仓目录、初始化规则、状态分层和 Git 边界见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
+
+> 适用目录：工作流发行仓库  
+> 适用包版本：`ai-delivery-workflow@0.2.0`
+> 使用方法和完整流程：[PROJECT-MANUAL.zh-CN.md](PROJECT-MANUAL.zh-CN.md)  
+> 查看器使用：[VIEWER-USER-GUIDE.zh-CN.md](VIEWER-USER-GUIDE.zh-CN.md)  
+> 查看器维护：[VIEWER-MAINTENANCE.zh-CN.md](VIEWER-MAINTENANCE.zh-CN.md)  
+> 正式状态使用：[STATE-CLI-USER-GUIDE.zh-CN.md](STATE-CLI-USER-GUIDE.zh-CN.md)  
+> 正式状态维护：[STATE-CLI-MAINTENANCE.zh-CN.md](STATE-CLI-MAINTENANCE.zh-CN.md)  
+> 审计物料逐文件说明：[../audit/FILE-GUIDE.zh-CN.md](../audit/FILE-GUIDE.zh-CN.md)
+
+## 1. 阅读说明
+
+本文解释发行源码、skills、模板、测试和示例文件的职责。对于内容和职责完全同构的大量文件，使用明确路径模式说明，避免重复 90 份相同描述。
+
+文件分为四类：
+
+| 类型 | 说明 |
+| --- | --- |
+| 发行源码 | npm 包实际发布并用于安装目标项目的 `bin/`、`lib/`、`skills/` 和 `docs/`。 |
+| 永久验证 | 根配置和 `verification/` 中的通用测试与审计校验器，用于维护本发行仓库。 |
+| 审计物料 | `audit/` 中 TaskLite 历史 V1 证据与当前契约 ITER-V2 物料，纳入 Git，但不会安装到目标项目。 |
+| 临时物料 | `.tmp/` 中的测试工作区、缓存、日志、报告、临时仓库、打包文件和单次场景脚本，整体忽略且可丢弃。 |
+
+## 2. 根目录
+
+| 路径 | 作用 | 是否进入 npm 包 |
+| --- | --- | --- |
+| `.gitignore` | 忽略本仓库 `.tmp/`、依赖和打包产物。 | 否 |
+| `AGENTS.md` | 当前仓库身份、维护源码、安装模板、永久验证、审计与临时物料的项目级 AI 边界。 | 否 |
+| `LICENSE` | MIT 许可证。npm 会按默认规则包含许可证。 | 是 |
+| `README.md` | 包首页和最短安装入口，链接到两份中文手册。 | 是 |
+| `package.json` | 包名、版本、CLI、Node.js 版本、依赖、全量测试与 `skills:validate` 命令和发布文件白名单。 | 是 |
+| `package-lock.json` | 锁定 `smol-toml`、`yaml` 及其依赖版本，保证本仓库安装可复现。 | 否 |
+| `bin/` | 命令行入口。 | 是 |
+| `lib/` | 安装、Hook TOML 合并、项目识别和引导实现。 | 是 |
+| `skills/` | 25 个可安装的项目级 Skills。 | 是 |
+| `docs/` | 完整项目手册、查看器使用/维护指南和本文。 | 是 |
+| `verification/` | 工作流仓库的通用自动化测试、专项验证器和长期测试辅助程序，纳入 Git，不进入 npm 包。 | 否 |
+| `audit/` | TaskLite 全流程审计物料；其中内嵌测试属于候选包、部署副本或历史快照，不随 `init` 安装。 | 否 |
+| `.tmp/` | 全部临时运行物料，整体忽略，可随时删除。 | 否 |
+
+## 3. CLI 与实现库
+
+双仓新增核心文件：
+
+| 文件 | 作用 |
+| --- | --- |
+| `lib/workspace.mjs` | 校验直接子目录代码路径，初始化或绑定两套 Git，读写 `.workflow/config/workspace.yaml`，并分别检查 branch、head、dirty paths 与 upstream 同步状态。 |
+| `verification/workspace-layout.test.mjs` | 覆盖空代码 Git、已有代码 Git、本地 bare remote clone、根忽略规则、双 Git 隔离、共享 checkpoint 恢复和 doctor。 |
+| `verification/dual-repo-e2e.test.mjs` | 在临时目录实际执行 TaskLite 双版本收尾、独立发布、同版本重发、Hotfix 同步和镜像回滚。 |
+| `audit/generate-dual-repo.mjs` | 创建 `.tmp/dual-repo-e2e/` 真实双 Git 工作区，并生成不含 `.git` 的持久审阅样本。 |
+| `audit/DUAL-REPO-FULL-FLOW/` | 双仓全流程持久物料，包含任务分片、共享 checkpoint、双 Tag 记录、发布、重发、Hotfix 和回滚证据。 |
+| `audit/AUTONOMOUS-GUIDANCE/` | 安装后零命令自主规划与引导的脱敏黑盒审计；保存声明清单、原始 Git 对象证明和四个最小远程快照，区分仓库可复算结论与未获平台签名的运行声明。 |
+
+### 3.1 `bin/`
+
+| 文件 | 作用 |
+| --- | --- |
+| `bin/ai-delivery.mjs` | npm `ai-delivery` 可执行入口；解析 `init`、`inspect`、`bootstrap`、`doctor`、`state`、`--dry-run`、`--force` 和版本参数，调用 `lib/` 并设置退出码。 |
+| `bin/validate-skills.mjs` | `npm run skills:validate` 的维护命令入口；调用 Skill 校验库、输出汇总或逐条错误并设置退出码，不会被 `init` 复制到业务项目。 |
+
+### 3.2 `lib/`
+
+| 文件 | 作用 |
+| --- | --- |
+| `lib/project-installer.mjs` | 实现项目级安装和诊断。复制 25 个 Skills、本地物料查看器及自包含 Bootstrap/状态/Evolution CLI，创建研发、发布和自进化目录，vendoring YAML 但不修改业务依赖；包版本升级时备份并替换受管资产，同版本冲突仅在 `--force` 时替换，降级默认拒绝。 |
+| `lib/project-bootstrap.mjs` | 只读扫描仓库并分类五种项目状态；识别代码、技术、Git、正式工作流和 runtime；为新接入项目生成草稿基线、文件清单、上下文索引、接入评估和引导计划；中断项目直接路由 checkpoint。 |
+| `lib/yaml-runtime.mjs` | 为发行包和安装后的项目内 Bootstrap 运行时解析 YAML；优先使用包依赖，项目内回退到状态 CLI 的 vendored YAML。 |
+| `lib/delivery-state.mjs` | 正式状态公共命令实现；管理物料、节点、Gate、候选和发布，提供 revision、锁、原子写、checksum、审计和 `verify`。 |
+| `lib/evolution.mjs` | 项目级自进化公共命令实现；管理反馈、提案、风险、扩展版本、批准、trial、Hook 调度、回退和 promotion bundle。 |
+| `lib/toml-hooks.mjs` | 使用结构化 TOML 解析和合并项目 Hook 配置；保留既有配置，检查显式禁用和事件注册，避免手工字符串拼接破坏 TOML。 |
+| `lib/skill-validator.mjs` | 校验 25 个 Skill 的 `SKILL.md` frontmatter、目录命名、`agents/openai.yaml` 元数据和中文文档覆盖；使用项目 Node.js `yaml` 依赖，不依赖 Python 或 `PyYAML`。 |
+
+## 4. 文档
+
+| 文件 | 作用 |
+| --- | --- |
+| `docs/PROJECT-MANUAL.zh-CN.md` | 完整中文项目手册：定位、安装、状态识别、全流程、Gate、原型、TDD、Git、发布、checkpoint、规范、审计、维护和故障排查。 |
+| `docs/FILE-REFERENCE.zh-CN.md` | 本文件，说明发行仓库全部有效文件及同构路径。 |
+| `docs/VIEWER-USER-GUIDE.zh-CN.md` | 查看器用户手册：安装、启动、界面、识别规则、安全边界、升级和故障排查。 |
+| `docs/VIEWER-MAINTENANCE.zh-CN.md` | 查看器维护手册：权威源码、架构、API、推导契约、修改入口、验证流程和完成定义。 |
+| `docs/STATE-CLI-USER-GUIDE.zh-CN.md` | 正式状态 CLI 用户手册：命令、revision、Gate、失败恢复和生产使用规则。 |
+| `docs/STATE-CLI-MAINTENANCE.zh-CN.md` | 正式状态 CLI 维护手册：实现边界、自包含安装、验证契约、测试和完成定义。 |
+| `docs/EVOLUTION-USER-GUIDE.zh-CN.md` | 自进化用户手册：反馈、风险、生命周期、Hook、trial、批准、回退和导出。 |
+| `docs/EVOLUTION-MAINTENANCE.zh-CN.md` | 自进化维护手册：权威源码、安装边界、数据模型、安全限制和验证方法。 |
+
+## 5. 永久验证源码
+
+| 文件 | 覆盖内容 |
+| --- | --- |
+| `verification/project-installer.test.mjs` | 项目级安装、Bootstrap 自包含入口、包版本升级、保留既有物料、dry-run、冲突备份、可选查看器隔离、Hook 禁用、路径逃逸防护、CLI init/doctor、中文规范合并和规范正文冲突。 |
+| `verification/project-bootstrap.test.mjs` | 空项目、存量代码、敏感文件排除、中断恢复、依赖就绪任务、部分安装、缺失 bootstrap skill 和 CLI inspect 只读输出。 |
+| `verification/prototype-handoff.test.mjs` | 原型不可变身份、多终端成员、三道体验 Gate、设计系统、产品核对、稳定 ID、UI handoff 及规划/开发体验变更追踪。 |
+| `verification/documentation.test.mjs` | 手册存在、README 链接、25 个 Skill 名称、主要文件域、YAML 解析、仓库内容边界和 npm `docs` 发布白名单。 |
+| `verification/skill-validation.test.mjs` | 验证当前 25 个 Skill 通过校验、无效 fixture 被拒绝、`skills:validate` 命令在 npm 包内可达且维护文档完整。 |
+| `verification/release-planner.test.mjs` | 连续版本闭包、同版本重发、倒退、断链、stale、缺 Tag 和 Git 血缘。 |
+| `verification/audit-workflow.test.mjs` | 运行审计总验证器，要求历史 V1 与当前契约 V2 均通过、各归档 15 个任务，并检查 checksum 格式和未发布版本数。 |
+| `verification/autonomous-guidance-evidence.test.mjs` | 验证自主引导证据可离线复算，并拒绝不完整清单、错误 commit tree、被篡改的快照/运行日志和符号链接逃逸。 |
+| `verification/workflow-viewer.test.mjs` | 验证查看器目录扫描、状态与关系推导、HTTP UI、`.workflow/` 读取边界和前后端语法。 |
+| `verification/delivery-state.test.mjs` | 验证正式状态 inspect/verify、物料版本、节点流转、Gate、revision 冲突、checksum 和绕过写入检测。 |
+| `verification/checkpoint-task-state.test.mjs` | 独立验证 checkpoint、任务依赖、恢复顺序、共享发布和版本归档。 |
+| `verification/evolution.test.mjs` | 验证反馈脱敏与幂等、证据门槛、风险抬升、checksum 批准、Hook、冲突、trial 晋升与回退。 |
+| `verification/audit/verify-audit.mjs` | 一键检查审计节点、引用、checksum、部署、发布列车、归档和自主引导证据一致性。 |
+| `verification/audit/verify-autonomous-guidance.mjs` | 复算自主引导结果/运行日志、原始 commit/tree、四个 Git blob 路径归属和任务语义，并报告仓库可验证与平台未认证声明。 |
+
+## 6. Skill 通用结构
+
+每个 `skills/ai-delivery-*/` 目录都包含：
+
+| 路径模式 | 数量 | 作用 |
+| --- | ---: | --- |
+| `skills/ai-delivery-*/SKILL.md` | 25 | Skill 入口；frontmatter 定义名称和触发条件，正文定义职责、步骤、Gate、输出及失败边界。 |
+| `skills/ai-delivery-*/agents/openai.yaml` | 25 | OpenAI/Codex 的 Skill 展示名称、简短说明和默认提示配置。 |
+| `skills/ai-delivery-*/references/*.md` | 22+ | 详细契约、Schema 语义、流程规则和边界。只有对应 skill 被调用时才按引用读取。 |
+| `skills/ai-delivery-*/assets/**` | 按需 | 安装模板或节点产物模板，AI 应复制并填写，不应重新发明结构。 |
+| `skills/ai-delivery-checkpoint-task/scripts/*.mjs` | 3 | checkpoint 状态机、Hook 记录和自测脚本。 |
+
+`agents/openai.yaml` 的职责在全部 25 个 Skill 中相同，以下各节不再逐行重复。
+
+## 7. 引导、编排和运行时 skills
+
+### 7.1 `ai-delivery-bootstrap`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-bootstrap/SKILL.md` | 新会话和陌生仓库入口；分类空项目、存量项目、就绪、中断和不一致状态。 |
+| `skills/ai-delivery-bootstrap/references/bootstrap-contract.md` | 五种状态、只读 inspect、可写 bootstrap、生成产物和下游路由的完整契约。 |
+| `skills/ai-delivery-bootstrap/agents/openai.yaml` | bootstrap 的 Codex 元数据。 |
+
+### 7.2 `ai-delivery-orchestrate`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-orchestrate/SKILL.md` | 主编排器；读取正式状态、恢复任务、路由各 specialist skill、维护 Gate 和版本生命周期。 |
+| `skills/ai-delivery-orchestrate/references/workflow-model.md` | 主流程图、状态枚举、运行时层次、人工 Gate、流转规则和恢复规则。 |
+| `skills/ai-delivery-orchestrate/references/formal-state-contract.md` | 正式状态唯一写入口、命令、mutation 顺序、revision 和完整性契约。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md` | 安装到目标项目根 `AGENTS.md` 的受管说明区块。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.gitattributes` | 安装到目标工作流仓库的 LF 属性规则，保证正式状态和物料 checksum 跨平台稳定。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/project.yaml` | 初始项目描述和旧身份字段兼容模板，不是生产事实写入口。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/workflow-state.yaml` | schema 2 正式审计模板；分别保存研发与发布 scope、局部 revision、节点、Gate 和尝试次数，并保存累计研发/生产身份。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/artifact-registry.yaml` | 初始正式产物注册表。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/standards-baseline.yaml` | 当前产物采用的规范版本模板。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/standards/index.yaml` | 项目规范索引模板。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/standards/STD-DOC-LANG-001.md` | 默认简体中文文档规范。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/standards/STD-ARTIFACT-PATH-001.md` | 所有研发流程文档默认输出到 `.workflow/` 的路径规范。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/standards/STD-TEST-LOCATION-001.md` | 应用测试遵循代码仓库原生框架和目录、测试源码不进入 `.workflow/` 的规范。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.codex/config.toml` | 完整项目模板中的 Hook 配置副本；与 checkpoint skill 的安装源保持一致，供整体模板审阅。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/hooks/hook-event.mjs` | 完整项目模板中的 Hook 记录器副本；与 checkpoint skill 的脚本保持一致，供整体模板审阅。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/state/state.mjs` | 安装后正式状态 CLI wrapper；使用 vendored YAML 调用统一状态模块。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/evolution/evolve.mjs` | 安装后 Evolution CLI wrapper；复用状态运行时 vendored YAML 并调用统一 Evolution 模块。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/bootstrap/bootstrap.mjs` | 安装后自主入口 wrapper；提供不依赖全局命令的只读识别和引导上下文生成。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/evolution/index.yaml` | 初始自进化索引，schema 1；不伪造反馈、提案或扩展。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/server.mjs` | 零依赖本地查看器服务；扫描 `.workflow/`，计算状态、关系和 checksum，并提供只读 API 与静态资源。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.cmd` | Windows CMD 启动脚本，默认启动并打开本地查看器。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.ps1` | PowerShell 启动脚本。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.sh` | macOS/Linux Shell 启动脚本。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/index.html` | 查看器三栏应用壳、筛选控件、物料表和详情检查器。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/app.js` | 前端扫描结果状态、筛选、关系跳转、checksum 复制及 Markdown/CSV/JSON/图片预览交互。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/styles.css` | 查看器设计令牌、桌面三栏布局、表格、详情区和移动端响应式样式。 |
+| `skills/ai-delivery-orchestrate/agents/openai.yaml` | orchestrate 的 Codex 元数据。 |
+
+### 7.3 `ai-delivery-checkpoint-task`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-checkpoint-task/SKILL.md` | 任务登记、激活、checkpoint、完成、恢复和按版本归档规则。 |
+| `skills/ai-delivery-checkpoint-task/references/checkpoint-contract.md` | runtime 布局、CLI 命令、状态、Hook 事件和恢复选择契约。 |
+| `skills/ai-delivery-checkpoint-task/references/checkpoint-recovery.zh-CN.md` | 中文 10 任务中断示例，证明完成 5 项后从第 6 项继续。 |
+| `skills/ai-delivery-checkpoint-task/scripts/task-state.mjs` | 任务状态机 CLI；原子写任务、checkpoint、resume、事件、活动标记和版本归档。 |
+| `skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs` | 读取 Codex Hook stdin，脱敏和截断后追加事件，并原子更新心跳。 |
+| `skills/ai-delivery-checkpoint-task/assets/codex-hook-config.toml` | 安装到项目 `.codex/config.toml` 的 10 类 Hook 注册模板。 |
+| `skills/ai-delivery-checkpoint-task/assets/runtime-template/task.json` | 单任务权威快照示例。 |
+| `skills/ai-delivery-checkpoint-task/assets/runtime-template/resume.md` | 面向 AI 和人的紧凑恢复摘要模板。 |
+| `skills/ai-delivery-checkpoint-task/assets/runtime-template/version-archive.json` | 迭代版本归档清单示例。 |
+| `skills/ai-delivery-checkpoint-task/agents/openai.yaml` | checkpoint skill 的 Codex 元数据。 |
+
+### 7.4 `ai-delivery-evolve-workflow`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-evolve-workflow/SKILL.md` | `$ai-delivery-evolve-workflow` 入口；规定反馈捕获、安全点评估、风险治理、trial、回退和导出。 |
+| `skills/ai-delivery-evolve-workflow/references/evolution-contract.md` | 生命周期、目录、manifest、风险、Hook JSON 和 trial 契约。 |
+| `skills/ai-delivery-evolve-workflow/agents/openai.yaml` | 自进化 Skill 的 Codex 元数据。 |
+
+## 8. 产品、架构和体验 skills
+
+### 8.1 `ai-delivery-define-product`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-define-product/SKILL.md` | 以逐项访谈完成发现 Gate A 和产品 Gate B，维护渠道、功能、故事、验收和术语。 |
+| `skills/ai-delivery-define-product/references/product-contract.md` | 产品发现与定义的字段、ID、版本、Gate 和追踪契约。 |
+| `assets/product-template/discovery-baseline.md` | 问题、用户、目标、边界、假设、风险和成功信号模板。 |
+| `assets/product-template/product-manual.md` | 产品定位、范围和统一业务语言模板。 |
+| `assets/product-template/product-baseline.yaml` | 绑定全部产品定义子产物的主基线模板。 |
+| `assets/product-template/terminals.csv` | 渠道与终端范围矩阵模板。 |
+| `assets/product-template/features.csv` | 产品功能清单模板。 |
+| `assets/product-template/feature-terminals.csv` | 功能与终端多对多关系模板。 |
+| `assets/product-template/feature-detail.md` | 单项产品功能说明模板。 |
+| `assets/product-template/user-stories.csv` | 用户故事模板。 |
+| `assets/product-template/acceptance-criteria.csv` | Given/When/Then 验收标准模板。 |
+
+本节中 `assets/...` 均位于 `skills/ai-delivery-define-product/` 下。
+
+### 8.2 `ai-delivery-design-architecture`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-design-architecture/SKILL.md` | 初始模式设计技术栈和主要边界；校准模式接收原型并冻结最终架构。 |
+| `skills/ai-delivery-design-architecture/references/architecture-contract.md` | 应用、技术、数据、安全、部署、可观测架构和决策 Gate 契约。 |
+| `assets/architecture-template/architecture-baseline.md` | 架构基线模板。 |
+| `assets/architecture-template/architecture-gate.yaml` | 重大架构决策和批准记录模板。 |
+| `assets/architecture-template/prototype-architecture-validation.yaml` | 架构对 UI handoff、产品核对、体验变更和不可变原型集的接收模板。 |
+
+本节中 `assets/...` 均位于 `skills/ai-delivery-design-architecture/` 下。
+
+### 8.3 `ai-delivery-design-experience`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-design-experience/SKILL.md` | 管理工具选择、可运行低保真原型、视觉系统/UI 框架、正式 UI、三道人工 Gate、调整记录、产品核对和下游交接。 |
+| `references/experience-contract.md` | 体验基线、页面状态、功能覆盖和原型来源确认契约。 |
+| `references/prototype-management-contract.md` | 原型成员、工具、页面、画布、文件、评审、调整和 checksum 的管理契约。 |
+| `assets/experience-template/prototype-set.yaml` | 多成员原型集的稳定 identity 和版本模板。 |
+| `assets/experience-template/prototype-manifest.yaml` | 单个原型成员及源文件身份模板。 |
+| `assets/experience-template/prototype-tool-candidates.csv` | 可用原型工具候选及适配分析。 |
+| `assets/experience-template/prototype-tool-selection.yaml` | 每个成员的人工工具选择凭据。 |
+| `assets/experience-template/page-catalog.csv` | `P01`、`P01-01` 等稳定页面目录。 |
+| `assets/experience-template/screen-states.csv` | 页面状态、触发、行为、恢复和无障碍要求。 |
+| `assets/experience-template/feature-screen-coverage.csv` | 功能、终端、流程、页面和状态覆盖。 |
+| `assets/experience-template/canvas-catalog.csv` | 原型画布目录和页面族边界。 |
+| `assets/experience-template/canvas-pages.csv` | 画布与页面显式关系。 |
+| `assets/experience-template/prototype-files.csv` | 原型源文件和修订目录。 |
+| `assets/experience-template/prototype-file-terminals.csv` | 原型文件与目标终端关系。 |
+| `assets/experience-template/prototype-traceability.csv` | 产品、终端、页面、状态、元素与源修订追踪。 |
+| `assets/experience-template/prototype-review-decision.yaml` | 视觉或交互原型必须执行分阶段人工评审的决定记录。 |
+| `assets/experience-template/prototype-review-sessions.csv` | 人工评审轮次和批准状态。 |
+| `assets/experience-template/prototype-review-comments.csv` | 稳定评论 ID、类型、对象和处置状态。 |
+| `assets/experience-template/prototype-adjustment-log.csv` | 评论对应的实际原型调整记录。 |
+| `assets/experience-template/prototype-impact-assessment.yaml` | 需求变化和架构影响评估。 |
+| `assets/experience-template/prototype-confirmation.yaml` | 原型来源、完整性和冻结确认。 |
+| `assets/experience-template/low-fidelity-confirmation.yaml` | 可运行低保真原型的 `UX-LF` 人工确认。 |
+| `assets/experience-template/visual-direction.yaml` | 整体色调、字体、密度、图标、响应式和无障碍方向。 |
+| `assets/experience-template/design-tokens.json` | 颜色、字体、间距、尺寸、边框、圆角、阴影、层级、断点和动效 Token。 |
+| `assets/experience-template/ui-framework-candidates.csv` | 与产品性质、架构和可用能力匹配的 UI 框架候选。 |
+| `assets/experience-template/ui-framework-selection.yaml` | 人工确认的 UI 框架及精确版本、依据和限制。 |
+| `assets/experience-template/component-state-matrix.csv` | 正式 UI 组件在各状态下的视觉、交互和无障碍规则。 |
+| `assets/experience-template/visual-system-confirmation.yaml` | 视觉系统和框架选型的 `UX-VS` 人工确认。 |
+| `assets/experience-template/interaction-contract.csv` | 触发、前置状态、状态变化、反馈、错误和键盘行为的结构化契约。 |
+| `assets/experience-template/page-component-map.csv` | 页面元素、正式 UI 组件和框架组件的稳定映射。 |
+| `assets/experience-template/formal-ui-confirmation.yaml` | 可运行正式 UI 的 `UX-UI` 人工确认。 |
+| `assets/experience-template/experience-change-set.csv` | 以稳定 ID 表达新增、修改、停用、取代和未变体验内容。 |
+| `assets/experience-template/experience-change-domains.csv` | 一项体验变更对应布局、交互、视觉、响应式等多个领域的关系表。 |
+| `assets/experience-template/requirement-change-set.csv` | 原型调整中识别出的需求变化及产品处置状态。 |
+| `assets/experience-template/prototype-product-coverage.csv` | 产品需求与原型行为的双向覆盖矩阵。 |
+| `assets/experience-template/product-prototype-reconciliation.yaml` | 全部候选原型完成后的产品统一核对结论。 |
+| `assets/experience-template/experience-baseline.yaml` | 三道 Gate 和产品核对通过后冻结的体验基线清单。 |
+| `assets/experience-template/ui-handoff.yaml` | 下游唯一就绪入口，绑定所有 Gate、契约、变更和 checksum。 |
+
+本节中省略前缀的 `references/` 和 `assets/` 均位于 `skills/ai-delivery-design-experience/` 下。
+
+## 9. 平台、规划和测试设计 skills
+
+### 9.1 `ai-delivery-prepare-platform`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-prepare-platform/SKILL.md` | 准备构建、CI/CD、环境、配置、观测、制品和回滚平台。 |
+| `references/platform-contract.md` | 平台输入、环境、配置、安全、就绪和汇合契约。 |
+| `assets/platform-template/environment-ledger.csv` | 环境、版本、制品、配置和验证状态台账模板。 |
+
+### 9.2 `ai-delivery-plan-iteration`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-plan-iteration/SKILL.md` | 按价值、风险和依赖规划敏捷垂直切片，不在此阶段预拆前后端技术任务。 |
+| `references/planning-contract.md` | backlog、切片、来源、依赖、优先级和完成条件契约。 |
+| `assets/planning-template/backlog.csv` | 产品待办及排序维度模板。 |
+| `assets/planning-template/vertical-slices.csv` | 可独立验证垂直切片模板。 |
+| `assets/planning-template/slice-sources.csv` | 切片到功能、故事、验收标准的来源追踪。 |
+| `assets/planning-template/slice-dependencies.csv` | 切片先后依赖。 |
+| `assets/planning-template/slice-prototype-traceability.csv` | 切片与原型成员、页面、状态和 checksum 追踪。 |
+| `assets/planning-template/slice-experience-change-traceability.csv` | 切片与可执行体验变更、影响和测试范围的追踪。 |
+
+### 9.3 `ai-delivery-design-tests`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-design-tests/SKILL.md` | 开发前设计风险测试策略、原型可测性和公开测试契约。 |
+| `references/test-design-contract.md` | 测试策略、测试层次、数据、环境、质量门禁和开发公开接缝契约。 |
+| `assets/test-design-template/iteration-test-contract.md` | 开发与独立测试共同使用的公开行为契约。 |
+| `assets/test-design-template/prototype-test-scope.csv` | 每个相关原型成员的测试范围和显式决定。 |
+| `assets/test-design-template/prototype-test-validation.yaml` | 测试设计对 UI handoff、产品核对、体验变更及原型 identity/checksum 的接收凭据。 |
+
+本节 9.1 至 9.3 中省略前缀的文件均位于对应 skill 目录。
+
+## 10. 开发与变更审查 skills
+
+### 10.1 `ai-delivery-develop-iteration`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-develop-iteration/SKILL.md` | 为一个切片动态推导技术工作包和能力角色，协调 TDD、独立审查和候选组装。 |
+| `references/development-contract.md` | 工作包、动态角色、分支、TDD、审查、追踪和候选冻结契约。 |
+| `assets/development-template/task-prototype-traceability.csv` | UI 任务到原型成员、页面、画布、文件、元素和 checksum 的追踪模板。 |
+| `assets/development-template/task-experience-change-traceability.csv` | 开发任务到体验变更及 create/update/remove/migrate/no-code 动作的追踪。 |
+
+### 10.2 `ai-delivery-execute-work-package`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-execute-work-package/SKILL.md` | 执行一个边界明确的技术工作包；验证依赖和范围，按 TDD 实现并提交证据。 |
+| `references/work-package-contract.md` | 单工作包必填输入、允许修改范围、角色能力、测试接缝、输出和失败条件。 |
+
+### 10.3 `ai-delivery-review-change`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-review-change/SKILL.md` | 由独立上下文审查产品行为、架构、项目规范、安全和测试质量。 |
+| `references/review-contract.md` | 审查输入隔离、发现字段、严重级别、决定和复审规则。 |
+
+## 11. 候选验证和失败处理 skills
+
+### 11.1 `ai-delivery-verify-candidate`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-verify-candidate/SKILL.md` | 在可复现环境中独立验证不可变候选并给出发布建议。 |
+| `references/candidate-verification-contract.md` | 风险测试拆分、覆盖、环境、原型一致性、缺陷和候选决策契约。 |
+| `assets/verification-template/test-work-packages.csv` | 动态风险测试工作包模板。 |
+| `assets/verification-template/defects.csv` | 缺陷、根源节点、证据、状态和复验范围模板。 |
+| `assets/verification-template/defect-artifacts.csv` | 缺陷与受影响正式产物的关系模板。 |
+
+### 11.2 `ai-delivery-execute-test`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-execute-test/SKILL.md` | 独立执行一个功能、集成、端到端、安全、性能、无障碍、兼容、迁移或恢复测试包。 |
+| `references/test-execution-contract.md` | 受控环境、候选身份、证据、结果和测试独立性契约。 |
+
+### 11.3 `ai-delivery-triage-failure`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-triage-failure/SKILL.md` | 根据证据判断失败的真正拥有节点，避免测试节点直接修复生产者产物。 |
+| `references/failure-routing-contract.md` | 需求、体验、架构、规划、平台、代码、测试工具、发布和生产失败的分类及回流规则。 |
+
+## 12. 发布、部署和生产验证 skills
+
+### 12.0 新增版本收尾与发布编排
+
+| 路径 | 作用 |
+| --- | --- |
+| `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 计划和发布候选模板。 |
+
+### 12.1 `ai-delivery-prepare-release`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-prepare-release/SKILL.md` | 在 R06 冻结一个已验证发布候选，核对完整变更、实际交付物和回滚能力；生产审批独立位于 R07。 |
+| `references/release-contract.md` | release ID、候选 digest、Tag、交付清单、配置、迁移、验证、回滚和审批契约。 |
+| `assets/release-template/release-manifest.yaml` | 不可变发布清单模板。 |
+| `assets/release-template/delivery-items.csv` | 镜像、应用、配置、数据、基础设施、文档和运维项的实际交付清单模板。 |
+
+### 12.2 `ai-delivery-deploy-production`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-deploy-production/SKILL.md` | 仅执行精确人工批准且未变化的迭代发布包，记录生产转换，不混入测试或开发。 |
+| `references/deployment-contract.md` | 部署前核对、锁、执行、证据、失败停止和镜像回滚边界。 |
+
+### 12.3 `ai-delivery-verify-production`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-verify-production/SKILL.md` | 每次部署或回滚后独立验证技术与业务信号，决定 released、失败或回滚。 |
+| `references/production-verification-contract.md` | 生产制品身份、烟雾/业务信号、决策、预授权回滚和归档准入契约。 |
+| `assets/production-verification-template/production-verification.md` | 生产验证报告模板。 |
+
+## 13. 治理 skills
+
+### 13.1 `ai-delivery-validate-artifacts`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-validate-artifacts/SKILL.md` | 在流转前校验注册表、基线、CSV 关系、版本、批准、规范固定和交接引用。 |
+| `references/artifact-contract.md` | 稳定 ID、状态、版本、checksum、引用完整性、不可变和 stale 传播契约。 |
+
+### 13.2 `ai-delivery-manage-git`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-manage-git/SKILL.md` | 管理 protected main、迭代分支、工作包分支/worktree、hotfix、release Tag 和串行生产转换。 |
+| `references/git-policy.md` | 分支命名、合并、Tag、候选保留、清理和“镜像回滚而非回滚分支”规范。 |
+
+### 13.3 `ai-delivery-manage-standards`
+
+| 文件 | 作用 |
+| --- | --- |
+| `skills/ai-delivery-manage-standards/SKILL.md` | 把人机对话中形成的长期规则分类、提案、批准、版本化、解析和应用。 |
+| `references/standards-contract.md` | 规范 ID、状态、适用域、版本、批准、例外、冲突和基线固定契约。 |
+| `assets/standards-template/standard.md` | 新建项目规范的正文模板。 |
+
+## 14. 审计物料目录
+
+`audit/` 根目录的 17 个编号阶段是已归档的历史 V1；它保留当时契约下的执行事实，但缺少后来增加的完整原型管理及接收凭据。`audit/ITER-V2/` 使用当前契约执行下一迭代。每个具体文件的用途由 [../audit/FILE-GUIDE.zh-CN.md](../audit/FILE-GUIDE.zh-CN.md) 维护。整个目录只属于维护仓库审计资产，不随 `init` 安装。
+
+| 目录 | 作用 |
+| --- | --- |
+| `audit/00-governance/` | 项目、流程、产物、物料、交接和规范基线。 |
+| `audit/01-product-discovery/` | 产品发现基线和 Gate A。 |
+| `audit/02-product-definition/` | 产品手册、终端、功能、故事、验收标准和 V1-V5 路线。 |
+| `audit/03-architecture-initial/` | 初始架构、技术栈、API 草案和架构决策。 |
+| `audit/04-experience-design/` | 体验基线、功能页面覆盖和页面状态。 |
+| `audit/05-architecture-reconcile/` | 最终架构、组件影响和冻结 OpenAPI。 |
+| `audit/06-platform-preparation/` | 平台就绪、CI、配置、环境和容器方案评估。 |
+| `audit/07-iteration-planning/` | backlog、垂直切片、来源、依赖和 V1 计划。 |
+| `audit/08-test-design/` | 策略、公开测试契约、追踪、门禁、数据和环境。 |
+| `audit/09-development/` | 动态角色、工作包、TDD 证据、代码、候选包和候选清单。 |
+| `audit/10-change-review/` | 独立审查报告、发现和决定。 |
+| `audit/11-candidate-verification/` | 风险测试包、证据、覆盖、缺陷、候选决定和验证工具。 |
+| `audit/12-release-preparation/` | 完整变更覆盖、上线交付清单、发布清单和回滚就绪。 |
+| `audit/13-production-approval/` | 绑定精确发布包的模拟人工审批。 |
+| `audit/14-production-deployment/` | 独立部署计划、记录、证据和部署副本。 |
+| `audit/15-production-verification/` | 生产烟雾脚本、证据、报告和发布决定。 |
+| `audit/16-version-archive/` | ITER-V1 的 15 个任务、checkpoint、事件、恢复摘要和版本索引。 |
+| `audit/ITER-V2/` | 当前契约下的第二次迭代，交付“完成任务”，包含可运行低保真与正式 UI、三道人工 Gate、调整记录、产品核对、体验变更追踪、上下游接收凭据、TDD、发布、部署、验证和版本归档。 |
+| `audit/RELEASE-TRAIN-DEMO/` | 当前双状态机契约示例：五个累计版本、VER-02 至 VER-05 的多版本发布、完整 R00-R10 物料和同版本重发。 |
+
+`audit/` 根文件：
+
+| 文件 | 作用 |
+| --- | --- |
+| `audit/README.md` | TaskLite 示例边界、阅读顺序和运行命令。 |
+| `audit/FILE-GUIDE.zh-CN.md` | 审计目录全部 628 个文件及同构归档路径的权威说明。 |
+| `audit/REVIEW-CHECKLIST.md` | 人工审阅全流程完整性的清单。 |
+| `audit/V1-CONTRACT-COMPATIBILITY.md` | 解释历史 V1 能证明什么、缺少哪些当前强制物料，以及为何不能原地补写。 |
+| `audit/generate-v2.mjs` | 从 V1 基线可重复生成并执行 ITER-V2，包含真实 TDD、确定性候选打包、部署、生产烟雾和版本归档。 |
+
+## 15. 安装后生成而非发行的文件
+
+这些文件不在 npm 包中作为业务状态发布，而是在目标项目运行时创建：
+
+| 路径 | 作用 |
+| --- | --- |
+| `.agents/skills/ai-delivery-*/` | 从包内 `skills/` 复制的项目级能力。 |
+| `.codex/config.toml` | 合并后的项目 Hook 配置。 |
+| `.workflow/config/workspace.yaml` | 工作流仓库与唯一代码仓库的路径、身份、远程和分支契约。 |
+| `.workflow/config/install-manifest.json` | 安装版本、范围、skill 根、`.workflow` 根、Bootstrap、状态、Evolution 与查看器入口、固定 skill 清单，以及受管运行时 SHA-256。 |
+| `.workflow/tools/hooks/hook-event.mjs` | 本地 Hook 执行文件。 |
+| `.workflow/tools/state/` | 正式状态 CLI、统一状态模块及自包含 YAML 运行时。 |
+| `.workflow/tools/bootstrap/` | 核心自主入口；只读识别项目状态、生成首次引导上下文并输出机器可读路由。 |
+| `.workflow/tools/viewer/` | 随 `init` 安装的只读工作流物料查看系统及启动脚本。 |
+| `.workflow/delivery/runtime/backups/<timestamp>/` | `--force` 替换前备份。 |
+| `AGENTS.md` 中的 `ai-delivery` 受管区块 | 告诉后续 AI 如何启动、恢复和使用项目流程。 |
+| `.gitattributes` 中的工作流 LF 规则 | 保持 `.workflow/`、项目级 Skills 和根控制文件的字节级 checksum 在 Windows、macOS、Linux 间一致。 |
+| `.workflow/delivery/bootstrap/runs/<id>/` | 项目识别产生的草稿仓库上下文。 |
+| `.workflow/delivery/runtime/tasks/*.json` | 当前迭代任务权威快照。 |
+| `.workflow/delivery/runtime/checkpoints/<task>/*.json` | 不可变任务里程碑副本。 |
+| `.workflow/delivery/runtime/events/*.jsonl` | 状态机和 Hook 的仅追加事件。 |
+| `.workflow/delivery/runtime/heartbeats/*.json` | 最近 Hook 活动心跳。 |
+| `.workflow/delivery/runtime/resumes/*.md` | 任务恢复摘要。 |
+| `.workflow/control/archives/versions/<version-id>/` | Git 可携带的权威版本任务归档；归档后活动 task/checkpoint 分片从普通恢复范围移除。 |
+| `.workflow/delivery/runtime/archive/` | 可丢弃的本地详细归档副本和索引，不作为跨 clone 的权威来源。 |
+| `.workflow/product/` | 可跨迭代复用的产品基线。 |
+| `.workflow/architecture/` | 可跨迭代复用的架构基线。 |
+| `.workflow/experience/` | 可跨迭代复用的体验基线和原型管理基线。 |
+| `.workflow/iterations/<iteration-id>/<node-id>/` | 迭代内每个流程节点的默认文档输出目录。 |
+| `.workflow/releases/<release-id>/<release-node>/` | 独立发布 R00 至 R10 的默认文档输出目录。 |
+| `.workflow/delivery/runtime/active-task.json` | 当前工作流工作区的唯一活动任务指针，任务关闭后删除；外部代码 worktree 通过 `--state-root` 或环境变量关联。 |
+
+## 16. 本地和生成目录
+
+下列目录不是发行源码，不应作为产品文件维护：
+
+| 路径 | 说明 |
+| --- | --- |
+| `node_modules/` | `npm install` 产生的依赖。 |
+| `.tmp/` | 本机测试工作区、缓存、日志、报告、临时 Git 仓库、打包文件、认证辅助文件和单次场景脚本；整体忽略。 |
+| `.agents/` | 本发行仓库当前为空；实际业务项目安装后才包含项目 skills。 |
+| `.codex/` | 本发行仓库当前为空；实际业务项目安装后才包含项目配置。 |
+| `.git/` | 版本控制元数据；当前工作区不应依靠本文重建或修改它。 |
+| `*.tgz` | `npm pack` 生成的临时发布包。 |
+
+## 17. 文件修改责任
+
+| 文件类型 | 修改规则 |
+| --- | --- |
+| `SKILL.md` 和契约 | 修改后同步模板、测试、主手册和流程模型。 |
+| assets 模板 | 修改字段时同步生产者、消费者和交接测试。 |
+| 已批准基线 | 不原地修改；创建新版本并做影响分析。 |
+| Hook 事件 | 只能作为审计和心跳，不推进正式节点。 |
+| runtime 当前任务 | 通过 `task-state.mjs` 原子写入，不手工拼接。 |
+| 已归档版本 | 不原地修改。 |
+| `audit/` V1 | 已完成模拟发布并归档，不原地修改。 |
+| 规范 | 通过 `$ai-delivery-manage-standards` 提案、人工批准和版本化。 |
+
+当仓库文件发生变化时，应先更新本文件的对应章节，再运行文档一致性测试和 `npm pack --dry-run`。