♻️ refactor(skills): standardize first-party skill contracts

upgrade commit-message, style-cleanup, and bulk-refactor-workflow
to use trigger-focused frontmatter and a shared contract structure.

add a first-party skill quality test gate and register it in tests
documentation.

skills/bulk-refactor-workflow/SKILL.md

@@ -1,65 +1,109 @@
 ---
 name: bulk-refactor-workflow
-description:
-  "Safe bulk refactors and mass edits across a repo (rename APIs, global
-  replacements, mechanical changes). Triggers: bulk refactor, mass edit, rename
-  symbol, global replace, 批量重构, 全局替换, 统一改名, 大范围修改."
+description: Use when renaming symbols, migrating APIs, or applying safe mechanical changes across many files in the repository.
 ---
 
 # Bulk Refactor Workflow（批量重构 / 大范围修改）
 
+## Overview
+
+Guide repository-wide mechanical edits without losing scope control or damaging
+unrelated work. Core principle: enumerate first, transform mechanically, verify
+in loops, and keep every batch auditable.
+
 ## When to Use
 
-- Rename API / symbol / file convention across many files
-- Mechanical refactors (imports, formatting, lint fixes, signature migrations)
-- Cross-cutting changes touching 10+ files
+- Rename APIs, symbols, file conventions, or repeated string patterns
+- Apply scripted or structural edits across many files
+- Migrate callers to a new interface where the change pattern is repeatable
 
-## Inputs（required）
+## When Not to Use
 
-- Scope：目录/文件类型/排除项（include/exclude）
-- Transformation：要做的规则（rename A→B、替换模式、接口迁移策略）
-- Constraints：是否允许行为变化？是否需要兼容期？是否允许自动格式化？
-- Verification：必须通过哪些命令/检查（最少一个）
+- One-off logic changes where no repeatable transformation exists
+- Exploratory redesign or feature work that needs new architecture decisions
+- Cleanup that is only formatting/lint alignment; use `style-cleanup` directly
 
-## Procedure（default）
+## Inputs
 
-1. **Baseline**
+- Scope: directories, file types, include/exclude rules
+- Transformation: rename, replace, codemod, scripted edit, migration strategy
+- Constraints: behavior-preserving vs. compatibility window vs. staged rollout
+- Verification commands: smallest useful loop plus final gate
 
-   - 确保工作区干净：`git status --porcelain`
-   - 跑一个基线验证（至少 build 或核心测试子集），避免“本来就坏”
+## Procedure
 
-2. **Enumerate**
+1. **Baseline and bound the scope**
 
-   - 先搜索再改：用 `rg`/`git grep` 列出全部命中
-   - 分类命中：真实调用 vs 注释/文档/样例；避免误改
+   - Record `git status --short`.
+   - Dirty worktrees are allowed.
+   - Do not revert unrelated changes.
+   - Mark the exact target file set before editing.
+   - Run a baseline verification command so existing failures are not misattributed
+     to the refactor.
 
-3. **Apply Mechanical Change**
+2. **Enumerate every intended hit**
 
-   - 优先使用确定性的机械变换（脚本/结构化编辑）而非手工逐个改
-   - 每轮改动后立即做小验证（编译/单测子集）
-   - 复杂迁移优先“两阶段”：先兼容旧接口（deprecated），再清理旧接口
+   - Search before editing with `rg`, `git grep`, or a structured query.
+   - Separate real code hits from comments, docs, generated files, and samples.
+   - Write down exclusions before running the transformation.
 
-4. **Format & Lint（按项目约定）**
+3. **Choose the safest mechanical transform**
 
-   - 仅在确认“会破坏 diff 可读性”前提下分批格式化（避免把重构和格式揉在一起）
+   - Prefer deterministic transforms: codemods, scripts, structured edits, or
+     narrow search/replace with explicit scope.
+   - If compatibility matters, use a staged migration: adapt providers first,
+     migrate callers second, remove compatibility layer last.
 
-5. **Verify & Report**
-   - 跑约定的验证命令并记录输出
-   - 汇总影响范围：改动文件数、主要改动点、潜在风险
+4. **Apply in bounded batches**
 
-## Execution Hint（optional）
+   - First, apply the transformation in bounded batches.
+   - Verify each batch before widening scope.
+   - Stop immediately if output differs from the expected hit class.
 
-如果环境支持“执行型批量处理”（例如脚本执行），优先用脚本完成批量修改，然后只把**最小 diff + 摘要**交付，避免上下文膨胀与漏改。
+5. **Verify in loops**
 
-## Output Contract（stable）
+   - Run the smallest relevant verification after each batch.
+   - Re-check the hit list after edits to confirm the intended pattern is gone and
+     unintended patterns were not introduced.
 
-- Scope：改动覆盖范围（文件/目录/语言）
-- Transformation：执行的规则（可复用）
-- Changes：关键改动摘要（按类别）
-- Verification：命令 + 证据（输出/退出码/产物）
-- Risks：高风险点与回滚建议
+6. **Finish with targeted cleanup**
+
+   - If the mechanical change leaves formatting or lint fallout, Use `style-cleanup` for the final formatting/lint pass.
+   - Keep that cleanup scoped to the refactor set unless the user approves a wider
+     pass.
+
+7. **Report**
+
+   - Summarize files touched, transform rules used, verification evidence, and any
+     residual risk.
+
+## Output Contract
+
+- `Scope:` files, directories, and exclusions actually used
+- `Transformation:` exact rule or script applied
+- `Batches:` how the work was partitioned
+- `Verification:` commands, exit status, and what each loop proved
+- `Risks:` remaining ambiguous areas, compatibility debt, or deferred cleanup
+
+## Success Criteria
+
+- Every changed file belongs to the declared scope
+- The transformation is reproducible and explainable
+- Verification passes at both batch level and final gate
+- Unrelated work in the repository is preserved
+
+## Failure Handling
+
+- If the hit list is ambiguous, stop and refine scope before editing
+- If the transform cannot be expressed mechanically, downgrade to a normal
+  refactor plan instead of pretending it is safe bulk work
+- If verification fails mid-batch, stop, inspect the smallest failing delta, and
+  correct the transform before continuing
+- If compatibility risk is higher than expected, split the migration into staged
+  commits or phases
 
 ## Guardrails
 
-- 任何“全局替换”都必须先给出命中清单与排除策略
-- 避免把行为重构与格式化/无关清理混在同一轮
+- Never run repository-wide replacement without an explicit hit review
+- Never mix unrelated cleanup into the same batch
+- Never hide a large-scope behavior change behind the label "mechanical refactor"