@heihei0299/matt-skills 1.3.2 → 1.5.2

package/.agents/skills/ci-guard/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ci-guard
+description: "Guard the GitHub Actions release pipeline: orchestrate workflow flow, enforce pre-release verification, and self-correct after publish. Use when CI is flaky/failing, when setting up or editing .github/workflows/ci.yml, or before tagging a release to npm."
+---
+
+# CI Guard
+
+**guard** 为领衔词的发布门禁技能：以一次**可复现的失败**为起点，把 `verify → build → publish` 编排成不可绕过的门，把**预发布校验**做成硬门槛，把**发布后自纠**做成闭环。本技能沉淀自 `heihei0299/pi-switch` 23 次运行中 14 次失败的复盘（见 `.scratch/research/ci-actions-调研.md`）——不替代 `diagnose-fix` 的通用诊断，只收敛 CI/发布这一条链。
+
+## 何时用
+
+- Actions 持续红 / 偶发红（尤其是 `verify` 单点红而 `publish` 仍绿）
+- 新建或改动 `.github/workflows/ci.yml`、调整 `cargo test` / `clippy` / `rustfmt` 参数
+- 打 tag 前、发 npm 前、或发布后需要自检/回滚
+
+## 三段式门禁
+
+```
+① 编排 flows → ② 预发布 gate → ③ 发布后自纠
+```
+
+每段有**完成条件**（可验证），未满足不进入下一段。
+
+---
+
+### ① 编排 flows —— 让工作流不可被绕过
+
+**做**：
+- `on`：`push.tags: ["v*"]` **必须**同时配 `push.branches: [main]`（或 `master`）+ `pull_request.branches: [main]` + `workflow_dispatch`。否则直推 `main` 的修复（如 `2d68f62`）无法被 CI 验证，tag 才暴露问题
+- `jobs` 依赖：`publish.needs: [build, verify]`，**禁止** `needs: build` 单依赖。门禁失效的直接原因就是 `verify` 红仍发包
+- `permissions` 最小化：`verify`/`build` 只需 `contents: read`，仅 `publish` 保留 `contents: write` + `packages: write`（或 `id-token: write` 若用 OIDC）
+- `concurrency`：`group: ci-${{ github.ref }}` + `cancel-in-progress: true`，避免同分支并行互踩
+
+**完成条件**：
+- [ ] `git diff HEAD -- .github/workflows/ci.yml` 显示 `on.push.branches` 存在
+- [ ] `publish.needs` 包含 `verify`
+- [ ] `workflow_dispatch` 可手动触发全量
+
+---
+
+### ② 预发布 gate —— 测试 GitHub Action 流程
+
+本段是**硬门槛**，顺序固定：`action lint → workflow dry-run → dispatch 验证`，任一步红即阻断 `publish`。
+
+**action lint**：
+- `actionlint` 校验 `.github/workflows/ci.yml` 语法与 `on/needs/permissions` 完整性
+- `yamllint` 检查缩进与重复键
+
+**workflow dry-run**：
+- `act --dry-run` 或 `gh workflow view` 模拟 `verify/build/publish` 三 job 依赖与 `if` 条件
+- 校验 `publish.needs` 含 `verify` 且 `workflow_dispatch` 可手动触发
+
+**dispatch 验证**：
+- 通过 `gh workflow run ci.yml --ref main -f dry_run=true` 触发试运行，观察 `verify` 日志与产物上传
+- 失败即阻断 `publish`，日志留存于 Actions
+
+**完成条件**：
+- [ ] `actionlint` 0 error
+- [ ] `act --dry-run` 三 job 依赖正确
+- [ ] `workflow_dispatch` 试运行通过
+
+---
+
+### ③ 发布后自纠 —— 发出去的包自己负责
+
+**发布时**：
+- `npm publish --access public` 仅在 `if: startsWith(github.ref, 'refs/tags/v')` 且 `needs` 全绿时执行
+- 发布前 `actions/download-artifact` 校验 `if-no-files-found: error`，发布后 `npm view <pkg>@<version> version` 回读确认
+
+**自纠**：
+- 失败即 **阻断**：`verify` 红 → `publish` 不执行（由 `needs` 保证）；`publish` 自身失败（`409 already exists` / `401`）→ 工作流整体 `failure`，不静默
+- 发布后 30s 内 `curl https://registry.npmjs.org/<pkg>/<version>` 校验可用；失败则 `gh issue create --title "chore(release): vX.Y.Z 发布后自检失败" --body "run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"` 并 `gh release delete vX.Y.Z --yes`（或 `npm unpublish <pkg>@<version>` 在 72h 内）
+- `workflow_dispatch` 支持 `inputs.rollback_version` 手动回滚
+
+**完成条件**：
+- [ ] `npm view` 回读与 tag 一致
+- [ ] 失败路径有 issue/通知（非静默）
+- [ ] `git tag` 与 `package.json version` 一致（`scripts/release.sh` 或 `npm version` 保证）
+
+---
+
+## 反模式
+
+- **单依赖 publish**：`needs: build` 是本仓 7 次带病发布的根因
+- **仅 tag 触发**：`push.branches` 缺失导致主干修复无 CI
+- **静默发布**：`publish` 失败不建 issue / 不删 tag，下次 `409` 叠加
+- **`-A clippy::all`**：掩盖真实告警
+
+## 引用
+
+- 调研：`.scratch/research/ci-actions-调研.md`（23 次运行全量、`proxy.rs:115` vs `config.rs:460` 对比）
+- 修复：`2d68f62 fix(ci): gate publish on verify and serialize Rust tests`
+- 关联技能：`diagnose-fix`（通用诊断）、`commit-check`（提交前门禁）、`tdd`（测试隔离后的回归）
+

