pi-shepherd 0.1.1 → 0.2.0

package/rules.json

@@ -20,7 +20,7 @@
 				"flags": ""
 			}
 		],
-		"reason": "编辑了 Python 文件，必须：1) 运行 ruff check <file> 做格式检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
+		"reason": "编辑了 Python 文件，必须：1) 运行 ruff check <file> 做格式检查；2) 验证测试——迭代场景用 fast 档 `uv run python scripts/run_test_gate.py --fast`（按 diff 只跑受影响子项目，分钟级反馈）；change 收尾/宣称「全量测试通过」SHALL 跑全量 `uv run python scripts/run_test_gate.py`（fast 凭证 .test-gate-fast-state.json 不属于全量绿证据）。",
 		"enabled": true
 	},
 	{
@@ -34,13 +34,13 @@
 				"pattern": "(>>|>|tee|sed\\s+-i|cp\\s|mv\\s).*settings\\.json|settings\\.json\\s*(>>|>)"
 			}
 		],
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
+		"reason": "直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具（自动备份+文件锁+校验），或 settings_rollback 回滚。",
 		"enabled": true
 	},
 	{
-		"comment": "[Rust] 编辑后必须格式检查 + 跑测试",
+		"comment": "[Rust] 编辑/写入后必须格式检查 + 跑测试",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -50,27 +50,12 @@
 			}
 		],
 		"reason": "编辑了 Rust 文件，必须：1) 运行 cargo clippy 做格式和 lint 检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
-	},
-	{
-		"comment": "[Rust][write] 写入后必须格式检查 + 跑测试",
-		"hook": "tool_result",
-		"tool": "write",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.rs$",
-				"flags": ""
-			}
-		],
-		"reason": "写入了 Rust 文件，必须：1) 运行 cargo clippy 做格式和 lint 检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
+		"enabled": false
 	},
 	{
-		"comment": "[TypeScript] 编辑后必须跑测试",
+		"comment": "[TypeScript] 编辑/写入后必须跑测试",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -83,41 +68,33 @@
 		"enabled": true
 	},
 	{
-		"comment": "[TypeScript][write] 写入后必须跑测试",
-		"hook": "tool_result",
-		"tool": "write",
+		"comment": "[arch] 会话结束前检查 git 状态（已停用：多会话并行时仓库级 git_dirty 误伤其他会话任务，收尾检查移入 opsx-archive 归档流程）",
+		"hook": "agent_end",
+		"check": "",
 		"action": "notify",
+		"reason": "Git 检测到未提交或未跟踪的文件。收尾时请确认：\n1. git add + commit（必须带 session ID）\n2. 如有重要决策/发现 → 更新记忆文件",
+		"enabled": false,
+		"subagent": false,
 		"conditions": [
 			{
-				"field": "path",
-				"pattern": "\\.ts$",
-				"flags": ""
+				"builtin": "git_dirty"
+			},
+			{
+				"builtin": "git_untracked"
 			}
 		],
-		"reason": "写入了 TypeScript 文件，必须跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
-	},
-	{
-		"comment": "收尾规则 — agent_end 时提醒 commit + 记忆 + 总结，commit 必须带 session ID",
-		"hook": "agent_end",
-		"action": "notify",
-		"check": "has_edits",
-		"reason": "⚠️  shepherd: 检测到文件编辑，执行收尾工作：\n1️⃣ **Git commit**：如有未提交的 git 改动 → git add + git commit。**⚠️ commit message 末尾必须加 `session:${PI_SESSION_ID}`** — 这是硬性要求，不是建议。session ID 用于会话分析和 roadmap 追踪，缺少会导致无法追溯。格式示例：`feat: xxx session:019e71c9-b340-7fae-a330-98d837e72099`\n2️⃣ **记忆更新**：如有值得记住的知识 → memory_update\n3️⃣ **会话总结**：简要总结本次会话做了什么",
-		"stopReason": [
-			"stop"
-		],
-		"enabled": true
+		"conditionLogic": "or"
 	},
 	{
-		"comment": "[memory] git commit 后提醒更新记忆",
+		"comment": "[memory] git commit 后提醒更新记忆（已停用：记忆更新检查移入 opsx-archive 归档流程收口）",
 		"hook": "tool_result",
 		"tool": "bash",
 		"pattern": "git\\s+commit",
 		"action": "steer",
-		"reason": "📝 刚执行了 git commit。检查本轮是否有值得跨会话保留的知识（架构决策、踩坑教训、结论），如果有 → 用 memory_update 工具写入。用法：①先调 memory_index 看已有文件，判断重复/合并/新建；②调 memory_update(fileName, content, scope) 一步写入文件+更新索引。fileName 格式：topic--kw1,kw2,kw3.md。scope：L1=跨项目通用，L2=项目级（默认）。单文件不超 200 行。如果没有新知识则忽略。",
+		"reason": "📝 刚执行了 git commit。请检查：**记忆更新** — 是否有值得跨会话保留的知识（架构决策、踩坑教训、结论），如果有 → 用 memory_update 写入。用法：①先调 memory_index 看已有文件；②调 memory_update(fileName, content, scope) 一步写入。fileName 格式：topic--kw1,kw2,kw3.md。scope：L1=跨项目通用，L2=项目级（默认）。单文件不超 200 行。如不需要则忽略。",
 		"subagent": false,
 		"requireSuccess": true,
-		"enabled": true
+		"enabled": false
 	},
 	{
 		"comment": "[arch] enforce-read-over-bash-cat：bash 中 cat|head/tail 读文件时强制用 read 工具",
@@ -142,65 +119,33 @@
 		"subagent": false
 	},
 	{
-		"comment": "[dev] 编辑扩展代码时提醒参考规范",
-		"hook": "tool_result",
-		"tool": "edit",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
-			}
-		],
-		"action": "steer",
-		"reason": "📝 编辑了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
-		"requireSuccess": true,
-		"subagent": false,
-		"enabled": true
-	},
-	{
-		"comment": "[dev] 写入扩展代码时提醒参考规范",
+		"comment": "[dev] 编辑/写入扩展代码时提醒参考规范",
 		"hook": "tool_result",
-		"tool": "write",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
-			}
-		],
-		"action": "steer",
-		"reason": "📝 写入了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
-		"requireSuccess": true,
-		"subagent": false,
-		"enabled": true
-	},
-	{
-		"comment": "[dev] 编辑扩展代码后提醒跑 typecheck",
-		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
+				"pattern": "extensions[/\\\\].*\\.ts$"
 			}
 		],
 		"action": "steer",
