@heihei0299/matt-skills 3.0.14 → 3.0.16

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

@@ -14,7 +14,7 @@ disable-model-invocation: true
 - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
 - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
 
-每个 issue 开始时记录 `issue_base = HEAD`。一个 issue 可以包含一个或多个 commits；不要求固定 commit 数量，也不为满足数量约束强制 amend、squash 或重写历史。
+每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；仅当 Full Review 产生 blocking findings 时，最多再形成 1 个 finding-fix commit。
 
 生命周期：
 
@@ -50,7 +50,7 @@ disable-model-invocation: true
 
 Verify 通过后读取 [review.md](references/review.md)。
 
-先将当前 issue 交付所需的代码、测试、文档和配置形成 committed Review Point，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
+先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
 
 完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
 
@@ -65,15 +65,17 @@ Verify 通过后读取 [review.md](references/review.md)。
 
 Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
 
-Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
+Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
+
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的实现/Review commit range。
 
 ## 运行纪律
 
 - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
 - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
 - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
-- 完整 Review 前必须形成 committed Review Point；不得用未提交 working tree 代替 `code-review` 所需的 committed diff。
-- 每个 issue 只有一次逻辑上的完整双轴 Review；完整 Review 之后只处理增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
+- Red-Green / Verify 期间不按 Behavior、阶段或验证动作拆 commit；完整 Review 前只形成 1 个 committed Review Point。
+- 每个 issue 只有一次逻辑上的完整双轴 Review；若有 blocking findings，只允许 1 个 finding-fix commit 与最多 1 次逻辑增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
 - 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `HEAD` 作为新的 `issue_base`。
 - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
 

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

@@ -1,24 +1,28 @@
 # Finalize
 
-仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，也不修改已经 Review 的代码、测试、交付文档或配置。
+仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改已经 Review 的代码、测试、交付文档或配置，也不为单个 issue 创建收尾 commit。
 
 ## 步骤
 
 1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
-2. 更新 Acceptance Criteria 与 progress/tracker，记录已 Review 的实现范围、Review、验证与运行结果；此时不得提前标记 `resolved` 或解除 blockers。
+2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录已 Review 的实现范围、Review、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
 3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
-4. 仅在未发现上述遗漏且所有必要状态同步准备完成后，才同步 `resolved` / blockers 状态。
-5. 若状态同步修改了仓库内的 tracker/progress/status 文件，将这些状态修改提交；不得在该提交中混入产品实现或其它未 Review 的交付修改。
-6. 确认所有必要状态同步成功后，设置 `issue_head = HEAD`。
+4. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
+5. Finalize 不创建 commit；设置 `issue_head = review_head`。此时当前 `HEAD` 应与 `review_head` 一致。
 
-无需为了固定 commit 数量而 amend、squash 或重写当前 issue 的历史。
+## 批次状态同步
+
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
+
+- 不混入产品实现、测试、交付文档或配置修改；
+- 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
+- 不因 issue 数量增加而拆成多个 status commits。
 
 ## 出口
 
 - Acceptance Criteria 全部通过；
 - `issue_base...review_head` 的实现范围已经完成 Review；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
-- tracker/progress/status 与实际 Review、验证和完成状态一致；
-- `review_head` 之后若存在 commits，只包含当前 issue 的状态收尾修改；
-- `issue_head = HEAD` 已记录；
+- tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
+- `issue_head = review_head`；
 - issue 已 `resolved`，已满足的 blockers 已解除。

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

@@ -22,12 +22,12 @@ for each layer:
     Verify
     Review
     Finalize
-    issue_head = HEAD
+    issue_head = review_head
 ```
 
 `Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
 