package/.agents/skills/ci-guard/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "CI Guard"
+  short_description: "Guard release pipeline: orchestrate flows, enforce verify gate, self-correct after publish"
+policy:
+  allow_implicit_invocation: false

package/.agents/skills/commit-check/SKILL.md

@@ -5,35 +5,32 @@ description: "Run the pre-commit gate before any commit: verify docs match the i
 
 # Commit Check
 
-提交前的**门禁检查**：审查文档 → 对齐 README → 保持目录卫生 → 规范 commit message，四项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
+提交前的**门禁检查**：文档一致性 → 保持目录卫生 → 规范 commit message，三项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
 
-## 四项检查（全部通过才 commit）
+## 三项检查（全部通过才 commit）
 
-### ① 审查文档
+### ① 文档一致性
+> 覆盖原 ① 审查文档 的全部检查项与原 ② 对齐 README 的全部检查项
 
 - 本次改动涉及的行为/接口/配置/命令是否有对应文档（README、`docs/`、技能正文）描述
 - 文档描述与实现一致：无过期信息、无声称未实现的功能、无遗留的旧接口描述
-- 涉及技能/模板/配置改动时，检查正文引用的路径与实际一致（如相对路径、目录结构）
 - 发现不一致 → 先修文档（或更新实现），再进入下一步
-
-### ② 对齐 README
-
 - 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
 - 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
 - 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
