@heihei0299/matt-skills 2.0.2 → 2.1.2

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

@@ -1,13 +1,13 @@
-# 四阶段详细定义
+# 三阶段详细定义 + Finalize
 
-单 `spec` / 单 `task` 与多 `task` 共用下表四阶段。多 issue 的依赖图、Kahn 分层、层收敛、全量收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
+单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、全量收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
 
 ## 目录
 
 - [① Contract：明确交付契约](#阶段-①-contract明确交付契约)
 - [② Red-Green：行为级 TDD](#阶段-②-red-green行为级-tdd)
 - [③ Verify：最终验证与审查](#阶段-③-verify最终验证与审查)
-- [④ Deliver：提交与 Tracker 收尾](#阶段-④-deliver提交与-tracker-收尾)
+- [Finalize：非阶段交付收尾](#finalize非阶段交付收尾)
 - [跨阶段运行纪律](#跨阶段运行纪律)
 - [状态统一](#状态统一)
 - [回退路由](#回退路由)
@@ -21,12 +21,12 @@
 2. 产品实现之前存在有效 Red；
 3. 最终 diff 对应的相关测试和 typecheck 通过；
 4. ticket 要求真实运行时，真实运行验证已完成；
-5. Standards 与 Spec Review 无 blocking finding；
+5. 当前稳定 diff 已完成一次 `code-review` 且无 blocking finding；
 6. README/docs 与实现一致；
 7. 每个 issue 形成独立、可追溯的 commit；
 8. Tracker 状态与真实完成度一致。
 
-Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通过，issue 才能标记为 `resolved`。
+Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finalize 全部通过，issue 才能标记为 `resolved`。
 
 
 ## 阶段 ① Contract：明确交付契约
@@ -58,11 +58,10 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 5. 完成一次 **Preflight** 并记录真实结果：
    - 当前 `HEAD`、工作区状态和 `BASE_HEAD=$(git rev-parse HEAD)`；
    - 可用的 test、typecheck、build 命令；
-   - 可用的 subagent model；
+   - `code-review` 可用性；
    - 可用的 browser 或 Playwright 路径；
-   - 可用的敏感信息扫描脚本；
    - ticket 要求的真实运行验证方式。
-6. 建立一次验证矩阵，列出 targeted tests、typecheck、全量测试、必要 build、smoke/package/security check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
+6. 建立一次验证矩阵，列出 targeted tests、typecheck、全量测试、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
 7. 识别公共测试边界和 Behaviors。一个 Seam 是一个公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 Seam 可以包含多个 Behaviors。每个 Behavior 明确输入、可观察输出、对应 Acceptance Criterion 和验证层级。
 8. spec 已确认且未变化的 Seam 直接复用；只有出现需求歧义、验收缺口、范围变化、破坏性操作或互斥方案时才请求用户确认。
 
@@ -137,7 +136,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 当前 issue 影响范围测试
 → 必要 build
 → 必要真实运行验证
-→ 一次 Standards + Spec Review
+→ 当前稳定 diff 调用一次 code-review
 → 修复 blocking finding 后的定向复核
 ```
 
@@ -150,46 +149,36 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 
 ### Review
 
-1. 每个 issue 恰好执行一次正式双轴 review：
-   - **Standards**：是否符合仓库规则和代码质量要求；
-   - **Spec**：是否逐条满足当前 issue 的 Acceptance Criteria。
-2. 两个轴独立输出、互不掩盖；每个轴明确限制输出，例如 `≤ 400 words / ≤ 40 行`。
-3. findings 分类为：当前 issue blocking、后续 ticket、advisory、out of scope。只处理当前 issue blocking finding；其余记录而不扩大范围。
-4. 修复 blocking finding 后只运行受影响测试、typecheck 和 finding 的 delta recheck，不重新启动完整双轴 review。审查结果只在对话输出，不生成 `review-*.md` 等书面报告文件。
+1. 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。
+2. `tdd-implement` 只负责 **何时调用 review**；审查维度、reviewer 数量、提示词、上下文与输出格式全部以 `code-review` 为唯一事实源，不在这里复制或弱化。
+3. `code-review` 未完成或存在 blocking finding 时，issue 保持未完成。只修当前 issue blocking finding；其余 findings 按 `code-review` 的分类与输出处理，不无记录地扩大范围。
+4. 修复 blocking finding 后，只运行受影响测试/typecheck 与 finding delta recheck，不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
+5. Review 结果只在对话/运行记录中消费，不由 `tdd-implement` 额外生成自己的 review 报告格式。
 
 ### 出口条件
 
 - 最终 diff 对应的相关测试通过；
 - 必要 typecheck/build 通过；
 - ticket 要求的真实运行验证已完成并记录实际结果；
-- 一次 Standards + Spec Review 已完成；
+- 当前稳定 diff 已完成一次 `code-review`；
 - 无 blocking finding；
 - 受影响范围的最后一次证据对应当前 diff。
 
 ---
 
-## 阶段 ④ Deliver：提交与 Tracker 收尾
+## Finalize：非阶段交付收尾
 
 ### 入口条件
 
 - Verify 出口条件满足。
 
-### Commit 前门禁
+### Commit
 
-按以下顺序完成并记录事实：
+1. 如本次实现要求 README/docs/config/package 同步，完成必要更新。
+2. 按当前 issue 范围直接创建一个独立 commit。
+3. 不执行额外敏感信息/安全扫描，不做 `git diff --cached` 复核，也不设置额外 commit message 门禁。
 
-1. 最终逐条检查 Acceptance Criteria；
-2. 检查 README/docs/config/package 与实现一致；
-3. 复核 Scope Ledger，确认没有未记录的范围扩张；
-4. 确认证据对应最后一次代码或测试修改；
-5. 检查临时文件、构建产物和未跟踪文件；
-6. 对 staged diff 执行敏感信息检查；
-7. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；
-8. 检查 commit message；
-9. 确认暂存区只包含当前 issue；
-10. 执行 `git diff --cached`，再创建当前 issue 的独立 commit。
-
-执行敏感信息扫描脚本（`bash .agents/skills/commit-check/scripts/scan-sensitive.sh --staged-only`），检查 staged diff、commit message 和 Git history preservation，全部通过后创建当前 issue 的独立 commit。
+仓库级 Git 安全与历史保护规则仍然适用；Finalize 不重复定义或扩展这些规则。
 
 ### Tracker 收尾
 
@@ -200,19 +189,16 @@ Commit 成功后：
 - 追加实施总结；
 - 更新 `.scratch/<feature>/progress.md` 的 `Status`、`Commit`、`Review`、`Tests`；
 - 记录 commit hash、message、最终测试命令/数量/结果和真实运行结果；
-- 清理本次产生的临时进程、目录和一次性文件；
 - 确认下一 issue 的 blockers 已解除。
 
-阶段 ④ 开始后不新增产品 Behavior。若实现、测试或文档不完整，回到对应阶段；不要在 Tracker 收尾后继续修改源码，也不要通过额外 docs-only commit 掩盖遗漏。只有四个阶段全部通过，才可把 issue 标记为 `resolved`。
+Finalize 开始后不新增产品 Behavior。若实现、测试或文档不完整，回到对应阶段；只有三个阶段与 Finalize 全部通过，才可把 issue 标记为 `resolved`。
 
 ### 出口条件
 
 - commit 已创建且为当前 issue 的独立提交；
 - Acceptance Criteria 全部通过；
 - issue 状态为 `resolved`（无关联 issue 的直接 spec 则在会话中输出总结）；
-- 实施总结和 `progress.md` 已同步；
-- 工作区符合预期，无本次临时产物或残留未跟踪文件；
-- 文档与实现一致，Git 历史保护校验通过。
+- 实施总结和 `progress.md` 已同步。
 
 ---
 
@@ -231,7 +217,7 @@ Commit 成功后：
 
 ### 验证证据失效
 
-任何产品代码或测试文件再次变化，旧的测试、typecheck、build 和 review 证据立即失效；必须重新验证受影响范围。只能使用最后一次修改之后的结果证明当前 diff 已完成。
+任何产品代码或测试文件再次变化，旧的测试、typecheck、build 等受影响证据立即失效，必须重新验证受影响范围。正式 `code-review` 调用本身不因 finding 修复而重复；post-review 修复必须完成受影响验证和 finding delta recheck。若修改引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
 
 ### Git History Preservation
 
@@ -253,7 +239,7 @@ Issue:    ready-for-agent | in_progress | resolved | blocked
 Progress: pending | in_progress | done | blocked
 ```
 
-状态转换：Contract 完成后 Issue/Progress 为 `in_progress`；Red-Green 完成后 Behaviors 为 `completed`，Issue 仍为 `in_progress`；Verify 完成后 Issue 仍为 `in_progress`；Deliver 完成后 Issue 为 `resolved`、Progress 为 `done`。外部阻塞记录为 `blocked`，恢复后回到 `in_progress`。
+状态转换：Contract 完成后 Issue/Progress 为 `in_progress`；Red-Green 完成后 Behaviors 为 `completed`，Issue 仍为 `in_progress`；Verify 完成后 Issue 仍为 `in_progress`；Finalize 完成后 Issue 为 `resolved`、Progress 为 `done`。外部阻塞记录为 `blocked`，恢复后回到 `in_progress`。
 
 ---
 
@@ -264,6 +250,6 @@ Progress: pending | in_progress | done | blocked
 | ① Contract | 需求歧义、验收缺口、范围变化 | → ① 补充契约和验证矩阵 |
 | ② Red-Green | 有效 Red、实现、formatter、typecheck 或相关测试失败 | → ② 修复当前 Behavior |
 | ③ Verify | 测试、build、真实运行或 review finding 失败 | → ② 修复 Behavior；需求偏差 → ① |
-| ④ Deliver | docs、敏感扫描、staged diff、commit message 或 Tracker 信息不完整 | → ①/③ 修复对应证据；仍在 Deliver 前完成 |
+| Finalize | 必要 docs 未同步、commit 失败或 Tracker 信息不完整 | → ①/③ 修复对应问题；仍在 Finalize 完成前解决 |
 
 多 issue 的层收敛、全量失败、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。

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

@@ -0,0 +1,24 @@
+# Verify
+
+仅在 `tdd-implement` Step ③ 读取。验证必须对应当前最终 diff；产品代码或测试再次变化时，测试/typecheck/build 等受影响证据失效。
+
+## 固定顺序
+
+`影响范围测试 → 必要 build → 必要真实运行验证 → code-review 一次 → blocking 修复后的定向复核`
+
+## 规则
+
+- 单 issue / 单 spec：按 Contract 验证矩阵运行完整相关测试；多 issue：只跑当前 issue 影响范围，全仓测试留给 orchestration A4。
+- ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
+- 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
+- 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。`tdd-implement` 只规定调用时机；审查维度、reviewer 数量、提示词、上下文与输出格式以 `code-review` 为唯一事实源。
+- `code-review` 未完成或返回 blocking finding 时，issue 保持未完成；只修当前 issue 的 blocking finding，其余按 review 结果记录。
+- 修复 blocking finding 后，只重跑受影响测试/typecheck 并对该 finding 做 delta recheck；不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
+
+## 出口
+
+- 最终 diff 的相关测试/typecheck/build 通过；
+- 要求的真实运行验证有实际证据；
+- 当前稳定 diff 已完成一次 `code-review`；
+- 无 blocking finding；
+- post-review 修复（如有）的受影响验证与 finding delta recheck 已完成。

package/README.md

@@ -1,6 +1,6 @@
 # matt-skills
 
-mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓库：工作区内容镜像为 `template/` 模板快照，以 npm 包 `@heihei0299/matt-skills` 分发，目标仓库一条命令即完成初始化。
+mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓库：工作区维护完整 skill 集合，其中一部分 proprietary skill 只供本仓库使用；`template/` 只包含可分发内容，以 npm 包 `@heihei0299/matt-skills` 分发，目标仓库一条命令即完成初始化。
 
 ## 模板结构
 
@@ -8,7 +8,7 @@ mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓
 template/
 ├── AGENTS.md         项目级全局配置（行为路由 + 分文件指针）
 ├── .agents/
-│   └── skills/       33 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test；另含 show-me）单一源；模板全量 33，默认安装编程相关 26（engineering 18 + 独有所需 1 + 核心独有 4，见 config/engineering.json 与 config/required.json），--all 展开全量
+│   └── skills/       workspace 的完整 skill 单一源；template 只携带可分发 skill，默认安装 programming 范围，--all 展开全部可分发 skill
 ├── .pi/              pi-agent 项目配置
 │   ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
 │   ├── prompts/      issue-audit 命令（prompt template）
@@ -17,39 +17,60 @@ template/
 └── .opencode/        opencode 项目配置
     ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
     ├── agents/       issue-audit 子代理定义
-│    ├── commands/     issue-audit + 10 个显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents/commit-check）
+    ├── commands/     issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
     ├── docs/agents/  5 个分文件（运行时纪律 / 技能设计 / issue tracker / triage labels / domain）
     ├── CONTEXT.md    术语表
     ├── package.json  插件依赖清单
     └── .gitignore
 ```
 
+## 独有 skill 分发边界
+
+本仓库维护 7 个独有（proprietary）skill：
+
+### 可分发的 5 个
+
+- `tdd-implement`
+- `diagnose-fix`
+- `grill-to-spec`
+- `scaffold-functional-test`
+- `show-me`
+
+默认 programming 范围中的 4 个独有 skill 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`；`scaffold-functional-test` 可分发但默认可选。
+
+### 仓库内部的 2 个
+
+- `ci-guard`
+- `commit-check`
+
+`ci-guard` 和 `commit-check` 只服务 matt-skills 仓库自身，不会通过 `list`、`install`、`init`、`sync`、`--all` 或 global install 分发到用户项目。workspace 保留完整集合，template 只包含可分发集合。
+
 ## 初始化
 
 在目标仓库根目录执行一条命令：
 
 ```sh
-npx @heihei0299/matt-skills init              # 默认编程相关 26（engineering 18 + 独有所需 4 + 核心独有 4），--all 展开全量 33
-npx @heihei0299/matt-skills init --all       # 安装全量 33（含 productivity）
+npx @heihei0299/matt-skills init              # 默认 programming 范围
+npx @heihei0299/matt-skills init --all       # 安装全部可分发 skill（含 productivity）
 ```
 
-`init` 默认只在目标没有 `AGENTS.md` 时初始化；已有项目默认跳过以保护定制，显式 `init --all` 会刷新模板并安装/覆盖全量 33 个 skill。模板全量 33，默认仅安装默认范围 26（engineering 18 + 独有所需 4 + 核心独有 4，见 config/engineering.json 与 config/required.json），无需二次拉取上游。
+`init` 默认只在目标没有 `AGENTS.md` 时初始化；已有项目默认跳过以保护定制，显式 `init --all` 会刷新模板并安装/覆盖全部可分发 skill。模板已经包含可分发内容，无需二次拉取上游；repo-local skill 不会进入目标项目。
 
-选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含非编程技能（productivity，默认编程 26：engineering 18 + 独有所需 4 + 核心独有 4）；已有目标使用 `init --all` 刷新，普通 `init` 跳过。
+选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发的非默认 skill（包括 productivity 和 optional proprietary）；已有目标使用 `init --all` 刷新，普通 `init` 跳过。
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync                                 # 默认安全增量：AGENTS.md 有定制则跳过，默认技能 26 rm+cp（不删多余）
-npx @heihei0299/matt-skills sync --all                           # 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 AGENTS.md（不跳过定制），不删多余
-npx @heihei0299/matt-skills sync --dry-run --json                # 预演：只比对不写盘（默认范围，--all 全量可透传）
+npx @heihei0299/matt-skills sync                                 # 默认安全增量：同步默认 programming skill（不删多余）
+npx @heihei0299/matt-skills sync --all                           # 同步全部可分发 skill（不删多余）
+npx @heihei0299/matt-skills sync --dry-run --json                # 预演：只比对不写盘（默认范围，--all 可透传）
 npx @heihei0299/matt-skills sync --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`sync` 专为已有项目设计，两档语义：`--dry-run` 仅对比不写盘（默认范围 engineering + 独有所需，`--all` 展开全量同名集合，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；默认安全增量写盘（`AGENTS.md` 若含 `tdd-implement` 则跳过，`.agents/skills` 按默认范围 26 `rm+cp` 覆盖但不删多余，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留共享技能自动清理但保留项目自定义）；`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余。`--dest`、`--upstream`、`--ref`、`--json`、`--all`、`--dry-run` 可透传。
-目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 26，`--all` 全量 33）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；10 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
-**pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
+`sync` 专为已有项目设计，两档语义：写盘模式下默认同步默认 programming 范围，`--all` 同步全部可分发 skill；`--dry-run` 仅对比上游、不写盘，默认比较 engineering + required 的上游部分，`--all` 比较全量上游范围，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`。上游 dry-run/check 不比较 proprietary，因为它们不属于上游；默认安全增量写盘不删多余，模板配置增量更新，旧镜像中的共享 skill 自动清理但保留项目自定义。repo-local skill 永远不新增、不覆盖、不删除，发现历史副本时只提示保留。`--dest`、`--upstream`、`--ref`、`--json`、`--all`、`--dry-run` 可透传。
+目标仓库会话即自动加载可分发共享技能（`.agents/skills/` 单一源）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；可分发的显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
+**pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部可分发共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
 
-**手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全量技能）：
+**手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全部可分发 skill）：
 
 ```sh
 cp -r template/. /path/to/target/
@@ -67,9 +88,9 @@ git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-ski
 
 | 工作区 | 模板 |
 |--------|------|
-| `.agents/skills/`（全部 33 个：上游 26 + 独有 7：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test、show-me） | `template/.agents/skills/`（全量快照，单一源） |
+| `.agents/skills/`（workspace 完整 skill 集合：upstream + proprietary） | `template/.agents/skills/`（仅可分发 skill） |
 | `.agents/skills/` 的 harness 占位说明 | `template/.pi/skills/.gitkeep` + `README.md`、`template/.opencode/skills/.gitkeep` + `README.md`（空目录占位，供项目自定义） |
-│   │   ├── commands/     issue-audit + 10 个显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents/commit-check）
+│   │   ├── commands/     issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
 | `.pi/prompts/issue-audit.md`（pi 命令：opencode 版适配，去 subagent frontmatter） | `template/.pi/prompts/issue-audit.md` |
 | `AGENTS.md` | `template/AGENTS.md`（引用映射为 `.opencode/` 路径） |
 | `CONTEXT.md` | `template/.opencode/CONTEXT.md` + `template/.pi/CONTEXT.md` |
@@ -78,7 +99,7 @@ git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-ski
 共享技能统一在 `.agents/skills` 单一源，不再双份镜像到 `.opencode/skills` / `.pi/skills`。
 `test/template-sync.test.js` 守护同步（含路径映射），漏同步测试即红。
 
-新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为独有技能落在本仓库（当前独有：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test），上游技能通过 `scripts/sync-upstream.js` 同步到 `.agents/skills` 后随模板分发。
+新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为 proprietary skill 落在本仓库。Proprietary skill 再分为 distributable 和 repo-local：后者只服务本仓库，不进入 template 或任何用户安装路径。上游技能通过 `scripts/sync-upstream.js` 同步到 `.agents/skills` 后，只有可分发内容会进入模板。
 
 ## harness 支持
 
@@ -119,13 +140,13 @@ CODEX_E2E=1 npm run codex:smoke             # 显式运行真实 smoke test
 
 - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
 - **项目**：
-  - `.agents/skills/` — 共享技能单一源（默认编程 26，`--all` 全量 32，自动发现）
+  - `.agents/skills/` — 可分发共享技能单一源（默认 programming，`--all` 全部可分发，自动发现）
   - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
   - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
   - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
 ### opencode
 
-- **项目**：`.agents/skills/`（共享技能单一源，默认编程 26，`--all` 全量 33）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 10 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
+- **项目**：`.agents/skills/`（可分发共享技能单一源，默认 programming，`--all` 全部可分发）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 可分发显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
 
 同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
 
@@ -134,23 +155,23 @@ CODEX_E2E=1 npm run codex:smoke             # 显式运行真实 smoke test
 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
 
 ```sh
-node bin/cli.js init [--dest <dir>] [--all]                               # 初始化项目：template 全量 33，默认编程 26
+node bin/cli.js init [--dest <dir>] [--all]                               # 初始化项目：默认 programming 或全部可分发 skill
 node bin/cli.js sync [--all] [--dry-run] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新（默认编程，--all 仅同名 upsert + AGENTS.md）
 node bin/cli.js list [--json] [--all]                                            # 列出技能（默认编程）
 node bin/cli.js install [选项]                                                 # 把技能复制到目标工具目录（交互式选择，默认编程）
 node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync --dry-run，默认范围）
 ```
 
-`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含非编程（productivity，默认编程 26：engineering 18 + 独有所需 1 + 核心独有 4），见「初始化」。
-`sync` 选项：`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余；`--dry-run` 预演（只比对不写盘，`--json` 可解析，有差异 `exit 1`）；`--all` 展开同名全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认即安全增量（`AGENTS.md` 有定制则跳过）。
-`check` 选项：`--json`、`--all`（默认范围：engineering + 独有所需）、`--upstream <url>`、`--ref <ref>`（等价 `sync --dry-run`）。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发 skill，见「初始化」。
+`sync` 选项：写盘时 `--all` 更新全部可分发同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余；默认写盘只同步默认 programming；`--dry-run` 只比对上游、不写盘（默认 engineering + required 上游范围，`--all` 为全量上游范围，`--json` 可解析，有差异 `exit 1`）；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认安全增量会保留目标定制。
+`check` 选项：`--json`、`--all`（默认只比较 engineering + required 上游范围；proprietary 不参与上游 compare）、`--upstream <url>`、`--ref <ref>`（等价 `sync --dry-run`）。
 
 `install` 选项：
 
 - `--dest <dir>`：复制到指定目录（覆盖工具映射）
 - `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
 - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
-- `--all`：安装全部技能（默认编程 26，`--all` 33，交互勾选时仅列默认范围）；`--force`：覆盖已存在的技能
+- `--all`：安装全部可分发 skill（交互勾选时默认只列 programming 范围）；`--force`：覆盖已存在的技能
 
 
 ### 上游同步（自动更新）
@@ -160,14 +181,14 @@ node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]
 - **本地 CLI**：`matt-skills sync` 两档——`--dry-run` 只读比对（有差异 `exit 1`，`--json` 可解析）、默认安全增量与 `sync --all` 仅同名 upsert + `AGENTS.md`；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 为只读别名（等价 `sync --dry-run`）；`matt-skills update` 已合并到 `sync`（执行提示 `update 已合并到 sync` 且 `exit 1`）
 ```sh
 npx @heihei0299/matt-skills sync --dry-run --json              # 预演只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
-npx @heihei0299/matt-skills sync                               # 默认安全增量（AGENTS.md 定制跳过，默认技能 26）
+npx @heihei0299/matt-skills sync                               # 默认安全增量（AGENTS.md 定制跳过，默认 programming）
 npx @heihei0299/matt-skills sync --all                         # 仅同名 upsert + AGENTS.md
 npx @heihei0299/matt-skills check --json             # 等价 sync --dry-run
 node scripts/sync-upstream.js --check               # 等价底层脚本（CLI sync/check 的实现）
 node scripts/sync-upstream.js --apply --dry-run
 ```
 
-实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单 + `config/required.json` 为独有所需白名单（当前仅 grilling：grill-to-spec 经 grill-with-docs 所需，属 productivity 但默认同步；其余 productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
+实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 proprietary 分类契约排除本仓库独有 skill，以 `config/engineering.json` 为编程白名单，以 `config/required.json` 为独有所需白名单；上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除。上游同步只维护 workspace，模板生成时再按 distributable 边界投影。
 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
 ## 发布
 
@@ -200,7 +221,7 @@ npm publish
 
 ```sh
 npm test                          # 全量测试
-npm run build:template            # 从单源生成 template/.agents/skills（全量 33 技能）+ 空占位
+npm run build:template            # 从 workspace 生成仅含可分发 skill 的 template + 空占位
 ```
 
 交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。