-一个 issue Finalize 完成后立即进入下一个可调度 issue。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
+一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = review_head`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
 
 验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
 
@@ -45,10 +45,10 @@ for each layer:
 其中：
 
 - `issue_base...review_head` 是已完成 Review 的实现范围；
-- `issue_base...issue_head` 是当前 issue 的完整提交范围；
+- `issue_head = review_head`，因此 `issue_base...issue_head` 只包含当前 issue 的 Review Point commit，以及可选的唯一 finding-fix commit；
 - `issue_head` 是下一个 issue 的 `issue_base`。
 
-当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
+当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
 
 ## 冲突与失败
 
@@ -61,5 +61,6 @@ for each layer:
 
 - 所有可执行 issue 均按依赖顺序完成；
 - issue、依赖状态与 progress 一致；
-- 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确；
+- 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确，且每个 issue 最多包含 2 个由本技能产生的实现/Review commits；
+- 仓库内状态同步如有需要，只形成最多 1 个批次 state-sync commit；
 - 不存在被误当作已完成的 blocked issue。

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

@@ -19,10 +19,10 @@
 
 1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
 2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
-3. 将当前 issue 已完成并验证的交付修改提交到当前 branch；
+3. 将当前 issue 已完成并验证的交付修改合并形成当前 issue 唯一的 Review Point commit；不得按 Behavior、阶段或验证动作拆分 commit；
 4. 确认不存在属于当前 issue 交付内容的未提交修改。
 
-一个 issue 可以在这里已有一个或多个 commits。Commit 是 Review artifact，不代表 issue 已完成。
+完整 Review 前每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
 
 完整 Review 使用：
 
@@ -51,32 +51,32 @@
 
 ## 3. 增量 Review
 
-存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。可将由同一改动共同解决的相关 findings 一起处理，不要求“一 finding 一 commit”。
+存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。一次性处理当前全部 open findings，不按 finding 拆分 commit。
 
-每个 issue 最多执行 2 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
+每个 issue 最多执行 1 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
 
-每轮修复前，若 `incremental_review_rounds >= 2` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
+若 `incremental_review_rounds >= 1` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
 
-每轮修复：
+唯一一轮 finding 修复：
 
-1. 修复选定的 open findings；
+1. 一次性修复当前全部 open findings；
 2. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD；否则直接进入受影响证据的重新验证；
-3. 重新验证修复直接影响的证据；
-4. 将本轮修复提交到当前 issue 的 commit range，并确认不存在属于本轮修复的未提交修改；
-5. 只针对 `last_reviewed_head...HEAD` 与本轮目标 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
+3. 重新验证全部修复直接影响的证据；
+4. 将本轮全部修复合并形成最多 1 个 finding-fix commit，并确认不存在属于本轮修复的未提交修改；不得按 finding 拆分 commit；
+5. 只针对 `last_reviewed_head...HEAD` 与现有 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
 
 若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
 
 增量 Review 通过时：
 
-- 仅关闭本轮已由证据确认解决的 findings；
+- 仅关闭已由证据确认解决的 findings；
 - 设置 `last_reviewed_head = HEAD`。
 
-增量 Review 正常完成但未通过时：
+增量 Review 正常完成但仍有 open findings 时：
 
 - 保留未关闭 findings；
 - 不推进 `last_reviewed_head`；
-- 若尚未达到 2 轮上限，下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
+- 停止当前 issue，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
 
 增量 Review 发生技术失败时：
 
@@ -87,13 +87,12 @@
 
 当 `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 实现范围；
+- `incremental_review_rounds <= 1`；
+- `review_head` 指向 Review Point commit，或唯一的 finding-fix commit；
+- `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围，最多包含 2 个由本技能产生的 issue commits；
 - 不存在属于该实现范围的未提交交付修改。

package/README.md

@@ -62,7 +62,7 @@ npx @heihei0299/matt-skills sync --all       # 同步全部可分发 skills
 npx @heihei0299/matt-skills sync --dry-run --json
 ```
 
-`init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`sync --all` 才将其整体刷新为当前分发模板。`sync` 不删除目标项目的额外文件或自定义 skills。
+`init` 对已有 `AGENTS.md` 始终跳过；已有项目使用 `sync`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`--all` 只扩大技能范围。需要显式刷新 `AGENTS.md` 时使用 `sync --refresh-agents`；无受管区块时会先备份为 `AGENTS.md.bak`。`sync` 不删除目标项目的额外文件或自定义 skills。
 
 默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
 
@@ -72,17 +72,19 @@ npx @heihei0299/matt-skills sync --dry-run --json
 npx @heihei0299/matt-skills list [--all] [--json]
 npx @heihei0299/matt-skills install [--all] [--tools <list>] [--global] [--dest <dir>]
 npx @heihei0299/matt-skills init [--all] [--dest <dir>]
-npx @heihei0299/matt-skills sync [--all] [--dry-run] [--json] [--dest <dir>]
+npx @heihei0299/matt-skills sync [--all] [--dry-run] [--refresh-agents] [--dest <dir>]
 npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
 ```
 
 常用选项：
 