-- **特例：skill 与 AGENTS.md 的模板同步增量**：若 `git diff HEAD` 仅涉及 `AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + `.agents/skills/`/`.pi/skills/`/`.opencode/skills/` 的技能文件 + `.gitignore` 的 `.pi/` 忽略，且同目录存在 `AGENTS.md.bak`（模板同步 `sync`/`init --force` 的备份），视为模板同步的预期增量，禁止自动 `checkout -- AGENTS.md` 回滚；存在性按文件系统判（`ls .agents/skills/<name> .pi/skills/<name> .opencode/skills/<name>` 任一存在即算存在，不以 `git ls-files` 为准）；缺技能则正向补齐而非回滚文档
-
-### ③ 保持目录卫生
+- **特例**：`AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + 技能文件 + `.gitignore` 的 `.pi/` 忽略，且存在 `AGENTS.md.bak` 时，视为模板同步预期增量，不回滚
+### ② 保持目录卫生
 
 - `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
-- 清理本次改动产生的临时文件（一次性脚本、转储、探针）——仅删本次产生的未跟踪临时产物，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4
+- 无关文件（一次性脚本、转储、探针、调试日志）直接追加至 `.gitignore`，不执行删除；仅对本次产生的 `[DEBUG-...]` 临时产物做受控清理，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4
 - 若本次会话记录了 `BASE_HEAD`，commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才提交
 - 确认没有敏感信息进入改动（密钥、token、`.env`、私钥）——跑 `scripts/scan-sensitive.sh`，不用手写扫描
 - 提交后工作区应为干净状态（`git status` 无输出）
 
-### ④ 规范 commit message
+### ③ 规范 commit message
 
 - 格式遵循仓库约定（常见：`<type>(<scope>): <subject>`，type 用 feat/fix/docs/chore/refactor/test）
+> 模板：`feat(<scope>): <subject>` / `fix(<scope>): <subject>` — 例 `feat(tdd): add seam login`，`fix(ci): gate publish on verify`
 - subject 描述变更内容而非过程（不说"我做了什么"，说"改成了什么"）
 - 需要时补充 body：动机、影响范围、验收证据（测试结果、同步确认）
 - 一次 commit 只含一个逻辑变更；多主题拆多个 commit
@@ -42,24 +39,22 @@ description: "Run the pre-commit gate before any commit: verify docs match the i
 
 - 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
 - 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
-- 不顺手重构：只检查与本次改动直接相关的内容，不扩权到无关文档/目录
 - 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
 
 ## 执行顺序（回合内串行）
 
-1. 跑 ① 审查文档 → ② 对齐 README → ③ 保持目录卫生 → ④ 写 commit message
+1. 跑 ① 文档一致性 → ② 保持目录卫生 → ③ 写 commit message
 2. 任一项发现问题：修复后重跑该项，全部通过才 commit
 3. commit 后确认 `git status` 干净，工作结束
 
-**回合连续性**：四项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到四项全过或遇到外部阻塞（权限/授权缺失）。
+**回合连续性**：三项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到三项全过或遇到外部阻塞（权限/授权缺失）。
 
 ## 出口条件
 
-- [ ] 文档审查通过（无过期/不一致描述）
-- [ ] README 对齐（涉及结构/分发改动时已同步）
+- [ ] 文档一致性（文档与 README 均已对齐）
 - [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
 - [ ] commit message 规范（遵循仓库格式）
-- 四项全过 → commit
+- 三项全过 → commit
 
 ## 引用
 

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

@@ -34,7 +34,6 @@ description: "Complete diagnosis→fix→regression channel for bugs: diagnose,
 
 - **无逃生舱**：不存在正确 seam 时，**本身即 finding**——向用户明确说明"架构阻止锁定该 bug"，请求 seam 决策或记录为架构改进建议（可转交 `/improve-codebase-architecture`）；**不得**绕过测试直接改代码。
 - **轻量声明**：本技能不套用 tdd-implement 的重流程——不做逐 todo 的循环编排、不设 seams 确认步骤、无 typecheck/commit 前置门禁；单 seam 修复场景直走红-绿。
-
 **出口条件**：回归测试先红 → 写最小修复 → 回归测试变绿。
 
 ## ③ 回归验证

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

@@ -57,7 +57,6 @@ disable-model-invocation: true
 | 触发点 | 条件 | 动作 |
 |--------|------|------|
 | ② seam 确认 | 用户不同意 seams | → ① 补充 |
-| ② 综合时 | 关键信息缺失 | → ① 补采 |
 | ② 发布后 | spec 有问题 | → ① 重新循环 |
 
 ## 异常终止
@@ -72,8 +71,6 @@ disable-model-invocation: true
 
 - ① 出口达成后方可进入 ②
 - 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
-- ② 探索代码只为确认 seams 与术语——只读不改
-- 产出物格式细则（Glossary/ADR/Spec 守则）与反模式见 [references/rules.md](references/rules.md)，不在本文件重写
 
 ## 引用
 

package/.agents/skills/instance-test/SKILL.md

@@ -1,61 +1,70 @@
 ---
 name: instance-test
 disable-model-invocation: true
-description: "Verify project meets expected goals by running prompt instances in isolated temp dirs"
+description: "matt-skills 专属功能测试示范（由 scaffold-functional-test 从 spec 生成）— 验证 sync 合并 update 后的行为；仅显式调用"
 ---
 
-# Instance Test
+# Instance Test — matt-skills 专属示范
 
-Run **instance** prompts to verify project meets expected goals via actual functional tests. Each **instance** is a prompt + expected outcome, executed in an isolated temp dir — no mocks, no stubs.
+本 skill 是 **matt-skills 专属**的功能测试示范，由 `scaffold-functional-test` 从 `.scratch/sync-merge-update/spec.md` 生成（见 `references/instances.md` 头部 `spec hash` + `generatedAt`）。它是生成器产出形态的示例，不随 Template Snapshot 分发，仅保留于 Workspace。旧通用执行器文案已废弃。
+
+兼容别名：`instance-test` 保留原名以兼容历史调用，实际为 `matt-functional-test` 的示范实现。
 
 ## Steps
 
 ### 1. Gather instances
 
-Collect the **instance** set to run:
+实例集已由生成器按**受控扩展模型**落盘于 `references/instances.md`（头部含 `spec hash` + `generatedAt`，每实例含**溯源** `spec.md` 章节/行号，`<!-- manual -->` 段受保护）。
 
-- User-provided instances (prompt, command, expected files/stdout/exit code), or
-- Derived from `spec.md`/`README` acceptance criteria — extract each verifiable behavior as one instance, then confirm the list with the user before running.
+执行前校验指纹：若当前 spec 的 `spec hash` 与 `references/instances.md` 头部不一致，提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖，需用户显式确认才 regenerate（AI 先给 diff 建议）。
 
-Each **instance** must declare: command to run, expected files/content, expected stdout phrases, expected exit code.
+每实例声明：`prompt/command/expected files/content/expected stdout phrases/expected exit code` 必选，`setup/env/timeout/type/teardown` 可选，默认 `type: cli`。
 
-Completion: instance list is fixed (prompt, expected outcome, verification command) — no instance is added mid-run.
+完成：实例清单已固定（含溯源与指纹），`<!-- manual -->` 段未被覆盖。
 
 ### 2. Run instances
 
 For each **instance** in order:
 
-1. `mktemp -d` isolated dir (or `git worktree` / `--dest` if the project supports it).
-2. Execute the instance's command — capture stdout/stderr and exit code.
-3. Snapshot result files and side effects declared in expected.
+1. `mktemp -d` 隔离目录（或项目支持的 `git worktree` / `--dest`），单线程串行，不并行。
+2. 执行实例的 `command` 与可选 `setup`，捕获 stdout/stderr 与 exit code。
+3. 快照 `expected` 声明的文件与副作用。
 
-Do not run instances in parallel — one **instance** at a time, so failures are isolated and artifacts do not collide.
+一个 **instance** 一次，失败不阻断后续，产物不碰撞。
 
-Completion: every **instance** has a run dir with captured output and file snapshot.
+完成：每实例均有独立 run dir 与捕获输出。
 
 ### 3. Evaluate
 
-Compare each **instance**'s actual vs expected:
+对比每实例的 actual vs expected：
 
-- File existence/content (`test -f`, `grep -q`, `diff`).
-- Stdout/stderr contains expected phrases.
-- Exit code matches expected.
+- 文件存在性/内容（`test -f`/`grep -q`/`diff`）
+- Stdout/stderr 含预期短语
+- Exit code 一致
+- 扩展字段（`env`/`timeout`/`type`）行为符合声明
 
-Mark `PASS`/`FAIL` per **instance** with evidence (file path, stdout line, or diff).
+标记 `PASS`/`FAIL`，附 `expected vs actual` diff 与 run dir 证据。
 
-Completion: every **instance** has a `PASS` or `FAIL` with evidence — no unevaluated instance.
+完成：每实例均有 `PASS` 或 `FAIL` 且含证据。
 
 ### 4. Report
 
-Summarize in conversation:
+对话内汇总：
+
+- `PASS m/n` + per-instance evidence
+- 失败项列出 gap（expected vs actual）与 run dir 复现路径
+- 成功默认清理临时目录、失败默认保留；`--keep` 保留全部；`--report` 显式开启才落盘报告文件
+
+不以文件刷屏——默认输出在对话，报告文件仅显式开启才写。
 
-- `PASS m/n` with per-instance evidence.
-- Failures list the gap (expected vs actual) and the run dir for reproduction.
-- Clean up temp dirs unless `--keep` is requested.
+## 实例来源
 
-Do not write a report file (`report-*.md`) — output stays in conversation. Keep temp dirs only on failure for debugging.
+- 源 spec：`.scratch/sync-merge-update/spec.md`（`spec hash` 见 `references/instances.md` 头部）
+- 推导策略：混合推导（验收标准锚点 + 需求/接口/边界补充），每实例含溯源，无溯源视为幻觉
+- 手工段：`<!-- manual -->` 保护
 
-## References
+## 引用
 
-- Instance definitions (if any): `references/instances.md` — example set, auto-loaded only when present, not required.
-- Project expected behavior: `spec.md`/`README`/`--help` — the source of truth for what to verify.
+- 生成器：`scaffold-functional-test`（读 spec 产出本 skill）
+- 领域术语：`CONTEXT.md`
+- 技能设计：`docs/agents/skill-design.md`

package/.agents/skills/instance-test/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
   display_name: "Instance Test"
-  short_description: "Verify project via prompt instances in isolated temp projects"
+  short_description: "matt-skills 专属功能测试示范 — 验证 sync 合并 update 后行为"
 policy:
   allow_implicit_invocation: false

package/.agents/skills/instance-test/references/instances.md

@@ -1,48 +1,75 @@
-# Instances template
+# Instances for matt-skills — sync 行为功能测试（由 scaffold-functional-test 生成）
 
-Generic template for **instance** functional tests. Each **instance** is a prompt + command + expected outcome. Copy and adapt for your project; the example below is for `matt-skills`.
+> 源 spec：`.scratch/sync-merge-update/spec.md`
+> spec hash: `062a76fc872d`  # .scratch/sync-merge-update/spec.md 的 sha256 前 12 位
+> generatedAt: 2026-05-11
+> 推导策略：混合推导（验收标准锚点 + 需求/行为补充），每实例含溯源，无溯源视为幻觉
 
-## Format
+本文件由 `scaffold-functional-test` 按**受控扩展模型**生成：必选 `prompt/command/expected files/content/expected stdout phrases/expected exit code`，可选 `setup/env/timeout/type/teardown`，默认 `type: cli`。执行语义：`mktemp -d` 隔离、单线程串行、`PASS m/n` 汇总、证据含 `expected vs actual` diff + `run dir`。
 
-Each instance declares:
+执行前校验：对比当前 `.scratch/sync-merge-update/spec.md` 的 hash 与本文件头部 `spec hash`，不一致时提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖。
 
-- Prompt: human intent (what to verify)
-- Command: shell command to run in isolated dir
-- Expected: files/content, stdout phrases, exit code
+---
 
-Verification commands are in `SKILL.md` steps.
+## 1. sync 默认 check（无参不写盘）
 
-## Example: matt-skills functional behavior
+- Prompt: 验证 `matt-skills sync` 无参等价 check，打印表且不改 AGENTS.md
+- 溯源: spec.md — 需求/行为「`matt-skills sync` 无参：等价 `check`」+ 验收标准「`sync` 无参在已定制的 `pi-switch` 仓库上不改 `AGENTS.md`」
+- type: cli
+- setup: `node bin/cli.js init --dest <tmp>` 后手工改 `AGENTS.md` 加入 `tdd-implement` 定制行
+- Command: `node bin/cli.js sync --dest <tmp>`（无参）
+- Expected:
+  - `git diff HEAD -- AGENTS.md` 为空（`AGENTS.md` 未被覆盖）
+  - stdout 含 `上游 HEAD` 与 `新增/更新/删除/一致` 表头
+  - stdout 含 `--json` 可解析提示或表格行
+  - exit 0 或 1（有差异时 exit 1，判 exit code 符合 check 语义）
+- Expected files/content: `AGENTS.md` 保留定制行，无 `AGENTS.md.bak` 新增
+- Expected stdout phrases: `上游 HEAD`, `一致`
+- Expected exit code: 1（有差异时）/ 0（无差异时）— 按实现定义，测试以实际 check 语义为准
 
-### 1. Fresh init
-Prompt: verify fresh project initialization
-Command: `node bin/cli.js init --dest <tmp>`
-Expected: `AGENTS.md`, `.opencode/skills/tdd-implement/SKILL.md`, `.pi/skills/tdd-implement/SKILL.md`, `.agents/skills/tdd` (22 upstream) exist; stdout `模板：已复制` + `上游技能：已装 22`; no `.bak`; exit 0.
+## 2. sync --apply 安全增量（AGENTS.md 跳过、上游强制覆盖不删）
 
-### 2. Init skip on existing
-Prompt: verify idempotent init without --force
-Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
-Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
+- Prompt: 验证 `sync --apply` 为安全增量，`AGENTS.md` 定制跳过、上游技能被覆盖但 remove 列表不删
+- 溯源: spec.md — 需求/行为「`sync --apply`：安全增量写盘。`AGENTS.md` 若含独有路由则跳过；上游技能 `rm+cp force` 覆盖，跳过 `PROPRIETARY`，不执行 `remove`」+ 验收标准「`sync --apply` 后上游技能被强制更新为上游 `HEAD`，`remove` 列表的技能仍保留」
+- type: cli
+- setup: 在 `<tmp>` 放置旧版上游技能 `test-skill` 过期文件，并手工改 `AGENTS.md`
+- Command: `node bin/cli.js sync --apply --dest <tmp>`
+- Expected:
+  - `AGENTS.md` 仍含定制行（未被模板覆盖）
+  - 上游技能文件已更新为上游 HEAD 内容（`diff` 无旧版残留）
+  - `remove` 列表中的技能目录仍存在（未被删除）
+- Expected files/content: `AGENTS.md` 定制行存在；`test-skill` 被覆盖为新版；无 `AGENTS.md.bak`（安全档不备份）或按实现保留但不覆盖
+- Expected stdout phrases: `已同步` 或 `已更新` 或 `同步`
+- Expected exit code: 0
+- timeout: 30000
 
-### 3. Init --force with direct overwrite
-Prompt: verify forced init directly overwrites
-Command: `init --force --dest <tmp>` after local edit
-Expected: stdout `已覆盖` + `已装 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; no `.agents/skills/*.bak`; no `.opencode.bak`/`.pi.bak`; exit 0.
+## 3. sync --force 硬盖（AGENTS.md 备份后覆盖、全量 add/update/remove）
 
