@namewta/speculo 1.0.24 → 2.0.1

package/template/skills/engineering-standards-builder/SKILL.md

@@ -1,161 +0,0 @@
----
-name: engineering-standards-builder
-description: Generate or refresh project-specific engineering skills after the user explicitly invokes the builder.
-disable-model-invocation: true
-metadata: {"speculo-invocation": "user-only"}
----
-
-# Engineering Standards Builder
-
-本 Skill 只在用户明确调用时运行。它不会在新项目中自动启动，也不把 Builder 自带的通用建议直接复制成项目规范。
-
-目标是先理解当前项目真实的代码、目录、配置、测试、CI 与模板，再生成一组可长期复用的项目专属 Skill：一个稳定的工程规范路由入口，以及零个或多个有独立触发价值的领域 Skill。
-
-```text
-项目事实 + 用户指定的重点范围 + 已确认目标
-  -> 证据审计与冲突收敛
-  -> 最小充分 Skill Set
-  -> .agents/skills/
-```
-
-## 产物与所有权
-
-始终生成根路由：
-
-```text
-.agents/skills/
-├── engineering-standards/
-│   ├── SKILL.md
-│   ├── generated-skill-set.json
-│   └── references/project/
-│       ├── 00-project-profile.md
-│       ├── 01-module-map.md
-│       ├── 02-decisions-and-exceptions.md
-│       ├── 03-skill-map.md
-│       ├── 04-source-and-template-map.md
-│       └── review-checklist.md
-└── <optional-domain-skill>/
-    ├── SKILL.md
-    └── references/...
-```
-
-`engineering-standards` 是规范权威与路由器；领域 Skill 负责可独立触发的实现导航，不重复定义冲突规则。`generated-skill-set.json` 只登记 Builder 拥有的 `.agents/skills/*` 路径。刷新时不得改动或删除清单之外的 Skill。
-
-## 最小原则
-
-- 不按语言、目录或 Agent 数量机械拆 Skill。
-- 能由根路由和少量 references 清楚表达时，不新增领域 Skill。
-- 没有项目证据的规则不生成；Builder references 只提供审计维度与 fallback。
-- 不复制项目源码、FM 模板或脚手架正文；引用其真实路径并说明适用条件、集成步骤和验证方式。
-- 不新增配置文件、参数、时间戳、hash 或模型元数据来制造形式化负担。
-- 扫描深度、文件数和字节限制只是脚本内部资源保护，不是用户需要决策的项目规范。
-
-## 执行流程
-
-### 1. 确定项目根与学习范围
-
-从用户当前工作目录、Git/Workspace 边界和用户指定的代码或目录确定真实项目根。记录需要重点学习的模块、代码、目录、模板或脚手架；未指定时覆盖所有可编辑模块。
-
-读取现有 `AGENTS.md`、`CLAUDE.md`、贡献文档、架构文档和 `.agents/skills/`，但将它们视为待验证证据。识别 generated、vendor、build、cache、fixture 与冻结目录。发现已有 `generated-skill-set.json` 时进入 refresh；只有 legacy `engineering-standards` 时，在计划中声明接管该根 Skill，其他现有 Skill 一律视为非 Builder 所有。
-
-冲突优先级见 [治理与证据优先级](references/rules/00-governance-and-precedence.md)，路径和 scope 见 [证据、拓扑与作用域](references/rules/02-evidence-topology-and-scope.md)。本阶段只读。
-
-**完成标准**：项目根、重点范围、排除范围、现有规范和 Builder 写入边界明确。
-
-### 2. 建立确定性事实基线
-
-运行扫描器并捕获 stdout；默认不在项目中持久化 inventory：
-
-```bash
-node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
-```
-
-扫描合同见 [项目发现合同](references/rules/01-project-discovery.md)。扫描器只提供拓扑基线，不能替代源码审计。继续读取真实 manifest/build 配置、CI 命令、公共入口、代表性实现、测试、消费者与项目模板。
-
-**完成标准**：每个可编辑模块有路径、技术栈、入口、质量门禁和证据；扫描限制、冲突与未知项已记录。
-
-存在可机械验证的边界/约束缺口时，读取 [工程约束](references/rules/09-mechanical-guardrails.md)，决定是否提出接入与验证方案。
-
-### 3. 用 Agent Team 分域取证
-
-当运行环境支持 Agent Team 且存在两个以上可独立审计的证据域时，默认由 leader 并行派发只读 scout。证据域按项目真实边界划分，例如架构与公共 API、后端、前端、公共复用、测试与 CI、FM/脚手架；不得套用固定角色表。
-
-leader 是唯一写入者。每个 scout 必须返回同一份精简证据合同：
-
-```text
-Scope
-Observed capability
-Canonical source paths
-Mature implementations
-Template paths
-Consumers and tests
-Applicable conditions
-Legacy/counterexamples
-Conflicts/unknowns
-Recommended skill boundary
-```
-
-leader 必须复读高影响路径，检查跨域冲突，并把同一事实的重复报告合并。Agent Team 不可用或任务不可合理拆分时，leader 按相同合同顺序审计；结果标准不变。
-
-**完成标准**：重要规范均有真实路径、消费者或测试支撑；反例、旧实现和未知项没有被“多数模式”掩盖。
-
-### 4. 收敛规范与 Skill 边界
-
-先识别项目已经声明的 canonical 模板或代码样板，例如 `docs/fm/**`、scaffold、generator assets。模板与成熟代码冲突时，判断它是目标模板、过期模板还是仅负责骨架，并记录 current、target 与 migration；不得静默任选一方。
-
-只有同时满足以下条件才创建领域 Skill：
-
-1. 有可独立描述的触发场景；
-2. 会在多次开发中复用；
-3. 有充分的项目源码、模板、测试或配置证据；
-4. 与根路由或其他领域 Skill 边界清晰；
-5. 独立后能明显减少无关上下文。
-
-否则内容留在 `engineering-standards`。领域 Skill 名称来自项目语义，不使用固定列表或固定数量。高影响未知项按 [决策收敛合同](references/rules/03-interview-and-decisions.md) 询问；用户已授权直接生成时，将无法安全推断的事项记为 `pending-decision`。
-
-只读取与项目事实匹配的 [通用规则索引](references/rules/README.md)、[TypeScript/JavaScript](references/typescript/README.md)、[Java](references/java/README.md)、[Go](references/go/README.md) 或 [Rust](references/rust/README.md) references。内置语言包和 [未内置语言 fallback](references/rules/16-language-adapter-contract.md) 是检查清单，不是高于项目代码的规范来源。
-
-**完成标准**：每个生成 Skill 都有独立价值和证据边界；没有为了覆盖目录或技术栈而过度拆分。
-
-### 5. 计划、生成与刷新
-
-先展示精简计划：模块与证据摘要、Skill Map、每个 Skill 的来源路径、保留/更新/新增/删除项、冲突决策和验证命令。用户已在当前请求中授权实施时，展示后直接执行。
-
-按 [Skill Set 生成合同](references/rules/14-generation-contract.md) 和 [模板索引](templates/README.md) 生成。所有项目引用使用项目根相对路径，并说明：何时读取、它负责什么、输出位置、需要哪些手工集成、运行什么验证。
-
-先准备完整候选内容并校验，再替换 Builder 拥有的文件。刷新规则：
-
-- 只更新或删除旧 `generated-skill-set.json` 登记的路径；
-- 名称与未登记 Skill 冲突时停止覆盖并重新命名或询问；
-- 保留仍有效的用户决策、例外和项目特有知识；
-- 删除或重命名必须在计划中显式列出；
-- 候选验证失败时保留旧 Skill Set；发布后验证失败时恢复旧内容；
-- 相同项目事实与决策重复运行应无无意义 diff。
-
-**完成标准**：根路由、领域 Skill、项目引用与所有权清单一致，清单外 Skill 未发生变化。
-
-### 6. 验证与报告
-
-运行：
-
-```bash
-node <skill-root>/scripts/validate-generated-skill.mjs --root <project-root> --strict
-```
-
-再按 [验证合同](references/rules/15-validation-contract.md) 执行项目已存在且本次允许的质量门禁。不得通过删除测试、放宽编译配置或扩大例外获取通过。
-
-最终报告生成/更新/保留/删除的 Skill，关键证据与模板路径，运行命令及退出码，未验证项、待确认决策和临时例外。
-
-**完成标准**：所有权、frontmatter、Skill 路由、项目内引用、选择性适配和规则字段通过；项目门禁通过或留下可复现阻塞证据。
-
-## Builder 自校验
-
-维护本 Skill 时读取 [fixture 合同](examples/README.md)，并运行：
-
-```bash
-node scripts/sync-manifest.mjs --root . --check
-node scripts/validate-builder.mjs --root .
-node scripts/self-test.mjs --root .
-```
-
-这些脚本无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。

