@givolt/i3-composer-agent 2.3.7 → 3.1.0

package/skills/i3-enterprise-sop/references/engineering-skeleton/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/skills/i3-enterprise-sop/references/engineering-skeleton/readme.md

@@ -0,0 +1,52 @@
+# 工程骨架资源入口
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+资源内容版本：1.0.0。定位：语言无关的工程目录规范。AD 确定工程与模块的落点，原 Plan 把路径写入任务，获准的原 Build 在这些位置实现，再核对实际文件。目录规范不要求先取得企业代码模板或选定统一技术栈。
+
+## 1. 从哪里开始
+
+1. 读 [目录规范](directory-standard.md)，按实际项目选择 PBC 组合工程或独立 Agent 组织方式；只采用需要的工程目录。
+2. 按 [采用与交接说明](adoption.md)，在项目已有工程说明或 AD 中写明采用版本、实际路径和必要例外。
+3. 把明确采用的 AD、公共技术规约及该说明交给原 Plan；计划经所需审阅后，由原 Build 或原 Build auto 按原有条件执行。
+4. 按采用说明核对新增、修改文件的真实落点；构建、测试和业务验证仍执行各自原有要求。
+
+现有项目规范优先，已有代码不为套目录批量迁移。安装资源、目录存在或 JSON 引用本身都不会自动启用企业 SOP，也不会使原 Plan／Build 自动读取本资源。必须在本次任务或已采用项目指引中明确引用。
+
+## 2. 本资源包含什么
+
+| 文件 | 用途 |
+| --- | --- |
+| [catalog.json](catalog.json) | 资源版本、目录规范及两类组织方式的索引 |
+| [directory-standard.md](directory-standard.md) | 目录职责、命名、工程边界、共享内容及实际落点规则 |
+| [adoption.md](adoption.md) | AD、原 Plan、原 Build 的交接，手动／JSON 引用及目录验收；§6 提供存量映射、规范选择性更新、人工保护和按需迁移说明 |
+
+pbc-composite 与 agent-standalone 是目录组织方式。frontend、backend、agents、jobs 是可按需采用的工程类别；它们不表示本资源已提供或验证任何语言／框架的代码模板。
+
+公共技术规约继续使用项目已有规范或企业 SOP 已有资源，本资源不另建技术权威。UI 原型模板仍用于交互与样式设计，生产工程由实际 AD、任务和技术栈确定。
+
+## 3. 实施与采用边界
+
+本资源归属于SOP Skill的references/engineering-skeleton，与公共技术规约共用同一资料根；不新增顶级Skill或命令，不改原版技能、命令、原型或Hook。原版 25 个 Skill／9 个命令与已发布版本的既有能力保留；整合 SOP 后的目标数量仍为 27／11／4。
+
+业务 JSON 顶层仍为 schemaVersion、scope、selected。需要时沿用 selected 主题内已有 engineeringSkeleton，引用项目真实采用说明；直接给原 Plan 同一组实际路径也可。不另建 project.yaml、锁文件、任务数据库或候选登记流程。
+
+目录规范作为SOP自有分发资源；原生命令的真实读取／实施效果、发行包与宿主安装、人工验收分别验证。该资源没有提供目录生成器或代码框架模板，也不声称用提示词即可硬性拦截所有越界写入。
+
+## 4. 现有项目与规范更新从哪里开始
+
+- 已有工程先按[采用说明 §6](adoption.md)只读映射实际目录和命令，复用 web、services 或框架根布局，不为统一示例搬源码或再造同名工程。
+- 新资源只供比较。先读项目当前采用说明和本次明确的新来源，展示差异及受影响规格／任务；人可选择保留当前、部分采用或整体采用。没有明确采用就不写项目副本、JSON 或代码。
+- 明确采用后，保留项目例外、人工条款和文件历史。使用项目既有说明或规格承载结果；不另建采用状态库，目录确需迁移再交原 Plan／获准 Build。
+
+标准项目沿用自己的 SPEC 或等效规格，不因为采用目录规范就补企业 BRD／PRD／AD 或启用企业 SOP。企业项目按已选 AD／PRD 交接。手动路径继续可用；已有 JSON 只引用实际采用文件，不增加更新或迁移状态。
+
+安装文件与项目采用副本需区分：直接改过安装目录的内容先识别并保留为项目资料，不把本说明当作安装器自动保护所有人工修改的证明。已选来源不可读或旧版本已被替换时，展示准确缺项和选择，不静默换源或宣称仍在用旧版。
+
+本版补齐的是采用规则与可复制用法；实际模型读取、选择性更新、迁移、包／安装效果仍按各自证据验收，不以说明存在或版本号提高代替。

