@heihei0299/matt-skills 3.1.1 → 3.1.3

package/README.md

@@ -66,7 +66,9 @@ npx @heihei0299/matt-skills sync --dry-run --json
 
 `init` 对已有 `AGENTS.md` 始终跳过；已有项目使用 `sync`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`--all` 只扩大技能范围。需要显式刷新 `AGENTS.md` 时使用 `sync --refresh-agents`；无受管区块时会先备份为 `AGENTS.md.bak`。`sync` 不删除目标项目的额外文件或自定义 skills。
 
-默认 workflow 范围固定为 7 个入口及依赖 skills，包含 `initialize-project`、`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`grilling` 和 `domain-modeling`；其中默认独有 skills 是 `initialize-project`。`tdd` 及其他可分发 skills 仍通过 `--all` 获取。
+默认 `init` / `sync` 不分发 `.pi` 与 `.opencode`；需要完整 harness 配置时使用 `--all`。
+
+默认 workflow 范围固定为 9 个入口及依赖 skills，包含 `initialize-project`、`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`grilling`、`domain-modeling`、`tdd` 和 `diagnosing-bugs`；其中默认独有 skills 是 `initialize-project`。
 
 ## CLI
 

package/bin/cli.js

@@ -34,7 +34,7 @@ Usage:
 
 Init options:
   --dest <path>   Target directory (default: current directory)
-  --all           Include all distributable skills; default only default workflow skills
+  --all           Include all distributable skills and .pi/.opencode; default workflow skills only
   --help, -h      Show this help
 提示：已有 AGENTS.md 时 init 始终跳过；需要更新已有项目请使用 sync。
 
@@ -47,7 +47,7 @@ Usage:
   matt-skills sync [--all|--dry-run|--refresh-agents] [--dest <path>]
 
 Sync options:
-  --all              同步全部可分发技能；不改变 AGENTS.md 刷新策略
+  --all              同步全部可分发技能和 .pi/.opencode；不改变 AGENTS.md 刷新策略
   --refresh-agents   显式刷新 AGENTS.md；无受管区块时先备份为 AGENTS.md.bak
   --dry-run          预演目标项目变化，只比对不写盘
   --json             仅与 --dry-run 一起使用，输出机器可读结果

package/bin/commands/init.js

@@ -31,7 +31,7 @@ export async function runInit(args) {
   if (await pathExists(marker)) {
     process.stdout.write('模板已存在（AGENTS.md），跳过\n');
   } else {
-    await copyTemplate(target);
+    await copyTemplate(target, { includeHarness: all });
     const selectedSkills = await listSkillNames({ onlyProgramming });
     await distributeProjectSkills({ target, sourceDir: SKILLS_DIR, skillNames: selectedSkills });
     process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILLS_DIR}）\n`);

package/bin/commands/sync.js

@@ -55,7 +55,7 @@ async function syncCommand({ dest, all, dryRun, json, refreshAgents, quiet = fal
   }
 
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
-  const template = await syncTemplate({ target, refreshAgents });
+  const template = await syncTemplate({ target, refreshAgents, includeHarness: all });
   if (template.initialized) {
     output('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
     output(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILLS_DIR}）\n`);

package/bin/project/template.js

@@ -8,17 +8,18 @@ const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '../..');
 export const TEMPLATE_DIR = path.join(ROOT, 'template');
 const DRY_RUN_PATHS = ['AGENTS.md', 'AGENTS.md.bak', '.opencode', '.pi', '.agents/skills', '.claude/skills'];
 
