@heihei0299/matt-skills 3.0.8 → 3.0.10

package/.agents/skills/tdd-implement/SKILL.md

@@ -65,7 +65,7 @@ Verify 通过后读取 [review.md](references/review.md)。
 
 Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
 
-Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、文档/配置或验证遗漏，按 `finalize.md` 返回对应 Step，不得绕过 Review 直接完成。
+Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
 
 ## 运行纪律
 

package/.agents/skills/tdd-implement/references/finalize.md

@@ -5,23 +5,19 @@
 ## 步骤
 
 1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
-2. 更新 Acceptance Criteria 与 progress/tracker，记录已 Review 的实现范围、Review、验证与运行结果，并同步 `resolved` / blockers 状态。
-3. 若上述状态同步修改了仓库内的 tracker/progress/status 文件，将这些状态修改提交；不得在该提交中混入产品实现或其它未 Review 的交付修改。
-4. 确认所有必要状态同步成功后，设置 `issue_head = HEAD`。
+2. 更新 Acceptance Criteria 与 progress/tracker，记录已 Review 的实现范围、Review、验证与运行结果；此时不得提前标记 `resolved` 或解除 blockers。
+3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
+4. 仅在未发现上述遗漏且所有必要状态同步准备完成后，才同步 `resolved` / blockers 状态。
+5. 若状态同步修改了仓库内的 tracker/progress/status 文件，将这些状态修改提交；不得在该提交中混入产品实现或其它未 Review 的交付修改。
+6. 确认所有必要状态同步成功后，设置 `issue_head = HEAD`。
 
 无需为了固定 commit 数量而 amend、squash 或重写当前 issue 的历史。
 
-若 Finalize 中发现遗漏：
-
-- 仅缺验证证据：返回 Verify 补足证据，再回 Finalize；
-- 需要修改代码、测试、交付文档或配置：将该遗漏加入 `open_findings`，返回对应 Red-Green / Verify 完成修改与验证，提交修复后按 `review.md` 做增量 Review；`full_review_done` 保持为 `true`。
-
-不得在 Finalize 中直接补实现后继续标记完成。
-
 ## 出口
 
 - Acceptance Criteria 全部通过；
 - `issue_base...review_head` 的实现范围已经完成 Review；
+- Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
 - tracker/progress/status 与实际 Review、验证和完成状态一致；
 - `review_head` 之后若存在 commits，只包含当前 issue 的状态收尾修改；
 - `issue_head = HEAD` 已记录；

package/.agents/skills/tdd-implement/references/review.md

@@ -4,13 +4,14 @@
 
 ## 状态
 
-进入当前 issue 的 Review 时维护：
+当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次；后续因 finding 修复返回 Red-Green / Verify 后继续 Review 时保留现有状态，不得重新初始化：
 
 - `issue_base`：当前 issue 开始时的 `HEAD`；
 - `full_review_done = false`；
 - `open_findings = []`；
 - `last_reviewed_head = null`；
-- `review_head = null`。
+- `review_head = null`；
+- `incremental_review_rounds = 0`。
 
 ## 1. 形成 committed Review Point
 
@@ -52,6 +53,10 @@
 
 存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。可将由同一改动共同解决的相关 findings 一起处理，不要求“一 finding 一 commit”。
 
+每个 issue 最多执行 2 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
+
+每轮修复前，若 `incremental_review_rounds >= 2` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
+
 每轮修复：
 
 1. 修复选定的 open findings；
@@ -60,23 +65,35 @@
 4. 将本轮修复提交到当前 issue 的 commit range，并确认不存在属于本轮修复的未提交修改；
 5. 只针对 `last_reviewed_head...HEAD` 与本轮目标 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
 
+若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
+
 增量 Review 通过时：
 
 - 仅关闭本轮已由证据确认解决的 findings；
 - 设置 `last_reviewed_head = HEAD`。
 
-增量 Review 未通过或发生技术失败时：
+增量 Review 正常完成但未通过时：
 
+- 保留未关闭 findings；
+- 不推进 `last_reviewed_head`；
+- 若尚未达到 2 轮上限，下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
+
+增量 Review 发生技术失败时：
+
+- 不增加 `incremental_review_rounds`；
 - 不推进 `last_reviewed_head`；
 - 不移除未确认关闭的 findings；
