@givolt/i3-composer-agent 2.3.2 → 2.3.3

package/skills/i3-ui-prototype/scripts/native-pilot-lib.cjs

@@ -4,6 +4,7 @@ const {fs,path,crypto,assert,hash,json,id,inside,walk,write,entries,excluded}=F;
 const skillRoot=path.resolve(__dirname,'..');
 const frameworkRoot=path.join(skillRoot,'assets/frameworks/vue-antdv-next');
 const templates=()=>require('./template-contract.cjs');
+const projectRegistry=require('./project-registry.cjs');
 function metadata(directory) { const data=json(inside(directory,'prototype.json')); assert.equal(data.schemaVersion,2,'Not a native v2 prototype'); assert.equal(data.runtime.kind,'vue-antdv-next'); return data; }
 function effectiveReview(data,current) {
   const review=data.review;
@@ -32,6 +33,9 @@ function defaultScope() {
   ],exemptions:[],openQuestions:[]};
 }
 function createPrototype(options) {
+  const installedFile=path.resolve(__dirname,'../../../.i3-composer-agent.json');
+  if(fs.existsSync(installedFile))options=require('./execution-policy.cjs').creationOptions(options,json(installedFile));
+  if(options.executionPolicy!==undefined){assert.equal(options.executionPolicy,require('./execution-policy.cjs').ID,'Unsupported execution policy');assert.equal(options.host,'codebuddy','Explicit CodeBuddy host required for A+B');}
   assert.ok(options.framework===undefined||options.framework==='vue-antdv-next','Unsupported framework / 不支持的框架');
   assert.ok(options.title===undefined||(typeof options.title==='string'&&options.title.trim()),'Title must be a nonempty string');
   const project=path.resolve(options.project||'.'); assert.ok(fs.statSync(project).isDirectory(),'Project must exist'); id(options.id);
@@ -41,24 +45,29 @@ function createPrototype(options) {
     provider=require('./prototype-lib.cjs').checkDesignProvider({...options,project});
     if(provider.availability!=='available') return {status:'needs-design-provider',provider,sideEffects:[],choices:['locate-or-repair','explicit-template-mode','analyze']};
   }
-  const template=options.templateRoot?templates().loadTemplate(path.resolve(options.templateRoot)):templates().loadBundledTemplate();
+  assert.ok(!(options.templateRoot && options.template), 'Choose a template ID or an explicit template root');
+  const template=options.templateRoot?templates().loadTemplate(path.resolve(options.templateRoot)):templates().loadBundledTemplate(options.template);
   const reference=template.kind==='content-reference';
   assert.ok(!reference||options.scope,'A sourced scope file is required for business generation; no default device demo');
   const scope=options.scope?json(path.resolve(options.scope)):defaultScope();
+  const appliesTo=projectRegistry.moduleIds(scope);
   const selection=reference?require('./content-template.cjs').scopeInputs(template,scope,templates()):null;
+  const generation=scope.schemaVersion===3?require('./generation-contract.cjs').compile(template,scope):null;
   const content=reference?{pageTitle:scope.title||'业务原型'}:templates().projectAdminListContent(template);
   if(options.title!==undefined)content.pageTitle=options.title;
   const profile=json(path.join(frameworkRoot,'profile.json'));
   const target=inside(project,`prototypes/${options.id}`); assert.ok(!fs.existsSync(target),'Prototype exists; revise without reinitializing');
-  const lockFile=inside(project,'.i3-ui-prototypes.lock'); const lock=fs.openSync(lockFile,'wx');
+  return projectRegistry.transaction(project,store=>{
   let stage=null,published=false;
   try {
     fs.mkdirSync(path.dirname(target),{recursive:true}); stage=fs.mkdtempSync(path.join(path.dirname(target),'.native-'));
-    const registryPath=inside(project,'.i3-ui-prototypes.json'); const registry=fs.existsSync(registryPath)?json(registryPath):{schemaVersion:1,prototypes:[]};
+    const registry=store.registry;
     assert.equal(registry.schemaVersion,1); assert.ok(Array.isArray(registry.prototypes)); assert.ok(!registry.prototypes.some(p=>p.id===options.id),'Duplicate prototype ID');
     const frameworkFiles=entries(frameworkRoot,walk(frameworkRoot,'',excluded));
     const instanceId=crypto.randomUUID();
     const data={schemaVersion:2,id:options.id,title:options.title||content.pageTitle||'设备清单原型',revision:'r001',artifactKind:'framework-prototype',runtime:{kind:'vue-antdv-next',version:'1',...(reference?{contentReference:true}:{})},...(reference?{business:{status:'needs-adaptation',source:'inputs/scope.json'}}:{}),template:{id:template.id,version:template.version,digest:template.digest},framework:{id:'vue-antdv-next',version:profile.version||'1',digest:hash(JSON.stringify(frameworkFiles))},expertMode:mode,expert:{status:provider?'pending':'skipped',provider},verification:{status:'not-run'},review:{status:'pending-review'},instanceId};
+    if(generation)data.runtime.generationContract=1;
+    if(options.executionPolicy){data.runtime.executionPolicy=options.executionPolicy;write(stage,'inputs/execution-policy.json',require('./execution-policy.cjs').create({host:options.host,mode,officialCallable:!options.officialSourceFallback}));}
     write(stage,'prototype.json',data);
     for(const file of template.files) {
       assert.equal(file.encoding,'base64');
@@ -66,28 +75,35 @@ function createPrototype(options) {
     }
     write(stage,'inputs/template-snapshot.json',template);
     write(stage,'inputs/scope.json',scope);
+    if(generation)write(stage,'inputs/generation.json',generation);
     write(stage,'inputs/capabilities.json',selection?selection.fixed:{schemaVersion:1,definition:template.definition,bindings:template.index.bindings,regions:template.index.regions,decisions:[]});
-    write(stage,'inputs/framework.json',{profile,componentMap:json(path.join(frameworkRoot,'component-map.json')),acceptance:json(path.join(frameworkRoot,'acceptance.json')),files:frameworkFiles});
+    write(stage,'inputs/framework.json',{profile,componentMap:generation?require('./generation-evidence.cjs').framework():json(path.join(frameworkRoot,'component-map.json')),acceptance:json(path.join(frameworkRoot,'acceptance.json')),files:frameworkFiles});
     const checked=templates().checkInstanceCapabilities(path.join(stage,'inputs')); assert.equal(checked.status,'passed',checked.errors?.join('; '));
-    const requiredScenarios=checked.requiredScenarios.map(s=>typeof s==='string'?s:s.id);
-    write(stage,'inputs/acceptance.json',{schemaVersion:1,requiredScenarios,scenarioDetails:checked.requiredScenarios,frameworkScenarios:reference?['framework-responsive','framework-instance-isolation','template-content-projection',...(selection.fixed.regions.some(region=>region.mode==='edit-form')?['framework-drawer-motion','framework-mask-blur','framework-focus-scroll']:[])]:['framework-drawer-motion','framework-mask-blur','framework-focus-scroll','framework-states','framework-responsive','framework-instance-isolation','template-content-projection'],browserReview:json(path.join(frameworkRoot,'acceptance.json')).browserReview});
+    const scenarioDetails=[...checked.requiredScenarios,...(generation?.scenarios||[])],requiredScenarios=scenarioDetails.map(s=>typeof s==='string'?s:s.id);
+    const hasDrawer=reference&&(selection.fixed.regions.some(region=>region.mode==='edit-form')||generation?.bindings.some(binding=>binding.capabilityId==='dialog'&&binding.parameters.presentation==='drawer'));
+    write(stage,'inputs/acceptance.json',{schemaVersion:1,requiredScenarios,scenarioDetails,frameworkScenarios:reference?['framework-responsive','framework-instance-isolation','template-content-projection',...(hasDrawer?['framework-drawer-motion','framework-mask-blur','framework-focus-scroll']:[])]:['framework-drawer-motion','framework-mask-blur','framework-focus-scroll','framework-states','framework-responsive','framework-instance-isolation','template-content-projection'],browserReview:json(path.join(frameworkRoot,'acceptance.json')).browserReview});
+    if(options.executionPolicy){const all=json(inside(stage,'inputs/acceptance.json'));assert.ok(options.executionAssertions,`Strict policy requires --execution-assertions with fixed expected JSON facts for: ${[...all.requiredScenarios,...all.frameworkScenarios].join(', ')}`);const fixed=require('./execution-assertions.cjs').validate(json(path.resolve(options.executionAssertions)),[...all.requiredScenarios,...all.frameworkScenarios]);write(stage,'inputs/execution-assertions.json',fixed);}
     const requirements=json(path.join(stage,'inputs/scope.json')).requirements;
-    write(stage,'requirements-map.json',{schemaVersion:2,requirements:requirements.map(r=>({...r,pages:reference?r.pages:template.index.pages.map(page=>page.id),scenarios:reference?checked.requiredScenarios.filter(s=>s.bindingId.startsWith('app-shell/')||r.pages.some(page=>s.bindingId.startsWith(page+'/'))).map(s=>s.id):requiredScenarios})),bindings:selection?selection.fixed.bindings:template.index.bindings});
+    write(stage,'requirements-map.json',{schemaVersion:2,requirements:requirements.map(r=>({...r,pages:reference?r.pages:template.index.pages.map(page=>page.id),scenarios:reference?scenarioDetails.filter(s=>s.bindingId.startsWith('app-shell/')||r.pages.some(page=>s.bindingId.startsWith(page+'/'))).map(s=>s.id):requiredScenarios})),bindings:[...(selection?selection.fixed.bindings:template.index.bindings),...(generation?.bindings||[])]});
     const starter=path.join(frameworkRoot,reference?profile.starter:(profile.legacyStarter||profile.starter));
     fs.cpSync(starter,path.join(stage,'app'),{recursive:true,filter:file=>!excluded(`starter/${path.relative(starter,file).split(path.sep).join('/')}`,path.basename(file))});
     const themeBinding=(selection?selection.fixed.bindings:template.index.bindings).find(binding=>binding.capabilityId==='theme');
-    write(stage,'app/public/prototype-config.json',{instanceId,storageNamespace:`i3-native-${options.id}-${instanceId}`,mockVersion:reference?'business-v1':'admin-list-v1',title:data.title,...(reference?{pages:scope.pages.map(page=>({id:page.id,title:page.title}))}:{content}),...(themeBinding?{theme:templates().resolveThemeParameters(themeBinding.parameters)}:{})});
+    write(stage,'app/public/prototype-config.json',{instanceId,storageNamespace:`i3-native-${options.id}-${instanceId}`,mockVersion:reference?'business-v1':'admin-list-v1',title:data.title,...(reference?{pages:scope.pages.map(page=>({id:page.id,title:page.title}))}:{content}),...(generation?{presentation:generation.presentation,navigation:generation.navigation,generation:{pages:generation.pages}}:{}),...(themeBinding?{theme:templates().resolveThemeParameters(themeBinding.parameters)}:{})});
     write(stage,'mocks/contract.json',reference?{schemaVersion:1,instanceId,status:'needs-business-data',requirements:scope.requirements.map(r=>r.id)}:{schemaVersion:1,seed:'admin-list-v1',count:21,pageSize:10,selection:'current-page-clear-on-page-or-filter',instanceId});
     write(stage,'design-system/MASTER.md',`# ${data.title}\n\n使用 antDv-next 原生组件与主题。管理列表采用紧凑信息层级，正文与操作可读；错误在字段附近呈现。抽屉保留进入与退出过程，显式开启遮罩模糊。\n\n本地模拟，不代表生产权限。\n`);
+    if(generation)write(stage,'design-system/MASTER.md',require('./generation-evidence.cjs').designSummary(generation,`# ${data.title}\n\nPrototypeShell 提供已选原生外壳；按逐区域／字段／操作合同实现业务，补齐真实源码映射和浏览器证据。骨架不是业务完成。本地模拟不代表生产权限。`));
+    if(generation)write(stage,'design-system/implementation.json',require('./generation-evidence.cjs').initialize(generation));
     write(stage,'design-system/decisions.json',{schemaVersion:1,records:[],reviewStatus:mode==='template'?'skipped':'pending'});
     write(stage,'qa/design-advice.json',{schemaVersion:2,provider,queries:[],records:[],status:mode==='template'?'skipped':'pending'});
     write(stage,'HANDOFF.md',`# ${data.title}\n\n本次为 ${mode} 模式；来源 ${template.id} ${template.version}。运行形态为真实 Vue＋antDv-next。读取 inputs 中固定合同和实际源码，勿从安装目录更新旧合同。\n\n使用 native-pilot.cjs inspect／build／preview。当前未验证，待用户评审；不要把检查通过当用户认可。\n`);
     const candidate=manifest(stage); data.inputs={digest:candidate.inputDigest}; write(stage,'prototype.json',data);
     fs.renameSync(stage,target); published=true;
-    registry.prototypes.push({id:options.id,directory:`prototypes/${options.id}`,appliesTo:[],schemaVersion:2}); write(project,'.i3-ui-prototypes.json',registry);
-    return {status:'created',directory:target,revision:'r001',digest:manifest(target).digest};
+    const digest=manifest(target).digest;
+    registry.prototypes.push({id:options.id,directory:`prototypes/${options.id}`,appliesTo,schemaVersion:2}); store.save();
+    return {status:'created',directory:target,revision:'r001',digest};
   } catch(error) { if(published) fs.rmSync(target,{recursive:true,force:true}); throw error; }
-  finally { if(stage&&fs.existsSync(stage)) fs.rmSync(stage,{recursive:true,force:true}); fs.closeSync(lock); fs.unlinkSync(lockFile); }
+  finally { if(stage&&fs.existsSync(stage)) fs.rmSync(stage,{recursive:true,force:true}); }
+  });
 }
 function inspectDesignReview(directory,current=manifest(directory)) {
   const data=metadata(directory);
@@ -112,12 +128,16 @@ function inspectWithInputs(directory,options={},acceptedInputDigest) {
     assert.equal(acceptedInputDigest??data.inputs.digest,current.inputDigest,'Input contract changed; explicitly revise fixed inputs');
     const capability=templates().checkInstanceCapabilities(path.join(directory,'inputs')); assert.equal(capability.status,'passed',capability.errors?.join('; '));
     const acceptance=json(inside(directory,'inputs/acceptance.json'));
+    require('./execution-runtime.cjs').policy(directory);
     require('./native-devtools.cjs').readPolicy(directory);
     for(const scenario of capability.requiredScenarios.map(s=>typeof s==='string'?s:s.id)) assert.ok(acceptance.requiredScenarios.includes(scenario),`Required scenario omitted: ${scenario}`);
     const fixedFramework=json(inside(directory,'inputs/framework.json'));
     if(fixedFramework.acceptance?.scenarios?.some(scenario=>scenario.id==='template-content-projection'&&scenario.required))assert.ok(acceptance.frameworkScenarios.includes('template-content-projection'),'Required template-content-projection scenario omitted from fixed framework acceptance');
     const template=json(inside(directory,'inputs/template-snapshot.json')),mapping=json(inside(directory,'requirements-map.json')),scope=json(inside(directory,'inputs/scope.json'));
-    const pageIds=new Set(data.runtime.contentReference?['app-shell',...scope.pages.map(page=>page.id)]:template.index.pages.map(page=>page.id)),bindingIds=new Set(json(inside(directory,'inputs/capabilities.json')).bindings.map(binding=>binding.id));
+    const generation=scope.schemaVersion===3?json(inside(directory,'inputs/generation.json')):null;
+    if(generation){assert.equal(data.runtime.generationContract,1,'Generation runtime identity is required');require('./generation-contract.cjs').verify(template,scope,generation);for(const scenario of generation.scenarios)assert.ok(acceptance.requiredScenarios.includes(scenario.id),`Generation scenario omitted: ${scenario.id}`);}
+    projectRegistry.moduleIds(scope);
+    const pageIds=new Set(data.runtime.contentReference?['app-shell',...scope.pages.map(page=>page.id)]:template.index.pages.map(page=>page.id)),bindingIds=new Set([...json(inside(directory,'inputs/capabilities.json')).bindings,...(generation?.bindings||[])].map(binding=>binding.id));
     for(const requirement of scope.requirements)assert.ok(mapping.requirements.some(item=>item.id===requirement.id),`Requirement omitted from mapping: ${requirement.id}`);
     for(const requirement of mapping.requirements) {
       assert.ok(scope.requirements.some(item=>item.id===requirement.id),`Unknown mapped requirement: ${requirement.id}`);
@@ -131,14 +151,17 @@ function inspectWithInputs(directory,options={},acceptedInputDigest) {
     if(data.runtime.contentReference) {
       assert.deepEqual(config.pages,scope.pages.map(page=>({id:page.id,title:page.title})),'Business configuration differs from fixed page scope');
       assert.ok(['needs-adaptation','adapted'].includes(data.business?.status),'Unknown business implementation status');
-      const fixedBindings=json(inside(directory,'inputs/capabilities.json')).bindings;
+      const fixedBindings=[...json(inside(directory,'inputs/capabilities.json')).bindings,...(generation?.bindings||[])];
       assert.deepEqual((mapping.bindings||[]).map(binding=>binding.id).sort(),fixedBindings.map(binding=>binding.id).sort(),'Business mapping omits fixed capabilities');
     }
     const themeBinding=json(inside(directory,'inputs/capabilities.json')).bindings.find(binding=>data.runtime.contentReference?binding.capabilityId==='theme':binding.id==='devices/device-list/theme');
     if(themeBinding)assert.deepEqual(config.theme,templates().resolveThemeParameters(themeBinding.parameters),'Theme configuration differs from fixed input binding');
     else assert.equal(config.theme,undefined,'Theme requires an explicit optional capability binding');
+    if(generation){assert.deepEqual(config.presentation,generation.presentation,'Customer presentation differs from fixed choices');assert.deepEqual(config.navigation,generation.navigation,'Navigation differs from fixed generation');assert.deepEqual(config.generation,{pages:generation.pages},'Business page patterns differ from fixed generation');}
     const deps=json(inside(directory,'app/package.json')).dependencies; assert.ok(deps['antdv-next'] && deps.vue,'Native framework dependencies missing');
+    if(generation)require('./generation-evidence.cjs').validateImplementation(directory,generation,json(inside(directory,'design-system/implementation.json')),{complete:!!options.acceptance,frameworkMap:fixedFramework.componentMap});
     if(options.acceptance) {
+      if(generation){assert.equal(generation.pendingDecisions.length,0,'Reference applicability decisions remain unresolved');assert.equal(generation.pendingReferenceElements.length,0,'Reference functional elements remain unaccounted for');}
       if(data.runtime.contentReference)assert.equal(data.business?.status,'adapted','Business implementation pending; a scaffold cannot pass acceptance');
       const adoptedAdvice=inspectDesignReview(directory,current).adoptedAdvice;
       const report=options.report||json(inside(directory,json(inside(directory,'qa/latest.json')).report));
@@ -149,7 +172,9 @@ function inspectWithInputs(directory,options={},acceptedInputDigest) {
       assert.deepEqual(report.consoleErrors,[],'Browser errors remain');
       const required=[...acceptance.requiredScenarios,...acceptance.frameworkScenarios];
       for(const scenario of required) assert.ok(report.journeys.some(j=>j.id===scenario && j.status==='passed'),`Missing browser scenario: ${scenario}`);
+      if(generation)require('./generation-evidence.cjs').validateObservations(directory,generation,report);
       for(const record of adoptedAdvice)assert.ok(report.journeys.some(j=>j.id===record.verificationScenario && j.status==='passed'),`Advice verification missing: ${record.resultIdentity}`);
+      require('./execution-runtime.cjs').requireStage(directory,'delivery',module.exports,{businessReport:report});
     }
     return {status:'passed',level:options.acceptance?'acceptance':'structure',revision:current.revision,digest:current.digest,verification:data.verification.status,review:effectiveReview(data,current).status};
   } catch(error) { return {status:'failed',errors:[error.message]}; }
@@ -186,12 +211,35 @@ function revise(directory,options) {
       assert.equal(checked.status,'passed',checked.errors?.join('; '));
     } else assert.equal(data.inputs.digest,current.inputDigest,'Input contract changed; revise --accept-inputs must explicitly validate the new contract');
     assert.equal(manifest(directory).digest,current.digest,'Candidate changed while validating fixed inputs');
-    if(options.acceptInputs)data.inputs={digest:current.inputDigest};
-    data.revision=options.revision; data.verification={status:'not-run'}; data.review={status:'pending-review'};
-    write(directory,'prototype.json',data); return manifest(directory);
+    const scope=json(inside(directory,'inputs/scope.json')); projectRegistry.moduleIds(scope);
+    return projectRegistry.withInstanceAssociation(directory,scope,()=>{
+      if(options.acceptInputs)data.inputs={digest:current.inputDigest};
+      data.revision=options.revision; data.verification={status:'not-run'}; data.review={status:'pending-review'};
+      write(directory,'prototype.json',data); return manifest(directory);
+    });
+  });
+}
+function replan(directory,options) { const owner=options.owner||`replan-${crypto.randomUUID()}`;return mutate(directory,{...options,owner},()=>require('./generation-replan.cjs').run(directory,{...options,owner},module.exports)); }
+function build(directory,options={}) { const gates=require('./execution-runtime.cjs');gates.requireStage(directory,'implementation',module.exports);gates.requireStage(directory,'design',module.exports);return require('./native-build.cjs').build(directory,options,{manifest,inspect}); }
+function synchronizeIndex(options={}) {
+  id(options.id);
+  const index=projectRegistry.read(options.project),entry=index.registry.prototypes.find(item=>item.id===options.id);
+  assert.ok(entry,'Prototype is not registered');
+  const directory=inside(index.project,entry.directory),scope=json(inside(directory,'inputs/scope.json'));
+  assert.ok(scope.moduleIds!==undefined||scope.schemaVersion===2,'Legacy scope has no explicit moduleIds; do not invent or rewrite old input contracts');
+  const current=manifest(directory);
+  return mutate(directory,{...options,expectedRevision:current.revision,expectedDigest:current.digest},()=>{
+    const checked=inspect(directory);assert.equal(checked.status,'passed',checked.errors?.join('; '));
+    return projectRegistry.transaction(index.project,store=>{
+      const selected=store.registry.prototypes.find(item=>item.id===options.id);
+      assert.ok(selected&&selected.directory===entry.directory,'Prototype index entry changed during synchronization');
+      const fixed=json(inside(directory,'inputs/scope.json')),appliesTo=projectRegistry.moduleIds(fixed);
+      assert.equal(manifest(directory).digest,current.digest,'Candidate changed during synchronization');
+      selected.appliesTo=appliesTo;store.save();
+      return {status:'synchronized',index:store.file,id:selected.id,appliesTo};
+    });
   });
 }
-function build(directory,options={}) { return require('./native-build.cjs').build(directory,options,{manifest,inspect}); }
 function verifyBuild(directory,buildId) { return require('./native-build.cjs').verifyBuild(directory,buildId,{manifest}); }
 function preview(directory,options={}) { return require('./native-build.cjs').preview(directory,options,{manifest}); }
 function recordRun(directory,report) {
@@ -241,4 +289,4 @@ function compareBaseline(directory) {
 }
 function state(directory,options={}) { return require('./native-delivery.cjs').state(directory,options,module.exports); }
 function finalize(directory,options={}) { return require('./native-delivery.cjs').finalize(directory,options,module.exports); }
-module.exports={analyze,prepareTemplate,createPrototype,manifest,inspect,inspectDesignReview,effectiveReview,claim,release,revise,build,verifyBuild,preview,recordRun,confirmBaseline,compareBaseline,state,finalize};
+module.exports={analyze,prepareTemplate,createPrototype,manifest,inspect,inspectDesignReview,effectiveReview,claim,release,revise,replan,synchronizeIndex,build,verifyBuild,preview,recordRun,confirmBaseline,compareBaseline,state,finalize};

package/skills/i3-ui-prototype/scripts/native-pilot.cjs

@@ -5,14 +5,29 @@ const fs=require('node:fs');
 const lib=require('./native-pilot-lib.cjs');
 async function main(argv=process.argv.slice(2)) {
   const operation=argv.shift()||'analyze'; const positional=[]; const options={};
-  while(argv.length) { const value=argv.shift(); if(value.startsWith('--')) { const key=value.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase()); options[key]=!argv.length||argv[0].startsWith('--')?true:argv.shift(); } else positional.push(value); }
+  while(argv.length) { const value=argv.shift(); if(value==='--') { options.command=argv.splice(0); break; } if(value.startsWith('--')) { const key=value.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase()); options[key]=!argv.length||argv[0].startsWith('--')?true:argv.shift(); } else positional.push(value); }
   const root=positional[0]?path.resolve(positional[0]):null;
   switch(operation) {
     case 'analyze': return lib.analyze(options);
+    case 'paths': { const context=require('./prototype-locations.cjs').resolveLocations(options); return {...require('./project-registry.cjs').paths(options.project,options.id),host:context.host,scope:context.scope,projectKey:context.projectKey,toolsDirectory:context.toolsDirectory,cacheDirectory:context.cacheDirectory}; }
+    case 'index': return require('./project-registry.cjs').query(options);
+    case 'sync-index': return lib.synchronizeIndex(options);
+    case 'migrate-index': return require('./project-registry.cjs').migrate(options);
+    case 'browser-cache': return require('./browser-workspace.cjs').prepare(options);
+    case 'browser-cli': return require('./browser-workspace.cjs').runCli(options);
+    case 'archive-browser-output': return require('./browser-workspace.cjs').archive(options);
     case 'prepare-template': return lib.prepareTemplate(options);
     case 'sync-template': { const templates=require('./template-contract.cjs'); return options.check?templates.loadTemplate(root).index:templates.syncTemplate(root); }
-    case 'template-page': { const templates=require('./template-contract.cjs'); return require('./content-template.cjs').pageContent(root?templates.loadTemplate(root):templates.loadBundledTemplate(),options.page); }
+    case 'template-page': { const templates=require('./template-contract.cjs'); return require('./content-template.cjs').pageContent(root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),options.page); }
+    case 'generation-options': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),meta=require('./generation-contract.cjs').resource(snapshot,'generation.json');return {status:'passed',readOnly:true,template:snapshot.id,...meta,patterns:require('./generation-contract.cjs').definition().patterns}; }
+    case 'generation-plan': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template);const contract=require('./generation-contract.cjs');return contract.view(contract.compile(snapshot,JSON.parse(fs.readFileSync(path.resolve(options.scope),'utf8'))),options); }
+    case 'inventory': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),value=require('./template-inventory.cjs').verifySnapshot(snapshot);return options.details?value:{status:'passed',readOnly:true,template:snapshot.id,files:Object.keys(value.files).length,routes:value.routes.length,pages:value.pages.length,fragments:value.fragments.length,components:Object.keys(value.components).length,events:value.eventCount}; }
+    case 'sync-generation-assets': return require('./generation-assets.cjs').refresh(path.resolve(__dirname,'..'),{check:!!options.check});
     case 'create': return lib.createPrototype(options);
