@givolt/i3-composer-agent 2.3.6 → 3.0.0

package/references/engineering-skeleton-resources/adoption.md

@@ -0,0 +1,200 @@
+# 工程目录规范的采用与原 Plan／Build 交接
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+版本：1.0.0。配套：[工程目录规范](directory-standard.md)。适用于明确选择该规范的新项目或现有项目，不随安装自动启用。§1—5 以企业 AD 交接为例；标准项目沿用自己的 SPEC 或等效规格，不补企业文档。存量接入、选择性更新和人工保护见 §6；入口与资源索引见 [README](README.md)。
+
+## 1. 采用时明确什么
+
+先确定真实业务项目根、当前能力／需求主题、所选 AD 及已有代码位置。项目已有工程规范时优先复用；本资源补充目录职责或映射，不重选技术栈，也不把维护 i3 Skill 的仓库当成业务工程根。
+
+目录规范可以在 AD 准备时选定，无需另外调用一个工程骨架命令。技术栈、工程内部布局及构建命令仍由公共技术规约、实际配置和 AD 明确。目录规范能够先采用；尚未确定的技术决策只限制依赖它的设计或实施任务。
+
+将采用结果写入项目已有工程说明；没有合适位置时，可使用 docs/engineering/engineering-layout.md，或直接写在 AD 的相应章节。以下是填写要点，实际路径和状态据实填写，不为每个项目重复建立全部文档：
+
+| 项目 | 填写内容 |
+| --- | --- |
+| 采用来源 | 实际采用规范的真实可读路径及正文版本（本资源为 1.0.0）；使用项目副本时保留其来源、明确选用范围及本项目修改说明 |
+| 组织方式 | pbc-composite 或 agent-standalone；选择理由与项目根 |
+| 实际工程映射 | 工程稳定标识、类别、实际根、已有／拟建、业务模块、共享维护方与消费者 |
+| 配套依据 | 当前 AD 的身份／版本／路径、公共技术规约、必要契约及已有代码 |
+| 目录例外 | 现有结构或框架惯例与规范示例的差异、理由、影响及明确采用情况 |
+| 验证要求 | 本次文件落点核对及实际构建／测试方法；尚无代码时写待实施，不预填通过 |
+
+使用项目已采用副本后，以该副本为本次输入；发行资源更新不覆盖它。原路径失效、版本含糊或映射冲突时先说明准确缺项，不静默改读另一个来源。
+
+## 2. AD 如何引用
+
+沿用现有 AD 模板的栏目，不修改模板或原 Spec：
+
+| 现有 AD 位置 | 本次承接内容 |
+| --- | --- |
+| §0.3 公共技术规约、契约与骨架的本次采用 | 引用目录规范或项目采用说明的准确路径／版本，说明适用工程 |
+| §9.2 项目目录与维护位置 | 工程根、模块／源码、配置、测试、契约和运行装配的真实或拟建路径及 owner |
+| §9.6 工程骨架采用与落地 | 区分现有工程事实与拟建内容；落实当前技术选择、构建／启动／验证／恢复条件及依赖缺口 |
+
+其他版本的 AD 使用同义栏目。AD 的整体技术架构图、功能架构图、数据实体关系及必要详细设计仍完整保留，不能以目录规范替代。
+
+目录标准是实际可读的规范输入，不能据此把“可运行代码模板已取得”或“工程已生成”填为成功。未采用代码框架模板时可据实写“目录规范已采用；工程拟建；未采用代码框架模板”；语言／框架代码由后续获准任务实现。已有代码则引用真实代码／配置。若本项目另行要求复用特定代码模板，仍需取得它，不由本规范替代。
+
+一个 PBC 多份主题 PRD 的各自 AD 引用同一项目规范，并分别映射相关模块；不因 PRD 数量或版本变化重复创建工程。
+
+## 3. 交给原 Plan 的方式
+
+原 Plan 读取 SPEC.md 或等效规格。选定 AD 与其准确 PRD、公共技术规约、契约及目录采用说明共同提供本次等效规格；原 SPEC 六项内容须足够明确。独立 TestCase 为可选输入，已有且适用就引用；原型按需，可与 AD 并行。
+
+手动方式直接提供上述实际路径。已有三字段 JSON 时，可让本次任务先解析 selected 中当前主题的 engineeringSkeleton 及配套路径，再实际读取正文；选择路径不等于读取成功、认可或实施许可。无需为了目录规范新建 JSON，也不把工程说明写入新的顶层字段。
+
+先按当前主题读采用说明和必要规范条款，再读该主题 AD／PRD、所涉代码和共享消费者；不一次加载全部历史、所有主题或所有工程源码。跨主题共用约束及直接依赖仍须读齐。
+
+在项目根使用以下提示；替换方括号中的实际路径。它是原命令的明确任务上下文，不是新增命令参数：
+
+```text
+/i3-plan
+为本次已明确的需求范围制定计划：
+AD：[实际 AD 路径]；准确 PRD：[实际 PRD 路径]。
+公共技术规约：[已采用规范路径]；工程目录采用说明：[实际路径]。
+必要共享契约及已有代码：[实际路径；没有则说明不适用]。
+请实际读取这些来源；缺项或冲突先列出，不猜技术版本。
+按 AD 的工程／模块映射拆任务，明确新增或修改文件相对项目根的位置、
+工程负责人／共享依赖、验收条件及实际验证方法。
+将源码、配置和测试放入已采用位置；已有结构的例外明确写在计划里。
+保留原 Plan 的默认产物、唯一任务目标和审阅停点，不改业务稿。
+```
+
+计划沿用 tasks/plan.md 和原方法确定的唯一任务目标；默认文件目标为 tasks/todo.md，采用其他 tracker 时不复制竞争状态。不同未完成工作不覆盖。工程落点不是把模块名写入任务即可：任务的 Files likely touched 应包含预计路径，验收条件要核对真实新增／修改文件；实施中合理新增文件也须按映射核对。
+
+## 4. 原 Build 如何执行
+
+计划满足原有认可及执行条件后，原 Build 从计划取任务。任务必须指向当前 AD、目录采用说明和所需规范，使执行时能实际回读，而非只相信计划摘要或 JSON 的存在。
+
+```text
+/i3-build
+执行当前计划的下一项获准任务。
+先回读该任务引用的 AD、目录采用说明及所需规范／代码。
+按已采用工程根和模块路径实现；出现目录冲突先说明位置、原因和建议，
+不自行另建同名工程或把源码放进 spec、tasks、文档模板目录。
+完成原有验证后，对照任务及目录映射列出实际变更文件和落点差异。
+业务稿、人工代码和已完成任务按原规则保留。
+```
+
+原 /i3-build auto 使用同一份获准 Plan 和目录映射，保持原有 spec/ 识别、Git、计划认可、TDD／构建及逐任务执行条件。它不会因为本资源存在而自动读取规范；需要时在本次任务上下文明确引用。企业跨阶段 auto／调度不在本资源范围。
+
+规范期望目录约束被设计、任务和验收共同落实，不提供拦截一切写入的 Hook。未实际读取、任务没有落点或实际文件越界时，不声称目录验收通过。
+
+## 5. Build 后如何核目录
+
+在实际业务项目中核对本次任务新增、修改和必要删除的文件。可用 git status --short、针对任务的 git diff／文件清单及实际配置获取事实；不把其他人的未提交文件混作本次结果，也不只看空目录树。
+
+| 核对项 | 通过条件 |
+| --- | --- |
+| 来源与范围 | 当前 AD、目录采用说明及任务可回读，采用版本和实际工程根一致 |
+| 文件落点 | 每个变更文件都能映射到工程／模块、共用资产或原有管理文档位置；例外有明确依据 |
+| 工程边界 | 同一工程标识未重复创建，未按每份 PRD 再造底座；没有未经采用的顶层代码目录 |
+| 共享责任 | 契约、共用代码及跨工程测试各有实际维护位置与相关消费者，未复制其他主题的共享权威 |
+| 构建与测试 | 实际配置的源码、资源、测试和产物路径与采用映射一致；完成本次要求的原有验证 |
+| 人工内容 | 既有目录、项目自改规范、人工代码和已完成任务保留；无整仓覆盖或未经说明的移动／删除 |
+
+结果沿用原工程验证记录或本次任务总结，至少列出“文件／实际位置／采用依据／差异处理／验证结果”。不另建任务完成率或审批状态文件。构建产物、依赖、缓存按实际工具配置和忽略规则处理，不因出现 dist、target、node_modules 等就判源码越界。
+
+落点有偏差时先标注准确位置、影响、推荐和可选处理（按规范调整，或明确采用例外后同步 AD／Plan），不自动移动人工代码或改业务稿。目录核对通过与构建、业务测试、独立审查、Ship 就绪及发布分别记录。
+
+## 6. 现有工程与后续变更
+
+### 6.1 先确定本次范围与真实现状
+
+仅在本次任务明确采用或项目已采用指引指定时读取本资源。标准项目沿用自己的 SPEC 或等效规格，目录采用不要求补企业 BRD／PRD／AD；§2—5 的 AD 交接是企业 SOP 用法，标准项目将相同目录依据交给自己的规格与原 Plan。安装、目录存在、PRD 或 JSON 字样不激活企业 SOP。
+
+先确定实际业务项目根、本次需求／工程范围、已选规格、当前采用说明和唯一任务目标，再只读检查相关工程入口、源码／测试、构建／运行配置、项目自改说明及必要共享消费者。按当前主题加载必要来源和直接依赖，不一次读全部历史或所有工程；不猜语言／框架版本，不因缺项重选技术栈。
+
+### 6.2 把现有目录映射到逻辑职责
+
+| 逻辑职责 | 现有位置示例 | 映射与保护要求 |
+| --- | --- | --- |
+| frontend | web/、apps/console/ | 保留前端工程标识、框架入口和内部结构；不另外生成同名 frontend 工程 |
+| backend | services/asset-api/、server/ | 映射真实源码／测试／配置位置，不再建 backend/asset-api/ 的第二套底座 |
+| agents | 项目根“.”、已有服务内模块、agents/ 下工程 | 独立 Agent 可沿用根布局；服务内组件映射真实子路径，不强行拆工程 |
+| jobs | worker/、jobs/、现有后端任务模块 | 按触发与执行职责映射；目录名不决定进程或部署边界 |
+| 共用资产与配置 | 既有契约、shared、测试、CI／运行装配位置 | 保留实际维护位置、owner 和消费者；不按每份 PRD 复制共享权威 |
+
+采用结果复用项目现有工程说明，或写入当前规格；没有合适载体时才按需使用 docs/engineering/engineering-layout.md。至少列出来源／版本、项目根与组织方式、工程稳定标识及类别、实际根、已有／拟建、源码／配置／测试位置、维护方／消费者、例外与理由、真实验证命令和未定项。不要求每个项目重复建全部文档。
+
+在只读接入阶段，输出映射建议、缺项和影响，不创建目录、不写采用说明、不改业务稿或 JSON。人明确采用后才更新获准的工程说明；规格变化可由人修改或按原 Spec 形成候审稿，I5 不自动修业务稿。缺失事实只限制依赖它的任务，不能无依据阻断其他范围。
+
+已有不同工作的未完计划时，指出准确冲突并保留 tasks/plan.md、todo 或已有 tracker；不覆盖、批量关闭或另建竞争任务库。接入规范不清除旧任务、未提交改动或原始失败记录。
+
+### 6.3 比较新资源，再明确选择
+
+实际读取项目当前采用说明／副本，以及本次明确比较的新资源；先展示准确路径、正文版本、条款差异、项目例外和受影响工程／规格／未完任务。如有可读的旧采用来源，可辅助判断；没有时列明无法确定之处，不猜哪些段落属于用户修改，不建立新的基线库或自动合并器。
+
+| 选择 | 可写范围 | 后续依据 |
+| --- | --- | --- |
+| 保留当前 | 项目采用资料、业务稿、JSON、代码和历史均不写；在本次答复说明选择即可 | 继续读取原采用文件，不因新资源可读而换源 |
+| 部分采用 | 仅更新明确选中的条款及必要采用说明；保留其余本地约定和人工段落 | 标明选用来源／版本、选中条款及本地例外，不宣称整套新版都已采用 |
+| 整体采用 | 明确替换的是哪些规范内容，并逐项说明人工差异如何保留或处理；变更前保留原文件历史 | 新项目采用资料成为依据；整体采用不等于整文件／整仓覆盖或源码迁移 |
+
+人已明确选择且范围充分时继续完成该范围，不重复索要同一确认。涉及未明确的冲突，先给出准确位置、影响、推荐和可选操作：保留原约定、采用具体条款，或先人工修改。审查只标注问题，保留人工修改空间；不以审查意见自动修业务稿。
+
+仅改获准位置，保留人工代码、项目副本、其他主题及已完成任务。无法区分段落或文件归属时先列冲突，不把整个文件当成可替换生成物。选定新规则与现有规格／任务不一致时，先处理受影响范围，再实施依赖它的任务；采用说明更新不自动扩大已有 Build／auto 授权。
+
+### 6.4 版本和引用如何传递
+
+资源版本、项目采用内容和已实现工程分别核对。1.0.0 是资源内容版本，不使项目规格、工程代码或软件发行版自动升级。项目采用内容沿用现有文档版本／变更记录；版本从实际文件名与正文回读，不新增强制版本字段、成功锁或另一套状态库。
+
+手动方式直接交入当前规格、已采用说明及必要技术规范／契约／代码的实际路径。已有业务 JSON 顶层仍只有 schemaVersion、scope、selected，需要时沿用 selected.topics 中该主题 engineeringSkeleton 的字符串路径。没有 JSON 可以继续，不为本资源强制新建清单。
+
+采用文件路径未变时，JSON 不为记录版本重复写入；同路径人工改稿后重新读当前正文并核对任务，不要求保持旧 SHA256，不凭旧报告沿用认可。路径确需改选时，在人明确采用后沿用现有交接工具的准确预览／确认规则，只改相关主题引用并保留历史；其他 selected 和人工内容保留。不增加更新、迁移、候选、交付或审批字段。
+
+已选来源不可读或版本含糊时，展示缺项、影响和可选操作，不静默改读全局／另一路径或最高版本。原采用路径若直接指向已被升级替换的安装文件、旧版已不可读，就不能声称“仍使用旧版”；由人选择采用当前真实版本，或从实际可读历史恢复项目副本，不伪造旧内容。
+
+安装目录和项目采用副本分开。曾直接修改安装文件时，先识别并另存为项目资料，再处理升级。本规则保护采用作业中的项目自改内容，不证明原安装器已保护所有安装目录修改；安装／分发行为另按实际合同验证。
+
+### 6.5 需要物理迁移时交给原 Plan／Build
+
+规范更新默认不移动代码。只有真实工程、维护、构建或部署需求才提出迁移，不能仅因旧路径与示例不同就改名。目录迁移方案复用已有规格／工程说明与原 Plan，不另建迁移登记库。
+
+迁移任务须明确旧路径→新路径、实际涉及文件、共同消费者、导入引用、源码／测试／资源及构建／运行／CI／部署配置、人工与未提交内容保护、验证方法和失败恢复范围。企业项目按所选 AD 衔接；标准项目用本次规格承接。未知影响不能填为已核对。
+
+原 Plan 实际读取后，将文件路径、依赖、验收和恢复写进 tasks/plan.md 与原方法确定的唯一任务目标，保留计划认可停点。获准原 Build 回读任务所需来源，只处理明确清单，核实际新增／修改／必要删除文件和共享消费者；不以采用规范为由整仓复制、整目录覆盖或递归删除。
+
+完成本次要求的程序测试、构建和消费者回归，按 §5 核真实落点。只检查过 CI／部署配置而未实际运行时分别说明，不能报为运行通过。迁移完成不清除旧完成任务，以新任务记录本次变化；撤销未实施需求不自动删工程，功能退役另有明确移除／迁移／回归任务。
+
+恢复复用项目已有 Git／备份和明确文件范围，保留本地及其他人的修改，不执行整仓 reset 或覆盖人工内容来还原。计划认可、单任务实施、目录验收、业务审查和发布按各自原条件执行，不由 JSON 或目录存在推导。
+
+### 6.6 可复制的任务说明
+
+以下是自然语言任务或原命令的任务上下文，不是新参数。已采用指引能准确定位时先按指引查找并展示来源，只向用户补问缺少的选择或事实。
+
+```text
+先只读检查当前项目已采用的工程说明、当前规格、相关代码／构建配置和未完计划。
+按现状列出工程类别、真实根、源码／测试位置、维护方与必要例外。
+优先保留已有目录和人工内容，不生成目录、不搬代码、不改业务稿或 JSON。
+给出映射建议、准确缺项、推荐和可选操作，交我决定。
+```
+
+```text
+比较项目当前采用说明与本次明确的新目录资源；先展示实际路径和正文版本。
+按项目已采用指引查找，不能准确定位的来源再向我确认，不自动选最高版本。
+列出条款差异及对当前规格／未完任务的影响，保留人工约定。
+我尚未选择时只给建议；我明确选择后仅更新获准条款并展示差量、保留原文件历史。
+未采用的条款不写回，目录不迁移，业务稿和代码不自动修改。
+```
+
+```text
+/i3-plan
+依据当前明确采用的工程说明和本次规格，规划已明确的目录调整：
+旧位置：[路径] → 新位置：[路径]；范围：[文件／模块]。
+先实际读取所选来源、代码、引用和相关配置；按需读直接消费者。
+每项任务写明文件路径、人工内容保护、测试／构建和失败恢复方法。
+保留原计划／唯一任务目标和已完成事实；本轮只规划，等待原有认可后再 Build。
+```
+
+获准后使用原 /i3-build 执行当前明确任务，要求回读采用依据、核实际文件与配置落点，并如实列出验证和未通过项。原 /i3-build auto 的原有条件保持，不把上述迁移任务扩展为企业跨阶段调度。
+
+本节提供作业规则，不能代替真实调用／读取、任务认可、文件保护和迁移结果的证据；没有运行的步骤保留待验证，原始失败和人工处理意见不转写为通过。