-- 下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
+- 恢复后重试当前逻辑轮次。
 
 当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
 
+当 `incremental_review_rounds = 2` 且 `open_findings` 仍非空时，Review 不通过：保持 issue 未完成，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
+
 ## 出口
 
 - `full_review_done = true`；
 - `open_findings` 为空；
 - `review_head` 非空；
+- `incremental_review_rounds <= 2`；
 - `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围；
 - 不存在属于该实现范围的未提交交付修改。

package/README.md

@@ -12,11 +12,11 @@ template/
 └── .pi/                      pi prompts、docs 与项目自定义 skills 占位
 ```
 
-共享 Skills 不作为 Template Snapshot 的持久化副本；`init`、`sync` 和 `install` 根据 distribution boundary 从 Workspace 的 canonical source 分发到目标项目的 `.agents/skills/`。
+共享 Skills 不作为 Template Snapshot 的持久化副本；`init`、普通 `sync` 和 `install` 从 Workspace 的 canonical source 分发到各工具的默认项目目录：Codex 为 `.agents/skills/`、pi 为 `.pi/skills/`、opencode 为 `.opencode/skills/`、Claude 为 `.claude/skills/`。
 
 - `PROJECT.md` 描述项目是什么；操作规则放在 `AGENTS.md`。
 - `.opencode/CONTEXT.md` / `.pi/CONTEXT.md` 保存领域术语与边界。
-- `.opencode/skills/` 与 `.pi/skills/` 仅用于项目自定义 skills。
+- 各工具默认项目目录承载共享 skills；同步只处理可分发 skill 名称，不删除额外的项目自定义 skills。
 - `ci-guard`、`commit-check` 是本仓库维护用的 repo-local skills，不会分发到目标项目。
 
 ## 独有 skill 分发边界
@@ -73,13 +73,13 @@ npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <re
 
 - `--all`：包含全部可分发 skills，默认范围只包含 programming skills。
 - `--dest <dir>`：指定目标目录。
-- `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级共享 skills 统一写入 `.agents/skills/`。
+- `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级 skills 写入所选工具的默认目录。
 - `--global`：写入用户级 skills 目录。
 - `--dry-run`：只检查差异，不写入；`--json` 输出机器可读结果。
 
 ## Codex CLI 支持
 
-Codex 与其他 harness 共用项目级 `.agents/skills/` 唯一共享源；全局 skills 位于 `~/.codex/skills`。
+Codex 的项目级 skills 位于 `.agents/skills/`；全局 skills 位于 `~/.codex/skills`。`init` 和普通 `sync` 默认同时分发到四个工具的项目目录。
 
 ```sh
 npm run codex:smoke

package/bin/cli.js

@@ -33,10 +33,12 @@ process.stdout.on('error', (err) => {
   throw err;
 });
 
+const PROJECT_SKILL_DIRS = '.agents/skills、.pi/skills、.opencode/skills、.claude/skills';
+
 const HELP_GLOBAL = `matt-skills — install and manage this skill collection
 
 Usage:
-  matt-skills init [options]                   Initialize a project: template + skills (.agents/skills)
+  matt-skills init [options]                   Initialize a project: template + skills (${PROJECT_SKILL_DIRS})
   matt-skills sync [--all|--dry-run] [--dest <path>]   Sync existing project to latest template + skills
   matt-skills list [--all] [--json]            List available skills and their descriptions
   matt-skills install [options]                Install skills (interactive by default)
