@givolt/i3-composer-agent 2.3.1 → 2.3.3

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

@@ -0,0 +1,214 @@
+'use strict';
+const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto'), assert = require('node:assert/strict');
+const hash = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const copy = value => JSON.parse(JSON.stringify(value));
+function resource(snapshot, name) {
+  const file = snapshot.files.find(item => item.path === name);
+  assert.ok(file, `Template generation resource is missing: ${name}`);
+  return JSON.parse(Buffer.from(file.content, 'base64').toString('utf8'));
+}
+function definition() { return JSON.parse(fs.readFileSync(path.join(__dirname, '../assets/capabilities/generation.json'), 'utf8')); }
+function source(requirement) {
+  return requirement?.source && ['type', 'reference', 'statement'].every(key => typeof requirement.source[key] === 'string' && requirement.source[key].trim());
+}
+function validateParameters(capability, value) {
+  assert.ok(value && typeof value === 'object' && !Array.isArray(value), 'Capability parameters must be an object');
+  for (const [key, item] of Object.entries(value)) {
+    const rule = capability.parameters[key]; assert.ok(rule, `Unsupported ${capability.id} parameter: ${key}`);
+    if (rule.enum) assert.ok(rule.enum.includes(item), `Invalid ${capability.id} parameter: ${key}`);
+    if (rule.boolean) assert.equal(typeof item, 'boolean');
+    if (rule.string) assert.ok(typeof item === 'string' && item.trim(), `Invalid string parameter: ${key}`);
+    if (rule.integer) assert.ok(Number.isInteger(item) && item >= rule.integer, `Invalid integer parameter: ${key}`);
+    if (rule.strings) assert.ok(Array.isArray(item) && item.every(value => typeof value === 'string' && value.trim()), `Invalid list parameter: ${key}`);
+    if (rule.positiveIntegers) assert.ok(Array.isArray(item) && item.length >= 2 && new Set(item).size === item.length && item.every(value => Number.isInteger(value) && value > 0), `Invalid page-size parameter: ${key}`);
+  }
+  if (capability.id === 'pagination' && Object.keys(value).length) require('./template-contract.cjs').resolvePaginationParameters(value);
+  return copy(value);
+}
+function reference(inventory, start) {
+  const fragments = new Map(inventory.fragments.map(fragment => [fragment.file, fragment])), visited = new Set(), nodes = [], events = [], elements = [], capabilities = new Set();
+  function visit(file) {
+    if (visited.has(file)) return; visited.add(file);
+    const fragment = fragments.get(file); assert.ok(fragment, `Reference fragment is missing: ${file}`);
+    for (const node of fragment.nodes) {
+      nodes.push(node.id);
+      for (const [event, expression] of Object.entries(node.attributes)) if (event.startsWith('data-on-')) events.push({ nodeId: node.id, event, expression });
+      const componentName = node.attributes['data-component'], component = inventory.components[componentName];
+      const nodeEvents = Object.entries(node.attributes).filter(([key]) => key.startsWith('data-on-')).map(([event, expression]) => ({ event, expression }));
+      if (nodeEvents.length || (component && component.classification.kind !== 'icon' && component.classification.capabilities.some(id => id !== 'review-tools'))) elements.push({ nodeId: node.id, fragment: file, component: componentName || null, capabilities: (component?.classification.capabilities || []).filter(id => id !== 'review-tools'), events: nodeEvents });
+      if (component) {
+        for (const capability of component.classification.capabilities) capabilities.add(capability);
+        if (component.classification.source) visit(component.classification.source);
+      }
+    }
+  }
+  visit(start);
+  return { fragments: [...visited], nodes, events, elements, capabilities: [...capabilities].sort() };
+}
+function navigation(items, pages) {
+  if (items === undefined) return pages.map(page => ({ key: page.id, label: page.title }));
+  const seen = new Set(), groups = new Set();
+  function walk(values) {
+    assert.ok(Array.isArray(values) && values.length, 'Navigation entries must be a nonempty array');
+    return values.map(item => {
+      if (item.children) {
+        assert.ok(!item.pageId && /^[a-z][a-z0-9-]{0,63}$/.test(item.id || '') && item.title?.trim() && !groups.has(item.id), 'Invalid or duplicate navigation group'); groups.add(item.id);
+        return { key: `@${item.id}`, label: item.title, children: walk(item.children) };
+      }
+      const page = pages.find(page => page.id === item.pageId);
+      assert.ok(page && !seen.has(page.id), 'Duplicate or unknown navigation page'); seen.add(page.id);
+      return { key: page.id, label: item.title || page.title };
+    });
+  }
+  const result = walk(items); assert.equal(seen.size, pages.length, 'Navigation omits a declared page'); return result;
+}
+function compile(snapshot, scope, options = {}) {
+  assert.equal(scope.schemaVersion, 3, 'Generation contracts require sourced scope schemaVersion=3');
+  const meta = resource(snapshot, 'generation.json'), rules = copy(options.definition || definition());
+  assert.equal(meta.schemaVersion, 1, 'Unsupported template generation version'); assert.equal(rules.schemaVersion, 1);
+  assert.equal(meta.templateId, snapshot.id, 'Generation metadata belongs to a different template');
+  assert.equal(hash(rules), meta.definitionDigest, 'Generation catalog differs from the frozen template rule identity');
+  assert.ok(meta.frameworks.includes(options.framework || 'vue-antdv-next'), 'Unsupported template/framework choice');
+  const presentation = { ...meta.defaults, ...scope.generation?.presentation };
+  for (const key of Object.keys(presentation)) assert.ok(Object.hasOwn(meta.choices[key] || {}, presentation[key]), `Unsupported presentation choice: ${key}=${presentation[key]}`);
+  const requirements = new Map((scope.requirements || []).map(item => [item.id, item]));
+  assert.ok(requirements.size === scope.requirements.length && requirements.size && [...requirements.values()].every(item => typeof item.id === 'string' && item.id.trim() && source(item)), 'Every generation requirement needs a unique identity and source');
+  const inventory = require('./template-inventory.cjs').verifySnapshot(snapshot), bindings = [], pages = [], coverage = [], decisions = scope.generation?.decisions || [];
+  assert.ok(Array.isArray(decisions), 'Generation applicability decisions must be an array');
+  const keys = new Set();
+  for (const decision of decisions) {
+    const key = `${decision.pageId}/${decision.regionId || "*"}/${decision.capabilityId}`; assert.ok(!keys.has(key), 'Duplicate generation applicability decision'); keys.add(key);
+    assert.ok(rules.capabilities[decision.capabilityId], 'Unknown generation capability decision');
+    assert.ok(['adopted', 'not-applicable'].includes(decision.decision), 'Unsupported generation decision');
+    if (decision.decision === 'not-applicable') { assert.ok(!decision.regionId && !Object.keys(decision.parameters || {}).length, 'Capability exclusion applies to the page and has no ignored parameters'); assert.ok(!decisions.some(item => item !== decision && item.pageId === decision.pageId && item.capabilityId === decision.capabilityId), 'Conflicting capability applicability decisions'); }
+    const requirement = requirements.get(decision.requirementId);
+    assert.ok(decision.reason?.trim() && source(requirement) && (decision.pageId === 'app-shell' || requirement.pages?.includes(decision.pageId)), 'Generation decision requires a reason and matching requirement source');
+  }
+  function bind(pageId, regionId, capabilityId, parameters = {}) {
+    assert.ok(rules.capabilities[capabilityId], `Unknown pattern capability: ${capabilityId}`);
+    const id = `${pageId}/${regionId}/${capabilityId}`;
+    const defaults = parameters.mode === 'fixed' ? { minimumTestPages: 3 } : rules.capabilities[capabilityId].defaults;
+    if (!bindings.some(item => item.id === id)) bindings.push({ id, pageId, regionId, capabilityId, parameters: validateParameters(rules.capabilities[capabilityId], { ...defaults, ...parameters }) });
+  }
+  for (const capability of rules.core) bind('app-shell', 'shell', capability);
+  if (meta.shell) coverage.push({ pageId: 'app-shell', ...reference(inventory, meta.shell) });
+  assert.ok(scope.pages?.length, 'Generation pages are required');
+  for (const page of scope.pages) {
+    assert.match(page.id || '', /^[a-z][a-z0-9-]{0,63}$/); assert.ok(page.id !== 'app-shell' && page.title?.trim(), 'Business page identity/title required');
+    assert.ok(!pages.some(item => item.id === page.id), 'Duplicate generation page');
+    const selected = snapshot.index.pages.find(item => item.id === page.referencePage); assert.ok(selected, `Unknown reference page: ${page.referencePage}`);
+    assert.ok(page.regions?.length, 'Generation regions are required');
+    const regionIds = new Set();
+    for (const region of page.regions) {
+      assert.match(region.id || '', /^[a-z][a-z0-9-]{0,63}$/);
+      assert.ok(!regionIds.has(region.id), 'Duplicate generation region'); regionIds.add(region.id);
+      const pattern = region.pattern || region.mode;
+      assert.ok(meta.patterns.includes(pattern) && rules.patterns[pattern], `Unsupported page pattern: ${pattern}`);
+      const selectedCapabilities = new Set(rules.patterns[pattern].required);
+      const editPresentation = region.parameters?.edit?.presentation || (['form-page','wizard','permissions'].includes(pattern) ? 'page' : region.parameters?.dialog?.presentation || 'drawer');
+      if (selectedCapabilities.has('edit')) {
+        if (pattern === 'form-page') assert.equal(editPresentation, 'page', 'A form-page requires page presentation');
+        if (pattern === 'edit-form') assert.ok(['drawer','modal'].includes(editPresentation), 'An edit-form requires dialog presentation');
+        if (editPresentation !== 'page') selectedCapabilities.add('dialog');
+        if (region.parameters?.dialog?.presentation) assert.equal(region.parameters.dialog.presentation, editPresentation, 'Edit and dialog presentation must agree');
+      }
+      for (const key of Object.keys(region.parameters || {})) {
+        assert.ok(rules.capabilities[key], `Unsupported capability parameter group: ${key}`);
+        assert.ok(selectedCapabilities.has(key) || decisions.some(item => item.pageId === page.id && item.regionId === region.id && item.capabilityId === key && item.decision === 'adopted'), `Unused capability parameter group: ${key}`);
+      }
+      for (const capability of selectedCapabilities) {
+        const selectedDefaults = capability === 'hierarchy' ? { kind: pattern === 'tree-table' ? 'tree-table' : pattern === 'permissions' ? 'permission-tree' : 'filter-tree', selectionPolicy: pattern === 'permissions' ? 'cascade' : pattern === 'tree-table' ? 'independent' : 'single' } : capability === 'edit' ? { presentation: editPresentation } : capability === 'dialog' && selectedCapabilities.has('edit') ? { presentation: editPresentation } : {};
+        bind(page.id, region.id, capability, { ...selectedDefaults, ...region.parameters?.[capability] });
+      }
+      for (const [kind, items] of Object.entries({ field: region.fields || [], action: region.actions || [] })) {
+        assert.ok(Array.isArray(items), 'Declare sourced field/action arrays'); const elementIds = new Set();
+        for (const item of items) {
+          assert.ok(/^[a-z][a-z0-9-]{0,63}$/.test(item.id || '') && !elementIds.has(item.id), 'Invalid or duplicate field/action identity'); elementIds.add(item.id);
+          assert.ok(item.label?.trim() && source(requirements.get(item.requirementId)) && requirements.get(item.requirementId).pages?.includes(page.id), 'Business field/action requires a label and matching requirement source');
+          if (kind === 'field') assert.ok(['text','textarea','select','number','checkbox','radio','date','time','tree-select','read-only'].includes(item.kind), 'Unsupported business field kind');
+          else assert.ok(['create','read','update','delete','submit','state-change','other'].includes(item.kind) && ['page','row','selected','node'].includes(item.target) && item.outcome?.trim(), 'Business action needs kind, target and expected outcome');
+          bindings.push({ id: `${page.id}/${region.id}/${kind}/${item.id}`, pageId: page.id, regionId: region.id, capabilityId: 'interaction', kind, parameters: copy(item) });
+        }
+      }
+    }
+    pages.push({ id: page.id, title: page.title, referencePage: page.referencePage, regions: page.regions.map(region => ({ id: region.id, pattern: region.pattern || region.mode, fields: copy(region.fields || []), actions: copy(region.actions || []) })) });
+    coverage.push({ pageId: page.id, ...reference(inventory, selected.fragment) });
+  }
+  for (const decision of decisions) {
+    assert.ok(decision.pageId === 'app-shell' || pages.some(page => page.id === decision.pageId), 'Decision page is not declared');
+    const alreadyRequired = bindings.some(item => (item.pageId === decision.pageId || item.pageId === 'app-shell') && item.capabilityId === decision.capabilityId);
+    assert.ok(!(alreadyRequired && decision.decision === 'not-applicable'), 'Cannot exempt a required selected-pattern capability');
+    if (decision.decision !== 'adopted') continue;
+    if (!decision.regionId) {
+      assert.ok(alreadyRequired, 'An adopted capability needs a declared region');
+      assert.ok(!Object.keys(decision.parameters || {}).length, 'Required capability parameters belong on the selected region');
+      continue;
+    }
+    const page = scope.pages.find(item => item.id === decision.pageId);
+    const region = decision.pageId === 'app-shell' && decision.regionId === 'shell' ? { id: 'shell' } : page?.regions.find(item => item.id === decision.regionId);
+    assert.ok(region, 'An adopted capability needs a declared region');
+    if (bindings.some(item => item.pageId === decision.pageId && item.regionId === region.id && item.capabilityId === decision.capabilityId)) assert.ok(!Object.keys(decision.parameters || {}).length, 'Required capability parameters belong on the selected region');
+    else bind(decision.pageId, region.id, decision.capabilityId, { ...region.parameters?.[decision.capabilityId], ...decision.parameters });
+  }
+  const pendingDecisions = [];
+  for (const item of coverage) for (const capabilityId of item.capabilities) {
+    if (capabilityId === 'review-tools') continue;
+    assert.ok(rules.capabilities[capabilityId], `Unmapped reference capability: ${capabilityId}`);
+    if (!bindings.some(binding => (binding.pageId === item.pageId || binding.pageId === 'app-shell') && binding.capabilityId === capabilityId) && !decisions.some(decision => decision.pageId === item.pageId && decision.capabilityId === capabilityId)) pendingDecisions.push({ pageId: item.pageId, capabilityId });
+  }
+  // Each functional reference element is accounted for, including elements whose
+  // capability is already core. Adopting a generic capability never accounts for
+  // every example button, field or event implicitly.
+  const referenceDecisions = scope.generation?.referenceDecisions || [], accounted = new Set();
+  assert.ok(Array.isArray(referenceDecisions), 'Reference element decisions must be an array');
+  for (const decision of referenceDecisions) {
+    const requirement = requirements.get(decision.requirementId), selected = coverage.find(item => item.pageId === decision.pageId);
+    assert.ok(selected && source(requirement) && (decision.pageId === 'app-shell' || requirement.pages?.includes(decision.pageId)) && decision.reason?.trim(), 'Reference element decision requires matching requirement source and reason');
+    assert.ok(['mapped','not-applicable'].includes(decision.decision) && Array.isArray(decision.nodeIds) && decision.nodeIds.length, 'Explicit reference node IDs and disposition required');
+    for (const nodeId of decision.nodeIds) {
+      const key = `${decision.pageId}/${nodeId}`, element = selected.elements.find(item => item.nodeId === nodeId);
+      assert.ok(element && !accounted.has(key), 'Unknown or duplicate reference element disposition'); accounted.add(key);
+      if (decision.decision === 'mapped') {
+        assert.ok(Array.isArray(decision.bindingIds) && decision.bindingIds.length, 'Mapped reference elements need actual binding IDs');
+        for (const bindingId of decision.bindingIds) assert.ok(bindings.some(binding => binding.id === bindingId && (binding.pageId === decision.pageId || binding.pageId === 'app-shell')), 'Reference element binding belongs to another page or is absent');
+        const relevant = element.capabilities.length ? element.capabilities : ['interaction'];
+        assert.ok(bindings.some(binding => decision.bindingIds.includes(binding.id) && relevant.includes(binding.capabilityId)), 'Reference element mapping needs a matching semantic capability');
+      } else assert.ok(!decision.bindingIds?.length, 'Excluded reference elements cannot claim implementation');
+    }
+  }
+  const pendingReferenceElements = coverage.flatMap(item => item.elements.filter(element => !accounted.has(`${item.pageId}/${element.nodeId}`)).map(element => ({ pageId: item.pageId, ...element })));
+  function scenarioExpectation(binding, scenario) {
+    if (binding.capabilityId === 'pagination' && scenario.id === 'page-size' && binding.parameters.mode === 'fixed') return `固定容量 ${binding.parameters.fixedPageSize} 不可更改，界面说明正确；翻页、总数和选择符合固定容量约定。`;
+    if (binding.capabilityId === 'columns' && scenario.id === 'persistence-scroll' && !binding.parameters.persist) return '列配置按声明仅在本轮生效，刷新恢复默认；宽表可滚动且操作列可达。';
+    if (binding.capabilityId === 'dialog' && scenario.id === 'lifetime' && binding.parameters.presentation === 'modal') return '弹窗打开、关闭和进出动效生命周期完整，未提前卸载，符合固定弹窗呈现。';
+    return scenario.expected;
+  }
+  const scenarios = bindings.flatMap(binding => binding.kind ? [{ id: `generation/${binding.id}`, bindingId: binding.id, pageId: binding.pageId, regionId: binding.regionId, capabilityId: binding.capabilityId, steps: [`在当前构建中操作 ${binding.parameters.label}，核对身份、状态和需求来源。`], expected: binding.kind === 'action' ? binding.parameters.outcome : `字段 ${binding.parameters.label} 的类型、必填、只读、校验与联动符合固定字段声明。`, parameters: copy(binding.parameters) }] : rules.capabilities[binding.capabilityId].scenarios.map(scenario => ({ ...copy(scenario), expected: scenarioExpectation(binding, scenario), id: `generation/${binding.id}/${scenario.id}`, bindingId: binding.id, pageId: binding.pageId, regionId: binding.regionId, capabilityId: binding.capabilityId, parameters: copy(binding.parameters) })));
+  for (const decision of referenceDecisions.filter(item => item.decision === 'mapped')) for (const nodeId of decision.nodeIds) {
+    const element = coverage.find(item => item.pageId === decision.pageId).elements.find(item => item.nodeId === nodeId);
+    const relevant = element.capabilities.length ? element.capabilities : ['interaction'];
+    const binding = bindings.find(item => decision.bindingIds.includes(item.id) && relevant.includes(item.capabilityId));
+    scenarios.push({ id: `generation/reference/${decision.pageId}/${hash(nodeId).slice(0,16)}`, bindingId: binding.id, pageId: decision.pageId, regionId: binding.regionId, capabilityId: binding.capabilityId, referenceNodeId: nodeId, referenceEvents: copy(element.events), requirementId: decision.requirementId, steps: ['在对应实际页面操作或检查本参考节点映射的控件，覆盖其采用的交互和状态。'], expected: `核对实际控件、对象、交互结果和状态符合需求与本次取舍：${decision.reason}；不能用同能力下的另一个控件代替。`, parameters: { bindingIds: copy(decision.bindingIds) } });
+  }
+  return { schemaVersion: 1, definition: rules, template: { id: snapshot.id, version: snapshot.version, digest: snapshot.digest }, presentation, navigation: navigation(scope.generation?.navigation, pages), pages, bindings, decisions: copy(decisions), referenceCoverage: coverage, pendingDecisions, referenceDecisions: copy(referenceDecisions), pendingReferenceElements, scenarios };
+}
+function verify(snapshot, scope, fixed) {
+  assert.deepEqual(fixed, compile(snapshot, scope, { definition: fixed.definition }), 'Fixed generation contract differs from selected patterns, sourced decisions or customer choices');
+  return { status: 'passed', bindings: fixed.bindings.length, scenarios: fixed.scenarios.length, pendingDecisions: fixed.pendingDecisions.length, pendingReferenceElements: fixed.pendingReferenceElements.length };
+}
+function view(contract, options = {}) {
+  if (options.details) return contract;
+  if (options.page) assert.ok(options.page === 'app-shell' || contract.pages.some(page => page.id === options.page), 'Unknown generation page');
+  const coverage = contract.referenceCoverage.filter(item => !options.page || item.pageId === options.page);
+  if (options.fragment) assert.ok(coverage.some(item => item.fragments.includes(options.fragment)), 'Unknown reference fragment for selected page');
+  const pending = contract.pendingReferenceElements.filter(item => !options.page || item.pageId === options.page), groups = new Map();
+  for (const item of pending) { const key = `${item.pageId}/${item.fragment}`; if (!groups.has(key)) groups.set(key, { pageId: item.pageId, fragment: item.fragment, pending: 0 }); groups.get(key).pending++; }
+  const scenarios = contract.scenarios.filter(item => !options.page || item.pageId === options.page);
+  return { status: 'planned', readOnly: true, template: contract.template, presentation: contract.presentation,
+    pages: contract.pages.filter(item => !options.page || item.id === options.page), bindings: contract.bindings.filter(item => !options.page || item.pageId === options.page),
+    pendingDecisions: contract.pendingDecisions.filter(item => !options.page || item.pageId === options.page),
+    referenceReview: { pendingCount: pending.length, fragments: [...groups.values()], ...(options.fragment ? { elements: pending.filter(item => item.fragment === options.fragment) } : {}) },
+    acceptance: { scenarios: scenarios.length, ...(options.page ? { scenarioIds: scenarios.map(item => item.id) } : {}) },
+    next: 'Use --page <business-page-id|app-shell> --fragment <reference-path> for nodes; --details returns the full fixed contract.' };
+}
+module.exports = { compile, verify, definition, resource, view };