package/skills/i3-enterprise-sop/references/handoff-contract.md

@@ -0,0 +1,196 @@
+# JSON 交接与手动传递合同
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+合同版本：v0.8.2；资源组合：0.16.2。当前修订：只保留明确选用路径，新增Plan消费规则的源码／分发／真实验证分层记录，尚未发布。S06—S08旧候选相关证据保留原对象，不作为本修订验证。命令与 Skill 共用本合同，原专业方法、写权限和停轮不变。
+
+## 1. 两步交接及路径基准
+
+第一步按企业任务形成 BRD、同 PBC 多主题独立 PRD、各自 AD／TestCase 及必要辅助引用；第二步用本次实际选定集合承接 SPEC 六项，交原 Plan，再按获准任务进入原 Build／test／review／Ship。可以从已有 PRD、AD 或 Plan 接入，不补跑 BRD、不编造 EBC 或历史批准，一个主题就绪可独立交接。
+
+资源模板、提示词和共用合同属于资料根；真实规范、业务文档和工程资产属于项目选择，不能互相冒充。一份清单对应明确的业务项目根与工作范围。建议位置 .i3/sop/{实际工作范围}/handoff.json，已有位置优先；多份清单并存先确定本次对象，不按文件名、更新时间或最高版本猜选。
+
+清单内相对路径统一相对本次明确的业务项目根，不相对清单目录、资源根或临时 cwd。开始先从任务及已采用指引明确根并实际核对，迁移项目后重定根。明确提供的项目外资料可用绝对路径并在现有采用说明标来源／移植影响；不全盘查找或擅自复制。路径存在只是定位事实，还须读取正文核身份、版本、范围和直接上游。
+
+## 2. 最小字段
+
+| 字段 | 含义 | 约束 |
+| --- | --- | --- |
+| schemaVersion | 清单格式，首期值 1 | 不等于软件、模板或业务文档版本；未知格式只读报告差异，不自动迁移 |
+| scope | 实际工作范围，work 必填，已知 ebc 才写 | 结合明确的项目根定位，不推断能力登记或历史 |
+| selected | 已明确选定且实际读过的真实输入引用 | 空对象可用；选择不代表批准 |
+
+3.0 清单顶层只保留 schemaVersion、scope、selected，不生成 candidates 或 delivery，不执行候选登记或撤回。生成文档后展示实际路径，明确选用后才写 selected。原 Plan 保存 tasks/plan.md 与默认 tasks/todo.md，或在计划中说明唯一任务目标；Build 按获准任务继续，产物不重复回写 JSON。
+
+首次准备格式如下，仅表达范围，无未来路径。此示例不是本包的真实业务清单，也不由安装自动创建。
+
+```json
+{
+  "schemaVersion": 1,
+  "scope": {"work": "巡检管理任务编排"},
+  "selected": {}
+}
+```
+
+selected 可有 brd、technicalBaseline 以及 topics。每个主题按 capabilityId 和 prdId 共同区分；未知身份先核对，不补造。topics 内可有 prd、ad、testCase、engineeringSkeleton、prototype 和 contracts。单项文档引用用字符串路径，contracts用路径数组，按需存在，不预填。一个主题多个 PRD 版本为不同候选，主题身份不变；不同主题独立版本，不强制 PRD／AD／TestCase 同号。
+
+prototype、engineeringSkeleton、contracts 等配套仍按实际选用情况记录在主题中。旧清单中的 candidates、delivery 仅兼容读取，不参与当前输入选择；只读操作不改旧稿，明确选用写入时保存原始历史并移除这两个旧字段。其他未知顶层扩展不静默删除，应先说明用途或手动迁移；scope／selected 内的人工内容保留。不复制正文、任务完成率、approved、passed、审批结论或会话摘要。
+
+文档版本从选定文件名与正文回读核对，不另维护一套容易失配的版本值。TestCase为Plan可选输入：没有独立文件则省略字段；AD／已采用测试规范需承接本次验证要求，Plan可安排补齐设计。工程骨架引用真实采用说明或模板／源码，AD目录图不等于可应用资产；Build应用验证后才有真实工程根和相关锁。
+
+基础交接不强制 SHA256，同路径人工修改允许；摘要、版本和旧审阅都不能替代当前正文。工程已有契约锁、模板生成基线或不可变证据的摘要机制仍保留，不由本合同删除。
+
+## 3. 生成、登记和选择时点
+
+以下为文档审阅到明确选用的交接规则；本次源码修订未测试。同主题改选仍用[受控预览](selection-handoff.md)，手动传递保留。
+
+| 时点 | 拟实现的登记动作 | 停点与边界 |
+| --- | --- | --- |
+| 首次明确采用文档 | 明确项目根／范围和清单位置；只有本次允许写清单时才初始化并记录选定引用 | 不在生成待审稿、安装或只读任务中创建清单；选用不代替原方法认可 |
+| 从已有 PRD／AD／Plan 接入 | 回读实际材料及范围，明确采用后可登记所选输入；Plan沿用原产物约定 | 不要求先有 BRD 或补历史批准，不默认认领所有文件 |
+| 成功生成或明确委托修订 | 最后编辑后回读最终稿，展示真实路径并交审 | 不登记候选、不自动改 selected；原方法要求停轮时立即停轮 |
+| 用户明确选用某稿 | 回读对象与配套，按已明确范围更新 selected；已有选择可复用 | 留清单旧稿和业务旧稿，选择不代批准；持久选择不能由当次临时覆盖推定 |
+| 原 Plan 或后续工程产物完成 | 按原方法保存计划、唯一任务目标及实际工程／报告，不回写 delivery | 原方法不天然读写清单；后续按原产物路径和任务来源交接，保留原停点 |
+| guide／status／review／recheck 或其他只读任务 | 不创建目录、清单、报告或采用记录 | 只在会话报告，获准调用者另存，零项目写入 |
+
+文档生成／修订只写本次明确目标及必要已授权历史，交审停轮；选用登记是另项获准作业。显式plan只写原规划产物，不改业务稿或清单，不向原Skill／命令注入额外权限。AD准备优先读既有规范和实际技术栈／骨架选择；缺规范时可建议来源或最小候选，用户可手动调整，不能为填清单静默生成总规约或切换工程。
+
+## 4. 实际读取与冲突处理
+
+1. 先判断本次流程。明确标准任务不读取／使用企业清单、模板或提示词；资源存在不激活企业 SOP。
+2. 明确唯一清单、项目根和本次主题；只读本次选定材料及必要依赖。新稿不自动采用，未选版本或另一个主题不替换当前稿。读清单后必须实际读对应正文、采用依据和必要契约。
+3. 本轮明确手动路径可覆盖相同角色的当次输入，说明与现有选择的差异；不自动改 JSON／项目采用。来源间矛盾、未知格式或同主题重复选择不猜优先，报告具体范围等待明确。
+4. Plan前核本范围六项、依赖、已有未完计划及必要真实认可。Plan／任务保留实际来源、主题、需求／AC及验证依据，不只留下可变 JSON 链接。原 tasks/plan.md、唯一 todo／tracker及只规划停点保持。
+5. Build以获准 Plan任务为依据，回读关联实际设计。JSON或同路径内容已变时先核与计划差异；不能让旧任务静默按新设计施工，也不无故重置无关任务。
+6. 缺文件、不可读、主题／版本／上游矛盾或契约失效，报告准确路径、问题和依赖影响；无静默全局／历史／最新版兜底。仅限制依赖范围，可独立部分不全量阻断。实际测试、代码审查和Ship各保留原条件，GO不等于发布授权。
+
+原 /i3-spec 的默认根 SPEC.md 与原 /i3-build auto 的固定规格／Git条件仍保留；等效企业规格使用适用原方法交接，不写影子 SPEC、改原命令或使用 JSON 绕过限制。新项目的工程规格按 spec/ 组织，允许继续使用原Plan、逐任务Build及原Build auto；后者仍保留其完整规格、Git与计划认可条件。企业跨阶段auto留3.1.0，两者不混同。
+
+## 5. 修改保护及失败恢复
+
+本片可执行的最小恢复顺序、适用读集与复制提示见[恢复规则](recovery-contract.md)。复用本合同§8的init／select／resolve 三操作，不另建恢复状态库。只补登记与修订业务稿是不同任务；部分稿保留且不登记，工具失败先报告停止，后续获准作业回读后只补登记。status／恢复不调用Spec生成，但仍完成五项共用读取及实际用于定位的安装身份核对。
+
+| 情况 | 处理 |
+| --- | --- |
+| 项目自改模板／提示词／规范／同路径正文 | 读当前内容、保留修改及来源，核影响；不按发行摘要还原，不继承未核对的旧批准 |
+| 明确选用但登记失败 | 保留现有文档与旧清单，说明准确路径及失败；后续只补已明确选用的引用，不重新生成或覆盖文档 |
+| 文档失败或只有部分稿 | 不选用部分稿，不切换选择；部分稿及失败保留作业记录 |
+| 重复选用 | 相同主题与路径复用，不制造新业务版本／任务；需要清理旧字段时保留原始历史 |
+| 清单人工扩展或其他会话修改 | 保留未知字段和不属于本次的条目；写前回读，发现冲突停写，不用模板空表替换现稿 |
+| 无法保证原子并发更新 | 如实报告能力边界、保留差异与恢复依据；不能只凭提示词宣称消除并发覆盖 |
+
+清单登记与业务正文写入为可分别失败的动作，不宣称事务保证。更新前保存可回读旧稿，最后写后实际回读。未核实的外部动作不盲重试，不建设另一套审批／任务状态数据库。实际保护和恢复须在 S06／S08 验证，B04的只读定位证据不代替写入测试。
+
+## 6. 无 JSON 的手动方式
+
+没有清单也可使用原命令或适用 Skill 加明确企业任务和真实路径，不强制安装登记程序、建清单、补跑BRD或改项目指引。手动路径同样读取正文并核身份、配套与缺口；是否持久登记由实际意图决定，纯手动任务不写 JSON。
+
+```text
+本次使用企业SOP资料，按我给的实际路径手动交接，不创建JSON。
+请读取 <本次PRD>、<配套AD>、<已采用公共规范>、<骨架采用说明或真实工程模板> 及相关代码，核对本主题身份、直接上游、SPEC六项、依赖和未完计划。
+本轮只准备原Plan的输入摘要，保留实际来源及Q，交我审阅；已有TestCase就引用，没有则从AD／已采用测试规范核验证要求并安排补齐，不统一阻断规划。
+```
+
+此为准备任务；实际调用原 /i3-plan 或规划 Skill 时仍遵守其完整规则。命令／Skill共享引用含义、范围与停点，不假定所有宿主slash参数和工具一致。当前合同不证明新入口或原Plan／Build实际集成，相关验证留S10／S11。
+
+## 7. 新增、修改、撤回与退役的引用差量
+
+完整规则读[生命周期合同](lifecycle-contract.md)。schemaVersion仍1，不增加审批或任务状态。新主题／新版本保存后只展示实际路径，明确选用才更新对应selected及真实配套；未采用稿件没有JSON撤回操作。部分需求撤销保留完整主题；整个未实施主题的选择撤销另核任务与消费者，共用引用和其他主题保留。业务旧稿、选择前清单及依据留存，历史不默认采用。
+
+已实现功能的退役目标不代表生产已经切换；工程根、旧报告及已完成任务仍是历史事实。路径缺失是断引用，不推定撤销，不自动找高版本／history替换。只读影响预览不写任何项目对象。无JSON的手动交接含同样的变更意图、真实路径、旧新依据和原方法停点，不能因手动方式跳过必要正文读取或任务保护。
+
+## 8. S06最小辅助与边界
+
+工具为本资料根的[handoff.py](handoff.py)，版本v0.2.0，Python 3.9+标准库即可运行；先以`python3 <资料根>/handoff.py --help`核对接口。原版方法不导入或自动调用该工具，业务文档及原Plan／任务文件不由工具改写。
+
+| 操作 | 已实现结果 | 本片边界 |
+| --- | --- | --- |
+| init | 显式项目根、清单位置与work创建最小对象；同范围且已是三字段时重复调用不写；清理旧字段时保存原始历史 | 不自动扫描其他清单或推断EBC；scope不同拒绝覆盖 |
+| select | 直接登记明确初次选用或复用相同选择；同PBC不同prdId独立 | 不需要候选预登记；不同既有路径仍拒绝替换，配套及改选沿用准确预览；选用不是批准 |
+| resolve | 只读核选定路径；多主题要求明确身份 | 不读未选高版本或自动补TestCase；不改变Plan，语义和直接上游由调用方核 |
+| resolve＋manual | 没有清单也可按明确路径只读解析；已有清单可作当次覆盖 | 不创建JSON、目录、历史或采用关系；同角色重复手动路径报歧义 |
+
+引用角色：全局brd、technicalBaseline；主题prd、ad、testCase、prototype、engineeringSkeleton、contracts。主题引用需要capabilityId与prdId。相对路径按项目根，显式采用的项目外绝对路径只读引用，不复制；工程骨架可指真实采用文件或源码目录，仍须另读其实际说明。
+
+每次实际清单变化前保存同目录history旧稿，保留scope／selected内的人工内容与其他主题；未知顶层扩展先明确用途，不自动清理。写后脚本完整回读清单；调用方还须回读实际差量及必要旧稿。清单和history写入路径均拒绝符号链接越界。协作工具有基础排他锁、写前比对和原子替换；不保证与任意人工编辑器之间的事务，不自动清理旧锁或恢复失败。业务稿写入与JSON登记也不是跨文件事务。
+
+最小JSON不增加hash、批准或任务状态字段。同路径人工改稿后重新读取当前正文，不因旧路径或旧报告沿用认可。部分稿／失败的完成判定由调用方依据真实任务及回读证据负责；CLI成功只能说明路径登记，不能证明业务完成。
+
+S06原生验证仅证明旧版当时用法，不证明本次三字段和选用登记修订；S07命令、S08完整改选与恢复、S09独立审查、S10完整双入口矩阵、S11原Plan／Build实际消费和I4／I5工程仍分别取证。
+
+## 9. 真实调用与执行报告
+
+工具调用一经提交就是真实尝试；description中的“占位”“不执行”等文字不取消调用。状态说明、计划和待办只用会话文字，不提交探测或占位命令。按本轮明确工具范围操作，所需输入先实际读完；使用辅助时先核准确的`--help`接口，再做获准登记。必要工具被拒或失败就报告并停止依赖动作，不扩大权限或改用旁路；误发无关调用被拒，应如实列出，不将其说成辅助不可用，也不重复尝试。
+
+报告以真实tool_use／tool_result为依据，分别写清尝试、被拒、执行失败、成功及未确认；被拒也计入尝试。功能、写入边界、执行纪律及报告一致性分别判定。工具路径登记成功不能抵销其他偏差，模型自述不能代替轨迹或人工认可。
+
+需要外层执行复核时，调用者事先固定唯一项目、辅助路径、清单、主题、允许的引用和必需动作；由外层按[校验说明](verification/readme.md)检查原始轨迹、独立核心审计和最终报告。执行状态仅存在会话／外层证据报告，不写入业务handoff.json，不新增审批或任务状态，也不改变原方法。
+
+最终会话报告中附且仅附一个下列有界JSON块；每行对应本轮一条实际Bash尝试，ordinal从1连续编号，按真实顺序列全。operation只用help、init、select、resolve、other；status只用succeeded、blocked、failed、unconfirmed。禁止另加role等字段。长命令和来源由外层从轨迹保留，无须在此复制。下例为单次接口核对的格式示意，实际作业按真实次数展开：
+
+<!-- i3-sop-execution-report -->
+```json
+{"schemaVersion":1,"shellAttempts":[{"ordinal":1,"operation":"help","status":"succeeded"}]}
+```
+<!-- /i3-sop-execution-report -->
+
+没有回执或回执不支持时使用unconfirmed，不猜成功；权限明确拒绝为blocked，工具／进程或辅助明确失败为failed，实际成功回执为succeeded。外层检查通过仍需人工审阅；普通非Bash作业不被本CodeBuddy专用校验器强制增加调用。历史自由文字报告保持原样，问题另存校订说明，不追溯要求旧轮满足新增格式。
+
+上述shellAttempts只适用于直接Python辅助操作的既有S06校验。外层验证原生Skill、状态、Plan或Build前置时，显式选择[原生执行证据配置](verification/readme.md#原生方法与执行报告)，不把原校验器放宽为任意Bash守卫。该配置从真实轨迹提取全部工具尝试，最终报告只列失败／被拒／未确认尝试、调用者指定的输入核查和门禁状态；不要求模型手抄成功调用计数或工具ID。
+
+成功标志与正文矛盾时保留矛盾：例如Skill回执虽is_error=false但明确返回Error，不能报成功。路径存在、AD列有引用、宿主可能自动注入规则，都不证明已显式全文读取。已核／未核与未尝试分别写清；“无写入”“无Bash”“无工具调用”含义不同。报告的机器可核部分通过，不代表自由文字、设计语义或业务批准通过。
+
+## 10. 从选定 AD 到原 Plan、Build 的输入合同
+
+新项目业务文件默认在 spec/{能力}/，已有已采用路径不自动搬迁。资源根不变；JSON仍schemaVersion 1，不新增Spec角色、业务摘要、hash或批准／任务状态。工程入口由主题selected.ad或本轮手动AD路径定位；实际读取该AD、其准确PRD、规范／契约条款、骨架来源及必要代码。没有AD或六项不足时报告依赖缺口，JSON解析成功不能代替工程规格检查。
+
+生成文档后完整回读最终稿、展示路径并遵守原 Spec 的保存后停轮，不自动创建清单。用户明确采用后，获准交接作业才准备三字段清单并记录 selected；已有明确委托可直接承接，不重复询问。若登记失败只补准确选用引用，文档成功与选用登记成功分别报告。
+
+显式采用的项目指引可记录工作范围、capabilityId＋prdId和唯一清单，作为原Plan的查找线索；它不将标准任务切为SOP。若没有确定范围、多个主题可选或指引失效，原Plan应澄清／由用户手动给准确路径，不静默取最高版。原方法不会天然解析或写回JSON。
+
+可复制的最短手动交接：
+
+```text
+/i3-plan 本次使用企业SOP的等效规格。只规划：spec/巡检管理/巡检管理-任务编排-AD_v0.0.3.md 及其明确引用的PRD、已采用规范／契约、骨架来源和相关代码。完整核本主题SPEC六项、FR／AC、依赖和验证；TestCase按需。保留真实来源到tasks/plan.md与唯一任务目标，交我审阅，不实施。
+```
+
+有明确选用清单时可改为：
+
+```text
+/i3-plan 本次使用企业SOP。读取.i3/sop/巡检/handoff.json，仅选capabilityId=inspection、prdId=scheduling的AD及其必要配套；实际读正文并核直接上游／六项，不取候选或其他主题。按原方法规划并保留来源，交我审阅，不实施。
+```
+
+计划须保存真实输入路径／版本、主题、需求／AC及验证依据，不能仅保存一个可变清单链接。原默认产物、不同工作未完计划保护和人审停点保留；如使用原方法支持的外部tracker也只能有一个权威任务目标，并在原计划中说明。Plan 结果直接按原产物位置交接，不重复登记 JSON，不把缺少 delivery 列为交接缺口。
+
+原 /i3-build 只执行已获准的下一任务；原 /i3-build auto须满足其允许的规格位置与有效内容、Git条件和全计划明确认可。特别是.i3/sop、CODEBUDDY.md、docs/engineering及安装目录等未提交变化不在默认允许规划产物内，触发原停点时呈现冲突由用户决定，不能加ignore、隐藏或擅自提交业务稿绕过。已获准的独立测试仓库提交只证明该仓库的工程行为，不等于产品发布。
+
+Build前回读任务及关联实际设计，同路径或selected变化时核影响，受影响旧任务先由原Plan修订并获准，不用新稿偷换计划；无关任务和已完成历史保留。新会话回读真实来源与认可范围，不将模型自述、JSON或用例fixture当真人批准。按主题分组加载，必要共享约束仍完整覆盖。
+
+## 11. 门禁对象、时点和允许范围
+
+| 门禁 | 实际含义与时点 | 不应扩大或替代的事项 |
+| --- | --- | --- |
+| 原Spec保存后人审 | 起草／修订保存并完成最终回读后，按原方法停轮交审；后续采用与规划遵循真实审阅决定 | 不因外层检查通过继续自动调用Plan、Build或补登记 |
+| 明确选用登记 | 用户明确采用准确文档与配套，并允许写清单时才更新selected；原方法要求停轮则后续获准作业再做 | 新稿存在不构成选用；旧候选登记委托不构成选用委托；选用不等于Plan批准或开工许可 |
+| 局部Q／依赖缺口 | 写清影响的具体要求、契约、任务和最晚决定时点；未知保留待核 | 不把局部Q统一扩大成全部规划／登记禁令，也不跳过实际受影响任务前的决定 |
+| SOP Plan身份／直接上游冲突 | AD与本次准确PRD、所选范围的能力／主题标识或直接上游路径／PRD版本矛盾时，先停，不加载原规划、不写plan／todo或候选计划 | 疑似头部笔误、正文相似、文件已选或待审状态不代替人工处理；非阻断Q条款不能越过此停点，PRD／AD不强制同号 |
+| 原Plan审阅／批准 | 实际计划与唯一任务目标形成后，由真人明确批准具体版本、范围及检查点 | Spec认可、JSON选择、模型报告和测试fixture不能代替Plan批准 |
+| 原Build工程前置 | 保留原命令方法加载要求；auto核有效规格、真实Git基线和全计划明确认可 | 安全停止正确不代表全部调用义务已满足；缺后续实现证据不写成已执行TDD／构建／提交 |
+| 项目额外检查点 | 若计划要求任务完成后、提交前再次人审，应在计划审阅时明确是否采用、批准对象和时点 | 不静默新增检查点，同时承诺原auto无额外停轮；不改原Build来迁就候选Plan措辞 |
+| 测试／审查／Ship | 沿用各原方法的真实输入、质量、风险及授权条件；就绪与实际执行分别取证 | 外层报告、候选稿或Ship就绪结论不构成发布／生产操作许可 |
+
+这些门禁说明不新增业务JSON审批状态或替代原版规则。[单次受控交接](controlled-handoff.md)提供显式 CodeBuddy 入口，只对该次预检到明确选用登记或[同主题准确改选](selection-handoff.md)实施程序约束，不自动挂载其他会话或原版命令。改选先预览配套原文证据和Plan影响，再绑定该次明确选择；不更新原Plan或迁移批准。有真实项目约束冲突时只标注，给原因、推荐与可选操作，由使用者决定；业务稿与已完成任务不自动改写。
+
+## 12. 显式SOP Plan消费
+
+/i3-sop plan与显式Skill的plan按[同一规划合同](plan-handoff.md)确定唯一范围，复用resolve或明确手动路径，只读消费selected。计划输入不止AD，还包含准确PRD、实际规范／契约、工程采用和相关代码；已有适用TestCase／原型按需，SPEC六项仍核。实际调用原规划Skill并履行当前原Plan命令义务，保留原plan／todo、不同未完任务保护、回读与人审停轮。
+
+该动作不初始化或写回JSON，不登记Plan产物，不代批准或自动Build。无JSON不强制创建，坏JSON不静默换源；标准原/i3-plan保持原使用方式。工具只解析路径，身份／版本／直接上游及真实业务决定仍由实际原文与来源核对。
+
+手动和JSON Plan共用规划合同的首批必读及检查点；手动不豁免README、阶段索引、共用合同、交接合同与规划合同全文。身份或直接上游冲突优先于独立部分规划，先给证据和处理建议，不修改业务稿或JSON、不输出plan／todo；人工处理后重新核对再规划。此规则与§11局部Q的适用范围分开，不增加业务JSON状态或接管原版方法。