@@ -46,7 +48,7 @@ Usage:
   matt-skills --version | -v                  Show version
 `;
 
-const HELP_INIT = `matt-skills init [options] — Initialize a project: template + skills (.agents/skills)
+const HELP_INIT = `matt-skills init [options] — Initialize a project: template + skills (${PROJECT_SKILL_DIRS})
 
 Usage:
   matt-skills init [options]
@@ -70,6 +72,7 @@ Sync options:
   --dry-run       预演：只比对不写盘
   --dest <path>   Target directory (default: current directory)
   --help, -h      Show this help
+  项目 skills：${PROJECT_SKILL_DIRS}
 
 说明：默认不带 --all 增量同步默认 programming skill，并只更新 AGENTS.md 的 matt-skills 受管区块；没有受管标记的现有 AGENTS.md 原样保留。--all 时同步全部可分发 skill 并强制刷新 AGENTS.md。
 
@@ -110,7 +113,7 @@ Usage:
   matt-skills install [options]
 
 Install options:
-  --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection — 共享技能统一指向 .agents/skills，.pi/skills/.opencode/skills 仅用于项目自定义
+  --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool 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
@@ -217,15 +220,17 @@ async function syncManagedAgents(targetFile) {
 
 const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
 
-// 统一源：共享技能全部在 .agents/skills，harness 的 .pi/skills/.opencode/skills 仅用于项目自定义
-// 为兼容历史，pi/opencode/claude 的项目安装仍解析但统一指向 .agents/skills，并给出提示
 const PROJECT_DIRS = {
   codex: '.agents/skills',
-  pi: '.agents/skills',
-  opencode: '.agents/skills',
-  claude: '.agents/skills',
+  pi: '.pi/skills',
+  opencode: '.opencode/skills',
+  claude: '.claude/skills',
 };
 
+function projectSkillTargets(target) {
+  return TOOLS.map((tool) => ({ tool, dir: path.resolve(target, PROJECT_DIRS[tool]) }));
+}
+
 const GLOBAL_DIRS = {
   codex: '.codex/skills',
   pi: '.pi/agent/skills',
@@ -275,13 +280,8 @@ async function installCommand({ dest, all, force, tools, global }) {
       process.stdout.write('未选择任何工具，未安装任何技能\n');
       return;
     }
-    // 共享技能统一源提示：pi/opencode 的项目目录已改为 .agents/skills
-    const needsHint = selectedTools.some((t) => t === 'pi' || t === 'opencode');
-    if (needsHint && !global) {
-      process.stdout.write('提示：共享技能统一在 .agents/skills，.pi/skills/.opencode/skills 仅用于项目自定义技能\n');
-    }
     targets = selectedTools.map((tool) => ({ tool, dir: toolDir(tool, global) }));
-    // 去重：多个工具可能映射到同一目录（如 pi/opencode/codex 都指向 .agents/skills），合并去重避免重复计数
+    // 去重：保留对自定义 PROJECT_DIRS 映射的兼容。
     const seen = new Map();
     for (const t of targets) {
       if (!seen.has(t.dir)) seen.set(t.dir, t);
@@ -330,15 +330,16 @@ async function initCommand({ dest, all }) {
       filter: shouldCopyTemplatePath,
     });
     const selectedSkills = await listSkillNames({ onlyProgramming });
-    const skillsDir = path.join(target, '.agents', 'skills');
-    await mkdir(skillsDir, { recursive: true });
-    for (const name of selectedSkills) {
-      const source = path.join(SKILLS_DIR, name);
-      const destination = path.join(skillsDir, name);
-      if (path.resolve(source) === path.resolve(destination)) continue;
-      await cp(source, destination, { recursive: true, force: true });
+    for (const { dir } of projectSkillTargets(target)) {
+      await mkdir(dir, { recursive: true });
+      for (const name of selectedSkills) {
+        const source = path.join(SKILLS_DIR, name);
+        const destination = path.join(dir, name);
+        if (path.resolve(source) === path.resolve(destination)) continue;
+        await cp(source, destination, { recursive: true, force: true });
+      }
     }
-    process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
+    process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
   }
   // 统计（区分编程 vs 全量）
   const skillsDir = path.join(target, '.agents', 'skills');
@@ -407,7 +408,7 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       force: true,
       filter: shouldCopyTemplatePath,
     });
-    process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
+    process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
   } else {
     process.stdout.write('同步：检测到现有项目，将增量更新\n');
     if (all) {
@@ -416,7 +417,7 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
         force: true,
         filter: shouldCopyTemplatePath,
       });
-      process.stdout.write('模板：已同步（AGENTS.md 整体刷新、.opencode/、.pi/）\n');
+      process.stdout.write(`模板：已同步（AGENTS.md 整体刷新、skills：${PROJECT_SKILL_DIRS}）\n`);
     } else {
       let agentsManaged = false;
       try {
@@ -425,26 +426,23 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       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 (agentsManaged) {
-        process.stdout.write('模板：已同步（AGENTS.md 受管区块已更新，项目自定义内容已保留）\n');
+        process.stdout.write(`模板：已同步（AGENTS.md 受管区块已更新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
       } else {
-        process.stdout.write('模板：已同步（AGENTS.md 未受管，已原样保留）\n');
+        process.stdout.write(`模板：已同步（AGENTS.md 未受管、skills：${PROJECT_SKILL_DIRS}，已原样保留）\n`);
       }
     }
   }
   // 技能同步：--all 仅更新同名可分发技能内容，存在则覆盖，不存在则新增，并更新 AGENTS.md（由上一步已处理）；默认范围为默认 programming，不删多余
   const allSkills = await listSkillNames({ onlyProgramming });
