@flancer32/skill-adsm-ctx 0.2.1

package/test/unit/Validate/Service.test.mjs

@@ -0,0 +1,760 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import Service from '../../../src/Validate/Service.mjs';
+
+const constants = {
+  CONTEXT_SCHEMA: 'adsm-context',
+  DOC_LEVELS: ['product', 'architecture', 'environment', 'code'],
+  REQUIRED_PATHS: ['ctx', 'ctx/docs', 'ctx/adsm.json'],
+  SKIN_WORD_WARN: 160,
+  SKIN_WORD_ERROR: 240,
+  SKIN_LIST_WARN: 12,
+  SKIN_LIST_ERROR: 20,
+  DOC_LEVEL_MAX_DIRECTORIES: 9,
+  DOC_LEVEL_MAX_FILES: 9,
+};
+
+test('Validate service returns ok for matching metadata', async () => {
+  const fs = {
+    existsSync: (path) => [
+      '/project/ctx',
+      '/project/ctx/docs',
+      '/project/ctx/docs/product',
+      '/project/ctx/docs/architecture',
+      '/project/ctx/docs/environment',
+      '/project/ctx/docs/code',
+      '/project/ctx/adsm.json',
+    ].includes(path),
+    readFileSync: (filePath) => filePath.endsWith('adsm.json') ? '{"schema":"adsm-context","version":"0.1.0"}' : '',
+    readdirSync: (dirPath) => {
+      if (dirPath === '/project/ctx/docs') return dirents(['product', 'architecture', 'environment', 'code'], 'dir');
+      return [];
+    },
+  };
+  const service = new Service({
+    constants,
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.equal(result.errorCount, 0);
+  assert.equal(result.warningCount, 0);
+  assert.equal(result.metadata.version, '0.1.0');
+});
+
+test('Validate service reports missing paths and schema mismatch as errors', async () => {
+  const fs = {
+    existsSync: (path) => path === '/project/ctx/adsm.json',
+    readFileSync: () => '{"schema":"wrong","version":"0.1.0"}',
+    readdirSync: () => [],
+  };
+  const service = new Service({
+    constants,
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  assert.match(formatFindings(result.findings), /Missing: ctx/);
+  assert.match(formatFindings(result.findings), /Unexpected schema: wrong/);
+  assert.equal(result.findings.every((entry) => entry.severity === 'error'), true);
+});
+
+test('Validate service recognizes body and skin pairs recursively', async () => {
+  const files = {
+    '/project/ctx/docs/product/AGENTS.md': doc({
+      path: 'ctx/docs/product/AGENTS.md',
+      body: '## Purpose\n\nProduct routing.\n',
+    }),
+    '/project/ctx/docs/product/domain/ingress.md': doc({
+      path: 'ctx/docs/product/domain/ingress.md',
+      body: '## Purpose\n\nIngress context.\n',
+    }),
+    '/project/ctx/docs/product/domain/ingress.skin.en.md': skin({
+      path: 'ctx/docs/product/domain/ingress.skin.en.md',
+      agentDocument: 'ingress.md',
+    }),
+    '/project/ctx/docs/product/domain/memory.skin.en.md': skin({
+      path: 'ctx/docs/product/domain/memory.skin.en.md',
+      agentDocument: 'memory.md',
+    }),
+  };
+  const fs = {
+    existsSync: (filePath) => [
+      '/project/ctx',
+      '/project/ctx/docs',
+      '/project/ctx/docs/product',
+      '/project/ctx/docs/architecture',
+      '/project/ctx/docs/environment',
+      '/project/ctx/docs/code',
+      '/project/ctx/assets',
+      '/project/ctx/adsm.json',
+    ].includes(filePath),
+    readFileSync: (filePath) => filePath.endsWith('adsm.json')
+      ? '{"schema":"adsm-context","version":"0.1.0"}'
+      : files[filePath],
+    readdirSync: (dirPath) => {
+      const tree = {
+        '/project/ctx/docs': dirents(['product', 'architecture', 'environment', 'code'], 'dir'),
+        '/project/ctx/docs/product': [dirent('domain', 'dir'), dirent('AGENTS.md', 'file')],
+        '/project/ctx/docs/product/domain': [
+          dirent('ingress.md', 'file'),
+          dirent('ingress.skin.en.md', 'file'),
+          dirent('memory.skin.en.md', 'file'),
+        ],
+        '/project/ctx/docs/architecture': [],
+        '/project/ctx/docs/environment': [],
+        '/project/ctx/docs/code': [],
+        '/project/ctx/assets': [dirent('product', 'dir')],
+        '/project/ctx/assets/product': [dirent('domain', 'dir')],
+        '/project/ctx/assets/product/domain': [dirent('main-map.svg', 'file')],
+      };
+      return tree[dirPath] ?? [];
+    },
+  };
+  const service = new Service({
+    constants,
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.projection.bodies, ['ctx/docs/product/domain/ingress.md']);
+  assert.deepEqual(result.projection.skins, [
+    'ctx/docs/product/domain/ingress.skin.en.md',
+    'ctx/docs/product/domain/memory.skin.en.md',
+  ]);
+  assert.deepEqual(result.projection.pairs, [{
+    body: 'ctx/docs/product/domain/ingress.md',
+    skin: 'ctx/docs/product/domain/ingress.skin.en.md',
+  }]);
+  assert.deepEqual(result.projection.orphanSkins, ['ctx/docs/product/domain/memory.skin.en.md']);
+  assert.deepEqual(result.projection.assets, ['ctx/assets/product/domain/main-map.svg']);
+  assert.match(formatFindings(result.findings), /Orphan semantic skin: ctx\/docs\/product\/domain\/memory\.skin\.en\.md/);
+  assert.match(formatFindings(result.findings), /Missing paired agent document: ctx\/docs\/product\/domain\/memory\.skin\.en\.md references ctx\/docs\/product\/domain\/memory\.md/);
+});
+
+test('Validate service recognizes multiple language skins and rejects an unmarked skin', async () => {
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({path: 'ctx/docs/product/domain.md', body: 'Domain context.\n'}),
+    '/project/ctx/docs/product/domain.skin.en.md': skin({
+      agentDocument: 'domain.md',
+      path: 'ctx/docs/product/domain.skin.en.md',
+    }),
+    '/project/ctx/docs/product/domain.skin.ru.md': skin({
+      agentDocument: 'domain.md',
+      path: 'ctx/docs/product/domain.skin.ru.md',
+    }),
+    '/project/ctx/docs/product/overview.skin.md': skin({
+      agentDocument: 'overview.md',
+      path: 'ctx/docs/product/overview.skin.md',
+    }),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+
+  assert.equal(result.projection.pairs.length, 2);
+  assert.deepEqual(result.projection.pairs.map((pair) => pair.skin), [
+    'ctx/docs/product/domain.skin.en.md',
+    'ctx/docs/product/domain.skin.ru.md',
+  ]);
+  assert.match(formatFindings(result.findings), /skin-language-marker ctx\/docs\/product\/overview\.skin\.md Skin language marker is required/);
+});
+
+test('Validate service reports invalid metadata headers and skin structure', async () => {
+  const files = {
+    '/project/ctx/docs/product/AGENTS.md': doc({
+      path: 'ctx/docs/product/AGENTS.md',
+      body: '## Purpose\n\nProduct routing.\n',
+    }),
+    '/project/ctx/docs/product/domain.md': [
+      '# Product Domain',
+      '',
+      '- Path: `ctx/docs/product/wrong-domain.md`',
+      '',
+      '## Purpose',
+      '',
+      'Domain context.',
+      '',
+    ].join('\n'),
+    '/project/ctx/docs/product/domain.skin.en.md': [
+      '# Product Domain Skin',
+      '',
+      '- Path: `ctx/docs/product/domain.skin.en.md`',
+      '- Changed: `20260708`',
+      '',
+      '## Purpose',
+      '',
+      'Human-facing control.',
+      '',
+      '## Scope',
+      '',
+      'Includes:',
+      '',
+      '- domain identity.',
+      '',
+      '## Invariants',
+      '',
+      '- Keep the domain stable.',
+      '',
+      '## Agent Document',
+      '',
+      '`other.md`',
+      '',
+    ].join('\n'),
+  };
+  const fs = {
+    existsSync: (filePath) => [
+      '/project/ctx',
+      '/project/ctx/docs',
+      '/project/ctx/docs/product',
+      '/project/ctx/docs/architecture',
+      '/project/ctx/docs/environment',
+      '/project/ctx/docs/code',
+      '/project/ctx/adsm.json',
+      ...Object.keys(files),
+    ].includes(filePath),
+    readFileSync: (filePath) => filePath.endsWith('adsm.json')
+      ? '{"schema":"adsm-context","version":"0.1.0"}'
+      : files[filePath],
+    readdirSync: (dirPath) => {
+      const tree = {
+        '/project/ctx/docs': dirents(['product', 'architecture', 'environment', 'code'], 'dir'),
+        '/project/ctx/docs/product': [
+          dirent('AGENTS.md', 'file'),
+          dirent('domain.md', 'file'),
+          dirent('domain.skin.en.md', 'file'),
+        ],
+        '/project/ctx/docs/architecture': [],
+        '/project/ctx/docs/environment': [],
+        '/project/ctx/docs/code': [],
+      };
+      return tree[dirPath] ?? [];
+    },
+  };
+  const service = new Service({
+    constants,
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  const findings = formatFindings(result.findings);
+  assert.match(findings, /Path mismatch: ctx\/docs\/product\/domain\.md declares ctx\/docs\/product\/wrong-domain\.md/);
+  assert.match(findings, /Missing Changed attribute: ctx\/docs\/product\/domain\.md/);
+  assert.match(findings, /Missing skin section "Mental Model": ctx\/docs\/product\/domain\.skin\.en\.md/);
+  assert.match(findings, /Missing Excludes: block in Scope: ctx\/docs\/product\/domain\.skin\.en\.md/);
+  assert.match(findings, /Skin agent document mismatch: ctx\/docs\/product\/domain\.skin\.en\.md references ctx\/docs\/product\/other\.md but expected ctx\/docs\/product\/domain\.md/);
+  assert.match(findings, /Missing paired agent document: ctx\/docs\/product\/domain\.skin\.en\.md references ctx\/docs\/product\/other\.md/);
+});
+
+test('Validate service reports broken local markdown links', async () => {
+  const files = {
+    '/project/ctx/docs/product/overview.md': doc({
+      path: 'ctx/docs/product/overview.md',
+      body: 'See [domain](./missing.md).\n',
+    }),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  assert.match(formatFindings(result.findings), /Missing linked document: \.\/missing\.md resolves to ctx\/docs\/product\/missing\.md/);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'local-link-exists' && entry.severity === 'error'), true);
+});
+
+test('Validate service accepts repository-local markdown links outside ctx/docs', async () => {
+  const files = {
+    '/project/README.md': '# Repository Root\n',
+    '/project/docs/overview.md': '# External Docs\n',
+    '/project/ctx/docs/product/overview.md': doc({
+      path: 'ctx/docs/product/overview.md',
+      body: 'Read [repo root](../../../README.md) and [external docs](../../../docs/overview.md).\n',
+    }),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'local-link-exists' && entry.severity === 'error'), false);
+});
+
+test('Validate service reports warnings only for link fragments and skin warning thresholds', async () => {
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({
+      path: 'ctx/docs/product/domain.md',
+      body: 'Read [overview](./overview.md#purpose).\n',
+    }),
+    '/project/ctx/docs/product/domain.skin.en.md': skin({
+      extraLines: [
+        '- alpha.',
+        '- beta.',
+        '- gamma.',
+        '- delta.',
+        '- epsilon.',
+        '- zeta.',
+        '- eta.',
+        '- theta.',
+        '- iota.',
+        '- kappa.',
+        '- lambda.',
+      ],
+      path: 'ctx/docs/product/domain.skin.en.md',
+      purpose: 'Keep human-facing purpose stable.',
+      agentDocument: 'domain.md',
+    }),
+    '/project/ctx/docs/product/overview.md': doc({
+      path: 'ctx/docs/product/overview.md',
+      body: 'Overview.\n',
+    }),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.equal(result.errorCount, 0);
+  assert.ok(result.warningCount >= 2);
+  const findings = formatFindings(result.findings);
+  assert.match(findings, /Link anchor was not validated/);
+  assert.match(findings, /Skin list count \d+ exceeds warning threshold 12/);
+});
+
+test('Validate service measures only semantic skin content with Unicode-aware words', async () => {
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({
+      path: 'ctx/docs/product/domain.md',
+      body: 'Domain.\n',
+    }),
+    '/project/ctx/docs/product/domain.skin.en.md': [
+      '# Заголовок skin',
+      '',
+      '- Path: `ctx/docs/product/domain.skin.en.md`',
+      '- Changed: `20260715`',
+      '',
+      '## Purpose',
+      '',
+      'Привет мир',
+      '',
+      '## Mental Model',
+      '',
+      '## Scope',
+      '',
+      'Includes:',
+      '',
+      '- один',
+      '',
+      'Excludes:',
+      '',
+      '- два',
+      '',
+      '## Invariants',
+      '',
+      '## Agent Document',
+      '',
+      '`domain.md`',
+      '',
+    ].join('\n'),
+  };
+  const service = buildService({
+    constantsOverride: {
+      SKIN_WORD_WARN: 3,
+      SKIN_WORD_ERROR: 5,
+      SKIN_LIST_WARN: 2,
+      SKIN_LIST_ERROR: 3,
+    },
+    files,
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  const findings = formatFindings(result.findings);
+  assert.match(findings, /Skin word count 4 exceeds warning threshold 3/);
+  assert.doesNotMatch(findings, /skin-size-list-count/);
+});
+
+test('Validate service ignores skin headings and metadata when counting words', async () => {
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({
+      path: 'ctx/docs/product/domain.md',
+      body: 'Domain.\n',
+    }),
+    '/project/ctx/docs/product/domain.skin.en.md': [
+      '# Skin Title',
+      '',
+      '- Path: `ctx/docs/product/domain.skin.en.md`',
+      '- Changed: `20260708`',
+      '',
+      '## Purpose',
+      '',
+      'one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen',
+      '',
+      '## Mental Model',
+      '',
+      'seventeen eighteen nineteen twenty',
+      '',
+      '## Scope',
+      '',
+      'Includes:',
+      '',
+      '- alpha.',
+      '',
+      'Excludes:',
+      '',
+      '- beta.',
+      '',
+      '## Invariants',
+      '',
+      '- gamma.',
+      '',
+      '## Agent Document',
+      '',
+      '`domain.md`',
+      '',
+    ].join('\n'),
+  };
+  const service = buildService({
+    constantsOverride: {
+      SKIN_WORD_WARN: 30,
+      SKIN_WORD_ERROR: 40,
+      SKIN_LIST_WARN: 3,
+      SKIN_LIST_ERROR: 5,
+    },
+    files,
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.equal(result.warningCount, 0);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'skin-size-word-count'), false);
+});
+
+test('Validate service reports errors for skin size limits', async () => {
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({
+      path: 'ctx/docs/product/domain.md',
+      body: 'Domain.\n',
+    }),
+    '/project/ctx/docs/product/domain.skin.en.md': skin({
+      extraLines: [
+        '- one.',
+        '- two.',
+        '- three.',
+        '- four.',
+        '- five.',
+        '- six.',
+      ],
+      path: 'ctx/docs/product/domain.skin.en.md',
+      purpose: 'one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen',
+      agentDocument: 'domain.md',
+    }),
+  };
+  const service = buildService({
+    constantsOverride: {
+      SKIN_WORD_WARN: 12,
+      SKIN_WORD_ERROR: 20,
+      SKIN_LIST_WARN: 3,
+      SKIN_LIST_ERROR: 5,
+    },
+    files,
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  const findings = formatFindings(result.findings);
+  assert.match(findings, /Skin word count \d+ exceeds limit 20/);
+  assert.match(findings, /Skin list count \d+ exceeds limit 5/);
+});
+
+test('Validate service applies the 160 and 240 word skin boundaries', async () => {
+  await assertSkinBoundary({
+    wordCount: 160,
+    expected: 'normal',
+  });
+  await assertSkinBoundary({
+    wordCount: 161,
+    expected: 'warning',
+  });
+  await assertSkinBoundary({
+    wordCount: 240,
+    expected: 'warning',
+  });
+  await assertSkinBoundary({
+    wordCount: 241,
+    expected: 'error',
+  });
+});
+
+test('Validate service warns about an intentional documentation level capacity exception', async () => {
+  const files = {
+    '/project/ctx/docs/product/AGENTS.md': doc({
+      path: 'ctx/docs/product/AGENTS.md',
+      body: '## Documentation Capacity Exception\n\nThis level intentionally has more than nine files because its stable concepts must remain directly discoverable.\n',
+    }),
+    ...Object.fromEntries(Array.from({length: 10}, (_, index) => {
+      const name = `document-${index + 1}.md`;
+      return [`/project/ctx/docs/product/${name}`, doc({path: `ctx/docs/product/${name}`})];
+    })),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.match(formatFindings(result.findings), /warning doc-level-capacity ctx\/docs\/product Documentation level exceeds recommended capacity: 10 files/);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'doc-level-capacity-exception'), false);
+});
+
+test('Validate service requires an explicit capacity exception for overloaded documentation levels', async () => {
+  const files = {
+    '/project/ctx/docs/product/AGENTS.md': doc({
+      path: 'ctx/docs/product/AGENTS.md',
+      body: '## Local Rules\n\nKeep this level readable.\n',
+    }),
+    ...Object.fromEntries(Array.from({length: 10}, (_, index) => {
+      const name = `document-${index + 1}.md`;
+      return [`/project/ctx/docs/product/${name}`, doc({path: `ctx/docs/product/${name}`})];
+    })),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, false);
+  assert.match(formatFindings(result.findings), /error doc-level-capacity-exception ctx\/docs\/product\/AGENTS\.md Documentation Capacity Exception must be explicit/);
+});
+
+test('Validate service counts an agent document and its skin as one documentation file', async () => {
+  const files = {
+    '/project/ctx/docs/product/AGENTS.md': doc({
+      path: 'ctx/docs/product/AGENTS.md',
+      body: '## Local Rules\n\nKeep this level readable.\n',
+    }),
+    ...Object.fromEntries(Array.from({length: 9}, (_, index) => {
+      const name = `document-${index + 1}`;
+      return [`/project/ctx/docs/product/${name}.md`, doc({path: `ctx/docs/product/${name}.md`})];
+    })),
+    ...Object.fromEntries(Array.from({length: 9}, (_, index) => {
+      const name = `document-${index + 1}`;
+      return [`/project/ctx/docs/product/${name}.skin.en.md`, skin({
+        agentDocument: `${name}.md`,
+        path: `ctx/docs/product/${name}.skin.en.md`,
+      })];
+    })),
+  };
+  const service = buildService({files});
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'doc-level-capacity'), false);
+  assert.equal(result.findings.some((entry) => entry.ruleId === 'doc-level-capacity-exception'), false);
+});
+
+test('Validate service checks the documentation level directory recommendation separately', async () => {
+  const agentsPath = '/project/ctx/docs/product/AGENTS.md';
+  const fs = {
+    existsSync: (filePath) => [
+      '/project/ctx',
+      '/project/ctx/docs',
+      '/project/ctx/docs/product',
+      '/project/ctx/docs/architecture',
+      '/project/ctx/docs/environment',
+      '/project/ctx/docs/code',
+      '/project/ctx/adsm.json',
+      agentsPath,
+    ].includes(filePath),
+    readFileSync: (filePath) => filePath.endsWith('adsm.json')
+      ? '{"schema":"adsm-context","version":"0.1.0"}'
+      : doc({
+        path: 'ctx/docs/product/AGENTS.md',
+        body: '## Documentation Capacity Exception\n\nTen direct directories intentionally separate independent product areas.\n',
+      }),
+    readdirSync: (dirPath) => {
+      if (dirPath === '/project/ctx/docs') return dirents(['product', 'architecture', 'environment', 'code'], 'dir');
+      if (dirPath === '/project/ctx/docs/product') {
+        return [dirent('AGENTS.md', 'file'), ...dirents(Array.from({length: 10}, (_, index) => `area-${index + 1}`), 'dir')];
+      }
+      return [];
+    },
+  };
+  const service = new Service({
+    constants,
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+  const result = await service.execute({targetPath: '/project'});
+  assert.equal(result.ok, true);
+  assert.match(formatFindings(result.findings), /Documentation level exceeds recommended capacity: 10 directories/);
+});
+
+function buildService({constantsOverride = {}, files}) {
+  const existingPaths = new Set([
+    '/project/ctx',
+    '/project/ctx/docs',
+    '/project/ctx/docs/product',
+    '/project/ctx/docs/architecture',
+    '/project/ctx/docs/environment',
+    '/project/ctx/docs/code',
+    '/project/ctx/adsm.json',
+    ...Object.keys(files),
+  ]);
+  const fs = {
+    existsSync: (filePath) => existingPaths.has(filePath),
+    readFileSync: (filePath) => filePath.endsWith('adsm.json')
+      ? '{"schema":"adsm-context","version":"0.1.0"}'
+      : files[filePath],
+    readdirSync: (dirPath) => {
+      const tree = {
+        '/project/ctx/docs': dirents(['product', 'architecture', 'environment', 'code'], 'dir'),
+        '/project/ctx/docs/product': Object.keys(files)
+          .filter((entry) => entry.startsWith('/project/ctx/docs/product/'))
+          .map((entry) => entry.replace('/project/ctx/docs/product/', ''))
+          .filter((entry) => !entry.includes('/'))
+          .map((name) => dirent(name, 'file')),
+        '/project/ctx/docs/architecture': [],
+        '/project/ctx/docs/environment': [],
+        '/project/ctx/docs/code': [],
+      };
+      return tree[dirPath] ?? [];
+    },
+  };
+
+  return new Service({
+    constants: {...constants, ...constantsOverride},
+    fs,
+    pathService: {join: (...parts) => parts.join('/'), resolve: (value) => value},
+  });
+}
+
+async function assertSkinBoundary({wordCount, expected}) {
+  const skinText = skinWithWordCount({
+    agentDocument: 'domain.md',
+    path: 'ctx/docs/product/domain.skin.en.md',
+    wordCount,
+  });
+  const files = {
+    '/project/ctx/docs/product/domain.md': doc({
+      path: 'ctx/docs/product/domain.md',
+      body: 'Domain.\n',
+    }),
+    '/project/ctx/docs/product/domain.skin.en.md': skinText,
+  };
+  const service = buildService({
+    constantsOverride: {SKIN_LIST_WARN: 100, SKIN_LIST_ERROR: 101},
+    files,
+  });
+  const result = await service.execute({targetPath: '/project'});
+  const findings = formatFindings(result.findings);
+  if (expected === 'normal') {
+    assert.equal(result.warningCount, 0);
+    assert.equal(result.errorCount, 0);
+    assert.equal(result.ok, true);
+    assert.equal(findings.includes('Skin word count'), false);
+    return;
+  }
+  if (expected === 'warning') {
+    assert.equal(result.errorCount, 0);
+    assert.equal(result.warningCount, 1);
+    assert.match(findings, new RegExp(`Skin word count ${wordCount} exceeds warning threshold 160`));
+    return;
+  }
+  assert.equal(result.ok, false);
+  assert.equal(result.errorCount, 1);
+  assert.match(findings, new RegExp(`Skin word count ${wordCount} exceeds limit 240`));
+}
+
+function formatFindings(findings) {
+  return findings.map((entry) => `${entry.severity} ${entry.ruleId} ${entry.path} ${entry.message}`).join('\n');
+}
+
+function dirents(names, type) {
+  return names.map((name) => dirent(name, type));
+}
+
+function dirent(name, type) {
+  return {
+    name,
+    isDirectory: () => type === 'dir',
+    isFile: () => type === 'file',
+  };
+}
+
+function doc({path, body = ''}) {
+  return [
+    '# Document',
+    '',
+    `- Path: \`${path}\``,
+    '- Changed: `20260708`',
+    '',
+    body.trimEnd(),
+    '',
+  ].join('\n');
+}
+
+function skin({agentDocument, extraLines = [], path, purpose = 'Keep human-facing purpose stable.'}) {
+  return [
+    '# Skin',
+    '',
+    `- Path: \`${path}\``,
+    '- Changed: `20260708`',
+    '',
+    '## Purpose',
+    '',
+    purpose,
+    '',
+    '## Mental Model',
+    '',
+    'This is the human semantic frame.',
+    '',
+    '## Scope',
+    '',
+    'Includes:',
+    '',
+    '- the documented object.',
+    '',
+    'Excludes:',
+    '',
+    '- operational overload.',
+    '',
+    '## Invariants',
+    '',
+    '- Keep the documented object stable.',
+    ...extraLines,
+    '',
+    '## Agent Document',
+    '',
+    `\`${agentDocument}\``,
+    '',
+  ].join('\n');
+}
+
+function skinWithWordCount({agentDocument, path, wordCount}) {
+  const base = skin({
+    agentDocument,
+    path,
+    purpose: '',
+  });
+  const overhead = countWords(extractSemanticSkinText(base));
+  const extraWords = Math.max(0, wordCount - overhead);
+  const purpose = Array.from({length: extraWords}, () => 'alpha').join(' ');
+  return skin({
+    agentDocument,
+    path,
+    purpose,
+  });
+}
+
+function countWords(text) {
+  const matches = text.match(/[A-Za-z0-9][A-Za-z0-9'-]*/g);
+  return matches ? matches.length : 0;
+}
+
+function extractSemanticSkinText(text) {
+  return ['Purpose', 'Mental Model', 'Scope', 'Invariants']
+    .map((sectionName) => {
+      const body = [];
+      let insideSection = false;
+      for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        if (!insideSection) {
+          if (line === `## ${sectionName}`) insideSection = true;
+          continue;
+        }
+        if (line.startsWith('## ')) break;
+        body.push(rawLine);
+      }
+      return body.join('\n');
+    })
+    .join('\n')
+    .replace(/^\s*(?:Includes|Excludes):\s*$/gm, '');
+}