-### 4. Sync on existing
-Prompt: verify sync directly updates existing project
-Command: `sync --dest <tmp>` after local edit
-Expected: stdout `同步` + `已同步`/`已更新`; `AGENTS.md.bak` exists; `.agents/skills/tdd` updated; exit 0.
-Prompt: verify sync backs up existing project
-Command: `sync --dest <tmp>` after local edit
-Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.
+- Prompt: 验证 `sync --force` 硬盖，`AGENTS.md` 备份后被模板覆盖、技能与模板全量同步含删除
+- 溯源: spec.md — 需求/行为「`sync --force`：硬盖。`AGENTS.md` 先 `backupIfExists → .bak` 再 `cp -r force`；技能与模板均 `add/update/remove` 全做」+ 验收标准「`sync --force` 后 `AGENTS.md` 变为模板且 `AGENTS.md.bak` 存在，`remove` 列表的技能被删除」
+- type: cli
+- setup: 在 `<tmp>` 放置 `AGENTS.md` 定制行 + 一个上游已删的本地技能 `obsolete-skill/`
+- Command: `node bin/cli.js sync --force --dest <tmp>`
+- Expected:
+  - `AGENTS.md` 已被模板覆盖（定制行消失，与 `template/AGENTS.md` 一致）
+  - `AGENTS.md.bak` 存在且含定制行备份
+  - `obsolete-skill/` 已被删除
+- Expected files/content: `AGENTS.md` 内容等于 `template/AGENTS.md`；`AGENTS.md.bak` 存在
+- Expected stdout phrases: `已覆盖` 或 `硬盖`
+- Expected exit code: 0
 