+    case 'execution-begin': return require('./execution-runtime.cjs').begin(root,lib);
+    case 'execution-assertions-template': return require('./execution-assertions.cjs').template(options);
+    case 'execution-template': return require('./execution-runtime.cjs').template(root,lib);
+    case 'execution-check': return require('./execution-runtime.cjs').check(root,options.stage||'delivery',lib);
     case 'manifest': return lib.manifest(root);
     case 'inspect': return lib.inspect(root,{acceptance:!!options.acceptance});
     case 'state': return lib.state(root,options);
@@ -22,6 +37,7 @@ async function main(argv=process.argv.slice(2)) {
     case 'build': return lib.build(root,options);
     case 'preview': { const running=await lib.preview(root,options); process.stdout.write(JSON.stringify({url:running.url,buildId:running.build.buildId})+'\n'); return null; }
     case 'revise': return lib.revise(root,options);
+    case 'replan': return lib.replan(root,options);
     case 'claim': return lib.claim(root,options);
     case 'release': return lib.release(root,options.owner);
     case 'record-run': return lib.recordRun(root,JSON.parse(fs.readFileSync(path.resolve(options.report),'utf8')));

package/skills/i3-ui-prototype/scripts/project-registry.cjs

@@ -0,0 +1,126 @@
+'use strict';
+const { fs, path, crypto, hash, assert, json, id, inside, write } = require('./native-files.cjs');
+function paths(project, prototypeId) {
+  const root = fs.realpathSync(path.resolve(project || '.'));
+  assert.ok(fs.statSync(root).isDirectory(), 'Project must be a directory');
+  if (prototypeId !== undefined) id(prototypeId);
+  return { project: root, output: inside(root, 'prototypes'), index: inside(root, 'prototypes/index.json'),
+    legacyIndex: inside(root, '.i3-ui-prototypes.json'), lock: inside(root, 'prototypes/.index.lock'), legacyLock: inside(root, '.i3-ui-prototypes.lock'),
+    ...(prototypeId === undefined ? {} : { directory: inside(root, `prototypes/${prototypeId}`), preparation: inside(root, `prototypes/.preparation/${prototypeId}`), scopeFile: inside(root, `prototypes/.preparation/${prototypeId}/scope.json`) }) };
+}
+function moduleIds(scope = {}) {
+  if (scope.schemaVersion !== undefined) assert.ok([1, 2, 3].includes(scope.schemaVersion), 'Unsupported scope schemaVersion');
+  if (scope.moduleIds === undefined && ![2, 3].includes(scope.schemaVersion)) return [];
+  assert.ok(Array.isArray(scope.moduleIds), 'scope.moduleIds must be an array; use [] for unbound scope');
+  for (const value of scope.moduleIds) assert.ok(typeof value === 'string' && value.length <= 128 && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value), 'Invalid module identifier in scope.moduleIds; use stable PRD module IDs, not paths or requirement text');
+  return [...new Set(scope.moduleIds)];
+}
+function validate(registry, project) {
+  assert.equal(registry.schemaVersion, 1, 'Invalid project prototype registry version');
+  assert.ok(Array.isArray(registry.prototypes), 'Invalid project prototype registry');
+  const ids = new Set();
+  for (const entry of registry.prototypes) {
+    id(entry.id); assert.ok(!ids.has(entry.id), 'Duplicate prototype ID in registry'); ids.add(entry.id);
+    inside(project, entry.directory);
+    assert.ok(entry.appliesTo === undefined || (Array.isArray(entry.appliesTo) && entry.appliesTo.every(value => typeof value === 'string')), 'Invalid appliesTo array');
+  }
+  return registry;
+}
+function read(project) {
+  const locations = paths(project), modern = fs.existsSync(locations.index), legacy = fs.existsSync(locations.legacyIndex);
+  if (modern && legacy) assert.deepEqual(json(locations.index), json(locations.legacyIndex), 'Conflicting prototype indices; resolve or explicitly migrate before writing');
+  const file = modern || !legacy ? locations.index : locations.legacyIndex;
+  const bytes = fs.existsSync(file) ? fs.readFileSync(file) : null;
+  return { ...locations, file, legacy: !modern && legacy, duplicateLegacy: modern && legacy,
+    bytes, registry: validate(bytes ? JSON.parse(bytes.toString('utf8')) : { schemaVersion: 1, prototypes: [] }, locations.project) };
+}
+function transaction(project, operation, { allowDuplicate = false } = {}) {
+  const initial = read(project);
+  assert.ok(allowDuplicate || !initial.duplicateLegacy, 'Duplicate active indices; explicitly resolve before writing');
+  assert.ok(!fs.existsSync(initial.legacyLock), 'Legacy prototype writer lock is active');
+  const createdOutput = !fs.existsSync(initial.output), locks = [];
+  fs.mkdirSync(initial.output, { recursive: true });
+  const acquire = file => { const fd = fs.openSync(file, 'wx'); locks.push({ file, fd }); };
+  try {
+    acquire(initial.lock);
+    if (initial.legacy || initial.duplicateLegacy) acquire(initial.legacyLock);
+    else assert.ok(!fs.existsSync(initial.legacyLock), 'Legacy prototype writer lock is active');
+    const current = read(project);
+    assert.equal(current.file, initial.file, 'Prototype index location changed while acquiring lock');
+    assert.ok(allowDuplicate || !current.duplicateLegacy, 'Duplicate active indices');
+    return operation({ ...current, save() {
+      const latest = read(project);
+      assert.equal(latest.file, current.file, 'Prototype index location changed');
+      assert.deepEqual(latest.bytes, current.bytes, 'Prototype index changed outside the active writer');
+      validate(current.registry, current.project);
+      write(current.project, path.relative(current.project, current.file).split(path.sep).join('/'), current.registry);
+    } });
+  } finally {
+    for (const { file, fd } of locks.reverse()) { fs.closeSync(fd); fs.unlinkSync(file); }
+    if (createdOutput && fs.existsSync(initial.output) && !fs.readdirSync(initial.output).length) fs.rmdirSync(initial.output);
+  }
+}
+function query(options = {}) {
+  const current = read(options.project), prototypes = current.registry.prototypes;
+  if (options.module !== undefined) assert.ok(typeof options.module === 'string' && options.module.trim(), 'Provide a nonempty module identifier or existing legacy label');
+  const errors = [], invalid = new Set();
+  for (const entry of prototypes) {
+    try {
+      const scopeFile = inside(current.project, `${entry.directory}/inputs/scope.json`);
+      if (fs.existsSync(scopeFile)) {
+        const scope = json(scopeFile);
+        if (scope.schemaVersion === 2 || scope.moduleIds !== undefined) assert.deepEqual(entry.appliesTo || [], moduleIds(scope), 'appliesTo differs from fixed scope.moduleIds; explicitly revise or synchronize the index');
+      }
+    } catch (error) { invalid.add(entry.id); errors.push(`${entry.id}: ${error.message}`); }
+  }
+  const matches = options.module === undefined ? [] : prototypes.filter(entry => !invalid.has(entry.id) && entry.appliesTo?.includes(options.module));
+  return { status: errors.length ? 'failed' : 'checked', index: current.file, legacy: current.legacy, prototypes, errors,
+    matches, unbound: prototypes.filter(entry => !invalid.has(entry.id) && !entry.appliesTo?.length), selection: matches.length > 1 ? 'ambiguous' : matches.length ? 'matched' : 'none', readOnly: true,
+    note: 'Module association does not prove implementation, current verification or human approval.' };
+}
+function withInstanceAssociation(directory, scope, operation) {
+  const parent = path.dirname(path.resolve(directory));
+  if (path.basename(parent) !== 'prototypes' || (scope.schemaVersion !== 2 && scope.moduleIds === undefined)) return operation();
+  const project = path.dirname(parent), current = read(project);
+  if (!current.registry.prototypes.some(entry => path.resolve(project, entry.directory) === path.resolve(directory))) return operation();
+  const appliesTo = moduleIds(scope), metadataFile = inside(directory, 'prototype.json'), before = fs.readFileSync(metadataFile);
+  return transaction(project, store => {
+    const entry = store.registry.prototypes.find(item => path.resolve(project, item.directory) === path.resolve(directory));
+    assert.ok(entry, 'Prototype entry disappeared during revision');
+    try { const result = operation(); entry.appliesTo = appliesTo; store.save(); return result; }
+    catch (error) { write(directory, 'prototype.json', before.toString('utf8')); throw error; }
+  });
+}
+function migrate(options = {}) {
+  assert.ok(options.check === undefined || typeof options.check === 'boolean', '--check must be a boolean flag');
+  const initial = read(options.project);
+  if (!fs.existsSync(initial.legacyIndex)) return { status: 'current', index: initial.index, sideEffects: [] };
+  const original = fs.readFileSync(initial.legacyIndex), digest = hash(original);
+  if (options.expectedDigest !== undefined) assert.equal(options.expectedDigest, digest, 'Legacy index changed since preview');
+  const plan = { source: initial.legacyIndex, destination: initial.index, sourceDigest: digest, prototypes: initial.registry.prototypes.length };
+  if (options.check) return { status: 'migration-preview', ...plan, sideEffects: [] };
+  return transaction(options.project, store => {
+    assert.deepEqual(fs.readFileSync(store.legacyIndex), original, 'Legacy index changed during migration');
+    const folder = inside(store.project, `prototypes/.migration/index-${crypto.randomUUID()}`);
+    fs.mkdirSync(folder, { recursive: true });
+    const backup = inside(folder, 'legacy-index.json'), temp = inside(store.project, `prototypes/.index-${crypto.randomUUID()}.tmp`);
+    fs.writeFileSync(backup, original, { flag: 'wx' });
+    write(folder, 'source.json', { ...plan, backup, purpose: 'Source snapshot before explicit index migration' });
+    let created = false;
+    try {
+      if (!fs.existsSync(store.index)) {
+        fs.writeFileSync(temp, original, { flag: 'wx' });
+        try { fs.linkSync(temp, store.index); created = true; }
+        finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+      } else assert.deepEqual(fs.readFileSync(store.index), original, 'Destination index already exists with different content');
+      assert.deepEqual(fs.readFileSync(backup), original, 'Migration backup mismatch');
+      assert.deepEqual(fs.readFileSync(store.legacyIndex), original, 'Legacy index changed before commit');
+      fs.unlinkSync(store.legacyIndex);
+      return { status: 'migrated', ...plan, backup };
+    } catch (error) {
+      if (created && fs.existsSync(store.index) && fs.readFileSync(store.index).equals(original)) fs.unlinkSync(store.index);
+      throw error;
+    }
+  }, { allowDuplicate: true });
+}
+module.exports = { paths, moduleIds, read, transaction, query, withInstanceAssociation, migrate };

