@givolt/i3-composer-agent 3.0.0 → 3.2.1

package/scripts/ui-prototype-native-test.js

@@ -133,9 +133,16 @@ function write(directory, relative, value) {
   const file=path.join(directory,relative); fs.mkdirSync(path.dirname(file),{recursive:true});
   fs.writeFileSync(file,Buffer.isBuffer(value)||typeof value==='string'?value:JSON.stringify(value));
 }
-function candidate(t) {
+function candidate(t,extra={}) {
   const root=project(t); const template=legacyFixture.prepareTemplate(require(path.join(skillsDirectory,'i3-ui-prototype/scripts/template-contract.cjs')), {project:root});
-  return lib.createPrototype({project:root,id:'devices',templateRoot:template.directory,expertMode:'template'}).directory;
+  const options={project:root,id:'devices',templateRoot:template.directory,expertMode:'template',...extra};
+  if(options.executionPolicy){
+    write(root,'scope.json',{schemaVersion:1,requirements:[{id:'AUDIT-RETIREMENT-1',text:'Synthetic fixed business coverage',source:{type:'prd',reference:'unit-fixture',statement:'Synthetic contract fixture, not browser acceptance'}}],exemptions:[],openQuestions:[]});options.scope=path.join(root,'scope.json');
+    const A=require(path.join(skillsDirectory,'i3-ui-prototype/scripts/execution-assertions.cjs'));
+    const assertions=A.template(options);for(const scenario of assertions.scenarios)scenario.checks=[{method:'evaluate_script',pointer:'/observed',operator:'equals',expected:true}];
+    write(root,'assertions.json',assertions);options.executionAssertions=path.join(root,'assertions.json');options.host='codebuddy';
+  }
+  return lib.createPrototype(options).directory;
 }
 function syntheticBuild(directory,{embedded=true}={}) {
   const current=lib.manifest(directory);
@@ -166,6 +173,21 @@ function syntheticReport(directory,build=syntheticBuild(directory)) {
   return {id:'synthetic-guard-fixture',status:'passed',candidateDigest:build.current.digest,revision:build.current.revision,buildId:build.buildId,buildDigest:build.buildDigest,executor:'unit-fixture',tool:'unit-fixture',source:'synthetic-unit-fixture',startedAt:'2026-10-17T00:00:00.000Z',completedAt:'2026-10-17T00:00:01.000Z',consoleErrors:[],journeys:[...acceptance.requiredScenarios,...acceptance.frameworkScenarios].map(id=>({id,status:'passed'})),screenshots:['qa/fixtures/a.png','qa/fixtures/b.png'],trace:'qa/fixtures/trace.zip',viewports:[1440,768],previewBaseURL,observedResources:Object.entries(build.files).map(([name,sha256])=>({path:name,url:new URL(name==='index.html'?'':name,previewBaseURL).href,status:200,sha256,resourceType:name==='index.html'?'document':name.endsWith('.js')?'script':name.endsWith('.css')?'stylesheet':'fetch'}))};
 }
 
+for(const executionPolicy of ['buddy-ab-v2','codebuddy-ab-v1'])test(`${executionPolicy}: normal browser record and finalize need no retired Hook binding`,t=>{
+ const directory=candidate(t,{executionPolicy});
+ assert.equal(fs.existsSync(path.join(directory,'qa/execution-context.json')),false);
+ assert.throws(()=>lib.finalize(directory),/acceptance|verified|验收/i,'Retiring audit must not accept missing business evidence');
+ const report=syntheticReport(directory);lib.recordRun(directory,report);
+ const delivery=lib.finalize(directory);
+ assert.equal(delivery.status,'complete');assert.equal(delivery.invocationVerification,'unverified');assert.equal(delivery.checks.execution,undefined);
+ assert.equal(delivery.checks.devtoolsReview,'current');assert.equal(lib.state(directory).delivery.status,'current');
+ assert.equal(fs.existsSync(path.join(directory,'qa/execution-context.json')),false);
+ assert.equal(fs.existsSync(path.join(directory,'qa/execution-evidence.json')),false);
+ assert.equal(lib.state(directory).execution.auditHook,'retired');
+ const evidence=path.join(directory,'qa/fixtures/devtools-dom.txt');fs.appendFileSync(evidence,'edited');
+ assert.throws(()=>lib.finalize(directory),/DevTools review required/,'Stale browser evidence still blocks finalization');
+});
+
 test('new policy blocks finalization and human baseline when DevTools review is missing or stale',t=>{
  const directory=candidate(t),report=syntheticReport(directory);lib.recordRun(directory,report);
  const current=lib.manifest(directory),file=path.join(directory,'qa/devtools-review.json'),valid=fs.readFileSync(file);
@@ -358,7 +380,7 @@ test('ordinary revise can start repair of broken user code without accepting cha
 });
 
 test('a failing real npm test prevents the build command and fixed build publication', t => {
-  const directory=candidate(t),app=path.join(directory,'app'),file=path.join(app,'package.json');
+  const directory=candidate(t,{executionPolicy:'buddy-ab-v2'}),app=path.join(directory,'app'),file=path.join(app,'package.json');
   const pkg=JSON.parse(fs.readFileSync(file));
   pkg.scripts={typecheck:'node -e "process.exit(0)"',test:'node -e "process.exit(3)"',build:'node build-test.cjs'};
   fs.writeFileSync(file,JSON.stringify(pkg));

package/skills/i3-enterprise-sop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: i3-enterprise-sop
-description: "组织显式选择的企业 SOP 文档与规划交接。适用于明确调用 i3-enterprise-sop 起草 BRD、PRD、AD、TestCase、制定 Plan 或传递选定资料；短命令先澄清缺口，再复用原版方法。"
-# i3-description-source: "description: Organizes explicitly requested enterprise SOP documents and planning handoffs. Use when the user explicitly selects enterprise-sop for BRD, PRD, AD, TestCase, plan or reference handoff; short actions clarify missing facts before using the original method."
+description: "组织企业开发文档、工程规格和项目规划。适用于显式调用 i3-enterprise-sop 编写、整理或修订 BRD、PRD、AD、TestCase、生成工程 SPEC 或依据规格规划任务。"
+# i3-description-source: "description: 组织企业开发文档、工程规格和规划交接。用于用户显式选择 enterprise-sop 编写、整理或修订 BRD、PRD、AD、TestCase、工程 SPEC，或依据规格规划任务。Use when explicitly requesting enterprise-sop to prepare enterprise documents with bundled templates, engineering SPEC or project planning."
 ---
 
 <!-- i3:zh-CN:start -->
@@ -12,162 +12,222 @@ description: "组织显式选择的企业 SOP 文档与规划交接。适用于
 Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
 严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
 
-适用说明：组织显式选择的企业 SOP 文档与规划交接。适用于明确调用 i3-enterprise-sop 起草 BRD、PRD、AD、TestCase、制定 Plan 或传递选定资料；短命令先澄清缺口，再复用原版方法。
+适用说明：组织企业开发文档、工程规格和项目规划。适用于显式调用 i3-enterprise-sop 编写、整理或修订 BRD、PRD、AD、TestCase、生成工程 SPEC 或依据规格规划任务。
 <!-- i3:zh-CN:end -->
 
-# 企业 SOP 单阶段作业与路径交接
+# i3-enterprise-sop
 
 ## Overview
 
-把本次明确的企业任务、项目采用模板和原专业方法组织为一次作业。`/i3-sop` 与直接调用本 Skill 共用以下规则：四阶段文档生成／修订必须使用原 Spec；显式 `plan` 组织选定的等效规格并使用原规划能力，交审后停轮。后续由用户按获准计划调用原 Build。支持路径清单与纯手动传递，不接管原生命周期。
+主会话使用企业模板和原专业 Skill 完成一次文档作业。T1 保存文档并登记路径，T2 检查选定资料后生成工程 SPEC，T3 调用原规划能力；每阶段交人工审阅后停下。
 
 ## When to Use
 
-只用于用户显式选择本 Skill 或明确委托的企业 SOP 作业。安装、发现 PRD、已有清单或模型推荐均不切换流程。用户明确使用标准流程时，不读企业资源，不建清单，继续其指定的原方法。原 using、Skill、命令和停点不改。
+- 用户明确选择企业开发 SOP，输入可以是自然语言、外部文档或明确修订意见。
+- 新建、整理同类外部稿、授权修订均可直接进入对应阶段，不要求重跑完整上游。
+- 标准流程沿用原方法。只读分析、状态查询或退出不进入写稿，也不创建目录或清单。
 
-## Process
+## 执行流程
 
-### 1. 确定一次任务
+```text
+用户调用
+ |
+ +-- 动作不明确 -> 交互选择或退出
+ |                选定后进入对应分支
+ |
+ +-- brd / prd / ad / testcase -> T1
+ |   +-- 用户明确选用同类已有文档 -> 读取原件
+ |   +-- 需要生成或修订 -> 显式调用 i3-spec-driven-development Skill
+ |       -> 当前模板及来源 -> 保存文档 -> 落盘完整性检查
+ |   -> 创建/更新 spec/handoff.json，登记本次文档 -> 交人审阅 -> 停止
+ |
+ +-- spec -> T2
+ |   显式调用 i3-spec-driven-development Skill -> 默认读取 spec/handoff.json
+ |   -> 检查当前主题的 BRD、PRD、AD
+ |      +-- 缺项 -> 提示 T1 对应操作或补充已有文档 -> 停止等待
+ |      +-- 齐备 -> 读取正文及工程依据
+ |          -> 保存 spec/SPEC-{PBC名称}-{主题名称}.md -> 落盘完整性检查 -> 交人审阅 -> 停止
+ |
+ +-- plan -> T3
+     显式调用i3-planning-and-task-breakdown skill + 选定工程 SPEC 及必要来源
+     -> Plan 和任务 -> 落盘完整性检查 -> 交人审阅 -> 停止
+```
 
-入口接受 `brd`、`prd`、`ad`、`testcase`、`plan`、`review`、`status`，自然语言任务可省略；四阶段明确新建时用 generate，明确修订才用 revise。无参数只读引导并结束，列出以上动作；未知操作列有效动作后结束。`auto` 留在 3.1.0，不转交原 Build auto。显式操作和正文冲突时先澄清；只有动作唯一且确实委托作业的自然语言才可整理为对应动作。
+各分支遇到关键缺口时先提问并等待真实答复；下一阶段由用户明确启动。
 
-短命令先只读定位当前项目、项目规则、已采用材料和现有目标，不要求用户填写内部路径或参数。对象／任务不明时先澄清，不为问问题预加载全部阶段模板与所有主题；明确对象后再完成§2的本次必要读取。材料与有效决定唯一且充分时直接复用，不重复请求确认。缺少的关键业务事实不由默认值、模型推荐或旧聊天记忆代答。业务未明可先问业务事实，不能未经实际安装元数据核对就声称资料未安装；Glob未匹配隐藏目录不证明目录或资源不存在。
+### 1. 确定本次操作
 
-| 动作 | 缺少时只澄清本次必要事项 |
+| 意图 | 操作 |
 | --- | --- |
-| brd | 业务能力、目标、对象和边界；不要求先有JSON，不按菜单／部门代划PBC |
-| prd | BRD或等效业务依据、PBC／主题，新增主题还是修改既有主题；各PRD独立版本 |
-| ad | 准确PRD及配套、实际技术规约／契约／骨架选择的缺口；优先已有规范，原型按需并行 |
-| testcase | 准确PRD／AD、测试边界和关键预期／环境未知项；配套不一致先报告，不执行测试 |
-| plan | 清单或手动方式、本次主题／明确组合、必要规格缺口和未完计划冲突，详见[规划交接](../../references/enterprise-sop-resources/plan-handoff.md) |
-
-`plan` 的范围明确后，JSON与手动路径先经过同一个读取准备环节，不提前分流到原规划。先按项目采用记录或下文真实安装清单定位所选资料根，不能从skills目录猜资料路径。首批完整读取原 `/i3-plan` 命令正文及该根的README.md、stages.json、template-contracts.md、handoff-contract.md、plan-handoff.md；必读资源名以索引planHandoff.requiredResourceReads为同一清单，不只读专用plan说明就继续。手动方式仅省去JSON解析／辅助调用，不豁免共用说明、项目规则或必要业务依据；未知自改组合仍读实际选定原件。
-
-SOP准备环节的文件／目录定位使用Read、Glob、Grep，不以ls、find、mkdir等shell命令探测目录或试验权限。需要解析JSON时按当前宿主已许可的接口调用handoff.py；不要因Bash工具名称可见就认为任意命令已获准。原规划方法继续履行本次实际允许范围内的工具义务，不扩大权限。
-
-进入原规划前，核上述共用全文回执、原命令全文回执及准确业务／工程依据；相关代码之外，按实际技术栈定位并完整读取真实依赖／构建配置（Node项目例如package.json），不能只从AD或规范复制命令就声称工程配置已核。缺读／部分读／失败先补齐，未齐不加载原规划、不写plan／todo。再核身份与直接上游，最后取得原规划Skill成功回执，才可生成原产物。最终说明列实际读过的共用资料、工程配置、原命令路径和真实失败；只提名称、脚本已读或自称已遵守不代替模型读取。
-
-AD声明的能力／主题身份与本次PRD或所选范围冲突，或直接上游路径／声明版本与本次准确PRD矛盾时，必须先停：不调用原规划，不创建、修改plan／todo，也不另写候选计划。即使正文看起来一致、模型判断只是头部笔误，也只报告原文差异、影响和建议，等待人工处理后重新核对；不修改业务稿或JSON。“可独立规划部分”仅适用于身份与上游已核一致后的非阻断缺口。PRD与AD独立版本不必同号，核对的是AD准确引用的PRD版本。
+| `brd`、`prd`、`ad`、`testcase` | T1：确定类型及对象，保存文稿或选用同类已有稿，自动登记路径 |
+| `spec` | T2：检查清单及当前主题 BRD／PRD／AD，齐备后生成工程 SPEC |
+| `plan` | T3：选择工程 SPEC，生成实施计划和任务 |
+| 未给动作或意图不明 | 交互选择“企业文档（再选四类）／工程 SPEC／项目计划／退出” |
 
-业务澄清阶段尚未读取命名合同，不凭印象提供所谓默认文件名或首版版本；先问缺少的业务事实，之后按已采用规则或共用合同给准确输出约定。BRD梳理的是EBC业务范围，PBC由其识别和划分，不将二者混称。
+自动整理当前项目、输入及目标；只对真实歧义提问，不要求用户填写内部路径或任务卡。文件存在不授权覆盖，推荐不代替用户选定。
 
-目标已有稿件时先分清新建／新版本、明确修订、恢复或只读查看，不把裸阶段名解释成覆盖。写前确定唯一输出与版本，沿用项目已采用命名；未知事实保留Q和影响，不为凑章节虚构。
+### 2. 使用原方法，按需读取资料
 
-宿主有实际可用的结构化提问工具时使用简短问题和选项，允许用户自己说明；没有该工具、当前模式不能交互或工具不可用时，用普通会话提问并停轮等待。取消、无答复、预选、时间经过或含糊答复均不代替必要决定；等待期零项目写入，不先建占位稿、清单或采用记录。前四阶段把已有答复交原Spec，继续其真正需要的内容澄清，不能再做重复访谈或跳过原停点。plan则承接原规划的澄清，不重跑Spec。
+T1／T2 写作意图明确后，先通过宿主正式机制显式加载原 `i3-spec-driven-development` Skill并读取正文，再进行实质分析、澄清或写稿。Skill名称以宿主登记为准，可能带 `i3-` 前缀；加载失败先说明并停下。使用原 Skill 的 Specify 方法及外部格式能力，保留适用能力划分、内容、澄清和人审要求；T1 输出企业文档，T2 输出工程 SPEC。
 
-明确当前项目根、阶段／动作、工作范围、准确输入和唯一输出。多个清单或主题并存时先确定对象，不取目录最大版本。目录、命名及新项目默认见[共用合同](../../references/enterprise-sop-resources/template-contracts.md)§1；既有项目位置不自动迁移。
+上述原 Spec 与 T3 原规划都须真实调用，并向执行会话完整提供方法正文；不能截取返回，或只提供摘要、预览、长度及成功标识后按“已加载”继续。回包受限时按下述读取规则补齐同一原 Skill 的原文；补读文件不替代宿主的真实 Skill 调用，完整方法取得前不进行该方法的实质工作。
 
-纯路径登记或交接准备不生成／修订业务文档，不调用 Plan、Build 或测试。新稿起草、现稿修订、采用选择、业务认可和工程执行分别依据实际任务。
+- **来源选择：**按资源角色采用本轮明确材料 → 项目明确采用副本 → 本 Skill 对应资料。读取项目已有的适用规则和采用约定；项目自改模板优先，失效或冲突先说明，不静默换版。提供业务文档不等于选择某份模板。
+- **输入读取：**新建先定位当前完整模板和必要业务／工程原件；恢复或修订先完整取得当前稿及对应模板，再补本次必要来源，不重跑上游阶段。AD仍须按下文完整取得实际采用的规约与目录规范。已读且未变的来源复用，变化后重核受影响内容。索引、统计和引用不代替正文；请求范围、文件总长或后台已读不证明执行会话已收到。只有实际返回正文连续覆盖所选原件，才能报告完整读取。
+- **分页与续读：**UTF-8 长文或截断回包可用只读辅助 [read_text.py](references/read_text.py)：主会话内部执行 `python3 "<Skill>/references/read_text.py" --path "<当前原件>" --offset 0`，每次只回传一页，确认本页正文完整收到后，用返回的 `nextOffset` 读取下一页，直至连续覆盖到 `eof`。区分工具外层结果、分页对象与其中的 `text`，不得把对象当正文字符串处理，或把多页、多份长文拼成一次大回包。截断时减小 `--max-chars` 重读当前页；其他读取方式从实际收到的最后完整正文处重叠续读，按工具的真实范围语义核对接缝，不跳过未收到的中段。末页标识只说明读取位置，不能弥补此前缺页。该辅助不写文件、不替代原 Skill 调用，也不要求用户填写路径。
 
-任务说明本次输出目标已有稿件、该目标写入中断、登记失败、重复执行或人工修改时，先按[最小恢复规则](../../references/enterprise-sop-resources/recovery-contract.md)核现状，不把阶段名直接解释成重新 generate。只有上游 PRD 等输入已存在、目标 AD 尚未创建时，仍按明确的新建任务处理，不误判为现稿恢复。恢复默认只读评估；明确采用某份文档且允许登记时才改本次清单，明确委托修稿才另按原 Spec 执行。部分稿不自动续写或选用，已有 Plan 不因恢复改变。
+  主会话内部调用一页的示意：
 
-现稿需受控交接时采用[单次受控入口](../../references/enterprise-sop-resources/controlled-handoff.md)：调用方从本次采用记录整理准确路径，先运行 CodeBuddy 只读预检；外层核成功回执并确认本次准确选用委托后，才登记 selected；旧候选登记授权不构成选用委托。被此入口调用的只读会话只用 Read/Glob/Grep/Skill，不自行调用 shell、登记、原 Spec 或其他工程方法。缺读可在本次只读会话内补齐；拒绝、失败或选择冲突须列原因、推荐和可选操作，不能用后续成功抹去。入口不自动挂载普通会话，不改变标准流程或原版停点。
+  ```text
+  result = 执行 read_text.py --path "<当前原件>" --offset 当前游标（首次为 0）
+  退出码非 0：返回真实错误，先处理失败，不推进游标
+  page = 解析 result.stdout；向会话原样返回 page（含 path、offset、nextOffset、eof、text）
+  本页完整收到且 eof 为 false：下一次使用 page.nextOffset；eof 为 true：核对连续覆盖后结束
+  ```
 
-明确要求改变同主题既有选用组合时，按[改选与影响预览](../../references/enterprise-sop-resources/selection-handoff.md)处理：先只读核当前／目标 PRD、AD、已有用例／原型的直接上游及规约、契约、骨架、Plan／任务；展示准确差异、缺口、原因、推荐与选项。未列配套沿用旧引用但必须核绑定，不能将旧 AD 静默配给新 PRD；显式解除仅移除引用、保留文件。预览后取得该组准确路径的明确选择，才可使用受控辅助更新本主题。来源变化或配套未知须重新预览，不能用模型推荐、候选登记或自动模式代替人作选择。原 Plan、任务及已完成记录不因改选自动改写。
+  成功页不含 `ok` 字段，以进程退出码判断成功。`--max-chars` 默认 6000、允许 512—10000，限制的是包含路径、JSON 标记与换行的整包，正文可能更短；续读位置取 `nextOffset`，不按请求上限相加，也不只返回正文而丢弃游标。
+- **安装定位：**确有需要时局部核包身份、版本、布局、作用域、宿主和当前 Skill 的精确路径；不通读资产列表，也不以安装记录替换项目采用。
+- **澄清：**沿原 Spec 先核来源、已采用规约及真实答复，问清尚未决定且影响本次输出的关键缺口或实际冲突，并等待真人答复。提问说明已有事实及尚缺的差异，已定技术版本不与未定部署范围混问；不重复询问已有决定，也不把一般 Q 全部变成前置审批。资料充分就拟稿，一般未决项保留 Q、有依据的推荐／备选及影响；已有允许保留 Q 的约定时不再泛问能否保留，实际阻断事项仍须说明。多个独立决定分别表达，选项不捆绑额外限制、期限或技术选型。交互工具不可用时用会话文本等待；收到答复后绑定原问题及当前文档继续，来源改变才重核受影响事项。预选和工具授权不算业务答复，未答项保持未确认，不用候选覆盖既有决定。
+- **交互回执：**交互工具的接口未确认时先查实际工具定义，按其必填字段提问；向执行会话返回工具的真实答案或错误，不用自造的成功标记替代。工具报错先纠正调用，未取得真实答复就保持等待，不推定用户已选择。
+- **写入：**确定真实业务项目根及唯一文档目标，先读现稿和人工修改，保留修改前版本及影响。保持各文档独立版本、能力／主题身份与 FT／US／FR／AC，不按最大版本或同号猜配套。只写本次获准文档及按第4节登记的清单，保留来源、历史和未处理意见。
+- **长文写入与恢复：**长文从首次就按章节或可独立核对的小段写入，每次控制在当前工具可完整接收的范围内，确认实际结果后再续写。使用宿主写入能力将正文作为数据传递，避免把整稿嵌入可执行代码。调用失败先核目标文件现状，区分未写入、部分写入和已写入但回执失败；依据实际已保存正文确定续写点，仅补缺失或修复受影响段，不清空重写整稿或盲目重复追加。同类错误经针对修正仍重复，或无法确定续写边界时，保留稿件和原清单，说明已完成／缺失范围与原因并停下。
 
-未采用的文档保留原位置，在会话中说明实际路径和未选用状态；不登记候选，也没有候选撤回操作。已选主题的撤销、业务需求取消、文件删除和功能退役仍是另有范围的任务，不因未选用某稿而自动执行。
+**保存检查：**核对目标路径、非空正文、实际版本与本次拟交付内容一致；文件存在或标题数量只作辅助。正常保存不要求再次全文加载。分段写入按实际各段核对顺序及全部接缝，检查重复或遗漏；报错涉及的段须复核。工具可比对待保存文本与落盘内容，按需读取差异或受影响正文。完整性不能确认时保留稿件和原清单，说明原因并停下，不自动登记或推进。
 
-### 2. 读取适用来源
+**核验汇报：**自查使用现成只读工具或不落盘命令，不为常规统计生成临时脚本，也不扩大获准写入范围。分别说明结构核对、局部抽查、内容自查和工具验证的实际范围、结果及未验证项。抽查不称全文核验，围栏或图块存在不称图语法／渲染通过；只有实际执行相应解析、渲染或比对后才报告其结果。落盘检查、内容自查和人工审阅分别判断，统计不代替正文理解，登记成功不代表内容获批。
 
-本次动作为 `plan` 时先完成§1的统一共用读取，按所选资源根的[规划交接](../../references/enterprise-sop-resources/plan-handoff.md)核读取准备、身份及上游停点，再进入原规划分支；不是只读本说明便跳过其他共用文件。JSON／手动两种输入遵守同一必读清单，不套四阶段模板／生成提示词，不生成新规格。标准原规划任务不进入本Skill，也不因清单存在而读取企业资料。
+### 3. T1：企业文档
 
-本次动作是 review／recheck 时先按[统一审查约定](../../references/enterprise-sop-resources/review-handoff.md)分流：调用者定位项目采用及准确业务对象，由外层辅助解析索引、清单和依赖；不要先套下面生成／状态作业的五项共用全文读取。独立审查者仍完整读项目规则与实际采用约束、本阶段README、完整模板、唯一动作和业务原文；未知／自改组合按选定原件完整读取，不静默回退。纯引导／status／交接／恢复及生成／修订保持原读取规则。
+| 动作／完整模板 | 业务输入 | 自动带入及输出 |
+| --- | --- | --- |
+| BRD：[brd.md](references/templates/brd.md) | 业务诉求或外部 BRD；已有项目背景和约束 | 本模板；输出一个 EBC 的 BRD，明确目标、范围、场景、BR及 PBC 划分 |
+| PRD：[prd.md](references/templates/prd.md) | BRD及当前主题，或外部 PRD及业务依据 | 本模板和真实答复／适用规则；输出一个 PBC 的一个独立主题 PRD，保留完整行为、权限、状态、字段、AC及依赖 |
+| AD：[ad.md](references/templates/ad.md) | 选定 PRD，或外部 AD及需求依据 | 本模板、默认具体规约与目录规范（项目明确资料优先）、必要契约及工程事实；输出对应 PRD 的三图与完整工程详设 |
+| TestCase：[testcase.md](references/templates/testcase.md) | 选定 PRD／配套 AD，或外部 TestCase及产品、技术依据 | 本模板、必要采用资料及适用测试条件（按模板“来源选择”处理）；输出对应主题／AD 的覆盖、用例、预期和 TestReport 要求，不执行测试 |
 
-资料定位：本轮明确来源 → 项目已采用自改副本 → 同宿主项目安装 → 同宿主可读全局。实际读取项目规则、根说明及明确引用的采用约定；已选来源失效就报告，不静默换模板或跨宿主兜底。历史、验证样例和备份不作默认候选。
+一个业务项目对应一个 EBC，一个 EBC 一份逻辑 BRD；一个 PBC 可有多个主题 PRD，各自独立演进。AD绑定准确 PRD，TestCase绑定准确 PRD／AD，文档不强制同号。关键依据缺失先说明受限范围；企业文档已交审不代表工程规格已齐备。
 
-CodeBuddy没有对应角色的明确项目采用根时，先定位项目 `.codebuddy/` 中本包的隐藏安装清单：显式Glob `.codebuddy/.*composer*.json`，不能用默认忽略隐藏目录的全局Glob断言不存在。实际读取name／version／scope／resources，核本包身份及当前宿主范围；多个、异名或损坏清单先报告，不当作未安装。将resources.references相对于**该清单所在目录**展开，再进入其中的enterprise-sop-resources；不是skills目录，也不是相对于项目根直接展开references字段。可先Grep精确键找行号，再Read必要范围，不全文加载assets清单。项目确实未安装时才查同宿主可读全局清单；有项目自改采用根时不先探读发行副本。其他宿主依据其真实安装清单定位，不借CodeBuddy目录兜底。
+四类文档明确记录 `ebcId`、`ebcName`；PRD／AD／TestCase再记录 `pbcId`、`pbcName`、稳定 `prdId`及主题名称，BRD在PBC分配表记录各能力的编号、名称和边界。各稿保留自己的 `documentId`、文档版本、实际路径、状态和采用模板版本。编号沿用已确认业务来源，名称变化不换编号、不自动迁移目录；身份未明先澄清，不从目录名或文件名猜编号。
 
-阶段所需模板／原方法确实不可用时报告准确缺口并停下，可提示选择已有可读资料或安装；不把“无企业模板裸跑继续”列作同一次SOP作业的选项。用户另行明确改走标准流程才按原标准方法处理，不能静默降级。
+**统一命名：**目录名、文档文件名及本稿标题／身份信息、`handoff.json`中的名称和文档路径，统一复用本次同一份已确定的EBC／PBC名称和主题名称，不分别取名、缩写或替换同义名称。AD、TestCase和工程SPEC沿用对应PRD的PBC名称和主题名称；已有名称直接沿用，缺失或冲突时先澄清。清单仍使用现有字段，主题名称体现在文档及其路径中，不新增字段；既有明确采用路径和外部原件保持实际位置，不自动改名或搬迁。
 
-安装清单用于定位资料根，只读取识别所需的 name／version／scope／resources 字段；可先定位键再读取相应范围，不全文注入 assets 文件列表。业务与模板必要正文仍实际读取，不能用这种元数据裁剪替代内容核对。
+按各模板现有身份／输入／采用表记录引用ID与类型、来源身份、准确路径或URL、正文版本或固定提交及条款、采用范围与落实位置、实际状态与缺口，摘要按需记录。直接依据和跨PBC参考分别标明角色与提供方；主链身份与版本须一致，关联资料可来自其他能力。原型由PRD／AD固定引用，规约、目录规范、实际骨架与契约由AD记录采用及权威位置，TestCase承接适用版本和判据；不另建平行引用清单，也不因资料从JSON移出而省略必要正文读取。
 
-先读取所选资源根的 [README](../../references/enterprise-sop-resources/README.md)、[索引](../../references/enterprise-sop-resources/stages.json)、[共用合同](../../references/enterprise-sop-resources/template-contracts.md)、[交接合同](../../references/enterprise-sop-resources/handoff-contract.md)和[生命周期合同](../../references/enterprise-sop-resources/lifecycle-contract.md)。实际起草／审查时，再读索引指定的本阶段 README、manifest，以及该 manifest 指定的完整模板和本次唯一动作提示词；不按默认路径猜模板，也不加载四阶段全部资料。
+四类文档分别操作。用户明确选用同类已有文档时，读取原件并登记路径，不重复生成或覆盖原件；作为上游、参考或待整理／修订输入时，仍按本次委托写稿。
 
-明确企业 status、只读交接与恢复也须完成上述五项共用读取；它们不需要生成模板和 Spec，不等于可以跳过共用合同。安装清单实际用于定位时，逐项确认 name、version、scope、resources.references 的真实值；只搜索资产列表里的资源名称不算完成身份核对。列出实际路径及读取结果，缺项先补读或保留未通过，不以“已自动注入”代替回执，也不把后来补读追认为旧作业写前已读。
+新建企业文档默认按职责分目录：BRD直接保存在`spec/`根目录，完整路径为`spec/{EBC名称}-BRD_v{业务版本}.md`；PRD、AD、TestCase保存在各自PBC目录，完整路径为`spec/{PBC名称}/{PBC名称}-{主题名称}-{PRD|AD|TestCase}_v{各自版本}.md`。项目明确采用的位置或选用外部原件时登记实际路径，已有文档不因本规则自动移动。仅在生成权限和目标明确后创建必要目录。初始业务版本可建议v0.0.1，已有项目不机械改名或升版，模板版本与业务版本分开。
 
-写前列出本次适用路径／用途并核实际读取结果，必要来源未读／部分读／失败时先补齐或报告受影响范围，不能声称完成读取后写稿。项目自改内容保留，不按发行摘要还原。
+**EARS 使用：**适用行为写清责任系统及可观察响应，有前置条件或触发事件时明确写出，并核对异常和副作用。保留原文的条件、例外及“必须／应／可”的含义；关键缺口先澄清，一般未决项列为待确认问题（Q）。按当前模板使用，不为句式额外读取其他模板。
 
-交接清单相对路径以实际项目根解析；资源索引相对路径以资源根解析。按准确角色读取真实正文，核主题身份、正文／文件版本、直接上游与缺口。路径存在和脚本读文件均不代替模型实际全文读取及语义核对。
+**写前准备：**沿当前模板的既有章节简要对应本次来源、已定事项和待确认项，复用模板已有的覆盖／追溯位置，不另建中间文件或要求逐章审批。对应关系用于组织正文，不替代原件。开始写入前自查：必要正文已连续取得，关键冲突已有真实处理依据，或本次明确允许形成保留相应 Q 的可审阅稿；条件未满足就补读或澄清，不先写稿再补缺失输入。恢复只补本次获准的缺失或受影响章节，保留现稿和人工修改。
 
-### 3. 按任务复用原能力
+按完整模板写稿或修订，新增规范性要求回查来源、条件及强度，核行为条件与响应、跨章节权限／状态／AC和逐表列义。保存后按第2节核验落盘完整性，完成后按第4节自动登记本次文档路径，不再等待额外的登记口令。汇报文档及清单路径、版本、实际登记结果、保存检查、内容自查、Q及影响，请人审阅并结束当前轮；真实反馈后读取当前稿和准确答复修订，再交审。登记失败如实报告，不因此丢弃已保存稿件，也不自动进入后续阶段。
 
-起草或修订 BRD／PRD／AD／TestCase 时，必须先调用原 [i3-spec-driven-development](../i3-spec-driven-development/SKILL.md) Skill，再按本次明确的企业任务、模板和唯一输出执行；不是让 using 判断是否需要 Spec，也不调用会默认保存根 SPEC.md 的 `/i3-spec` 包装来替代它。原 Spec 支持外部规格格式与存储；内容要求、澄清、权限、认可及结束轮次完整保留，真实冲突先报告，不改原版或另造影子 SPEC。
+**AD 准备：**默认完整读取自带的[企业应用具体规约](references/technical-baseline/baselines/enterprise-application-technical-baseline-v0-0-4.md)和[目录规范 1.0.0](references/engineering-skeleton/directory-standard.md)，作为生成 AD 的技术与结构输入，不再要求用户先单独选用。项目已经明确采用自己的规约或目录约定时，优先沿用其实际版本。AD §0.3、§9.6直接记录来源、版本、适用范围及工程映射，不另建采用说明。
 
-`plan` 必须按[规划交接](../../references/enterprise-sop-resources/plan-handoff.md)实际调用原 [i3-planning-and-task-breakdown](../i3-planning-and-task-breakdown/SKILL.md)，读取并履行本宿主当前原 `/i3-plan` 命令合同。不是只输出提示词让用户再粘贴，不以提及名称或自行写计划代替成功加载；没有正式加载机制或调用失败时停止说明。Skill加载与命令转交分别记录，不声称等价执行另一个slash命令。此分支不调用Spec、不改业务稿／JSON、不进入Build。
+启动 AD 且没有项目替代规范时，直接将上述默认具体规约及版本矩阵作为本次设计输入，按实际范围记录采用及待落实条件，不再询问是否采用。规约中项目绑定或采用确认的说明在 AD 中据此落实；设计采用不表示真实安装、联调或业务批准。PRD 未规定的工程选型由已采用规约补充，接入细节待定不代表已定技术方向失效，不因此另建替代体系。只有明确的项目差异或实际冲突才交用户裁定。
 
-宿主提供 Skill 工具时须取得加载原 Spec 的成功回执，继续读取其本次适用正文；只在计划里写 Skill 名称、读取索引或自行声称已调用不算。原生没有该工具的宿主使用其正式技能加载机制并保留可核记录；方法不可用就说明缺口，不裸跑写稿。按任务另用适用专业方法，不造第二张全局路由表。纯引导、状态、只读审查和已有文件的路径登记不调用规格生成。
+没有可读、适用的具体技术规约时，先提示用户根据[通用技术规约模板](references/technical-baseline/templates/technical-baseline.md)生成。取得该技术文档的写入委托后，在当前准备环节起草规约并交审；用户确认后继续 AD，不用空模板代替实际规约，也不自行编选型。已选项目规约失效时先说明，不静默切回默认副本。
 
-AD 的直接产品依据是选定 PRD。公共技术规约优先复用项目已有规范；没有时说明可选来源或候选，不静默决定技术栈／骨架。原型按需，可与 AD 并行。TestCase 是测试设计，不执行测试，也不是所有 Plan 的必需文件。
+结合项目 CONSTRAINTS、ADR、正式契约和工程事实落实设计。目录规范不等于已经生成代码，已有与拟建位置分别写明，实际创建留给后续任务。原型按需，可与 AD并行；共享契约、数据责任、版本兼容和变更影响落实到 AD。
 
-写作成功后完整回读最终稿，展示实际路径并按原 Spec 停轮交审，不自动更新 JSON。只有本次任务已明确采用准确文档时，后续获准交接作业才登记 selected；已有明确委托可直接承接，不反复询问。失败／部分稿保留实际状态，不为填清单造未来路径或补批准。
+### 4. 自动登记与清单读取
 
-### 4. 最小路径交接
+T1 交稿时自动创建／更新 handoff.json，登记本次保存的文档；用户明确选用的同类已有文档同样登记实际路径。仅提供参考稿不视作选用成稿。先核所选文档的EBC身份、文档类型及PBC／PRD主题，身份不明时询问，不猜配套。一个业务项目对应一个EBC，新建清单保存在业务项目的`spec/`根目录，路径为`spec/handoff.json`；其中BRD引用`spec/`根目录文件，PRD／AD／TestCase引用各自`spec/{PBC名称}/`内的文件。路径和参数由主会话显式传入，既有明确采用的清单保留实际位置，不自动迁移。
 
-使用所选发行资料根的 [handoff.py](../../references/enterprise-sop-resources/handoff.py)；项目采用副本只有明确包含兼容辅助工具时才改用该工具。Python 3.9+ 为此辅助的运行条件；没有可用解释器时保留手动路径方式，不安装依赖或改项目环境。
+登记前读取原清单并保留历史，仅处理本次明确资料及输出，保留其他主题；登记后回读结果。实际更新时，旧清单保存在清单同级的`history/`目录，新位置对应`spec/history/`；已有历史不自动搬迁。登记记录所选资料路径，不表示文档获批、内容无缺口或允许开工。只读审查、状态查询和退出不创建或修改清单。
 
-先执行工具 `--help` 核接口。以下是工具操作，不是新增顶级命令；`<资料根>`与项目路径均须用实际位置替换。
+新版顶层仅 `schemaVersion`（整数2）、`scope`、`selected`。以下编号、版本和路径为结构示例，不是已形成或已批准的业务资料：
 
-```text
-python3 <资料根>/handoff.py init --project-root <项目根> --manifest <本次清单> --work <工作范围>
-python3 <资料根>/handoff.py select --project-root <项目根> --manifest <本次清单> --role prd --path <用户明确选用的现有PRD> --capability-id <PBC> --prd-id <主题ID>
-python3 <资料根>/handoff.py resolve --project-root <项目根> --manifest <本次清单> --capability-id <PBC> --prd-id <主题ID>
+```json
+{
+  "schemaVersion": 2,
+  "scope": {
+    "ebcId": "EBC-PM",
+    "ebcName": "项目管理"
+  },
+  "selected": {
+    "brd": "spec/项目管理-BRD_v1.1.md",
+    "topics": [
+      {
+        "pbcId": "PBC-PRJINIT",
+        "pbcName": "立项管理",
+        "prdId": "PRD-PRJINIT-001",
+        "prd": "spec/立项管理/立项管理-立项申请与评审-PRD_v0.1.0.md",
+        "ad": "spec/立项管理/立项管理-立项申请与评审-AD_v0.2.0.md",
+        "testCase": "spec/立项管理/立项管理-立项申请与评审-TestCase_v0.1.0.md"
+      }
+    ]
+  }
+}
 ```
 
-- 仅在本次已明确采用文档并允许写清单时使用 init／select；不在安装、生成待审稿或只读任务中初始化。清单顶层只有 schemaVersion、scope、selected；原 Plan 产物不回写 JSON。
-- select 直接登记明确选用的现有路径，无需先登记候选；初次或相同选择可复用，不代表业务批准或计划批准。不同既有路径仍拒绝直接替换，同主题改选沿用准确预览入口。旧候选操作不映射成选用，手动方式保留。
-- 一份 PRD 主题按 capabilityId＋prdId 区分。不同主题与 PRD／AD／TestCase 可独立版本，不补造缺失身份。工具不推断语义兼容，交接前仍核直接上游。
-- 工具只改本次清单和同目录 history 旧稿，保留其他主题及 scope／selected 内人工内容。旧 JSON 可只读取得 selected，明确选用写入时才备份并移除旧 candidates／delivery；未知顶层扩展先说明用途再处理，不静默删除。没有强制文档 hash，写后回读差量和原始历史。
-- 工具基础锁与写前比对不构成跨编辑器事务保证。登记失败保留文档和旧清单，只报告待补登记；不重复生成业务稿，不接管 Plan 或已完成任务。
+- 一份清单对应一个EBC，`scope.ebcId`、`scope.ebcName`为非空字符串；每条主题必有 `pbcId`、`pbcName`、`prdId`。`pbcId`＋`prdId`在本清单内唯一，同一 `pbcId` 的名称须一致。
+- `selected.topics`始终为数组，无主题时为`[]`；`brd`及主题中的`prd`／`ad`／`testCase`仅在实际形成并选用后登记非空文件路径。主题至少有一份已选资料，缺项省略，不填null、空串、未来路径或虚构配套。
+- 相对路径始终基于业务项目根，不随清单位置变化；脚本将新登记的项目内文档引用统一写成以`/`分隔的业务根相对路径，因此JSON中的BRD路径为`spec/{EBC名称}-BRD_v{业务版本}.md`，PRD／AD／TestCase路径为`spec/{PBC名称}/{PBC名称}-{主题名称}-{文档类型}_v{各自版本}.md`。主会话传入实际已保存的文件路径，脚本不猜目录、不移动文件；已有明确采用位置按实际路径登记，明确选用的外部原件可使用绝对路径。各文档自行记录版本及准确来源，SPEC和Plan继续记录自身来源。
+- 清单不保存 `work`、`capabilityId`、`technicalBaseline`、`engineeringSkeleton`、`prototype`、`contracts`；移出资料的准确引用由第3节及模板承接。v2未知字段先报错并保留原件，不静默删字段。
+
+可按实际CLI使用 [handoff.py](references/handoff.py)（Python 3.9+）：T1无清单时先`init`，再`select`；T2用`resolve`只读取得当前主题引用。T1写稿或明确选用文档的委托包含登记，不另问一次。所有操作必须显式传入预期`--ebc-id`，清单模式还须传同一业务根及实际清单位置；预期编号由当前任务与所选BRD／PRD确定，不能把清单里的值机械回填当作正文核验。
 
-### 5. 手动与只读方式
+`init`须提供`--ebc-name`；`select`主题资料须提供成对的`--pbc-id`、`--prd-id`，新建主题还须提供`--pbc-name`，已有主题可复用已登记名称。传入名称与已登记身份冲突时报告原文差异，不静默改名。`resolve`只有一个主题时可自动定位，多个主题必须显式选择，不能按最大版本猜选。返回结果含`scope`、所选`topic`身份与名称及各文档实际路径，只证明已读取路径，正文语义及配套仍由主会话核对。
 
-纯手动路径交接不创建 JSON、目录或采用记录；已有 JSON 的手动覆盖也仅限本次输入，不持久更改 selected。显式plan动作使用手动输入时，仍按规划合同允许原plan／todo产物，不能把“手动输入”误解成所有动作零写入。
+以下为新项目的内部调用示意，清单路径显式传入`spec/handoff.json`；既有明确采用的清单替换为其实际位置。其余参数由实际已选资料取得，不要求用户填写内部路径：
 
 ```text
-python3 <资料根>/handoff.py resolve --project-root <项目根> --work <工作范围> --capability-id <PBC> --prd-id <主题ID> --manual prd=<实际PRD> --manual ad=<配套AD>
+python3 "<Skill>/references/handoff.py" init --project-root "<业务根>" --manifest "spec/handoff.json" --ebc-id "<ebcId>" --ebc-name "<ebcName>"
+python3 "<Skill>/references/handoff.py" select --project-root "<业务根>" --manifest "spec/handoff.json" --ebc-id "<ebcId>" --role brd --path "<已选BRD路径>"
+python3 "<Skill>/references/handoff.py" select --project-root "<业务根>" --manifest "spec/handoff.json" --ebc-id "<ebcId>" --role prd --path "<已选PRD路径>" --pbc-id "<pbcId>" --pbc-name "<pbcName>" --prd-id "<prdId>"
+python3 "<Skill>/references/handoff.py" select --project-root "<业务根>" --manifest "spec/handoff.json" --ebc-id "<ebcId>" --role ad --path "<已选AD路径>" --pbc-id "<pbcId>" --prd-id "<prdId>"
+python3 "<Skill>/references/handoff.py" resolve --project-root "<业务根>" --manifest "spec/handoff.json" --ebc-id "<ebcId>" --pbc-id "<pbcId>" --prd-id "<prdId>"
 ```
 
-可完全不运行工具，直接读取明确路径并提供输入摘要与问题。两种方式都核身份、版本、直接上游和必要工程约束；缺 TestCase 如实记录验证依据，不强制建清单或重跑 BRD。
-
-引导、status、review、recheck 零项目写入。审查只给问题、原文位置、来源、影响和建议；作者会话不冒充独立审查，报告另存由获准调用者处理。
-
-review／recheck共用外层解析／模型正文读取规则，按[独立只读审查衔接](../../references/enterprise-sop-resources/review-handoff.md)执行。当前作者会话有获准且已验证的CLI隔离能力时，由外层调用者整理本次所选资料、准确目标和真实来源，使用该资料根的verification/review_handoff.py启动新的只读会话；辅助不在审查者内部执行，不调用原Spec、Plan或原代码review，不串行修稿。复查绑定旧稿、原报告及逐项人工回应，仍使用新上下文。没有隔离机制则给出可复制的新会话任务并结束；已在新会话也须如实说明实际权限证据，不能自称清除了上下文。证据检查通过仅接受本轮报告，业务问题及人工处理空间保留。
-
-### 6. 交原 Plan 与 Build
+已有v2清单不重复初始化。BRD登记不带PBC／PRD身份；主题资料仅使用`prd`／`ad`／`testCase`角色。EBC不匹配、名称冲突、旧版或未知字段均保留原件并说明原因；失败按实际参数、路径及范围核对，不盲重试、不另造清单规避。
 
-用户显式调用 `/i3-sop plan` 或本Skill的plan动作时，本Skill读取所选清单／明确手动路径，按[规划交接](../../references/enterprise-sop-resources/plan-handoff.md)组织原文输入并实际复用原规划。只生成原计划与唯一任务目标，完整回读并交人工审阅后停轮。四阶段文档作业仍不自动进入该动作；原 `/i3-plan` 加明确企业任务的手动方式保留。
+旧v1不自动迁移，也不把`work`当作EBC编号。只有明确处理具体业务清单时，先回读BRD／PRD核实身份，确认原型引用已由PRD／AD、规约／骨架／契约引用已由AD及适用TestCase承接，再按本次授权补齐文档及v2清单并保留原件／历史；引用未承接或授权不足时保留待处理，不仅删字段。
 
-Plan内的来源表逐项记录实际使用的PRD、AD、规范、契约、工程采用说明的完整项目相对路径（明确外部来源则绝对路径）及其文档版本，不只写AD_v…、契约简称或JSON位置。保存后将来源表与本次实际读取集合逐项对照，缺项先补齐Plan并再次全文回读，再交审；不修改来源业务稿或JSON。
+`select`支持`brd`／`prd`／`ad`／`testCase`四类文档换路径。主会话先回读新旧文档，核实EBC、PBC／PRD主题和文档类型，再登记本次明确使用的路径；脚本在清单模式的每次操作校验`--ebc-id`与`scope.ebcId`，不能省略。只更新指定字段，保留旧文档、清单历史、同主题其他引用及其他主题；回执中的`updatedSelection`提供旧／新路径，不写入业务JSON。
 
-新项目默认将业务文档存于 `spec/{能力}/`。工程规划入口是本次选定 AD 及其明确引用的 PRD、已采用规范、共享契约、真实骨架与相关代码；在入口及已选集合内逐项回读 SPEC 六项。BRD、空链接、JSON、只有文件落在 spec/ 均不证明工程规格齐备。不复制第五份核心 SPEC，不改 JSON schema 或强制业务 hash。
+PRD更新后保留原AD／TestCase引用，由T2检查是否配套，不自动改稿或删除引用。身份或范围不明、其他资料换选、清单并发变化及登记失败时，保留文稿与原清单，说明原因并停下；不绕过保护。T2只读解析不创建或修改清单。
 
-按[交接合同](../../references/enterprise-sop-resources/handoff-contract.md)§10准备原 `/i3-plan` 的实际输入。有明确采用指引可据其读取唯一范围；没有指引就手动列准确路径。原 Plan 不天然读写 JSON，多个主题／版本没有选择时先问，不猜。计划保留实际来源、主题、FR／AC、共享依赖和验证依据，仍输出原 `tasks/plan.md` 与唯一任务目标，不覆盖其他工作未完计划。
+T2默认读取已登记路径；用户仍可明确选择手动传递，不强制补JSON。`resolve --manual`只接受四类文档：有清单时仍核`--ebc-id`，覆盖仅对本次读取生效；无清单时提供`--ebc-id`、`--ebc-name`，主题资料另提供`--pbc-id`、`--pbc-name`、`--prd-id`，形成临时上下文。两种手动方式都不创建目录、清单或历史；主会话同样核BRD／PRD／AD身份、版本及必要引用。
 
-随后由用户审阅并明确批准计划，才调用原 `/i3-build` 或 `/i3-build auto`。原 Build auto 的有效规格、Git 干净基线、完整计划认可、逐任务测试／构建／提交和风险停点全保留；未提交的 `.i3/sop`、项目指引等可能触发原 Git 停点，不隐藏、不擅自提交业务文件规避。企业跨阶段 auto 与原 Build auto 是不同功能。
+### 5. T2：工程 SPEC
 
-### 7. 按主题加载与新会话恢复
+1. 确定预期EBC和PRD主题，优先沿用已明确采用的清单，否则默认定位并读取`spec/handoff.json`；显式传入实际`--manifest`及`--ebc-id`校验范围：从`selected.brd`取BRD，从当前`pbcId`＋`prdId`对应主题取PRD、AD。多个主题／版本不明先交人选择，不猜最新。无清单且未明确提供手动输入时，提示回T1生成并登记，或由用户补充已有文档；停下等待。
+2. 检查BRD、PRD、AD三份文档的路径、可读正文、EBC／PBC名称编号、主题身份与各自版本，以及AD引用的直接PRD是否与当前选定版本一致。生成稿与用户明确选用的外部稿均可使用。缺少任一项或无法读取时，列出具体缺项及T1对应的`brd`／`prd`／`ad`操作，提示生成或补充现有文件；停止本轮，不先写工程SPEC。PRD更新而AD仍引用旧版、身份名称冲突或其他来源矛盾时，先说明并提示处理，不继续写SPEC，也不用其他主题或旧稿代替。TestCase保持可选。
+3. 使用第2节已显式加载的原Spec，完整读取选定BRD、本主题PRD、配套AD，并沿文档的固定引用读取必要原型、实际采用规范／契约／骨架和相关配置；已有且适用的TestCase读取准确版本。直接依据须与本主题一致，跨PBC参考须明确提供方、用途及准确版本；缺少必要附件时说明受限范围，不因JSON精简而跳过。复用已确认业务事实，只澄清新增工程缺口或冲突。
+4. 按原 Spec 结构形成完整六项：Objective来自BRD／PRD；Commands、Project Structure、Code Style、Boundaries来自AD及实际规范／骨架／工程配置；Testing Strategy来自AD、已有用例或项目测试规范。写明精确技术版本、成功条件、Q及来源，关键设计落实为可实施和可验收条款，不只写“见AD”，也不编造工程事实。
+5. 新建工程SPEC保存在业务项目的`spec/`根目录，路径为`spec/SPEC-{PBC名称}-{主题名称}.md`；项目已有明确采用位置时沿用实际位置，不自动迁移或覆盖旧稿。记录主题身份、准确来源路径／版本及条款。通常一主题一份SPEC；涉及多个独立能力时按原Spec先划分并交人确认，不将PBC／prdId自动当技术module id。多选目标仍遵守各次审阅停点。
+6. 按第2节核验工程SPEC的落盘完整性并做内容自查，说明六项当前依据、未决影响与可交审范围，请人认可或修改并立即停轮，不自动生成Plan。
 
-只加载本次主题的完整 PRD、配套 AD、适用共享条款／必要跨主题契约及相关代码，不全量读所有主题、候选、最高版本和历史。按需分段覆盖长文；摘要用于导航，分段本身不保证总上下文降低。规划必须覆盖本范围全部需求／AC／接口／数据与验证，不因节省上下文漏掉共用边界。
+### 6. T3：原规划
 
-跨主题工作先辨明依赖图再分组读取；一个默认 Plan 只有一个有效任务目标。新会话实际回读范围、规则、来源、Plan／todo和Git状态；沿用原 i3-context-engineering 的持久记录／任务边界恢复方法，不宣称自动 token 监测。Build 前同路径或选用内容变化须核任务影响，不能偷偷将旧任务套新设计；修订计划与开工认可仍按原方法。
+1. 选择实际工程SPEC；未明确路径时，默认从业务项目的`spec/`根目录定位当前主题的`SPEC*.md`，既有明确采用位置沿用实际路径。多个范围／版本不明先问。无SPEC时提示T2或退出；普通文档、模板和JSON不当作工程规格。用户另行选择原Plan的等效规格方式，仍沿原能力处理。
+2. 显式调用原 `i3-planning-and-task-breakdown`并按第2节取得完整方法；宿主提供原Plan命令时读取正文并履行产物／停点约定，无命令包装时按原规划Skill执行。加载失败停下说明。
+3. 读取完整选定SPEC及相关代码，按其引用补读规划必要的AD／契约／采用依据，核六项、关键设计、来源变化、直接上游和原方法要求的实际认可。
+4. 输出原 `tasks/plan.md` 及唯一任务目标（默认 `tasks/todo.md`，或项目指定tracker）。将需求／AC和关键设计映射到任务、预计文件、结构与行为验收及验证步骤，记录准确来源。TestCase可选；已有适用版本就用，没有则从真实规格安排验证及必要用例设计任务，不豁免测试策略。
+5. 保留原方法的未完计划保护和依赖／切片规则，不覆盖其他工作未完成的计划。按第2节核验产物落盘完整性并做内容自查，交人审阅后停下；Plan获批后由用户按原Build及后续入口继续，遵守各原方法的权限和停点。
 
 ## Common Rationalizations
 
-| 说法 | 实际约束 |
+| 借口 | 纠正 |
 | --- | --- |
-| 新稿生成了，后续就该用它 | 只有明确选用才更新 selected；选用不等于业务批准或计划批准 |
-| 用户选了企业流程，后面可以自动做 | 本片只完成明确的一次作业，原方法停点及后续授权继续有效 |
-| 路径相同，可以沿用旧结论 | 当前正文和配套仍须回读；不靠旧摘要判断业务就绪 |
+| 输入少，就补齐一套默认业务或技术规则 | 关键缺口向真人澄清，一般问题标Q，建议保留未确认状态 |
+| 已保存或登记，就可以继续下一阶段 | 保存、登记、业务审阅、工程认可及Plan批准分别判断，保留当前停点 |
+| 索引或统计检查通过就等于内容正确 | 输入要实际读取必要正文；输出的落盘检查、内容自查与人工审阅分别判断 |
 
 ## Red Flags
 
-- 标准任务读取企业模板，或只读任务新建清单。
-- 用高版本、候选、历史记录或脚本成功替代明确选择和真实认可。
-- 为完成登记修改业务稿、Plan、任务勾选或原 Skill／命令。
+- 模板／项目副本被静默换版，或尚未明确的主题被自动选定。
+- 来源、权限、状态、关键工程约束在文档和任务间不一致。
+- 文件名／正文版本不符，覆盖人工修改，或把建议、预选和工具授权当成业务决定。
+- 没有原Skill实际加载结果，或作者自查被当作独立审查、业务认可或运行通过。
 
 ## Verification
 
-- 实际所读输入、模板／工具来源、主题与输出可定位；缺项和未核内容准确列出。
-- 新稿只展示路径，明确选用才更新 selected；写后已回读清单，旧稿及人工修改保留。
-- 纯手动路径交接及只读任务零项目变化；显式plan的手动输入只允许原规划产物，标准流程不误用企业资料。
-- 按[共用交接合同§9](../../references/enterprise-sop-resources/handoff-contract.md#9-真实调用与执行报告)报告真实尝试及回执；占位说明不用工具，拒绝／失败不漏报。需外层执行复核时附约定的最小报告块，不声称新命令、全流程、工程或发布已验收。
+- [ ] 实际调用原方法，输入、模板、来源及主题／版本可定位，未读和缺失范围如实说明。
+- [ ] 输出覆盖完整模板／原方法要求，事实、建议、决定、工程现状和运行结果分别表达。
+- [ ] 长文按段保存，实际段间衔接及失败续写范围已核对；已核验输出落盘完整性，内容自查覆盖来源、身份版本、权限／状态／AC、结构约束及表格，汇报范围与实际检查相符。
+- [ ] 修改前版本、人工编辑、未处理意见和失败记录保留，只写本次授权目标。
+- [ ] T1已保存并核验完整性或读取选定原件，并如实报告清单登记结果；T2已核对同一主题的BRD、PRD、AD，缺项或冲突时未写工程SPEC。
+- [ ] 汇报真实路径、版本、自查、Q及影响，按原方法交审停轮，不代签认可或自动推进。

package/{references/engineering-skeleton-resources → skills/i3-enterprise-sop/references/engineering-skeleton}/directory-standard.md

@@ -8,11 +8,12 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
-内容版本：1.0.0。适用范围：明确采用本规范的业务工程。目标是让 AD 约定的工程与模块位置，继续落实到原 Plan 的文件范围和原 Build 的真实产物。
+规范基线版本：1.0.0。作为本 Skill生成 AD 的默认目录输入；项目已有明确目录约定时优先沿用。AD记录本项目的实际映射，T2工程 SPEC承接约束，T3原 Plan安排任务，获准 Build形成真实产物。
 
 ## 1. 基本规则
 
 - 先确定实际业务项目根。工程相对路径均从该根解析；安装的 Skill／资源目录及 i3 维护工作树不是业务输出根。
+- 一个业务项目对应一个EBC；新建BRD、handoff.json及工程SPEC保存在`spec/`根目录，PRD／AD／TestCase保存在各自`spec/{PBC名称}/`目录。
 - 规范约定外层职责；工程内部遵循项目已采用的语言／框架惯例，具体位置由 AD 和真实配置明确。
 - 只采用当前需要的工程类别；实际有内容时再建目录。空目录不等于已交付工程，Git 也不保存空目录。需要先说明预留位置时可写有意义的 README，无需到处添加占位文件。
 - 新建工程标识使用稳定、可区分的小写短横线名称，例如 admin-web、business-api。语言内部包名／模块名遵循其自身规则；现有项目保留原名并建立映射。
@@ -26,11 +27,16 @@
 ```text
 project/
 ├── README.md                     工程入口、工程清单与真实命令
-├── spec/{能力}/                  当前业务文档及版本历史
+├── spec/                         文档及交接资料
+│   ├── {EBC名称}-BRD_v{业务版本}.md  EBC的BRD直接放在spec根目录
+│   ├── handoff.json              本项目EBC的交接清单
+│   ├── SPEC-{PBC名称}-{主题名称}.md  当前主题工程SPEC
+│   ├── history/                  清单实际更新时保留的历史
+│   └── {PBC名称}/                 本PBC各主题的PRD／AD／TestCase及版本历史
 ├── tasks/
 │   ├── plan.md                   原 Plan 的默认计划
 │   └── todo.md                   仅在采用默认文件任务目标时维护
-├── docs/engineering/             按需：项目规范／采用说明
+├── docs/engineering/             按需：项目技术规约与工程记录
 ├── frontend/<engineering-id>/    按需：前端源码工程
 ├── backend/<engineering-id>/     按需：业务后端源码工程
 ├── agents/<engineering-id>/      按需：本项目内 Agent 源码工程
@@ -50,7 +56,7 @@ project/
 
 使用现有 SOP JSON 时沿用其已采用位置；不要求为了目录规范再创建 .i3/project.yaml、templates.lock、contracts.lock 或生成记录库。已有项目或工具确有这些文件时按其真实用途保留。
 
-spec/ 下按业务能力组织文档。一个 EBC 的 BRD 识别相关 PBC；同一 PBC 的多个需求主题各有独立 PRD 版本及准确对应的 AD／TestCase，配套版本号可以不同。既有已采用文档目录不因本规范迁移。
+BRD默认直接保存到`spec/`根目录，路径为`spec/{EBC名称}-BRD_v{业务版本}.md`；PRD、AD、TestCase默认保存到各自PBC目录，路径为`spec/{PBC名称}/{PBC名称}-{主题名称}-{PRD|AD|TestCase}_v{各自版本}.md`。交接清单保存在`spec/handoff.json`，工程SPEC保存在`spec/SPEC-{PBC名称}-{主题名称}.md`；清单内相对路径均基于业务项目根，实际更新清单时保留的历史位于清单同级`history/`（新位置为`spec/history/`）。一个项目对应一个EBC，其BRD识别相关PBC，同一PBC的多个主题独立维护PRD及配套AD／TestCase版本，配套版本号可以不同。既有明确采用位置、历史及外部原件保留实际路径，不因本规范自动迁移。
 
 ## 3. 独立 Agent：agent-standalone
 
@@ -59,9 +65,14 @@ spec/ 下按业务能力组织文档。一个 EBC 的 BRD 识别相关 PBC；同
 ```text
 agent-project/
 ├── README.md
-├── spec/{能力}/
+├── spec/
+│   ├── {EBC名称}-BRD_v{业务版本}.md
+│   ├── handoff.json
+│   ├── SPEC-{PBC名称}-{主题名称}.md
+│   ├── history/                  清单实际更新时保留的历史
+│   └── {PBC名称}/                 本PBC各主题的PRD／AD／TestCase
 ├── tasks/                       原 Plan 和唯一任务目标
-├── docs/engineering/            按需：规范采用与工程说明
+├── docs/engineering/            按需：项目规范与工程记录
 ├── <框架构建／配置入口>
 ├── <源码根>/                    AD 确定的本应用源码
 ├── <程序测试位置>/              采用框架的原有测试位置
@@ -70,9 +81,9 @@ agent-project/
 └── delivery/                    按需：运行装配／部署
 ```
 
-采用说明把主 Agent 工程映射到项目根“.”。日后确需组合多个可独立构建工程时，按 AD 明确新增位置，不能因为模板示例存在 agents/ 就把当前代码自动搬进去。
+在 AD中把主 Agent 工程映射到项目根“.”。日后确需组合多个可独立构建工程时，按 AD 明确新增位置，不能因为模板示例存在 agents/ 就把当前代码自动搬进去。
 
-此处 Agent 是业务工程；3.1.0 规划的企业研发调度 Agent 是另一项产品能力。外部 Agent 服务只引用正式契约和消费者适配，不把其源码和内部 AD 复制到本项目。
+此处 Agent 是业务工程。外部 Agent 服务只引用正式契约和消费者适配，不把其源码和内部 AD 复制到本项目。
 
 ## 4. 四类工程与配套目录职责
 
@@ -95,20 +106,23 @@ jobs 可以是已有后端工程里的模块；Agent 也可以是已有工程中
 
 AD 至少映射本次需要的源码／业务模块、配置、测试、契约、迁移及运行装配位置；不适用项有依据说明。Plan 进一步列出每项任务预计新增／修改的文件及路径。Build 按获准任务生成有实际内容的文件，未选择工程不预建空架子。
 
-编译、打包、依赖和缓存产物遵循真实工具配置，例如 dist、target 等；在采用说明中必要时说明输出及忽略规则。不能把构建输出位置的差异等同于业务源码越界，也不通过移动编译产物掩盖源码位置错误。
+编译、打包、依赖和缓存产物遵循真实工具配置，例如 dist、target 等；在 AD中必要时说明输出及忽略规则。不能把构建输出位置的差异等同于业务源码越界，也不通过移动编译产物掩盖源码位置错误。
 
 项目根可按工具实际需要保留构建配置、workspace／CI 等公共文件，路径在 AD 或计划中说明。不要为满足外层分类，把框架入口强行放到无法正常工作的目录。
 
-## 6. AD、原 Plan、原 Build 的约束链
+## 6. 在 AD 中记录工程映射并交接
+
+不单独编写采用说明。直接在 AD §0.3、§9.2、§9.6记录：规范及版本、业务项目根、pbc-composite或agent-standalone组织方式、工程标识与职责、工程根和必要模块／配置／测试／契约／迁移／运行位置，以及共享维护方、已有／拟建状态和偏差理由。已有项目资料可以引用，不能把未知写成已应用。
 
 | 环节 | 必须明确的内容 | 如何核对 |
 | --- | --- | --- |
-| 采用说明／AD | 规范版本、项目根、所选组织方式、工程与模块映射、共享责任和例外 | 读真实来源与当前代码，区分已有、拟建及未定事项 |
-| 原 Plan | 当前 AD／采用说明引用；每项任务文件路径、依赖、验收与验证方法 | 任务可以落到真实或拟建位置，共享文件不安排互相覆盖的独立写入 |
-| 获准原 Build／Build auto | 实际回读任务所需来源，按映射生成／修改源码、配置、测试 | 对照任务和实际变更文件核落点，再完成原有测试／构建与任务处理 |
-| 原测试／Review／Ship | 实际代码、结果与本次范围 | 目录检查只是适用验收之一，不取代功能正确性、独立代码审查或发布条件 |
+| AD | 本规范或项目约定的准确来源、工程与模块映射、共享责任和例外 | 对照真实来源及代码，已有、拟建与未定分开 |
+| T2工程SPEC | 当前 AD的关键目录和设计约束、相关来源及准确版本 | 形成可实施、可验收条款，不仅写“见AD” |
+| T3原Plan | 选定工程SPEC；任务预计文件、依赖、结构／行为验收和验证方法 | 任务落到真实或拟建位置，共享文件不安排互相覆盖的写入 |
+| 获准原Build／Build auto | 任务所需来源，实际源码、配置和测试落点 | 对照任务及实际变更，遵守原测试、构建、提交和风险停点 |
+| 原测试／Review／Ship | 实际代码、运行结果与本次范围 | 目录只是适用验收之一，不替代功能正确性或发布条件 |
 
-原能力不会因为目录规范文件存在就自动消费它。显式任务或已采用项目指引负责把路径交进去；原版 Skill、命令、默认 Plan 和任务权威保持。具体可复制说明及核对步骤见 [采用与交接](adoption.md)。
+目录文件存在不代表后续方法已读取。按本 Skill将目录约束写入 AD和工程SPEC，再由原规划落实到任务；具体流程见 [SKILL.md](../../SKILL.md)。本规范不改变原版 Skill、命令或任务权威。
 
 ## 7. 存量工程、人工修改与变更