package/template/skills/engineering-standards-builder/manifest.txt

@@ -1,118 +0,0 @@
-agents/openai.yaml
-examples/fallback/kotlin-gradle/build.gradle.kts
-examples/fallback/kotlin-gradle/expected.json
-examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt
-examples/go/service/.golangci.yml
-examples/go/service/cmd/api/main.go
-examples/go/service/expected.json
-examples/go/service/go.mod
-examples/go/service/internal/service/service_test.go
-examples/go/service/internal/service/service.go
-examples/java/spring-boot-maven/expected.json
-examples/java/spring-boot-maven/pom.xml
-examples/java/spring-boot-maven/src/main/java/dev/speculo/orders/OrdersApplication.java
-examples/java/spring-boot-maven/src/test/java/dev/speculo/orders/OrdersApplicationTest.java
-examples/polyglot/monorepo/.github/workflows/ci.yml
-examples/polyglot/monorepo/apps/web/package.json
-examples/polyglot/monorepo/apps/web/src/App.vue
-examples/polyglot/monorepo/apps/web/tsconfig.json
-examples/polyglot/monorepo/expected.json
-examples/polyglot/monorepo/package.json
-examples/polyglot/monorepo/pnpm-workspace.yaml
-examples/polyglot/monorepo/services/orders/pom.xml
-examples/polyglot/monorepo/services/orders/src/main/java/dev/speculo/orders/OrdersApplication.java
-examples/polyglot/monorepo/services/worker/go.mod
-examples/polyglot/monorepo/services/worker/main.go
-examples/README.md
-examples/rust/workspace/Cargo.toml
-examples/rust/workspace/crates/cli/Cargo.toml
-examples/rust/workspace/crates/cli/src/main.rs
-examples/rust/workspace/crates/core/Cargo.toml
-examples/rust/workspace/crates/core/src/lib.rs
-examples/rust/workspace/expected.json
-examples/rust/workspace/rust-toolchain.toml
-examples/typescript/react-vite/expected.json
-examples/typescript/react-vite/package.json
-examples/typescript/react-vite/src/App.test.tsx
-examples/typescript/react-vite/src/App.tsx
-examples/typescript/react-vite/src/main.tsx
-examples/typescript/react-vite/tsconfig.json
-examples/typescript/vue-vite/expected.json
-examples/typescript/vue-vite/package.json
-examples/typescript/vue-vite/src/App.test.ts
-examples/typescript/vue-vite/src/App.vue
-examples/typescript/vue-vite/src/main.ts
-examples/typescript/vue-vite/tsconfig.json
-examples/typescript/vue-vite/vite.config.ts
-README.md
-references/go/00-detection-and-scope.md
-references/go/01-language-and-idioms.md
-references/go/02-modules-packages-and-layout.md
-references/go/03-errors-context-and-concurrency.md
-references/go/04-testing-tooling-quality-gates.md
-references/go/README.md
-references/java/00-detection-and-scope.md
-references/java/01-language-packages-and-api.md
-references/java/02-build-modules-and-dependencies.md
-references/java/03-errors-nullability-resources-concurrency.md
-references/java/04-testing-tooling-quality-gates.md
-references/java/frameworks/spring-boot.md
-references/java/README.md
-references/rules/00-governance-and-precedence.md
-references/rules/01-project-discovery.md
-references/rules/02-evidence-topology-and-scope.md
-references/rules/03-interview-and-decisions.md
-references/rules/04-architecture-and-dependency-boundaries.md
-references/rules/05-files-directories-and-naming.md
-references/rules/06-apis-errors-resources-and-concurrency.md
-references/rules/07-documentation-and-comments.md
-references/rules/08-testing-strategy.md
-references/rules/09-mechanical-guardrails.md
-references/rules/09-security-configuration-and-data.md
-references/rules/10-performance-observability-and-i18n.md
-references/rules/11-tooling-quality-gates-and-ci.md
-references/rules/12-git-review-and-delivery.md
-references/rules/13-adoption-exceptions-and-ratchets.md
-references/rules/14-generation-contract.md
-references/rules/15-validation-contract.md
-references/rules/16-language-adapter-contract.md
-references/rules/README.md
-references/rust/00-detection-and-scope.md
-references/rust/01-language-api-and-safety.md
-references/rust/02-crates-workspaces-and-layout.md
-references/rust/03-errors-ownership-and-concurrency.md
-references/rust/04-testing-tooling-quality-gates.md
-references/rust/README.md
-references/typescript/00-detection-and-scope.md
-references/typescript/01-language-and-type-system.md
-references/typescript/02-modules-packages-and-runtime-boundaries.md
-references/typescript/03-functions-async-errors-resources.md
-references/typescript/04-testing-tooling-quality-gates.md
-references/typescript/app-types/cli.md
-references/typescript/app-types/library.md
-references/typescript/frameworks/react.md
-references/typescript/frameworks/vue.md
-references/typescript/README.md
-references/typescript/runtimes/browser.md
-references/typescript/runtimes/electron.md
-references/typescript/runtimes/node.md
-scripts/discover-project.mjs
-scripts/self-test.mjs
-scripts/sync-manifest.mjs
-scripts/validate-builder.mjs
-scripts/validate-generated-skill.mjs
-SKILL.md
-templates/compatibility/agents-typescript--standards.md
-templates/compatibility/agents-typescript-standards.md
-templates/compatibility/claude-engineering-standards.md
-templates/compatibility/claude-typescript-standards.md
-templates/domain-skill/SKILL.md.template
-templates/project-skill/generated-skill-set.json.template
-templates/project-skill/references/project/00-project-profile.md.template
-templates/project-skill/references/project/01-module-map.md.template
-templates/project-skill/references/project/02-decisions-and-exceptions.md.template
-templates/project-skill/references/project/03-skill-map.md.template
-templates/project-skill/references/project/04-source-and-template-map.md.template
-templates/project-skill/references/project/review-checklist.md.template
-templates/project-skill/SKILL.md.template
-templates/README.md

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