-- `--all`：包含全部可分发 skills，默认范围只包含 programming skills。
+- `--all`：包含全部可分发 skills，默认范围只包含 programming skills；不会隐式刷新 `AGENTS.md`。
+- `--refresh-agents`：显式刷新目标 `AGENTS.md`；与 `--all`、`--dry-run` 可组合。
 - `--dest <dir>`：指定目标目录。
 - `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级 skills 统一写入 `.agents/skills/`，全局安装仍使用各工具目录。
 - `--global`：写入用户级 skills 目录。
-- `--dry-run`：只检查差异，不写入；`--json` 输出机器可读结果。
+- `--dry-run`：预演目标项目差异，不写入；`sync --dry-run --json` 输出机器可读结果。
+- `check --json`：输出上游比较的机器可读结果。普通 `sync --json` 不支持。
 
 ## Codex CLI 支持
 
@@ -100,9 +102,11 @@ CODEX_E2E=1 npm run codex:smoke
 非独有 skills 来自 [mattpocock/skills](https://github.com/mattpocock/skills)。
 
 ```sh
-npx @heihei0299/matt-skills sync --dry-run --json  # 检查上游差异
-npx @heihei0299/matt-skills sync                   # 同步默认范围
-npx @heihei0299/matt-skills sync --all             # 同步全部可分发范围
+npx @heihei0299/matt-skills check --json              # 检查上游差异
+npx @heihei0299/matt-skills sync --dry-run --json     # 预演目标项目变化
+npx @heihei0299/matt-skills sync                      # 同步默认范围
+npx @heihei0299/matt-skills sync --all                # 同步全部可分发范围
+npx @heihei0299/matt-skills sync --refresh-agents     # 同步并刷新 AGENTS.md
 ```
 
 ## 发布

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, writeFile, cp, stat, lstat, rm, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile, cp, stat, lstat, rm, mkdir, mkdtemp } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -39,7 +39,7 @@ const HELP_GLOBAL = `matt-skills — install and manage this skill collection
 
 Usage:
   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 sync [--all|--dry-run|--refresh-agents] [--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)
   matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
@@ -57,7 +57,7 @@ Init options:
   --dest <path>   Target directory (default: current directory)
   --all           Include all distributable skills; default only default programming skills
   --help, -h      Show this help
-提示：已有 AGENTS.md 时普通 init 跳过；显式 init --all 刷新模板并覆盖全量可分发 skills。
+提示：已有 AGENTS.md 时 init 始终跳过；需要更新已有项目请使用 sync。
 
 提示：matt-skills --help 查看全量
 `;
@@ -65,16 +65,19 @@ Init options:
 const HELP_SYNC = `matt-skills sync — Sync existing project to latest template + skills
 
 Usage:
-  matt-skills sync [--all|--dry-run] [--dest <path>]
+  matt-skills sync [--all|--dry-run|--refresh-agents] [--dest <path>]
 
 Sync options:
-  --all           仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 AGENTS.md
-  --dry-run       预演：只比对不写盘
-  --dest <path>   Target directory (default: current directory)
-  --help, -h      Show this help
+  --all              同步全部可分发技能；不改变 AGENTS.md 刷新策略
+  --refresh-agents   显式刷新 AGENTS.md；无受管区块时先备份为 AGENTS.md.bak
+  --dry-run          预演目标项目变化，只比对不写盘
+  --json             仅与 --dry-run 一起使用，输出机器可读结果
+  --dest <path>      Target directory (default: current directory)
+  --help, -h         Show this help
   项目 skills：${PROJECT_SKILL_DIRS}
 