package/references/engineering-skeleton-resources/catalog.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "resourceVersion": "1.0.0",
+  "kind": "directory-standard",
+  "standard": "directory-standard.md",
+  "adoption": "adoption.md",
+  "layouts": [
+    {
+      "id": "pbc-composite",
+      "description": "PBC组合工程，按需映射前端、后端、Agent和任务工程"
+    },
+    {
+      "id": "agent-standalone",
+      "description": "独立Agent工程，允许采用框架原有的根目录布局"
+    }
+  ]
+}

package/references/engineering-skeleton-resources/directory-standard.md

@@ -0,0 +1,119 @@
+# 工程目录规范
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+内容版本：1.0.0。适用范围：明确采用本规范的业务工程。目标是让 AD 约定的工程与模块位置，继续落实到原 Plan 的文件范围和原 Build 的真实产物。
+
+## 1. 基本规则
+
+- 先确定实际业务项目根。工程相对路径均从该根解析；安装的 Skill／资源目录及 i3 维护工作树不是业务输出根。
+- 规范约定外层职责；工程内部遵循项目已采用的语言／框架惯例，具体位置由 AD 和真实配置明确。
+- 只采用当前需要的工程类别；实际有内容时再建目录。空目录不等于已交付工程，Git 也不保存空目录。需要先说明预留位置时可写有意义的 README，无需到处添加占位文件。
+- 新建工程标识使用稳定、可区分的小写短横线名称，例如 admin-web、business-api。语言内部包名／模块名遵循其自身规则；现有项目保留原名并建立映射。
+- 工程标识与 PRD 主题、版本分开。同一工程可承接多主题；新增或修订 PRD 不自动复制工程。同一路径不得指向两个不同工程身份。
+- 目录不是进程、服务、仓库或部署边界。AD 明确源码工程、业务模块、运行应用和部署单元之间的实际关系。
+
+## 2. PBC 组合工程：pbc-composite
+
+以下是逻辑位置，按实际选择形成，不要求一次创建全部目录：
+
+```text
+project/
+├── README.md                     工程入口、工程清单与真实命令
+├── spec/{能力}/                  当前业务文档及版本历史
+├── tasks/
+│   ├── plan.md                   原 Plan 的默认计划
+│   └── todo.md                   仅在采用默认文件任务目标时维护
+├── docs/engineering/             按需：项目规范／采用说明
+├── frontend/<engineering-id>/    按需：前端源码工程
+├── backend/<engineering-id>/     按需：业务后端源码工程
+├── agents/<engineering-id>/      按需：本项目内 Agent 源码工程
+├── jobs/<engineering-id>/        按需：任务源码工程
+├── contracts/                    按需：受控接口与事件定义
+│   ├── exports/                  对外提供的契约
+│   ├── imports/                  明确采用的外部契约
+│   ├── internal/                 本项目工程间契约
+│   └── events/                   事件契约
+├── shared/                       按需：明确复用和维护边界的代码
+├── tests/cross-engine/           按需：跨工程验证
+└── delivery/                     按需：运行装配与部署资料
+    ├── local/                    本地依赖与联调配置
+    ├── dapr/                     仅在明确采用 Dapr 时使用
+    └── deploy/                   目标环境部署配置
+```
+
+使用现有 SOP JSON 时沿用其已采用位置；不要求为了目录规范再创建 .i3/project.yaml、templates.lock、contracts.lock 或生成记录库。已有项目或工具确有这些文件时按其真实用途保留。
+
+spec/ 下按业务能力组织文档。一个 EBC 的 BRD 识别相关 PBC；同一 PBC 的多个需求主题各有独立 PRD 版本及准确对应的 AD／TestCase，配套版本号可以不同。既有已采用文档目录不因本规范迁移。
+
+## 3. 独立 Agent：agent-standalone
+
+单一 Agent 应用可以把所选框架的源码与构建配置直接放在项目根下，避免无意义的 agents/<id> 包裹。按实际能力组织，不强制以下所有内容存在：
+
+```text
+agent-project/
+├── README.md
+├── spec/{能力}/
+├── tasks/                       原 Plan 和唯一任务目标
+├── docs/engineering/            按需：规范采用与工程说明
+├── <框架构建／配置入口>
+├── <源码根>/                    AD 确定的本应用源码
+├── <程序测试位置>/              采用框架的原有测试位置
+├── evals/                       按需：Agent 行为样例及评价
+├── contracts/                   按需：实际提供／消费契约
+└── delivery/                    按需：运行装配／部署
+```
+
+采用说明把主 Agent 工程映射到项目根“.”。日后确需组合多个可独立构建工程时，按 AD 明确新增位置，不能因为模板示例存在 agents/ 就把当前代码自动搬进去。
+
+此处 Agent 是业务工程；3.1.0 规划的企业研发调度 Agent 是另一项产品能力。外部 Agent 服务只引用正式契约和消费者适配，不把其源码和内部 AD 复制到本项目。
+
+## 4. 四类工程与配套目录职责
+
+| 类别或目录 | 应承接内容 | AD 需明确的实际位置与责任 |
+| --- | --- | --- |
+| frontend | 页面、路由、交互状态、客户端接口适配及适用 UI 测试 | 工程根、源码／页面模块、配置、测试、资源和构建产物；响应式／可访问性要求；业务授权仍由服务端落实 |
+| backend | 正式业务规则、授权、状态、数据及外部适配 | 工程根、包／模块、接口、配置、迁移与测试；数据 owner、事务、失败恢复及真实命令 |
+| agents | Agent 职责、模型调用、授权工具与必要运行记录 | 工程根、源码、工具、提示／配置、程序测试与行为评价；不得把分析建议冒充正式业务状态 |
+| jobs | 定时、异步、批处理等任务逻辑及必要执行记录 | 工程或模块位置、触发入口、调度配置、幂等、失败／重试与恢复；是否独立运行由 AD 决定 |
+| contracts | API、事件及必要共享数据协议 | 提供／消费方、正式来源／版本、维护位置；事件的归属位置只保留一处权威，不因分类重复拷贝 |
+| shared | 有真实复用者的共用实现 | 唯一维护方、消费者、依赖方向；不把业务归属不清的代码全放 shared |
+| tests/cross-engine | 多工程联调、共享契约及回归验证 | 需求／AC 来源、测试入口、数据、环境和结果位置；单工程测试仍跟随该工程惯例 |
+| delivery | 本地连接、运行装配及部署描述 | 运行身份、依赖、环境及部署单元映射；不保存真实密钥，目录存在不等于已部署 |
+
+jobs 可以是已有后端工程里的模块；Agent 也可以是已有工程中的组件。此时在 AD 映射真实子路径，不为凑四类顶层目录制造第二个工程。
+
+## 5. 工程内部目录与实际产物
+
+本规范不强制所有语言使用同一份 src/modules 布局。例如采用 Java 常规布局时，源码和测试可在 backend/business-api/src/main/java 与 src/test/java；采用前端框架时，其源文件可在 frontend/admin-web/src。准确目录、包名、扩展名和命令来自已采用技术规约、AD 和实际构建配置，这些例子不是技术选型。
+
+AD 至少映射本次需要的源码／业务模块、配置、测试、契约、迁移及运行装配位置；不适用项有依据说明。Plan 进一步列出每项任务预计新增／修改的文件及路径。Build 按获准任务生成有实际内容的文件，未选择工程不预建空架子。
+
+编译、打包、依赖和缓存产物遵循真实工具配置，例如 dist、target 等；在采用说明中必要时说明输出及忽略规则。不能把构建输出位置的差异等同于业务源码越界，也不通过移动编译产物掩盖源码位置错误。
+
+项目根可按工具实际需要保留构建配置、workspace／CI 等公共文件，路径在 AD 或计划中说明。不要为满足外层分类，把框架入口强行放到无法正常工作的目录。
+
+## 6. AD、原 Plan、原 Build 的约束链
+
+| 环节 | 必须明确的内容 | 如何核对 |
+| --- | --- | --- |
+| 采用说明／AD | 规范版本、项目根、所选组织方式、工程与模块映射、共享责任和例外 | 读真实来源与当前代码，区分已有、拟建及未定事项 |
+| 原 Plan | 当前 AD／采用说明引用；每项任务文件路径、依赖、验收与验证方法 | 任务可以落到真实或拟建位置，共享文件不安排互相覆盖的独立写入 |
+| 获准原 Build／Build auto | 实际回读任务所需来源，按映射生成／修改源码、配置、测试 | 对照任务和实际变更文件核落点，再完成原有测试／构建与任务处理 |
+| 原测试／Review／Ship | 实际代码、结果与本次范围 | 目录检查只是适用验收之一，不取代功能正确性、独立代码审查或发布条件 |
+
+原能力不会因为目录规范文件存在就自动消费它。显式任务或已采用项目指引负责把路径交进去；原版 Skill、命令、默认 Plan 和任务权威保持。具体可复制说明及核对步骤见 [采用与交接](adoption.md)。
+
+## 7. 存量工程、人工修改与变更
+
+已有 web、services、server 等工程组织先按现状映射到逻辑职责，不要求立即重命名。例外要写清实际路径、原因和适用范围；不能一边把旧结构认定有效，一边在新规范目录里生成第二套同名源码。
+
+新增需求优先落到原工程的相应模块。撤销未实施需求不自动删除工程或契约；功能退役通过明确的移除、迁移和回归任务处理，保留已完成历史及其他主题的共享依赖。目录规范变更不自动扩大已有任务授权。
+
+采用后的项目副本、人工源码与原始失败记录保留。升级资源不覆盖项目自改内容；实际迁移先评估导入、构建、测试、CI／部署和消费者影响，不用重建目录宣布迁移完成。

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

