@namewta/speculo 0.7.4 → 0.7.5

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

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { 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 REQUIRED_PROJECT_REFERENCES = [
+  'references/project/00-project-profile.md',
+  'references/project/01-module-map.md',
+  'references/project/02-decisions-and-exceptions.md',
+  'references/project/review-checklist.md',
+];
+const ADAPTERS = new Set(['typescript', 'java', 'go', 'rust']);
+
+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` +
+    `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` +
+    `  --help              Show this help\n`;
+}
+
+function parseArgs(argv) {
+  const result = { root: null, inventory: null, strict: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    if (arg === '--strict') { result.strict = true; continue; }
+    if (arg === '--root' || arg === '--inventory') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--root') result.root = value;
+      else result.inventory = 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('/'); }
+function isInside(root, candidate) {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return null;
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0) return null;
+  const values = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) values[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '');
+  }
+  return { values, body: text.slice(end + 5) };
+}
+
+function markdownLinks(text) {
+  const result = [];
+  const pattern = /\[[^\]]*\]\(([^)]+)\)/g;
+  let match;
+  while ((match = pattern.exec(text)) !== null) result.push(match[1].trim());
+  return result;
+}
+
+function isExternal(link) { return /^(?:[a-z]+:|#|\/\/)/i.test(link); }
+
+async function collectTree(rootAbs) {
+  const files = [];
+  const directories = [];
+  async function visit(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    directories.push({ abs: dir, entries });
+    entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    for (const entry of entries) {
+      const abs = path.join(dir, 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);
+    }
+  }
+  await visit(rootAbs);
+  return { files, directories };
+}
+
+function sectionForOffset(text, offset) {
+  const headings = [...text.matchAll(/^#{1,3}\s+.+$/gm)].map((match) => ({ index: match.index, text: match[0] }));
+  const previous = headings.filter((heading) => heading.index <= offset).at(-1);
+  const next = headings.find((heading) => heading.index > offset);
+  return {
+    title: previous?.text ?? '<document>',
+    text: text.slice(previous?.index ?? 0, next?.index ?? text.length),
+  };
+}
+
+async function loadInventory(args, rootReal) {
+  if (args.inventory) {
+    const inventoryAbs = path.resolve(rootReal, args.inventory);
+    if (!isInside(rootReal, inventoryAbs)) throw new Error(`--inventory escapes --root: ${args.inventory}`);
+    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 });
+  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) {
+  const wrapperRoot = path.join(projectRoot, wrapperRel);
+  if (!existsSync(wrapperRoot)) return;
+  const info = await stat(wrapperRoot);
+  if (!info.isDirectory()) { errors.push(`${wrapperRel} must be a directory`); return; }
+  const entries = await readdir(wrapperRoot, { withFileTypes: true });
+  const nonSkillEntries = entries.filter((entry) => entry.name !== 'SKILL.md');
+  if (nonSkillEntries.length > 0) errors.push(`${wrapperRel} compatibility wrapper must contain only SKILL.md`);
+  const skillPath = path.join(wrapperRoot, 'SKILL.md');
+  if (!existsSync(skillPath)) { errors.push(`${wrapperRel}/SKILL.md is missing`); return; }
+  const text = await readFile(skillPath, 'utf8');
+  const fm = parseFrontmatter(text);
+  if (!fm) { errors.push(`${wrapperRel}/SKILL.md frontmatter is malformed`); return; }
+  const expectedName = path.basename(wrapperRoot);
+  if (fm.values.name !== expectedName) errors.push(`${wrapperRel}/SKILL.md name must be ${expectedName}`);
+  const bodyLines = fm.body.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  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() {
+  let args;
+  try { args = parseArgs(process.argv.slice(2)); }
+  catch (error) {
+    process.stderr.write(`validate-generated-skill: ${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 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 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 text = await readFile(mainSkill, 'utf8');
+      const fm = parseFrontmatter(text);
+      if (!fm) errors.push(`${CANONICAL_REL}/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 (/typescript-(?:-)?standards\/SKILL\.md/.test(text)) errors.push('canonical Skill must not route back to a compatibility alias');
+    }
+
+    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}`);
+    }
+
+    for (const file of files.filter((item) => item.endsWith('.md'))) {
+      const rel = toPosix(path.relative(canonicalReal, 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)) {
+        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;
+        }
+        if (!existsSync(target)) errors.push(`${rel}: broken local link: ${link}`);
+      }
+
+      if (!rel.startsWith('references/project/')) {
+        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:']) {
+            if (!section.text.includes(field)) errors.push(`${rel} ${section.title}: ${levelMatch[1]} rule is missing ${field}`);
+          }
+        }
+      }
+    }
+
+    const inventory = await loadInventory(args, rootReal);
+    const detectedAdapters = new Set(inventory?.summary?.adapters ?? []);
+    const generatedReferenceRoot = path.join(canonicalReal, 'references');
+    const generatedAdapters = new Set();
+    if (existsSync(generatedReferenceRoot)) {
+      for (const entry of await readdir(generatedReferenceRoot, { withFileTypes: true })) {
+        if (entry.isDirectory() && ADAPTERS.has(entry.name)) generatedAdapters.add(entry.name);
+      }
+    }
+    for (const adapter of generatedAdapters) {
+      if (!detectedAdapters.has(adapter)) {
+        const message = `generated adapter ${adapter} has no matching Project Inventory signal`;
+        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 = [
+      ['vue', 'typescript', 'references/typescript/frameworks/vue.md'],
+      ['react', 'typescript', 'references/typescript/frameworks/react.md'],
+      ['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 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 [
+      '.agents/skills/typescript-standards',
+      '.agents/skills/typescript--standards',
+      '.claude/skills/engineering-standards',
+      '.claude/skills/typescript-standards',
+    ]) await validateWrapper(rootReal, wrapper, 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;
+        const text = await readFile(candidate, 'utf8');
+        const fm = parseFrontmatter(text);
+        if (fm?.values?.name === 'engineering-standards' && fm.body.trim().length > 400) {
+          errors.push(`substantial duplicate engineering-standards content found at ${toPosix(path.relative(rootReal, candidate))}`);
+        }
+      }
+    }
+
+    if ((inventory?.scan?.truncated ?? false) === true) warnings.push('Project Inventory scan was truncated; adapter selection 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);
+  }
+
+  for (const warning of warnings) process.stderr.write(`validate-generated-skill: WARN: ${warning}\n`);
+  if (errors.length) {
+    for (const error of errors) process.stderr.write(`validate-generated-skill: ERROR: ${error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`validate-generated-skill: OK${warnings.length ? ` (${warnings.length} warning(s))` : ''}\n`);
+}
+
+await main();

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

@@ -0,0 +1,18 @@
+# 生成模板索引
+
+模板只用于生成项目专属 Skill；占位符必须在写入目标前全部替换。
+
+## Canonical Skill
+
+- [主入口](project-skill/SKILL.md.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)
+- [评审清单](project-skill/references/project/review-checklist.md.template)
+
+## 单向兼容入口
+
+- [Agents：typescript-standards](compatibility/agents-typescript-standards.md)
+- [Agents：typescript--standards](compatibility/agents-typescript--standards.md)
+- [Claude：engineering-standards](compatibility/claude-engineering-standards.md)
+- [Claude：typescript-standards](compatibility/claude-typescript-standards.md)

package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript--standards.md

@@ -0,0 +1,6 @@
+---
+name: typescript--standards
+description: 兼容历史双连字符调用方；正式工程规范位于 engineering-standards。
+---
+
+读取并遵循 `../engineering-standards/SKILL.md`；本目录仅为单向兼容别名，不维护规范正文。

package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript-standards.md

@@ -0,0 +1,6 @@
+---
+name: typescript-standards
+description: 兼容旧调用方；正式工程规范位于 engineering-standards。
+---
+
+读取并遵循 `../engineering-standards/SKILL.md`；本目录仅为单向兼容别名，不维护规范正文。

package/template/skills/engineering-standards-builder/templates/compatibility/claude-engineering-standards.md

@@ -0,0 +1,6 @@
+---
+name: engineering-standards
+description: 路由到 .agents 中的 canonical 工程规范。
+---
+
+读取并遵循 `../../../.agents/skills/engineering-standards/SKILL.md`；本目录仅为单向 Agent 兼容入口。

package/template/skills/engineering-standards-builder/templates/compatibility/claude-typescript-standards.md

@@ -0,0 +1,6 @@
+---
+name: typescript-standards
+description: 兼容旧 Claude 调用方；正式工程规范位于 .agents/skills/engineering-standards。
+---
+
+读取并遵循 `../../../.agents/skills/engineering-standards/SKILL.md`；本目录仅为单向兼容别名。

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

@@ -0,0 +1,26 @@
+---
+name: engineering-standards
+description: 为 {{PROJECT_NAME}} 的实现、重构、评审与交付提供按模块路由的工程规范。处理代码、目录、测试、构建、依赖、API 或 CI 变化前使用。
+---
+
+# {{PROJECT_NAME}} Engineering Standards
+
+本 Skill 只描述本项目已确认的规范。先确定变更 scope，再加载最小充分 references；不要把一个模块的语言或框架规则扩散到其他模块。
+
+## 每次执行
+
+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。
+6. 实现前检查 public API、依赖方向、安全、错误/取消/资源和测试影响。
+7. 实现后运行项目画像中该 scope 的真实质量门禁，并按 [评审清单](references/project/review-checklist.md) 报告结果。
+
+## 约束
+
+- MUST 规则只有在 Verification 可执行或有精确 review 证据时成立。
+- 不适用规则不加载；generated/vendor/frozen scope 不手工修改。
+- 不通过删除测试、关闭核心规则、放宽编译配置或扩大例外获得通过。
+- 新代码遵循 Target；存量偏差按 Migration/Ratchet 处理。
+- 项目事实变化时更新 Project Profile/Module Map，再更新规则，不静默猜测。

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

@@ -0,0 +1,26 @@
+# 项目画像
+
+## 身份
+
+- Project: {{PROJECT_NAME}}
+- Repository root: {{REPOSITORY_ROOT}}
+- Topology: {{TOPOLOGY}}
+- Inventory schema: {{INVENTORY_SCHEMA_VERSION}}
+
+## 事实来源
+
+{{EVIDENCE_SUMMARY}}
+
+## 工具链与质量门禁
+
+{{QUALITY_GATES}}
+
+每个命令必须包含 scope、working directory、来源和当前状态（active/planned）。
+
+## 排除与冻结区域
+
+{{EXCLUDED_AND_FROZEN_PATHS}}
+
+## 未知与冲突
+
+{{UNKNOWNS_AND_CONFLICTS}}

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

@@ -0,0 +1,27 @@
+# 模块地图
+
+{{MODULE_TABLE}}
+
+每个模块至少记录：
+
+```text
+id
+path
+languages
+frameworks
+runtimes
+build systems
+source/test roots
+public entrypoints
+generated paths
+quality gates
+evidence/confidence
+```
+
+## 依赖方向
+
+{{DEPENDENCY_DIRECTIONS}}
+
+## 路由
+
+{{MODULE_RULE_ROUTES}}

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

@@ -0,0 +1,31 @@
+# 决策、迁移与例外
+
+## 决策
+
+{{DECISIONS}}
+
+推荐格式：
+
+```text
+Decision ID:
+Scope:
+Decision:
+Source: user-decision | repository-fact | official-guidance | builder-baseline
+Rationale:
+Migration:
+Verification:
+```
+
+## 当前状态与目标状态
+
+{{CURRENT_TARGET_MIGRATIONS}}
+
+## 例外
+
+{{EXCEPTIONS}}
+
+每个例外必须包含 ID、Scope、Rule、Owner、Reason、Risk、Compensation、Created、Expires/removal condition 和 Verification。没有 owner 或删除条件的临时例外无效。
+
+## 待确认
+
+{{PENDING_DECISIONS}}

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

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