@heihei0299/matt-skills 2.0.2 → 2.1.2

package/bin/cli.js

@@ -4,11 +4,17 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import prompts from 'prompts';
+import {
+  PROPRIETARY_SKILLS,
+  isDefaultProgrammingSkill,
+  isDistributableProprietarySkill,
+  isDistributableSkill,
+  isRepoLocalSkill,
+  REPO_LOCAL_SKILLS,
+} from './skill-boundaries.js';
 
 const SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.agents', 'skills');
 const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
-const PROPRIETARY_SKILLS = new Set(['ci-guard', 'tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check', 'scaffold-functional-test', 'show-me']);
-const PROPRIETARY_DEFAULT = new Set(['tdd-implement', 'diagnose-fix', 'commit-check', 'grill-to-spec', 'show-me']); // 默认仅装核心 4 + show-me，--all 才装全部 7
 const ENGINEERING_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'engineering.json');
 const REQUIRED_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'required.json');
 let ENGINEERING_SKILLS = null;
@@ -34,10 +40,10 @@ async function loadRequiredSkills() {
   return REQUIRED_SKILLS;
 }
 function isProgrammingSkill(name, engineering, required) {
-  return PROPRIETARY_DEFAULT.has(name) || engineering.has(name) || (required && required.has(name));
+  return isDefaultProgrammingSkill(name, engineering, required);
 }
 function isProgrammingAll(name, engineering) {
-  return PROPRIETARY_SKILLS.has(name) || engineering.has(name);
+  return isDistributableProprietarySkill(name) || engineering.has(name);
 }
 process.stdout.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
@@ -64,9 +70,9 @@ Usage:
 
 Init options:
   --dest <path>   Target directory (default: current directory)
-  --all           Include non-programming skills (productivity) and optional proprietary; default only core programming (engineering 18 + required 4 + default proprietary 4 → 26)
+  --all           Include all distributable skills; default only default programming skills
   --help, -h      Show this help
-提示：已有 AGENTS.md 时普通 init 跳过；显式 init --all 刷新模板并覆盖全量 skills。
+提示：已有 AGENTS.md 时普通 init 跳过；显式 init --all 刷新模板并覆盖全量可分发 skills。
 
 提示：matt-skills --help 查看全量
 `;
@@ -82,7 +88,7 @@ Sync options:
   --dest <path>   Target directory (default: current directory)
   --help, -h      Show this help
 
-说明：默认不带 --all 仅增量同步默认技能（26）且 AGENTS.md 有定制则跳过；--all 时对同名技能 upsert 并强制更新 AGENTS.md。
+说明：默认不带 --all 仅增量同步默认 programming skill 且 AGENTS.md 有定制则跳过；--all 时同步全部可分发 skill 并强制更新 AGENTS.md。
 
 提示：matt-skills --help 查看全量
 `;
@@ -93,7 +99,7 @@ Usage:
   matt-skills list [--all] [--json]
 
 List options:
-  --all           List all skills (default only core programming 26)
+  --all           List all distributable skills (default only default programming skills)
   --json          Output as JSON
   --help, -h      Show this help
 
@@ -106,7 +112,7 @@ Usage:
   matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
 
 Check options:
-  --all           Include non-programming and optional proprietary; default only core programming (26: engineering 18 + required 4 + default proprietary 4)
+  --all           Include the full upstream comparison scope; default engineering + required upstream skills (proprietary excluded)
   --json          Output as JSON
   --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
   --ref <ref>     Upstream ref (default: HEAD)
@@ -122,7 +128,7 @@ Usage:
 
 Install options:
   --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection — 共享技能统一指向 .agents/skills，.pi/skills/.opencode/skills 仅用于项目自定义
-  --all           Install all skills (default only core programming 26); skips skill selection
+  --all           Install all distributable skills (default only default programming); skips skill selection
   --force         Overwrite existing skills
   --global        Install to the user's global skill directories
   --project       Install to project skill directories (default)