package/skills/i3-ui-prototype/scripts/prototype-hooks.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict';
+// Explicit configuration lifecycle. check is read-only and never invokes the installer.
+const fs=require('node:fs'),path=require('node:path'),os=require('node:os'),assert=require('node:assert/strict');
+const R=require('./codebuddy-registration.cjs'),C=require('./codebuddy-context.cjs'),E=require('./execution-evidence.cjs');
+function context(options) {
+ assert.equal(options.host||'codebuddy','codebuddy','A+B supports CodeBuddy only');
+ const project=fs.realpathSync(path.resolve(options.project||'.')),scope=options.scope;
+ assert.ok(['project','global'].includes(scope),'Specify project or global installation scope');
+ const base=scope==='project'?path.join(project,'.codebuddy'):C.globalBase(options);
+ const recordText=R.fileIO.read(path.join(base,'state/i3-prototype/installation.json'));
+ const record=recordText?JSON.parse(recordText):null;
+ const unified=path.join(base,'i3-composer-agent/hooks/i3-prototype.cjs');
+ const scriptPath=options.entryPath||(fs.existsSync(unified)?unified:path.join(base,'skills/i3-ui-prototype/scripts/hosts/codebuddy.cjs'));
+ return {project,scope,base,record,scriptPath};
+}
+function prepare(options,runtime={}) {
+ const current=runtime.current||context(options),readText=runtime.readText||R.fileIO.read,action=options.action||'keep';
+ assert.ok(['keep','enable','disable'].includes(action),'Invalid Hook configuration action');
+ if(['keep','disable'].includes(action)&&!current.record){
+  if(action==='disable'){const settings=R.config(readText(path.join(current.base,'settings.json')));assert.ok(!Object.values(settings.hooks||{}).flat().some(g=>g.hooks.some(h=>h.command?.includes(R.OWNER))),'Unknown owned-looking Hook has no ownership record; preserve it for review');}
+  return {summary:{status:'not-enabled',scope:current.scope,changed:false},unchanged:true};
+ }
+ const product=options.product||current.record?.product;assert.ok(['ide','cli'].includes(product),'Use --codebuddy-product ide or cli when enabling Hooks');
+ if(action!=='disable') {
+  const manifest=readText(path.join(current.base,'.i3-composer-agent.json'));
+  if(manifest)assert.ok(!JSON.parse(manifest).agents?.includes('workbuddy'),'Shared CodeBuddy/WorkBuddy registration cannot safely identify the product; preserve settings and use an exclusive CodeBuddy scope');
+  assert.ok(!options.agents?.includes('workbuddy')||current.scope!=='project','Do not enable CodeBuddy audit in a shared WorkBuddy project target');
+ }
+ const explicit=options.transcriptRoot,roots=explicit==='auto'?[]:explicit?[path.resolve(explicit)]:current.record?.transcriptRoots||[];
+ const mode=explicit?(explicit==='auto'?'auto':'manual'):current.record?.transcriptMode||(roots.length?'manual':'auto');
+ if(action!=='disable') {
+  for(const root of roots){const relative=path.relative(current.project,root);assert.ok(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative),'Native log root must be outside the business project; QA exports are not native provenance');}
+ }
+ const settingsText=readText(path.join(current.base,'settings.json')),settings=R.config(settingsText);
+ if(action!=='disable')assert.ok(!settings.disableAllHooks&&!settings.allowManagedHooksOnly,'Host policy prevents automatic auditing; preserve the existing policy');
+ return R.plan({action,...current,product,nodePath:process.execPath,scriptDigest:runtime.scriptDigest||C.bundle(options.entrySource||(path.basename(current.scriptPath)==='i3-prototype.cjs'?current.scriptPath:path.join(__dirname,'hosts/codebuddy.cjs'))),currentText:settingsText,
+  transcriptMode:mode,transcriptRoots:roots,productVersion:options.productVersion||current.record?.productVersion||'unreported'});
+}
+function configure(options) {
+ const change=prepare(options);if(change.unchanged||options.preview)return change.summary;
+ return R.apply(change);
+}
+function check(options,runtime={}) {
+ const current=runtime.current||context(options),profile=require('../assets/hosts/codebuddy/profile.json');
+ const result={scope:current.scope,base:current.base,scriptPath:current.scriptPath,filesPresent:fs.existsSync(current.scriptPath),profile:profile.id,nativeValidation:profile.nativeValidation,readOnly:true,sideEffects:[]};
+ if(process.platform==='win32')return {...result,status:'unsupported',reason:'CodeBuddy Hook quoting on Windows has not been validated'};
+ if(!current.record){
+  const settings=R.config(R.fileIO.read(path.join(current.base,'settings.json')));
+  if(Object.values(settings.hooks||{}).flat().some(group=>group.hooks.some(h=>h.command?.includes(R.OWNER))))return {...result,status:'failed',errors:['Unknown prototype Hook registration has no ownership record; preserve it for review']};
+  return {...result,status:result.filesPresent?'files-present':'not-enabled'};
+ }
+ try {
+  const record=(runtime.registration||C.registration)(current.base),effective=(runtime.select||C.select)({project:current.project,product:record.product,home:options.home,env:options.env});
+  Object.assign(result,{product:record.product,productVersion:record.productVersion,registrationDigest:record.registrationDigest,effective:effective?.base===current.base,transcriptRoots:record.transcriptRoots,
+   transcript:{mode:record.transcriptMode||(record.transcriptRoots?.length?'manual':'auto'),status:'awaiting-native-event',invocationVerified:false}});
+  let observation=null;
+  const parent=path.join(current.base,'state/i3-prototype',C.projectKey(current.project));
+  const entries=runtime.entries||[];
+  if(!runtime.entries&&fs.existsSync(parent))for(const name of fs.readdirSync(parent)) {
+   if(!/^[a-f0-9]{24}$/.test(name))continue;
+   const raw=R.fileIO.read(path.join(parent,name,'session.json'));if(!raw)continue;
+   entries.push(...Object.values(JSON.parse(raw).bindings||{}));
+  }
+  for(const entry of entries)if(entry.project===current.project&&entry.registrationDigest===record.registrationDigest&&entry.settingsDigest===record.settingsDigest&&(!observation||entry.lastHook.at>observation.lastHook.at))observation=entry;
+  if(observation) {
+   result.transcript.path=observation.source.path;
+   C.prefix(observation.source.path,observation.source.bytes,observation.source.digest);
+   C.source({session_id:observation.sessionId,transcript_path:observation.source.path},record,current.project);
+   Object.assign(result.transcript,{status:'verified',invocationVerified:true});
+   result.observation={sessionId:observation.sessionId,projectKey:observation.projectKey,runId:observation.runId,event:observation.lastHook.event,at:observation.lastHook.at};
+  }
+  const recent=observation&&Date.now()-Date.parse(observation.lastHook.at)>=0&&Date.now()-Date.parse(observation.lastHook.at)<30*60*1000;
+  return {...result,status:result.effective&&recent?'active':record.product==='cli'?'pending-host-review':'registered',
+   activationScope:'Only the displayed project/session/configuration and adapter bytes; not all projects or business acceptance',
+   next:record.product==='cli'?'Review /hooks in CodeBuddy Code, then use a new session.':'Reload CodeBuddy and verify a real prototype write task.'};
+ }catch(error){if(result.transcript)Object.assign(result.transcript,{status:'unverified',invocationVerified:false});return {...result,status:'failed',errors:[error.message]};}
+}
+function main(argv=process.argv.slice(2)) {
+ const central=[path.resolve(__dirname,'../../../i3-composer-agent/hooks/manage.cjs'),path.resolve(__dirname,'../../../hooks/manage.cjs')].find(file=>fs.existsSync(file));
+ if(central)return require(central).main([...argv,'--groups','prototype']);
+ const options={action:argv.shift()||'check',host:'codebuddy',project:process.cwd()};
+ while(argv.length){const arg=argv.shift();assert.ok(arg.startsWith('--')&&argv[0]&&!argv[0].startsWith('--'),'Hook option needs a value');const key=arg.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase());assert.ok(['host','scope','project','product','productVersion','transcriptRoot'].includes(key),'Unknown Hook option');options[key]=argv.shift();}
+ return options.action==='check'?check(options):configure(options);
+}
+module.exports={context,globalBase:C.globalBase,prepare,configure,check,main};
+if(require.main===module)try{const result=main();process.stdout.write(JSON.stringify(result,null,2)+'\n');if(result.status==='failed')process.exitCode=1;}catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}

