@peterxiaoyang/superspec 0.1.8 → 0.1.9

package/README.md

@@ -82,6 +82,8 @@ superspec init --scope project
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
 
+初始化还会安装托管的 `.codex/hooks.json`。它会让 Codex 在写文件前、工具执行后、子智能体启动和停止时调用 SuperSpec，做检查和记录。
+
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
 ```powershell
@@ -157,6 +159,18 @@ openspec/changes/<变更ID>/.superspec/
 `.superspec/` 要不要提交到 git，由你的团队决定。
 如果不提交，删掉后就没有 git 历史可以恢复。
 
+## Hook 会做什么
+
+SuperSpec 安装的 hook 会在几个关键时机运行：
+
+- 写文件前：检查是否会改到 SuperSpec 的过程记录、提前归档、绕过任务检查，或写到当前任务不该写的地方
+- 工具执行后：如果刚跑的是测试或验证命令，就记录这次结果
+- 子智能体启动和停止时：记录这次子智能体运行的基本信息
+
+这些 hook 的默认超时时间是 `120` 秒。这个时间限制的是 hook 自己的检查过程，不限制 `npm test`、构建命令或子智能体本身能运行多久。
+
+hook 不是安全沙箱。它能减少误操作、拦住一部分明显会破坏流程记录的写入，并留下审计线索；但不能保证阻止所有绕过，也不能把记录变成不可伪造的安全证明。
+
 ## 重要边界
 
 SuperSpec 能让流程更规范，但它不是安全锁。
@@ -175,7 +189,7 @@ SuperSpec 能让流程更规范，但它不是安全锁。
 - 阻止恶意伪造记录
 - 替代正式的安全审计、合规审计或法律证明
 
-也就是说，SuperSpec v1 是“流程纪律工具”，不是“强制安全系统”。
+也就是说，SuperSpec 目前是“流程纪律 + 审计辅助工具”，不是“强制安全系统”。hook 会增强可见性和一部分写入检查，但它仍然不能替代正式的安全控制。
 
 ## 常用命令
 
@@ -223,6 +237,7 @@ superspec doctor
 
 ```text
 .codex/
+  hooks.json
   skills/superspec-explore/
   skills/superspec-propose/
   skills/superspec-apply/

package/dist/src/hooks/health.js

@@ -7,26 +7,26 @@ const EXPECTED_HOOK_MATRIX = [
     {
         eventName: "PreToolUse",
         matcher: "Bash|apply_patch|Edit|Write|mcp__.*",
-        timeout: 10,
-        statusMessage: "SuperSpec hook write policy",
+        timeout: 120,
+        statusMessage: "SuperSpec 写入策略检查",
     },
     {
         eventName: "PostToolUse",
         matcher: "Bash",
-        timeout: 30,
-        statusMessage: "SuperSpec hook runtime evidence",
+        timeout: 120,
+        statusMessage: "SuperSpec 运行证据记录",
     },
     {
         eventName: "SubagentStart",
         matcher: ".*",
-        timeout: 30,
-        statusMessage: "SuperSpec hook subagent start",
+        timeout: 120,
+        statusMessage: "SuperSpec 子智能体启动记录",
     },
     {
         eventName: "SubagentStop",
         matcher: ".*",
-        timeout: 30,
-        statusMessage: "SuperSpec hook subagent stop",
+        timeout: 120,
+        statusMessage: "SuperSpec 子智能体停止记录",
     },
 ];
 function isRecord(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",

package/templates/hooks/codex-hooks.json

@@ -12,8 +12,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 10,
-            "statusMessage": "SuperSpec hook write policy"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 写入策略检查"
           }
         ]
       }
@@ -25,8 +25,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook runtime evidence"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 运行证据记录"
           }
         ]
       }
@@ -38,8 +38,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook subagent start"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 子智能体启动记录"
           }
         ]
       }
@@ -51,8 +51,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook subagent stop"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 子智能体停止记录"
           }
         ]
       }