@givolt/i3-composer-agent 2.3.6 → 3.0.0

package/references/enterprise-sop-resources/ad/templates/AD.md

@@ -0,0 +1,337 @@
+# AD 模板
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+**原型按需，AD 可并行。**AD 的直接产品依据是本次选定的 PRD；原型不是进入 AD 的统一前置。无界面时可说明不适用；有界面且页面、行为和交互定义已充分明确时，也不强制另做原型。需要原型时，可与架构、数据、接口等 AD 设计并行；关键交互未定，只限制依赖它的具体设计与交接范围。项目明确要求的原型认可仍在相应范围交接前满足，不把“可起草 AD”写成“全部设计已可实施”。
+
+**审查只标注，使用者决定处理。**文档审查者只读标注问题、准确位置、来源、影响和修改建议，不直接修改候选。使用者可以人工修改、明确委托模型修订、有依据地不采纳建议，或将业务问题保持待确认；审查意见不自动触发改写。保留旧稿、人工修改、原报告和逐项处理依据，按项目既有约束进行必要复查；缺少真实答复不为清零而补造规则，人工编辑也不自动等于审查通过或业务批准。
+
+模板版本：v0.0.4。日期：2026-10-18。状态：自有资源候选；模板可供明确采用，业务内容与认可另行记录。
+
+采用[模板与交接合同](../../template-contracts.md)。AD 同时承载技术架构和完整工程设计，实例文件名为 `{PBC}-{需求主题}-AD_v0.0.1.md`。本次采用一个明确 PRD 版本，不强制两份文档同号；相关主题和公共基线固定引用，不让本 AD 隐式承担另一 PRD 的全部设计。
+
+AD §9 明确保留原 SPEC 的完整命令、项目目录、代码风格和工程边界；测试策略与 TestCase §3.1 固定衔接。四类模板是外部规格表示，不另造第五核心规格、不强制复制 SPEC，也不改变继承 Skill 的触发、输出、工具、验证或认可要求。所填状态和字段不构成原方法所需的人类决定。
+
+**整体技术架构图、功能架构图、ER 图均为必需视图。** 下列图是填写骨架，占位实体、关系、基数和箭头不代表已经确认的架构。实例必须按真实输入替换，正文表格补全工程定义；图形齐全不等于可以实施。缺口只阻断依赖它的范围，不能为补齐图而虚构组件、表或业务规则。
+
+---
+
+# {PBC名称} · {需求主题} — 架构与工程设计
+
+## 0. 身份、采用与比较基准
+
+| 项目 | 本次实际值 |
+| --- | --- |
+| 能力与需求主题 | `{PBC capabilityId/名称；稳定prdId/主题；已知EBC引用}` |
+| 文档身份/版本/位置 | `{documentId；实际版本；可回读路径；摘要可选}` |
+| 直接产品依据 | `{唯一选定PRD身份、版本和实际路径；回读正文，摘要可选，不自动取最新}` |
+| 原型/组件/公共基线 | `{适用版本与认可范围；没有或不适用则说明影响}` |
+| 当前设计范围 | `{全部有效目标、变化/保留/替代及仅比较材料}` |
+| 现有工程基准 | `{代码、数据、接口、实际运行/部署状态；未实现/未读取分别说明}` |
+| 模板、责任与状态 | `{固定模板；维护/编写/复核责任；草稿或实际认可范围}` |
+
+### 0.1 固定输入与权威定义
+
+| 输入/附件 | 实际身份/路径/文内版本（摘要可选） | 定义权威范围 | 本 AD 使用位置 | 已读/可用/认可与缺口 |
+| --- | --- | --- | --- | --- |
+| `{PRD/原型/已有代码/外部规范/Schema等}` | `{能回读的固定内容}` | `{产品/交互/API/数据/公共规则等}` | `{章节/条目}` | `{文档存在不代表真实服务可用}` |
+
+精确 OpenAPI、Schema、DDL、数据字典可以在受控附件维护，正文声明权威范围并固定引用，不能各自保存不同答案。没有附件时在正文完整定义；不能虚构附件已存在。
+
+### 0.2 决定、未决与变化
+
+| ID | 事项/方案 | 已定规则/项目决定/待核实 | 来源、备选及理由 | 影响范围 | 实际认可或关闭依据 |
+| --- | --- | --- | --- | --- | --- |
+| `{DEC/Q等稳定ID}` | `{具体事项}` | `{三类分开}` | `{不将建议写成事实}` | `{功能/契约/数据/任务}` | `{未取得则注明}` |
+
+输入变化或公共规则被突破时，先处理权威定义与兼容影响，再继续受影响设计；不能以本主题局部例外悄悄改变共同协议。
+
+### 0.3 公共技术规约、契约与骨架的本次采用
+
+AD准备先读取项目明确采用的公共规范、CONSTRAINTS、ADR及工程事实，已有资料适用时直接引用，不复制平行技术规约。没有取得规范时，列出已查范围和缺口，引导选择已有规范或起草最小候选；技术栈、版本、工程骨架与例外由真实来源及使用者决定。若要另写公共技术规约候选，先明确该辅助目标及写入范围；本次只授权AD时，保留Q并起草独立部分，不静默多写文件。
+
+| 采用ID／类型 | 权威位置／文内版本／条款 | 本次角色与适用范围 | 本AD落实位置／例外 | 实际读取与缺口／决定依据 |
+| --- | --- | --- | --- | --- |
+| `{BASE：公共规范}` | `{项目已采用规范的实际路径与条款}` | `{本主题适用部分，不以规范代产品规则}` | `{具体章节或明确偏差}` | `{已读内容；未取得或冲突保留Q}` |
+| `{CONTRACT／DATA：共享定义}` | `{唯一Schema、契约正文或提供方AD固定章节}` | `{提供／消费／只读；精确行为范围}` | `{§5、§6、§8及精确条目}` | `{选用依据不等于服务就绪}` |
+| `{SKELETON：工程骨架}` | `{真实模板／源码或采用说明及其实际指向}` | `{工程类型、适用目录和责任}` | `{§9.6；与规范兼容或例外}` | `{已取得／拟采用／未应用／未验证分别记录}` |
+
+本表只组织引用，详细权威仍在来源文件，字段定义不在多表重复维护。单独提供模板时说明配套提示词和兼容范围；实际读取选定资料根的README、阶段索引、阶段清单、模板及本次提示词，不以安装根的索引替代项目已采用副本。已选来源失效或冲突时报告实际差异，不跨宿主、历史样例或最大版本兜底。
+
+基本交接按路径、正文及文内版本核对，不强制SHA256；同路径人工修改需要回读并判断影响，旧认可不自动转移。正式发布规范或契约已有的不可变版本／摘要要求按其原用途保留。本模板不实现JSON登记、自动选择或项目配置写入。
+
+## 1. 需求覆盖与工程驱动
+
+| PRD 需求/AC/质量条目 | 本次处理 | 设计条款/图/组件 | 可观察结果 | TestCase 引用或待形成 | 缺口及阻断范围 |
+| --- | --- | --- | --- | --- | --- |
+| `{固定版本和稳定条目；含复合子项}` | `{新增/修改/复用/停用}` | `{精确落点}` | `{成功/拒绝/失败}` | `{用例或未形成}` | `{具体条件}` |
+
+覆盖 PRD 明确的权限、生命周期、质量和跨主题交接，不只覆盖主流程。需求保留与代码可复用分别核实，数量相等不证明含义一致。
+
+## 2. 整体技术架构
+
+### 2.1 技术架构图（必需）
+
+```mermaid
+flowchart LR
+  Entry["{真实参与方/入口}"] --> Component["{责任组件/边界}"]
+  Component --> Authority["{权威数据/外部能力}"]
+```
+
+`{替换为本主题有效架构：系统边界、实际/拟建组件、同步/异步方向、数据归属和关键外部依赖；涉及多个工程或共享底座时标实际关系。不因使用模型、容器或工作流就推定微服务。}`
+
+| 组件/工程 | 职责与明确不负责项 | 拥有的数据/状态 | 输入输出与依赖 | 实际/拟建及证据 | 对应需求 |
+| --- | --- | --- | --- | --- | --- |
+| `{真实或拟建对象}` | `{明确边界}` | `{谁可写、谁读取}` | `{契约及方向}` | `{未知不写已就绪}` | `{固定PRD条目}` |
+
+### 2.2 技术与工程基线
+
+| 领域 | 适用选型/精确版本 | 有效规则或固定权威引用 | 本主题落实位置 | 兼容/实际可用性 | 待核实及责任 |
+| --- | --- | --- | --- | --- | --- |
+| `{前端/后端/数据库/身份/消息/CI/CD/部署等实际项}` | `{有依据或待定}` | `{不能只写继承旧资料}` | `{本AD具体条款}` | `{方向确定/文档核对/真实运行分开}` | `{缺口}` |
+
+项目骨架、仓库、运行时、依赖版本和身份系统按实际来源填写。外部骨架或集团契约未提供时标未取得，不猜测它不存在，也不擅自另造平行工程。新增/升级依赖说明用途、版本、许可、兼容及下游同步。
+
+### 2.3 本次采用组合与兼容判断
+
+| 组合／范围 | 提供方与消费方AD的实际路径／版本 | 规范条款／契约与数据版本 | 代码／制品／环境事实 | 兼容判断与依据 | 未决、允许推进及迁移／退出条件 |
+| --- | --- | --- | --- | --- | --- |
+| `{本主题及必要关联范围}` | `{独立主题、独立版本；未形成如实说明}` | `{引用§0.3与唯一权威，不重写正文}` | `{未产生不填已部署或已测试}` | `{设计相容／未知／冲突；实际证据位置}` | `{并存窗口、发布顺序、恢复限制及责任；未知列Q}` |
+
+分别核调用类型、序列化与严格消费者，行为／权限／默认值／状态，数据迁移及并存写入，运行时和装配条件。新增字段、枚举或默认值也可能不兼容；文档同号、SemVer主版本相同或Schema校验通过都不能替代实际语义与消费者核对。设计核对、可交Plan、获准Build和真实集成结果分别表达，不要求所有AD机械升级到最新规范。
+
+## 3. 功能架构与实现链路
+
+### 3.1 功能架构图（必需）
+
+```mermaid
+flowchart TD
+  Topic["{当前PRD主题/边界}"] --> FunctionA["{有效功能及稳定ID}"]
+  Topic --> FunctionB["{另一有效功能或必要交接}"]
+```
+
+`{图中每个功能引用真实PRD条目，体现责任、依赖和边界，不为图形对称添加能力。跨主题共用部分标注权威与接口，不复制另一份需求。}`
+
+### 3.2 逐功能工程落点
+
+| 功能/AC | 用户与前置条件 | 页面/入口与动作 | API/事件/工具/服务规则 | 数据读写与事务 | 异常/恢复与可观察结果 | 实现前提 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `{固定PRD条目及全部子项}` | `{身份/权限/状态}` | `{UI标识或无UI依据}` | `{具体条款引用}` | `{表/列或外部/派生来源}` | `{拒绝、冲突、失败、未知等}` | `{就绪范围与缺口}` |
+
+共享定义只在后文或附件定义一次，功能表精确引用。图上箭头不能代替契约、字段或错误定义；不能只复制需求文字来表示设计完成。
+
+### 3.3 端到端顺序与跨主题交接
+
+`{入口→服务/工作流→数据/外部依赖→可观察结果；说明调用先后、同步/异步、事实维护者、超时未知、重复和补偿，必要时补时序图。共享底座只设一个任务归属，其他主题引用依赖。}`
+
+## 4. 页面、组件、字段与交互
+
+| UI ID/路由 | 任务与布局/组件 | 原型/token/组件固定版本 | 可见/可操作/数据范围 | 状态与本次变化 |
+| --- | --- | --- | --- | --- |
+| `{入口、参数、弹层、关闭和返回}` | `{实际区域}` | `{认可范围、差异；未形成说明}` | `{服务端仍校验}` | `{具体条款}` |
+
+| UI.字段 | 控件/前端类型 | 来源/API精确路径 | 必填/null/空串/默认与产生者 | 校验/格式/单位/精度 | 权限/状态条件 | 错误、焦点与输入保留 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `{输入、展示列、过滤/统计项逐项}` | `{实际组件和类型}` | `{选项key/label及来源版本}` | `{明确区别}` | `{有来源的约束}` | `{显示/只读/编辑}` | `{可纠正且可达}` |
+
+| 动作 | 前置状态/权限 | 请求顺序/字段 | 成功结果与反馈 | 失败/超时/未知结果 | 重复/并发/取消 |
+| --- | --- | --- | --- | --- | --- |
+| `{实际动作}` | `{何时可执行}` | `{契约ID}` | `{刷新/路由/焦点/输入变化}` | `{错误码与恢复}` | `{旧响应丢弃、幂等、取消不等于服务端撤销}` |
+
+落实初始、加载、空数据、正常、校验失败、依赖失败、无权限及适用的部分成功/只读/失效状态；定义排序、分页、过滤、提交时机、异步选项和失效选项。长内容、窄屏、局部滚动、键盘/标签/焦点和错误可达性有明确行为，不靠删内容或整页缩放应付。无 UI 的主题说明实际依据，不虚构页面。
+
+## 5. API、事件、工具与精确契约
+
+### 5.1 契约目录与完整定义
+
+| 契约 ID | 协议/方法/路径或主题/版本 | 调用方→提供方 | 作用范围/授权 | 输入输出权威位置 | 副作用/兼容 |
+| --- | --- | --- | --- | --- | --- |
+| `{API/EVT/TOOL等}` | `{真实定义或明确待定}` | `{责任组件}` | `{身份、租户、对象归属}` | `{完整Schema/正文}` | `{真实行为}` |
+
+每项契约逐项明确：
+
+- 请求的路径、查询、头、正文全部字段、类型、长度/精度、必填、默认、枚举、null/省略及未知字段处理。
+- 响应全部字段、列表元素、分页、派生值、成功/失败结构和禁止返回内容。
+- 可信身份和租户来源、功能/资源授权、拒绝条件及审计；客户端参数不得绕过对象级检查。
+- 事务、并发版本、幂等范围/键/生命周期、重放响应、冲突和结果未知时的查询与恢复。
+- 业务错误码、依赖错误、超时、重试责任/上限、限流、降级和外部成功/本地失败的处置。
+- 兼容与迁移窗口；事件适用时补 Schema、生产/消费方、顺序范围、重复/乱序/迟到、死信与人工处理。
+
+示例 JSON、接口名称或“标准 CRUD”不能代替这些定义。无事件/工具需求时说明不适用，不因模板列举自动引入。
+
+### 5.2 提供／消费关系与单一权威
+
+| 契约／定义ID及版本 | 唯一权威路径／精确章节 | 提供／维护方及AD | 消费方及AD／需求或AC | 本主题映射、授权与失败恢复 | 核对方法与实际就绪／缺口 |
+| --- | --- | --- | --- | --- | --- |
+| `{引用§5.1实际条目}` | `{字段、行为分担时分别说明边界}` | `{逻辑维护责任与实际工程}` | `{只列实际消费者及准确版本}` | `{输入输出转换；幂等／重放／未知结果；不只列接口名}` | `{契约／语义／集成判据；未执行如实写}` |
+
+提供方完整定义允许操作及事务边界，消费方引用同一权威并明确调用、字段映射、超时／失败／恢复及受影响需求。两份AD不能各维护一份不同的共享协议，也不能循环依赖对方全文。外部PBC或独立Agent优先消费正式对外契约，不复制或批准提供方内部AD；Schema、行为与数据字典分别维护时写清各自唯一权威。
+
+## 6. ER 与完整数据设计
+
+### 6.1 ER 图（必需）
+
+```mermaid
+erDiagram
+  ENTITY_A ||--o{ ENTITY_B : "{实际关系}"
+```
+
+`{实体名、关系和一对多基数仅为图语法占位；实例按真实业务对象与工程关系替换，标注维护方、PK/FK、基数和可选性。外部只读、派生、快照实体注明来源和生命周期，不为画ER而新增数据库表。关系/数据尚未明确时保留问题并限制相关设计，不把占位图称作已确认ER。}`
+
+### 6.2 数据所有权与实体目录
+
+| 实体/表/集合 | 用途与权威维护者 | 新增/修改/复用基准 | 主键/关系与隔离 | 生命周期/归档/删除 | 固定定义位置 |
+| --- | --- | --- | --- | --- | --- |
+| `{物理名称或外部实体}` | `{谁写谁读}` | `{原DDL/契约版本}` | `{租户/项目/资源范围}` | `{有来源的保留/恢复规则}` | `{本章或唯一附件}` |
+
+#### 6.2.1 共享实体、状态与派生数据的责任
+
+| 实体／状态／共享文件ID | 唯一逻辑权威与定义位置 | 最终校验／受控写入边界 | 本主题提供／消费及相关AD | 副本／快照／派生来源及过期语义 | 并发、事务与恢复／Q |
+| --- | --- | --- | --- | --- | --- |
+| `{引用已有定义，不新造同名字段}` | `{负责业务含义及最终有效状态的模块；不是单一操作人员}` | `{经何授权、在哪一事务中改变}` | `{准确主题、版本和允许动作}` | `{时间点／版本、更新责任、一致性和补偿}` | `{冲突处理及缺口；不能只凭预查询保证并发}` |
+
+写入者可有多个经授权主体，但业务定义和最终校验责任必须清楚。只读快照、缓存和派生值不成为第二权威，过期展示不能直接批准业务动作；共享迁移、底座和文件只安排一个获准任务归属，其他主题列依赖。两个AD都拟修改同一字段、状态或共享文件时标注冲突与影响，不能静默覆盖，也不为填表擅定责任人、保留期限或业务例外。
+
+### 6.3 字段、约束与系统信息
+
+| 实体.字段 | 业务含义/来源/写入者 | 精确类型/长度/精度 | 可空/默认及产生时机 | PK/FK/UNIQUE/CHECK完整范围 | 读写/敏感/审计/兼容 |
+| --- | --- | --- | --- | --- | --- |
+| `{新增实体全部字段；改动实体的变化与依赖字段}` | `{PRD规则/服务上下文}` | `{可实施定义，枚举及含义}` | `{null/空串/省略区分}` | `{命名和作用域}` | `{具体规则}` |
+
+按实际需要定义编号、租户/归属、创建更新主体与时间、并发版本、软删除及幂等信息，不默认每张表都要全部字段。命名、主键、审计、保留、金额/数量单位、时区/并发及敏感规则有实际约定或例外；待业务答复字段不得提前固化为 DDL。
+
+### 6.4 查询、事务、迁移与回退
+
+| 读写/查询场景 | 精确过滤/连接/排序/范围 | 约束/索引及理由 | 事务/锁/版本/冲突 | 可验证行为 |
+| --- | --- | --- | --- | --- |
+| `{功能/API引用}` | `{不只写按用户查询}` | `{列顺序、唯一范围；性能假设待测}` | `{提交/回滚/重试责任}` | `{成功/拒绝/隔离/计数/冲突}` |
+
+`{现有→目标、DDL/回填顺序、旧值处理、数据量与锁风险、在线兼容窗口、执行前检查、失败恢复、回退限制和保留。新库也说明首次初始化失败边界；设计DDL不代表迁移已执行。}`
+
+## 7. UI—API—服务—数据双向映射
+
+| UI字段/触发或系统来源 | API请求/响应精确路径 | 转换/规则与执行者 | 数据字段/外部来源/派生公式 | 类型/空值/单位差异 | 异常及用例 |
+| --- | --- | --- | --- | --- | --- |
+| `{精确标识}` | `{operationId＋JSON路径}` | `{授权、映射、计算；无转换也注明}` | `{唯一来源及版本}` | `{明确双向约定}` | `{错误与TestCase引用}` |
+
+每个 UI 数据字段有来源、输入有处理去向、响应有生成来源、数据库字段有写入者与用途。隐藏系统字段同样映射；统计/外部/瞬时字段不必建数据库列，派生值写完整公式、过滤范围和更新时间。
+
+## 8. 状态、服务规则与恢复
+
+| 规则/状态 ID | 前置条件与触发者 | 确定分支/后置状态 | 权限、责任与事务 | 拒绝/异常/重复/未知 | 恢复与可观察证据 |
+| --- | --- | --- | --- | --- | --- |
+| `{PRD引用与技术细化}` | `{条件}` | `{允许/禁止转换}` | `{契约/数据引用}` | `{错误码及副作用边界}` | `{查询、补偿、审计、人工介入}` |
+
+跨主题共享状态有唯一权威，分别声明各主题可执行的变化和组合版本兼容关系；两份 AD 各自检查通过不能代替集成一致性检查。前端交互状态、服务端业务状态、Agent运行状态、jobs执行状态及只读派生状态分别归属；模型回答、队列完成或工作流结束不直接代表业务成功，结果未知按权威查询与恢复规则处理。
+
+### 智能能力/工作流（适用时）
+
+`{先说明产品是否需要，未需要写不适用及理由。适用时固定模型/Prompt、输入输出Schema、工具允许范围、副作用授权、业务结果/工作流历史/会话记忆/人工授权各自所有者与存储，补预算、限流、取消、补偿、重试、撤权/过期和恢复后复核。模型回复或工作流结束不作为业务完成的唯一依据。}`
+
+## 9. 安全、质量、观测与工程落位
+
+### 9.1 工程命令、参数、工作目录与前提
+
+按实际工程或模块逐行填写适用的 build、test、lint、dev。命令必须可执行到具体脚本／工具及参数，不只写“运行构建”或工具名称；命令尚未建立时明确标拟建与缺口，不把候选命令写成已运行。
+
+| 用途／工程范围 | 完整命令及必要参数 | 工作目录 cwd | 运行前提与依赖 | 允许副作用／所需授权 | 成功判据及固定依据 |
+| --- | --- | --- | --- | --- | --- |
+| build | `{本工程实际构建命令、目标及参数}` | `{相对项目根或固定工程根的明确目录}` | `{运行时／依赖／配置及准备条件}` | `{产物、生成文件及写入范围}` | `{预期退出／产物；脚本或规范版本}` |
+| test | `{实际测试命令、范围及必要参数；层级细分见TestCase §3.1}` | `{实际测试入口目录}` | `{数据、身份、真实依赖或替身边界}` | `{测试数据／服务副作用及清理边界}` | `{原有质量判据及固定来源}` |
+| lint | `{实际lint／静态检查命令及参数}` | `{实际目录}` | `{配置与插件版本}` | `{只检查或会修复／改写文件，分别明确}` | `{适用规则及失败条件}` |
+| dev | `{实际开发启动命令、服务／模式及参数}` | `{实际目录}` | `{配置、依赖、端口／就绪条件}` | `{监听、进程及可写范围}` | `{如何判断已启动与就绪，区别业务验收}` |
+
+多工程不共用一个含糊 cwd；测试的聚焦范围、全量回归和构建配置按需分行。某用途不适用时说明实际依据，未知时登记问题，不套用示例技术栈或猜测命令。说明参数是否改写文件、启动服务、访问外部系统或触发危险动作；本表只定义工程输入，不能自行授权执行。实际运行命令、条件与结果仍记录在任务验证或测试报告。
+
+### 9.2 项目目录与维护位置
+
+| 真实或拟建路径 | 内容与职责 | 所属工程／维护方 | 与本主题的关系 | 固定来源／当前事实 |
+| --- | --- | --- | --- | --- |
+| `{源码根与本主题模块路径}` | `{生产源码、共享模块及边界}` | `{明确责任}` | `{功能／契约条目}` | `{实际仓库位置或有依据的拟建方案}` |
+| `{测试与测试配置路径}` | `{单元／契约／集成／E2E等目录及入口}` | `{明确责任}` | `{与TestCase §3.1一致}` | `{固定配置；未存在如实注明}` |
+| `{文档／契约及适用生成物路径}` | `{规格、ADR、约束、接口定义或构建产物}` | `{权威维护位置与生成归属}` | `{可编辑原文／只读投影／生成内容分别说明}` | `{现有约定优先，不另建平行权威}` |
+
+路径表达实际代码、测试和文档组织，不从能力目录推导仓库或部署边界。沿用已建立的目录约定；实际目录变更须属于本次获准工程任务范围，不因填表自动执行或另作授权。
+
+### 9.3 真实代码风格示例与规范
+
+`{给出本项目一段真实、可定位的代码示例，注明文件路径、固定提交／版本及它体现的规则；或准确引用已采用、可回读的编码规范及其实际示例。包含命名、格式、模块／组件模式等本次适用约定，不只写“遵循最佳实践”。尚无真实示例或已采用规范时登记待确认，不把模型生成的建议冒充既有风格。}`
+
+| 适用语言／工程／范围 | 命名与格式规则 | 真实示例或固定规范及准确位置 | 检查配置／命令引用 | 例外及实际认可来源 |
+| --- | --- | --- | --- | --- |
+| `{本主题实际技术范围}` | `{实际规则及现有模式}` | `{可回读路径／版本／条目}` | `{AD §9.1及真实配置}` | `{无则写无；建议不算已批准例外}` |
+
+### 9.4 Always／Ask first／Never 工程边界
+
+业务角色权限与研发工程动作边界分别表达。读取现有项目规则、适用原 Skill 和真实用户决定，保留其约束；不得因本表或外部编排而静默降低要求。
+
+| 等级 | 明确动作与适用对象 | 必须满足的条件／触发点 | 权威规则或真实决定来源 | 尚未确认的影响 |
+| --- | --- | --- | --- | --- |
+| Always do | `{必须执行的验证、命名、输入校验等实际规则}` | `{何时、在哪个工程范围执行}` | `{原规则及准确版本／位置}` | `{具体缺口}` |
+| Ask first | `{原规则要求先问的数据库结构、依赖、CI等实际动作}` | `{何种变化需先取得谁对什么范围的决定}` | `{原要求与已取得的有效决定分别记录}` | `{没有决定不能填成已批准}` |
+| Never do | `{原规则禁止的密钥提交、越界编辑、无批准删除失败测试等实际动作}` | `{适用限制；不能以赶进度为例外}` | `{固定规则}` | `{冲突或例外请求先澄清}` |
+
+表中举例用于提示填写，不新增许可或自动批准例外。已有认可仅在真实对象和范围内复用；若项目规则与原技能要求冲突，先记录并澄清，不用模板优先级自行覆盖。
+
+### 9.5 安全、质量、观测与工程交接
+
+| 工程要求与固定依据 | 具体实施位置 | 条件/阈值/判据 | TestCase 方法与所需证据 | 未决及影响 |
+| --- | --- | --- | --- | --- |
+| `{身份/功能及资源权限/隔离/敏感信息/性能/可靠性/可访问性}` | `{组件/API/字段/规则}` | `{有来源，未知不造数字}` | `{未形成注明}` | `{责任与范围}` |
+
+`{日志/指标/追踪的关联标识、关键事件、脱敏/保留、告警与处置责任。基础组件能力不自动等于本产品目标已达到。}`
+
+### 9.6 工程骨架采用与落地
+
+| 工程/仓库/模块范围 | 实际骨架或拟采用模板及固定来源 | 初始化/增量内容 | 构建/启动/配置/依赖 | 测试与恢复前提 | 当前事实 |
+| --- | --- | --- | --- | --- | --- |
+| `{一能力不强制一工程}` | `{实际取得或待提供}` | `{只写有依据的工程任务}` | `{精确规则或缺口}` | `{必要条件}` | `{已存在/拟建/待核实}` |
+
+固定引用 §9.1–9.4 的命令、目录、代码风格和工程边界，不手工维护第二套不同答案。补充依赖与锁文件、构建制品、环境和密钥引用、部署顺序、特性开关、迁移兼容、回滚和运行交接；测试框架、测试目录、层级及适用覆盖要求由 TestCase §3.1 承接。不给真实凭据，不把配置计划当实际就绪，不代替生产授权；CONSTRAINTS、ADR 等辅助产物仍按原方法和项目约定维护。
+
+骨架引用必须最终落到真实模板／源码、明确版本或来源记录及所选目录；只有目录图或本模板占位行时记录“工程资产未取得”，不能写成可应用工程。优先保留现有仓库及人工代码，采用说明可引用源码及差异，不要求复制另一份平行骨架。适用的pbc-composite／agent-standalone与frontend／backend／agents／jobs按实际选择说明，contracts／shared／tests／delivery的责任不能遗漏；不需要的工程说明依据，不默认一PBC一仓库或一服务。
+
+AD只选择并定义落实与例外；原Plan据此安排初始化或增量任务、文件责任、验证和恢复；获准Build才实际应用模板或改动工程。现有工程根可记录真实路径，新工程未创建时只写拟建位置和缺口。contracts.lock在正式采用外部契约时形成；templates.lock及生成基线在实际应用并完成相应验证后形成；本次AD写作不创建锁、工程、运行报告或第二套任务tracker。更新须保护人工修改，实际应用失败不能覆盖旧有效基线，细节交I4／I5工程验证。
+
+## 10. TestCase 与实施计划交接
+
+| PRD需求/AC或工程条款 | AD精确落点 | 可观察成功/失败/副作用 | TestCase用例或待形成 | 实施前提与依赖 |
+| --- | --- | --- | --- | --- |
+| `{固定条目}` | `{图/字段/契约/事务/规则}` | `{可断言结果}` | `{固定引用或缺口}` | `{环境/契约/数据/工具/认可}` |
+
+先判断设计能否据以制定 Plan，再由 Plan 获得范围/执行模式认可并核实任务条件；不能把获批 Plan 写成形成 Plan 的前置要求。共享底座或独立技术准备可形成有依据的任务，不借初始化提前生成未定业务字段/权限/接口。
+
+### 10.1 公共变更、例外与影响范围
+
+| 变更对象、旧→新及来源 | 变化条款／语义和原因 | 直接与必要传递的契约／实体 | 消费AD／需求或AC | TestCase／实际Plan任务／交付影响 | 决定依据、证据及允许范围 |
+| --- | --- | --- | --- | --- | --- |
+| `{规范／契约／骨架／本AD；同路径修改也列实际变化}` | `{原规则、候选或真实决定分别说明}` | `{唯一权威及准确内容}` | `{固定版本和精确落点}` | `{真实引用；未形成写待形成，不补造任务／报告}` | `{受影响／不受影响、保留旧组合、例外、Q和重新核对}` |
+
+先确定变化及来源，再定位直接和必要传递消费者，核行为、权限、数据、迁移和运行组合，提出最小处理及恢复。公共定义改变需在其权威位置处理；本主题AD只记录建议和影响，不自行修改公共规范、契约或另一主题。保留原有有效需求及已交付行为的回归，范围降级或移出须有来源和真实决定；不机械重写无关AD、强制升版或重新询问未受影响的已有授权。
+
+独立审查只读标注，使用者可人工处理、明确委托修订、有据不采纳或保留Q；按改动影响复查，零问题不等于业务批准。若JSON清单尚未接入，直接手动传递准确路径仍有效。交原Plan时任务须保留实际PRD、AD、规范、契约、骨架来源及验证依据；Build按获准任务回读，输入变化先核与计划的影响，不靠可变清单链接或旧会话摘要代替正文。
+
+## 11. 完成核对、问题与版本记录
+
+- 三图已按真实范围填写，图、字段、接口、状态和责任一致，无占位图冒充完成。
+- 每个有效需求/AC/子项及质量条目有工程落点，正常、拒绝、异常和恢复均可判定。
+- 字段/API/事务/迁移与双向映射可实施，权威定义单源；未知关键业务参数不留给编码猜。
+- PRD 与实际采用的原型、公共基线及附件固定引用可回读，跨主题兼容关系明确；原型未形成或不适用时说明影响，不阻止独立范围的 AD 起草。
+- 适用 build／test／lint／dev 的完整命令、参数、cwd 和前提明确，源码／测试／文档目录、真实风格示例或固定规范、Always／Ask／Never 边界均有依据；缺项或不适用如实说明。
+- §0.3采用表、§2.3兼容组合、§5.2提供／消费、§6.2.1数据责任、§9.6骨架来源及§10.1变更影响相互一致；同号或Schema通过不代替语义兼容。
+- 公共规范优先复用，缺失及例外有依据；人工编辑可回读且不被恢复，未受影响主题和共享文件责任明确。
+- 实施位置和验证前提明确，设计、代码、实际测试和上线分别报告；未生成工程、锁或报告不登记成已存在。
+
+| 问题 ID | 缺失/冲突及来源 | 受影响要求/契约/任务 | 可继续部分 | 责任、最晚时点与真实关闭依据 |
+| --- | --- | --- | --- | --- |
+| `{稳定ID}` | `{事实/假设分开}` | `{具体范围}` | `{独立工作}` | `{未知责任如实写}` |
+
+本次交接结论：`{可交接的具体范围、不能交接范围及原因；实际认可及限制，不预填就绪。}`
+
+版本变化：`{版本、时间、来源变化、受影响PRD条目/图/字段/契约/用例/任务/证据，以及重新采用/复核安排；旧确认不搬到新内容。}`