package/skills/i3-ui-prototype/scripts/generation-evidence.cjs

@@ -0,0 +1,50 @@
+'use strict';
+// Structural evidence validation cannot prove an actual host/MCP invocation or UI outcome.
+const {fs,path,assert,json,inside,hash}=require('./native-files.cjs');
+const nonempty=(value,label)=>assert.ok(typeof value==='string'&&value.trim(),`${label} required`);
+const exact=(actual,expected,label)=>assert.deepEqual([...actual].sort(),[...expected].sort(),`${label} differs from fixed generation bindings/scenarios`);
+function framework(){return json(path.join(__dirname,'../assets/frameworks/vue-antdv-next/generation-component-map.json'));}
+function initialize(generation){return {schemaVersion:1,bindings:generation.bindings.map(binding=>({bindingId:binding.id,status:'pending',components:[],files:[],scenarioIds:generation.scenarios.filter(s=>s.bindingId===binding.id).map(s=>s.id)}))};}
+function validateImplementation(directory,generation,implementation,options={}){
+ assert.equal(implementation.schemaVersion,1,'Unsupported implementation mapping');assert.ok(Array.isArray(implementation.bindings),'Implementation bindings required');
+ exact(implementation.bindings.map(item=>item.bindingId),generation.bindings.map(item=>item.id),'Implementation binding coverage');
+ const map=options.frameworkMap||framework();let pending=0;
+ for(const binding of generation.bindings){
+  const item=implementation.bindings.find(item=>item.bindingId===binding.id);
+  assert.ok(map.capabilities[binding.capabilityId]?.components?.length,`Framework capability mapping missing: ${binding.capabilityId}`);
+  assert.ok(['pending','implemented'].includes(item.status),'Unknown implementation status');
+  assert.ok(Array.isArray(item.scenarioIds),'Implementation scenario IDs required');exact(item.scenarioIds,generation.scenarios.filter(s=>s.bindingId===binding.id).map(s=>s.id),'Implementation scenario coverage');
+  if(item.status==='pending'){pending++;continue;}
+  assert.ok(Array.isArray(item.components)&&item.components.length,'Implemented binding needs components');
+  for(const component of item.components)assert.ok(map.capabilities[binding.capabilityId].components.includes(component)||/^application:[A-Za-z][\w.-]*$/.test(component),`Undeclared framework component: ${component}`);
+  assert.ok(Array.isArray(item.files)&&item.files.length,'Implemented binding needs source files');
+  for(const source of item.files){
+   assert.ok(typeof source.path==='string'&&/^(?:app\/src\/|app\/public\/|mocks\/)/.test(source.path),'Implementation must reference actual application source');
+   nonempty(source.locator,'Implementation source locator');const file=inside(directory,source.path);assert.ok(fs.statSync(file).isFile(),'Implementation source must be a file');
+   assert.ok(fs.readFileSync(file,'utf8').includes(source.locator),`Implementation locator absent from source: ${source.path}`);
+  }
+ }
+ if(options.complete)assert.equal(pending,0,'Implementation pending; status alone cannot pass acceptance');
+ return {status:pending?'pending':'implemented',bindings:implementation.bindings.length,pending,invocationVerified:false};
+}
+function validateObservations(directory,generation,report){
+ const observations=report.generationObservations;assert.ok(Array.isArray(observations),'Generation observations required');
+ exact(observations.map(item=>item.scenarioId),generation.scenarios.map(item=>item.id),'Generation observation scenario coverage');
+ for(const scenario of generation.scenarios){
+  const item=observations.find(item=>item.scenarioId===scenario.id);assert.equal(item.bindingId,scenario.bindingId,'Observation binding differs');assert.equal(item.status,'passed','Generation observation must pass');
+  assert.ok(Array.isArray(item.steps)&&item.steps.length,'Actual generation observation steps required');
+  for(const step of item.steps)for(const key of ['action','target','observed'])nonempty(step[key],`Observation step ${key}`);
+  assert.ok(Array.isArray(item.toolCallIds)&&item.toolCallIds.length,'Observation needs actual host tool call locators');for(const call of item.toolCallIds)nonempty(call,'Tool call ID');
+  assert.ok(Array.isArray(item.evidence)&&item.evidence.length,'Observation evidence files required');
+  for(const evidence of item.evidence){assert.ok(typeof evidence.path==='string'&&evidence.path.startsWith('qa/'),'Observation evidence must be inside QA');const bytes=fs.readFileSync(inside(directory,evidence.path));assert.ok(bytes.length,'Observation evidence is empty');assert.equal(hash(bytes),evidence.sha256,'Observation evidence bytes changed');}
+ }
+ return {status:'passed',scenarios:observations.length,invocationVerified:false};
+}
+function designSummary(generation,previous=''){
+ const start='<!-- generation-choices:start -->',end='<!-- generation-choices:end -->';
+ const block=`${start}\n客户固定选择：布局 ${generation.presentation.layout}；风格 ${generation.presentation.style}；密度 ${generation.presentation.density}。四主题默认明亮；覆盖外壳、组件与浮层。未决能力 ${generation.pendingDecisions.length} 项；未决参考功能节点 ${generation.pendingReferenceElements.length} 项。当前依据为 inputs/generation.json。\n${end}`;
+ const first=previous.indexOf(start),last=previous.indexOf(end);
+ assert.ok((first===-1&&last===-1)||(first>=0&&last>first&&previous.indexOf(start,first+1)===-1&&previous.indexOf(end,last+1)===-1),'Ambiguous generation design markers; preserve the existing design');
+ return first===-1?`${previous.trimEnd()}\n\n${block}\n`:`${previous.slice(0,first)}${block}${previous.slice(last+end.length)}`;
+}
+module.exports={framework,initialize,validateImplementation,validateObservations,designSummary};

