@namewta/speculo 0.8.11 → 1.0.1

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

@@ -83,27 +83,43 @@ function assertFixture(inventory, expected, fixtureName) {
 
 async function writeGeneratedFixture(projectRoot) {
   await mkdir(path.join(projectRoot, 'src'), { recursive: true });
+  await mkdir(path.join(projectRoot, 'docs', 'fm'), { 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');
+  await writeFile(path.join(projectRoot, 'docs', 'fm', 'component.vue.ftl'), '<template><main>${title}</main></template>\n');
 
   const canonical = path.join(projectRoot, '.agents', 'skills', 'engineering-standards');
+  const domain = path.join(projectRoot, '.agents', 'skills', 'generated-vue-development');
   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 mkdir(path.join(domain, 'references'), { recursive: true });
+  await writeFile(path.join(canonical, 'generated-skill-set.json'), `${JSON.stringify({
+    schema_version: 1,
+    generator: 'engineering-standards-builder',
+    skills: [
+      { name: 'engineering-standards', path: '.agents/skills/engineering-standards', role: 'router' },
+      { name: 'generated-vue-development', path: '.agents/skills/generated-vue-development', role: 'domain' },
+    ],
+  }, null, 2)}\n`);
+  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), [skills](references/project/03-skill-map.md), [sources](references/project/04-source-and-template-map.md), [review](references/project/review-checklist.md), [rules](references/rules/core.md), [TypeScript](references/typescript/language.md), and [Vue](references/typescript/frameworks/vue.md). Route Vue work to [generated-vue-development](../generated-vue-development/SKILL.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', '03-skill-map.md'), '# Skill Map\n\n- generated-vue-development: Vue implementation.\n');
+  await writeFile(path.join(canonical, 'references', 'project', '04-source-and-template-map.md'), '# Source and Template Map\n\n- [Vue implementation](../../../../../src/App.vue)\n- [Component template](../../../../../docs/fm/component.vue.ftl)\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;
+  await writeFile(path.join(domain, 'SKILL.md'), '---\nname: generated-vue-development\ndescription: Implement Vue features in the generated fixture.\n---\n\n# Vue Development\n\nRead `../engineering-standards/SKILL.md`, then inspect [the mature component](../../../src/App.vue) and [the project template](../../../docs/fm/component.vue.ftl).\n');
+  await writeFile(path.join(domain, 'references', 'workflow.md'), '# Workflow\n\nUse the project template and verify the component.\n');
+  return { canonical, domain };
 }
 
 async function main() {
@@ -174,9 +190,39 @@ async function main() {
 
     const generatedTemp = await mkdtemp(path.join(os.tmpdir(), 'standards-builder-generated-'));
     tempRoots.push(generatedTemp);
-    const canonical = await writeGeneratedFixture(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()}`);
+    assert(valid.status === 0, `valid generated Skill Set was rejected: ${(valid.stderr || valid.stdout).trim()}`);
+
+    const unowned = path.join(generatedTemp, '.agents', 'skills', 'user-maintained-skill');
+    await mkdir(unowned, { recursive: true });
+    await writeFile(path.join(unowned, 'SKILL.md'), '---\nname: user-maintained-skill\ndescription: User-owned fixture skill.\n---\n\n# User Skill\n');
+    const withUnowned = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(withUnowned.status === 0, 'validator must ignore a Skill outside the Builder ownership manifest');
+
+    const sourceMap = path.join(canonical, 'references', 'project', '04-source-and-template-map.md');
+    const sourceMapText = await readFile(sourceMap, 'utf8');
+    await writeFile(sourceMap, `${sourceMapText}\n- [Missing project source](../../../../../src/missing.ts)\n`);
+    const brokenSource = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(brokenSource.status !== 0, 'validator must reject a missing project source link');
+    await writeFile(sourceMap, sourceMapText);
+
+    const ownershipPath = path.join(canonical, 'generated-skill-set.json');
+    const ownershipText = await readFile(ownershipPath, 'utf8');
+    const badOwnership = JSON.parse(ownershipText);
+    badOwnership.skills[1].path = '.agents/skills/../outside';
+    await writeFile(ownershipPath, `${JSON.stringify(badOwnership, null, 2)}\n`);
+    const escapingOwnership = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(escapingOwnership.status !== 0, 'validator must reject an invalid owned Skill path');
+    await writeFile(ownershipPath, ownershipText);
+
+    const routerPath = path.join(canonical, 'SKILL.md');
+    const routerText = await readFile(routerPath, 'utf8');
+    await writeFile(routerPath, routerText.replace('[generated-vue-development](../generated-vue-development/SKILL.md)', '`generated-vue-development`'));
+    const missingRoute = runNode(generatedValidator, ['--root', generatedTemp, '--strict']);
+    assert(missingRoute.status !== 0, 'validator must reject a domain Skill that is not linked by the router');
+    await writeFile(routerPath, routerText);
+
     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');
@@ -186,7 +232,7 @@ async function main() {
     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');
+    process.stdout.write('self-test: generated Skill Set validator OK\n');
 
     const manifest = runNode(manifestScript, ['--root', args.root, '--check']);
     assert(manifest.status === 0, `manifest check failed: ${(manifest.stderr || manifest.stdout).trim()}`);

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

@@ -35,7 +35,8 @@ async function collect(rootReal) {
   const directories = [];
   async function visit(directory) {
     const relDir = toPosix(path.relative(rootReal, directory)) || '.';
-    const entries = await readdir(directory, { withFileTypes: true });
+    const entries = (await readdir(directory, { withFileTypes: true }))
+      .filter((entry) => entry.name !== '.DS_Store');
     entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
     directories.push({ abs: directory, rel: relDir, entries });
     for (const entry of entries) {
@@ -89,7 +90,7 @@ function normalizeLinkTarget(sourceAbs, link) {
 }
 
 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`;
+  return `${files.map((file) => file.rel).filter((rel) => rel !== 'manifest.txt' && path.posix.basename(rel) !== '.DS_Store').sort((a, b) => a.localeCompare(b, 'en')).join('\n')}\n`;
 }
 
 function failLines(errors, warnings) {
@@ -138,9 +139,11 @@ async function main() {
         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');
+        if (frontmatter.values['disable-model-invocation'] !== 'true') errors.push('Builder must remain explicitly user-invoked with disable-model-invocation: true');
+      }
+      for (const requiredConcept of ['Agent Team', 'generated-skill-set.json', '最小原则', 'Skill 边界']) {
+        if (!skillText.includes(requiredConcept)) errors.push(`SKILL.md is missing core contract: ${requiredConcept}`);
       }
-      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');
@@ -218,6 +221,15 @@ async function main() {
         if (!indexText.includes(file.name)) errors.push(`template is not indexed in templates/README.md: ${file.rel}`);
       }
     }
+    for (const requiredTemplate of [
+      'templates/project-skill/SKILL.md.template',
+      'templates/project-skill/generated-skill-set.json.template',
+      'templates/project-skill/references/project/03-skill-map.md.template',
+      'templates/project-skill/references/project/04-source-and-template-map.md.template',
+      'templates/domain-skill/SKILL.md.template',
+    ]) {
+      if (!fileByRel.has(requiredTemplate)) errors.push(`required Skill Set template missing: ${requiredTemplate}`);
+    }
 
     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}`);

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

@@ -1,28 +1,32 @@
 #!/usr/bin/env node
 
 import { existsSync } from 'node:fs';
-import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+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';
 import { fileURLToPath } from 'node:url';
 
-const CANONICAL_REL = '.agents/skills/engineering-standards';
+const ROUTER_REL = '.agents/skills/engineering-standards';
+const OWNERSHIP_FILE = 'generated-skill-set.json';
 const REQUIRED_PROJECT_REFERENCES = [
   'references/project/00-project-profile.md',
   'references/project/01-module-map.md',
   'references/project/02-decisions-and-exceptions.md',
+  'references/project/03-skill-map.md',
+  'references/project/04-source-and-template-map.md',
   'references/project/review-checklist.md',
 ];
 const ADAPTERS = new Set(['typescript', 'java', 'go', 'rust']);
+const ROLES = new Set(['router', 'domain']);
 
 function usage() {
   return `Usage: node scripts/validate-generated-skill.mjs --root <project-root> [options]\n\n` +
-    `Validate .agents/skills/engineering-standards and optional compatibility wrappers.\n\n` +
+    `Validate the Builder-owned project Skill Set and optional compatibility wrappers.\n\n` +
     `Options:\n` +
     `  --root <path>       Project root (required)\n` +
     `  --inventory <path>  Project Inventory JSON below --root; auto-discover when omitted\n` +
-    `  --strict            Require every detected adapter/framework and reject unselected ones\n` +
+    `  --strict            Reject generated language/framework content without project signals\n` +
     `  --help              Show this help\n`;
 }
 
@@ -37,7 +41,8 @@ function parseArgs(argv) {
       if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
       if (arg === '--root') result.root = value;
       else result.inventory = value;
-      i += 1; continue;
+      i += 1;
+      continue;
     }
     throw new Error(`unknown argument: ${arg}`);
   }
@@ -46,6 +51,7 @@ function parseArgs(argv) {
 }
 
 function toPosix(value) { return value.split(path.sep).join('/'); }
+
 function isInside(root, candidate) {
   const rel = path.relative(root, candidate);
   return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
@@ -64,24 +70,43 @@ function parseFrontmatter(text) {
 }
 
 function markdownLinks(text) {
-  const result = [];
+  const links = [];
   const pattern = /\[[^\]]*\]\(([^)]+)\)/g;
   let match;
-  while ((match = pattern.exec(text)) !== null) result.push(match[1].trim());
-  return result;
+  while ((match = pattern.exec(text)) !== null) {
+    let target = match[1].trim();
+    if (target.startsWith('<')) {
+      const close = target.indexOf('>');
+      if (close >= 0) target = target.slice(1, close);
+    } else {
+      const titleIndex = target.search(/\s+["']/);
+      if (titleIndex >= 0) target = target.slice(0, titleIndex);
+    }
+    links.push(target);
+  }
+  return links;
 }
 
 function isExternal(link) { return /^(?:[a-z]+:|#|\/\/)/i.test(link); }
 
+function linkTarget(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 collectTree(rootAbs) {
   const files = [];
   const directories = [];
-  async function visit(dir) {
-    const entries = await readdir(dir, { withFileTypes: true });
-    directories.push({ abs: dir, entries });
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
     entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    directories.push({ abs: directory, entries });
     for (const entry of entries) {
-      const abs = path.join(dir, entry.name);
+      const abs = path.join(directory, entry.name);
       if (entry.isSymbolicLink()) throw new Error(`symlink is not allowed in generated Skill: ${toPosix(path.relative(rootAbs, abs))}`);
       if (entry.isDirectory()) { await visit(abs); continue; }
       if (entry.isFile()) files.push(abs);
@@ -108,12 +133,27 @@ async function loadInventory(args, rootReal) {
     return JSON.parse(await readFile(inventoryAbs, 'utf8'));
   }
   const discoverScript = path.join(path.dirname(fileURLToPath(import.meta.url)), 'discover-project.mjs');
-  const result = spawnSync(process.execPath, [discoverScript, '--root', rootReal], { encoding: 'utf8', timeout: 60000, maxBuffer: 64 * 1024 * 1024 });
+  const result = spawnSync(process.execPath, [discoverScript, '--root', rootReal], {
+    encoding: 'utf8',
+    timeout: 60000,
+    maxBuffer: 64 * 1024 * 1024,
+  });
   if (result.status !== 0) throw new Error(`automatic project discovery failed: ${(result.stderr || result.stdout).trim()}`);
   return JSON.parse(result.stdout);
 }
 
-async function validateWrapper(projectRoot, wrapperRel, errors) {
+function validateExactKeys(value, allowed, label, errors) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${label} contains unsupported field: ${key}`);
+  }
+}
+
+async function validateWrapper(projectRoot, wrapperRel, ownedPaths, errors) {
+  if (ownedPaths.has(wrapperRel)) return;
   const wrapperRoot = path.join(projectRoot, wrapperRel);
   if (!existsSync(wrapperRoot)) return;
   const info = await stat(wrapperRoot);
@@ -132,7 +172,6 @@ async function validateWrapper(projectRoot, wrapperRel, errors) {
   if (bodyLines.length !== 1) errors.push(`${wrapperRel}/SKILL.md body must be exactly one non-empty routing line`);
   if (!fm.body.includes('engineering-standards')) errors.push(`${wrapperRel}/SKILL.md does not route to engineering-standards`);
   if (fm.body.length > 400) errors.push(`${wrapperRel}/SKILL.md contains too much content for a compatibility wrapper`);
-  if (/typescript-(?:-)?standards\/SKILL\.md/.test(fm.body) && !/engineering-standards/.test(fm.body)) errors.push(`${wrapperRel}/SKILL.md may form a wrapper loop`);
 }
 
 async function main() {
@@ -140,7 +179,8 @@ async function main() {
   try { args = parseArgs(process.argv.slice(2)); }
   catch (error) {
     process.stderr.write(`validate-generated-skill: ${error.message}\n\n${usage()}`);
-    process.exitCode = 2; return;
+    process.exitCode = 2;
+    return;
   }
   if (args.help) { process.stdout.write(usage()); return; }
 
@@ -149,51 +189,109 @@ async function main() {
   try {
     const rootReal = await realpath(path.resolve(args.root));
     if (!(await stat(rootReal)).isDirectory()) throw new Error('--root is not a directory');
-    const canonicalRoot = path.join(rootReal, CANONICAL_REL);
-    if (!existsSync(canonicalRoot)) throw new Error(`${CANONICAL_REL} is missing`);
-    const canonicalReal = await realpath(canonicalRoot);
-    if (!isInside(rootReal, canonicalReal)) throw new Error(`${CANONICAL_REL} resolves outside project root`);
-    const { files, directories } = await collectTree(canonicalReal);
-    for (const directory of directories) {
-      if (directory.entries.length === 0) errors.push(`empty generated directory: ${toPosix(path.relative(rootReal, directory.abs))}`);
+
+    const routerRoot = path.join(rootReal, ROUTER_REL);
+    if (!existsSync(routerRoot)) throw new Error(`${ROUTER_REL} is missing`);
+    const routerReal = await realpath(routerRoot);
+    if (!isInside(rootReal, routerReal)) throw new Error(`${ROUTER_REL} resolves outside project root`);
+
+    const ownershipPath = path.join(routerReal, OWNERSHIP_FILE);
+    if (!existsSync(ownershipPath)) throw new Error(`${ROUTER_REL}/${OWNERSHIP_FILE} is missing`);
+    let ownership;
+    try { ownership = JSON.parse(await readFile(ownershipPath, 'utf8')); }
+    catch (error) { throw new Error(`${ROUTER_REL}/${OWNERSHIP_FILE} is invalid JSON: ${error.message}`); }
+
+    validateExactKeys(ownership, new Set(['schema_version', 'generator', 'skills']), OWNERSHIP_FILE, errors);
+    if (ownership.schema_version !== 1) errors.push(`${OWNERSHIP_FILE} schema_version must be 1`);
+    if (ownership.generator !== 'engineering-standards-builder') errors.push(`${OWNERSHIP_FILE} generator must be engineering-standards-builder`);
+    if (!Array.isArray(ownership.skills) || ownership.skills.length === 0) errors.push(`${OWNERSHIP_FILE} skills must be a non-empty array`);
+
+    const entries = Array.isArray(ownership.skills) ? ownership.skills : [];
+    const names = new Set();
+    const ownedPaths = new Set();
+    const routers = [];
+    for (const [index, entry] of entries.entries()) {
+      const label = `${OWNERSHIP_FILE} skills[${index}]`;
+      validateExactKeys(entry, new Set(['name', 'path', 'role']), label, errors);
+      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry?.name ?? '')) errors.push(`${label} name must be kebab-case`);
+      const expectedPath = `.agents/skills/${entry?.name}`;
+      if (entry?.path !== expectedPath) errors.push(`${label} path must equal ${expectedPath}`);
+      if (!ROLES.has(entry?.role)) errors.push(`${label} role must be router or domain`);
+      if (names.has(entry?.name)) errors.push(`${label} duplicates name ${entry?.name}`);
+      if (ownedPaths.has(entry?.path)) errors.push(`${label} duplicates path ${entry?.path}`);
+      names.add(entry?.name);
+      ownedPaths.add(entry?.path);
+      if (entry?.role === 'router') routers.push(entry);
+    }
+    if (routers.length !== 1) errors.push(`${OWNERSHIP_FILE} must contain exactly one router`);
+    else if (routers[0].name !== 'engineering-standards' || routers[0].path !== ROUTER_REL) {
+      errors.push(`${OWNERSHIP_FILE} router must be engineering-standards at ${ROUTER_REL}`);
     }
-    const fileSet = new Set(files);
-    const mainSkill = path.join(canonicalReal, 'SKILL.md');
-    if (!fileSet.has(mainSkill)) errors.push(`${CANONICAL_REL}/SKILL.md is missing`);
-    else {
+
+    const ownedRoots = [];
+    const ownedMainSkills = new Map();
+    const allOwnedFiles = [];
+    for (const entry of entries) {
+      if (typeof entry?.path !== 'string' || typeof entry?.name !== 'string') continue;
+      const skillRoot = path.resolve(rootReal, entry.path);
+      if (!isInside(rootReal, skillRoot)) { errors.push(`${entry.path} escapes project root`); continue; }
+      if (!existsSync(skillRoot)) { errors.push(`owned Skill is missing: ${entry.path}`); continue; }
+      const skillReal = await realpath(skillRoot);
+      if (!isInside(rootReal, skillReal)) { errors.push(`${entry.path} resolves outside project root`); continue; }
+      const info = await stat(skillReal);
+      if (!info.isDirectory()) { errors.push(`${entry.path} must be a directory`); continue; }
+
+      const tree = await collectTree(skillReal);
+      ownedRoots.push(skillReal);
+      for (const directory of tree.directories) {
+        if (directory.entries.length === 0) errors.push(`empty generated directory: ${toPosix(path.relative(rootReal, directory.abs))}`);
+      }
+      allOwnedFiles.push(...tree.files);
+      const mainSkill = path.join(skillReal, 'SKILL.md');
+      ownedMainSkills.set(entry.name, mainSkill);
+      if (!tree.files.includes(mainSkill)) { errors.push(`${entry.path}/SKILL.md is missing`); continue; }
       const text = await readFile(mainSkill, 'utf8');
       const fm = parseFrontmatter(text);
-      if (!fm) errors.push(`${CANONICAL_REL}/SKILL.md frontmatter is malformed`);
+      if (!fm) errors.push(`${entry.path}/SKILL.md frontmatter is malformed`);
       else {
-        if (fm.values.name !== 'engineering-standards') errors.push(`canonical frontmatter name must be engineering-standards, found ${fm.values.name ?? '<missing>'}`);
-        if (!fm.values.description) errors.push('canonical frontmatter description is missing');
+        if (fm.values.name !== entry.name) errors.push(`${entry.path}/SKILL.md name must be ${entry.name}`);
+        if (!fm.values.description) errors.push(`${entry.path}/SKILL.md description is missing`);
       }
-      if (/typescript-(?:-)?standards\/SKILL\.md/.test(text)) errors.push('canonical Skill must not route back to a compatibility alias');
     }
 
+    const routerFiles = new Set(allOwnedFiles.filter((file) => isInside(routerReal, file)));
     for (const required of REQUIRED_PROJECT_REFERENCES) {
-      const abs = path.join(canonicalReal, required);
-      if (!fileSet.has(abs)) errors.push(`required generated reference is missing: ${required}`);
+      if (!routerFiles.has(path.join(routerReal, required))) errors.push(`required router reference is missing: ${required}`);
     }
 
-    for (const file of files.filter((item) => item.endsWith('.md'))) {
-      const rel = toPosix(path.relative(canonicalReal, file));
+    const routerMain = path.join(routerReal, 'SKILL.md');
+    const routerLinkTargets = new Set();
+    const evidenceLinks = new Set();
+    const sourceMapPath = path.join(routerReal, 'references/project/04-source-and-template-map.md');
+
+    for (const file of allOwnedFiles.filter((item) => item.endsWith('.md'))) {
+      const rel = toPosix(path.relative(rootReal, file));
       const text = await readFile(file, 'utf8');
       if (/\{\{[A-Z0-9_]+\}\}|<PROJECT_NAME>|<REPOSITORY_ROOT>/.test(text)) errors.push(`${rel}: unresolved template placeholder`);
-      for (let link of markdownLinks(text)) {
+      for (const link of markdownLinks(text)) {
         if (isExternal(link)) continue;
-        if (link.startsWith('<') && link.endsWith('>')) link = link.slice(1, -1);
-        const targetPart = link.split('#')[0].split('?')[0];
-        if (!targetPart) continue;
-        const target = path.resolve(path.dirname(file), decodeURIComponent(targetPart));
-        if (!isInside(canonicalReal, target)) {
-          errors.push(`${rel}: link escapes canonical Skill: ${link}`);
-          continue;
+        const target = linkTarget(file, link);
+        if (!target) continue;
+        if (!isInside(rootReal, target)) { errors.push(`${rel}: link escapes project root: ${link}`); continue; }
+        if (!existsSync(target)) { errors.push(`${rel}: broken project link: ${link}`); continue; }
+        const directInfo = await lstat(target);
+        if (directInfo.isSymbolicLink()) { errors.push(`${rel}: link target must not be a symlink: ${link}`); continue; }
+        const targetReal = await realpath(target);
+        if (!isInside(rootReal, targetReal)) { errors.push(`${rel}: link resolves outside project root: ${link}`); continue; }
+        if (file === routerMain) routerLinkTargets.add(targetReal);
+        if (file === sourceMapPath && !ownedRoots.some((ownedRoot) => isInside(ownedRoot, targetReal))) {
+          if (!directInfo.isFile()) errors.push(`${rel}: project evidence link must target a file: ${link}`);
+          else evidenceLinks.add(targetReal);
         }
-        if (!existsSync(target)) errors.push(`${rel}: broken local link: ${link}`);
       }
 
-      if (!rel.startsWith('references/project/')) {
+      const routerProjectPrefix = toPosix(path.relative(rootReal, path.join(routerReal, 'references/project')));
+      if (!rel.startsWith(`${routerProjectPrefix}/`)) {
         for (const levelMatch of text.matchAll(/^Level:\s*(MUST|SHOULD)\s*$/gm)) {
           const section = sectionForOffset(text, levelMatch.index);
           for (const field of ['Scope:', 'Source:', 'Rule:', 'Verification:']) {
@@ -203,9 +301,26 @@ async function main() {
       }
     }
 
+    if (existsSync(sourceMapPath) && evidenceLinks.size === 0) {
+      errors.push('04-source-and-template-map.md must link to at least one real project file outside the generated Skill Set');
+    }
+
+    for (const entry of entries.filter((item) => item?.role === 'domain')) {
+      const mainSkill = ownedMainSkills.get(entry.name);
+      if (mainSkill && existsSync(mainSkill)) {
+        const mainReal = await realpath(mainSkill);
+        if (!routerLinkTargets.has(mainReal)) errors.push(`router SKILL.md does not link to domain Skill: ${entry.name}`);
+      }
+    }
+
+    if (existsSync(routerMain)) {
+      const routerText = await readFile(routerMain, 'utf8');
+      if (/typescript-(?:-)?standards\/SKILL\.md/.test(routerText)) errors.push('router Skill must not route back to a compatibility alias');
+    }
+
     const inventory = await loadInventory(args, rootReal);
     const detectedAdapters = new Set(inventory?.summary?.adapters ?? []);
-    const generatedReferenceRoot = path.join(canonicalReal, 'references');
+    const generatedReferenceRoot = path.join(routerReal, 'references');
     const generatedAdapters = new Set();
     if (existsSync(generatedReferenceRoot)) {
       for (const entry of await readdir(generatedReferenceRoot, { withFileTypes: true })) {
@@ -218,12 +333,6 @@ async function main() {
         if (args.strict) errors.push(message); else warnings.push(message);
       }
     }
-    for (const adapter of detectedAdapters) {
-      if (!generatedAdapters.has(adapter)) {
-        const message = `detected adapter ${adapter} is missing from generated references`;
-        if (args.strict) errors.push(message); else warnings.push(message);
-      }
-    }
 
     const detectedFrameworks = new Set(inventory?.summary?.frameworks ?? []);
     const frameworkContracts = [
@@ -232,17 +341,11 @@ async function main() {
       ['spring-boot', 'java', 'references/java/frameworks/spring-boot.md'],
     ];
     for (const [framework, requiredAdapter, rel] of frameworkContracts) {
-      const present = fileSet.has(path.join(canonicalReal, rel));
-      const frameworkDetected = detectedFrameworks.has(framework);
-      const adapterDetected = detectedAdapters.has(requiredAdapter);
-      if (present && (!frameworkDetected || !adapterDetected)) {
+      const present = routerFiles.has(path.join(routerReal, rel));
+      if (present && (!detectedFrameworks.has(framework) || !detectedAdapters.has(requiredAdapter))) {
         const message = `generated framework rule ${framework} has no matching ${requiredAdapter} adapter and framework signal`;
         if (args.strict) errors.push(message); else warnings.push(message);
       }
-      if (!present && frameworkDetected && adapterDetected) {
-        const message = `detected framework ${framework} is missing generated rule ${rel}`;
-        if (args.strict) errors.push(message); else warnings.push(message);
-      }
     }
 
     for (const wrapper of [
@@ -250,16 +353,15 @@ async function main() {
       '.agents/skills/typescript--standards',
       '.claude/skills/engineering-standards',
       '.claude/skills/typescript-standards',
-    ]) await validateWrapper(rootReal, wrapper, errors);
+    ]) await validateWrapper(rootReal, wrapper, ownedPaths, errors);
 
-    // Detect substantial duplicate canonical copies under known agent roots.
     for (const baseRel of ['.agents/skills', '.claude/skills']) {
       const base = path.join(rootReal, baseRel);
       if (!existsSync(base)) continue;
       for (const entry of await readdir(base, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
         const candidate = path.join(base, entry.name, 'SKILL.md');
-        if (!existsSync(candidate) || candidate === mainSkill) continue;
+        if (!existsSync(candidate) || candidate === routerMain) continue;
         const text = await readFile(candidate, 'utf8');
         const fm = parseFrontmatter(text);
         if (fm?.values?.name === 'engineering-standards' && fm.body.trim().length > 400) {
@@ -268,7 +370,7 @@ async function main() {
       }
     }
 
-    if ((inventory?.scan?.truncated ?? false) === true) warnings.push('Project Inventory scan was truncated; adapter selection requires manual verification');
+    if ((inventory?.scan?.truncated ?? false) === true) warnings.push('Project Inventory scan was truncated; source coverage requires manual verification');
     for (const item of inventory?.conflicts ?? []) warnings.push(`Project Inventory conflict: ${item.scope ?? 'repository'} ${item.type}`);
   } catch (error) {
     errors.push(error.stack ?? error.message);

package/template/skills/engineering-standards-builder/templates/README.md

@@ -1,15 +1,24 @@
-# 生成模板索引
+# 项目 Skill Set 模板索引
 
-模板只用于生成项目专属 Skill；占位符必须在写入目标前全部替换。
+模板只用于生成项目专属 Skill Set；占位符必须在写入目标前全部替换。模板提供最小结构，不要求生成固定数量的领域 Skill 或 references。
 
-## Canonical Skill
+## 根路由 Skill
 
 - [主入口](project-skill/SKILL.md.template)
+- [Builder 所有权清单](project-skill/generated-skill-set.json.template)
 - [项目画像](project-skill/references/project/00-project-profile.md.template)
 - [模块地图](project-skill/references/project/01-module-map.md.template)
 - [决策与例外](project-skill/references/project/02-decisions-and-exceptions.md.template)
+- [Skill 地图](project-skill/references/project/03-skill-map.md.template)
+- [源码与模板地图](project-skill/references/project/04-source-and-template-map.md.template)
 - [评审清单](project-skill/references/project/review-checklist.md.template)
 
+## 可选领域 Skill
+
+- [领域入口](domain-skill/SKILL.md.template)
+
+只有通过 Skill 拆分门时才创建领域 Skill。领域 references 由真实证据决定，不提供固定目录模板。
+
 ## 单向兼容入口
 
 - [Agents：typescript-standards](compatibility/agents-typescript-standards.md)

package/template/skills/engineering-standards-builder/templates/domain-skill/SKILL.md.template

@@ -0,0 +1,32 @@
+---
+name: {{SKILL_NAME}}
+description: {{DESCRIPTION}}
+---
+
+# {{TITLE}}
+
+处理以下触发场景时使用本 Skill：
+
+{{TRIGGERS}}
+
+先读取项目根路由 `../engineering-standards/SKILL.md` 中的全局边界与决策。本 Skill 只负责 {{DOMAIN_RESPONSIBILITY}}，不重新定义跨域规范。
+
+## 适用范围
+
+{{SCOPE_AND_EXCLUSIONS}}
+
+## 实现流程
+
+{{WORKFLOW}}
+
+## 项目事实源
+
+{{SOURCE_AND_TEMPLATE_ROUTES}}
+
+读取真实源码、模板、消费者和测试；不要把它们复制进本 Skill。每个来源都要说明适用条件、输出位置、手工集成和验证。
+
+## 完成检查
+
+{{VERIFICATION}}
+
+无法由项目证据确认的事项标记 `pending-decision`，不要用 Builder 默认补齐。

package/template/skills/engineering-standards-builder/templates/project-skill/SKILL.md.template

@@ -1,26 +1,31 @@
 ---
 name: engineering-standards
-description: 为 {{PROJECT_NAME}} 的实现、重构、评审与交付提供按模块路由的工程规范。处理代码、目录、测试、构建、依赖、API 或 CI 变化前使用。
+description: 为 {{PROJECT_NAME}} 的代码、目录、测试、构建、依赖、API 与交付变更提供项目专属规范和领域 Skill 路由。
 ---
 
 # {{PROJECT_NAME}} Engineering Standards
 
-本 Skill 只描述本项目已确认的规范。先确定变更 scope，再加载最小充分 references；不要把一个模块的语言或框架规则扩散到其他模块。
+本 Skill 是项目工程规范的权威入口。先确定变更 scope，再读取最小充分的项目证据或领域 Skill；同级领域 Skill 不得覆盖这里的决策与边界。
 
 ## 每次执行
 
 1. 读取 [项目画像](references/project/00-project-profile.md) 和 [模块地图](references/project/01-module-map.md)。
-2. 将当前任务映射到 repository、module、language、framework、runtime 或 path scope。
-3. 读取与变更相关的通用规则：{{COMMON_RULE_LINKS}}。
-4. 按模块地图只读取适用语言/框架规则：{{ADAPTER_ROUTE_LINKS}}。
-5. 读取 [决策与例外](references/project/02-decisions-and-exceptions.md)，确认 current、target、migration 与未到期 exception。
+2. 将当前任务映射到 repository、module、language、framework、runtime、path 或 public-api scope。
+3. 读取 [Skill 地图](references/project/03-skill-map.md)，判断是否应转到领域 Skill：{{DOMAIN_SKILL_ROUTES}}。
+4. 按任务读取 [源码与模板地图](references/project/04-source-and-template-map.md) 中的真实代码、模板、消费者和测试，不复制这些事实源。
+5. 读取 [决策与例外](references/project/02-decisions-and-exceptions.md)，区分 current、target、migration、pending-decision 和未到期 exception。
 6. 实现前检查 public API、依赖方向、安全、错误/取消/资源和测试影响。
-7. 实现后运行项目画像中该 scope 的真实质量门禁，并按 [评审清单](references/project/review-checklist.md) 报告结果。
+7. 实现后运行该 scope 的真实质量门禁，并按 [评审清单](references/project/review-checklist.md) 报告。
+
+## 项目规则路由
+
+{{PROJECT_RULE_ROUTES}}
 
 ## 约束
 
-- MUST 规则只有在 Verification 可执行或有精确 review 证据时成立。
-- 不适用规则不加载；generated/vendor/frozen scope 不手工修改。
-- 不通过删除测试、关闭核心规则、放宽编译配置或扩大例外获得通过。
+- 项目代码、测试、配置、CI 和已声明模板是事实源；通用建议不能伪装成项目规范。
+- MUST 只有在 Verification 可执行或有精确 review 证据时成立。
+- generated/vendor/frozen scope 不手工修改。
+- 不通过删除测试、放宽核心配置或扩大例外获得通过。
 - 新代码遵循 Target；存量偏差按 Migration/Ratchet 处理。
-- 项目事实变化时更新 Project Profile/Module Map，再更新规则，不静默猜测。
+- 事实变化时先更新项目画像、来源地图和决策，再更新规范。