@heihei0299/matt-skills 3.0.22 → 3.0.26

package/.agents/skills/research/SKILL.md

@@ -7,6 +7,18 @@ Spin up a **background agent** to do the research, so you keep working while it
 
 Its job:
 
+Before fetching remote pages, stage source ingestion:
+
+- Discover/search candidate sources.
+- Rank candidates by first-party authority and relevance.
+- Fetch only the 1–2 strongest sources initially; use a targeted page or section when supported.
+- Inspect those results and identify the remaining uncertainty.
+- Fetch another source only when it contributes independent evidence or resolves that uncertainty.
+- Stop fetching once the question has sufficient evidence.
+
+Do not fetch several URLs merely for coverage or flood one reasoning turn with uninspected output. Broader parallel collection remains valid when the user explicitly requests comprehensive literature coverage, multi-source fact verification, or a survey where breadth is itself the task; batch those sources when possible.
+
+
 1. Investigate the question against **primary sources** (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it.
 2. Write the findings to a single Markdown file, citing each claim's source.
 3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

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

@@ -8,7 +8,25 @@ disable-model-invocation: true
 
 完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能负责 issue 级实现、验证、证据记录与收尾编排。
 
-> Ticket defines WHAT. TDD determines HOW to prove it. Repository determines HOW to implement it.
+## Issue context scope
+
+Implementation context is current-issue scoped.
+
+At issue startup:
+1. Read the current issue body.
+2. Do not read future issue bodies.
+3. Future issues may be inspected only by compact metadata: ID, title, status, and dependency.
+4. Expand another issue only when the current issue explicitly depends on a contract that cannot otherwise be resolved.
+5. Read only the specific dependent section needed.
+
+If the complete active Skill content is already present in the current conversation, do not read the same Skill file again merely to confirm its rules.
+
+Re-read only when:
+- the conversation contains only a partial/summary copy;
+- the file is known to have changed during the session; or
+- the user explicitly requests a fresh read.
+
+This scope does not prohibit current-issue referenced specs, code required to implement the current issue, relevant tests, or a genuinely required dependency contract.
 
 ## 入口
 
@@ -34,7 +52,11 @@ Issue 状态使用 `ready`、`in_progress`、`verified`、`resolved`、`blocked`
 
 ### ② Verify
 
-读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
+执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
+
+- ticket 要求真实运行验证时，执行与验收目标匹配的实际验证；
+- 验证通过后不机械重复等价验证；
+- 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
 
 **出口：**当前 issue 所需最终验证通过，并完成要求的真实运行验证；状态进入 `verified`。
 
@@ -73,24 +95,10 @@ Rulings:
 
 读取 [finalize.md](references/finalize.md)。Finalize 只做当前 issue 的状态收敛和 tracker/progress/status 记录，不新增 Behavior、不修改产品实现、不补测试。
 
-**出口：**当前 issue 已 `resolved`，已满足的 blockers 已解除；仓库内状态变更进入 batch state-sync 集合。
-
-## Batch State Sync
-
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit。该 commit 不混入产品实现，也不属于任何单个 issue 的 `issue_base...issue_head` 范围。
+**出口：**当前 issue 已 `resolved`，已满足的 blockers 已解除。
 
 ## 运行纪律
 
-- Red-Green 必须覆盖当前 issue 的全部待实现 Behavior；Red-Green / Verify 不按 Behavior、阶段或验证动作拆 commit。
-- Verify 通过后形成当前 issue 唯一 delivery commit，再记录 evidence；Finalize 不创建实现 commit。
-- `tdd-implement` 不自动调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
 - 已有充分或等价证据时不重复搜索、读取或验证；后续 issue 优先消费 ledger 与 git history。
 - 只有外部阻塞、需要用户决策、destructive / irreversible 操作、安全敏感行为或 ticket/spec 已无法可靠解释时才暂停。
 - 当前 Step 达到出口后立即进入下一 Step；发现失败时保留实际状态，不把失败静默当作完成。
-
-## References
-
-- TDD：[tdd](.agents/skills/tdd/SKILL.md)
-- Verify：[verify.md](references/verify.md)
-- Finalize / State Sync：[finalize.md](references/finalize.md)
-- 多 issue 编排：[orchestration.md](references/orchestration.md)

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

@@ -1,23 +1,14 @@
 # Finalize
 
-仅在当前 issue 完成 Red-Green、Verify、delivery commit 和 Evidence Record 后执行。Finalize 只负责当前 issue 的状态收敛与 tracker/progress/status 记录，不新增产品 Behavior，不修改产品实现，不补测试。
+仅在当前 issue 完成 Red-Green、Verify、delivery commit 和 Evidence Record 后执行。Finalize 只负责当前 issue 的收尾检查与状态收敛，不新增产品 Behavior，不修改产品实现，不补测试。
 
 ## 步骤
 
-1. 确认当前 issue 的必要验证已通过，`issue_head` 已记录为 delivery commit，evidence ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
-2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态；外部 tracker 可在此同步，仓库内 tracker/progress/status 只记录为 batch 待同步状态。
+1. 确认当前 issue 的必要验证已通过，`issue_head` 仍指向 delivery commit，evidence ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
+2. 确认当前 issue 的实现、测试、交付文档和配置均已包含在 delivery commit 中。
 3. 若发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green 或 Verify。
 4. 仅在未发现上述遗漏后，将当前 issue 标记为 `resolved`，解除已满足的 blockers。
-5. Finalize 不创建 commit；设置最终 `issue_head = HEAD`。
-
-## Batch State Sync
-
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
-
-- 不混入产品实现、测试、交付文档或配置；
-- 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
-- 不因 issue 数量增加而拆成多个 status commits；
-- 不触发 `code-review`。
+5. Finalize 不创建 commit，也不改变 `issue_head`。
 
 ## 出口
 
@@ -25,6 +16,5 @@
 - 当前 issue 必要验证已通过；
 - delivery commit 与 evidence ledger 已记录；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
-- tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
-- `issue_head = HEAD`；
+- `issue_head` 仍指向 delivery commit；
 - issue 已 `resolved`，已满足的 blockers 已解除。

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

@@ -1,10 +1,12 @@
 # 多 issue 编排
 
-仅在存在多个 `Type: task` issue 时生效。每个 issue 都按 `Red-Green → Verify → Record → Finalize` 独立完成；本文件只负责依赖顺序与 batch state sync。
+仅在存在多个 `Type: task` issue 时生效。每个 issue 都按 `Red-Green → Verify → Record → Finalize` 独立完成；本文件只负责依赖顺序、失败关闭与 batch state sync。
 
 ## 1. 构建依赖图
 
-读取每个 issue 的 `Blocked by`：
+构建依赖图时，只提取各 issue 的调度元数据：ID、Status、Blocked by / dependency。
+不得为构建依赖图读取未来 issue 正文、Acceptance Criteria、实现说明或其它 body 内容。
+如果调度元数据位于独立 issue 文件中，使用定点搜索/范围读取只取得对应 metadata 字段；不要全文打开所有 future issue 文件。
 
 - 无依赖时视为可直接调度；
 - 引用了其它 issue 时建立依赖边；
@@ -20,42 +22,22 @@ for each dependency layer:
     issue_base = HEAD
     Red-Green
     Verify
-    Record
+    Record (delivery commit 后设置 issue_head = HEAD)
     Finalize
-    issue_head = HEAD
 ```
 
-- `Red-Green` 与 `Verify` 是当前 issue 的 correctness gate；
-- `Record` 形成当前 issue 唯一 delivery commit，设置 `issue_head` 并记录 evidence ledger；
-- `Finalize` 只收敛状态、解除已满足 blockers，并把仓库内 tracker/progress/status 变更加入 batch state-sync 集合；
-- Issue loop 不调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
-
 当前 issue Finalize 完成后，依赖它的 issue 才可进入可执行状态。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。
 
-## 3. 状态与证据
-
-每个完成 issue 只携带后续调度所需的最小状态：
-
-- `Status`；
-- `issue_base`；
-- `issue_head`；
-- Acceptance、TDD、Verify 和 Rulings evidence；
-- 已解除的 blockers。
-
-Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复研究前序 issue 已确认且已记录的事实；context compact 后优先使用 ledger 与 git history。Ledger 不保存完整测试输出，只保存命令/场景及结果。
-
-## 4. Batch State Sync
+## 3. Batch State Sync
 
 全部可执行 issue 完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit。该 commit：
 
 - 不混入产品实现、测试、交付文档或配置；
 - 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
 - 不因 issue 数量增加而拆成多个 status commits；
-- 不触发 `code-review`。
 
 ## 冲突与失败
 
-- `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告；
 - issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`；
 - 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定；
 - 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成；
@@ -65,6 +47,5 @@ Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复
 
 - 所有可执行 issue 均按依赖顺序完成并有 evidence ledger；
 - issue、依赖状态、Acceptance、Verify 与 progress 一致；
-- `tdd-implement` 的 `code-review` 调用次数为 0；
 - 不存在被误当作已完成的 blocked issue；
 - 仓库内状态同步如有需要，只形成最多 1 个 batch state-sync commit。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.22",
+  "version": "3.0.26",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -1,15 +1,17 @@
 ## Workflow
 按任务选择最匹配的 skill / 工具：
-* 代码理解 / 定位 / 调用链 / 依赖关系 / 数据流 → `codegraph explore`
+* 需要新增证据的代码理解 / 定位 / 调用链 / 依赖关系 / 数据流 → `codegraph explore`
 * 行为修改 / 功能实现 / bug 修复 / 逻辑调整 → `tdd`
 * 多来源调研 / 方案比较 / 技术选型 / 最佳实践 / 外部实现 → `research`
 `research` 仅用于多来源综合；单一资料、官方文档和实时事实直接查询。
 未命中 skill 时直接执行。明确不改变行为的文案、注释、格式和机械修改无需 `tdd`。
 仅当关键歧义无法从仓库事实解决，且会改变实现、范围、风险或验收结果时询问用户。
-## Context
+## Context / CodeGraph
 以当前代码、配置、测试和版本化文档为事实来源；更具体的项目指令优先。
-代码理解优先使用 `codegraph explore`；已锁定符号时使用 `codegraph node`。
-只获取完成任务所需的最小上下文；信息充分后停止探索。CodeGraph 不足时降级到 `rg` 和必要文件读取。
+- 有 issue/spec 时先读当前 issue；否则从用户问题和最相关 symbol/path 开始。
+- 只按当前未决问题逐步扩展上下文；README/package/tests/docs 按需读取。
+- 当前上下文已有充分且未过时的证据时，不做等价重复读取。
+- 当当前上下文不足、需要新增代码理解证据时，优先使用 `codegraph explore`；结果充分后不再 broad grep/read。
 实现时复用现有抽象、接口和依赖方向，不创建平行实现或无关扩展。
 ## Validation
 验证应足以证明修改正确且未破坏直接受影响行为。

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

@@ -1,15 +0,0 @@
-# Verify
-
-验证必须对应当前最终 diff；实现或测试变化后，只重新验证受影响证据。
-
-## 规则
-
-- 只验证当前 issue 的必要范围，不因进入 Verify 自动扩大验证范围。
-- ticket 要求真实运行验证时，执行与验收目标匹配的实际验证。
-- 验证通过后不机械重复等价验证。
-- 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
-
-## 出口
-
-- 当前 issue 的必要验证通过；
-- 要求的真实运行验证完成。