@namewta/speculo 0.7.4 → 0.7.5

package/template/skills/engineering-standards-builder/scripts/self-test.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+import { cp, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+function usage() {
+  return `Usage: node scripts/self-test.mjs --root <skill-root>\n\n` +
+    `Run deterministic scanner fixtures plus generated-Skill validator success and failure cases.\n\n` +
+    `Options:\n  --root <path>  Skill root (required)\n  --help         Show this help\n`;
+}
+
+function parseArgs(argv) {
+  let root = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    if (arg === '--root') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) throw new Error('--root requires a value');
+      root = value; i += 1; continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!root) throw new Error('--root is required');
+  return { root: path.resolve(root) };
+}
+
+async function findExpectedFiles(root) {
+  const result = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    for (const entry of entries) {
+      const abs = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(abs);
+      else if (entry.isFile() && entry.name === 'expected.json') result.push(abs);
+    }
+  }
+  await visit(root);
+  return result;
+}
+
+function runNode(script, args, options = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
+    encoding: 'utf8', timeout: options.timeout ?? 60000, maxBuffer: 64 * 1024 * 1024,
+    cwd: options.cwd,
+  });
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function assertIncludes(actual, expected, label) {
+  for (const value of expected ?? []) {
+    assert(actual.includes(value), `${label}: expected ${JSON.stringify(value)} in ${JSON.stringify(actual)}`);
+  }
+}
+
+function assertFixture(inventory, expected, fixtureName) {
+  if (expected.topology) assert(inventory.topology === expected.topology, `${fixtureName}: topology expected ${expected.topology}, got ${inventory.topology}`);
+  if (expected.minimumModules) assert(inventory.modules.length >= expected.minimumModules, `${fixtureName}: expected at least ${expected.minimumModules} modules, got ${inventory.modules.length}`);
+  assertIncludes(inventory.summary.languages, expected.languages, `${fixtureName} summary.languages`);
+  assertIncludes(inventory.summary.adapters, expected.adapters, `${fixtureName} summary.adapters`);
+  for (const value of expected.absentAdapters ?? []) assert(!inventory.summary.adapters.includes(value), `${fixtureName}: adapter ${value} must be absent`);
+  assertIncludes(inventory.summary.frameworks, expected.frameworks, `${fixtureName} summary.frameworks`);
+  assertIncludes(inventory.summary.buildSystems, expected.buildSystems, `${fixtureName} summary.buildSystems`);
+  assertIncludes(inventory.summary.testSystems, expected.testSystems, `${fixtureName} summary.testSystems`);
+  assertIncludes((inventory.ciCommands ?? []).map((item) => item.responsibility), expected.ciResponsibilities, `${fixtureName} ciResponsibilities`);
+  if (expected.module) {
+    const module = inventory.modules.find((item) => item.path === expected.module.path);
+    assert(module, `${fixtureName}: module ${expected.module.path} not found`);
+    for (const key of ['languages', 'frameworks', 'buildSystems', 'testSystems', 'runtimes', 'applicationTypes']) {
+      assertIncludes(module[key] ?? [], expected.module[key], `${fixtureName} module.${key}`);
+    }
+  }
+  assert(inventory.scan.truncated === false, `${fixtureName}: scan unexpectedly truncated`);
+  assert(inventory.modules.every((module) => Array.isArray(module.evidence)), `${fixtureName}: every module must contain evidence`);
+}
+
+async function writeGeneratedFixture(projectRoot) {
+  await mkdir(path.join(projectRoot, 'src'), { recursive: true });
+  await writeFile(path.join(projectRoot, 'package.json'), `${JSON.stringify({
+    name: 'generated-validation-fixture', private: true,
+    dependencies: { vue: '^3.5.0' }, devDependencies: { typescript: '^5.9.0', vite: '^7.0.0' },
+  }, null, 2)}\n`);
+  await writeFile(path.join(projectRoot, 'tsconfig.json'), '{"compilerOptions":{"strict":true},"include":["src"]}\n');
+  await writeFile(path.join(projectRoot, 'src', 'App.vue'), '<script setup lang="ts">const value = 1</script>\n<template><main>{{ value }}</main></template>\n');
+
+  const canonical = path.join(projectRoot, '.agents', 'skills', 'engineering-standards');
+  await mkdir(path.join(canonical, 'references', 'project'), { recursive: true });
+  await mkdir(path.join(canonical, 'references', 'rules'), { recursive: true });
+  await mkdir(path.join(canonical, 'references', 'typescript', 'frameworks'), { recursive: true });
+  await writeFile(path.join(canonical, 'SKILL.md'), `---\nname: engineering-standards\ndescription: Generated fixture standards.\n---\n\n# Engineering Standards\n\nRead [profile](references/project/00-project-profile.md), [modules](references/project/01-module-map.md), [decisions](references/project/02-decisions-and-exceptions.md), [review](references/project/review-checklist.md), [rules](references/rules/core.md), [TypeScript](references/typescript/language.md), and [Vue](references/typescript/frameworks/vue.md).\n`);
+  await writeFile(path.join(canonical, 'references', 'project', '00-project-profile.md'), '# Project Profile\n\nVue fixture.\n');
+  await writeFile(path.join(canonical, 'references', 'project', '01-module-map.md'), '# Module Map\n\n- module:. uses TypeScript and Vue.\n');
+  await writeFile(path.join(canonical, 'references', 'project', '02-decisions-and-exceptions.md'), '# Decisions and Exceptions\n\nNo exceptions.\n');
+  await writeFile(path.join(canonical, 'references', 'project', 'review-checklist.md'), '# Review Checklist\n\n- Verify scope.\n');
+  const rule = `# Core Rules\n\n### CORE-001 Validated boundary\nScope: repository\nLevel: MUST\nSource: repository-fact\nApplies when: external input enters the application.\nRule: Validate external input before domain use.\nRationale: Preserve trusted internal models.\nVerification: Review boundary tests.\nException: Recorded project exception only.\n`;
+  await writeFile(path.join(canonical, 'references', 'rules', 'core.md'), rule);
+  await writeFile(path.join(canonical, 'references', 'typescript', 'language.md'), rule.replace('CORE-001', 'TS-001'));
+  await writeFile(path.join(canonical, 'references', 'typescript', 'frameworks', 'vue.md'), rule.replace('CORE-001', 'VUE-001'));
+  return canonical;
+}
+
+async function main() {
+  let args;
+  try { args = parseArgs(process.argv.slice(2)); }
+  catch (error) {
+    process.stderr.write(`self-test: ${error.message}\n\n${usage()}`);
+    process.exitCode = 2; return;
+  }
+  if (args.help) { process.stdout.write(usage()); return; }
+
+  const scanner = path.join(args.root, 'scripts', 'discover-project.mjs');
+  const generatedValidator = path.join(args.root, 'scripts', 'validate-generated-skill.mjs');
+  const manifestScript = path.join(args.root, 'scripts', 'sync-manifest.mjs');
+  const fixtureRoot = path.join(args.root, 'examples');
+  const tempRoots = [];
+  try {
+    const expectedFiles = await findExpectedFiles(fixtureRoot);
+    assert(expectedFiles.length >= 6, `expected at least 6 fixtures, found ${expectedFiles.length}`);
+    for (const expectedPath of expectedFiles) {
+      const fixtureDir = path.dirname(expectedPath);
+      const fixtureName = path.relative(fixtureRoot, fixtureDir).split(path.sep).join('/');
+      const expected = JSON.parse(await readFile(expectedPath, 'utf8'));
+      const first = runNode(scanner, ['--root', fixtureDir]);
+      assert(first.status === 0, `${fixtureName}: scanner failed: ${(first.stderr || first.stdout).trim()}`);
+      const second = runNode(scanner, ['--root', fixtureDir]);
+      assert(second.status === 0, `${fixtureName}: second scanner run failed`);
+      assert(first.stdout === second.stdout, `${fixtureName}: scanner output is not deterministic`);
+      const inventory = JSON.parse(first.stdout);
+      assertFixture(inventory, expected, fixtureName);
+      process.stdout.write(`self-test: fixture OK ${fixtureName}\n`);
+    }
+
+    const missing = runNode(scanner, ['--root', path.join(args.root, 'examples', 'does-not-exist')]);
+    assert(missing.status !== 0, 'scanner must fail for a missing root');
+
+    const outputTemp = await mkdtemp(path.join(os.tmpdir(), 'standards-builder-output-'));
+    tempRoots.push(outputTemp);
+    const copiedFixture = path.join(outputTemp, 'fixture');
+    await cp(path.join(args.root, 'examples', 'typescript', 'vue-vite'), copiedFixture, { recursive: true });
+    const writeResult = runNode(scanner, ['--root', copiedFixture, '--output', '.inventory/project.json', '--pretty']);
+    assert(writeResult.status === 0, `scanner safe output failed: ${writeResult.stderr}`);
+    const outputInventory = JSON.parse(await readFile(path.join(copiedFixture, '.inventory', 'project.json'), 'utf8'));
+    assert(outputInventory.summary.frameworks.includes('vue'), 'safe output inventory lost Vue detection');
+    const escapeTarget = path.join(outputTemp, 'escape.json');
+    const escapeResult = runNode(scanner, ['--root', copiedFixture, '--output', '../escape.json']);
+    assert(escapeResult.status !== 0, 'scanner must reject output escaping root');
+    try { await readFile(escapeTarget, 'utf8'); throw new Error('scanner wrote an escaping output file'); }
+    catch (error) { if (error.message === 'scanner wrote an escaping output file') throw error; }
+    process.stdout.write('self-test: scanner safety OK\n');
+
+    const managedTemp = await mkdtemp(path.join(os.tmpdir(), 'standards-builder-managed-'));
+    tempRoots.push(managedTemp);
+    await cp(path.join(args.root, 'examples', 'typescript', 'vue-vite'), managedTemp, { recursive: true });
+    await mkdir(path.join(managedTemp, 'speculo', '.speculo'), { recursive: true });
+    await mkdir(path.join(managedTemp, 'speculo', 'skills', 'noise', 'examples'), { recursive: true });
+    await writeFile(path.join(managedTemp, 'speculo', '.speculo', 'workspace.json'), '{"schema_version":1}\n');
+    await writeFile(path.join(managedTemp, 'speculo', 'skills', 'noise', 'examples', 'go.mod'), 'module noise.invalid\n\ngo 1.24\n');
+    await writeFile(path.join(managedTemp, 'speculo', 'skills', 'noise', 'examples', 'Cargo.toml'), '[package]\nname = "noise"\nversion = "0.0.0"\n');
+    await mkdir(path.join(managedTemp, '.agents', 'skills', 'engineering-standards'), { recursive: true });
+    await writeFile(path.join(managedTemp, '.agents', 'skills', 'engineering-standards', 'SKILL.md'), '---\nname: engineering-standards\ndescription: existing\n---\n');
+    const managedResult = runNode(scanner, ['--root', managedTemp]);
+    assert(managedResult.status === 0, `managed-root exclusion scan failed: ${managedResult.stderr}`);
+    const managedInventory = JSON.parse(managedResult.stdout);
+    assert(!managedInventory.summary.languages.includes('go') && !managedInventory.summary.languages.includes('rust'), 'managed Speculo/Agent skill assets polluted project language detection');
+    assert(managedInventory.existingStandards.includes('.agents/skills/engineering-standards/SKILL.md'), 'managed standards entrypoint was not preserved as evidence');
+    process.stdout.write('self-test: managed asset exclusion OK\n');
+
+    const generatedTemp = await mkdtemp(path.join(os.tmpdir(), 'standards-builder-generated-'));
+    tempRoots.push(generatedTemp);
+    const canonical = await writeGeneratedFixture(generatedTemp);
+    const valid = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(valid.status === 0, `valid generated Skill was rejected: ${(valid.stderr || valid.stdout).trim()}`);
+    await writeFile(path.join(canonical, 'references', 'typescript', 'frameworks', 'react.md'), '# React\n');
+    const wrongFramework = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(wrongFramework.status !== 0, 'strict validator must reject an unselected React rule in a Vue-only project');
+    await rm(path.join(canonical, 'references', 'typescript', 'frameworks', 'react.md'));
+    const wrapper = path.join(generatedTemp, '.agents', 'skills', 'typescript-standards');
+    await mkdir(wrapper, { recursive: true });
+    await writeFile(path.join(wrapper, 'SKILL.md'), '---\nname: typescript-standards\ndescription: alias\n---\n\nRoute to engineering-standards.\nSecond body line.\n');
+    const badWrapper = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(badWrapper.status !== 0, 'validator must reject a multi-line compatibility wrapper');
+    process.stdout.write('self-test: generated Skill validator OK\n');
+
+    const manifest = runNode(manifestScript, ['--root', args.root, '--check']);
+    assert(manifest.status === 0, `manifest check failed: ${(manifest.stderr || manifest.stdout).trim()}`);
+    process.stdout.write('self-test: manifest OK\n');
+    process.stdout.write(`self-test: OK (${expectedFiles.length} fixtures)\n`);
+  } catch (error) {
+    process.stderr.write(`self-test: ERROR: ${error.stack ?? error.message}\n`);
+    process.exitCode = 1;
+  } finally {
+    for (const tempRoot of tempRoots) await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+await main();

package/template/skills/engineering-standards-builder/scripts/sync-manifest.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { lstat, readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+function usage() {
+  return `Usage: node scripts/sync-manifest.mjs --root <skill-root> [--check | --write]\n\n` +
+    `Validate or regenerate manifest.txt. The manifest lists every package file except itself.\n\n` +
+    `Options:\n` +
+    `  --root <path>  Skill root (required)\n` +
+    `  --check        Fail when manifest.txt is stale (default)\n` +
+    `  --write        Rewrite manifest.txt deterministically\n` +
+    `  --help         Show this help\n`;
+}
+
+function parseArgs(argv) {
+  const result = { root: null, mode: 'check' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    if (arg === '--check') { result.mode = 'check'; continue; }
+    if (arg === '--write') { result.mode = 'write'; continue; }
+    if (arg === '--root') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) throw new Error('--root requires a value');
+      result.root = value;
+      i += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!result.root) throw new Error('--root is required');
+  return result;
+}
+
+function toPosix(value) { return value.split(path.sep).join('/'); }
+
+async function collectFiles(rootReal) {
+  const result = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    for (const entry of entries) {
+      if (entry.name === '.DS_Store') continue;
+      const absolute = path.join(directory, entry.name);
+      const relative = toPosix(path.relative(rootReal, absolute));
+      if (entry.isSymbolicLink()) throw new Error(`symlink is not allowed in the skill package: ${relative}`);
+      if (entry.isDirectory()) { await visit(absolute); continue; }
+      if (!entry.isFile()) continue;
+      if (relative === 'manifest.txt') continue;
+      result.push(relative);
+    }
+  }
+  await visit(rootReal);
+  return result.sort((a, b) => a.localeCompare(b, 'en'));
+}
+
+async function main() {
+  let args;
+  try { args = parseArgs(process.argv.slice(2)); }
+  catch (error) {
+    process.stderr.write(`sync-manifest: ${error.message}\n\n${usage()}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (args.help) { process.stdout.write(usage()); return; }
+  try {
+    const rootReal = await realpath(path.resolve(args.root));
+    if (!(await stat(rootReal)).isDirectory()) throw new Error('--root is not a directory');
+    const manifestPath = path.join(rootReal, 'manifest.txt');
+    const expected = `${(await collectFiles(rootReal)).join('\n')}\n`;
+    if (args.mode === 'write') {
+      const info = await lstat(rootReal);
+      if (!info.isDirectory()) throw new Error('--root is not a directory');
+      await writeFile(manifestPath, expected, 'utf8');
+      process.stdout.write(`sync-manifest: wrote ${toPosix(path.relative(rootReal, manifestPath))}\n`);
+      return;
+    }
+    let actual;
+    try { actual = await readFile(manifestPath, 'utf8'); }
+    catch (error) {
+      if (error?.code === 'ENOENT') throw new Error('manifest.txt is missing; run with --write');
+      throw error;
+    }
+    if (actual !== expected) {
+      const actualSet = new Set(actual.split(/\r?\n/).filter(Boolean));
+      const expectedSet = new Set(expected.split(/\r?\n/).filter(Boolean));
+      const missing = [...expectedSet].filter((item) => !actualSet.has(item));
+      const stale = [...actualSet].filter((item) => !expectedSet.has(item));
+      const detail = [
+        missing.length ? `missing: ${missing.slice(0, 20).join(', ')}` : null,
+        stale.length ? `stale: ${stale.slice(0, 20).join(', ')}` : null,
+        !missing.length && !stale.length ? 'entries are not in deterministic order or newline format differs' : null,
+      ].filter(Boolean).join('; ');
+      throw new Error(`manifest.txt is stale (${detail}); run with --write`);
+    }
+    process.stdout.write(`sync-manifest: OK (${expected.split('\n').filter(Boolean).length} files)\n`);
+  } catch (error) {
+    process.stderr.write(`sync-manifest: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+await main();

package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+function usage() {
+  return `Usage: node scripts/validate-builder.mjs --root <skill-root>\n\n` +
+    `Validate the builder package: identity, links, reachability, manifest, fixtures, templates and script help.\n\n` +
+    `Options:\n  --root <path>  Skill root (required)\n  --help         Show this help\n`;
+}
+
+function parseArgs(argv) {
+  let root = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    if (arg === '--root') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) throw new Error('--root requires a value');
+      root = value; i += 1; continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!root) throw new Error('--root is required');
+  return { root };
+}
+
+function toPosix(value) { return value.split(path.sep).join('/'); }
+
+async function collect(rootReal) {
+  const files = [];
+  const directories = [];
+  async function visit(directory) {
+    const relDir = toPosix(path.relative(rootReal, directory)) || '.';
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    directories.push({ abs: directory, rel: relDir, entries });
+    for (const entry of entries) {
+      const abs = path.join(directory, entry.name);
+      const rel = toPosix(path.relative(rootReal, abs));
+      if (entry.isSymbolicLink()) throw new Error(`symlink is not allowed: ${rel}`);
+      if (entry.isDirectory()) { await visit(abs); continue; }
+      if (entry.isFile()) files.push({ abs, rel, name: entry.name });
+    }
+  }
+  await visit(rootReal);
+  return { files, directories };
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return null;
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0) return null;
+  const result = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) result[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '');
+  }
+  return { values: result, body: text.slice(end + 5) };
+}
+
+function markdownLinks(text) {
+  const links = [];
+  const pattern = /\[[^\]]*\]\(([^)]+)\)/g;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    let target = match[1].trim();
+    if (target.startsWith('<') && target.endsWith('>')) target = target.slice(1, -1);
+    const titleIndex = target.search(/\s+["']/);
+    if (titleIndex >= 0) target = target.slice(0, titleIndex);
+    links.push(target);
+  }
+  return links;
+}
+
+function isExternalLink(link) {
+  return /^(?:[a-z]+:|#|\/\/)/i.test(link);
+}
+
+function normalizeLinkTarget(sourceAbs, link) {
+  const withoutAnchor = link.split('#')[0].split('?')[0];
+  if (!withoutAnchor) return null;
+  let decoded;
+  try { decoded = decodeURIComponent(withoutAnchor); } catch { decoded = withoutAnchor; }
+  return path.resolve(path.dirname(sourceAbs), decoded);
+}
+
+async function computeManifest(rootReal, files) {
+  return `${files.map((file) => file.rel).filter((rel) => rel !== 'manifest.txt' && !rel.endsWith('/.DS_Store')).sort((a, b) => a.localeCompare(b, 'en')).join('\n')}\n`;
+}
+
+function failLines(errors, warnings) {
+  if (warnings.length) {
+    process.stderr.write(warnings.map((item) => `validate-builder: WARN: ${item}\n`).join(''));
+  }
+  if (errors.length) {
+    process.stderr.write(errors.map((item) => `validate-builder: ERROR: ${item}\n`).join(''));
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`validate-builder: OK${warnings.length ? ` (${warnings.length} warning(s))` : ''}\n`);
+}
+
+async function main() {
+  let args;
+  try { args = parseArgs(process.argv.slice(2)); }
+  catch (error) {
+    process.stderr.write(`validate-builder: ${error.message}\n\n${usage()}`);
+    process.exitCode = 2; return;
+  }
+  if (args.help) { process.stdout.write(usage()); return; }
+
+  const errors = [];
+  const warnings = [];
+  try {
+    const rootReal = await realpath(path.resolve(args.root));
+    if (!(await stat(rootReal)).isDirectory()) throw new Error('--root is not a directory');
+    const { files, directories } = await collect(rootReal);
+    const fileByAbs = new Map(files.map((file) => [file.abs, file]));
+    const fileByRel = new Map(files.map((file) => [file.rel, file]));
+
+    for (const directory of directories) {
+      if (directory.entries.length === 0) errors.push(`empty directory: ${directory.rel}`);
+    }
+
+    const skillFile = fileByRel.get('SKILL.md');
+    if (!skillFile) errors.push('SKILL.md is missing');
+    else {
+      const skillText = await readFile(skillFile.abs, 'utf8');
+      const frontmatter = parseFrontmatter(skillText);
+      if (!frontmatter) errors.push('SKILL.md frontmatter is missing or malformed');
+      else {
+        const expectedName = path.basename(rootReal);
+        if (frontmatter.values.name !== expectedName) errors.push(`frontmatter name must equal directory name (${expectedName}), found ${frontmatter.values.name ?? '<missing>'}`);
+        if (frontmatter.values.name !== 'engineering-standards-builder') errors.push('stable Skill ID must remain engineering-standards-builder for drop-in replacement');
+        if (!frontmatter.values.description) errors.push('frontmatter description is missing');
+        if (/[<>]/.test(frontmatter.values.description ?? '')) errors.push('frontmatter description must not contain angle brackets');
+      }
+      const completionCount = (skillText.match(/\*\*完成标准\*\*/g) ?? []).length;
+      if (completionCount < 7) errors.push(`SKILL.md must define completion criteria for all seven stages; found ${completionCount}`);
+    }
+
+    const localMarkdownFiles = files.filter((file) => /\.md(?:\.template)?$/.test(file.name) || file.name === 'SKILL.md.template');
+    const linkGraph = new Map();
+    for (const file of localMarkdownFiles) {
+      const text = await readFile(file.abs, 'utf8');
+      const targets = [];
+      for (const link of markdownLinks(text)) {
+        if (isExternalLink(link)) continue;
+        const targetAbs = normalizeLinkTarget(file.abs, link);
+        if (!targetAbs) continue;
+        if (!targetAbs.startsWith(`${rootReal}${path.sep}`) && targetAbs !== rootReal) {
+          errors.push(`${file.rel}: local link escapes skill root: ${link}`);
+          continue;
+        }
+        if (!existsSync(targetAbs)) {
+          const templateTarget = `${targetAbs}.template`;
+          if (!(file.rel.endsWith('.template') && existsSync(templateTarget))) {
+            errors.push(`${file.rel}: broken local link: ${link}`);
+            continue;
+          }
+        }
+        try {
+          const info = await lstat(targetAbs);
+          if (info.isSymbolicLink()) errors.push(`${file.rel}: link resolves through a symlink: ${link}`);
+        } catch { /* exists check already reported */ }
+        targets.push(targetAbs);
+      }
+      linkGraph.set(file.abs, targets);
+      if (!file.rel.startsWith('templates/') && /\{\{[A-Z0-9_]+\}\}/.test(text)) {
+        errors.push(`${file.rel}: unresolved template placeholder outside templates/`);
+      }
+    }
+
+    // All references must be reachable from the main entry through explicit Markdown links.
+    if (skillFile) {
+      const reachable = new Set();
+      const queue = [skillFile.abs];
+      while (queue.length) {
+        const current = queue.shift();
+        if (reachable.has(current)) continue;
+        reachable.add(current);
+        for (const target of linkGraph.get(current) ?? []) {
+          if (fileByAbs.has(target) && /\.md(?:\.template)?$/.test(path.basename(target))) queue.push(target);
+        }
+      }
+      for (const file of files.filter((item) => item.rel.startsWith('references/') && item.rel.endsWith('.md'))) {
+        if (!reachable.has(file.abs)) errors.push(`orphan reference not reachable from SKILL.md: ${file.rel}`);
+      }
+    }
+
+    const allowedReferenceRoots = new Set(['rules', 'typescript', 'java', 'go', 'rust']);
+    for (const file of files.filter((item) => item.rel.startsWith('references/'))) {
+      const first = file.rel.split('/')[1];
+      if (!allowedReferenceRoots.has(first)) errors.push(`unexpected top-level reference group: ${file.rel}`);
+    }
+    for (const required of ['references/rules', 'references/typescript', 'references/java', 'references/go', 'references/rust']) {
+      if (!directories.some((directory) => directory.rel === required)) errors.push(`required reference directory missing: ${required}`);
+    }
+
+    const allDocsText = (await Promise.all(files.filter((file) => file.rel.endsWith('.md')).map((file) => readFile(file.abs, 'utf8')))).join('\n');
+    for (const script of files.filter((file) => file.rel.startsWith('scripts/') && file.rel.endsWith('.mjs'))) {
+      if (!allDocsText.includes(script.name)) errors.push(`script is not referenced by Skill documentation: ${script.rel}`);
+      const result = spawnSync(process.execPath, [script.abs, '--help'], { encoding: 'utf8', timeout: 15000 });
+      if (result.status !== 0) errors.push(`${script.rel} --help failed: ${(result.stderr || result.stdout).trim()}`);
+      if (!/Usage:/.test(result.stdout)) errors.push(`${script.rel} --help does not print a Usage section`);
+    }
+
+    const templateFiles = files.filter((file) => file.rel.startsWith('templates/') && file.rel !== 'templates/README.md');
+    const templateIndex = fileByRel.get('templates/README.md');
+    if (!templateIndex) errors.push('templates/README.md is missing');
+    else {
+      const indexText = await readFile(templateIndex.abs, 'utf8');
+      for (const file of templateFiles) {
+        if (!indexText.includes(file.name)) errors.push(`template is not indexed in templates/README.md: ${file.rel}`);
+      }
+    }
+
+    const fixtureExpectations = files.filter((file) => file.name === 'expected.json' && file.rel.startsWith('examples/'));
+    if (fixtureExpectations.length < 6) errors.push(`at least six fixture contracts are required; found ${fixtureExpectations.length}`);
+    for (const requiredPrefix of ['examples/typescript/', 'examples/java/', 'examples/go/', 'examples/rust/', 'examples/polyglot/']) {
+      if (!fixtureExpectations.some((file) => file.rel.startsWith(requiredPrefix))) errors.push(`missing fixture family: ${requiredPrefix}`);
+    }
+    for (const fixture of fixtureExpectations) {
+      try { JSON.parse(await readFile(fixture.abs, 'utf8')); }
+      catch (error) { errors.push(`${fixture.rel}: invalid expected.json (${error.message})`); }
+    }
+    const selfTest = fileByRel.get('scripts/self-test.mjs');
+    if (selfTest) {
+      const text = await readFile(selfTest.abs, 'utf8');
+      if (!text.includes('expected.json')) errors.push('self-test.mjs must discover fixture expected.json files');
+    }
+
+    const manifestFile = fileByRel.get('manifest.txt');
+    if (!manifestFile) errors.push('manifest.txt is missing');
+    else {
+      const expected = await computeManifest(rootReal, files);
+      const actual = await readFile(manifestFile.abs, 'utf8');
+      if (actual !== expected) errors.push('manifest.txt is stale; run sync-manifest.mjs --write');
+    }
+
+    const flatReferenceFiles = files.filter((file) => /^references\/[^/]+\.md$/.test(file.rel));
+    if (flatReferenceFiles.length) errors.push(`references must be grouped by rules/language: ${flatReferenceFiles.map((file) => file.rel).join(', ')}`);
+
+    if (!warnings.length && files.length > 180) warnings.push(`package contains ${files.length} files; verify progressive disclosure remains focused`);
+  } catch (error) {
+    errors.push(error.stack ?? error.message);
+  }
+  failLines(errors, warnings);
+}
+
+await main();