-		"reason": "📝 编辑了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
+		"reason": "📝 编辑/写入了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
 		"requireSuccess": true,
 		"subagent": false,
 		"enabled": true
 	},
 	{
-		"comment": "[dev] 写入扩展代码后提醒跑 typecheck",
+		"comment": "[dev] 编辑/写入扩展代码后提醒跑 typecheck",
 		"hook": "tool_result",
-		"tool": "write",
+		"tool": "edit|write",
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
+				"pattern": "extensions[/\\\\].*\\.ts$"
 			}
 		],
 		"action": "steer",
-		"reason": "📝 写入了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
+		"reason": "📝 编辑/写入了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
 		"requireSuccess": true,
 		"subagent": false,
 		"enabled": true
@@ -208,25 +153,7 @@
 	{
 		"comment": "[TS] 禁止空格缩进 — TS 文件必须用 Tab",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.ts$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n  [\\S ]"
-			}
-		],
-		"reason": "❌ TS 文件要求 Tab 缩进，不是空格。请用 Tab 缩进重写代码。",
-		"enabled": true
-	},
-	{
-		"comment": "[TS][write] 禁止空格缩进 — TS 文件必须用 Tab",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -244,25 +171,7 @@
 	{
 		"comment": "[Python] 禁止 Tab 缩进 — Python 必须用 4 空格",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.py$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n\\t"
-			}
-		],
-		"reason": "❌ Python 文件禁止 Tab 缩进，必须用 4 空格（PEP 8）。",
-		"enabled": true
-	},
-	{
-		"comment": "[Python][write] 禁止 Tab 缩进 — Python 必须用 4 空格",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -280,25 +189,7 @@
 	{
 		"comment": "[Rust] 禁止 Tab 缩进 — Rust 必须用 4 空格",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.rs$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n\\t"
-			}
-		],
-		"reason": "❌ Rust 文件禁止 Tab 缩进，必须用 4 空格（rustfmt）。",
-		"enabled": true
-	},
-	{
-		"comment": "[Rust][write] 禁止 Tab 缩进 — Rust 必须用 4 空格",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -320,7 +211,7 @@
 		"action": "notify",
 		"pattern": ".",
 		"flags": "s",
-		"reason": "推荐用 code-graph 替代 grep 搜代码——code-graph 理解 AST 语义，能按符号名、调用链、引用关系精准定位，比 grep 逐行匹配快得多且不漏不误报。选工具方法：①模糊搜索 → semantic_code_search（默认首选）；②精确符号名 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph；⑤模块结构 → module_overview。grep 仅适合搜字面量字符串（TODO、配置值、错误消息）。如果当前搜索的就是字面量字符串则忽略此提醒。如果目标目录没有被 code-graph 索引（搜索返回空结果），调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引。",
+		"reason": "推荐用 code-graph 替代 grep 搜代码——理解 AST 语义，按符号名、调用链、引用关系精准定位。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用 → find_references；④调用链 → get_call_graph；⑤模块结构 → module_overview。grep 仅适合字面量（TODO、配置值），搜字面量则忽略此提醒。\n\n**涉及字段血缘/数据链路类任务？** → 使用 field-lineage 技能。\n\n**code-graph 故障排查：**\n- **搜不到东西？** → 可能是目标目录没索引。用 `code_graph_project_map()` 查看当前索引范围，不在范围内就调 `setup_codegraph({ directory: \"目标目录绝对路径\" })` 一键建索引（创建软链接+增量索引，即时可搜）。\n- **路径报错 `must be relative`？** → path 参数必须用相对路径（相对于 CWD），不能用绝对路径。\n- **刚改了代码搜不到？** → 索引可能过期，调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引（已索引目录重复调用有效，增量更新）。\n- **确实没有结果** → 忽略以上提醒，可能是符号确实不存在。",
 		"requiresTools": [
 			"code_graph_semantic_code_search"
 		],
@@ -333,7 +224,7 @@
 		"action": "notify",
 		"pattern": "\\b(grep|rg)\\b.*\\.(py|rs|ts|js|toml)(?=[\\s'\"|)]|$)",
 		"flags": "",
-		"reason": "💡 bash grep 搜代码文件不如用 pi 内置 grep 工具或 code-graph MCP 工具——code-graph 理解 AST 语义，能精准匹配符号名和调用关系。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph。如果搜的是字面量字符串（TODO、配置值）则忽略。如果目标目录没有被 code-graph 索引，调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引。",
+		"reason": "💡 bash grep 搜代码文件不如用 pi 内置 grep 工具或 code-graph MCP 工具——code-graph 理解 AST 语义，能精准匹配符号名和调用关系。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph。如果搜的是字面量字符串（TODO、配置值）则忽略。\n\n**code-graph 故障排查：**\n- **搜不到东西？** → 可能是目标目录没索引。用 `code_graph_project_map()` 查看当前索引范围，不在范围内就调 `setup_codegraph({ directory: \"目标目录绝对路径\" })` 一键建索引。\n- **路径报错？** → path 参数必须用相对路径（相对于 CWD），不能用绝对路径。\n- **刚改了代码搜不到？** → 调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引。",
 		"enabled": true
 	},
 	{
@@ -347,13 +238,13 @@
 				"pattern": "\\.(ts|js|py|rs)$"
 			}
 		],
