@heihei0299/matt-skills 1.6.4-test.1 → 2.0.1

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

@@ -1,94 +1,50 @@
 ---
 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."
+description: "保护本仓库 GitHub Actions CI/release pipeline：按发布、workflow 维护或发布后故障场景执行必要门禁。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/发布这一条链。
+本 skill 只编排当前仓库的 CI 与 npm 发布门禁。先读取 `.github/workflows/ci.yml`，以实际 workflow 的 job、input、condition 和权限为事实源；不要假设不存在的 job、input 或自动回滚行为。产品代码 bug 的诊断和修复交给 `diagnose-fix`，不在此重复通用诊断。
 
-## 何时用
+## 场景选择
 
-- Actions 持续红 / 偶发红（尤其是 `verify` 单点红而 `publish` 仍绿）
-- 新建或改动 `.github/workflows/ci.yml`、调整 `cargo test` / `clippy` / `rustfmt` 参数
-- 打 tag 前、发 npm 前、或发布后需要自检/回滚
+- 用户请求发布、打 release tag 或发布 npm → **发布路径**；
+- 用户修改 workflow，或报告 Actions 红/偶发红 → **workflow 维护路径**；
+- tag 已发布但 registry、release 或 post-check 异常 → **发布后故障路径**。
 
-## 三段式门禁
+只执行命中的路径；普通发布不运行与当前 workflow 无关的 lint、dry-run 或 dispatch。
 
-```
-① 编排 flows → ② 预发布 gate → ③ 发布后自纠
-```
+## 发布路径
 
-每段有**完成条件**（可验证），未满足不进入下一段。
+1. 读取当前 package metadata 和 workflow；确认正式 tag 的 commit 可从 `main` 到达，目标 tag 尚不存在，版本与 tag 约定一致。
+2. 运行项目规定的测试和 `npm pack --dry-run`，确认发布内容和实际结果。
+3. 只有前两步通过后才创建并推送 `vX.Y.Z` tag；不从非 `main` commit 推送正式 tag。
+4. 等待 tag workflow 完成，确认 `verify` 成功后才进入 `publish`，并记录 Actions run URL、job 结论和实际 npm tag。
+5. 使用 `npm view <package>@<version> version` 或 registry API 回读，确认发布版本真实可见。
 
----
-
-### ① 编排 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` 检查缩进与重复键
+出口：tag、Actions 和 registry 的实际结果均已记录；任一失败都阻断“发布成功”结论。
 
-**workflow dry-run**：
-- `act --dry-run` 或 `gh workflow view` 模拟 `verify/build/publish` 三 job 依赖与 `if` 条件
-- 校验 `publish.needs` 含 `verify` 且 `workflow_dispatch` 可手动触发
+## Workflow 维护路径
 
-**dispatch 验证**：
-- 通过 `gh workflow run ci.yml --ref main -f dry_run=true` 触发试运行，观察 `verify` 日志与产物上传
-- 失败即阻断 `publish`，日志留存于 Actions
+1. 读取当前 workflow，按实际内容检查触发器、`publish.needs`、job `if`、权限和 concurrency；不硬编码 job 名称。
+2. 只有 workflow 在本次范围内发生变化，或故障需要时，才运行已安装的 `actionlint` / `yamllint`；工具不可用就记录 `unavailable`，不得伪报通过。
+3. 需要 dry-run 或手动 dispatch 时，只使用 workflow 已声明的 input；不得传入未声明的 `dry_run` 等参数。若无安全的 dry-run input，改用静态依赖检查或一次不发布的验证运行。
+4. 失败时区分 workflow wiring、项目测试、授权/registry 和 runner 环境；只修复当前请求范围内的问题。
 
-**完成条件**：
-- [ ] `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` 保证）
-
----
+出口：实际 workflow 结构、检查命令和运行结果均有证据；未验证项明确列出。
 
-## 反模式
+## 发布后故障路径
 
-- **单依赖 publish**：`needs: build` 是本仓 7 次带病发布的根因
-- **仅 tag 触发**：`push.branches` 缺失导致主干修复无 CI
-- **静默发布**：`publish` 失败不建 issue / 不删 tag，下次 `409` 叠加
-- **`-A clippy::all`**：掩盖真实告警
+1. 读取对应 Actions run、npm registry 和 Git tag 的实际状态，确认是未发布、发布延迟、重复版本、授权失败还是 post-check 失败。
+2. 创建或补充带 run URL 的 issue，记录 registry 查询结果和失败分类。
+3. 只按照当前 workflow 声明的人工回滚步骤操作；不自行声称删除 release、删除 tag 或 `npm unpublish` 已发生。
 
-## 引用
+出口：故障分类、保留的远端对象和人工下一步均已明确。
 
-- 调研：`.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`（测试隔离后的回归）
+## 不做什么
 
+- 不把每次发布都扩展为完整 CI 工具链演练；
+- 不引用不存在的 `build` job、`dry_run` input 或 `rollback_version` input；
+- 不把历史事故描述当成当前仓库事实；
+- 不自动删除 tag/release，不静默吞掉 publish 或 post-check 失败。

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

@@ -1,63 +1,95 @@
 ---
 name: commit-check
-description: "Run the pre-commit gate before any commit: verify docs match the implementation, align README, keep the directory clean, and write a clear commit message. Use whenever the user is about to commit or asks to check anything about the commit — e.g. verifying docs/README are in sync, cleaning up temp files, scanning for secrets/keys/.env in the change, or having you write the commit message. Not for general PR/code review (that's code-review), and not for explaining git/commit conventions (that's a teach task)."
+description: "检查 matt-skills 当前 staged commit 的范围、敏感信息和 commit message，并按改动路径执行对应同步检查。"
+disable-model-invocation: true
 ---
 
 # Commit Check
 
-提交前的**门禁检查**：文档一致性 → 保持目录卫生 → 规范 commit message，三项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
+用户显式调用 `/commit-check` 后运行本技能。它是提交前的 staged commit gate：检查将要提交的内容是否属于当前逻辑变更、是否包含敏感信息、以及 commit message 是否可追溯。
 
-## 三项检查（全部通过才 commit）
+本技能只检查，不负责 staging，不执行 `git commit`，也不要求整个工作区干净。通过后报告 `ready to commit`，由调用方执行提交。
 
-### ① 文档一致性
-> 覆盖原 ① 审查文档 的全部检查项与原 ② 对齐 README 的全部检查项
+## 三项核心 gate
 
-- 本次改动涉及的行为/接口/配置/命令是否有对应文档（README、`docs/`、技能正文）描述
-- 文档描述与实现一致：无过期信息、无声称未实现的功能、无遗留的旧接口描述
-- 发现不一致 → 先修文档（或更新实现），再进入下一步
-- 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
-- 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
-- **重点聚焦（README + matt-skills 流程）**：本次门禁优先对齐 `README.md` 与 matt-skills 流程相关文件——`AGENTS.md`（路由）、`CONTEXT.md`（术语）、`docs/agents/*`（`skill-design.md`/`runtime-discipline.md`/`issue-tracker.md`/`triage-labels.md`/`domain.md`）、`template/` 镜像（含 `.agents/skills` 全量、`AGENTS.md`、`CONTEXT.md`、`docs/agents`）、`.agents/skills/*`（技能正文与 `references/`）、`config/*` 与 `scripts/build-template.js`；改动触及上述任一文件时，逐项核对 README 的结构说明/清单/映射表与模板镜像是否同步，未同步先修复再 commit
-- 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
-- **特例**：`AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + 技能文件 + `.gitignore` 的 `.pi/` 忽略，且存在 `AGENTS.md.bak` 时，视为模板同步预期增量，不回滚
-### ② 保持目录卫生
+### ① Staged scope
 
-- `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
-- 无关文件（一次性脚本、转储、探针、调试日志）直接追加至 `.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` 无输出）
+- 读取 `git diff --cached --name-status` 和 `git diff --cached`。
+- staged diff 必须非空，并且只包含当前用户请求的逻辑变更。
+- 列出 staged 文件和关键 diff，无法确认范围时报告疑点并阻塞。
+- 调用方负责 `git add`；本技能不自动 stage、unstage 或清理文件。
+- 工作区可以保留其它未暂存修改；不以 `git status` 全干净作为出口条件。
 
-### ③ 规范 commit message
+### ② Sensitive scan
 
-- 格式遵循仓库约定（常见：`<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
+运行确定性扫描脚本，不手写 grep：
 
-## 不做什么
+```bash
+bash .agents/skills/commit-check/scripts/scan-sensitive.sh --staged-only
+```
 
-- 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
-- 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
-- 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
+- 结构化 secret assignment 和 private key block → **fail**。
+- 普通 `api_key`、`secret`、`token`、`password`、`.env` 等关键词 → **warning**，由调用方人工确认。
+- 扫描只针对 staged diff；不因未暂存内容阻塞本次 commit。
 
-## 执行顺序（回合内串行）
+### ③ Commit message
 
-1. 跑 ① 文档一致性 → ② 保持目录卫生 → ③ 写 commit message
-2. 任一项发现问题：修复后重跑该项，全部通过才 commit
-3. commit 后确认 `git status` 干净，工作结束
+- 使用 `<type>(<scope>): <subject>` 基本格式；`type` 使用 `feat`、`fix`、`docs`、`chore`、`refactor`、`test` 等仓库约定值。
+- subject 描述变更结果，不描述操作过程。
+- body 可选；只有确实需要时补充动机、影响范围或验收证据。
+- 一个 commit 只表达一个逻辑变更；多主题拆分提交。
+- 本技能检查并给出 message 结论，但不代替调用方执行 commit。
 
-**回合连续性**：三项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到三项全过或遇到外部阻塞（权限/授权缺失）。
+## matt-skills 路径适配
 
-## 出口条件
+以下 staged 路径触发 matt-skills 专属检查；普通源码或测试 commit 不触发这些额外检查：
 
-- [ ] 文档一致性（文档与 README 均已对齐）
-- [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
-- [ ] commit message 规范（遵循仓库格式）
-- 三项全过 → commit
+```text
+README.md
+AGENTS.md
+CONTEXT.md
+docs/agents/**
+template/**
+.agents/skills/**
+config/**
+scripts/build-template.js
+.opencode/commands/**
+.pi/prompts/**
+```
 
-## 引用
+相关路径变更时：
 
-- 代码审查语义：[code-review](.agents/skills/code-review/SKILL.md)（唯一事实源，本技能不重写）
-- 完整实现流程：[tdd-implement](.agents/skills/tdd-implement/SKILL.md)（含流程内收尾的文档对齐与目录卫生）
+- README、公开行为、命令、配置或流程描述变化 → 检查对应文档与实现一致；
+- `AGENTS.md`、`CONTEXT.md`、`docs/agents/`、`template/`、技能或镜像变化 → 运行相关模板/契约测试，至少覆盖 `test/template-sync.test.js`；
+- `commit-check` 自身变化 → 运行 `test/commit-check.test.js` 和 `test/commit-check-scan.test.js`；
+- `tdd-implement` 变化 → 运行 `test/tdd-implement-stages.test.js`；
+- `config/`、构建脚本、opencode command 或 pi prompt 变化 → 运行对应 CLI、模板或命令测试；
+- 只检查本次 staged 路径相关的内容，不通读全部 README、docs 或模板。
+
+这些是 matt-skills 的条件化仓库检查，不改变上面的三项核心 gate。
+
+## Git history pointer
+
+遵循 `CONTEXT.md` 和 `docs/agents/` 中的 Git History Preservation 规则。本技能只在当前会话存在 `BASE_HEAD` 时执行必要祖先校验：
+
+```bash
+git merge-base --is-ancestor "$BASE_HEAD" HEAD
+```
+
+完整的禁止命令、恢复和 stash 规则只在仓库级文档维护，不在本技能重复展开。
+
+## 执行顺序与出口
+
+1. 检查 staged scope，确认 staged diff 非空且属于当前逻辑变更。
+2. 执行 `scan-sensitive.sh --staged-only`。
+3. 检查 commit message。
+4. 根据 staged 路径执行必要的 matt-skills 条件化检查。
+5. 输出 staged 文件、三项 gate 结果、warning、条件化检查结果和 `ready to commit` 或具体阻塞项。
+
+发现阻塞项时停止并报告；不自动修复、不自动 stage、不自动 commit。
+
+## 不负责的内容
+
+- 不做完整代码审查；审查语义由对应审查流程负责。
+- 不执行测试先行、typecheck、build、真实运行或 tracker 收尾；这些属于对应实现流程。
+- 不成为任何实现流程的自动子步骤；仅按 staged 路径提供本仓库提交 gate。

package/.agents/skills/commit-check/scripts/scan-sensitive.sh

@@ -1,36 +1,29 @@
 #!/usr/bin/env bash
-# Deterministic secret scan for commit-check check ③.
-# The grep patterns are fragile to freehand — run this instead of re-writing
-# the scan every time. Two confidence tiers:
-#   FAIL  — structured secrets (KEY=value assignments, private key blocks)
-#   WARN  — bare keywords (may legitimately appear in docs that mention them)
-# Checks the staged diff (fail) and, unless --staged-only is passed, reports
-# matches in the unstaged diff (warn).
-#
-# Usage:
-#   scripts/scan-sensitive.sh            # staged (fail) + unstaged (warn)
-#   scripts/scan-sensitive.sh --staged-only
+# Deterministic staged-diff secret scan for commit-check.
+# FAIL: structured assignments and private-key blocks.
+# WARN: bare keywords that may legitimately appear in documentation.
 set -euo pipefail
 
+if [[ $# -gt 1 || ( $# -eq 1 && "$1" != "--staged-only" ) ]]; then
+  echo "usage: $0 [--staged-only]" >&2
+  exit 2
+fi
+
 fail_patterns='(api[_-]?key|secret|token|passwd|password)[[:space:]]*[=:][[:space:]]*[^[:space:]]{8,}|BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'
 warn_patterns='(api[_-]?key|secret|token|passwd|password|\.env)'
 
+staged_diff=$(git diff --cached -U0)
 fail=0
 
-if git diff --cached -U0 | grep -inE "$fail_patterns"; then
+if grep -inE "$fail_patterns" <<< "$staged_diff"; then
   echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
   fail=1
 else
   echo "✅ No structured secrets in staged diff."
-  if git diff --cached -U0 | grep -inE "$warn_patterns"; then
-    echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
-  fi
 fi
 
-if [[ "${1:-}" != "--staged-only" ]]; then
-  if git diff -U0 | grep -inE "$fail_patterns"; then
-    echo "⚠  Structured-secret matches in UNSTAGED diff — decide whether they belong in the commit." >&2
-  fi
+if grep -inE "$warn_patterns" <<< "$staged_diff"; then
+  echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
 fi
 
 exit "$fail"

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

@@ -5,61 +5,38 @@ description: "Complete diagnosis→fix→regression channel for bugs: diagnose,
 
 # Diagnose Fix
 
-诊断 **bug** 并修复的编排技能：诊断语义以 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 为唯一事实源，修复语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只编排三个阶段并设一道**硬门槛**，不重写两个上游技能的规则。
+本 skill 只连接诊断、TDD 修复和回归三个阶段。诊断细节以 [`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md) 为事实源，红绿语义以 [`tdd`](.agents/skills/tdd/SKILL.md) 为事实源；不复制两个上游的完整步骤。
 
-本技能是**长程任务**（Long-Horizon Skill）：诊断 → 修复 → 回归在**一个回合内串行完成**，自带**回合连续性**（Turn Continuity）规则（见下文）。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
+## 流程
 
-## 流程速览
+### ① 诊断
 
-```
-① 诊断 → ② TDD 修复（硬门槛）→ ③ 回归验证
-```
+委托 `diagnosing-bugs` 完成 Phase 1–4：建立能捕捉用户症状的 tight feedback loop，实际复现并最小化，再形成可证伪的假设并按单变量探针验证。
 
-## ① 诊断
+出口：反馈回路已实际变红，且最小复现已确认；此阶段不写修复代码。
 
-按 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 的 Phase 1-4 执行：
+### ② TDD 修复
 
-1. **反馈回路**（Phase 1）：构建能对 _这个 bug_ 变红的紧致 pass/fail 信号——优先失败测试，其次 curl/CLI/浏览器脚本/重放/一次性 harness 等；没有回路不进入假设。
-2. **复现 + 最小化**（Phase 2）：跑回路看它红，确认失败模式与用户描述一致；逐步删减输入/调用方/配置，只保留 load-bearing 元素。
-3. **假设**（Phase 3）：生成 3-5 个可证伪的排名假设，先展示给用户。
-4. **探针**（Phase 4）：一次只改一个变量，临时探针用 `[DEBUG-...]` 前缀标记。
+1. 在正确的公共 seam 上提出回归测试边界，并遵循 `tdd` 要求获得用户确认；只确认本次 seam，不建立重型 seam ledger。
+2. 加载 `tdd`，先把最小复现转成失败回归测试并实际看到 Red。
+3. 只写让该测试 Green 的最小修复，并遵循 `tdd` 的红绿循环。
 
-**出口条件**：反馈回路已红（已实际跑过并确认捕捉到该 bug）、复现已最小化。诊断完成前不写任何修复代码。
+**硬门槛：**不存在已实际观察到的失败回归测试时，不得写任何修复代码。不存在正确 seam 时，本身就是 finding；记录架构阻塞，不绕过测试直接修改。
 
-## ② TDD 修复（硬门槛）
+出口：回归测试先 Red，最小修复后 Green；不进入 `tdd-implement` 的长流程。
 
-**TDD 语义（红-绿循环、seam 定义、好测试标准、anti-patterns）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源**——本技能不重写；进入本阶段前先读取 tdd 技能。
+### ③ 回归收尾
 
-**硬门槛**：写任何修复代码之前，必须已存在一个**失败**的回归测试——把最小复现转写为正确 seam 上的测试，先运行看它红，然后才允许写修复代码让它变绿。
+按 `diagnosing-bugs` 的收尾要求重跑阶段 ① 的原始、未最小化反馈回路，确认用户症状消失；清理 `[DEBUG-...]` 探针和一次性 harness，并记录最终验证的假设。
 
-- **无逃生舱**：不存在正确 seam 时，**本身即 finding**——向用户明确说明"架构阻止锁定该 bug"，请求 seam 决策或记录为架构改进建议（可转交 `/improve-codebase-architecture`）；**不得**绕过测试直接改代码。
-- **轻量声明**：本技能不套用 tdd-implement 的重流程——不做逐 todo 的循环编排、不设 seams 确认步骤、无 typecheck/commit 前置门禁；单 seam 修复场景直走红-绿。
-**出口条件**：回归测试先红 → 写最小修复 → 回归测试变绿。
+出口：原始症状消失、回归测试 Green、临时诊断产物已清理。
 
-## ③ 回归验证
+## 回合连续性
 
-1. 重跑诊断阶段①的**原始反馈回路**（未最小化场景）确认症状消失。
-2. 清理：删除所有 `[DEBUG-...]` 标记的临时探针与一次性 harness（`grep` 前缀确认无残留）。
-3. 在 commit / PR 消息中写明**验证正确的假设**（诊断阶段哪个假设被证实），让下一个调试者受益。
-
-**出口条件**：原始症状消失 + 回归测试绿 + 临时探针清理完成。
-
-## 反模式（不做什么）
-
-完整反模式清单见 [references/anti-patterns.md](references/anti-patterns.md)——正文各阶段规则是正面约束，反模式清单是负向边界；细节只在一处存在，本文件不重复。
-
-## 回合连续性规则
-
-诊断 → 修复 → 回归**在一个回合内串行完成**，不等用户"继续"：构建回路 → 复现 → 假设 → 探针 → 失败测试 → 修复 → 回归 → 清理整条链一气呵成，中途不停顿。
-
-输出只允许发生在以下三种情况：
-- **合规交互点**：技能要求的用户确认——阶段①假设清单展示、阶段②无 seam finding 上报或 seam 决策请求
-- **外部阻塞**：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
-- **阶段出口**：整个阶段的出口条件满足（阶段①回路已红 + 复现最小化；阶段②失败测试已红 → 修复变绿；阶段③症状消失 + 回归绿 + 清理完成）
-
-预告下一步后立即执行该步骤，回合终点仅为合规交互点、外部阻塞或阶段出口条件满足。进度输出本身不结束回合——输出后继续执行，直到三类终点之一达成。
+诊断 → seam 确认 → Red → 修复 → Green → 原始回路 → 清理在一个回合内连续推进。只在用户必须确认 seam、发现无 seam finding、外部环境阻塞或整个阶段出口时暂停；预告下一步后立即执行。
 
 ## 引用
 
-- 诊断：[diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md)
-- TDD 修复：[tdd 技能](.agents/skills/tdd/SKILL.md)、[tdd/tests.md](.agents/skills/tdd/tests.md)、[tdd/mocking.md](.agents/skills/tdd/mocking.md)
+- 诊断：[`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md)
+- 修复：[`tdd`](.agents/skills/tdd/SKILL.md)
+- 负向边界：[`references/anti-patterns.md`](references/anti-patterns.md)

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

@@ -6,75 +6,38 @@ disable-model-invocation: true
 
 # Grill to Spec
 
-**grill-with-docs**（grilling + domain-modeling）与 **to-spec** 的编排器。本 skill 只做编排：把设计压力测试成共识，把共识综合成 spec 发布——不写代码，不动源码。
-
-## 职责
-
-| 做 | 不做 |
-|----|------|
-| 编排 `grill-with-docs` → `to-spec` 完整通道 | 不编写代码、不修改任何源码（含测试） |
-| 引导用户从模糊想法 → 结构化 spec | 不拆 tickets（`/to-tickets` 职责） |
-| grilling 逐问挑战、打磨设计 | 不调用 `/code-review` |
-| 同步产出领域文档（glossary inline；ADR 草稿经用户确认后落盘） | 阶段②仅综合，不新增采访 |
-| 综合对话为可执行的 spec 文档并发布 | 不维护已发布的 spec |
-| 产出物仅限领域文档与 spec | 实现与修复交给实现类 skill（如 `/tdd-implement`） |
+只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试。
 
 ## 流程
 
-```text
-① Grill with docs → ② Synthesize to spec
-```
-
-① 加载 `/grill-with-docs`：grilling 采访（一次一问、等反馈；决策逐条交由用户定夺）+ domain-modeling 产出 glossary/ADR。出口：用户确认共识达成。
-
-   ① 内 ADR 子流转（与 glossary 的 inline 更新严格区分）：
-   1. 触发：仅当 domain-modeling 三条件全满足（难逆转 / 无上下文费解 / 真实权衡）才提议 ADR
-   2. 草稿：按 ADR-FORMAT 把完整标题+正文展示给用户审阅，等待反馈
-   3. 确认：用户显式说「确认/写入」才落盘；用户拒绝则不写、继续访谈；用户要求修改则改草稿重新确认
-   4. 未确认前不得创建或写入 `docs/adr/` 下的任何文件
-
-② 加载 `/to-spec`：探索代码（glossary 词汇贯穿 spec、尊重相关 ADR）→ 确认 seams（既有优先、最高 seam、理想一个）→ 编写 spec 草稿 → 展示给用户确认（只展示等决定，不新增采访提问）→ 发布到 `.scratch/<feature-slug>/spec.md` 并标 `ready-for-agent`。出口：spec 已发布。
-
-## 产出物（格式严格对齐下游技能）
-
-本技能产出物仅以下三种，格式以各技能文件为唯一事实源，不在本技能重写：
-
-| 产出物 | 位置 | 格式来源 |
-|--------|------|----------|
-| Glossary | `CONTEXT.md`（多上下文：`CONTEXT-MAP.md` + 各上下文 `CONTEXT.md`） | [CONTEXT-FORMAT.md](.agents/skills/domain-modeling/CONTEXT-FORMAT.md) |
-| ADR | `docs/adr/NNNN-slug.md`（多上下文：系统级在根，上下文级在 `src/<ctx>/docs/adr/`） | [ADR-FORMAT.md](.agents/skills/domain-modeling/ADR-FORMAT.md) |
-| Spec | 发布到 issue tracker：`.scratch/<feature-slug>/spec.md` | [to-spec 七节模板](.agents/skills/to-spec/SKILL.md) |
+### ① 形成共识
 
-三类产出物的格式细则（Glossary 守则 / ADR 守则 / Spec 守则）见 [references/rules.md](references/rules.md)——SKILL.md 不重复细节。
+调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
 
-## 不可协商规则（无任何例外）
+- glossary 按上游规则 inline 更新；
+- 只有确需 ADR 时才创建 ADR 草稿；
+- ADR 必须先展示完整草稿，用户明确确认后才写入，未确认不得落盘。
 
-- **写入 ADR 必须由用户显式确认，无论任何情况、无任何例外**：三条件全满足、决策看似显然、② 补记，均不豁免。ADR 一旦落盘记录不可撤销（可 supersede，但痕迹永存），全部门槛都在写入之前
-- **ADR 与 glossary 不对称**：`CONTEXT.md` 术语可随访谈 inline 更新（domain-modeling 规则），ADR 必须先审草稿、用户确认后才落盘——禁止把 inline 逻辑套用到 ADR
+出口：用户确认共识已达成，且所有 ADR 草稿都已获得单独确认或明确不写入。
 
-## 回退
+### ② 发布 spec
 
-| 触发点 | 条件 | 动作 |
-|--------|------|------|
-| ② seam 确认 | 用户不同意 seams | → ① 补充 |
-| ② 发布后 | spec 有问题 | → ① 重新循环 |
+将已确认的共识交给 [`to-spec`](.agents/skills/to-spec/SKILL.md)，完成代码库理解、seam 提案和 spec 组装。
 
-## 异常终止
+- 将 seam 提案并入最终 spec 草稿，不单独制造一次重复确认；
+- 发布前展示完整 spec 草稿，用户一次明确确认后才写入 `.scratch/<feature-slug>/spec.md`；
+- 发布时使用 `ready-for-agent`，格式细则只读取 [`references/rules.md`](references/rules.md)。
 
-| 情况 | 处理 |
-|------|------|
-| 用户中途放弃 / 无主题 | 终止 |
-| tracker 未配置 | 提示 `/setup-matt-pocock-skills`，终止 |
-| ① 超过 5 轮无进展 | 建议暂停或缩小范围 |
+出口：spec 已发布，路径、状态和未纳入范围已报告。
 
-## 约束
+## 本 skill 独有门禁
 
-- ① 出口达成后方可进入 ②
-- 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
+- ADR：草稿 → 用户确认 → 落盘，任何情况不例外；
+- spec：共识与 seam 合并为一个最终草稿，只设置一次发布前确认；
+- 全程不写代码、不修改测试、不执行实现。
 
-## 引用
+## 异常
 
-- [grill-with-docs](.agents/skills/grill-with-docs/SKILL.md)
-- [grilling](.agents/skills/grilling/SKILL.md)
-- [domain-modeling](.agents/skills/domain-modeling/SKILL.md)
-- [to-spec](.agents/skills/to-spec/SKILL.md)
+- 用户放弃或没有可形成 spec 的主题时终止；
+- issue tracker 未配置时报告配置阻塞，不绕过发布；
+- 用户改变已确认的设计时回到 ①，不在 ② 静默扩大范围。

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

@@ -1,75 +1,61 @@
 ---
 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)"
+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 regular instance execution (use the generated instance-test skill) nor for TDD (use tdd-implement)"
 ---
 
 # Scaffold Functional Test
 
-从本仓库的 spec 自动脚手架出**仓库专属的功能测试 skill**。本技能为**非 Long-Horizon 轻量 skill**（一次性 scaffold，不做多 seam 红绿循环），一次性完成「读 spec → 推导实例 → 落盘 skill → 自验证」闭环。术语定义见 `CONTEXT.md`。
+从仓库 spec 生成仓库专属的功能测试 skill。它是一次性 scaffold，不负责常规实例执行，也不进入 TDD 红绿循环。
 
-## 产出物
+生成物：`.agents/skills/<repo>-functional-test/`，至少包含 `SKILL.md` 与 `references/instances.md`；可按需要包含 runner。实例字段、溯源、指纹和保护段统一遵循 [`references/schema.md`](references/schema.md)。生成物纳入 git，但不复制到 `template/`。
 
-- 定制 skill 目录：`.agents/skills/<repo>-functional-test/`（含 `SKILL.md` + `references/instances.md` + 可选 `scripts/run.sh`）
-- 指纹：`spec hash` + `generatedAt` 写入生成物头部，用于后续执行前校验
-- 保护：`<!-- manual -->` 标记段不被覆盖
+## 流程
 
-生成物纳入 git，可回归复用，不进入 `template/` 再分发（生成器本身才随 Template Snapshot 分发）。
+### ① 采集行为
 
-## Steps
+读取用户指定的 spec，默认 `.scratch/<feature>/spec.md`；同时读取相关 `CONTEXT.md` 与 ADR。以 Acceptance Criteria 固定待覆盖行为清单。
 
-### ① 采集 Spec
+spec 不存在时可从 README 与 `--help` 建立候选清单，但必须把它标为候选并进入下一步确认，不得把推断当成需求。
 
-解析用户传入的 spec 路径，默认 `.scratch/<feature>/spec.md`。
+出口：行为清单的来源、范围和未覆盖项已明确。
 
-- 若 spec 存在：读取 `CONTEXT.md`/`docs/adr/` 相关术语与决策，提取待覆盖行为清单（以验收标准为锚点）。
-- 若 spec 不存在：回退到 `README` + `--help` 输出倒推行为清单，但必须进入 Step ② 的清单确认关卡，不静默臆测。
+### ② 推导并确认实例
 
-完成：待覆盖行为清单已固定，无未澄清歧义。
+按 [`references/schema.md`](references/schema.md) 为每个行为生成实例草案：每个实例必须有溯源，不能用无来源的隐含行为扩张范围。向用户展示实例清单并等待一次确认；确认前不落盘。
 
-### ② 推导实例
+出口：实例清单已确认，每个实例字段完整且可追溯。
 
-按混合推导策略生成实例草案：
+### ③ 生成或更新
 
-- 以验收标准为锚点，需求/接口/边界为补充，可为 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 和实例 reference：
 
-完成：实例清单已获用户确认，每实例含溯源与完整四元组。
+- 写入 spec 的 SHA-256 `spec hash` 与 ISO `generatedAt`；
+- 保留 `<!-- manual -->` 保护段；
+- 新建直接生成；更新已有生成物时先展示 diff，用户确认后才覆盖；
+- 不把本次生成物写入 `template/`。
 
-### ③ 脚手架落盘
+出口：文件结构、指纹和人工段均符合 schema。
 
-按受控扩展模型写入定制 skill 目录：
+### ④ 结构验证
 
-- `SKILL.md`：执行语义（见下节「执行语义」）
-- `references/instances.md`：实例集（含溯源、必选+可选字段、头部 `spec hash` + `generatedAt`）
-- 不覆盖 `<!-- manual -->` 保护段；覆盖式更新需经用户确认；重生成时先给出 diff 建议，用户确认后才应用。
+生成后立即做快速、确定性的结构验证：文件存在、schema 字段、实例溯源、spec hash、`generatedAt`、manual 段保护和内部链接均通过后再报告成功。不默认执行完整实例集，不启动服务，不产生功能测试副作用。
 
-完成：定制 skill 目录已落盘，指纹正确，人工段受保护。
+出口：结构验证结果为 `PASS`，失败则报告具体 gap，不回滚生成物。
 
-### ④ 自验证
+## 可选行为验证
 
-落盘后立即按实例执行语义串行执行一轮实例集作自验证：
-
-- `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。
+仅当用户明确要求运行实例集时，才调用生成的功能测试 skill 执行隔离、串行的实例验证；届时按实例捕获 stdout/stderr、exit code 和 expected-vs-actual evidence，并由执行 skill 报告 `PASS m/n`。这不是 scaffold 的默认步骤。
 
 ## 不做什么
 
-- 不替代 `tdd`/`tdd-implement` 的红绿循环与 `commit-check` 门禁
-- 不自动织入每次 `tdd-implement` 或 `commit-check`；仅 `tdd-implement --with-functional` 显式 opt-in
+- 不替代生成后的功能测试 skill；
+- 不替代 `tdd`、`tdd-implement` 或 `commit-check`；
+- 不覆盖 `<!-- manual -->` 段，不静默重生成，不把 README/`--help` 推断写成无溯源实例。
 
 ## 引用
 
+- 实例 schema：[`references/schema.md`](references/schema.md)
 - 领域术语：`CONTEXT.md`
 - 技能设计规则：`docs/agents/skill-design.md`
-- 示范产物：`.agents/skills/instance-test/`（本仓库专属，见其 SKILL.md）
-- Issue tracker：`docs/agents/issue-tracker.md`
+- 示范产物：`.agents/skills/instance-test/`