-### 5. Sync --force without backup
-Prompt: verify sync --force does not backup
-Command: `sync --force --dest <tmp>`
-Expected: stdout `已覆盖` without new `.bak`; exit 0.
+## 4. update 已合并到 sync --apply（删除分支、提示已合并）
 
-### 6. List
-Prompt: verify skill listing
-Command: `list` and `list --json`
-Expected: 27 skills, includes `tdd` with correct description; `--json` is valid JSON array; exit 0.
+- Prompt: 验证 `matt-skills update` 已删除，执行后报错提示已合并到 `sync --apply`，且 `--help` 不再列 `update`
+- 溯源: spec.md — 需求/行为「`matt-skills update`：删除该分支，`main` 中 `command === 'update'` 改为 `stderr: 'update 已合并到 sync --apply'` 且 `exit 1`，`--help` 不再列 `update`」+ 验收标准「`matt-skills update` 执行后报错提示已合并，`--help` 无 `update`」
+- type: cli
+- Command: `node bin/cli.js update 2>&1; echo "exit:$?"` 与 `node bin/cli.js --help`
+- Expected:
+  - `update` 命令 stdout/stderr 含 `已合并到 sync --apply` 且 exit 1
+  - `--help` 输出不含独立的 `update` 子命令行（不匹配 `^\s*update`）
+- Expected stdout phrases: `已合并到 sync --apply`
+- Expected exit code: 1（`update` 分支）
+- env: {}
+
+<!-- manual -->
+<!-- 以下为人工定制实例保护段：由开发者手写，scaffold-functional-test 重生成时不覆盖此段以上的内容。如需新增手工实例，请在此段后追加。 -->

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

