@givolt/i3-composer-agent 3.0.0 → 3.1.0

package/scripts/ui-demo-test.js

@@ -0,0 +1,170 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawn } = require('node:child_process');
+const { runInNewContext } = require('node:vm');
+const installation = path.join(__dirname, 'lib/installation.js');
+const skills = fs.existsSync(installation) ? require(installation).loadInstallation().skillsDirectory : path.resolve(__dirname, '../skills');
+const resources = require(path.join(skills, 'i3-ui-demo/scripts/resources.cjs'));
+
+test('i3-ui-demo waits for a submitted template choice and accepts submitted empty as default', () => {
+  assert.equal(resources.selectTemplates({ submitted: false }).status, 'needs-selection');
+  assert.deepEqual(resources.selectTemplates({ submitted: true, values: [] }).selected, ['enterprise-admin']);
+  assert.deepEqual(resources.selectTemplates({ submitted: true, values: ['1', 'enterprise-admin'] }).selected, ['enterprise-admin']);
+});
+
+test('i3-ui-demo never substitutes unavailable templates or drops one from a multiple selection', () => {
+  for (const values of [['2'], ['3'], ['4'], ['1', '2'], ['unknown']]) {
+    assert.throws(() => resources.selectTemplates({ submitted: true, values }), /unavailable|Unknown/);
+  }
+});
+
+test('i3-ui-demo resolves its own enterprise template and design rules', () => {
+  const result = resources.resolveResources();
+  assert.equal(result.skillRoot, resources.root);
+  assert.equal(result.templateRoot, path.join(resources.root, 'assets/templates/enterprise-admin'));
+  assert.equal(result.template.id, 'enterprise-admin');
+  assert.ok(fs.statSync(result.generation).isFile());
+  assert.ok(fs.statSync(result.designRules).isFile());
+  assert.ok(fs.statSync(path.join(result.templateRoot, 'reference/src/shell/ConsoleShell.html')).isFile());
+  const generation = JSON.parse(fs.readFileSync(result.generation, 'utf8'));
+  assert.ok(generation.choices.layout.sidebar);
+  assert.ok(generation.choices.style.business);
+  assert.equal(result.versions.component.version, '1.6.0');
+  assert.equal(result.versions.design.version, '2.15.0');
+});
+
+test('i3-ui-demo template resolution works without another prototype skill and never falls back to its template', t => {
+  const temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-demo-owned-template-')));
+  t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
+  const own = path.join(temporary, 'skills', path.basename(resources.root));
+  fs.cpSync(resources.root, own, { recursive: true });
+  const isolated = require(path.join(own, 'scripts/resources.cjs'));
+  assert.equal(isolated.resolveResources().templateRoot, path.join(own, 'assets/templates/enterprise-admin'));
+  const dependencies = require(path.join(own, 'scripts/dependencies.cjs'));
+  const detection = dependencies.check({ project: temporary, home: path.join(temporary, 'home'), host: 'codebuddy', env: {} });
+  assert.equal(detection.ready, false);
+  assert.equal(detection.design.availability, 'missing');
+  assert.equal(detection.official.availability, 'missing');
+  const ownGeneration = path.join(own, 'assets/templates/enterprise-admin/generation.json');
+  const foreign = path.join(temporary, 'skills', path.basename(resources.root).startsWith('i3-') ? 'i3-ui-prototype' : 'i3-ui-prototype', 'assets/templates/enterprise-admin');
+  fs.cpSync(path.dirname(ownGeneration), foreign, { recursive: true });
+  fs.unlinkSync(ownGeneration);
+  assert.throws(() => isolated.resolveResources(), /missing/i);
+});
+
+test('i3-ui-demo owns one complete capability contract including native mappings and lifecycle checks', () => {
+  const definition = JSON.parse(fs.readFileSync(path.join(resources.root, 'assets/templates/enterprise-admin/capability-definition.json'), 'utf8'));
+  assert.equal(definition.schemaVersion, 2);
+  assert.equal(Object.keys(definition.capabilities).length, 26);
+  assert.equal(Object.keys(definition.patterns).length, 10);
+  for (const capability of Object.values(definition.capabilities)) {
+    assert.ok(capability.implementation.components.length, capability.id);
+    assert.ok(capability.scenarios.every(scenario => scenario.expected && scenario.id), capability.id);
+    const native = capability.nativeChecks || [];
+    assert.equal(new Set(native.map(check => check.id)).size, native.length, capability.id);
+  }
+  assert.equal(definition.capabilities.pagination.defaults.mode, 'adjustable');
+  assert.ok(definition.capabilities.feedback.parameters.states.includesByMode['management-list'].includes('empty'));
+  assert.ok(definition.capabilities.dialog.nativeChecks.some(check => check.id === 'mask-blur'));
+  assert.ok(definition.capabilities.theme.scenarios.some(check => check.id === 'accessibility'));
+});
+
+test('default native presentation matches the owned template palette and dimensions', () => {
+  const source = file => fs.readFileSync(path.join(resources.root, 'assets/starter/src/domain', file), 'utf8');
+  const themes = source('theme.ts').match(/export const THEME_PRESETS = (\{[\s\S]*?\n\}) as const/);
+  const recipe = source('presentation.ts').match(/export function presentationTokens\(value: Presentation\) \{([\s\S]*?)\n\}/);
+  assert.ok(themes && recipe, 'The native theme and presentation definitions must be readable');
+  // Installer checks support Node 20; evaluate the actual JS expressions without importing TS.
+  const body = recipe[1].replace(" as 'small' | 'middle' | 'large'", '');
+  const actual = runInNewContext(`const presets = ${themes[1]}; function tokens(value) {${body}};
+    ({light:presets.light,presentation:tokens({layout:'sidebar',style:'business',density:'standard'})});`, {}, { timeout: 1000 });
+  const profile = resources.resolveResources().visual;
+  assert.equal(actual.light.primary, profile.nativeTokens.colorPrimary);
+  assert.equal(actual.light.bg, profile.nativeTokens.colorBgLayout);
+  assert.equal(actual.light.text, profile.nativeTokens.colorText);
+  assert.equal(actual.light.border, profile.nativeTokens.colorBorder);
+  assert.equal(actual.light.panelBorder, profile.nativeTokens.colorBorderSecondary);
+  assert.equal(actual.presentation.borderRadius, profile.nativeTokens.borderRadius);
+  assert.equal(actual.presentation.panelRadius, profile.panelRadius);
+  assert.equal(actual.presentation.spacing, profile.spacing);
+});
+
+test('reference mappings reject unrelated capabilities and create separate node scenarios', () => {
+  const scope = { pages: [{ id: 'assets', title: '资产', referencePage: 'models-page', regions: [{ id: 'list', pattern: 'management-list',
+    fields: [{ id: 'name', label: '名称', requirementId: 'R1', type: 'text' }],
+    actions: [{ id: 'query', label: '查询', requirementId: 'R1', target: 'page', outcome: '展示匹配资产' }] }] }],
+    requirements: [{ id: 'R1', text: '查询资产', pages: ['assets'], source: { type: 'user', reference: 'request', statement: '查询资产' } }] };
+  const element = resources.readPage('models-page').elements.find(item => item.component === 'ProTable');
+  const decision = { pageId: 'assets', nodeIds: [element.id], decision: 'mapped', reason: '对应资产列表', requirementId: 'R1', bindingIds: ['assets/list/collection'] };
+  const mapped = resources.plan({ ...scope, generation: { referenceDecisions: [decision] } });
+  assert.ok(mapped.scenarios.some(item => item.referenceNodeId === element.id));
+  assert.ok(!mapped.pendingReferenceElements.some(item => item.pageId === 'assets' && item.id === element.id));
+  assert.throws(() => resources.plan({ ...scope, generation: { referenceDecisions: [{ ...decision, bindingIds: ['app-shell/shell/theme'] }] } }), /capabilit|mapping/i);
+  assert.throws(() => resources.plan({ ...scope, generation: { decisions: [{ pageId: 'assets', capabilityId: 'pagination', decision: 'not-applicable', reason: '省略', requirementId: 'R1' }] } }), /Required/);
+  assert.equal(new Set(mapped.scenarios.map(item => item.id)).size, mapped.scenarios.length);
+  assert.throws(() => resources.plan({ ...scope, pages: [{ ...scope.pages[0], regions: [{ id: 'form', pattern: 'form-page', parameters: { edit: { presentation: 'drawer' } } }] }] }), /presentation/i);
+});
+
+test('i3-ui-demo reads selected page structure, behavior and styles without an installed prototype skill', t => {
+  const temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-demo-page-')));
+  t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
+  const own = path.join(temporary, 'skills', path.basename(resources.root));
+  fs.cpSync(resources.root, own, { recursive: true, filter: file => path.basename(file) !== '.DS_Store' });
+  const isolated = require(path.join(own, 'scripts/resources.cjs'));
+  const page = isolated.readPage('models-page');
+  assert.ok(page.fragments.some(fragment => fragment.file.endsWith('ModelsPage.html')));
+  assert.ok(page.behaviorFiles.some(file => file.endsWith('ModelsPage.js')));
+  assert.ok(page.behaviorFiles.some(file => file.endsWith('/models/store.js')));
+  assert.ok(page.styleFiles.includes('reference/styles/tokens.css'));
+  assert.ok(page.elements.length > 0);
+  assert.ok(page.elements.some(element => element.events.length > 0));
+  assert.ok(!JSON.stringify(page).includes('i3-ui-prototype'));
+  assert.equal(isolated.readCapability('pagination').defaults.minimumTestPages, 3);
+});
+
+test('i3-ui-demo maps required page capabilities and keeps reference decisions pending until accounted for', () => {
+  const scope = { title: '资产管理', pages: [{ id: 'assets', title: '资产台账', referencePage: 'models-page',
+    regions: [{ id: 'list', pattern: 'management-list' }] }],
+    requirements: [{ id: 'ASSET-01', text: '资产查询、分页和批量处理', pages: ['assets'],
+      source: { type: 'user', reference: 'request', statement: '创建资产管理列表' } }] };
+  const plan = resources.plan(scope);
+  assert.equal(plan.status, 'pending-implementation');
+  assert.ok(plan.bindings.some(binding => binding.id === 'assets/list/columns'));
+  assert.ok(plan.bindings.some(binding => binding.id === 'app-shell/shell/theme'));
+  assert.ok(plan.pendingReferenceElements.length > 0);
+  assert.ok(plan.scenarios.some(scenario => scenario.bindingId === 'assets/list/pagination'));
+  assert.throws(() => resources.plan({ ...scope, pages: [{ ...scope.pages[0], referencePage: 'missing' }] }), /reference|page/i);
+  assert.throws(() => resources.plan({ ...scope, pages: [{ ...scope.pages[0], regions: [{ id: 'list', pattern: 'management-list',
+    parameters: { pagination: { mode: 'fixed' } } }] }] }), /fixedPageSize/);
+});
+
+test('i3-ui-demo rejects changed or missing owned capability and style resources', t => {
+  const temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-demo-integrity-')));
+  t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
+  const own = path.join(temporary, 'skills', path.basename(resources.root));
+  fs.cpSync(resources.root, own, { recursive: true, filter: file => path.basename(file) !== '.DS_Store' });
+  const isolated = require(path.join(own, 'scripts/resources.cjs'));
+  const css = path.join(own, 'assets/templates/enterprise-admin/reference/styles/tokens.css');
+  fs.appendFileSync(css, '\n:root { --easel-primary: red; }\n');
+  assert.throws(() => isolated.resolveResources(), /integrity|changed|digest/i);
+});
+
+test('owned template preview serves its entry, offline runtime and styles without an instance app folder', { timeout: 10000 }, async t => {
+  const child = spawn(process.execPath, [path.join(resources.root, 'assets/templates/enterprise-admin/serve.cjs'), '0'], { stdio: ['ignore','pipe','pipe'] });
+  t.after(() => child.kill());
+  const url = await new Promise((resolve, reject) => {
+    child.on('error', reject);
+    child.on('exit', code => reject(new Error(`Preview exited: ${code}`)));
+    child.stdout.on('data', chunk => { const match = String(chunk).match(/http:\/\/127\.0\.0\.1:\d+\//); if (match) resolve(match[0]); });
+  });
+  const response = await fetch(url);
+  assert.equal(response.status, 200);
+  assert.match(await response.text(), /src="offline\.js"/);
+  for (const file of ['offline.js','reference/styles/tokens.css']) {
+    const asset = await fetch(new URL(file, url));
+    assert.equal(asset.status, 200, file);
+  }
+});

package/scripts/ui-prototype-execution-runtime-test.js

@@ -10,7 +10,7 @@ test('new execution inputs freeze complete scenario expectations without changin
  const file=path.join(options.project,'assertions.json');fs.writeFileSync(file,JSON.stringify(assertions));
  const fresh=lib.createPrototype({...options,id:'strict',host:'codebuddy',executionPolicy:'codebuddy-ab-v1',executionAssertions:file});
  assert.equal(X.policy(fresh.directory).id,'codebuddy-ab-v1');assert.equal(lib.inspect(fresh.directory).status,'passed');
- assert.equal(X.check(fresh.directory,'delivery',lib).status,'failed');assert.throws(()=>X.requireStage(fresh.directory,'implementation',lib),/binding|execution-begin/);
+ assert.equal(X.check(fresh.directory,'delivery',lib).status,'failed');const stage=X.requireStage(fresh.directory,'implementation',lib);assert.equal(stage.status,'not-required');assert.equal(stage.auditHook,'retired');assert.equal(stage.invocationVerification,'unverified');
  assert.deepEqual(lib.manifest(legacy.directory),before);assert.deepEqual(fs.readdirSync(options.project).sort(),['assertions.json','prototypes','scope.json']);
 });
 test('missing or incomplete fixed facts cannot silently create a strict artifact or affect legacy state',t=>{

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

@@ -39,7 +39,7 @@ Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、
 | prd | BRD或等效业务依据、PBC／主题，新增主题还是修改既有主题；各PRD独立版本 |
 | ad | 准确PRD及配套、实际技术规约／契约／骨架选择的缺口；优先已有规范，原型按需并行 |
 | testcase | 准确PRD／AD、测试边界和关键预期／环境未知项；配套不一致先报告，不执行测试 |
-| plan | 清单或手动方式、本次主题／明确组合、必要规格缺口和未完计划冲突，详见[规划交接](../../references/enterprise-sop-resources/plan-handoff.md) |
+| plan | 清单或手动方式、本次主题／明确组合、必要规格缺口和未完计划冲突，详见[规划交接](references/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解析／辅助调用，不豁免共用说明、项目规则或必要业务依据；未知自改组合仍读实际选定原件。
 
@@ -55,33 +55,33 @@ AD声明的能力／主题身份与本次PRD或所选范围冲突，或直接上
 
 宿主有实际可用的结构化提问工具时使用简短问题和选项，允许用户自己说明；没有该工具、当前模式不能交互或工具不可用时，用普通会话提问并停轮等待。取消、无答复、预选、时间经过或含糊答复均不代替必要决定；等待期零项目写入，不先建占位稿、清单或采用记录。前四阶段把已有答复交原Spec，继续其真正需要的内容澄清，不能再做重复访谈或跳过原停点。plan则承接原规划的澄清，不重跑Spec。
 
-明确当前项目根、阶段／动作、工作范围、准确输入和唯一输出。多个清单或主题并存时先确定对象，不取目录最大版本。目录、命名及新项目默认见[共用合同](../../references/enterprise-sop-resources/template-contracts.md)§1；既有项目位置不自动迁移。
+明确当前项目根、阶段／动作、工作范围、准确输入和唯一输出。多个清单或主题并存时先确定对象，不取目录最大版本。目录、命名及新项目默认见[共用合同](references/template-contracts.md)§1；既有项目位置不自动迁移。
 
 纯路径登记或交接准备不生成／修订业务文档，不调用 Plan、Build 或测试。新稿起草、现稿修订、采用选择、业务认可和工程执行分别依据实际任务。
 
-任务说明本次输出目标已有稿件、该目标写入中断、登记失败、重复执行或人工修改时，先按[最小恢复规则](../../references/enterprise-sop-resources/recovery-contract.md)核现状，不把阶段名直接解释成重新 generate。只有上游 PRD 等输入已存在、目标 AD 尚未创建时，仍按明确的新建任务处理，不误判为现稿恢复。恢复默认只读评估；明确采用某份文档且允许登记时才改本次清单，明确委托修稿才另按原 Spec 执行。部分稿不自动续写或选用，已有 Plan 不因恢复改变。
+任务说明本次输出目标已有稿件、该目标写入中断、登记失败、重复执行或人工修改时，先按[最小恢复规则](references/recovery-contract.md)核现状，不把阶段名直接解释成重新 generate。只有上游 PRD 等输入已存在、目标 AD 尚未创建时，仍按明确的新建任务处理，不误判为现稿恢复。恢复默认只读评估；明确采用某份文档且允许登记时才改本次清单，明确委托修稿才另按原 Spec 执行。部分稿不自动续写或选用，已有 Plan 不因恢复改变。
 
-现稿需受控交接时采用[单次受控入口](../../references/enterprise-sop-resources/controlled-handoff.md)：调用方从本次采用记录整理准确路径，先运行 CodeBuddy 只读预检；外层核成功回执并确认本次准确选用委托后，才登记 selected；旧候选登记授权不构成选用委托。被此入口调用的只读会话只用 Read/Glob/Grep/Skill，不自行调用 shell、登记、原 Spec 或其他工程方法。缺读可在本次只读会话内补齐；拒绝、失败或选择冲突须列原因、推荐和可选操作，不能用后续成功抹去。入口不自动挂载普通会话，不改变标准流程或原版停点。
+现稿需受控交接时采用[单次受控入口](references/controlled-handoff.md)：调用方从本次采用记录整理准确路径，先运行 CodeBuddy 只读预检；外层核成功回执并确认本次准确选用委托后，才登记 selected；旧候选登记授权不构成选用委托。被此入口调用的只读会话只用 Read/Glob/Grep/Skill，不自行调用 shell、登记、原 Spec 或其他工程方法。缺读可在本次只读会话内补齐；拒绝、失败或选择冲突须列原因、推荐和可选操作，不能用后续成功抹去。入口不自动挂载普通会话，不改变标准流程或原版停点。
 
-明确要求改变同主题既有选用组合时，按[改选与影响预览](../../references/enterprise-sop-resources/selection-handoff.md)处理：先只读核当前／目标 PRD、AD、已有用例／原型的直接上游及规约、契约、骨架、Plan／任务；展示准确差异、缺口、原因、推荐与选项。未列配套沿用旧引用但必须核绑定，不能将旧 AD 静默配给新 PRD；显式解除仅移除引用、保留文件。预览后取得该组准确路径的明确选择，才可使用受控辅助更新本主题。来源变化或配套未知须重新预览，不能用模型推荐、候选登记或自动模式代替人作选择。原 Plan、任务及已完成记录不因改选自动改写。
+明确要求改变同主题既有选用组合时，按[改选与影响预览](references/selection-handoff.md)处理：先只读核当前／目标 PRD、AD、已有用例／原型的直接上游及规约、契约、骨架、Plan／任务；展示准确差异、缺口、原因、推荐与选项。未列配套沿用旧引用但必须核绑定，不能将旧 AD 静默配给新 PRD；显式解除仅移除引用、保留文件。预览后取得该组准确路径的明确选择，才可使用受控辅助更新本主题。来源变化或配套未知须重新预览，不能用模型推荐、候选登记或自动模式代替人作选择。原 Plan、任务及已完成记录不因改选自动改写。
 
 未采用的文档保留原位置，在会话中说明实际路径和未选用状态；不登记候选，也没有候选撤回操作。已选主题的撤销、业务需求取消、文件删除和功能退役仍是另有范围的任务，不因未选用某稿而自动执行。
 
 ### 2. 读取适用来源
 
-本次动作为 `plan` 时先完成§1的统一共用读取，按所选资源根的[规划交接](../../references/enterprise-sop-resources/plan-handoff.md)核读取准备、身份及上游停点，再进入原规划分支；不是只读本说明便跳过其他共用文件。JSON／手动两种输入遵守同一必读清单，不套四阶段模板／生成提示词，不生成新规格。标准原规划任务不进入本Skill，也不因清单存在而读取企业资料。
+本次动作为 `plan` 时先完成§1的统一共用读取，按所选资源根的[规划交接](references/plan-handoff.md)核读取准备、身份及上游停点，再进入原规划分支；不是只读本说明便跳过其他共用文件。JSON／手动两种输入遵守同一必读清单，不套四阶段模板／生成提示词，不生成新规格。标准原规划任务不进入本Skill，也不因清单存在而读取企业资料。
 
-本次动作是 review／recheck 时先按[统一审查约定](../../references/enterprise-sop-resources/review-handoff.md)分流：调用者定位项目采用及准确业务对象，由外层辅助解析索引、清单和依赖；不要先套下面生成／状态作业的五项共用全文读取。独立审查者仍完整读项目规则与实际采用约束、本阶段README、完整模板、唯一动作和业务原文；未知／自改组合按选定原件完整读取，不静默回退。纯引导／status／交接／恢复及生成／修订保持原读取规则。
+本次动作是 review／recheck 时先按[统一审查约定](references/review-handoff.md)分流：调用者定位项目采用及准确业务对象，由外层辅助解析索引、清单和依赖；不要先套下面生成／状态作业的五项共用全文读取。独立审查者仍完整读项目规则与实际采用约束、本阶段README、完整模板、唯一动作和业务原文；未知／自改组合按选定原件完整读取，不静默回退。纯引导／status／交接／恢复及生成／修订保持原读取规则。
 
 资料定位：本轮明确来源 → 项目已采用自改副本 → 同宿主项目安装 → 同宿主可读全局。实际读取项目规则、根说明及明确引用的采用约定；已选来源失效就报告，不静默换模板或跨宿主兜底。历史、验证样例和备份不作默认候选。
 
-CodeBuddy没有对应角色的明确项目采用根时，先定位项目 `.codebuddy/` 中本包的隐藏安装清单：显式Glob `.codebuddy/.*composer*.json`，不能用默认忽略隐藏目录的全局Glob断言不存在。实际读取name／version／scope／resources，核本包身份及当前宿主范围；多个、异名或损坏清单先报告，不当作未安装。将resources.references相对于**该清单所在目录**展开，再进入其中的enterprise-sop-resources；不是skills目录，也不是相对于项目根直接展开references字段。可先Grep精确键找行号，再Read必要范围，不全文加载assets清单。项目确实未安装时才查同宿主可读全局清单；有项目自改采用根时不先探读发行副本。其他宿主依据其真实安装清单定位，不借CodeBuddy目录兜底。
+没有对应角色的明确项目采用根时，默认资料根是**本次实际加载的 SOP Skill 目录下 references/**，从其中 README 与 stages.json 进入；工程骨架也在同一根的 engineering-skeleton/，不另借共用资料。CodeBuddy先显式Glob `.codebuddy/.*composer*.json` 定位本包隐藏安装清单，核 name／version／scope、catalog.skills 与本 Skill 的 SKILL.md、references/readme.md 两项精确 assets；可先Grep找行号再Read必要范围，不全文加载assets列表。多个安装、正文身份不符、缺登记或资料缺失时先报告，不当作未安装。resources.references继续定位原版共用资料，不能用来推导SOP专属根。项目确实未安装时才查同宿主可读全局安装，并仍从实际Skill定位；有项目自改采用根时不先探读发行副本。其他宿主按其真实安装的Skill位置定位，不借CodeBuddy目录兜底。
 
 阶段所需模板／原方法确实不可用时报告准确缺口并停下，可提示选择已有可读资料或安装；不把“无企业模板裸跑继续”列作同一次SOP作业的选项。用户另行明确改走标准流程才按原标准方法处理，不能静默降级。
 
 安装清单用于定位资料根，只读取识别所需的 name／version／scope／resources 字段；可先定位键再读取相应范围，不全文注入 assets 文件列表。业务与模板必要正文仍实际读取，不能用这种元数据裁剪替代内容核对。
 
-先读取所选资源根的 [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 指定的完整模板和本次唯一动作提示词；不按默认路径猜模板，也不加载四阶段全部资料。
+先读取所选资源根的 [README](references/readme.md)、[索引](references/stages.json)、[共用合同](references/template-contracts.md)、[交接合同](references/handoff-contract.md)和[生命周期合同](references/lifecycle-contract.md)。实际起草／审查时，再读索引指定的本阶段 README、manifest，以及该 manifest 指定的完整模板和本次唯一动作提示词；不按默认路径猜模板，也不加载四阶段全部资料。
 
 明确企业 status、只读交接与恢复也须完成上述五项共用读取；它们不需要生成模板和 Spec，不等于可以跳过共用合同。安装清单实际用于定位时，逐项确认 name、version、scope、resources.references 的真实值；只搜索资产列表里的资源名称不算完成身份核对。列出实际路径及读取结果，缺项先补读或保留未通过，不以“已自动注入”代替回执，也不把后来补读追认为旧作业写前已读。
 
@@ -93,7 +93,7 @@ CodeBuddy没有对应角色的明确项目采用根时，先定位项目 `.codeb
 
 起草或修订 BRD／PRD／AD／TestCase 时，必须先调用原 [i3-spec-driven-development](../i3-spec-driven-development/SKILL.md) Skill，再按本次明确的企业任务、模板和唯一输出执行；不是让 using 判断是否需要 Spec，也不调用会默认保存根 SPEC.md 的 `/i3-spec` 包装来替代它。原 Spec 支持外部规格格式与存储；内容要求、澄清、权限、认可及结束轮次完整保留，真实冲突先报告，不改原版或另造影子 SPEC。
 
-`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。
+`plan` 必须按[规划交接](references/plan-handoff.md)实际调用原 [i3-planning-and-task-breakdown](../i3-planning-and-task-breakdown/SKILL.md)，读取并履行本宿主当前原 `/i3-plan` 命令合同。不是只输出提示词让用户再粘贴，不以提及名称或自行写计划代替成功加载；没有正式加载机制或调用失败时停止说明。Skill加载与命令转交分别记录，不声称等价执行另一个slash命令。此分支不调用Spec、不改业务稿／JSON、不进入Build。
 
 宿主提供 Skill 工具时须取得加载原 Spec 的成功回执，继续读取其本次适用正文；只在计划里写 Skill 名称、读取索引或自行声称已调用不算。原生没有该工具的宿主使用其正式技能加载机制并保留可核记录；方法不可用就说明缺口，不裸跑写稿。按任务另用适用专业方法，不造第二张全局路由表。纯引导、状态、只读审查和已有文件的路径登记不调用规格生成。
 
@@ -103,7 +103,7 @@ AD 的直接产品依据是选定 PRD。公共技术规约优先复用项目已
 
 ### 4. 最小路径交接
 
-使用所选发行资料根的 [handoff.py](../../references/enterprise-sop-resources/handoff.py)；项目采用副本只有明确包含兼容辅助工具时才改用该工具。Python 3.9+ 为此辅助的运行条件；没有可用解释器时保留手动路径方式，不安装依赖或改项目环境。
+使用所选发行资料根的 [handoff.py](references/handoff.py)；项目采用副本只有明确包含兼容辅助工具时才改用该工具。Python 3.9+ 为此辅助的运行条件；没有可用解释器时保留手动路径方式，不安装依赖或改项目环境。
 
 先执行工具 `--help` 核接口。以下是工具操作，不是新增顶级命令；`<资料根>`与项目路径均须用实际位置替换。
 
@@ -131,17 +131,17 @@ python3 <资料根>/handoff.py resolve --project-root <项目根> --work <工作
 
 引导、status、review、recheck 零项目写入。审查只给问题、原文位置、来源、影响和建议；作者会话不冒充独立审查，报告另存由获准调用者处理。
 
-review／recheck共用外层解析／模型正文读取规则，按[独立只读审查衔接](../../references/enterprise-sop-resources/review-handoff.md)执行。当前作者会话有获准且已验证的CLI隔离能力时，由外层调用者整理本次所选资料、准确目标和真实来源，使用该资料根的verification/review_handoff.py启动新的只读会话；辅助不在审查者内部执行，不调用原Spec、Plan或原代码review，不串行修稿。复查绑定旧稿、原报告及逐项人工回应，仍使用新上下文。没有隔离机制则给出可复制的新会话任务并结束；已在新会话也须如实说明实际权限证据，不能自称清除了上下文。证据检查通过仅接受本轮报告，业务问题及人工处理空间保留。
+review／recheck共用外层解析／模型正文读取规则，按[独立只读审查衔接](references/review-handoff.md)执行。当前作者会话有获准且已验证的CLI隔离能力时，由外层调用者整理本次所选资料、准确目标和真实来源，使用该资料根的verification/review_handoff.py启动新的只读会话；辅助不在审查者内部执行，不调用原Spec、Plan或原代码review，不串行修稿。复查绑定旧稿、原报告及逐项人工回应，仍使用新上下文。没有隔离机制则给出可复制的新会话任务并结束；已在新会话也须如实说明实际权限证据，不能自称清除了上下文。证据检查通过仅接受本轮报告，业务问题及人工处理空间保留。
 
 ### 6. 交原 Plan 与 Build
 
-用户显式调用 `/i3-sop plan` 或本Skill的plan动作时，本Skill读取所选清单／明确手动路径，按[规划交接](../../references/enterprise-sop-resources/plan-handoff.md)组织原文输入并实际复用原规划。只生成原计划与唯一任务目标，完整回读并交人工审阅后停轮。四阶段文档作业仍不自动进入该动作；原 `/i3-plan` 加明确企业任务的手动方式保留。
+用户显式调用 `/i3-sop plan` 或本Skill的plan动作时，本Skill读取所选清单／明确手动路径，按[规划交接](references/plan-handoff.md)组织原文输入并实际复用原规划。只生成原计划与唯一任务目标，完整回读并交人工审阅后停轮。四阶段文档作业仍不自动进入该动作；原 `/i3-plan` 加明确企业任务的手动方式保留。
 
 Plan内的来源表逐项记录实际使用的PRD、AD、规范、契约、工程采用说明的完整项目相对路径（明确外部来源则绝对路径）及其文档版本，不只写AD_v…、契约简称或JSON位置。保存后将来源表与本次实际读取集合逐项对照，缺项先补齐Plan并再次全文回读，再交审；不修改来源业务稿或JSON。
 
 新项目默认将业务文档存于 `spec/{能力}/`。工程规划入口是本次选定 AD 及其明确引用的 PRD、已采用规范、共享契约、真实骨架与相关代码；在入口及已选集合内逐项回读 SPEC 六项。BRD、空链接、JSON、只有文件落在 spec/ 均不证明工程规格齐备。不复制第五份核心 SPEC，不改 JSON schema 或强制业务 hash。
 
-按[交接合同](../../references/enterprise-sop-resources/handoff-contract.md)§10准备原 `/i3-plan` 的实际输入。有明确采用指引可据其读取唯一范围；没有指引就手动列准确路径。原 Plan 不天然读写 JSON，多个主题／版本没有选择时先问，不猜。计划保留实际来源、主题、FR／AC、共享依赖和验证依据，仍输出原 `tasks/plan.md` 与唯一任务目标，不覆盖其他工作未完计划。
+按[交接合同](references/handoff-contract.md)§10准备原 `/i3-plan` 的实际输入。有明确采用指引可据其读取唯一范围；没有指引就手动列准确路径。原 Plan 不天然读写 JSON，多个主题／版本没有选择时先问，不猜。计划保留实际来源、主题、FR／AC、共享依赖和验证依据，仍输出原 `tasks/plan.md` 与唯一任务目标，不覆盖其他工作未完计划。
 
 随后由用户审阅并明确批准计划，才调用原 `/i3-build` 或 `/i3-build auto`。原 Build auto 的有效规格、Git 干净基线、完整计划认可、逐任务测试／构建／提交和风险停点全保留；未提交的 `.i3/sop`、项目指引等可能触发原 Git 停点，不隐藏、不擅自提交业务文件规避。企业跨阶段 auto 与原 Build auto 是不同功能。
 
@@ -170,4 +170,4 @@ Plan内的来源表逐项记录实际使用的PRD、AD、规范、契约、工
 - 实际所读输入、模板／工具来源、主题与输出可定位；缺项和未核内容准确列出。
 - 新稿只展示路径，明确选用才更新 selected；写后已回读清单，旧稿及人工修改保留。
 - 纯手动路径交接及只读任务零项目变化；显式plan的手动输入只允许原规划产物，标准流程不误用企业资料。
-- 按[共用交接合同§9](../../references/enterprise-sop-resources/handoff-contract.md#9-真实调用与执行报告)报告真实尝试及回执；占位说明不用工具，拒绝／失败不漏报。需外层执行复核时附约定的最小报告块，不声称新命令、全流程、工程或发布已验收。
+- 按[共用交接合同§9](references/handoff-contract.md#9-真实调用与执行报告)报告真实尝试及回执；占位说明不用工具，拒绝／失败不漏报。需外层执行复核时附约定的最小报告块，不声称新命令、全流程、工程或发布已验收。

package/{references/enterprise-sop-resources → skills/i3-enterprise-sop/references}/ad/assets-manifest.json

@@ -6,8 +6,8 @@
   "stage": "ad",
   "documentType": "AD",
   "source": {
-    "path": "references/i3-enterprise-sop/ad/templates/AD.md",
-    "resourcePath": "templates/AD.md",
+    "path": "skills/i3-enterprise-sop/references/ad/templates/ad.md",
+    "resourcePath": "templates/ad.md",
     "templateVersion": "v0.0.4",
     "sha256": "0e48c7149792aede3b5c7be70b65b7e4f9b312889760f2fb4105d184162abeae",
     "role": "complete-document-template",
@@ -38,9 +38,9 @@
   ],
   "files": [
     {
-      "path": "README.md",
-      "sourceSha256": "eb4c075d6ba4f8ed8fcdd0e42fddfbc1326ca1a8ffb7dd702701cf6f9d82459e",
-      "sha256": "71191b896caf41ee775fdf85327e2a9f56c759248551507a3e5473a7270a4a6e",
+      "path": "readme.md",
+      "sourceSha256": "70b8e0b39b3e8c2ee6f1123fd0f57a10d9848c697ab43240970414b7f79a0246",
+      "sha256": "0052fe43876055749d6988f9ad246c08bdfa3929985bcb53cc9d89e063ba0056",
       "role": "stage-guidance"
     },
     {
@@ -68,39 +68,19 @@
       "role": "stage-action-guidance"
     },
     {
-      "path": "templates/AD.md",
+      "path": "templates/ad.md",
       "sourceSha256": "0e48c7149792aede3b5c7be70b65b7e4f9b312889760f2fb4105d184162abeae",
       "sha256": "37d3f77efe23b85ebaf50cfad09d92344227d4f778ea7e965c4fea70d89817bb",
       "role": "complete-document-template"
     }
   ],
-  "derivedFrom": {
-    "path": "docs/sop-design/templates/AD.md",
-    "templateVersion": "v0.0.2",
-    "sha256": "215a570d4c9310752edebfe7022d423855086f769db0b6bdef29d055f35caea5",
-    "included": false,
-    "role": "maintenance-provenance-only-not-runtime-dependency",
-    "changes": [
-      "distribution title",
-      "template version and status",
-      "package-contained shared-contract link"
-    ]
-  },
   "projectDiscovery": {
-    "entryRelativeToReferences": "enterprise-sop-resources/README.md",
+    "entryRelativeToReferences": "readme.md",
     "stagesRelativeToEntry": "stages.json",
-    "ordinaryInstallEnablesEnterpriseWorkflow": false
+    "ordinaryInstallEnablesEnterpriseWorkflow": false,
+    "resourceRoot": "actual-loaded-sop-skill/references"
   },
   "revision": "20261018-B02",
   "revisionScope": "AD linkage content and four task prompts; no original skill/command or auto-registration change",
-  "revisionProvenance": [
-    {
-      "path": "history/sop-design/20261018-before-b02-ad-linkage/branches/prd-sop-resources-source/references/i3-enterprise-sop/ad/templates/AD.md",
-      "templateVersion": "v0.0.3",
-      "sha256": "63e30a247f9172c4b15bc48da0c6e71a4df849b7b387652cb33f23761d08a6d2",
-      "included": false,
-      "role": "immutable-maintenance-provenance-not-runtime-dependency"
-    }
-  ],
   "validationBoundary": "distribution hashes are computed using existing pure reference mapping; no npm build, installation, new entry or engineering claim"
 }

package/{references/enterprise-sop-resources/ad/README.md → skills/i3-enterprise-sop/references/ad/readme.md}

@@ -12,9 +12,9 @@
 
 审查加载分支：review／recheck完整读取本README、完整模板、唯一动作、实际业务与采用约束，依[统一审查约定](../review-handoff.md)由外层解析元数据并保留变化核对。下文涉及整套共用文件的加载要求在这两个动作按该分支理解；未知自改组合完整读选定原件，其余作业及实质条款保持。
 
-前版子包版本：0.3.2；模板内容版本：v0.0.4。状态：本地候选，尚未发布。完整[模板](templates/AD.md)和[共用合同](../template-contracts.md)用于明确任务，不新增Skill／命令／自动调度，原方法内容／工具／认可／停轮保留。
+前版子包版本：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／前端等方法；实际原生调用和读取分别取证。
+从[入口](../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. 本阶段输入与内容
 
@@ -61,10 +61,10 @@ review／recheck在独立新上下文只读会话输出，审查者零项目写
 
 ## B05 变更交接规则
 
-B05当时资源子包0.3.0；本次增量见收口说明，模板正文和版本保持。按[入口](../README.md)§3列本次必要读取，实际读三份共用合同及本次唯一动作；[生命周期合同](../lifecycle-contract.md)统一新增、修改、撤销和退役，不新增命令、JSON程序或工程执行器。
+B05当时资源子包0.3.0；本次增量见收口说明，模板正文和版本保持。按[入口](../readme.md)§3列本次必要读取，实际读三份共用合同及本次唯一动作；[生命周期合同](../lifecycle-contract.md)统一新增、修改、撤销和退役，不新增命令、JSON程序或工程执行器。
 
 完整三图和详设继续保留；核所选PRD、公共规约、共享契约／数据owner、必要消费者、实际骨架、移除／兼容／迁移／恢复和工程任务影响。原方法停点、只读审查与人工空间、候选／选择／Plan边界保留，项目副本升级不覆盖人工内容。
 
 ## B05收口资源增量
 
-B05当时子包0.3.1，模板正文及版本不改。统一修订全文回读措辞、适用来源和单项目审查证据；外层校验见[说明](../verification/README.md)。不把辅助资料／Plan统一变前置，不自动改业务稿、JSON、任务或原版方法。旧验证与历史版本按当时对象保留。
+B05当时子包0.3.1，模板正文及版本不改。统一修订全文回读措辞、适用来源和单项目审查证据；外层校验见[说明](../verification/readme.md)。不把辅助资料／Plan统一变前置，不自动改业务稿、JSON、任务或原版方法。旧验证与历史版本按当时对象保留。