-		"reason": "💡 搜代码文件推荐用 code-graph。如果 code-graph 返回空结果，可能是目标目录没有被索引。调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引（软链接+增量索引，当前会话即刻可搜）。用法参考 code-graph 技能：semantic_code_search（模糊搜索）、get_ast_node（精确符号）、get_call_graph（调用链）、module_overview（模块结构）。",
+		"reason": "💡 搜代码文件推荐用 code-graph。如果 code-graph 搜不到，排查步骤：\n1. `code_graph_project_map()` 查看当前索引了哪些目录\n2. 不在范围内 → `setup_codegraph({ directory: \"目标目录绝对路径\" })` 建索引\n3. 路径报错 → 用相对路径，不用绝对路径\n4. 刚改过代码 → `setup_codegraph({ directory: \"项目路径\" })` 重建索引\n用法：semantic_code_search（模糊搜索）、get_ast_node（精确符号）、get_call_graph（调用链）、module_overview（模块结构）。",
 		"enabled": true
 	},
 	{
-		"comment": "[deps] 编辑 package.json 时提醒依赖合规检查",
+		"comment": "[deps] 编辑/写入 package.json 时提醒依赖合规检查",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -364,20 +255,6 @@
 		"reason": "📦 编辑了 package.json 依赖字段。请对照 DEPENDENCY-GUIDE.md 检查合规性：① pi SDK 必须放 peerDependencies + optionalDependencies，禁止放 dependencies/devDependencies；② shared-utils 运行时引用放 dependencies（开发放 devDependencies）；③ 检查 files 白名单是否存在；④ 添加新依赖后运行 scan-deps.sh 验证无嵌套/版本冲突。",
 		"enabled": true
 	},