package/references/enterprise-sop-resources/assets-manifest.json

@@ -0,0 +1,199 @@
+{
+  "schemaVersion": 1,
+  "resourceId": "i3-enterprise-sop",
+  "resourceVersion": "0.16.2",
+  "status": "local-short-command-plan-candidate",
+  "index": "stages.json",
+  "files": [
+    {
+      "path": "README.md",
+      "sourceSha256": "85dec32c439e9ed0481bdccf5d9705dce09db08990a13cf8b894484c10ed1c30",
+      "sha256": "b9f6a2a7e9735dd0d3846098255775d1471362a2147679f86904cc676fd6fb06",
+      "role": "shared-guidance"
+    },
+    {
+      "path": "template-contracts.md",
+      "sourceSha256": "2191a528b5b880ffcdcaee5c950dd88eea14c0219396021334dd7f872a5eaad0",
+      "sha256": "8088464b3fe260a1d36f92b2678dd3e724c6325ad3202a2e4387296f598fcfce",
+      "role": "shared-guidance"
+    },
+    {
+      "path": "codebuddy-project-guide.md",
+      "sourceSha256": "e361662cbfe5996143e9c873094f0a61e955a163a9956e0b7da1b86389b73032",
+      "sha256": "ea64bc1f521b8dc38b718d81b983d9b1d14344173c029c077bf128b0b6f800de",
+      "role": "shared-guidance"
+    },
+    {
+      "path": "stages.json",
+      "sourceSha256": "a2048acd71bbdfa78f9f81f4b6b90eee3e1d3229697731a6fd7c17979b08a04b",
+      "sha256": "9210982a926a7ec1a9e63e48b165a2dba0641d19d7739f656f4f35c80e3c3c6f",
+      "role": "stage-index"
+    },
+    {
+      "path": "handoff-contract.md",
+      "sourceSha256": "a2156a58ec75c9e0b5af3b7290bf464d1bcffde4965b3487156b7efdfd55437c",
+      "sha256": "558d9d0524dbd503dd99d175387827b1c29394cb0bbd7fb1423ff2232c6a6e93",
+      "role": "shared-handoff-contract"
+    },
+    {
+      "path": "lifecycle-contract.md",
+      "role": "shared-lifecycle-contract",
+      "sourceSha256": "816dcddc8c6824bcaf5f466f541714d62c82d3a2a281460ea041009e1fe61965",
+      "sha256": "e037a1cde62140d4cac12d9f02b195d99c6091982503cd1f4b3642776ef4ab3d"
+    },
+    {
+      "path": "verification/README.md",
+      "role": "read-evidence-guide",
+      "sourceSha256": "2ce5c4984bd2da9b1c3b451eeecf79fc50b189bea32844bb337592a86032b04c",
+      "sha256": "fa39cdc3639911676397e891ed85d11558abf36ff8f0397384dd9b76d655c4a3"
+    },
+    {
+      "path": "verification/check_reads.py",
+      "role": "readonly-read-evidence-checker",
+      "sourceSha256": "718834c11183dd8d37b48bca4c262330d66a9f4cdc7ceee76b3a2809809a7e5c",
+      "sha256": "718834c11183dd8d37b48bca4c262330d66a9f4cdc7ceee76b3a2809809a7e5c"
+    },
+    {
+      "path": "verification/review-output.schema.json",
+      "role": "readonly-review-output-contract",
+      "sourceSha256": "366dcfe39d5dca6a99b6eff5af400f288ed164cca04e28de316b36cadcfc42b1",
+      "sha256": "70e2e5c66c72fc52193310a5b52f43faaabda192619baa365751c398b4a4d944"
+    },
+    {
+      "path": "handoff.py",
+      "role": "path-only-handoff-helper",
+      "sourceSha256": "47646c379e47aa68af65f3ed9241cafe6cfa98bc0f87e352e15ebd17384e7d31",
+      "sha256": "47646c379e47aa68af65f3ed9241cafe6cfa98bc0f87e352e15ebd17384e7d31"
+    },
+    {
+      "path": "verification/check_execution.py",
+      "role": "readonly-execution-report-checker",
+      "sourceSha256": "8afc04b48e145c30dba17299d5a6296cd56f200e440d7b56f048cd30fe58c0c5",
+      "sha256": "8afc04b48e145c30dba17299d5a6296cd56f200e440d7b56f048cd30fe58c0c5"
+    },
+    {
+      "path": "verification/check_native_execution.py",
+      "role": "readonly-native-execution-report-checker",
+      "sourceSha256": "4ca29aad4e88119cf5ae40fe21c5dab9f0acb4a65e349f9fdbb16955ab12d0ee",
+      "sha256": "4ca29aad4e88119cf5ae40fe21c5dab9f0acb4a65e349f9fdbb16955ab12d0ee"
+    },
+    {
+      "path": "recovery-contract.md",
+      "role": "shared-minimal-recovery-guidance",
+      "sourceSha256": "2de34a682703a45d660d18986217e0094a81477181e783a338b152e83c6b6f16",
+      "sha256": "c057f525d39923905b1b0cbe9a1eee76df8874993867d9d209e5949c1289d4a3"
+    },
+    {
+      "path": "controlled_handoff.py",
+      "role": "explicit-controlled-handoff-adapter",
+      "sourceSha256": "3ddd708560eaeb9ce32fb7c6a7e8dededc331e5fcfe742290c0cc42cbd74403f",
+      "sha256": "9816ff559e4890d168c47858ddab256ff321c07f456209c6f8f34cedb3d43212"
+    },
+    {
+      "path": "controlled-handoff.md",
+      "role": "controlled-handoff-contract",
+      "sourceSha256": "37b7c053a48a4127e50913296988f8db4ff734d94be002e494b30959baa40dda",
+      "sha256": "40daaaea72d4c2766f39d0cae46c71fc7ef5c021fcfa5d65153481d34b151f06"
+    },
+    {
+      "path": "selection_handoff.py",
+      "role": "same-topic-selection-helper",
+      "sourceSha256": "44b3fd8c8de985efa80054ee43402b338b1855a3eed1aef00153c55c69ee5ed0",
+      "sha256": "44b3fd8c8de985efa80054ee43402b338b1855a3eed1aef00153c55c69ee5ed0"
+    },
+    {
+      "path": "selection-handoff.md",
+      "role": "same-topic-selection-contract",
+      "sourceSha256": "0ea2e2058b4cd9c820b2836d6ab9c01f5d8a717c46d8758334003407980c332c",
+      "sha256": "a338b4aecabd3353ea871322ec9f016e2590858182a5aa0a5b6f2d5ec7119afb"
+    },
+    {
+      "path": "review-handoff.md",
+      "role": "independent-readonly-review-contract",
+      "sourceSha256": "ebe62b4a7d50bfd7a54dcff6897686a2fd3736302242a9144b6281ddff6085cb",
+      "sha256": "a04238ea42eda2c9ed198a20917f589a53ee3a301472b312ffa60a68614115e3"
+    },
+    {
+      "path": "verification/review_handoff.py",
+      "role": "explicit-independent-review-adapter",
+      "sourceSha256": "d5d902f43b3893b2d686ce71a8cae21beaad807959e5f09ed6d0e6e008a2a728",
+      "sha256": "d5d902f43b3893b2d686ce71a8cae21beaad807959e5f09ed6d0e6e008a2a728"
+    },
+    {
+      "path": "plan-handoff.md",
+      "role": "explicit-native-plan-handoff",
+      "sourceSha256": "35505e939e4b20249d11e90656305c2d48663213a396bb1e9c11b01c7dbbe9ae",
+      "sha256": "594c4b34f7b58ea6f9367ca73e968565a88c0a934a55495bc54e4cb0b4bc11f8"
+    }
+  ],
+  "stageManifests": [
+    {
+      "stage": "brd",
+      "path": "brd/assets-manifest.json",
+      "resourceVersion": "0.2.3",
+      "sha256": "f2aa07526c0511d7630fe1c7a62ca210ce26dc47e20d9c003ff25c67d4a0109e"
+    },
+    {
+      "stage": "prd",
+      "path": "prd/assets-manifest.json",
+      "resourceVersion": "0.3.3",
+      "sha256": "a39068389dda581c153a378d02b3f706db7a59088fe6d7fd5ffc1e5db3021071"
+    },
+    {
+      "stage": "ad",
+      "path": "ad/assets-manifest.json",
+      "resourceVersion": "0.3.3",
+      "sha256": "54e85603508d82cb0b44cdf8e2c89bf0c1b60fe9d58f8ee1be7e9688be2ee4da"
+    },
+    {
+      "stage": "testcase",
+      "path": "testcase/assets-manifest.json",
+      "resourceVersion": "0.3.4",
+      "sha256": "8773f990f1cc387fd97e1950c27791f0ba5e90ed245f43eb5dadb5bc5644fed2"
+    }
+  ],
+  "existingPrdSubtreePreserved": false,
+  "runtimeDependenciesOutsideResourceRoot": false,
+  "newSkillOrCommandIncluded": true,
+  "engineeringAssetsIncluded": false,
+  "autoSupported": false,
+  "revision": "20261019-S00-S06-minimal",
+  "revisionScope": "Owned Plan shared-read and identity/upstream stop clarification; original methods, business drafts, templates and three-field JSON unchanged.",
+  "auxiliaryManifests": [
+    {
+      "resourceId": "technical-baseline",
+      "path": "technical-baseline/assets-manifest.json",
+      "resourceVersion": "0.2.0",
+      "sha256": "f75504397858c3628226c2a0b2939ed4a105c182932949f14ff1ef9fd9a947fc",
+      "businessStage": false
+    }
+  ],
+  "jsonRegistrationImplemented": true,
+  "existingPrdTemplatePreserved": true,
+  "candidateRevision": "20261021-plan-gates-r4",
+  "reviewContractRevision": {
+    "revision": "20261019-B05-review-contract",
+    "scope": "strict report contract, classified diagnostics and caller-bound source roles; no business template or original method changes",
+    "previousCandidate": "20261018-B05-closure-r2"
+  },
+  "roleSchemaRevision": {
+    "revision": "20261019-B05-role-schema-closure",
+    "scope": "shared scope role bindings and schema generator; separate report-object validation for authorized correction",
+    "previousCandidate": "20261019-B05-review-contract-r1"
+  },
+  "newSkillIncluded": true,
+  "newCommandIncluded": true,
+  "executionReportRevision": {
+    "version": "0.1.0",
+    "scope": "Owned direct helper report supports help/init/select/resolve/other; no candidate operation; source edit not tested"
+  },
+  "nativeExecutionReportRevision": {
+    "version": "0.1.0",
+    "scope": "separate native evidence profile, actual tool/report reconciliation and explicit gate meanings; business drafts unchanged"
+  },
+  "minimalRecoveryRevision": {
+    "version": "0.4.0",
+    "scope": "explicitly selected reference backfill, human edit protection and same-topic selection; no candidate registry; not tested"
+  },
+  "controlledHandoffRevision": "20261020-selected-only-untested"
+}