-  const skillsDir = path.join(target, '.agents', 'skills');
-  await mkdir(skillsDir, { recursive: true });
+  const skillTargets = projectSkillTargets(target);
+  const skillsDir = path.resolve(target, PROJECT_DIRS.codex);
   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 },
-  ];
+  const preserveLocations = skillTargets.map(({ tool, dir }) => ({
+    dir,
+    label: PROJECT_DIRS[tool],
+    isWorkspaceSource: path.resolve(dir) === path.resolve(SKILLS_DIR),
+  }));
+  for (const { dir } of skillTargets) await mkdir(dir, { recursive: true });
   for (const name of REPO_LOCAL_SKILLS) {
     for (const location of preserveLocations) {
       if (!location.isWorkspaceSource && await pathExists(path.join(location.dir, name))) {
@@ -454,24 +452,26 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   }
   let installed = 0;
   let updated = 0;
-  for (const name of allSkills) {
-    const src = path.join(SKILLS_DIR, name);
-    const dst = path.join(skillsDir, name);
-    if (path.resolve(src) === path.resolve(dst)) {
-      updated++;
-      continue;
-    }
-    const exists = await pathExists(dst);
-    if (exists) {
-      await rm(dst, { recursive: true, force: true });
-      await cp(src, dst, { recursive: true, force: true });
-      updated++;
-    } else {
-      await cp(src, dst, { recursive: true, force: true });
-      installed++;
+  for (const { dir } of skillTargets) {
+    for (const name of allSkills) {
+      const src = path.join(SKILLS_DIR, name);
+      const dst = path.join(dir, name);
+      if (path.resolve(src) === path.resolve(dst)) {
+        if (path.resolve(dir) === skillsDir) updated++;
+        continue;
+      }
+      const exists = await pathExists(dst);
+      if (exists) {
+        await rm(dst, { recursive: true, force: true });
+        await cp(src, dst, { recursive: true, force: true });
+        if (path.resolve(dir) === skillsDir) updated++;
+      } else {
+        await cp(src, dst, { recursive: true, force: true });
+        if (path.resolve(dir) === skillsDir) installed++;
+      }
     }
   }
-  // Harness skill directories may contain project-local Skills. Preserve them because
+  // Project skill directories may contain project-local Skills. Preserve them because
   // their origin cannot be distinguished safely from a historical shared mirror.
   // 清理过时的 .pi/settings.json 指向
   try {

package/package.json

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

package/template/.opencode/skills/README.md

@@ -1,4 +1,4 @@
 # 项目技能（opencode）
 
-此目录用于存放项目自定义技能（project-local skills）。
-共享技能统一在 `.agents/skills/`。
+此目录用于存放项目 skills（共享或 project-local）。
+共享技能默认在 `.opencode/skills/`；同步不会删除额外的项目自定义 skills。

package/template/.pi/skills/README.md

@@ -1,4 +1,4 @@
 # 项目技能（pi）
 
-此目录用于存放项目自定义技能（project-local skills）。
-共享技能统一在 `.agents/skills/`。
+此目录用于存放项目 skills（共享或 project-local）。
+共享技能默认在 `.pi/skills/`；同步不会删除额外的项目自定义 skills。