package/skills/i3-ui-prototype/scripts/generation-replan.cjs

@@ -0,0 +1,34 @@
+'use strict';
+const {fs,path,assert,json,inside,write}=require('./native-files.cjs');
+function run(directory,options,lib){
+ const meta=json(inside(directory,'prototype.json')),old=json(inside(directory,'inputs/scope.json'));
+ assert.equal(meta.runtime.generationContract,1,'Replan requires an existing generation contract; legacy inputs are not implicitly upgraded');assert.equal(old.schemaVersion,3);
+ const scope=json(path.resolve(options.scope));assert.equal(scope.schemaVersion,3,'Replan cannot downgrade the fixed generation contract');
+ const template=json(inside(directory,'inputs/template-snapshot.json')),fixed=json(inside(directory,'inputs/generation.json'));
+ const generation=require('./generation-contract.cjs').compile(template,scope,{definition:fixed.definition}),templates=require('./template-contract.cjs');
+ const selection=require('./content-template.cjs').scopeInputs(template,scope,templates);
+ const checked=templates.checkCapabilities({...selection.fixed,scope});assert.equal(checked.status,'passed',checked.errors?.join('; '));
+ const scenarioDetails=[...checked.requiredScenarios,...generation.scenarios];const previous=json(inside(directory,'inputs/acceptance.json'));
+ const drawer=generation.bindings.some(binding=>binding.capabilityId==='dialog'&&binding.parameters.presentation==='drawer');
+ const acceptance={...previous,requiredScenarios:scenarioDetails.map(item=>typeof item==='string'?item:item.id),scenarioDetails,frameworkScenarios:['framework-responsive','framework-instance-isolation','template-content-projection',...(drawer?['framework-drawer-motion','framework-mask-blur','framework-focus-scroll']:[])]};
+ const config=json(inside(directory,'app/public/prototype-config.json')),theme=selection.fixed.bindings.find(item=>item.capabilityId==='theme');
+ const changes={
+  'inputs/scope.json':scope,'inputs/generation.json':generation,'inputs/capabilities.json':selection.fixed,'inputs/acceptance.json':acceptance,
+  'requirements-map.json':{schemaVersion:2,requirements:scope.requirements.map(r=>({...r,scenarios:scenarioDetails.filter(s=>s.bindingId.startsWith('app-shell/')||r.pages.some(page=>s.bindingId.startsWith(page+'/'))).map(s=>s.id)})),bindings:[...selection.fixed.bindings,...generation.bindings]},
+  'app/public/prototype-config.json':{...config,pages:scope.pages.map(page=>({id:page.id,title:page.title})),presentation:generation.presentation,navigation:generation.navigation,generation:{pages:generation.pages},theme:templates.resolveThemeParameters(theme.parameters)},
+  'design-system/implementation.json':require('./generation-evidence.cjs').initialize(generation),
+  'design-system/MASTER.md':require('./generation-evidence.cjs').designSummary(generation,fs.readFileSync(inside(directory,'design-system/MASTER.md'),'utf8')),
+  'mocks/contract.json':{...json(inside(directory,'mocks/contract.json')),status:'needs-business-data',requirements:scope.requirements.map(item=>item.id)},
+  'prototype.json':{...meta,business:{...meta.business,status:'needs-adaptation'}}
+ };
+ // Retain implementation locations for review, but require re-attestation after input changes.
+ const implemented=json(inside(directory,'design-system/implementation.json'));
+ for(const item of changes['design-system/implementation.json'].bindings){const prior=implemented.bindings.find(entry=>entry.bindingId===item.bindingId);if(prior){item.components=prior.components;item.files=prior.files;}}
+ const backup=new Map(Object.keys(changes).map(file=>[file,fs.readFileSync(inside(directory,file))]));
+ try{
+  for(const [file,value]of Object.entries(changes))write(directory,file,value);
+  const current=lib.manifest(directory);
+  return lib.revise(directory,{owner:options.owner,revision:options.revision,expectedRevision:current.revision,expectedDigest:current.digest,acceptInputs:true});
+ }catch(error){for(const [file,bytes]of backup)fs.writeFileSync(inside(directory,file),bytes);throw error;}
+}
+module.exports={run};