@@ -161,6 +167,7 @@ async function listSkills({ onlyProgramming = false } = {}) {
     if (!entry.isDirectory()) continue;
     if (entry.name.endsWith('.bak')) continue;
     if (entry.name === 'skill-creator') continue;
+    if (isRepoLocalSkill(entry.name)) continue;
     if (onlyProgramming && !isProgrammingSkill(entry.name, engineering, required)) continue;
     let content;
     try {
@@ -182,6 +189,13 @@ async function pathExists(p) {
     return false;
   }
 }
+
+function shouldCopyTemplatePath(src) {
+  const relative = path.relative(TEMPLATE_DIR, src);
+  const parts = relative.split(path.sep);
+  return !(parts[0] === '.agents' && parts[1] === 'skills' && isRepoLocalSkill(parts[2]));
+}
+
 const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
 
 // 统一源：共享技能全部在 .agents/skills，harness 的 .pi/skills/.opencode/skills 仅用于项目自定义
@@ -262,6 +276,12 @@ async function installCommand({ dest, all, force, tools, global }) {
     process.stdout.write('未选择任何技能，未安装任何技能\n');
     return;
   }
+  const knownDistributable = new Set(skills.map((skill) => skill.name));
+  for (const name of selected) {
+    if (!isDistributableSkill(name, knownDistributable)) {
+      throw new Error(`${name} is repository-local or unavailable and cannot be distributed`);
+    }
+  }
   for (const { tool, dir } of targets) {
     let installed = 0;
     let skipped = 0;
@@ -287,7 +307,11 @@ async function initCommand({ dest, all }) {
   if (await pathExists(marker) && !all) {
     process.stdout.write('模板已存在（AGENTS.md），跳过\n');
   } else {
-    await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+    await cp(TEMPLATE_DIR, target, {
+      recursive: true,
+      force: true,
+      filter: shouldCopyTemplatePath,
+    });
     process.stdout.write('模板：已复制（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
     // 默认范围（engineering + 独有所需 + 默认独有），--all 才保留其余 productivity
     if (onlyProgramming && path.resolve(target) !== path.resolve(path.join(path.dirname(fileURLToPath(import.meta.url)), '..'))) {
@@ -311,7 +335,7 @@ async function initCommand({ dest, all }) {
   let installed = 0;
   try {
     const entries = await readdir(skillsDir, { withFileTypes: true });
-    installed = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== '.git' && e.name !== 'skill-creator').length;
+    installed = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== '.git' && e.name !== 'skill-creator' && !isRepoLocalSkill(e.name)).length;
   } catch {}
   const allSkillsFull = await listSkills({ onlyProgramming: false });
   const engineeringForStats = await loadEngineeringSkills();
@@ -322,12 +346,12 @@ async function initCommand({ dest, all }) {
   const displayTotal = onlyProgramming ? programmingCount : allSkillsFull.length;
   const displayUpstream = onlyProgramming ? upstreamProg : upstreamFull;
   if (path.resolve(skillsDir) === path.resolve(SKILLS_DIR)) {
-    process.stdout.write(`技能：已装 ${installed}、跳过 0（全量 ${allSkillsFull.length}，含上游 ${upstreamFull}；编程 ${programmingCount}，含上游 ${upstreamProg}）\n`);
+    process.stdout.write(`技能：已装 ${installed}、跳过 0（可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}；默认编程 ${programmingCount}，含上游 ${upstreamProg}）\n`);
   } else {
     if (onlyProgramming) {
-      process.stdout.write(`技能：已装 ${installed}（编程 ${displayTotal}，含上游 ${displayUpstream}；全量 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
+      process.stdout.write(`技能：已装 ${installed}（默认编程 ${displayTotal}，含上游 ${displayUpstream}；可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
     } else {
-      process.stdout.write(`技能：已装 ${installed}（全量 ${displayTotal}，含上游 ${displayUpstream}）\n`);
+      process.stdout.write(`技能：已装 ${installed}（可分发 ${displayTotal}，含上游 ${displayUpstream}）\n`);
     }
   }
   process.stdout.write(`目标路径：${target}\n`);
@@ -340,7 +364,7 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
     if (json) {
       process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
     } else {
-      const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量）';
+      const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量上游）';
       const lines = [];
       lines.push(`上游 HEAD: ${cmp.head}`);
       lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
@@ -368,7 +392,11 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   // 模板同步：默认模式下过滤 skills，仅同步默认子集
   async function copyTemplateFiltered() {
     if (!onlyProgramming) {
-      await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      await cp(TEMPLATE_DIR, target, {
+        recursive: true,
+        force: true,
+        filter: shouldCopyTemplatePath,
+      });
       return;
     }
     // 默认范围：分别复制非 skills 部分，skills 由后续 allSkills 循环处理
@@ -391,7 +419,11 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   if (!(await pathExists(marker))) {
     process.stdout.write('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
     if (onlyProgramming) await copyTemplateFiltered();
-    else await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+    else await cp(TEMPLATE_DIR, target, {
+      recursive: true,
+      force: true,
+      filter: shouldCopyTemplatePath,
+    });
     process.stdout.write('模板：已复制（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
   } else {
     process.stdout.write('同步：检测到现有项目，将增量更新\n');
@@ -416,21 +448,30 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
           }
         } catch {}
       } else {
-        await cp(path.join(TEMPLATE_DIR, '.agents'), path.join(target, '.agents'), { recursive: true, force: true });
+        await cp(path.join(TEMPLATE_DIR, '.agents'), path.join(target, '.agents'), {
+          recursive: true,
+          force: true,
+          filter: shouldCopyTemplatePath,
+        });
         await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
         await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
       }
       process.stdout.write('模板：已同步（AGENTS.md 跳过，已含定制）\n');
     } else {
       if (onlyProgramming) await copyTemplateFiltered();
-      else await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      else await cp(TEMPLATE_DIR, target, {
+        recursive: true,
+        force: true,
+        filter: shouldCopyTemplatePath,
+      });
       process.stdout.write('模板：已同步（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
     }
   }
-  // 技能同步：--all 仅更新同名技能内容，存在则覆盖，不存在则新增，并更新 AGENTS.md（由上一步已处理）；默认范围 26，--all 时按全量同名集合处理，不删多余
+  // 技能同步：--all 仅更新同名可分发技能内容，存在则覆盖，不存在则新增，并更新 AGENTS.md（由上一步已处理）；默认范围为默认 programming，不删多余
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const allNames = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== 'skill-creator' && e.name !== '.git').map((e) => e.name);
   let allSkills = allNames.sort();
+  allSkills = allSkills.filter((name) => !isRepoLocalSkill(name));
   if (onlyProgramming) {
     const engineering = await loadEngineeringSkills();
     const required = await loadRequiredSkills();
@@ -438,6 +479,23 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   }
   const skillsDir = path.join(target, '.agents', 'skills');
   await mkdir(skillsDir, { recursive: true });
+  const preservedRepoLocal = [];
+  const preserveLocations = [
+    {
+      dir: skillsDir,
+      label: '.agents/skills',
+      isWorkspaceSource: path.resolve(skillsDir) === path.resolve(SKILLS_DIR),
+    },
+    { dir: path.join(target, '.pi', 'skills'), label: '.pi/skills', isWorkspaceSource: false },
+    { dir: path.join(target, '.opencode', 'skills'), label: '.opencode/skills', isWorkspaceSource: false },
+  ];
+  for (const name of REPO_LOCAL_SKILLS) {
+    for (const location of preserveLocations) {
+      if (!location.isWorkspaceSource && await pathExists(path.join(location.dir, name))) {
+        preservedRepoLocal.push(`${location.label}/${name}`);
+      }
+    }
+  }
   let installed = 0;
   let updated = 0;
   for (const name of allSkills) {
@@ -468,7 +526,7 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       if (!e.isDirectory()) continue;
       if (e.name === '.git' || e.name.endsWith('.bak')) continue;
       if (e.name === '.gitkeep' || e.name === 'README.md') continue;
-      if (allSkills.includes(e.name) || PROPRIETARY_SKILLS.has(e.name)) {
+      if (allSkills.includes(e.name)) {
         await rm(path.join(dir, e.name), { recursive: true, force: true });
       }
     }
@@ -484,7 +542,10 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       }
     }
   } catch {}
-  const modeLabel = onlyProgramming ? '编程' : '全量';
+  if (preservedRepoLocal.length) {
+    process.stdout.write(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
+  }
+  const modeLabel = onlyProgramming ? '默认编程' : '全部可分发';
   process.stdout.write(`技能：新增 ${installed}、更新 ${updated}（${modeLabel} ${allSkills.length}）\n`);
   process.stdout.write(`目标路径：${target}\n`);
 }
@@ -584,7 +645,7 @@ async function checkCommand(args) {
   } else {
     const lines = [];
     lines.push(`上游 HEAD: ${cmp.head}`);
-    const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量）';
+    const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量上游）';
     lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
     lines.push('');
     const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;

package/bin/skill-boundaries.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG_PATH = path.join(ROOT, 'config', 'proprietary.json');
+const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+
+function toUniqueSet(value, key) {
+  if (!Array.isArray(value) || new Set(value).size !== value.length) {
+    throw new Error(`invalid proprietary classification: ${key} must be a unique array`);
+  }
+  return new Set(value);
+}
+
+export const PROPRIETARY_SKILLS = toUniqueSet(config.all, 'all');
+export const DISTRIBUTABLE_PROPRIETARY_SKILLS = toUniqueSet(config.distributable, 'distributable');
+export const REPO_LOCAL_SKILLS = toUniqueSet(config.repoLocal, 'repoLocal');
+export const DEFAULT_PROPRIETARY_SKILLS = toUniqueSet(config.default, 'default');
+
+const classified = new Set([...DISTRIBUTABLE_PROPRIETARY_SKILLS, ...REPO_LOCAL_SKILLS]);
+const missing = [...PROPRIETARY_SKILLS].filter((name) => !classified.has(name));
+const extra = [...classified].filter((name) => !PROPRIETARY_SKILLS.has(name));
+const overlap = [...DISTRIBUTABLE_PROPRIETARY_SKILLS].filter((name) => REPO_LOCAL_SKILLS.has(name));
+const invalidDefaults = [...DEFAULT_PROPRIETARY_SKILLS].filter((name) => !DISTRIBUTABLE_PROPRIETARY_SKILLS.has(name));
+if (missing.length || extra.length || overlap.length || invalidDefaults.length) {
+  throw new Error(
+    `invalid proprietary classification: missing=${missing.join(',')} extra=${extra.join(',')} ` +
+    `overlap=${overlap.join(',')} defaults=${invalidDefaults.join(',')}`,
+  );
+}
+
+export function isProprietarySkill(name) {
+  return PROPRIETARY_SKILLS.has(name);
+}
+
+export function isDistributableProprietarySkill(name) {
+  return DISTRIBUTABLE_PROPRIETARY_SKILLS.has(name);
+}
+
+export function isRepoLocalSkill(name) {
+  return REPO_LOCAL_SKILLS.has(name);
+}
+
+export function isDefaultProprietarySkill(name) {
+  return DEFAULT_PROPRIETARY_SKILLS.has(name);
+}
+
+export function isDefaultProgrammingSkill(name, engineering, required) {
+  return (
+    DEFAULT_PROPRIETARY_SKILLS.has(name) ||
+    engineering.has(name) ||
+    (required && required.has(name))
+  );
+}
+
+export function isDistributableSkill(name, knownNames) {
+  if (!knownNames) return isDistributableProprietarySkill(name);
+  const known = knownNames instanceof Set ? knownNames : new Set(knownNames);
+  return known.has(name) && !REPO_LOCAL_SKILLS.has(name);
+}

package/config/proprietary.json

@@ -1,9 +1,28 @@
-[
-  "ci-guard",
-  "tdd-implement",
-  "grill-to-spec",
-  "diagnose-fix",
-  "commit-check",
-  "scaffold-functional-test",
-  "show-me"
-]
+{
+  "all": [
+    "ci-guard",
+    "tdd-implement",
+    "grill-to-spec",
+    "diagnose-fix",
+    "commit-check",
+    "scaffold-functional-test",
+    "show-me"
+  ],
+  "distributable": [
+    "tdd-implement",
+    "diagnose-fix",
+    "grill-to-spec",
+    "scaffold-functional-test",
+    "show-me"
+  ],
+  "repoLocal": [
+    "ci-guard",
+    "commit-check"
+  ],
+  "default": [
+    "tdd-implement",
+    "diagnose-fix",
+    "grill-to-spec",
+    "show-me"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "2.0.2",
+  "version": "2.1.2",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/scripts/sync-upstream.js

@@ -5,10 +5,10 @@ import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { PROPRIETARY_SKILLS } from '../bin/skill-boundaries.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const LOCAL_SKILLS_DIR = path.join(ROOT, '.agents', 'skills');
-const PROPRIETARY_PATH = path.join(ROOT, 'config', 'proprietary.json');
 const ENGINEERING_PATH = path.join(ROOT, 'config', 'engineering.json');
 const REQUIRED_PATH = path.join(ROOT, 'config', 'required.json');
 const UPSTREAM_URL = 'https://github.com/mattpocock/skills.git';
@@ -19,12 +19,7 @@ const RENAMES = {
 };
 
 async function loadProprietary() {
-  try {
-    const raw = await readFile(PROPRIETARY_PATH, 'utf8');
-    return new Set(JSON.parse(raw));
-  } catch {
-    return new Set(['ci-guard', 'tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check', 'scaffold-functional-test', 'show-me']);
-  }
+  return new Set(PROPRIETARY_SKILLS);
 }
 
 async function loadEngineering() {
@@ -210,7 +205,8 @@ export async function applySync({ upstreamUrl, tmpDir, ref, dryRun = false, forc
   const actions = [];
 
   if (dryRun) {
-    return { ...cmp, actions, dryRun: true };
+    await rm(dest, { recursive: true, force: true });
+    return { ...cmp, dest: null, actions, dryRun: true };
   }
 
   // 处理重命名

package/template/.agents/skills/diagnose-fix/SKILL.md

@@ -1,42 +1,43 @@
 ---
 name: diagnose-fix
-description: "Complete diagnosis→fix→regression channel for bugs: diagnose, then fix via a TDD red-green loop with a hard gate (no fix code before a failing regression test). Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
+description: "Complete diagnosis→fix→regression channel for bugs and performance regressions: diagnose, then fix behind observed red regression evidence. Functional bugs require a failing regression test; performance regressions may use a benchmark/perf harness with an explicit failing threshold. Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
 ---
 
 # Diagnose Fix
 
-本 skill 只连接诊断、TDD 修复和回归三个阶段。诊断细节以 [`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md) 为事实源，红绿语义以 [`tdd`](.agents/skills/tdd/SKILL.md) 为事实源；不复制两个上游的完整步骤。
+本 skill 只连接诊断、受保护的最小修复和回归三个阶段。诊断细节以 [`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md) 为事实源，普通功能 bug 的红绿语义以 [`tdd`](.agents/skills/tdd/SKILL.md) 为事实源；不复制两个上游的完整步骤。
 
 ## 流程
 
 ### ① 诊断
 
-委托 `diagnosing-bugs` 完成 Phase 1–4：建立能捕捉用户症状的 tight feedback loop，实际复现并最小化，再形成可证伪的假设并按单变量探针验证。
+委托 `diagnosing-bugs` 完成修复前的诊断活动：建立能捕捉用户症状的 tight feedback loop，实际复现并最小化，再形成可证伪的假设并按单变量探针验证。不要依赖固定 Phase 编号；以上游当前“进入修复前必须完成的诊断出口”为事实源。
 
-出口：反馈回路已实际变红，且最小复现已确认；此阶段不写修复代码。
+出口：反馈回路已实际变红，最小复现已确认，且导致症状的假设已有证据；此阶段不写修复代码。
 
-### ② TDD 修复
+### ② 受保护的最小修复
 
-1. 在正确的公共 seam 上提出回归测试边界，并遵循 `tdd` 要求获得用户确认；只确认本次 seam，不建立重型 seam ledger。
-2. 加载 `tdd`，先把最小复现转成失败回归测试并实际看到 Red。
-3. 只写让该测试 Green 的最小修复，并遵循 `tdd` 的红绿循环。
+先判断 Red 证据类型：
 
-**硬门槛：**不存在已实际观察到的失败回归测试时，不得写任何修复代码。不存在正确 seam 时，本身就是 finding；记录架构阻塞，不绕过测试直接修改。
+- **功能 bug**：在正确的公共 seam 上提出回归测试边界，遵循 `tdd` 要求获得用户确认；把最小复现转成失败回归测试并实际看到 Red，再写最小修复直到 Green。
+- **性能回归**：复用 `diagnosing-bugs` 的 performance branch，建立可重复的 benchmark、timing harness、query-count 或 profiler-derived threshold；必须先实际观察到该阈值失败，再做最小修复，并用同一测量方式确认转绿。不为满足形式强造一个无法代表真实性能症状的普通单元测试。
 
-出口：回归测试先 Red，最小修复后 Green；不进入 `tdd-implement` 的长流程。
+**硬门槛：**不存在已实际观察到的 **red-capable regression evidence** 时，不得写修复代码。功能 bug 的证据必须是正确 seam 上的失败回归测试；性能回归可使用带明确阈值且可重复的 benchmark/perf harness。不存在正确 seam 或可靠性能测量边界时，本身就是 finding；记录阻塞，不绕过证据直接修改。
+
+出口：功能 bug 为 regression test Red → 最小修复 → Green；性能回归为 benchmark/perf threshold Red → 最小修复 → Green。两者都不进入 `tdd-implement` 的长流程。
 
 ### ③ 回归收尾
 
-按 `diagnosing-bugs` 的收尾要求重跑阶段 ① 的原始、未最小化反馈回路，确认用户症状消失；清理 `[DEBUG-...]` 探针和一次性 harness，并记录最终验证的假设。
+按 `diagnosing-bugs` 的收尾要求重跑阶段 ① 的原始、未最小化反馈回路，确认用户症状消失；功能 bug 重跑回归测试，性能回归重跑原始基准/测量；清理 `[DEBUG-...]` 探针和一次性 harness，并记录最终验证的假设。
 
-出口：原始症状消失、回归测试 Green、临时诊断产物已清理。
+出口：原始症状消失、对应 regression evidence 为 Green、临时诊断产物已清理。
 
 ## 回合连续性
 
-诊断 → seam 确认 → Red → 修复 → Green → 原始回路 → 清理在一个回合内连续推进。只在用户必须确认 seam、发现无 seam finding、外部环境阻塞或整个阶段出口时暂停；预告下一步后立即执行。
+诊断 → Red 证据 → 修复 → Green → 原始回路 → 清理在一个回合内连续推进。只有功能 bug 的 seam 确认、发现无正确 seam/测量边界、外部环境阻塞或整个阶段出口可以暂停；预告下一步后立即执行。
 
 ## 引用
 
-- 诊断：[`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md)
-- 修复：[`tdd`](.agents/skills/tdd/SKILL.md)
+- 诊断与性能分支：[`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md)
+- 功能 bug 修复：[`tdd`](.agents/skills/tdd/SKILL.md)
 - 负向边界：[`references/anti-patterns.md`](references/anti-patterns.md)

package/template/.agents/skills/diagnose-fix/references/anti-patterns.md

@@ -5,14 +5,15 @@ SKILL.md 正文各阶段规则是正面约束；本文件是负向边界（不
 ## 诊断阶段
 
 - 不跳过反馈回路直接猜根因：回路未红之前不进入假设、不写修复代码
-- 不把最小复现留在 harness 里：必须转写为正确 seam 上的回归测试，harness 只作诊断工具
+- 功能 bug 不把最小复现永久留在 harness 里：必须转写为正确 seam 上的回归测试；性能回归可保留最小、可重复且有明确阈值的 benchmark/perf harness 作为回归证据
 - 不一次改多个变量：探针一次只改一个，`[DEBUG-...]` 前缀标记
 
 ## 修复阶段
 
-- 不绕过测试直接改代码（见 SKILL.md ②无逃生舱）——没有 seam 是 finding，不是豁免
-- 不套用 tdd-implement 重流程：见 SKILL.md ②轻量声明——单 seam 修复直走红-绿，不引入重流程编排
-- 不重写 tdd 技能的红-绿语义：seam 定义、好测试标准、mocking 边界一律查上游技能
+- 不绕过 red-capable regression evidence 直接改代码——功能 bug 没有正确 seam 是 finding；性能回归没有可靠测量边界同样是 finding，不是豁免
+- 不为性能问题强造一个不能代表真实慢路径的普通单元测试；优先复用 diagnosis 中已经验证过的 benchmark、timing、query-count 或 profiler-derived threshold
+- 不套用 tdd-implement 重流程：单个 bug/perf regression 的修复保持轻量，不引入完整 delivery orchestration
+- 不重写 tdd 技能的红-绿语义：功能 bug 的 seam 定义、好测试标准、mocking 边界一律查上游技能
 
 ## 回归阶段
 

package/template/.agents/skills/grill-to-spec/SKILL.md

@@ -30,6 +30,10 @@ disable-model-invocation: true
 
 出口：spec 已发布，路径、状态和未纳入范围已报告。
 
+## 回合连续性
+
+本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的 ADR/spec 草稿、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。确认完成后在同一任务链继续推进到下一可验证出口，不要求用户额外回复“继续”。
+
 ## 本 skill 独有门禁
 
 - ADR：草稿 → 用户确认 → 落盘，任何情况不例外；

package/template/.agents/skills/grill-to-spec/references/rules.md

@@ -1,33 +1,28 @@
-# 守则：Grill-to-Spec 产出物格式细则
+# 守则：Grill-to-Spec 本地增量规则
 
-三类产出物（Glossary / ADR / Spec）格式的**唯一细节出处**，由 SKILL.md 直链引用。SKILL.md 只保留流程、导航与不可协商规则，本文件不重复流程内容。
+本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
 
-## Glossary 守则
+## Glossary 增量规则
 
-- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问
-- 只是 glossary：零实现细节，不当 spec/scratch pad
-- 只收本上下文特有术语，通用编程概念不收
-- 定义 WHAT 非 HOW，1-2 句；opinionated，同义词列 `_Avoid_`；术语解析即 inline 更新，不批量
+- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
+- 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
+- glossary 可按上游流程 inline 更新，不额外增加确认轮次。
 
-## ADR 守则
+## ADR 增量规则
 
-- 三条件全满足才提议（难逆转 / 无上下文费解 / 真实权衡）；`docs/adr/` 懒创建
-- 格式：标题 + 1-3 句正文；可选节（Status/Considered Options/Consequences）按需，大多数不需要
-- 编号：`0001-slug.md` 顺序递增，扫描最高号 +1
-- 草稿经用户显式确认后落盘，任何情况无例外（见 SKILL.md 流程① 与不可协商规则）
+- 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
+- ADR 草稿必须完整展示并获得用户明确确认后才落盘；这是本 skill 的独有硬门禁。
+- 不把 ADR 当 glossary 一样静默 inline 更新。
 
-## Spec 守则
+## Spec 增量规则
 
-- 完整七节模板逐节不缺：Problem Statement / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope / Further Notes
-- User Stories：长编号列表，`As an <actor>, I want a <feature>, so that <benefit>` 格式
-- Implementation Decisions：不含文件路径/代码片段；例外——原型产出的决策密集片段可 inline，注明来源并裁剪至决策部分
-- 全文贯穿 glossary 词汇；尊重所触区域既有 ADR
-- seams：既有优先于新建、取最高、理想数量 1，与用户确认
-- 发布后标 `ready-for-agent`，triage 状态以 issue 文件顶部 `Status:` 行记录
+- Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
+- seam 提案并入最终 spec 草稿，不再制造独立的一次确认。
+- 发布前只做一次最终 spec 明确确认；确认后写入并标记 `ready-for-agent`。
+- 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
 
-## 反模式（不做什么）
+## 反模式
 
-- 不把守则当逐条朗读的检查清单——守则约束产出物格式，不约束对话节奏
-- 不把 ADR 当 glossary 一样 inline 更新（见 SKILL.md 不可协商规则）
-- 不产出守则之外的文件：产出物只有三种（Glossary / ADR / Spec）
-- 不在本文件之外重复守则细节——SKILL.md 与 references 之间信息只在一处存在
+- 不复制 `to-spec` 的章节清单、User Story 模板或 Implementation Decisions 细则。
+- 不产出 Glossary / ADR / Spec 之外的额外设计文件。
+- 不把本文件当逐条朗读的对话脚本；它只约束本地增量行为。

package/template/.agents/skills/scaffold-functional-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: scaffold-functional-test
 disable-model-invocation: false
-description: "Scaffold a repo-specific functional-test skill from spec — use when the user wants to generate a customized functional-test suite/skill from a spec/README/help; not for regular instance execution (use the generated instance-test skill) nor for TDD (use tdd-implement)"
+description: "Scaffold a repo-specific functional-test skill from spec — use when the user wants to generate a customized functional-test suite/skill from a spec/README/help; supports CLI, HTTP, browser, and file-oriented behaviors; not for regular instance execution nor for TDD"
 ---
 
 # Scaffold Functional Test
@@ -22,9 +22,11 @@ spec 不存在时可从 README 与 `--help` 建立候选清单，但必须把它
 
 ### ② 推导并确认实例
 
-按 [`references/schema.md`](references/schema.md) 为每个行为生成实例草案：每个实例必须有溯源，不能用无来源的隐含行为扩张范围。向用户展示实例清单并等待一次确认；确认前不落盘。
+按 [`references/schema.md`](references/schema.md) 为每个行为选择最接近真实用户路径的实例类型：`cli`、`http`、`browser` 或 `file`。每个实例必须有溯源，不能用无来源的隐含行为扩张范围，也不能为了统一格式给 browser/http 行为强塞无意义的 stdout/exit-code 字段。
 
-出口：实例清单已确认，每个实例字段完整且可追溯。
+向用户展示实例清单并等待一次确认；确认前不落盘。
+
+出口：实例清单已确认，每个实例类型、字段和断言完整且可追溯。
 
 ### ③ 生成或更新
 
@@ -39,19 +41,20 @@ spec 不存在时可从 README 与 `--help` 建立候选清单，但必须把它
 
 ### ④ 结构验证
 
-生成后立即做快速、确定性的结构验证：文件存在、schema 字段、实例溯源、spec hash、`generatedAt`、manual 段保护和内部链接均通过后再报告成功。不默认执行完整实例集，不启动服务，不产生功能测试副作用。
+生成后立即做快速、确定性的结构验证：文件存在、schema 字段、实例类型、实例溯源、spec hash、`generatedAt`、manual 段保护和内部链接均通过后再报告成功。不默认执行完整实例集，不启动服务，不产生功能测试副作用。
 
 出口：结构验证结果为 `PASS`，失败则报告具体 gap，不回滚生成物。
 
 ## 可选行为验证
 
-仅当用户明确要求运行实例集时，才调用生成的功能测试 skill 执行隔离、串行的实例验证；届时按实例捕获 stdout/stderr、exit code 和 expected-vs-actual evidence，并由执行 skill 报告 `PASS m/n`。这不是 scaffold 的默认步骤。
+仅当用户明确要求运行实例集时，才调用生成的功能测试 skill 执行隔离、串行的实例验证；执行器按实例 `type` 捕获对应 evidence：CLI 的 stdout/stderr/exit code，HTTP 的 status/body/headers，browser 的页面/DOM/network/console 证据，file 的文件与内容 diff，并报告 expected-vs-actual 与 `PASS m/n`。这不是 scaffold 的默认步骤。
 
 ## 不做什么
 
 - 不替代生成后的功能测试 skill；
 - 不替代 `tdd`、`tdd-implement` 或 `commit-check`；
-- 不覆盖 `<!-- manual -->` 段，不静默重生成，不把 README/`--help` 推断写成无溯源实例。
+- 不覆盖 `<!-- manual -->` 段，不静默重生成，不把 README/`--help` 推断写成无溯源实例；
+- 不把所有行为强制降格成 CLI 测试。
 
 ## 引用