@@ -0,0 +1,75 @@
+---
+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 running tests (use instance-test) nor for TDD (use tdd-implement)"
+---
+
+# Scaffold Functional Test
+
+从本仓库的 spec 自动脚手架出**仓库专属的功能测试 skill**。本技能为**非 Long-Horizon 轻量 skill**（一次性 scaffold，不做多 seam 红绿循环），一次性完成「读 spec → 推导实例 → 落盘 skill → 自验证」闭环。术语定义见 `CONTEXT.md`。
+
+## 产出物
+
+- 定制 skill 目录：`.agents/skills/<repo>-functional-test/`（含 `SKILL.md` + `references/instances.md` + 可选 `scripts/run.sh`）
+- 指纹：`spec hash` + `generatedAt` 写入生成物头部，用于后续执行前校验
+- 保护：`<!-- manual -->` 标记段不被覆盖
+
+生成物纳入 git，可回归复用，不进入 `template/` 再分发（生成器本身才随 Template Snapshot 分发）。
+
+## Steps
+
+### ① 采集 Spec
+
+解析用户传入的 spec 路径，默认 `.scratch/<feature>/spec.md`。
+
+- 若 spec 存在：读取 `CONTEXT.md`/`docs/adr/` 相关术语与决策，提取待覆盖行为清单（以验收标准为锚点）。
+- 若 spec 不存在：回退到 `README` + `--help` 输出倒推行为清单，但必须进入 Step ② 的清单确认关卡，不静默臆测。
+
+完成：待覆盖行为清单已固定，无未澄清歧义。
+
+### ② 推导实例
+
+按混合推导策略生成实例草案：
+
+- 以验收标准为锚点，需求/接口/边界为补充，可为 spec 未显式写的隐含行为（如 `--help` 文案、错误码、幂等性）补实例，但每条实例必须标注**溯源**（spec 章节/行号或 `README/--help` 来源），无溯源的实例视为幻觉需删除。
+- 每实例声明**受控扩展模型**：必选 `prompt/command/expected files/content/expected stdout phrases/expected exit code`，可选 `setup/env/timeout/type/teardown`，默认 `type: cli`。
+- **强制门禁**：实例清单必须与用户确认后才进入 Step ③；无确认不落盘。
+
+完成：实例清单已获用户确认，每实例含溯源与完整四元组。
+
+### ③ 脚手架落盘
+
+按受控扩展模型写入定制 skill 目录：
+
+- `SKILL.md`：执行语义（见下节「执行语义」）
+- `references/instances.md`：实例集（含溯源、必选+可选字段、头部 `spec hash` + `generatedAt`）
+- 不覆盖 `<!-- manual -->` 保护段；覆盖式更新需经用户确认；重生成时先给出 diff 建议，用户确认后才应用。
+
+完成：定制 skill 目录已落盘，指纹正确，人工段受保护。
+
+### ④ 自验证
+
+落盘后立即按实例执行语义串行执行一轮实例集作自验证：
+
+- `mktemp -d` 隔离（或项目支持的 `git worktree` / `--dest`），单线程串行，不并行。
+- 每实例捕获 stdout/stderr 与 exit code，按 `test -f`/`grep -q`/`diff` 对比判定 `PASS`/`FAIL`，单 FAIL 不阻断后续。
+- 对话内输出 `PASS m/n` + per-instance evidence（`expected vs actual diff` + `run dir`），失败不回滚生成物但给出 gap 供迭代 `regenerate`。
+- 成功默认清理临时目录、失败默认保留（`--keep` 保留全部）；`--report` 显式开启才落盘报告文件。
+
+完成：自验证已执行，对话内汇总完成，证据可复现。
+
+## 执行语义（生成物复用）
+
+生成物本身的执行语义与 `instance-test` 一致：`mktemp -d` 串行、`PASS m/n` 汇总、证据含 `expected vs actual diff` + `run dir`。执行前校验 `spec hash` 指纹：若当前 spec 已变更，提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖，需用户显式确认才 regenerate。
+
+## 不做什么
+
+- 不替代 `tdd`/`tdd-implement` 的红绿循环与 `commit-check` 门禁
+- 不自动织入每次 `tdd-implement` 或 `commit-check`；仅 `tdd-implement --with-functional` 显式 opt-in
+
+## 引用
+
+- 领域术语：`CONTEXT.md`
+- 技能设计规则：`docs/agents/skill-design.md`
+- 示范产物：`.agents/skills/instance-test/`（本仓库专属，见其 SKILL.md）
+- Issue tracker：`docs/agents/issue-tracker.md`

