@namewta/speculo 0.8.11 → 0.8.13

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，再更新规则，不静默猜测。
+- 事实变化时先更新项目画像、来源地图和决策，再更新规范。

package/template/skills/engineering-standards-builder/templates/project-skill/generated-skill-set.json.template

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "generator": "engineering-standards-builder",
+  "skills": [
+{{SKILL_ENTRIES}}
+  ]
+}

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/00-project-profile.md.template

@@ -11,11 +11,13 @@
 
 {{EVIDENCE_SUMMARY}}
 
+证据使用项目根相对路径。扫描结果只作基线，重要结论必须由源码、配置、CI、测试、消费者或已声明模板复核。
+
 ## 工具链与质量门禁
 
 {{QUALITY_GATES}}
 
-每个命令必须包含 scope、working directory、来源和当前状态（active/planned）。
+每个命令必须包含 scope、working directory、来源和当前状态（active/planned）。`planned` 不能作为已通过门禁。
 
 ## 排除与冻结区域
 

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/01-module-map.md.template

@@ -18,6 +18,8 @@ quality gates
 evidence/confidence
 ```
 
+不要因根目录 manifest 或单个扩展名把语言/框架规则扩散到其他模块。
+
 ## 依赖方向
 
 {{DEPENDENCY_DIRECTIONS}}
@@ -25,3 +27,5 @@ evidence/confidence
 ## 路由
 
 {{MODULE_RULE_ROUTES}}
+
+领域 Skill 的独立触发和 owner 统一记录在 [Skill 地图](03-skill-map.md)。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/02-decisions-and-exceptions.md.template

@@ -10,7 +10,7 @@
 Decision ID:
 Scope:
 Decision:
-Source: user-decision | repository-fact | official-guidance | builder-baseline
+Source: user-decision | repository-fact | project-template | official-guidance | builder-baseline
 Rationale:
 Migration:
 Verification:

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/03-skill-map.md.template

@@ -0,0 +1,19 @@
+# Skill 地图
+
+`engineering-standards` 是规范权威。只有当前任务命中下表中的独立触发条件时，才读取对应领域 Skill。
+
+{{SKILL_MAP}}
+
+每个领域 Skill 记录：
+
+```text
+Name
+Role
+Triggers
+Scope
+Canonical evidence
+Exclusions
+Relationship to engineering-standards
+```
+
+清单外的项目 Skill 不归 Engineering Standards Builder 所有，不得因 refresh 被修改或删除。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/04-source-and-template-map.md.template

@@ -0,0 +1,22 @@
+# 源码与模板地图
+
+这里导航到项目中的唯一事实源，不复制源码、FM 模板或脚手架正文。每个记录必须含至少一个可解析的项目内 Markdown 链接。
+
+{{SOURCE_AND_TEMPLATE_RECORDS}}
+
+推荐格式：
+
+```text
+## <Capability>
+- Read when:
+- Canonical source/template: project-relative Markdown link
+- Role:
+- Applies when:
+- Produces:
+- Manual integration:
+- Consumers/tests:
+- Verification:
+- Legacy/counterexamples:
+```
+
+模板只负责骨架时必须明确列出生成后仍需完成的业务逻辑、注册、import、配置和测试。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/review-checklist.md.template

@@ -3,12 +3,14 @@
 只检查与当前 scope 和风险相关的条目。
 
 - [ ] 变更映射到模块地图中的明确 scope。
+- [ ] 只读取了 Skill 地图路由的最小充分领域 Skill 和项目来源。
 - [ ] 依赖只通过允许的 public contract，未产生循环或深导入。
 - [ ] 外部输入、权限、秘密和敏感数据边界已处理。
 - [ ] 错误、超时、取消、资源和并发生命周期完整。
 - [ ] public API、schema、事件、CLI 或持久化兼容影响已说明。
 - [ ] 测试层级匹配风险，失败与清理路径被覆盖。
 - [ ] generated/vendor/frozen 文件未被无意修改。
+- [ ] 引用的源码/FM/脚手架仍是项目真实路径，未在 Skill 中复制第二份事实源。
 - [ ] 实际运行的 format/lint/compile/test/build 命令及退出码已记录。
 - [ ] 当前状态、目标状态、Ratchet 与例外没有混写。
 - [ ] 文档、迁移、回滚、可观测性和发布影响按需更新。