package/skills/i3-ui-prototype/scripts/prototype-lib.cjs

@@ -5,6 +5,7 @@ const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const templateRegistry = require('./template-adapters.cjs').createTemplateRegistry();
 const { discoverProviderCandidates } = require('./design-provider-discovery.cjs');
+const projectRegistry = require('./project-registry.cjs');
 const hash = value => crypto.createHash('sha256').update(value).digest('hex');
 const json = file => JSON.parse(fs.readFileSync(file, 'utf8'));
 function ensure(condition, message) { if (!condition) throw new Error(message); }
@@ -113,11 +114,8 @@ function initPrototype(options, registry = templateRegistry) {
   ensure(fs.existsSync(project) && fs.statSync(project).isDirectory(), 'Project directory does not exist');
   const directory = contained(project, `prototypes/${id}`);
   ensure(!fs.existsSync(directory), 'Prototype already exists / 原型已存在，使用 revise 或另选标识');
-  const lockPath = contained(project, '.i3-ui-prototypes.lock');
-  const lock = fs.openSync(lockPath, 'wx');
-  try {
-  const registryPath = contained(project, '.i3-ui-prototypes.json');
-  const registry = fs.existsSync(registryPath) ? json(registryPath) : { schemaVersion: 1, prototypes: [] };
+  return projectRegistry.transaction(project, store => {
+  const registry = store.registry;
   ensure(registry.schemaVersion === 1 && Array.isArray(registry.prototypes), 'Invalid project prototype registry');
   ensure(!registry.prototypes.some(entry => entry.id === id), 'Prototype registry already contains identifier');
   const preset = selected.preset;
@@ -142,11 +140,11 @@ function initPrototype(options, registry = templateRegistry) {
     fs.renameSync(staging, directory);
     created = true;
     registry.prototypes.push({ id, directory: `prototypes/${id}`, appliesTo: [] });
-    atomicJson(project, '.i3-ui-prototypes.json', registry);
+    store.save();
   } catch (error) { if (created) fs.rmSync(directory, { recursive: true, force: true }); throw error; }
   finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
   return { status: 'created', directory, template: template.id, expertMode };
-  } finally { fs.closeSync(lock); fs.unlinkSync(lockPath); }
+  });
 }
 function contentManifest(directory, registry = templateRegistry) {
   const metadata = json(contained(directory, 'prototype.json'));

package/skills/i3-ui-prototype/scripts/prototype-locations.cjs

@@ -2,6 +2,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const crypto = require('node:crypto');
 // Reviewed mirror of i3's installer target table; maintenance tests require byte equality.
 const registry = require('../assets/optional-skills/host-targets.json');
 const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
@@ -11,6 +12,7 @@ function globalSkillsDir(agent, home, env) {
   let base = home;
   if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
   if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (config.env === 'CODEBUDDY_CONFIG_DIR' && (!path.isAbsolute(base) || /[\x00\r\n]/.test(base))) throw new Error('CODEBUDDY_CONFIG_DIR must be an absolute safe directory');
   if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
     const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
     if (alternative) return path.join(home, alternative);
@@ -41,8 +43,10 @@ function resolveLocations(options = {}) {
   const projectBase = path.dirname(projectSkills), globalBase = globalSkills ? path.dirname(globalSkills) : null;
   // Some hosts put skills directly in the workspace; tools still get a host directory.
   const projectToolsBase = projectBase === project ? path.join(project, `.${host}`) : projectBase;
+  const projectKey = `${path.basename(project).replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 32) || 'project'}-${crypto.createHash('sha256').update(project).digest('hex').slice(0, 16)}`;
+  const cacheBase = path.join(scope === 'global' ? globalBase : projectToolsBase, 'cache/i3-prototype');
   return { host, scope, project, home, skillsDirectory, base, projectSkills, globalSkills,
-    projectBase, globalBase, projectToolsBase,
+    projectBase, globalBase, projectToolsBase, projectKey, cacheDirectory: scope === 'global' ? path.join(cacheBase, projectKey) : cacheBase,
     toolsDirectory: path.join(scope === 'global' ? globalBase : projectToolsBase, 'tools/i3-prototype') };
 }
 function scopeBases(context) {

package/skills/i3-ui-prototype/scripts/template-contract.cjs

@@ -1,4 +1,5 @@
 'use strict';
+const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
@@ -300,6 +301,7 @@ function checkCapabilities({ definition, bindings = [], regions = [], scope = {}
 }
 function syncTemplate(directory, { write = true } = {}) {
   directory = path.resolve(directory);
+  if (write && fs.existsSync(path.join(directory, 'component-inventory.json'))) fs.writeFileSync(path.join(directory, 'template-inventory.json'), JSON.stringify(require('./template-inventory.cjs').scan(directory), null, 2) + '\n');
   const files = filesUnder(directory);
   const manifest = readJson(localFile(directory, 'template.json'));
   identifier(manifest.id, 'template');
@@ -345,8 +347,15 @@ function loadTemplate(directory) {
   if (!stored || canonical(stored) !== canonical(expected)) throw new Error('Template index is stale / 源和索引不同步; run sync-template.cjs');
   return templateSnapshot(directory, expected);
 }
-function loadBundledTemplate() {
-  const directory = path.join(ASSETS, 'templates/enterprise-admin');
+function loadBundledTemplate(templateId, { templatesRoot = path.join(ASSETS, 'templates') } = {}) {
+  const catalog = readJson(localFile(templatesRoot, 'catalog.json'));
+  templateId ||= catalog.defaultTemplate; identifier(templateId, 'template');
+  const selected = catalog.templates.find(item => item.id === templateId);
+  assert.ok(selected?.availability === 'available' && selected.contentRoot, `Unsupported or not available native template: ${templateId}`);
+  const directory = localFile(templatesRoot, selected.contentRoot);
+  const manifest = readJson(localFile(directory, 'template.json'));
+  assert.equal(manifest.kind, 'content-reference', 'Native templates require an explicit content-reference manifest');
+  assert.equal(manifest.id, templateId, 'Template catalog identity differs from its manifest');
   return templateSnapshot(directory, syncTemplate(directory, { write: false }));
 }
 function prepareTemplate({ project, id = 'enterprise-admin' }) {