-说明：默认不带 --all 增量同步默认 programming skill，并保留现有 AGENTS.md；--all 时同步全部可分发 skill 并强制刷新 AGENTS.md。
+说明：默认同步默认编程 skill 并保留现有 AGENTS.md；--all 只扩大技能范围。
+      --refresh-agents 与 --all、--dry-run 可组合；上游检查请使用 check。
 
 提示：matt-skills --help 查看全量
 `;
@@ -126,6 +129,8 @@ Install options:
 
 const HELP = HELP_GLOBAL;
 
+const DRY_RUN_PATHS = ['AGENTS.md', 'AGENTS.md.bak', '.opencode', '.pi', '.agents/skills', '.claude/skills'];
+
 function parseFrontmatter(text) {
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return {};
@@ -377,7 +382,7 @@ async function initCommand({ dest, all }) {
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
   const onlyProgramming = !all;
-  if (await pathExists(marker) && !all) {
+  if (await pathExists(marker)) {
     process.stdout.write('模板已存在（AGENTS.md），跳过\n');
   } else {
     await cp(TEMPLATE_DIR, target, {
@@ -422,73 +427,124 @@ async function initCommand({ dest, all }) {
   }
   process.stdout.write(`目标路径：${target}\n`);
 }
-async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
+async function copyDryRunInputs(target, stage) {
+  for (const relative of DRY_RUN_PATHS) {
+    const source = path.join(target, relative);
+    if (!await pathExists(source)) continue;
+    const destination = path.join(stage, relative);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await cp(source, destination, { recursive: true, force: true });
+  }
+}
+
+async function compareDryRunTrees(target, stage) {
+  const result = { added: [], updated: [], removed: [] };
+  for (const relative of DRY_RUN_PATHS) {
+    const before = path.join(target, relative);
+    const after = path.join(stage, relative);
+    const beforeExists = await pathExists(before);
+    const afterExists = await pathExists(after);
+    if (!beforeExists && afterExists) result.added.push(relative);
+    else if (beforeExists && !afterExists) result.removed.push(relative);
+    else if (beforeExists && afterExists && !await sameTree(before, after)) result.updated.push(relative);
+  }
+  return result;
+}
+
+function formatTargetComparison({ target, result, onlyProgramming, refreshAgents }) {
+  const lines = [
+    `目标: ${target}`,
+    `范围: ${onlyProgramming ? '默认编程' : '全部可分发'}${refreshAgents ? '；刷新 AGENTS.md' : ''}`,
+    '',
+  ];
+  const totalDiff = result.added.length + result.updated.length + result.removed.length;
+  if (totalDiff === 0) {
+    lines.push('✅ 无需更新');
+    return lines.join('\n');
+  }
+  if (result.added.length) lines.push(`新增 (${result.added.length}): ${result.added.join(', ')}`);
+  if (result.updated.length) lines.push(`更新 (${result.updated.length}): ${result.updated.join(', ')}`);
+  if (result.removed.length) lines.push(`删除 (${result.removed.length}): ${result.removed.join(', ')}`);
+  return lines.join('\n');
+}
+
+async function refreshAgentsFile(targetFile) {
+  const templateFile = path.join(TEMPLATE_DIR, 'AGENTS.md');
+  const current = await readFile(targetFile, 'utf8');
+  const template = await readFile(templateFile, 'utf8');
+  const merged = mergeManagedAgents(current, template);
+  if (merged !== null) {
+    if (merged !== current) await writeFile(targetFile, merged);
+    return 'managed';
+  }
+  await cp(targetFile, `${targetFile}.bak`, { force: true });
+  await cp(templateFile, targetFile, { force: true });
+  return 'full';
+}
+
+async function syncCommand({ dest, all, dryRun, json, refreshAgents, quiet = false }) {
   const onlyProgramming = !all;
+  const output = (text) => {
+    if (!quiet) process.stdout.write(text);
+  };
+  if (!dryRun && json) throw new Error('--json 仅支持 sync --dry-run');
   if (dryRun) {
-    const { compare, formatComparison } = await import('../scripts/sync-upstream.js');
-    const cmp = await compare({ upstreamUrl, ref, onlyProgramming });
-    if (json) {
-      process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
-    } else {
-      process.stdout.write(formatComparison(cmp) + '\n');
+    const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
+    const stage = await mkdtemp(path.join(os.tmpdir(), 'matt-skills-sync-dry-run-'));
+    try {
+      await copyDryRunInputs(target, stage);
+      await syncCommand({ dest: stage, all, dryRun: false, json: false, refreshAgents, quiet: true });
+      const result = await compareDryRunTrees(target, stage);
+      const payload = { target, result, onlyProgramming, refreshAgents };
+      if (json) output(`${JSON.stringify(payload, null, 2)}\n`);
+      else output(`${formatTargetComparison(payload)}\n`);
+      const totalDiff = result.added.length + result.updated.length + result.removed.length;
+      if (totalDiff > 0) process.exitCode = 1;
+    } finally {
+      await rm(stage, { recursive: true, force: true });
     }
-    const { rm } = await import('node:fs/promises');
-    await rm(cmp.dest, { recursive: true, force: true });
-    const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
-    if (totalDiff > 0) process.exitCode = 1;
     return;
   }
 
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
-  // 模板同步：默认模式下过滤 skills，仅同步默认子集
   async function copyTemplateFiltered() {
-    if (!onlyProgramming) {
-      await cp(TEMPLATE_DIR, target, {
-        recursive: true,
-        force: true,
-        filter: shouldCopyTemplatePath,
-      });
-      return;
-    }
-    // Skeleton only; shared Skills are copied from the canonical source below.
-    await cp(path.join(TEMPLATE_DIR, 'AGENTS.md'), path.join(target, 'AGENTS.md'), { force: true });
-    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 (!(await pathExists(marker))) {
-    process.stdout.write('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
-    if (onlyProgramming) await copyTemplateFiltered();
-    else await cp(TEMPLATE_DIR, target, {
+    await cp(TEMPLATE_DIR, target, {
       recursive: true,
       force: true,
       filter: shouldCopyTemplatePath,
     });
-    process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
+  }
+  if (!(await pathExists(marker))) {
+    output('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
+    await copyTemplateFiltered();
+    output(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
   } else {
-    process.stdout.write('同步：检测到现有项目，将增量更新\n');
-    if (all) {
-      await cp(TEMPLATE_DIR, target, {
-        recursive: true,
-        force: true,
-        filter: shouldCopyTemplatePath,
-      });
-      process.stdout.write(`模板：已同步（AGENTS.md 整体刷新、skills：${PROJECT_SKILL_DIRS}）\n`);
+    output('同步：检测到现有项目，将增量更新\n');
+    let agentsManaged = false;
+    let agentsRefreshed = false;
+    let agentsRefreshMode = null;
+    if (refreshAgents) {
+      agentsRefreshMode = await refreshAgentsFile(marker);
+      agentsRefreshed = true;
     } else {
-      let agentsManaged = false;
       try {
         agentsManaged = await syncManagedAgents(marker);
       } 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 (agentsManaged) {
-        process.stdout.write(`模板：已同步（AGENTS.md 受管区块已更新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
-      } else {
-        process.stdout.write(`模板：已同步（AGENTS.md 未受管、skills：${PROJECT_SKILL_DIRS}，已原样保留）\n`);
-      }
+    }
+    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 (agentsRefreshed && agentsRefreshMode === 'managed') {
+      output(`模板：已同步（AGENTS.md 受管区块已刷新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
+    } else if (agentsRefreshed) {
+      output(`模板：已同步（AGENTS.md 已刷新，旧文件备份为 AGENTS.md.bak、skills：${PROJECT_SKILL_DIRS}）\n`);
+    } else if (agentsManaged) {
+      output(`模板：已同步（AGENTS.md 受管区块已更新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
+    } else {
+      output(`模板：已同步（AGENTS.md 未受管、skills：${PROJECT_SKILL_DIRS}，已原样保留）\n`);
     }
   }