@@ -0,0 +1,165 @@
+# 企业 SOP 四阶段资料入口
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+资源组合版本：0.16.2；指引版本：v0.16.2。本组合增加显式plan与四阶段短命令澄清，源码／分发／真实宿主验证分别记录，暂不发布。业务JSON顶层仅schemaVersion、scope、selected，候选登记及撤回流程已退出；原版25技能／9命令及既有原型能力保持，本地SOP增量与3.0目标仍27／11／4。S08按精简范围关闭，三字段登记完整验证留S10；旧S06—S08证据只对应当时对象。企业跨阶段auto仍3.1.0。
+
+本组合增加[公共技术规约分发资料](technical-baseline/README.md)：通用模板v0.0.1与可选企业应用规约v0.0.2分别定位，规约附带其明确引用的目录规范／采用说明0.2.0。可选规约按辅助清单baselines条目定位，只有项目明确采用才生效；已有项目规范及自改副本优先。旧S10候选与报告不改，本组合打包／安装证据另取，不转算真实模型通过。
+
+文档review／recheck采用[独立只读审查合同](review-handoff.md)：外层在获准环境使用一次新的只读CodeBuddy会话，绑定准确目标、所选模板／业务来源及复查原报告和人工回应。报告保存与审查分开，业务稿不自动改写；缺隔离时整理新会话任务，不冒充独立审查，不新增业务JSON字段。
+
+原生方法的调用／报告复核与S06路径辅助校验分开，按[外层校验说明](verification/README.md#原生方法与执行报告)显式使用；门禁对象和时点见[交接合同§11](handoff-contract.md#11-门禁对象时点和允许范围)。外层检查不自动改业务稿，不生成批准或启用企业流程。
+
+需要程序约束现稿交接时显式采用[单次受控入口](controlled-handoff.md)：先限制 CodeBuddy 只读，再核真实回执，最后仅登记用户明确采用的准确路径并回读。该入口与事后证据校验分开，不是随安装启用的通用拦截器，不代替原生方法、人审或企业auto。
+
+同主题已有选择需要替换时采用[改选预览合同](selection-handoff.md)：先核准确组合、上游原文证据与当前 Plan 影响，再经该次明确选择受限更新；新稿生成不自动选用。旧稿、其他主题、公共技术来源、工程骨架与 Plan／任务保持，新的规划输入由用户显式调用/i3-sop plan组织并复用原规划；原/i3-plan加明确任务的手动方式仍可用。
+
+本次输出目标已有稿件、中断、待补登记、重复执行及人工修改按[最小恢复规则](recovery-contract.md)处理；已有上游输入不把新目标误判为恢复。先核现稿，不重复生成解决清单问题；恢复状态及失败留在会话／外层证据中，不增加业务JSON状态字段。status与恢复保持根README、索引和三份共用合同的完整读取，安装身份按必要元数据核实。
+
+## 1. 先确定本次流程
+
+本轮明确标准流程时使用原方法，不读取或采用企业模板、提示词、清单和企业目录。只有本轮明确企业 SOP，或用户明确且适用于本任务的选择记录，才加载企业资料。安装、项目指引存在、发现 handoff.json 或出现 PRD 一词都不构成选择。资料不授予操作、写入或发布权限；当次任务不自动变成项目永久采用。
+
+CodeBuddy 可明确说：“为当前项目启用 i3 企业 SOP 资料指引，保留已有项目说明，不更改全局配置。”接入先实际读 CODEBUDDY.md，只追加[项目片段](codebuddy-project-guide.md)的完整有界标记，保留已有内容。同名片段复用，自改片段不自动替换；标记不完整、符号链接或归属不清时停止改写。更新先说明差异，按宿主要求新会话验证真实加载，不改全局规则。文件存在不证明宿主加载；其他宿主另取证。
+
+## 2. 分开定位三种来源
+
+| 来源 | 查找与采用规则 |
+| --- | --- |
+| 模板、作业提示词和资源合同 | 本轮明确指定的对应资源→项目明确采用副本→同宿主项目安装→同宿主可读全局安装；只向下查尚未选定的角色，不用低优先级源替换失效的已选源 |
+| 真实业务、公共规范、契约、骨架 | 先读项目根 README、适用项目规则、其引用的采用记录和 docs/README；以实际选择、适用范围及真实正文为准，不把资源模板当项目规范或可运行工程 |
+| 本次交接对象 | 已明确的唯一 JSON 清单或手动指定路径；只取本次主题的已选材料，候选、历史、样例和验证记录不作默认输入 |
+
+CodeBuddy 项目安装入口为 .codebuddy/.i3-composer-agent.json：确认 name 为 i3-composer-agent，按 resources.references 定位 enterprise-sop-resources/README.md，资源路径相对安装清单所在目录。安装识别只读name／version／scope／resources等必要元数据，可先定位键再读相应范围，不全文加载assets文件列表；项目确实未安装时才查同宿主可读全局清单；清单存在却损坏、名称不符、引用失效或被拒绝读取，不当成“未安装”静默兜底。已选项目副本时，安装清单只作安装事实，不能接管采用。
+
+查找顺序也约束实际读取：先读项目根约定及其采用记录，确定对应角色尚无明确来源时，才访问下一优先级。已选定项目资料根时，不再读取低优先级的安装／全局资源README、索引或正文，除非本轮明确要求比较来源；不并行探读多套入口再事后宣称只采用其中一套。安装清单若先前已读，只保留安装事实，不顺势进入其资源。
+
+不全盘搜索、跨项目或跨宿主借安装；全局可读时不重复要求项目安装。history、验证目录、备份和样例只在本次明确指定用途时读取。目录列表、索引、聊天摘要和自动上下文只是线索，必须实际读选定根 README、索引、采用记录及本次所需正文。
+
+本轮只指定一个模板时，只覆盖该角色。提示词及共用规则先沿项目采用组合；尚未选定才按上述顺序提议固定来源，说明兼容范围。冲突不得靠“本轮优先”取消既有规范、权限或质量要求；明确本次覆盖范围后执行，持久修改采用须另有相应意图。无需因已明确选择重复提问。
+
+## 3. 按索引读完整资源
+
+review／recheck 的读取职责以[统一审查约定](review-handoff.md)为准：外层解析索引／清单／依赖并保留变化检查，模型完整读阶段README、模板、唯一动作、业务及实际约束。只对已固定覆盖组合精简；项目自改或未知规则继续完整读选定原件。以下生成／修订、status、交接与恢复读取规则保持；审查不再一律重复加载纯元数据和整套校验说明。
+
+先实际读[阶段索引](stages.json)和其中三份共用合同：[模板合同](template-contracts.md)、[交接合同](handoff-contract.md)、[生命周期合同](lifecycle-contract.md)。再按本次阶段／动作读本阶段README、manifest、完整模板和唯一对应generate、review、revise或recheck提示词；不是一次读取四份动作提示词或全部模板。
+
+本次读取清单由已读索引、局部manifest及直接任务确定：先列实际路径和用途，再逐项成功回读；未读／失败／部分读不能记“已读”。按以下检查收尾，不为了少读省掉必要依赖，也不为“完整”探读未选根。
+
+| 必读对象 | 本次适用范围 |
+| --- | --- |
+| 项目规则与采用依据 | 本项目CODEBUDDY、根README、实际引用的采用与docs约定，先于安装资源 |
+| 当前资源根与共用合同 | 选定根README、stages及三份共用合同；manifest内dependencies的适用正文也实际读 |
+| 阶段资料 | 本阶段README、manifest、完整模板、本次唯一动作提示词；索引／manifest可被项目改路径，不能按默认名猜 |
+| 公共技术规约辅助资料 | 本次要求辅助准备／模板缺口核对时：按auxiliaryResources读其manifest，再读manifest指定entry和template；三者缺一不能声称完整辅助读取 |
+| 业务与必要依赖 | 只取本次所选正文及必要直接／传递约束；骨架采用说明指向真实来源README／源码时，实际读该来源，说明完备或缺口 |
+| 已选缺项 | 读取到具体缺项后准确报告文件／目录区别及影响；不再加载其他动作或低优先级源兜底，独立工作只建议不执行 |
+
+结束前对照这份本次清单，报告已成功读取、仍缺／失败、未要求的资料和具体依赖影响。不要用搜索结果、索引列名、行数或作者摘要替代正文；长文按实际工具截断分段覆盖。维护来源、旧证据和模板中的示例链接不自动成为业务必读。本组合提供[外层只读校验](verification/README.md)，由获准调用者对照本次适用清单和CodeBuddy原生轨迹执行；单独加载资料不会自动启用校验，也不拦截工具调用。文件存在、读取覆盖和语义正确分别判断。
+
+| 路径类别 | 相对基准与边界 |
+| --- | --- |
+| sharedContract、handoffContract、projectGuide、阶段／辅助资源 resourceRoot 和 manifest | 当前选定 stages.json 所在目录 |
+| 阶段模板 source.resourcePath、prompts、files | 对应阶段 manifest 所在目录；source.path 为维护来源，不作安装路径 |
+| 辅助资源 entry、template、files | 对应辅助 manifest 所在目录 |
+| dependencies.path | 声明该依赖的 manifest 所在目录，允许在选定资源根内引用共用文件 |
+| 业务 JSON 及手动交接相对路径 | 本次明确的业务项目根，详见[交接合同](handoff-contract.md)；不相对清单目录或临时 cwd |
+
+资源索引的路径经解析后须保持在选定 SOP 资源根内，含符号链接解析；越界、不可读、损坏或版本／主题矛盾时报告具体缺口和影响，不改用安装原件、全局新版或历史副本。真实业务文件不受资源根约束，明确提供的项目外来源可使用绝对路径并说明可移植性，不自行复制。
+
+| 阶段／辅助资料 | 输入、方法与边界 |
+| --- | --- |
+| brd | 业务描述、EBC、完整 BRD 模板；必须原Spec；按需澄清／文档方法，候选 PBC 不冒充获批 |
+| prd | 选定 BRD 或等效依据、PBC、主题、完整 PRD；原规格方法及适用认可／停轮保留 |
+| ad | 选定 PRD、真实规范／工程事实、完整 AD；必须原Spec；按需文档／接口／前端方法，原型按需并行 |
+| testcase | 直接产品依据 PRD、配套 AD、测试规范、完整 TestCase；必须原Spec；仅设计，不借原 /i3-test 生成文档或冒充执行 |
+| technical-baseline（辅助） | AD 准备时按需定位；优先复用项目已有规范。只有缺少适用规范且本次明确选择才起草最小候选；不是第五阶段 |
+
+公共技术规约的[采用说明](technical-baseline/README.md)和模板用于核对来源与缺口。现有规范已充分时直接引用，不复制总规约、不修改原规范。技术栈与工程骨架是项目实际选择；模板不预设答案，选型、候选、采用、应用、验证分别表达。
+
+四阶段固定组合：BRD 0.2.3／模板 v0.0.3，PRD、AD各0.3.3／模板v0.0.4，TestCase 0.3.4／模板v0.0.4；公共技术规约辅助资源 0.1.2／模板 v0.0.1。四阶段模板正文原字节保留，B05仅增补说明和动作提示词，PRD 子包“未提供其他模板”仅描述该子目录；其中 AD 责任说明不是完整 AD。采用旧切片缺资料时报告差异，不默认混版。
+
+## 4. 保护项目采用与人工修改
+
+使用本次已选根及实际本地内容，记录发行来源、项目差异与适用范围。发行 manifest 的 sourceSha256／sha256 描述源码／品牌分发原件，不是要求项目副本永久不变的锁；本地修改可在现有采用说明中说明。未计算摘要如实写，不填假 SHA，不因内容已变就恢复原件；版本标签与正文矛盾先核对，不能拿摘要免除实际读取。
+
+安装升级不切换项目采用，不覆盖项目副本、已生成文档或自改指引。本次只读定位也不“修复”索引／清单。更新模板或提示词先比较差异，保留项目旧稿和修改，明确目标和相应授权后才单独合并，不批量升级实例。已选源失效只限制依赖范围，可独立继续的部分仍可继续。
+
+沿用项目命名，一能力一目录。同 PBC 多主题 PRD 各自独立版本；AD／TestCase固定直接上游，不强制同号或猜最大版本。写前整理项目根、阶段／作业、业务身份、实际资源及本地差异、输入、唯一输出、假设／Q和停点，展开“占位符→字段→值→来源”，实际写入及最终回读同一路径。现稿先读，不机械升版；权限、归属或覆盖风险未清不写。
+
+## 5. 文档、JSON与手动交接
+
+文档生成后完整回读、展示路径并交审，不自动创建或更新JSON。用户明确采用后才用init／select记录所选输入，清单顶层仅schemaVersion、scope、selected；resolve只读解析。手动路径方式继续可用，候选登记及撤回不再提供。
+
+
+第一步用企业任务、模板及原方法形成规格集合；第二步将本次选定集合交原 Plan，再按获准任务 Build／test／review／Ship。原方法不会天然读写 JSON，需要明确任务或适用的项目指引实际组织来源；S11另验证接点。Plan 保留 tasks/plan.md 和唯一 todo／tracker，不生成影子 SPEC 绕过原入口限制。
+
+review／recheck 只读会话标注，独立审查需真实新上下文；审查者不改文档、项目、JSON或报告，获准调用者另存。人工可修改、明确委托、有据不采纳或保持 Q。原型按需并行；TestCase为Plan的可选输入，验证内容、六项要求和依赖任务执行条件仍须满足。生成文档不等于采用，选用登记不等于批准、开工或测试通过，不自动进入下一阶段。
+
+## 6. 可直接说的任务
+
+- “按企业SOP，查找本项目采用资料，为巡检管理的任务编排主题生成PRD，完成后交我审阅。”
+- “按企业SOP准备本主题AD。有已采用公共规范就引用；没有则说明选已有规范或起草候选的选项，技术栈和骨架等我调整确认，不自动生成一批资料。”
+- “本次只读核对交接：读取项目选定的JSON及本主题实际来源，列缺口，不写任何文件，不生成下一阶段。”
+- “本次按路径手动传递所选PRD、AD、已有规范和骨架说明，不创建JSON；核对后只规划供我审阅，已有TestCase则引用，没有则按依赖安排补齐。”
+- “本次使用标准流程，生成原标准规格，不采用企业SOP。”
+
+以上为自然语言任务，不是已实现的新 slash 或业务 CLI。资源合同、源码分发闭包、安装、宿主加载、模型实际读取、内容质量、工程执行、人工验收和发布分别取证。
+
+## 7. 新增、修改、撤销和功能退役
+
+按[生命周期合同](lifecycle-contract.md)先核意图与候选／目标／已实现事实，选本次阶段及唯一目标。新增主题独立版本，修改保留完整目标，取消不标任务完成，已完成任务和历史报告保留；已实现功能通过新退役设计与获准工程任务移除。资料作业不顺带改Plan、任务、代码、生产或其他主题，JSON改为明确选用登记，本修订未测试；既有改选保护保留，撤销／退役引用差量及完整组合恢复仍按计划范围，本片最小恢复见上文；真实原Plan与Build交接留S11。
+
+可以说“按企业SOP，修订本主题的完整PRD，说明新增／修改／保留／撤销及配套影响，只写本次候选交我审阅”；或“只读分析撤销某FR／功能退役，核文档、JSON、任务和消费者，零项目写入”。不新增变更子命令，不因资源升级改变标准流程或项目永久选择。
+
+B05-r2收尾澄清：最后一次Write／Edit后分段完整读取最终稿；全文回读后再Edit也须再次完整覆盖，不以局部回读冒充最终全文核对。必要输入缺读先明确缺口，补读不追认为过去已读。本修订不新增读取守卫或扩大辅助资料的按需适用范围。
+
+## B05收口：适用性与外层证据
+
+先按本次目标确定必要输入，不把所有工程文件、辅助模板或Plan／todo都设为所有阶段前置；涉及已有任务、影响或不存在断言时，回读对应实际来源或明确未核。候选列表和现稿中自称的比较材料只是线索，只有本次明确指定的比较范围才读取未选版本。不得用现稿元数据自行扩大本轮任务。
+
+“未读取／部分读取”“读取失败”“已验证路径缺失”“不在本次选定集合”“内容尚未核实”分别陈述。无消费者、无需迁移、不受影响及全历史不存在等结论给出实际已核范围；没有证据时保留Q，不从未读推出否定。模板章节与业务现稿章节分开引用，Glob无匹配不证明目录存在且为空。
+
+外层校验按实际返回行核必要输入全文、唯一目标末次编辑后全文回读、未选／越界读取及只读边界。审查者每条发现和已核事实附所指文件的短原文摘录；摘录匹配及读取通过仍不代替理由和反例的人工核验。校验失败保留稿件与局部意见，明确受限范围，不声称完整交接，不自动修稿或推进。新入口、JSON登记及原Plan／Build消费仍留后续。
+
+## 审查输出契约与定向复核
+
+资源组合0.5.2补齐[审查会话契约](verification/review-output.schema.json)、外层错误分类与调用者来源角色绑定，详见[说明](verification/README.md)。原生失败不改写；定向格式／来源复核不自动改业务稿，达到当次约定轮次仍失败交人工裁定。该工具仍由外层明确执行，不自动加载／拦截原方法。
+
+## 来源角色同源生成增量
+
+当前组合0.5.3采用[共用生成与校验工具](verification/README.md)：同一scope角色表为模型生成role枚举，并在实际CLI参数核对；授权校订报告独立检查内容，不追认为原生通过。仅自有辅助变化，四阶段及辅助模板正文、原版技能和命令保持。新独立验证一次，失败交人工裁定，不发布。
+
+## S06最小交接切片
+
+本次资料根采用 `references/enterprise-sop-resources`，避免新增同名Skill时品牌引用重写误改资料路径。源码工作区保留旧目录兼容链接；该链接不作为分发依赖。项目已采用副本仍按真实采用记录读取，不改其位置或正文。
+
+[handoff.py](handoff.py)提供三字段清单创建、明确初次选用和只读解析，接口及限制见[交接合同§8](handoff-contract.md#8-s06最小辅助与边界)。手动路径方式不要求使用工具或创建JSON。共享JSON只存路径，不保存批准、完成率或运行结果。脚本读取不代替模型全文回读与语义核对。
+
+本片不含命令接入、既有选择替换、完整修订恢复、独立审查调度、Plan／Build自动消费或工程生成；对应S07—S11及I4／I5继续保留。模板正文和业务稿不变，先交人工审阅，暂不发布。
+
+## 7. spec/ 业务目录与原生命令
+
+新项目的BRD、同PBC多主题PRD、各自AD与TestCase默认写入spec/{能力}/，命名沿共用合同；现有项目约定优先，不搬旧稿／历史。这里的spec/是业务输出，references/enterprise-sop-resources是安装资料，两者不混用。起草／修订必先成功调用原Spec Skill，使用其外部格式与存储能力；原/i3-spec包装及using不变。
+
+原Plan使用本次AD与其明确引用的产品／工程集合承接六项，原Build按获准任务继续；原Build auto保持其规格、Git、完整计划认可及逐任务测试／构建／提交停点。具体输入示例和上下文范围见[交接合同§10](handoff-contract.md#10-从选定-ad-到原-planbuild-的输入合同)。JSON不天然触发或被原命令读写，手动准确路径继续支持。只有当前主题和必要共享约束进入上下文，摘要不能替代真实正文。
+
+/i3-sop无参数只读引导；brd／prd／ad／testcase为单阶段文档任务，plan为一次原规划交接，review／status只读；未知动作及auto不写入、不猜阶段。直接Skill和命令规则相同。工程骨架由AD选择、Plan排任务、获准Build应用验证；本资料不提供可运行骨架生成器，I4／I5仍需真实工程验证。
+
+## 8. 短命令与原规划交接
+
+可以直接使用/i3-sop brd、prd、ad、testcase或plan；明确调用本Skill并给同一动作也适用。不新增必填参数或路径。先定位已有项目材料，只问本次缺少的业务事实／对象选择；唯一且充分就继续，不重复确认。结构化问答取决于宿主实际可用工具，否则会话提问并等待；取消／无答复不写占位文件。
+
+四阶段写作仍须成功调用原Spec并守内容与停轮；plan按[规划交接](plan-handoff.md)只读解析本主题清单或手动材料，完整读准确PRD／AD、已采用规范／必要契约、工程采用与相关代码，实际加载原规划Skill并履行原Plan命令义务。保存原tasks/plan.md与唯一任务目标，回读交审后停轮，不写业务稿／JSON、不自动Build。无清单可手动，标准原/i3-plan不强制读handoff；27技能／11命令不变。
+
+本次不改审查辅助、审查提示词／Schema、四阶段模板或实际技术规约。共享说明更新后若不匹配审查辅助的固定资料指纹，沿用其现有完整读取所选原件的回退，不放宽判据或冒用旧S10证据。
+
+## 11. SOP Plan读取与身份停点
+
+JSON与手动输入共用[规划交接](plan-handoff.md)的首批完整读取及原方法检查点，手动不省略共用规则。文件名清单统一登记于stages.json的planHandoff.requiredResourceReads；辅助解析不代替模型阅读全文。AD能力／主题身份或直接上游路径／PRD版本矛盾时先停，不加载原规划、不写plan／todo或候选计划。PRD与AD独立版本不必同号，未知非阻断Q与身份冲突分开处理；不改业务稿、JSON或原版能力。

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

@@ -0,0 +1,70 @@
+# 企业 SOP · AD 阶段资源
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+当前子包版本：0.3.3；模板内容版本沿本阶段manifest，正文不改。下文B05等旧版本文字保留为历史说明。
+
+审查加载分支：review／recheck完整读取本README、完整模板、唯一动作、实际业务与采用约束，依[统一审查约定](../review-handoff.md)由外层解析元数据并保留变化核对。下文涉及整套共用文件的加载要求在这两个动作按该分支理解；未知自改组合完整读选定原件，其余作业及实质条款保持。
+
+前版子包版本：0.3.2；模板内容版本：v0.0.4。状态：本地候选，尚未发布。完整[模板](templates/AD.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-documentation-and-adrs，按需API／前端等方法；实际原生调用和读取分别取证。
+
+## 1. 本阶段输入与内容
+
+
+- 固定本次PRD身份／版本、有效需求／AC和共享权威；只配套选定主题，不猜另一主题最新稿。产品预期由PRD维护，设计推导标候选。
+- 必须有整体技术架构图、功能架构图、ER图和正文详设；核ER基数、主外键／即时约束、事务次序／锁、状态归属、并发／幂等、重试／结果未知／恢复。三图不证明代码已实现。
+- 逐需求落实UI／字段／API／服务／数据库、错误／副作用、权限／数据范围、索引／迁移／回退；共享状态和契约单一权威，跨主题原子边界准确，外部服务未验证如实写。
+- 原型按需，可与AD并行，无原型不统一阻断；已采用原型核版本／范围／必要认可，未定交互只限制依赖部分，不修改原型登记假装关联。
+- SPEC六项保留完整命令／参数／cwd／环境、项目结构、真实代码风格示例、测试策略固定引用和Always／Ask first／Never。AD选骨架、原Plan排任务、获准Build才实际应用；目录图不冒充工程已生成。
+
+
+## 2. 来源与项目采用
+
+模板继承完整设计v0.0.2及原AD资源v0.0.3，B02按已确认方案补规范采用、提供／消费、数据责任、兼容组合、骨架与影响表，三图和全部详设责任保留。维护来源／真实摘要在清单derivedFrom中标included:false，不要求业务用户读取开发目录。
+
+sourceSha256为源码字节，sha256为既有品牌流程分发字节，清单不算自身哈希。项目副本先检查目标和人工修改；明确采用的自改副本优先，当前local hash与发行来源分开，不强制恢复原件。模板版本、项目修订与业务版本分开，不猜最新或机械升版。
+
+## 3. 写入、人工修改与退出
+
+模型从已读项目约定整理准确输入／模板／唯一目标及缺口，用户不必填每个路径。目标已存在先读和保留旧稿，不覆盖未读人工内容；仅授权目标可写。最后编辑后回读，新增规范要求逐条回源，权限／状态一致，逐表核列数和列义。
+
+review／recheck在独立新上下文只读会话输出，审查者零项目写入，报告由获准调用者另存。人可自行修改、明确委托、有据不采纳或保持Q，修订不代答业务决定。
+
+候选完成汇报实际来源／目标、假设／Q、自查和未执行事项后交人工审阅并停轮，不自动其他文档、Plan、Build、测试执行、提交或发布。模板／包／安装／宿主读取／模型行为／业务人审分别记录，本文不宣称完整3.0或所有宿主通过。
+
+
+## 4. B02衔接与阅读顺序
+
+| 位置 | 本次明确的内容 |
+| --- | --- |
+| AD §0.3 | 已有规范优先；真实路径、文内版本、适用条款、落实与例外；选择不等于批准 |
+| AD §2.3 | 提供／消费AD、规范与契约、代码／环境及并存迁移组合；未验证保留未知 |
+| AD §5.2、§6.2.1、§8 | 共享契约及数据单一权威，受控写入、快照和业务／Agent／jobs状态责任 |
+| AD §9.6 | 真实骨架／源码、适用工程和恢复；AD选型→原Plan任务→获准Build实际应用 |
+| AD §10.1 | 公共变化的直接与必要传递影响，旧组合、回归、例外及不受影响范围 |
+
+先读本次选定根的README、stages.json、AD清单、完整模板和本次提示词；项目自改根的索引不能由安装根代替。再读准确PRD、实际公共规范／CONSTRAINTS／ADR、契约及必要关联AD章节、骨架采用说明及其真实模板／源码。以准确章节控制上下文，不能只读作者摘要；不要求将无关主题全文装入会话。
+
+公共规范缺失时说明已查范围，允许用户选择已有规范或单独授权最小候选；只有AD写入权限时保留Q，不另写规范。共享定义优先引用项目实际来源，不依赖本包必须提供公共规范，也不强制从B01模板再生成一份。项目已采用的技术栈和骨架允许人工调整，按影响记录真实决定，不以模板示例替代。
+
+基础交接按路径回读，不强制摘要；发行清单摘要用于分发完整性，不用于恢复或覆盖项目自改副本。四种作业共用上述内容核对，但审查／复查始终零项目写入，修订只改明确目标；不自动修改规范、契约、其他主题、清单或任务状态。
+
+本地组合只同步本AD子包版本及清单引用，既有BRD／PRD／TestCase和B01资源保持。该句为B02时点记录；B03／B04及B05资源已有后续增量，JSON接点和完整跨层验证仍在后续；本次不新增依赖、Skill、命令或工程生成器，不证明/i3-sop已经可用。
+
+## B05 变更交接规则
+
+B05当时资源子包0.3.0；本次增量见收口说明，模板正文和版本保持。按[入口](../README.md)§3列本次必要读取，实际读三份共用合同及本次唯一动作；[生命周期合同](../lifecycle-contract.md)统一新增、修改、撤销和退役，不新增命令、JSON程序或工程执行器。
+
+完整三图和详设继续保留；核所选PRD、公共规约、共享契约／数据owner、必要消费者、实际骨架、移除／兼容／迁移／恢复和工程任务影响。原方法停点、只读审查与人工空间、候选／选择／Plan边界保留，项目副本升级不覆盖人工内容。
+
+## B05收口资源增量
+
+B05当时子包0.3.1，模板正文及版本不改。统一修订全文回读措辞、适用来源和单项目审查证据；外层校验见[说明](../verification/README.md)。不把辅助资料／Plan统一变前置，不自动改业务稿、JSON、任务或原版方法。旧验证与历史版本按当时对象保留。