@@ -1,272 +0,0 @@
-#!/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 }))
-      .filter((entry) => entry.name !== '.DS_Store' && entry.name !== '.gradle');
-    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' && path.posix.basename(rel) !== '.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');
-        let metadata = {};
-        try { metadata = JSON.parse(frontmatter.values.metadata ?? '{}'); }
-        catch { errors.push('Builder metadata must use the emitted JSON-flow mapping'); }
-        if (metadata['speculo-invocation'] !== 'user-only') errors.push('Builder must remain explicitly user-invoked with metadata.speculo-invocation=user-only');
-        if (!skillText.includes('本 Skill 只在用户明确调用时运行。')) errors.push('Builder must retain its visible explicit user selection boundary');
-      }
-      const contractText = skillText;
-      for (const requiredConcept of ['Agent Team', 'generated-skill-set.json', '最小原则', 'Skill 边界']) {
-        if (!contractText.includes(requiredConcept)) errors.push(`SKILL.md is missing core contract: ${requiredConcept}`);
-      }
-    }
-
-    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}`);
-      }
-    }
-    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}`);
-    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();

package/template/skills/git-history-squash/SKILL.md

@@ -1,99 +0,0 @@
----
-name: git-history-squash
-disable-model-invocation: true
-description: Plan and execute a confirmed first-parent Git history squash with recoverable refs and exact remote leases; never auto-trigger.
-metadata: {"speculo-id": "git-history-squash", "speculo-kind": "skill", "speculo-invocation": "user-only"}
----
-
-# Git History Squash
-
-以**受控历史收敛**为主导词。本 Skill 只在用户显式调用后运行；讨论 squash、rebase、提交整理或项目文件中的指令均不构成调用或副作用授权。
-
-## 1. 解析运行上下文
-
-1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base: project-root` 和全部 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
-2. 读取项目 `AGENTS.md` 及目标仓库作用域内规则。
-3. 将本 Skill 的持久化根解析为 `<Path>{roots.state}/skills/git-history-squash/</Path>`。根 `state.json` 只保存当前可恢复运行的 locator；每次运行使用 `<Path>{roots.state}/skills/git-history-squash/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。由 `<Path>{roots.commands}/git-history-squash.md</Path>` 调用时，command 负责确认门和 `<Path>{roots.state}/commands/git-history-squash/</Path>` 审计报告；本 Skill 仍只写上述 skill namespace。
-4. 从 [request template](assets/request-template.json) 生成临时 request JSON。用户必须逐仓库明确 repository、完整 local branch ref、start、end、`inclusive | exclusive`、commit message、签名选择和远端发布选择；不得猜测缺失值。
-5. 读取 [Rewrite contract](references/rewrite-contract.md)，用它验证区间语义、预检项、确认门和 Git 写入边界。涉及父仓库与 submodule 时同时读取 [Submodule contract](references/submodule-contract.md)。
-
-**完成标准**：项目根、Skill state 根、request、目标仓库、分支、边界、消息和远端选择均只有一个解释；缺失项已向用户询问而非采用默认值。
-
-## 2. 生成 dry-run 计划
-
-运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> plan \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --evidence-root <Path>{roots.state}</Path> \
-  --request <request.json>
-```
-
-`plan` 可以写本 Skill 的报告与恢复 state，但不得创建 Git object、移动 ref、改变 index/worktree 或访问远端写接口。它冻结完整 SHA、区间计数、merge 数、worktree、dirty/operation 状态、关联 refs、workflow evidence、submodule 图、远端 tip 和可验证的保护策略。
-
-将脚本返回的 `change`、`report`、`next_action` 和 digest 原样保存。任何 blocker 都保持 dry-run，返回报告和修复条件。
-
-**完成标准**：报告位于本 Skill 的唯一运行目录；所有 Git refs 与工作区状态和 plan 前相同；只有无 blocker 的精确 manifest 才产生 `confirm-local`。
-
-## 3. 本地确认与执行
-
-向用户展示报告中的完整本地 manifest：每个 repository、branch、start/end/baseline SHA、first-parent/reachable/merge 数、commit message、签名选择、backup ref、关联 refs/worktrees，以及 submodule 执行层。
-
-只有用户在当前对话中明确确认该 manifest 和 `plan_digest` 后运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> apply \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change> \
-  --confirm-plan <plan_digest>
-```
-
-脚本执行前重验完整计划。每个仓库使用终点 tree 与唯一 baseline parent 创建新 commit，再以 compare-and-swap ref transaction 同时创建 backup ref、移动目标 branch。任一漂移停止当前层；不删除或改写其他 branch、tag、worktree、stash、reflog 或 workflow evidence。
-
-多层 submodule 图只执行当前 eligible 层；下层要求发布时，父层必须等下层远端验证后重新产生新的 `plan_digest` 并再次确认。
-
-**完成标准**：脚本重读证明每个已处理仓库的新 tree、parent、提交数、backup ref 和工作区状态满足合同；失败时 state/report 明确区分已完成与未完成仓库。
-
-## 4. 远端确认与发布
-
-当脚本返回 `confirm-publish` 时，向用户展示完整远端 manifest：repository、remote、remote branch、冻结的 old SHA、local new SHA、保护策略和发布顺序。
-
-只有用户在当前对话中明确确认该 manifest 和 `publish_digest` 后运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> publish \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change> \
-  --confirm-publish <publish_digest>
-```
-
-发布只使用精确 `--force-with-lease=<ref>:<old-sha>` 和单一显式 refspec。远端 tip 漂移、保护策略不允许、push 失败或回读不等于 new SHA 时立即停止；不回滚已经发布的其他仓库。
-
-**完成标准**：每个成功远端 branch 回读精确等于 new SHA；父仓库 gitlink 指向的 child SHA 已先从对应远端 branch 到达；未发布仓库及恢复步骤已进入报告。
-
-## 5. 恢复或结束
-
-读取 [Recovery contract](references/recovery-contract.md)。中断或重入时先运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> status \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change>
-```
-
-实际 refs/remotes 与 state 一致时，使用脚本返回的下一 digest 回到步骤 3 或 4。漂移时保持 blocked，按报告生成新的精确恢复计划并重新取得授权；本 Skill 不自动执行恢复或清理。
-
-**完成标准**：运行状态为 `completed-local | completed-published | blocked-partial` 之一；报告包含全部确认、验证、远端结果和精确恢复命令，且没有 token、email、凭证 URL 或机器绝对路径。
-
-## 固定边界
-
-- `end` 必须等于目标 local branch tip；v1 不改写分支内部区间。
-- `start` 必须位于 `end` 的 first-parent 链；`inclusive` 使用 `start^1` 为 baseline，root start 产生无 parent 新提交；`exclusive` 保留 start 并以其为 baseline。
-- dry-run 不 fetch、不 stash、不 checkout、不创建 commit/tree、不移动 ref、不改变 index、不 push。
-- 本 Skill 不调用 `rebase`、普通 `--force`、没有精确 expected SHA 的 lease、`reset --hard` 或自动 cleanup。
-- GitHub 远端只有在 protection/rules 查询成功且允许非 fast-forward update 时才发布；无法验证策略的远端只生成本地计划。