-function shouldCopyTemplatePath(src) {
+function shouldCopyTemplatePath(src, includeHarness) {
   const relative = path.relative(TEMPLATE_DIR, src);
   const parts = relative.split(path.sep);
-  return !(parts[0] === '.agents' && parts[1] === 'skills');
+  if (parts[0] === '.agents' && parts[1] === 'skills') return false;
+  return includeHarness || (parts[0] !== '.pi' && parts[0] !== '.opencode');
 }
 
-export async function copyTemplate(target) {
+export async function copyTemplate(target, { includeHarness = true } = {}) {
   await cp(TEMPLATE_DIR, target, {
     recursive: true,
     force: true,
-    filter: shouldCopyTemplatePath,
+    filter: (src) => shouldCopyTemplatePath(src, includeHarness),
   });
 }
 
@@ -77,10 +78,10 @@ export async function refreshAgentsFile(targetFile) {
   return 'full';
 }
 
-export async function syncTemplate({ target, refreshAgents }) {
+export async function syncTemplate({ target, refreshAgents, includeHarness = true }) {
   const marker = path.join(target, 'AGENTS.md');
   if (!(await pathExists(marker))) {
-    await copyTemplate(target);
+    await copyTemplate(target, { includeHarness });
     return { initialized: true, agentsManaged: false, agentsRefreshed: false, agentsRefreshMode: null };
   }
 
@@ -95,7 +96,9 @@ export async function syncTemplate({ target, refreshAgents }) {
       agentsManaged = await syncManagedAgents(marker, path.join(TEMPLATE_DIR, 'AGENTS.md'));
     } catch {}
   }
-  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 });
+  if (includeHarness) {
+    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 });
+  }
   return { initialized: false, agentsManaged, agentsRefreshed, agentsRefreshMode };
 }

package/config/default.json

@@ -1,9 +1,11 @@
 [
+  "diagnosing-bugs",
   "domain-modeling",
   "grill-with-docs",
   "grilling",
   "initialize-project",
   "setup-matt-pocock-skills",
+  "tdd",
   "to-spec",
   "to-tickets"
 ]

package/package.json

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

package/scripts/sync-upstream.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { cp, readdir, readFile, rm, stat, mkdir } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, readdir, readFile, readlink, rename, rm, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -30,20 +30,31 @@ async function loadRequired() {
   return loadSkillSet(REQUIRED_PATH, 'required');
 }
 