-	{
-		"comment": "[deps][write] 写入 package.json 时提醒依赖合规检查",
-		"hook": "tool_result",
-		"tool": "write",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "package\\.json$"
-			}
-		],
-		"reason": "📦 写入了 package.json 依赖字段。请对照 DEPENDENCY-GUIDE.md 检查合规性：① pi SDK 必须放 peerDependencies + optionalDependencies，禁止放 dependencies/devDependencies；② shared-utils 运行时引用放 dependencies（开发放 devDependencies）；③ 检查 files 白名单是否存在；④ 添加新依赖后运行 scan-deps.sh 验证无嵌套/版本冲突。",
-		"enabled": true
-	},
 	{
 		"comment": "[通用] 脚本执行失败时提醒先 --help",
 		"hook": "tool_result",
@@ -394,9 +271,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[roadmap] 禁止直接编辑 roadmap JSON — 必须用 roadmap 工具",
+		"comment": "[roadmap] 禁止直接编辑/写入 roadmap JSON — 必须用 roadmap 工具",
 		"hook": "tool_call",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "block",
 		"conditions": [
 			{
@@ -405,112 +282,214 @@
 			}
 		],
 		"reason": "⛔ 禁止直接编辑 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接改 JSON 会绕过这些机制导致数据不一致。",
-		"enabled": true
+		"enabled": false
 	},
 	{
-		"comment": "[roadmap] 禁止直接写入 roadmap JSON — 必须用 roadmap 工具",
+		"comment": "[roadmap] 禁止通过 bash/python 脚本直接读写 roadmap JSON — 必须用 roadmap 工具",
 		"hook": "tool_call",
-		"tool": "write",
+		"tool": "bash",
 		"action": "block",
 		"conditions": [
 			{
-				"field": "path",
-				"pattern": "\\.roadmap\\.json$|\\broadmap/roadmap\\.json$"
+				"field": "command",
+				"pattern": "((roadmap\\.json|\\.roadmap\\.json)[\\s\\S]*(open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat))|((open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat)[\\s\\S]*(roadmap\\.json|\\.roadmap\\.json))"
 			}
 		],
-		"reason": "⛔ 禁止直接写入 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接改 JSON 会绕过这些机制导致数据不一致。",
-		"enabled": true
+		"reason": "⛔ 禁止通过 bash/python 脚本直接读写 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接碰底层 JSON 会绕过这些机制导致数据不一致。",
+		"enabled": false
 	},
 	{
-		"comment": "[roadmap] 禁止通过 bash/python 脚本直接读写 roadmap JSON — 必须用 roadmap 工具",
-		"hook": "tool_call",
-		"tool": "bash",
 		"action": "block",
+		"comment": "[settings] 禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
 		"conditions": [
 			{
 				"field": "command",
-				"pattern": "((roadmap\\.json|\\.roadmap\\.json)[\\s\\S]*(open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat))|((open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat)[\\s\\S]*(roadmap\\.json|\\.roadmap\\.json))"
+				"pattern": "^(?!.*\\b(git|grep|find|ls|cat|head|tail|diff|test|python3.*json\\.load)\\b).*settings\\.json",
+				"flags": "s"
 			}
 		],
-		"reason": "⛔ 禁止通过 bash/python 脚本直接读写 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接碰底层 JSON 会绕过这些机制导致数据不一致。",
-		"enabled": true
+		"hook": "tool_call",
+		"message": "⛔ 禁止通过 bash 修改 settings.json！使用 settings_patch 工具安全修改（支持全局 scope='global' 和项目级 scope='project'），或 settings_rollback 回滚。",
+		"reason": "禁止通过 bash 直接写入 settings.json（如 echo > / sed -i / python 写入），但允许 git 操作（status/diff/reset/checkout/restore/add/rm/log）和只读命令（grep/find/ls/cat/head/tail/diff/test/python3 解析读取）。必须使用 settings_patch 工具。",
+		"tool": "bash",
+		"enabled": false
 	},
 	{
-		"comment": "[GDScript] 编辑 .gd 文件后提醒写/跑 GUT 测试",
-		"reason": "跟 Python/Rust/TS 规则一致——编辑代码后提醒补充单元测试。触发条件：edit 工具的 file 参数匹配 .gd 扩展名。提醒内容：是否有对应的 GUT 测试？如果没有，建议补写。如果有，提醒跑 run_unit_tests.sh 验证。",
-		"trigger": {
-			"tool": "edit",
-			"event": "tool_result",
-			"match": "\\.gd$"
-		},
-		"action": "notify"
+		"comment": "[git] commit 成功后提醒 push",
+		"reason": "项目已有远程仓库 origin，commit 后应同步推送避免本地积压",
+		"trigger": "bash",
+		"event": "tool_result",
+		"condition": "bash command contains 'git commit' and exit code is 0",
+		"action": "notify",
+		"message": "commit 成功。检查是否有远程仓库（git remote），有的话立即 git push 同步到远程。"
+	},
+	{
+		"comment": "[arch] 编辑 YAML 规则后提醒同步安全网",
+		"hook": "tool_result",
+		"tool": "edit|write",
+		"action": "steer",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "docs[/\\\\]agent[/\\\\]api[/\\\\].*\\.yaml$"
+			}
+		],
+		"reason": "📝 架构 artifacts YAML 已变更！请执行以下闭环步骤：\n1. python scripts/govern_sync.py --preview（预览安全网变化）\n2. python scripts/govern_sync.py --apply（应用更新）\n3. python scripts/govern_check.py（验证闭环完整性）",
+		"enabled": false,
+		"subagent": false
 	},
 	{
+		"comment": "[quality] 大量代码编辑后提醒运行治理检查",
+		"hook": "tool_result",
+		"tool": "edit|write",
 		"action": "notify",
-		"comment": "[GDScript][write] 写入 .gd 文件后提醒写/跑 GUT 测试",
-		"reason": "跟 edit 规则配对。新建 .gd 文件时提醒创建对应的测试文件。",
-		"trigger": {
-			"event": "tool_result",
-			"match": "\\.gd$",
-			"tool": "write"
-		}
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "src[/\\\\].*\\.rs$"
+			}
+		],
+		"reason": "📝 编辑了源码。请确认：\n1. cargo clippy --all-targets -- -D warnings\n2. cargo test\n3. bash scripts/check_arch.sh（架构合规）\n4. python scripts/govern_check.py（治理健康度）",
+		"enabled": false,
+		"subagent": false
 	},
 	{
-		"comment": "[settings] 禁止 edit settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119 行变 3 行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
-		"tool": "edit",
-		"hook": "tool_call",
-		"action": "block",
-		"message": "⛔ 禁止直接 edit settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
+		"comment": "[roadmap] 读计划文件时提醒标记 task 为 doing",
+		"hook": "tool_result",
+		"tool": "read",
+		"action": "steer",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "\\.pi[/\\\\]plans[/\\\\].*\\.md$"
+			}
+		],
+		"reason": "📖 你正在读取计划文件，说明即将开始执行某个 Task。请在开始编码之前先用 roadmap_update(roadmapId, taskId, {status: 'doing'}) 将对应 Task 标记为 🔄 doing，这样其他会话能看到你正在做什么，避免冲突。如果已经标记过则无视。",
+		"subagent": false,
+		"requireSuccess": true,
+		"enabled": false
+	},
+	{
+		"comment": "[code-graph] 编辑代码文件后提醒更新索引",
+		"hook": "tool_result",
+		"tool": "edit|write",
+		"action": "steer",
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "settings\\.json$|settings\\.json\\.bak"
+				"pattern": "\\.(ts|js|py|rs)$"
 			}