package/.agents/skills/scaffold-functional-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Scaffold Functional Test"
+  short_description: "Scaffold a repo-specific functional-test skill from spec — not for running tests nor TDD"
+policy:
+  allow_implicit_invocation: true

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

@@ -45,4 +45,3 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 - Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
 - 单线详规：[stages.md](references/stages.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)
-- Issue tracker 约定：[issue-tracker.md](../../docs/agents/issue-tracker.md)

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

@@ -46,7 +46,7 @@ for each 层 Li in L1..Ln:
   并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
   等待：阻塞直到 Li 全部子代理返回回执卡片
   验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
-  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②全量测试套件通过 ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或全量/卫生/历史任一失败按 A5 回退重派该 issue
+  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 回退重派该 issue
 全部层层收敛通过后进入 A4 全量收敛
 ```
 
@@ -108,7 +108,7 @@ for each 层 Li in L1..Ln:
 
 全部层逐 issue 验收通过后，编排器执行：
 
-1. **全量测试套件**：跑仓库完整测试套件（阶段④口径），失败则按 A5 回退。
+1. **全量测试套件**：跑仓库完整测试套件（所有 issue 执行完毕后的唯一全量，阶段④与 A2 已改为相关，仅此一次）
 2. **历史校验**：执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明编排过程中历史被改写，立即经 `git reflog` 恢复后重跑收敛。
 3. **目录卫生**：`git status` 确认无 `[DEBUG-...]` 残留、无未跟踪临时文件；有残留则仅删本次临时产物后重检，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
 4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件，不透传子代理全量日志（各 issue 的 `## 实施总结` 已落盘，详查落盘文件）。

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

@@ -35,7 +35,6 @@
 
 ### 边界
 
-- 本阶段只澄清需求——实现与测试设计在后续阶段进行
 
 ---
 
@@ -61,8 +60,6 @@
 
 - 一个 seam 对应一个公共接口上的一个待测行为（输入 + 预期输出）：一个 seam = 一个测试 + 一个最小实现 cycle；同一接口的多个行为拆分为多个 seam，而非内部函数
 
-> Seams 定义参考：[tdd 技能](.agents/skills/tdd/SKILL.md#seams--where-tests-go)
-
 ---
 
 ## 阶段 ③：TDD 开发循环
@@ -132,8 +129,6 @@
 - 全部 todo 为 done 才进入阶段④
 - 测试质量规则（公共接口验证、独立断言、mock 边界、重构归属 review）见 tdd 技能，不在本阶段重写
 
-> Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
-> 好测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
 
 ---
 
@@ -145,7 +140,7 @@
 
 ### 操作
 
-1. 运行仓库的完整测试套件
+1. 运行仓库的完整测试套件（单线模式的唯一全量；多 issue 子代理此步仅相关，全量由 A4 统一执行）
 2. 检查所有测试是否通过
 
 ### 出口条件
@@ -251,7 +246,7 @@
 
 ## Todo 规定
 
-本节为阶段②/③的共用规定，完成"任务拆分"到"回合内执行"的闭环。
+本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 编排与串联，不再重写层次细节。
 
 ### 拆分层级（大小任务层次）