-async function hashFile(filePath) {
-  const buf = await readFile(filePath);
-  return createHash('sha256').update(buf).digest('hex');
-}
-
 async function hashDir(dir) {
-  // 对 SKILL.md 做 hash，用于比对；若无 SKILL.md 则对目录内所有文件联合 hash
-  const skillMd = path.join(dir, 'SKILL.md');
-  try {
-    await stat(skillMd);
-    return await hashFile(skillMd);
-  } catch {
-    return null;
+  const files = [];
+
+  async function collect(current, relative = '') {
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      const entryRelative = path.posix.join(relative, entry.name);
+      if (entry.isDirectory()) await collect(entryPath, entryRelative);
+      else if (entry.isFile()) files.push({ path: entryPath, relative: entryRelative, type: 'file' });
+      else if (entry.isSymbolicLink()) files.push({ path: entryPath, relative: entryRelative, type: 'symlink' });
+    }
+  }
+
+  await collect(dir);
+  files.sort((a, b) => (a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0));
+
+  const hash = createHash('sha256');
+  for (const file of files) {
+    hash.update(`${file.type}\0${file.relative}\0`);
+    hash.update(file.type === 'symlink' ? await readlink(file.path) : await readFile(file.path));
+    hash.update('\0');
   }
+  return hash.digest('hex');
 }
 
 async function listSkills(dir) {
@@ -62,17 +73,30 @@ async function fetchUpstream({ tmpDir, upstreamUrl = UPSTREAM_URL, ref = 'HEAD'
   const dest = tmpDir || path.join(os.tmpdir(), `matt-skills-upstream-${Date.now()}`);
   await rm(dest, { recursive: true, force: true });
   await mkdir(path.dirname(dest), { recursive: true });
-  const clone = spawnSync('git', ['clone', '--depth', '1', upstreamUrl, dest], { encoding: 'utf8' });
-  if (clone.status !== 0) {
-    throw new Error(`git clone 失败: ${clone.stderr || clone.stdout}`);
-  }
-  if (ref && ref !== 'HEAD') {
-    const co = spawnSync('git', ['-C', dest, 'checkout', ref], { encoding: 'utf8' });
-    if (co.status !== 0) throw new Error(`git checkout ${ref} 失败: ${co.stderr}`);
+  try {
+    const clone = spawnSync('git', ['clone', '--depth', '1', upstreamUrl, dest], { encoding: 'utf8' });
+    if (clone.status !== 0) {
+      throw new Error(`git clone 失败: ${clone.stderr || clone.stdout || clone.error?.message || 'unknown error'}`);
+    }
+    if (ref && ref !== 'HEAD') {
+      const fetched = spawnSync('git', ['-C', dest, 'fetch', '--depth', '1', 'origin', ref], { encoding: 'utf8' });
+      if (fetched.status !== 0) {
+        throw new Error(`git fetch ${ref} 失败: ${fetched.stderr || fetched.stdout || fetched.error?.message || 'unknown error'}`);
+      }
+      const co = spawnSync('git', ['-C', dest, 'checkout', '--detach', 'FETCH_HEAD'], { encoding: 'utf8' });
+      if (co.status !== 0) {
+        throw new Error(`git checkout ${ref} 失败: ${co.stderr || co.stdout || co.error?.message || 'unknown error'}`);
+      }
+    }
+    const rev = spawnSync('git', ['-C', dest, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+    if (rev.status !== 0) {
+      throw new Error(`git rev-parse 失败: ${rev.stderr || rev.stdout || rev.error?.message || 'unknown error'}`);
+    }
+    return { dest, head: rev.stdout.trim() || 'unknown' };
+  } catch (error) {
+    await rm(dest, { recursive: true, force: true }).catch(() => {});
+    throw error;
   }
-  const rev = spawnSync('git', ['-C', dest, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
-  const head = rev.stdout ? rev.stdout.trim() : 'unknown';
-  return { dest, head };
 }
 
 async function collectUpstreamSkills(upstreamRoot) {
@@ -95,27 +119,27 @@ async function collectUpstreamSkills(upstreamRoot) {
   return map;
 }
 
-async function collectLocalSkills(proprietary) {
+async function collectLocalSkills(proprietary, localSkillsDir = LOCAL_SKILLS_DIR) {
   const map = new Map();
-  const names = await listSkills(LOCAL_SKILLS_DIR);
+  const names = await listSkills(localSkillsDir);
   for (const name of names) {
     if (name === 'skill-creator') continue; // 本地符号链接，不纳入上游比对
     if (proprietary.has(name)) continue;
-    const dir = path.join(LOCAL_SKILLS_DIR, name);
+    const dir = path.join(localSkillsDir, name);
     const h = await hashDir(dir);
     map.set(name, { dir, hash: h });
   }
   return map;
 }
 
-export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true } = {}) {
+export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true, localSkillsDir = LOCAL_SKILLS_DIR } = {}) {
   const proprietary = await loadProprietary();
   const engineering = await loadEngineering();
   const required = await loadRequired();
   const fetched = await fetchUpstream({ tmpDir, upstreamUrl, ref });
   const upstreamRoot = fetched.dest;
   const upstreamMapFull = await collectUpstreamSkills(upstreamRoot);
-  const localMapFull = await collectLocalSkills(proprietary);
+  const localMapFull = await collectLocalSkills(proprietary, localSkillsDir);
   // 默认范围：engineering 桶（编程）+ 独有所需（config/required.json，如 grill-to-spec 经 grill-with-docs 所需的 grilling）；--all 则含全部 productivity
   const upstreamMap = onlyProgramming
     ? new Map([...upstreamMapFull.entries()].filter(([name, v]) => v.bucket === 'engineering' || required.has(name)))
@@ -188,59 +212,124 @@ export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true
   };
 }
 
-export async function applySync({ upstreamUrl, tmpDir, ref, dryRun = false, force = false, onlyProgramming = true } = {}) {
-  const proprietary = await loadProprietary();
-  const cmp = await compare({ upstreamUrl, tmpDir, ref, onlyProgramming });
+async function verifyStagedSkills({ stageDir, effectiveMap, upstreamMapFull, result }) {
+  const sourceFor = (name) => effectiveMap.get(name) || upstreamMapFull.get(name);
+  const expected = new Set([
+    ...result.renamed.map((r) => r.to),
+    ...result.added.filter((name) => !result.renamed.some((r) => r.to === name)),
+    ...result.updated.filter((name) => !name.includes('→')),
+  ]);
+
+  for (const name of expected) {
+    const source = sourceFor(name);
+    const staged = path.join(stageDir, name);
+    if (!source || await hashDir(staged) !== source.hash) {
+      throw new Error(`同步暂存校验失败: ${name}`);
+    }
+  }
+  for (const name of [...result.removed, ...result.renamed.map((r) => r.from)]) {
+    try {
+      await stat(path.join(stageDir, name));
+      throw new Error(`同步暂存校验失败: ${name} 应被删除`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+async function commitStagedSkills(localSkillsDir, stageDir) {
+  const parent = path.dirname(localSkillsDir);
+  const backupDir = await mkdtemp(path.join(parent, '.matt-skills-sync-backup-'));
+  await rm(backupDir, { recursive: true, force: true });
+  let originalMoved = false;
+  let stageMoved = false;
+
+  try {
+    await rename(localSkillsDir, backupDir);
+    originalMoved = true;
+    await rename(stageDir, localSkillsDir);
+    stageMoved = true;
+  } catch (error) {
+    try {
+      if (stageMoved) await rename(localSkillsDir, stageDir);
+      if (originalMoved) await rename(backupDir, localSkillsDir);
+    } catch (rollbackError) {
+      throw new Error(`同步失败且回滚失败: ${rollbackError.message}; 原始错误: ${error.message}`);
+    }
+    await rm(backupDir, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+
+  await rm(backupDir, { recursive: true, force: true });
+}
+
+export async function applySync({ upstreamUrl, tmpDir, ref, dryRun = false, force = false, onlyProgramming = true, localSkillsDir = LOCAL_SKILLS_DIR, failAfter = null } = {}) {
+  const cmp = await compare({ upstreamUrl, tmpDir, ref, onlyProgramming, localSkillsDir });
   const { dest, head, upstreamMap, upstreamMapFull, result } = cmp;
   const effectiveMap = onlyProgramming ? upstreamMap : upstreamMapFull;
   const actions = [];
+  let stageDir = null;
 
-  if (dryRun) {
-    await rm(dest, { recursive: true, force: true });
-    return { ...cmp, dest: null, actions, dryRun: true };
-  }
+  try {
+    if (dryRun) return { ...cmp, dest: null, actions, dryRun: true };
+    const hasDiff = result.added.length + result.updated.length + result.removed.length + result.renamed.length > 0;
+    if (!hasDiff) return { ...cmp, dest: null, actions, head };
 
-  // 处理重命名
-  for (const r of result.renamed) {
-    const src = effectiveMap.get(r.to)?.dir || upstreamMapFull.get(r.to)?.dir;
-    if (!src) continue;
-    const dst = path.join(LOCAL_SKILLS_DIR, r.to);
-    const oldDst = path.join(LOCAL_SKILLS_DIR, r.from);
-    await rm(oldDst, { recursive: true, force: true });
-    await rm(dst, { recursive: true, force: true });
-    await cp(src, dst, { recursive: true, force: true });
-    actions.push(`rename ${r.from} → ${r.to}`);
-  }
+    const stagePrefix = path.join(path.dirname(localSkillsDir), '.matt-skills-sync-stage-');
+    stageDir = await mkdtemp(stagePrefix);
+    await rm(stageDir, { recursive: true, force: true });
+    await cp(localSkillsDir, stageDir, { recursive: true, force: true });
+    let successfulOperations = 0;
+    const stageOperation = async (operation) => {
+      if (Number.isInteger(failAfter) && failAfter >= 0 && successfulOperations >= failAfter) {
+        throw new Error(`注入同步失败（已完成 ${successfulOperations} 个暂存操作）`);
+      }
+      const value = await operation();
+      successfulOperations++;
+      return value;
+    };
+    const sourceFor = (name) => effectiveMap.get(name)?.dir || upstreamMapFull.get(name)?.dir;
 
-  for (const name of result.added) {
-    if (result.renamed.some((r) => r.to === name)) continue;
-    const src = effectiveMap.get(name)?.dir || upstreamMapFull.get(name)?.dir;
-    if (!src) continue;
-    const dst = path.join(LOCAL_SKILLS_DIR, name);
-    await cp(src, dst, { recursive: true, force: true });
-    actions.push(`add ${name}`);
-  }
+    // 处理重命名
+    for (const r of result.renamed) {
+      const src = sourceFor(r.to);
+      if (!src) continue;
+      await stageOperation(() => rm(path.join(stageDir, r.from), { recursive: true, force: true }));
+      await stageOperation(() => rm(path.join(stageDir, r.to), { recursive: true, force: true }));
+      await stageOperation(() => cp(src, path.join(stageDir, r.to), { recursive: true, force: true }));
+      actions.push(`rename ${r.from} → ${r.to}`);
+    }
 
-  for (const name of result.updated) {
-    if (name.includes('→')) continue;
-    const src = effectiveMap.get(name)?.dir || upstreamMapFull.get(name)?.dir;
-    if (!src) continue;
-    const dst = path.join(LOCAL_SKILLS_DIR, name);
-    await rm(dst, { recursive: true, force: true });
-    await cp(src, dst, { recursive: true, force: true });
-    actions.push(`update ${name}`);
-  }
+    for (const name of result.added) {
+      if (result.renamed.some((r) => r.to === name)) continue;
+      const src = sourceFor(name);
+      if (!src) continue;
+      await stageOperation(() => cp(src, path.join(stageDir, name), { recursive: true, force: true }));
+      actions.push(`add ${name}`);
+    }
 
-  for (const name of result.removed) {
-    const dst = path.join(LOCAL_SKILLS_DIR, name);
-    await rm(dst, { recursive: true, force: true });
-    actions.push(`remove ${name}`);
-  }
+    for (const name of result.updated) {
+      if (name.includes('→')) continue;
+      const src = sourceFor(name);
+      if (!src) continue;
+      await stageOperation(() => rm(path.join(stageDir, name), { recursive: true, force: true }));
+      await stageOperation(() => cp(src, path.join(stageDir, name), { recursive: true, force: true }));
+      actions.push(`update ${name}`);
+    }
 
-  // 清理临时目录
-  await rm(dest, { recursive: true, force: true });
+    for (const name of result.removed) {
+      await stageOperation(() => rm(path.join(stageDir, name), { recursive: true, force: true }));
+      actions.push(`remove ${name}`);
+    }
 
-  return { ...cmp, dest: null, actions, head };
+    await verifyStagedSkills({ stageDir, effectiveMap, upstreamMapFull, result });
+    await commitStagedSkills(localSkillsDir, stageDir);
+    stageDir = null;
+    return { ...cmp, dest: null, actions, head };
+  } finally {
+    await rm(dest, { recursive: true, force: true }).catch(() => {});
+    if (stageDir) await rm(stageDir, { recursive: true, force: true }).catch(() => {});
+  }
 }
 export function formatComparison(cmp) {
   const { result, counts, head, onlyProgramming } = cmp;

package/template/AGENTS.md

@@ -1,33 +1,30 @@
-## Workflow
-按任务选择最匹配的 skill / 工具：
-* 需要新增证据的代码理解 / 定位 / 调用链 / 依赖关系 / 数据流 → `codegraph explore`
-* 目标项目首次初始化或刷新项目上下文 → `initialize-project`
-* 首次使用 spec / tickets 流程，需要配置 issue tracker 和领域文档 → `setup-matt-pocock-skills`
-* 模糊需求、设计讨论并同步 ADR / glossary → `grill-with-docs`
-* 已有共识，需要发布 spec → `to-spec`
-* 已有 spec / 计划，需要拆分可执行 tickets → `to-tickets`
-未命中 skill 时直接执行。明确不改变行为的文案、注释、格式和机械修改直接处理。
-仅当关键歧义无法从仓库事实解决，且会改变实现、范围、风险或验收结果时询问用户。
+本仓库遵循全局 `AGENTS.md`；以下规则仅用于具体化本项目工作流，不放宽全局安全、授权或运行时权限边界。
+
 ## Context / CodeGraph
-以当前代码、配置、测试和版本化文档为事实来源；更具体的项目指令优先。
-- 有 issue/spec 时先读当前 issue；否则从用户问题和最相关 symbol/path 开始。
-- 只按当前未决问题逐步扩展上下文；README/package/tests/docs 按需读取。
-- 当前上下文已有充分且未过时的证据时，不做等价重复读取。
-- 当当前上下文不足、需要新增代码理解证据时，优先使用 `codegraph explore`；结果充分后不再 broad grep/read。
+
+以当前代码、配置、测试和版本化文档为项目事实来源；更具体的目录级规则优先。
+有当前 issue / spec 时先读它；否则从用户问题和最相关的 symbol / path 开始。
+只围绕当前未决问题扩展上下文；README、package、tests、docs 按需读取。
+当前上下文已有充分且未过时的证据时，不做等价重复读取。
+当前上下文不足且需要新增代码理解证据时，优先使用 `codegraph explore`；结果充分后不再执行等价的 broad grep / read。
 实现时复用现有抽象、接口和依赖方向，不创建平行实现或无关扩展。
+
 ## Validation
-验证应足以证明修改正确且未破坏直接受影响行为。
-优先验证原问题、相关测试和直接受影响模块；不重复已有有效证据。
-公共 API、共享抽象、跨模块调用链或局部验证不足时扩大验证范围；普通修改不自动运行全量测试。
+
+优先验证原问题、相关测试和直接受影响模块。
+公共 API、共享抽象、跨模块调用链或局部验证不足时扩大验证范围。
+项目已有针对当前改动的验证入口时优先使用，不自行创建等价验证流程。
+
 ## Git
-- 每个独立 issue/spec 对应一个 commit；不得按实现、测试、review 等阶段拆分。
-- 仅在本次改动完成并通过相关验证后提交。checkpoint 例外，但须明确标注未完成或未通过的验证。
-- commit 前检查 `git diff` 和 `git status`；只 stage 本次任务改动，不覆盖、回滚或提交用户及其他任务的既有修改。
-- `commit` 不授权 `push` 或发布；远程写入须单独授权。
-- commit 后报告 hash、验证命令及结果。
-## Security
-* 不读取、输出或提交未经授权的真实 secrets。
-* 按现有 lockfile 恢复依赖可直接执行。
-* 新增/升级依赖、部署、发布、`git push`、远程写入和破坏性操作必须明确授权。
+
+每个独立 issue / spec 对应一个交付 commit，不按实现、测试、review 等阶段拆分。
+仅在本次任务完成并通过相关验证后 commit；明确要求 checkpoint 时可提交未完成状态，并注明未完成或未通过的验证。
+commit 前检查 `git diff` 和 `git status`；只 stage 当前任务改动，不混入其他任务或用户已有修改。
+commit 不授权 push、发布或其他远程写入。
+commit 后报告 hash，以及本次执行的主要验证及结果。
+
 ## Completion
-完成时简要说明结果和验证；有重要未验证项、限制或风险时说明；有 commit 时报告 hash。
+
+完成时简要说明结果、关键修改和验证。
+存在重要未验证项、已知限制、既有失败或剩余风险时明确指出。
+有 commit 时报告 commit hash。