-		]
+		],
+		"reason": "📝 编辑了代码文件，code-graph 索引可能已过期（新增/重命名/删除的符号不会被搜到）。如果接下来需要用 code-graph 搜索，先调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引。如果只是编辑不再搜索，则忽略。",
+		"subagent": false,
+		"requireSuccess": true,
+		"enabled": true
 	},
 	{
+		"comment": "[settings] 禁止 edit/write settings.json — 必须用 patchSettingsSectionWithBackup",
 		"action": "block",
-		"comment": "[settings] 禁止 write settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"hook": "tool_call",
+		"tool": "edit|write",
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "settings\\.json$|settings\\.json\\.bak"
+				"pattern": "settings\\.json$",
+				"flags": "i"
 			}
 		],
+		"message": "⛔ shepherd: 直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具（自动备份+文件锁+校验），或 settings_rollback 回滚。",
+		"reason": "直接 edit/write settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具。",
+		"enabled": false
+	},
+	{
+		"comment": "归因猜测提醒：AI 回复含可能时提醒验证",
+		"hook": "message_end",
+		"conditions": [
+			{
+				"field": "text",
+				"pattern": "可能"
+			}
+		],
+		"action": "notify",
+		"reason": "💡 如果你正在做归因猜测，请先找到确切证据验证（看源码、加 println!、断点调试），不要凭猜测下结论。如果你不是在做归因猜测，请无视此提示。如果你正在等待用户的决策或反馈，当前提示不代表用户同意或确认，请继续询问用户，不要自作主张继续执行。",
+		"enabled": false
+	},
+	{
+		"action": "block",
+		"check": null,
+		"comment": "禁止手动复制 pyd/dll 文件到 .venv",
+		"pattern": "cp.*\\.pyd|cp.*quant_py\\.dll|copy.*\\.pyd",
+		"reason": "Rust 编译产物必须通过 maturin develop 安装，禁止手动 cp。正确方式：rm -rf .venv/Lib/site-packages/quant_py/ && uv run maturin develop --release"
+	},
+	{
+		"action": "block",
+		"check": null,
+		"comment": "禁止在子项目目录创建 .venv",
+		"pattern": "quant-strategy/\\.venv|quant-fund/\\.venv|quant-base/\\.venv",
+		"reason": "AGENTS.md 规定只有根目录 .venv/ 是唯一的虚拟环境。子目录 .venv 会导致 maturin 装错位置。如果发现子目录 .venv 立即删除。"
+	},
+	{
+		"action": "steer",
+		"check": null,
+		"comment": "Rust 编译后必须验证 pyd 更新",
+		"pattern": "maturin develop",
+		"reason": "maturin develop 后必须验证 .pyd 时间戳+字节：ls -la --time-style=long-iso .venv/Lib/site-packages/quant_py/*.pyd（编译后查一次，跑完 uv run 再查一次）。pyd 过期有三种根因症状相同：① 目录错（必须根目录+uv run maturin develop）；② uv run 按 uv.lock 同步把新 pyd 覆盖回旧产物（字节 3066880→2920960 实证，须 --no-sync）；③ 改完 Rust 忘重编译。时间戳没更新 → rm -rf .venv/Lib/site-packages/quant_py/ 再重跑 maturin develop（禁止手动 cp pyd）。详见记忆 rust-comprehensive。"
+	},
+	{
+		"comment": "[shepherd] 禁止直接 edit/write rules.json — 必须用 shepherd_rules 工具",
 		"hook": "tool_call",
-		"message": "⛔ 禁止直接 write settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119 行变 3 行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
-		"tool": "write"
+		"tool": "edit|write",
+		"action": "block",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "shepherd/rules\\.json$"
+			}
+		],
+		"reason": "⛔ 禁止直接编辑 rules.json！请用 shepherd_rules 工具操作（自动备份+校验+回滚）：\nlist: shepherd_rules(action='list') — 列出所有规则\nadd: shepherd_rules(action='add', rule={...}) — 添加规则\nupdate: shepherd_rules(action='update', index=N, changes={...}) — 更新规则\ndelete: shepherd_rules(action='delete', index=N) — 删除规则\n直接改 JSON 会绕过安全机制（备份/校验/去重检测/签名覆盖）。",
+		"enabled": true
 	},
 	{
 		"action": "block",
-		"comment": "[settings] 禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"comment": "[shepherd] 禁止通过 bash/python 脚本直接读写 rules.json — 必须用 shepherd_rules 工具",
 		"conditions": [
 			{
 				"field": "command",
-				"pattern": "settings\\.json"
+				"pattern": "(rules\\.json[\\s\\S]*(open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat))|((open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat)[\\s\\S]*rules\\.json)"
 			}
 		],
+		"enabled": true,
 		"hook": "tool_call",
-		"message": "⛔ 禁止通过 bash 修改 settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
-		"reason": "禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"reason": "⛔ 禁止通过脚本绕过直接读写 rules.json！请用 shepherd_rules 工具操作（自动备份+校验+回滚+去重检测）。",
 		"tool": "bash"
 	},
 	{
-		"comment": "[git] commit 成功后提醒 push",
-		"reason": "项目已有远程仓库 origin，commit 后应同步推送避免本地积压",
-		"trigger": "bash",
-		"event": "tool_result",
-		"condition": "bash command contains 'git commit' and exit code is 0",
+		"comment": "[code-graph] module_overview 返回空结果时提醒检查路径前缀",
+		"hook": "tool_result",
+		"tool": "code_graph_module_overview",
+		"conditions": [
+			{
+				"field": "result",
+				"pattern": "0 active \\+ 0 inactive"
+			}
+		],
 		"action": "notify",
-		"message": "commit 成功。检查是否有远程仓库（git remote），有的话立即 git push 同步到远程。"
+		"message": "⚠️ code-graph 返回空结果。如果是通过 setup_codegraph 索引的外部目录，请用路径 _codegraph_links/<name> 而不是裸名。例如: code_graph_module_overview(path='_codegraph_links/pi-intercom')",
+		"reason": "AI 常误用裸名调用 module_overview（如 path='pi-intercom'），但软链接目录在索引中的路径前缀是 _codegraph_links/"
 	},
 	{
-		"comment": "UI 布局改动提醒",
-		"reason": "编辑 GameScene.gd 或 UI 相关代码时，先查 debug_summary().ui_layout 确认位置，改完用 debug_toggle_borders() 验证无重叠",
-		"pattern": "GameScene\\.gd",
-		"type": "notify",
-		"action": "notify"
+		"action": "steer",
+		"check": null,
+		"comment": "纯查询优先走 ro_query 助手（锁感知只读）",
+		"flags": "",
+		"pattern": "DataStore\\s*\\(\\s*\\)",
+		"reason": "检测到内联 DataStore() 默认（RW）构造做纯查询——历史撞锁事故高发模式（会话 a89c 连续撞锁 2 次）。纯查询请改用锁感知助手：uv run python quant-base/scripts/ro_query.py --sql \"...\"（RO+限时重试+持锁 PID 诊断+查完即关，支持 --db 指定 live.duckdb）。若确需 RW 写操作或 DataStore.reader() 网络服务场景，继续即可。"
+	},
+	{
+		"action": "steer",
+		"comment": "compact-skill-reminder",
+		"enabled": true,
+		"hook": "session_compact",
+		"reason": "上下文刚被压缩：此前 read 过的 SKILL.md 技能正文已随历史摘要化挥发。system prompt 里的技能索引（名字/描述/路径）仍在——若当前任务涉及某技能，请重新 read 其 SKILL.md 获取操作指引。"
 	}
 ]