@heihei0299/matt-skills 1.3.1 → 1.3.3

package/template/.opencode/skills/scaffold-functional-test/SKILL.md

@@ -0,0 +1,77 @@
+---
+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
+- 不支持并行执行与 `docker` 隔离
+- 不处理超出混合推导锚点范围的源码静态分析隐式行为挖掘
+
+## 引用
+
+- 领域术语：`CONTEXT.md`
+- 技能设计规则：`docs/agents/skill-design.md`
+- 示范产物：`.agents/skills/instance-test/`（本仓库专属，见其 SKILL.md）
+- Issue tracker：`docs/agents/issue-tracker.md`

package/template/.opencode/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/template/.pi/CONTEXT.md

@@ -0,0 +1,55 @@
+# matt-skills
+
+The domain vocabulary for this repo — two sections: how this repository is positioned (`## Repository`) and the terms that govern how long-horizon skills are written, reviewed, and evolved (`## Skill Design`). Every term here is a single source of truth; skills and docs reference it rather than restating the definition.
+
+## Repository
+
+**Template Repository** (模板仓库):
+This repository's identity. It is the config repo for mattpocock/skills: it distributes project-level config (AGENTS.md behavior routing, `.opencode/docs/agents/` discipline files, `.opencode/CONTEXT.md` glossary) plus only the Proprietary Skills, not the upstream skill copies. The workspace content is mirrored into `template/` as a Template Snapshot, and initializing a Target Repository is a one-time copy of that snapshot. The workspace copy also serves this repo's own sessions.
+_Avoid_: skill distribution repo
+
+**Upstream Repository** (上游仓库):
+mattpocock/skills — the source of the 22 skill bodies (skills/engineering, 17 skills; skills/productivity, 5 skills) that target repos fetch manually per the README. This repo never copies upstream skills into `template/`.
+_Avoid_: source repo, skill origin
+
+**Proprietary Skill** (独有技能):
+A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check and scaffold-functional-test). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The issue-audit subagent is NOT a skill: it ships as a subagent + command under `.opencode/` and is distributed through the Template Snapshot without a skill directory.
+_Avoid_: private skill, local skill
+
+**Workspace** (工作区):
+The root-level working copies of the template content — `.agents/skills/` (proprietary skill sources), `.opencode/` (issue-audit agent, explicit-skill commands, plugin manifests), `.pi/` (pi-agent project config: `.pi/skills/` + `.pi/prompts/` issue-audit command), `AGENTS.md`, `CONTEXT.md`, `docs/`. Where this repo's own sessions load, modify, and test the content. The template paths mirror them with a path mapping: `.agents/skills/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}` → `template/.opencode/skills/` and `template/.pi/skills/` (dual mirror), `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/`.
+_Avoid_: working copy, source repo
+
+**Template Snapshot** (模板快照):
+Everything under `template/` — the mirror of the workspace content with the path mapping above (proprietary skills land under `.opencode/skills/` and `.pi/skills/`, opencode commands under `.opencode/commands/`, the pi issue-audit command under `.pi/prompts/`, discipline files and glossary under `.opencode/`, AGENTS.md at the top level), generated by manual sync, used to initialize other repositories. There is no release pipeline; the sync direction is one-way: workspace → snapshot. `test/template-sync.test.js` guards the mirror stays in sync.
+_Avoid_: release snapshot, published snapshot
+
+**Target Repository** (目标仓库):
+A repository initialized by copying `template/` into its root and then fetching the upstream skills per the README. It then loads the upstream skills from its own `.agents/skills/`, the Proprietary Skills from `.opencode/skills/` (directly under opencode) and `.pi/skills/` (auto-discovered under pi), the explicit-skill commands from `.opencode/commands/` (opencode) and the `issue-audit` command from `.pi/prompts/` (pi) / `.opencode/commands/` (opencode), and the project-level global config from `.opencode/` and `AGENTS.md`.
+_Avoid_: inheriting repo, child repo
+
+**Initialize** (初始化):
+The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`), then fetching the 22 upstream skills from the Upstream Repository. Copying, not inheriting — no runtime relationship survives the copy.
+_Avoid_: inherit, bootstrap
+
+**Sync** (同步):
+`matt-skills sync` 同步 Target Repository 的模板与上游技能：默认仅对比不写盘（`check`），`--apply` 为安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，上游技能直接强制覆盖 `rm+cp` 但不 `remove`，独有技能与 `template/.opencode/.pi` 增量 `add/update`）、`--force` 为硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板全量 `add/update/remove`）。`update` 已合并到 `sync` 并删除。
+_Avoid_: update, force sync
+
+## Skill Design
+
+**Turn Continuity** (回合连续性):
+The rule that a long-horizon skill must carry a positive instruction to keep executing within a turn — red → green → typecheck → next seam serial in one turn until the stage's exit condition is met. The stage exit is reached when all of its seams are complete — one seam going green is not an exit, and progress output does not itself end the turn. It is the skill's own guard against premature turn-end; it must not rely on the harness `/goal` line (which does not exist when no `/goal` is active).
+_Avoid_: keep going, don't stop
+
+**Chunking** (拆小步 / 进度编排):
+Splitting a giant turn — one large `write` or a batch of `replace`s — into small steps that are individually verified before continuing, so the turn never hits output caps and gets truncated mid-work.
+_Avoid_: step-by-step, take it slow
+
+**Git History Preservation** (Git 历史保护):
+Every git-touching skill must preserve history after `BASE_HEAD=$(git rev-parse HEAD)` recorded at stage entry — history may only be appended. Before any commit or stage exit, verify `git merge-base --is-ancestor $BASE_HEAD HEAD`; if it fails, history was rewritten and must be recovered via `git reflog` before continuing. "Directory clean" (`git status` clean) may only be achieved by deleting the skill's own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files); destructive git commands `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked`, `git push --force`, `git rebase -i` are forbidden without explicit user confirmation.
+_Avoid_: force clean, stash all
+
+**Long-Horizon Skill** (长程多阶段技能):
+A skill whose run spans multiple stages or seams executed continuously (e.g. tdd-implement, diagnosing-bugs, improve-codebase-architecture, wayfinder, grill-to-spec, to-spec). The class of skill that must carry a Turn Continuity rule.
+_Avoid_: complex skill, big skill

package/template/.pi/docs/agents/runtime-discipline.md

@@ -1,6 +1,6 @@
 # Runtime Discipline
 
-本仓库会话的运行时纪律，执行口径源自 `.opencode/docs/agents/skill-design.md` 的三条规则（规范正文）。术语定义见 `.opencode/CONTEXT.md`。
+本仓库会话的运行时纪律，执行口径源自 `docs/agents/skill-design.md` 的四条规则（规范正文）。术语定义见 `CONTEXT.md`。
 
 ## 回合连续性规则
 
@@ -11,7 +11,7 @@
 - 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
 - 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
 
-预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.opencode/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.agents/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
 
 ## 运行纪律（长程任务）
 
@@ -20,6 +20,7 @@
 - **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
 - **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
 - **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
+- **Git 历史保护（Git History Preservation）**：任何触及 git 的操作必须追加历史、不可改写丢弃。阶段入口记录 `BASE_HEAD=$(git rev-parse HEAD)`，阶段出口与 commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才继续。"目录卫生"仅删本次产生的 `[DEBUG-...]`/一次性脚本等未跟踪临时文件，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认）。
 
 ## 执行原则（细则）
 

package/template/.pi/docs/agents/skill-design.md

@@ -1,18 +1,17 @@
 # Skill Design Spec
 
-The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../../.opencode/CONTEXT.md) — reference them there, never restate the definition.
-
-This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The three rules below are the preventive measures that came out of that diagnosis. They are repo rules, not advice.
+The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../CONTEXT.md) — reference them there, never restate the definition.
 
+This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The four rules below are the preventive measures that came out of that diagnosis and subsequent git-history incidents (see `docs/adr/0003-git-history-preservation.md`). They are repo rules, not advice.
 ## Rule 1 — Turn Continuity
 
 Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
 
-- State it **positively** (per the negation principle in `writing-great-skills`): describe the target behaviour, never the banned one.
+- State it **positively** (per the negation principle in `writing-for-agents`): describe the target behaviour, never the banned one.
 - It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
 - Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
 - A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
-- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](../../skills/tdd-implement/references/stages.md) stage ③.
+- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③.
 
 ## Rule 2 — Model Selection
 
@@ -26,7 +25,13 @@ Giant turns — a single `write` of a large file, or a batch `replace` of a hund
 - A batch of more than ~5 `replace`s: split into batches and verify after each batch.
 
 These thresholds are experience defaults; adjust them as practice shows better values.
+## Rule 4 — Git History Preservation
+
+Every skill that touches git must preserve history after `BASE_HEAD`: history may only be appended, never rewritten or dropped. The skill must record `BASE_HEAD=$(git rev-parse HEAD)` at stage entry, and verify `git merge-base --is-ancestor $BASE_HEAD HEAD` at every stage exit and before any commit — failure means history was rewritten and the skill must recover via `git reflog` before continuing.
+
+To achieve "directory clean" (`git status` clean) the skill may only delete its own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files) — it must never use git-level destructive commands to reach a clean state. The following are forbidden without explicit user confirmation: `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked` (use `--keep-index` instead and `pop` with verification), `git push --force`, `git rebase -i` and any `reset`/`checkout` that moves `HEAD` backward.
 
+Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](.agents/skills/commit-check/SKILL.md) ③ 目录卫生.
 ## Long-horizon skills inventory
 
 Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — new orchestration skill for diagnosis + TDD fix, carries its own Turn Continuity rule), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec`, `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

package/template/.pi/skills/ci-guard/SKILL.md

@@ -0,0 +1,104 @@
+---
+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`，避免同分支并行互踩
+- `cache`：`rust-cache` 或 `actions/cache` 缓存 `~/.cargo` + `target`，`actions/setup-node` 加 `cache: npm`，避免每次 `npm install` 重装
+- `find changed Rust files`：`git diff origin/main...HEAD` 在 tag 事件下为空，改为 `git diff --name-only HEAD~1...HEAD` 或直接全量 `cargo fmt --check` / `clippy`，避免误跳过
+
+**完成条件**：
+- [ ] `git diff HEAD -- .github/workflows/ci.yml` 显示 `on.push.branches` 存在
+- [ ] `publish.needs` 包含 `verify`
+- [ ] `workflow_dispatch` 可手动触发全量
+
+---
+
+### ② 预发布 gate —— 在写盘之前变红
+
+本段是**硬门槛**，顺序固定：`fmt → clippy → test → build`，任一步红即阻断 `publish`。
+
+**fmt / clippy**：
+- `rustfmt --check` 与 `cargo clippy --all-targets -- -D warnings` 必须与本地一致（`rust-toolchain.toml` 锁定 `stable` 版本）
+- 允许的 `-A` 必须显式列出（如本仓 `-A clippy::manual_checked_ops` 等 4 项），不批量 `-A clippy::all`
+
+**test（关键）**：
+- 落盘测试（如 `web::tests` 直写 `config.json` / `models.json`）**必须**测试隔离：`config_dir()` / `pi_dir()` / `models_path()` 在 `#[cfg(test)]` 下重定向到 `temp/pi-switch-test-<pid>`（参考 `src-rust/proxy.rs:115 init_test_state_dir()`，`config.rs:460` 为未隔离反例；曾用 `PI_SWITCH_CONFIG_DIR` 环境覆盖后被 `20f6f86` 误删，即回归）
+- 若暂未隔离，CI 侧以 `cargo test --release --lib -- --test-threads=1` 串行化为**过渡**（`2d68f62` 方案，322/322 稳定），并在代码侧记录 `TODO(ci-guard): 恢复 config_dir 测试隔离后去掉 --test-threads=1`
+- `verify` 必须跑 `cargo test --lib`（或 `--release --lib` 与发布一致），不跳过；`build` 矩阵 5 目标仅验编译，不代验测试
+
+**完成条件**：
+- [ ] 本地 `cargo test --lib -- --test-threads=1` 322/322 且 `cargo test --lib`（并行）亦 322/322 或已记录隔离 TODO
+- [ ] `cargo clippy --all-targets` 0 warning
+- [ ] `npm run build:webui` 在 `verify` 与 `build` 均执行（本仓 WebUI 缺失会导致 `publish` 产物不一致）
+
+---
+
+### ③ 发布后自纠 —— 发出去的包自己负责
+
+**发布时**：
+- `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
+- **真实落盘并行测试**：无 `#[cfg(test)]` 隔离的 `config_dir` 直写是偶发红的根因，`--test-threads=1` 只是止血
+- **静默发布**：`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`（测试隔离后的回归）
+
+## 执行清单（粘贴即用）
+
+```markdown
+- [ ] .github/workflows/ci.yml: on.push.branches: [main] 已加
+- [ ] publish.needs: [build, verify]
+- [ ] verify: cargo test --release --lib -- --test-threads=1（或已隔离则去掉该 flag）
+- [ ] config.rs: #[cfg(test)] config_dir/pi_dir → temp（或 TODO 已记录）
+- [ ] workflow_dispatch 可手动触发
+- [ ] npm view 回读 + 失败建 issue
+```