-  // 技能同步：--all 仅更新同名可分发技能内容，存在则覆盖，不存在则新增，并更新 AGENTS.md（由上一步已处理）；默认范围为默认 programming，不删多余
+  // --all 只扩大技能范围；同名覆盖、不存在新增，不删除目标中的额外技能。
   const allSkills = await listSkillNames({ onlyProgramming });
   const skillTargets = projectSkillTargets(target);
   const skillsDir = path.resolve(target, PROJECT_DIRS.codex);
@@ -569,20 +625,19 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
     if (await pathExists(piSettings)) {
       const txt = await readFile(piSettings, 'utf8');
       if (txt.includes('.opencode/skills') || txt.includes('../.opencode')) {
-        const { writeFile } = await import('node:fs/promises');
         await writeFile(piSettings, '{}\n');
       }
     }
   } catch {}
   if (cleanedLegacy.length) {
-    process.stdout.write(`迁移清理：${cleanedLegacy.join(', ')} 旧共享副本已移除\n`);
+    output(`迁移清理：${cleanedLegacy.join(', ')} 旧共享副本已移除\n`);
   }
   if (preservedRepoLocal.length) {
-    process.stdout.write(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
+    output(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
   }
   const modeLabel = onlyProgramming ? '默认编程' : '全部可分发';
-  process.stdout.write(`技能：新增 ${installed}、更新 ${updated}（${modeLabel} ${allSkills.length}）\n`);
-  process.stdout.write(`目标路径：${target}\n`);
+  output(`技能：新增 ${installed}、更新 ${updated}（${modeLabel} ${allSkills.length}）\n`);
+  output(`目标路径：${target}\n`);
 }
 
 function parseInitArgs(args) {
@@ -607,8 +662,7 @@ function parseSyncArgs(args) {
   let all = false;
   let dryRun = false;
   let json = false;
-  let upstreamUrl;
-  let ref;
+  let refreshAgents = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--dest') {
@@ -618,20 +672,13 @@ function parseSyncArgs(args) {
     else if (arg === '--all') all = true;
     else if (arg === '--dry-run') dryRun = true;
     else if (arg === '--json') json = true;
-    else if (arg === '--upstream') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--upstream' requires a value`);
-      upstreamUrl = args[++i];
-    } else if (arg.startsWith('--upstream=')) upstreamUrl = arg.slice('--upstream='.length);
-    else if (arg === '--ref') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--ref' requires a value`);
-      ref = args[++i];
-    } else if (arg.startsWith('--ref=')) ref = arg.slice('--ref='.length);
+    else if (arg === '--refresh-agents') refreshAgents = true;
     else if (arg === '--help' || arg === '-h') {} // handled at main
     else if (arg === '--apply') {} // deprecated alias, same as default safe incremental
     else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'sync'`);
     else throw new Error(`unknown argument '${arg}' for command 'sync'`);
   }
-  return { dest, all, dryRun, json, upstreamUrl, ref };
+  return { dest, all, dryRun, json, refreshAgents };
 }
 
 function parseInstallArgs(args) {
@@ -721,15 +768,15 @@ async function main() {
   if (!knownCommands.has(command)) {
     process.stderr.write(`error: unknown command '${command}'\n`);
     process.stderr.write(`Run 'matt-skills --help' for usage.\n`);
-    process.exitCode = 1;
+    process.exitCode = 2;
     return;
   }
   if (command === 'list') {
     // list strict: only --all/--json/--help allowed, rest handled via parse but we keep simple
     for (const a of rest) {
       if (a === '--all' || a === '--json' || a === '--help' || a === '-h') continue;
-      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 1; return; }
-      process.stderr.write(`error: unknown argument '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 1; return;
+      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 2; return; }
+      process.stderr.write(`error: unknown argument '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 2; return;
     }
     const onlyProgramming = !rest.includes('--all');
     const skills = await listSkills({ onlyProgramming });
@@ -759,21 +806,30 @@ async function main() {
     for (let i = 0; i < rest.length; i++) {
       const a = rest[i];
       if (a === '--all' || a === '--json' || a === '--help' || a === '-h') continue;
-      if (a === '--upstream' || a === '--ref') { i++; continue; }
+      if (a === '--upstream' || a === '--ref') {
+        if (i + 1 >= rest.length || rest[i + 1].startsWith('-')) {
+          process.stderr.write(`error: option '${a}' for command 'check' requires a value\n`);
+          process.stderr.write(`Run 'matt-skills check --help' for usage.\n`);
+          process.exitCode = 2;
+          return;
+        }
+        i++;
+        continue;
+      }
       if (a.startsWith('--upstream=') || a.startsWith('--ref=')) continue;
-      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 1; return; }
-      process.stderr.write(`error: unknown argument '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 1; return;
+      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 2; return; }
+      process.stderr.write(`error: unknown argument '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 2; return;
     }
     await checkCommand(rest);
     return;
   }
   if (command === 'update') {
     process.stderr.write('update 已合并到 sync（默认即增量同步）\n');
-    process.exitCode = 1;
+    process.exitCode = 2;
     return;
   }
 }
 main().catch((error) => {
   process.stderr.write(`error: ${error.message}\n`);
-  process.exitCode = 1;
+  process.exitCode = 2;
 });

package/package.json

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

package/template/AGENTS.md

@@ -1,3 +1,4 @@
+<!-- matt-skills:managed:start -->
 # AGENTS.md
 
 ## Workflow
@@ -75,3 +76,4 @@ codegraph node "<符号>"
 ## Completion
 
 完成时说明改动或审查结论、已执行验证、未执行验证及原因、剩余风险；如有 commit，报告 commit hash。
+<!-- matt-skills:managed:end -->