package/references/enterprise-sop-resources/brd/README.md

@@ -0,0 +1,50 @@
+# 企业 SOP · BRD 阶段资源
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+当前子包版本：0.2.3；模板内容版本沿本阶段manifest，正文不改。下文B05等旧版本文字保留为历史说明。
+
+审查加载分支：review／recheck完整读取本README、完整模板、唯一动作、实际业务与采用约束，依[统一审查约定](../review-handoff.md)由外层解析元数据并保留变化核对。下文涉及整套共用文件的加载要求在这两个动作按该分支理解；未知自改组合完整读选定原件，其余作业及实质条款保持。
+
+前版子包版本：0.2.2；模板内容版本：v0.0.3。状态：本地候选，尚未发布。完整[模板](templates/BRD.md)和[共用合同](../template-contracts.md)用于明确任务，不新增Skill／命令／自动调度，原方法内容／工具／认可／停轮保留。
+
+从[入口](../README.md)和[阶段索引](../stages.json)选本阶段，按[清单](assets-manifest.json)定位[生成](prompts/01-generate.md)、[独立只读审查](prompts/02-review.md)、[明确委托修订](prompts/03-revise.md)、[独立只读复查](prompts/04-recheck.md)，四作业不自动串行。可复用方法：访谈／概念澄清／文档，适用时i3-spec-driven-development；实际原生调用和读取分别取证。
+
+## 1. 本阶段输入与内容
+
+
+- 从真实背景、目标、角色、场景和BR核对范围，候选假设与已确认事实分开。EBC一份逻辑BRD有版本历史，不增MVP层。
+- 按目标、输入输出、对象／规则责任、依赖和独立演进边界提出PBC，不能按页面、部门、表或服务机械拆分。预给候选不能冒充任意业务自动识别成功。
+- BR到PBC分配、共享／未承接项、闭环、排除与收益验证可追溯；指标、权限、负责人或里程碑未知列Q，不编造。
+- 只交业务候选和PRD交接，不要求先有AD／TestCase，不宣称单份BRD满足六项或已获准编码。
+
+
+## 2. 来源与项目采用
+
+模板基于固定设计v0.0.2，仅调整分发标题、版本／状态和包内相对合同链接，完整正文责任保留。维护来源／真实摘要在清单derivedFrom中标included:false，不要求业务用户读取开发目录。
+
+sourceSha256为源码字节，sha256为既有品牌流程分发字节，清单不算自身哈希。项目副本先检查目标和人工修改；明确采用的自改副本优先，当前local hash与发行来源分开，不强制恢复原件。模板版本、项目修订与业务版本分开，不猜最新或机械升版。
+
+## 3. 写入、人工修改与退出
+
+模型从已读项目约定整理准确输入／模板／唯一目标及缺口，用户不必填每个路径。目标已存在先读和保留旧稿，不覆盖未读人工内容；仅授权目标可写。最后编辑后回读，新增规范要求逐条回源，权限／状态一致，逐表核列数和列义。
+
+review／recheck在独立新上下文只读会话输出，审查者零项目写入，报告由获准调用者另存。人可自行修改、明确委托、有据不采纳或保持Q，修订不代答业务决定。
+
+候选完成汇报实际来源／目标、假设／Q、自查和未执行事项后交人工审阅并停轮，不自动其他文档、Plan、Build、测试执行、提交或发布。模板／包／安装／宿主读取／模型行为／业务人审分别记录，本文不宣称完整3.0或所有宿主通过。
+
+## B05 变更交接规则
+
+资源子包0.2.0，模板正文和版本保持。按[入口](../README.md)§3列本次必要读取，实际读三份共用合同及本次唯一动作；[生命周期合同](../lifecycle-contract.md)统一新增、修改、撤销和退役，不新增命令、JSON程序或工程执行器。
+
+业务目标／能力边界／跨PBC责任未变时复用原BRD；新增主题不补造业务批准，变化只改本次明确范围。原方法停点、只读审查与人工空间、候选／选择／Plan边界保留，项目副本升级不覆盖人工内容。
+
+## B05收口资源增量
+
+B05当时子包0.2.1，模板正文及版本不改。统一修订全文回读措辞、适用来源和单项目审查证据；外层校验见[说明](../verification/README.md)。不把辅助资料／Plan统一变前置，不自动改业务稿、JSON、任务或原版方法。旧验证与历史版本按当时对象保留。