package/template/.pi/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/template/.pi/skills/scaffold-functional-test/SKILL.md

@@ -0,0 +1,77 @@
+---
+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
+- 不支持并行执行与 `docker` 隔离
+- 不处理超出混合推导锚点范围的源码静态分析隐式行为挖掘
+
+## 引用
+
+- 领域术语：`CONTEXT.md`
+- 技能设计规则：`docs/agents/skill-design.md`
+- 示范产物：`.agents/skills/instance-test/`（本仓库专属，见其 SKILL.md）
+- Issue tracker：`docs/agents/issue-tracker.md`

package/template/.pi/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/template/AGENTS.md

@@ -37,10 +37,10 @@
 - 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
 - 诊断 → diagnose-fix（编排 diagnosing-bugs 诊断 + tdd 修复，修复环节强制 TDD）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（审查文档 + 对齐 README + 目录卫生 + commit message）
 - 分诊 → triage；架构扫描 → improve-codebase-architecture；综合 spec → to-spec；拆票 → to-tickets
-- 教学 → teach；交接 → handoff；技能写作 → writing-great-skills
+- 教学 → teach；交接 → handoff；技能写作 → writing-for-agents
 - 兜底 → ask-matt；模板维护 → README.md
 
-显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-great-skills
+显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
 
 ## 分文件
 
@@ -53,7 +53,6 @@
 
 仓库被 CodeGraph 索引（根目录存在 `.codegraph/`）时，理解/定位代码**优先于** grep/find/读文件——一次调用拿到相关符号源码与调用路径：
 
-- **CLI**（首选）：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码。
-- **MCP 工具**（可用时补充）：`codegraph_explore` 输出与 CLI 相同；若列出但延迟加载，用工具搜索按名加载。
+- **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码。
 
 没有 `.codegraph/` 目录则完全跳过 CodeGraph——是否建立索引由用户决定。