package/skills/i3-ui-prototype/scripts/hosts/codebuddy.cjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+const fs=require('node:fs'),path=require('node:path');
+function main(argv=process.argv.slice(2),raw=fs.readFileSync(0,'utf8')) {
+ if(Buffer.byteLength(raw)>4*1024*1024)throw new Error('Hook input too large');
+ const options={};while(argv.length){const key=argv.shift();if(!key.startsWith('--')||!argv.length)throw new Error('Invalid Hook arguments');options[key.slice(2)]=argv.shift();}
+ const {OWNER,EVENTS}=require('../codebuddy-registration.cjs');
+ if(options.registration!==OWNER||!path.isAbsolute(options.base||'')||!EVENTS.includes(options.event)||!['ide','cli'].includes(options.product))throw new Error('Invalid Hook registration');
+ const result=require('../codebuddy-hook.cjs').handle(JSON.parse(raw),options);
+ if(result.deny)return {code:0,output:{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:result.reason}}};
+ if(result.feedback)return {code:2,output:{decision:'block',reason:result.reason}};
+ return {code:0,output:{continue:true}};
+}
+if(require.main===module)try{const result=main();process.stdout.write(JSON.stringify(result.output)+'\n');if(result.code===2)process.stderr.write(result.output.reason+'\n');process.exitCode=result.code;}
+catch(error){process.stderr.write(`i3 prototype audit unavailable: ${error.message}. Strict A gates remain unverified.\n`);process.exitCode=1;}
+module.exports={main};

package/skills/i3-ui-prototype/scripts/manage-baseline.cjs

@@ -5,7 +5,7 @@ try {
   const { options, positional } = lib.parseArgs(process.argv.slice(2));
   const [operation, directory] = positional;
   if (!directory || !['inspect', 'manifest', 'revise', 'confirm-baseline'].includes(operation)) throw new Error('Usage: manage-baseline.cjs <inspect|manifest|revise|confirm-baseline> <directory> [--revision r002] [--confirmation file.json]');
-  const result = operation === 'manifest' ? lib.contentManifest(directory) : operation === 'inspect' ? lib.compareBaseline(directory) : operation === 'revise' ? lib.revisePrototype(directory, options.revision) : lib.freezeBaseline(directory, JSON.parse(fs.readFileSync(options.confirmation, 'utf8')));
+  const result = operation === 'manifest' ? lib.contentManifest(directory) : operation === 'inspect' ? lib.compareBaseline(directory) : operation === 'revise' ? lib.revisePrototype(directory, options.revision, options) : lib.freezeBaseline(directory, JSON.parse(fs.readFileSync(options.confirmation, 'utf8')));
   process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   if (result.status === 'corrupt-baseline') process.exitCode = 1;
 } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }