@givolt/i3-composer-agent 2.2.3 → 2.3.1

package/scripts/design-provider-discovery-test.js

@@ -0,0 +1,190 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const childProcess = require('node:child_process');
+const installationFile = path.join(__dirname, 'lib/installation.js');
+const skillsDirectory = fs.existsSync(installationFile) ? require(installationFile).loadInstallation().skillsDirectory : path.resolve(__dirname, '../skills');
+const moduleFile = path.join(skillsDirectory, 'i3-ui-prototype/scripts/design-provider-discovery.cjs');
+
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-provider-discovery-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const home = path.join(root, 'home'), project = path.join(root, 'project');
+  fs.mkdirSync(home); fs.mkdirSync(project);
+  return { root, home, project, env: {} };
+}
+function write(file, value) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, typeof value === 'string' ? value : JSON.stringify(value)); }
+function skill(root) { write(path.join(root, 'SKILL.md'), '# Fixture UI/UX'); return root; }
+function discover(options, run = () => { throw new Error('Unexpected host CLI call'); }) {
+  const original = childProcess.spawnSync;
+  childProcess.spawnSync = run;
+  delete require.cache[require.resolve(moduleFile)];
+  let api;
+  try { api = require(moduleFile); } finally { childProcess.spawnSync = original; }
+  return api.discoverProviderCandidates(options);
+}
+function codexPlugin(f, overrides = {}) {
+  const record = { pluginId: 'ui-ux-pro-max@ui-ux-pro-max-skill', name: 'ui-ux-pro-max', marketplaceName: 'ui-ux-pro-max-skill', version: '2.15.0', installed: true, enabled: true, ...overrides };
+  const cache = path.join(f.env.CODEX_HOME || path.join(f.home, '.codex'), 'plugins/cache/ui-ux-pro-max-skill/ui-ux-pro-max', record.version);
+  if (!record.version.includes('..')) {
+    write(path.join(cache, '.claude-plugin/plugin.json'), { name: 'ui-ux-pro-max', version: record.version, skills: './.claude/skills/' });
+    skill(path.join(cache, '.claude/skills/ui-ux-pro-max'));
+  }
+  return { record, cache, run: () => ({ status: 0, stdout: JSON.stringify({ installed: [record], available: [] }) }) };
+}
+function registryPlugin(f, host, records, enabled = true) {
+  const config = path.join(f.home, `.${host}`), id = 'ui-ux-pro-max@fixture-market';
+  write(path.join(config, 'settings.json'), { enabledPlugins: { [id]: enabled } });
+  write(path.join(config, 'plugins/installed_plugins.json'), { version: 2, plugins: { [id]: records } });
+  for (const record of records) {
+    write(path.join(record.installPath, host === 'claude' ? '.claude-plugin/plugin.json' : '.codebuddy-plugin/plugin.json'), { name: 'ui-ux-pro-max', version: record.version, ...(host === 'claude' ? { skills: './.claude/skills/' } : {}) });
+    skill(path.join(record.installPath, host === 'claude' ? '.claude/skills/ui-ux-pro-max' : 'skills/ui-ux-pro-max'));
+  }
+  return config;
+}
+
+test('explicit provider has precedence over host roots and does not invoke discovery', t => {
+  const f = fixture(t), root = path.join(f.root, 'explicit');
+  assert.deepEqual(discover({ ...f, provider: root, providerRoots: ['/ignored'], host: 'codex' }), { candidates: [{ root, source: 'explicit' }], diagnostics: [] });
+});
+test('host-exposed provider roots work without host context and preserve order', t => {
+  const f = fixture(t), roots = [path.join(f.root, 'first'), path.join(f.root, 'second')];
+  assert.deepEqual(discover({ ...f, providerRoots: roots }).candidates.map(c => c.root), roots);
+  assert.equal(discover({ ...f, providerRoots: [] }).contextRequired, undefined);
+});
+test('unknown host requires context and cannot read another host cache', t => {
+  const f = fixture(t); skill(path.join(f.home, '.claude/skills/ui-ux-pro-max'));
+  assert.equal(discover(f).contextRequired, true);
+  assert.equal(discover({ ...f, host: 'unknown' }).contextRequired, true);
+  assert.deepEqual(discover({ ...f, host: 'unknown' }).candidates, []);
+});
+test('discover false prevents automatic host access', t => {
+  const f = fixture(t); skill(path.join(f.home, '.agents/skills/ui-ux-pro-max'));
+  assert.deepEqual(discover({ ...f, host: 'codex', discover: false }), { candidates: [], diagnostics: [], contextRequired: true });
+});
+test('Codex returns project then global skill locations and the exact enabled plugin version', t => {
+  const f = fixture(t), plugin = codexPlugin(f);
+  const project = skill(path.join(f.project, '.agents/skills/ui-ux-pro-max'));
+  const global = skill(path.join(f.home, '.codex/skills/ui-ux-pro-max'));
+  const stale = path.join(f.home, '.codex/plugins/cache/ui-ux-pro-max-skill/ui-ux-pro-max/99.0.0/.claude/skills/ui-ux-pro-max'); skill(stale);
+  let command;
+  const result = discover({ ...f, host: 'codex' }, (...args) => { command = args; return plugin.run(); });
+  assert.deepEqual(result.candidates.map(c => c.root), [project, global, path.join(plugin.cache, '.claude/skills/ui-ux-pro-max')]);
+  assert.equal(command[0], 'codex');
+  assert.deepEqual(command[1], ['plugin', 'list', '--marketplace', 'ui-ux-pro-max-skill', '--json']);
+  assert.ok(command[2].timeout > 0 && command[2].timeout <= 15000);
+  assert.equal(command[2].shell, false);
+});
+test('Codex honors isolated CODEX_HOME and never scans the default cache', t => {
+  const f = fixture(t); f.env.CODEX_HOME = path.join(f.root, 'custom-codex');
+  const plugin = codexPlugin(f);
+  const result = discover({ ...f, host: 'codex' }, plugin.run);
+  assert.equal(result.candidates.at(-1).root, path.join(plugin.cache, '.claude/skills/ui-ux-pro-max'));
+});
+test('Codex disabled cached plugin is not a candidate', t => {
+  const f = fixture(t), plugin = codexPlugin(f, { enabled: false });
+  const result = discover({ ...f, host: 'codex' }, plugin.run);
+  assert.deepEqual(result.candidates, []);
+  assert.equal(result.diagnostics[0].availability, 'disabled');
+});
+test('Codex missing installation does not inspect cached versions', t => {
+  const f = fixture(t); codexPlugin(f);
+  const result = discover({ ...f, host: 'codex' }, () => ({ status: 0, stdout: '{"installed":[],"available":[]}' }));
+  assert.deepEqual(result.candidates, []);
+  assert.ok(result.diagnostics.every(d => d.availability === 'missing'));
+});
+for (const [name, run] of [
+  ['missing CLI', () => ({ status: null, error: { code: 'ENOENT' }, stdout: '' })],
+  ['failed CLI', () => ({ status: 1, stderr: 'failure', stdout: '' })],
+  ['invalid JSON', () => ({ status: 0, stdout: '{bad' })],
+  ['invalid schema', () => ({ status: 0, stdout: '{}' })],
+]) test(`Codex ${name} is a discovery error, not a missing installation`, t => {
+  const f = fixture(t), result = discover({ ...f, host: 'codex' }, run);
+  assert.equal(result.diagnostics[0].availability, 'discovery-error');
+});
+test('Codex rejects multiple active installed records instead of selecting a version', t => {
+  const f = fixture(t), { record } = codexPlugin(f);
+  const result = discover({ ...f, host: 'codex' }, () => ({ status: 0, stdout: JSON.stringify({ installed: [record, { ...record, version: '2.14.0' }] }) }));
+  assert.deepEqual(result.candidates, []);
+  assert.equal(result.diagnostics[0].availability, 'ambiguous');
+});
+for (const [name, change] of [
+  ['wrong manifest version', m => { m.version = '2.14.0'; }],
+  ['wrong manifest name', m => { m.name = 'different'; }],
+  ['escaping skills declaration', m => { m.skills = '../../../outside'; }],
+  ['missing skills declaration', m => { delete m.skills; }],
+]) test(`Codex rejects ${name}`, t => {
+  const f = fixture(t), plugin = codexPlugin(f), file = path.join(plugin.cache, '.claude-plugin/plugin.json');
+  const manifest = JSON.parse(fs.readFileSync(file)); change(manifest); write(file, manifest);
+  const result = discover({ ...f, host: 'codex' }, plugin.run);
+  assert.deepEqual(result.candidates, []);
+  assert.equal(result.diagnostics[0].availability, 'discovery-error');
+});
+test('Codex validates the active version as a single safe path segment', t => {
+  const f = fixture(t), plugin = codexPlugin(f, { version: '../../escape' });
+  assert.equal(discover({ ...f, host: 'codex' }, plugin.run).diagnostics[0].availability, 'discovery-error');
+});
+test('Codex rejects a child skill symlink escaping the registered plugin root', t => {
+  const f = fixture(t), plugin = codexPlugin(f), outside = skill(path.join(f.root, 'outside'));
+  const child = path.join(plugin.cache, '.claude/skills/ui-ux-pro-max');
+  fs.rmSync(child, { recursive: true }); fs.symlinkSync(outside, child, 'dir');
+  const result = discover({ ...f, host: 'codex' }, plugin.run);
+  assert.deepEqual(result.candidates, []);
+  assert.equal(result.diagnostics[0].availability, 'discovery-error');
+});
+for (const host of ['claude', 'workbuddy', 'codebuddy']) test(`${host} selects only enabled registered plugins`, t => {
+  const f = fixture(t), installPath = path.join(f.root, host, 'plugin');
+  registryPlugin(f, host, [{ scope: 'user', installPath, version: '2.0.0' }]);
+  const result = discover({ ...f, host });
+  assert.deepEqual(result.candidates.map(c => c.root), [path.join(installPath, host === 'claude' ? '.claude/skills/ui-ux-pro-max' : 'skills/ui-ux-pro-max')]);
+  registryPlugin(f, host, [{ scope: 'user', installPath, version: '2.0.0' }], false);
+  const disabled = discover({ ...f, host });
+  assert.deepEqual(disabled.candidates, []); assert.equal(disabled.diagnostics[0].availability, 'disabled');
+});
+test('missing optional registry is normal, while corrupt metadata is an error', t => {
+  const f = fixture(t);
+  assert.ok(discover({ ...f, host: 'workbuddy' }).diagnostics.every(d => d.availability === 'missing'));
+  write(path.join(f.home, '.workbuddy/plugins/installed_plugins.json'), '{invalid');
+  assert.equal(discover({ ...f, host: 'workbuddy' }).diagnostics[0].availability, 'discovery-error');
+});
+test('a registered plugin with missing enablement metadata needs diagnosis instead of installation', t => {
+  const f = fixture(t);
+  const config = registryPlugin(f, 'workbuddy', [{ scope: 'user', installPath: path.join(f.root, 'plugin'), version: '2.0.0' }]);
+  fs.unlinkSync(path.join(config, 'settings.json'));
+  const result = discover({ ...f, host: 'workbuddy' });
+  assert.deepEqual(result.candidates, []);
+  assert.equal(result.diagnostics[0].availability, 'discovery-error');
+});
+test('project plugin scope must match the current project path', t => {
+  const f = fixture(t), installPath = path.join(f.root, 'plugin');
+  registryPlugin(f, 'claude', [{ scope: 'project', projectPath: path.join(f.root, 'other-project'), installPath, version: '2.0.0' }]);
+  assert.deepEqual(discover({ ...f, host: 'claude-code' }).candidates, []);
+  registryPlugin(f, 'claude', [{ scope: 'project', projectPath: f.project, installPath, version: '2.0.0' }]);
+  assert.equal(discover({ ...f, host: 'claude-code' }).candidates.length, 1);
+  registryPlugin(f, 'claude', [{ scope: 'project', installPath, version: '2.0.0' }]);
+  assert.deepEqual(discover({ ...f, host: 'claude-code' }).candidates, []);
+});
+test('ambiguous matching registry entries do not pick one arbitrarily', t => {
+  const f = fixture(t);
+  registryPlugin(f, 'workbuddy', [
+    { scope: 'user', installPath: path.join(f.root, 'first'), version: '2.0.0' },
+    { scope: 'user', installPath: path.join(f.root, 'second'), version: '2.1.0' },
+  ]);
+  const result = discover({ ...f, host: 'workbuddy' });
+  assert.deepEqual(result.candidates, []); assert.equal(result.diagnostics[0].availability, 'ambiguous');
+});
+test('host selection never borrows another host global plugin', t => {
+  const f = fixture(t);
+  registryPlugin(f, 'claude', [{ scope: 'user', installPath: path.join(f.root, 'claude'), version: '2.0.0' }]);
+  registryPlugin(f, 'workbuddy', [{ scope: 'user', installPath: path.join(f.root, 'workbuddy'), version: '2.0.0' }]);
+  assert.deepEqual(discover({ ...f, host: 'codebuddy' }).candidates, []);
+});
+test('WorkBuddy uses its global config override and the project CodeBuddy skills directory', t => {
+  const f = fixture(t); f.env.WORKBUDDY_CONFIG_DIR = path.join(f.root, 'custom-workbuddy');
+  const projectRoot = skill(path.join(f.project, '.codebuddy/skills/ui-ux-pro-max'));
+  const globalRoot = skill(path.join(f.env.WORKBUDDY_CONFIG_DIR, 'skills/ui-ux-pro-max'));
+  assert.deepEqual(discover({ ...f, host: 'workbuddy' }).candidates.map(c => c.root), [projectRoot, globalRoot]);
+});

package/scripts/design-provider-test.js

@@ -0,0 +1,68 @@
+'use strict';
+const { test, mock } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const cp = require('node:child_process');
+mock.method(cp, 'spawnSync', (command, args) => {
+  if (!args.includes('--json') || args[0] !== '-B') return { status: 1, stdout: '', stderr: 'No plugin CLI in isolated test' };
+  if (args[1].includes('query-fails')) return { status: 1, stdout: '', stderr: 'Python module unavailable' };
+  return { status: 0, stdout: JSON.stringify({ domain: 'ux', results: [{ name: 'Error summary' }] }), stderr: '' };
+});
+const installationFile = path.join(__dirname, 'lib/installation.js');
+const skillsDirectory = fs.existsSync(installationFile) ? require(installationFile).loadInstallation().skillsDirectory : path.resolve(__dirname, '../skills');
+const lib = require(path.join(skillsDirectory, 'i3-ui-prototype/scripts/prototype-lib.cjs'));
+function fixture(t) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-provider-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+}
+function provider(home, name) {
+  const root = path.join(home, name);
+  for (const file of ['SKILL.md', 'scripts/search.py', 'scripts/core.py', 'scripts/design_system.py', ...['ux-guidelines', 'styles', 'colors', 'typography', 'products', 'landing', 'ui-reasoning'].map(name => `data/${name}.csv`)]) {
+    fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+    fs.writeFileSync(path.join(root, file), 'fixture');
+  }
+  return root;
+}
+test('an incomplete project provider does not shadow a usable global provider', t => {
+  const home = fixture(t), local = path.join(home, 'project-provider'), global = provider(home, 'global-provider');
+  fs.mkdirSync(local);
+  const result = lib.checkDesignProvider({ providerRoots: [local, global] });
+  assert.equal(result.availability, 'available');
+  assert.equal(result.root, global);
+  assert.equal(result.attempts[0].availability, 'unusable');
+  assert.ok(result.attempts[0].missing.includes('scripts/search.py'));
+});
+test('a failed project query does not shadow a usable global provider', t => {
+  const home = fixture(t), local = provider(home, 'query-fails'), global = provider(home, 'global-provider');
+  const result = lib.checkDesignProvider({ providerRoots: [local, global] });
+  assert.equal(result.availability, 'available');
+  assert.equal(result.root, global);
+  assert.match(result.attempts[0].reason, /Python module unavailable/);
+});
+test('an explicit provider failure never silently selects a different provider', t => {
+  const home = fixture(t), selected = path.join(home, 'missing'), other = provider(home, 'other');
+  const result = lib.checkDesignProvider({ provider: selected, providerRoots: [other] });
+  assert.equal(result.availability, 'missing');
+  assert.deepEqual(result.searched, [selected]);
+});
+test('without host or provider the result requests context, not installation', t => {
+  const home = fixture(t);
+  const result = lib.initPrototype({ project: home, id: 'demo', home, env: {} });
+  assert.equal(result.provider.availability, 'needs-context');
+  assert.equal(result.choices[0].id, 'locate');
+  assert.ok(!result.choices.some(choice => choice.id === 'install'));
+  assert.equal(fs.existsSync(path.join(home, 'prototypes')), false);
+});
+test('all unusable providers preserve their individual failure reasons without asking to reinstall', t => {
+  const home = fixture(t), incomplete = path.join(home, 'incomplete'), failing = provider(home, 'query-fails');
+  fs.mkdirSync(incomplete);
+  const result = lib.initPrototype({ project: home, id: 'demo', providerRoots: [incomplete, failing] });
+  assert.equal(result.provider.availability, 'unusable');
+  assert.equal(result.provider.attempts.length, 2);
+  assert.equal(result.choices[0].id, 'repair');
+  assert.ok(!result.choices.some(choice => choice.id === 'install'));
+  assert.equal(fs.existsSync(path.join(home, 'prototypes')), false);
+});

package/scripts/enterprise-template-test.js

@@ -0,0 +1,179 @@
+'use strict';
+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 crypto = require('node:crypto');
+const { spawn, spawnSync } = require('node:child_process');
+const install = path.join(__dirname, 'lib/installation.js');
+const skills = fs.existsSync(install) ? require(install).loadInstallation().skillsDirectory : path.resolve(__dirname, '../skills');
+const skill = path.join(skills, 'i3-ui-prototype');
+const lib = require(path.join(skill, 'scripts/prototype-lib.cjs'));
+const enterprise = require(path.join(skill, 'scripts/enterprise-template.cjs'));
+const read = (root, file) => JSON.parse(fs.readFileSync(path.join(root, file), 'utf8'));
+function project(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'enterprise-template-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  return root;
+}
+function initialize(t, options = {}) {
+  return lib.initPrototype({ project: project(t), id: 'enterprise-demo', expertMode: 'template', purpose: 'template-review', ...options }).directory;
+}
+test('runtime branding changes uppercase product text only in runtime HTML and JavaScript', () => {
+  const source = 'EASEL easel-html /easel EASEL 研发';
+  for (const file of ['index.html', 'src/shell/ConsoleShell.html', 'src/models/data.js']) {
+    assert.equal(enterprise.brandRuntimeResource(file, source), 'i3-Composer easel-html /easel i3-Composer 研发');
+  }
+  for (const file of ['origin.json', 'licenses/EASEL.txt', 'qa/REVIEW.md', 'src/styles.css', 'tests/behavior.js', 'app.js']) {
+    const bytes = Buffer.from(source);
+    assert.equal(enterprise.brandRuntimeResource(file, bytes), bytes, file);
+  }
+  assert.ok(Buffer.isBuffer(enterprise.brandRuntimeResource('src/models/data.js', Buffer.from(source))));
+});
+test('generated enterprise runtime uses i3-Composer branding with one final adaptation record per changed source', t => {
+  const dir = initialize(t, { title: 'i3-Composer 品牌验收' });
+  const shell = fs.readFileSync(path.join(dir, 'app/src/shell/ConsoleShell.html'), 'utf8');
+  assert.match(shell, /<strong>i3-Composer<\/strong>/);
+  assert.doesNotMatch(shell, /EASEL/);
+  assert.match(fs.readFileSync(path.join(dir, 'app/index.html'), 'utf8'), /<title>i3-Composer/);
+  const models = fs.readFileSync(path.join(dir, 'app/src/models/data.js'), 'utf8');
+  assert.match(models, /i3-Composer 研发/);
+  assert.doesNotMatch(models, /EASEL/);
+  assert.match(fs.readFileSync(path.join(dir, 'app/src/permissions/MemberEditor.html'), 'utf8'), /i3-Composer 业务角色/);
+  assert.doesNotMatch(read(dir, 'requirements-map.json').scope, /EASEL/);
+  assert.doesNotMatch(fs.readFileSync(path.join(dir, 'mocks/README.md'), 'utf8'), /EASEL/);
+  const origin = enterprise.verifyReference(), source = read(dir, 'design-system/source.json');
+  assert.equal(origin.fileCount, 326);
+  assert.equal(new Set(source.adaptations.map(record => record.file)).size, source.adaptations.length);
+  const adapted = new Map(source.adaptations.map(record => [record.file, record]));
+  for (const [file, expected] of Object.entries(origin.files)) {
+    const generated = crypto.createHash('sha256').update(fs.readFileSync(path.join(dir, 'app', file))).digest('hex');
+    if (generated === expected) continue;
+    const record = adapted.get(file);
+    assert.ok(record, `Unrecorded runtime adaptation: ${file}`);
+    assert.equal(record.source, expected, file);
+    assert.equal(record.generated, generated, file);
+    assert.ok(record.reason, file);
+  }
+  assert.match(adapted.get('index.html').reason, /i3-Composer/);
+  assert.match(adapted.get('src/models/data.js').reason, /i3-Composer/);
+});
+test('four prototype families expose the EASEL enterprise template and explicitly defer the other three', () => {
+  const entries = lib.listTemplates();
+  assert.deepEqual(entries.map(x => x.id), ['enterprise-admin', 'ai-workbench', 'digital-twin', 'mobile-app']);
+  assert.deepEqual(entries.filter(x => x.availability === 'available').map(x => x.id), ['enterprise-admin']);
+  for (const entry of entries.slice(1)) assert.equal(entry.availability, 'planned');
+});
+test('default enterprise initializer preserves the complete EASEL runtime and its review scope', t => {
+  const dir = initialize(t), metadata = read(dir, 'prototype.json');
+  assert.equal(metadata.template.id, 'enterprise-admin');
+  assert.equal(metadata.purpose, 'template-review');
+  assert.equal(metadata.review.status, 'pending-review');
+  const inspection = lib.checkPrototype(dir);
+  assert.equal(inspection.status, 'passed', JSON.stringify(inspection));
+  const routes = read(dir, 'app/routes.json').filter(x => x.component && !x.path.startsWith('/module/'));
+  assert.equal(routes.length, 37);
+  assert.equal(new Set(routes.map(x => x.component)).size, 34);
+  for (const file of ['app/runtime/dom.js', 'app/styles/antdv.css', 'app/src/shell/ConsoleShell.html', 'app/licenses/antdv-next.txt', 'design-system/source.json']) {
+    assert.ok(fs.existsSync(path.join(dir, file)), file);
+  }
+});
+test('planned template families refuse initialization without silently generating a desktop demo', t => {
+  const root = project(t);
+  for (const template of ['ai-workbench', 'digital-twin', 'mobile-app']) {
+    assert.throws(() => lib.initPrototype({ project: root, id: template, template, expertMode: 'template' }), /planned|尚未|待建设/);
+  }
+  assert.equal(fs.existsSync(path.join(root, 'prototypes')), false);
+});
+test('all imported reference files retain their declared source hashes', () => {
+  const origin = read(skill, 'assets/templates/enterprise-admin/origin.json');
+  assert.equal(Object.keys(origin.files).length, 326);
+  for (const [file, expected] of Object.entries(origin.files)) {
+    const contents = fs.readFileSync(path.join(skill, 'assets/templates/enterprise-admin/reference', origin.storagePaths?.[file] || file));
+    assert.equal(crypto.createHash('sha256').update(contents).digest('hex'), expected, file);
+  }
+});
+test('an unadapted EASEL example cannot pass new-business acceptance', t => {
+  const dir = initialize(t, { purpose: 'business-prototype' });
+  assert.equal(read(dir, 'prototype.json').business.status, 'needs-adaptation');
+  assert.match(lib.checkPrototype(dir, { acceptance: true }).errors.join(' '), /业务|adapt/);
+});
+test('generated enterprise instances isolate their local demo storage and retain the original route behavior', t => {
+  const dir = initialize(t);
+  const source = fs.readFileSync(path.join(dir, 'app/src/shared/session.js'), 'utf8');
+  assert.match(source, /i3-enterprise-enterprise-demo-/);
+  assert.doesNotMatch(source, /i3-prototype-antdv-/);
+  assert.match(fs.readFileSync(path.join(dir, 'app/index.html'), 'utf8'), /enterprise-bootstrap\.mjs/);
+  assert.match(fs.readFileSync(path.join(dir, 'app/index.html'), 'utf8'), /tokens\.css/);
+  const other = initialize(t);
+  assert.notEqual(read(dir, 'prototype.json').runtime.storagePrefix, read(other, 'prototype.json').runtime.storagePrefix);
+});
+test('missing enterprise runtime imports are rejected while declarative data-bind attributes remain valid', t => {
+  const dir = initialize(t);
+  assert.equal(lib.checkPrototype(dir).status, 'passed');
+  fs.unlinkSync(path.join(dir, 'app/runtime/controls.js'));
+  const result = lib.checkPrototype(dir);
+  assert.equal(result.status, 'failed');
+  assert.match(result.errors.join(' '), /controls\.js/);
+});
+test('tampered template source assets are rejected before a new instance can be trusted', t => {
+  const temp = project(t);
+  const copy = path.join(temp, 'enterprise-admin');
+  fs.cpSync(path.join(skill, 'assets/templates/enterprise-admin'), copy, { recursive: true });
+  fs.appendFileSync(path.join(copy, 'reference/styles/app.css'), '\n/* unexpected source edit */');
+  const { verifyReference } = require(path.join(skill, 'scripts/enterprise-template.cjs'));
+  assert.throws(() => verifyReference(copy), /integrity|来源完整性/);
+});
+test('enterprise preview serves JavaScript modules and SVG assets with browser-compatible MIME types', async t => {
+  const dir = initialize(t);
+  const child = spawn(process.execPath, ['app/serve.cjs'], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] });
+  t.after(() => child.kill());
+  const url = await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Preview start timed out')), 5000);
+    child.stdout.on('data', data => { const match = data.toString().match(/http:\/\/127\.0\.0\.1:\d+\//); if (match) { clearTimeout(timer); resolve(match[0]); } });
+    child.once('error', reject);
+  });
+  const js = await fetch(url + 'app/app.js');
+  assert.equal(js.status, 200);
+  assert.match(js.headers.get('content-type'), /javascript/);
+  const svg = await fetch(url + 'app/assets/empty.svg');
+  assert.equal(svg.status, 200);
+  assert.match(svg.headers.get('content-type'), /image\/svg\+xml/);
+});
+test('gallery and generated enterprise instances deliver the same scrolling adapter while retaining the complete reference', t => {
+  const dir = initialize(t);
+  const css = fs.readFileSync(path.join(dir, 'app/usability.css'));
+  assert.equal(css.compare(fs.readFileSync(path.join(skill, 'assets/templates/enterprise-admin/usability.css'))), 0);
+  assert.match(fs.readFileSync(path.join(dir, 'app/index.html'), 'utf8'), /href="usability\.css"/);
+  const preview = lib.listTemplates()[0].preview.split('#')[0];
+  const entry = path.join(skill, 'assets/templates', preview);
+  assert.notEqual(preview, 'enterprise-admin/reference/index.html');
+  const html = fs.readFileSync(entry, 'utf8');
+  assert.match(html, /href="usability\.css"/);
+  for (const match of html.matchAll(/(?:src|href)="([^"#]+)"/g)) {
+    if (match[1].startsWith('data:')) continue;
+    assert.ok(fs.existsSync(path.resolve(path.dirname(entry), match[1])), match[1]);
+  }
+  const { verifyReference } = require(path.join(skill, 'scripts/enterprise-template.cjs'));
+  assert.equal(verifyReference().fileCount, 326);
+});
+test('scrolling behavior remains protected after an enterprise baseline is confirmed', t => {
+  const dir = initialize(t);
+  // Unit fixture only: these records exercise the baseline guard and do not
+  // claim real browser execution or human acceptance of a delivered prototype.
+  fs.writeFileSync(path.join(dir, 'qa/unit-fixture.txt'), 'UNIT FIXTURE ONLY');
+  const manifest = lib.contentManifest(dir);
+  const scenarios = new Set(read(dir, 'requirements-map.json').requirements.flatMap(x => x.scenarios));
+  fs.writeFileSync(path.join(dir, 'qa/browser.json'), JSON.stringify({
+    ...manifest, status: 'passed', source: 'UNIT FIXTURE ONLY', consoleErrors: [],
+    screenshots: ['qa/unit-fixture.txt'], viewports: [390, 1440],
+    journeys: [...scenarios].map(id => ({ id, status: 'passed' })),
+  }));
+  lib.freezeBaseline(dir, { revision: manifest.revision, digest: manifest.digest, reviewer: 'unit fixture', statement: 'UNIT FIXTURE ONLY', source: 'test fixture' });
+  fs.appendFileSync(path.join(dir, 'app/usability.css'), '\n/* changed scrolling behavior */\n');
+  assert.ok(lib.compareBaseline(dir).protectedChanges.includes('app/usability.css'));
+  const guard = spawnSync(process.execPath, [path.join(skill, 'scripts/check-prototype.cjs'), dir, '--enforce-baseline'], { encoding: 'utf8' });
+  assert.equal(guard.status, 1);
+  assert.match(guard.stdout, /Design constraints changed/);
+});

package/scripts/lib/skill-lint-test.js

@@ -9,7 +9,7 @@ const fs   = require('node:fs');
 const os   = require('node:os');
 const path = require('node:path');
 
-const { lintSkillContent, lintSkillLayout, topLevelFrontmatterKeys } = require('./skill-lint.js');
+const { lintSkillContent, lintSkillLayout, topLevelFrontmatterKeys, parseFrontmatter, frontmatterYamlErrors, lintPersonaContent } = require('./skill-lint.js');
 
 const KNOWN = new Set(['alpha', 'beta']);
 
@@ -648,3 +648,115 @@ test('the spec-key check tolerates CRLF frontmatter', () => {
   const { errors } = lintSkillContent('alpha', content, KNOWN);
   assert.equal(errors.filter(e => /key 'temperature'/.test(e)).length, 1);
 });
+
+test('parseFrontmatter ignores comments and nested metadata keys', () => {
+  const content = [
+    '---',
+    'name: alpha',
+    '# note: this is a comment',
+    'description: Designs alphas. Use when building one.',
+    'metadata:',
+    '  name: beta',
+    '  description: Nested details without trigger',
+    '---',
+    '',
+  ].join('\n');
+  assert.deepEqual(parseFrontmatter(content), {
+    name: 'alpha',
+    description: 'Designs alphas. Use when building one.',
+    metadata: '',
+  });
+});
+
+test('frontmatterYamlErrors ignores comment lines containing colons or quotes', () => {
+  const content = [
+    '---',
+    'name: alpha',
+    '# note: a comment: with a colon and "unclosed quote',
+    'description: "Designs alphas. Use when building one."',
+    '---',
+    '',
+  ].join('\n');
+  assert.deepEqual(frontmatterYamlErrors(content), []);
+});
+
+test('a skill with frontmatter comments and nested metadata passes validation', () => {
+  const content = withAllSections([
+    '---',
+    'name: alpha',
+    '# Note: keep description up to date: check docs',
+    'description: Designs alphas. Use when building one.',
+    'metadata:',
+    '  name: beta',
+    '  description: Internal notes',
+    '---',
+  ].join('\n'));
+  const { errors } = lintSkillContent('alpha', content, KNOWN);
+  assert.deepEqual(errors, []);
+});
+
+// ─── Personas (agents/<name>.md) ─────────────────────────────────────────────
+//
+// docs/agents.md: same frontmatter format as a skill, name equal to the file
+// stem, and the file ends with a Composition block. Nothing more is checked.
+
+function personaFile({ name = 'code-reviewer', description = 'Reviews changes. Use before merging.', body } = {}) {
+  const fm = ['---', name === null ? null : `name: ${name}`, description === null ? null : `description: ${description}`, '---']
+    .filter(l => l !== null).join('\n');
+  return `${fm}\n\n${body ?? '# Persona\n\n## Rules\n\nBe precise.\n\n## Composition\n\n- **Invoke via:** `/ship`.\n'}`;
+}
+
+test('a conforming persona produces no errors', () => {
+  assert.deepEqual(lintPersonaContent('code-reviewer', personaFile()).errors, []);
+});
+
+test('persona: frontmatter name must match the file stem', () => {
+  const { errors } = lintPersonaContent('code-reviewer', personaFile({ name: 'reviewer' }));
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /name 'reviewer' does not match file name 'code-reviewer'/);
+});
+
+test('persona: description is required', () => {
+  const { errors } = lintPersonaContent('code-reviewer', personaFile({ description: null }));
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /missing required field: 'description'/);
+});
+
+test('persona: a missing frontmatter block is reported and nothing else is attempted', () => {
+  const { errors } = lintPersonaContent('code-reviewer', '# Persona\n\n## Composition\n');
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /Missing or malformed YAML frontmatter/);
+});
+
+test('persona: frontmatter a host would reject as YAML is reported', () => {
+  const { errors } = lintPersonaContent('code-reviewer', personaFile({ description: 'Reviews: everything. Use before merging.' }));
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /Frontmatter line/);
+});
+
+test('persona: the Composition section is required', () => {
+  const { errors } = lintPersonaContent('code-reviewer', personaFile({ body: '# Persona\n\n## Rules\n\nBe precise.\n' }));
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /Missing "## Composition" section/);
+});
+
+test('persona: Composition must be the last section', () => {
+  const { errors } = lintPersonaContent('code-reviewer', personaFile({
+    body: '# Persona\n\n## Composition\n\n- **Invoke via:** `/ship`.\n\n## Output Format\n\nA report.\n',
+  }));
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /must be the last section, but "## Output Format" follows it/);
+});
+
+test('persona: a heading inside a fenced example after Composition is not a later section', () => {
+  const body = [
+    '# Persona', '', '## Composition', '', '- **Invoke via:** `/ship`. Report in this shape:', '',
+    '```markdown', '## Review: [title]', 'Findings…', '```', '',
+  ].join('\n');
+  assert.deepEqual(lintPersonaContent('code-reviewer', personaFile({ body })).errors, []);
+});
+
+test('persona: the Composition heading match is case-insensitive and tolerates trailing spaces', () => {
+  const body = '# Persona\n\n## composition   \n\n- **Invoke via:** `/ship`.\n';
+  assert.deepEqual(lintPersonaContent('code-reviewer', personaFile({ body })).errors, []);
+});