@peterxiaoyang/superspec 0.1.10 → 0.1.11

package/README.md

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

package/dist/src/hooks/adapter.js

@@ -224,11 +224,32 @@ function postToolUseOutput(decision) {
         },
     };
 }
+function isSubagentHookEvent(eventName) {
+    return eventName === "SubagentStart" || eventName === "SubagentStop";
+}
 function subagentOutput(decision, eventName) {
+    if (!decision.allowed) {
+        return {
+            systemMessage: `SuperSpec ${eventName} runlog skipped; ${decision.block_reasons.map((item) => item.message).join("; ") || "audit telemetry unavailable"}`,
+            hookSpecificOutput: {
+                hookEventName: eventName,
+                additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
+            },
+        };
+    }
     return {
         systemMessage: `SuperSpec ${eventName} runlog recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
     };
 }
+function inertSubagentOutput(eventName, message) {
+    return {
+        systemMessage: message,
+        hookSpecificOutput: {
+            hookEventName: eventName,
+            additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
+        },
+    };
+}
 function writeTempEvent(event) {
     const path = join(tmpdir(), `superspec-hook-event-${randomUUID()}.json`);
     writeFileSync(path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
@@ -241,8 +262,9 @@ function validateHookEvent(event) {
     if (!["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop"].includes(eventName)) {
         return `unsupported hook_event_name: ${eventName}`;
     }
-    if (typeof event.cwd !== "string" || !event.cwd)
+    if ((eventName === "PreToolUse" || eventName === "PostToolUse") && (typeof event.cwd !== "string" || !event.cwd)) {
         return "hook event missing required cwd";
+    }
     if (eventName === "PreToolUse") {
         if (typeof event.tool_name !== "string" || !event.tool_name)
             return "PreToolUse hook event missing required tool_name";
@@ -254,6 +276,7 @@ function validateHookEvent(event) {
 export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSync(0, "utf8")) {
     const parsedArgs = parseArgs(argv);
     let event;
+    let eventNameForFailure = "";
     try {
         if (!stdin.trim())
             throw new Error("hook stdin is empty");
@@ -261,11 +284,16 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         if (!isObject(parsed))
             throw new Error("hook stdin must be a JSON object");
         event = parsed;
+        eventNameForFailure = typeof event.hook_event_name === "string" ? event.hook_event_name : "";
         const validationError = validateHookEvent(event);
         if (validationError)
             throw new Error(validationError);
     }
     catch (err) {
+        if (isSubagentHookEvent(eventNameForFailure)) {
+            const payload = inertSubagentOutput(eventNameForFailure, `SuperSpec ${eventNameForFailure} runlog skipped: ${err.message}`);
+            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+        }
         return { code: 2, stdout: "", stderr: `SuperSpec hook event parse failed: ${err.message}\n` };
     }
     const inference = parsedArgs.change ? { state: "unique", change: parsedArgs.change } : inferChangeFromActiveSessions(event);
@@ -274,8 +302,9 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         const payload = noChangeFallback(event, inference);
         return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
     }
-    const eventRef = writeTempEvent(event);
+    let eventRef = null;
     try {
+        eventRef = writeTempEvent(event);
         const eventName = String(event.hook_event_name ?? "");
         let payload;
         if (eventName === "PreToolUse") {
@@ -298,14 +327,21 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
     }
     catch (err) {
+        if (isSubagentHookEvent(String(event.hook_event_name ?? ""))) {
+            const eventName = String(event.hook_event_name ?? "");
+            const payload = inertSubagentOutput(eventName, `SuperSpec ${eventName} runlog skipped: ${err.message}`);
+            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+        }
         return { code: 2, stdout: "", stderr: `SuperSpec hook failed closed: ${err.message}\n` };
     }
     finally {
-        try {
-            unlinkSync(resolve(eventRef));
-        }
-        catch {
-            // best effort temp cleanup
+        if (eventRef) {
+            try {
+                unlinkSync(resolve(eventRef));
+            }
+            catch {
+                // best effort temp cleanup
+            }
         }
     }
 }

package/dist/src/hooks/health.js

@@ -4,18 +4,6 @@ import { reason, sha256_file } from "../util.js";
 import { HOOK_ADAPTER_VERSION } from "./types.js";
 const HOOK_COMMAND = 'superspec-hook --change "$SUPERSPEC_CHANGE"';
 const EXPECTED_HOOK_MATRIX = [
-    {
-        eventName: "PreToolUse",
-        matcher: "Bash|apply_patch|Edit|Write|mcp__.*",
-        timeout: 120,
-        statusMessage: "SuperSpec 写入策略检查",
-    },
-    {
-        eventName: "PostToolUse",
-        matcher: "Bash",
-        timeout: 120,
-        statusMessage: "SuperSpec 运行证据记录",
-    },
     {
         eventName: "SubagentStart",
         matcher: ".*",

package/dist/src/install_engine.js

@@ -29,6 +29,13 @@ const CODEX_CONFIG_ENTRIES = [
     { table: "agents", key: "max_threads", value: String(CODEX_NATIVE_AGENT_MAX_THREADS) },
     { table: "agents", key: "max_depth", value: String(CODEX_NATIVE_AGENT_MAX_DEPTH) },
 ];
+const HOOK_COMMAND = 'superspec-hook --change "$SUPERSPEC_CHANGE"';
+const LEGACY_FOUR_HOOK_MATRIX = [
+    { eventName: "PreToolUse", matcher: "Bash|apply_patch|Edit|Write|mcp__.*", statusMessage: "SuperSpec 写入策略检查" },
+    { eventName: "PostToolUse", matcher: "Bash", statusMessage: "SuperSpec 运行证据记录" },
+    { eventName: "SubagentStart", matcher: ".*", statusMessage: "SuperSpec 子智能体启动记录" },
+    { eventName: "SubagentStop", matcher: ".*", statusMessage: "SuperSpec 子智能体停止记录" },
+];
 function package_version(packageRoot) {
     try {
         const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
@@ -38,6 +45,51 @@ function package_version(packageRoot) {
         return "0.0.0";
     }
 }
+function has_exact_keys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, idx) => key === expected[idx]);
+}
+function legacy_hook_entry_matches(entry, expected) {
+    if (!isObject(entry) || !has_exact_keys(entry, ["matcher", "hooks"]))
+        return false;
+    if (entry.matcher !== expected.matcher || !Array.isArray(entry.hooks) || entry.hooks.length !== 1)
+        return false;
+    const hook = entry.hooks[0];
+    return isObject(hook)
+        && has_exact_keys(hook, ["type", "command", "timeout", "statusMessage"])
+        && hook.type === "command"
+        && hook.command === HOOK_COMMAND
+        && hook.timeout === 120
+        && hook.statusMessage === expected.statusMessage;
+}
+function is_legacy_managed_four_hook_manifest(parsed) {
+    if (!isObject(parsed) || !has_exact_keys(parsed, ["superspec", "hooks"]))
+        return false;
+    if (!isObject(parsed.superspec) || !has_exact_keys(parsed.superspec, ["managed", "adapter_version", "strict_profile_default"]))
+        return false;
+    if (parsed.superspec.managed !== true
+        || parsed.superspec.adapter_version !== "superspec-hook@2"
+        || parsed.superspec.strict_profile_default !== "audit-only-until-r1-provenance-passes") {
+        return false;
+    }
+    if (!isObject(parsed.hooks) || !has_exact_keys(parsed.hooks, LEGACY_FOUR_HOOK_MATRIX.map((entry) => entry.eventName)))
+        return false;
+    return LEGACY_FOUR_HOOK_MATRIX.every((expected) => {
+        const entries = parsed.hooks[expected.eventName];
+        return Array.isArray(entries)
+            && entries.length === 1
+            && legacy_hook_entry_matches(entries[0], expected);
+    });
+}
+function target_is_legacy_managed_four_hook_manifest(targetAbs) {
+    try {
+        return is_legacy_managed_four_hook_manifest(JSON.parse(readFileSync(targetAbs, "utf8")));
+    }
+    catch {
+        return false;
+    }
+}
 export function load_install_map(packageRoot = PACKAGE_ROOT) {
     const mapPath = join(packageRoot, INSTALL_MAP_REL);
     if (!existsSync(mapPath))
@@ -315,6 +367,13 @@ export function install_workflow(repoRoot, opts = {}) {
             files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
             actions.push({ action: `install ${mapping.target}`, status: "ok" });
         }
+        else if (mapping.kind === "hook" && target_is_legacy_managed_four_hook_manifest(targetAbs)) {
+            // Previous SuperSpec default hooks installed PreToolUse/PostToolUse. Re-init must migrate
+            // that unmodified managed baseline so old blocking hooks do not stay in the workflow.
+            copyFileSync(sourceAbs, targetAbs);
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `install ${mapping.target}`, status: "updated", detail: "legacy managed four-hook manifest migrated to subagent-only manifest" });
+        }
         else if (opts.force) {
             copyFileSync(targetAbs, `${targetAbs}.bak`);
             copyFileSync(sourceAbs, targetAbs);
@@ -323,6 +382,11 @@ export function install_workflow(repoRoot, opts = {}) {
             files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
             actions.push({ action: `install ${mapping.target}`, status: "updated", detail: `existing file backed up to ${mapping.target}.bak` });
         }
+        else if (mapping.kind === "hook") {
+            copyFileSync(sourceAbs, `${targetAbs}.new`);
+            files.push({ path: mapping.target, sha256: targetSha, managed: false, preexisting: true });
+            actions.push({ action: `install ${mapping.target}`, status: "skipped", detail: `pre-existing hooks manifest kept; current SuperSpec manifest written to ${mapping.target}.new` });
+        }
         else {
             // Pre-existing different file: never overwrite, never delete (DISTRIBUTION §5 red line).
             files.push({ path: mapping.target, sha256: targetSha, managed: false, preexisting: true });

package/package.json

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

package/templates/hooks/codex-hooks.json

@@ -5,32 +5,6 @@
     "strict_profile_default": "audit-only-until-r1-provenance-passes"
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|apply_patch|Edit|Write|mcp__.*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 120,
-            "statusMessage": "SuperSpec 写入策略检查"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 120,
-            "statusMessage": "SuperSpec 运行证据记录"
-          }
-        ]
-      }
-    ],
     "SubagentStart": [
       {
         "matcher": ".*",

package/templates/workflow/skills/superspec-apply/SKILL.md

@@ -26,13 +26,6 @@ Apply 按 OpenSpec tasks 执行实现，负责 RED/GREEN 证据、任务勾选
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-apply --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
 superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
 ```

package/templates/workflow/skills/superspec-archive/SKILL.md

@@ -26,13 +26,6 @@ Archive 在 `review_complete` allowed 后收尾：确认 archive readiness、保
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-archive --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
 superspec guard workflow-packet --change "<change>" --gate archive_ready --format agent
 ```
@@ -67,7 +60,6 @@ openspec archive -y "<change>"
 
 ```text
 superspec guard check-archived --change "<change>" --format agent
-superspec guard hook-session-end --change "<change>" --reason archived --format agent
 ```
 
 `.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`、review/verification evidence、RED/GREEN evidence 和 archive evidence 必须能从 preservation manifest 追溯。

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -26,13 +26,6 @@ Explore 只做需求澄清、代码事实调查、范围边界和风险记录。
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-explore --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
 superspec init --scope project --format agent
 ```

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -26,13 +26,6 @@ Propose 把 discovery 转成 OpenSpec proposal package，并补 SuperSpec 业务
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-propose --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
 superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
 ```

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -26,13 +26,6 @@ Review 合并实现审查、架构审查、SuperSpec critic、final verification
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-review --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
 superspec guard check-init --change "<change>" --format agent
 ```