@peterxiaoyang/superspec 0.1.7 → 0.1.8

package/dist/src/hooks/types.d.ts

@@ -0,0 +1,72 @@
+import type { JsonMap, Reason } from "../util.ts";
+export declare const HOOK_ADAPTER_VERSION = "superspec-hook@2";
+export type HookTrust = "trusted" | "audit-only" | "untrusted";
+export type HookStrictProfile = "available" | "unavailable";
+export type HookEvent = JsonMap & {
+    hook_event_name?: string;
+    session_id?: string;
+    turn_id?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_use_id?: string;
+    tool_input?: JsonMap;
+    tool_response?: JsonMap;
+    agent_id?: string;
+    agent_type?: string;
+};
+export type HookDecision = {
+    allowed: boolean;
+    decision: "allow" | "block" | "status";
+    change_id: string;
+    gate: string;
+    strict_profile: HookStrictProfile;
+    enforcement: "pass-through" | "guarded" | "deny" | "audit-only";
+    trust: HookTrust;
+    block_reasons: Reason[];
+    audit_only_reasons: Reason[];
+    target_paths?: string[];
+    tool_name?: string;
+    hook_event_name?: string;
+    hook_event_id?: string;
+    actions?: JsonMap[];
+    next_allowed_actions: string[];
+    trust_warnings: string[];
+};
+export type HookSessionRecord = {
+    schema_version: 2;
+    kind: "hook_active_session";
+    trust: HookTrust;
+    change_id: string;
+    repo_root: string;
+    session_id: string;
+    workflow: string;
+    started_at: string;
+    expires_at: string;
+    guard_version: string;
+    adapter_version: string;
+    hook_manifest_hash: string | null;
+    strict_profile: HookStrictProfile;
+    audit_only_reasons: Reason[];
+};
+export type HookRunlogRecord = {
+    schema_version: 2;
+    kind: "subagent_start" | "subagent_stop";
+    trust: HookTrust;
+    hook_event_id: string;
+    hook_event_name: string;
+    hook_provenance: JsonMap;
+    session_id: string;
+    turn_id?: string;
+    run_id: string;
+    agent_id: string;
+    agent_type: string;
+    cwd?: string;
+    prompt_hash?: string;
+    prompt_ref?: string;
+    output_ref?: string;
+    output_hash?: string;
+    status?: string;
+    error?: string;
+    started_at?: string;
+    stopped_at?: string;
+};

package/dist/src/hooks/types.js

@@ -0,0 +1 @@
+export const HOOK_ADAPTER_VERSION = "superspec-hook@2";

package/dist/src/hooks/validation.d.ts

@@ -0,0 +1,3 @@
+import type { JsonMap, Reason } from "../util.ts";
+export declare function strictRoleRunlogReasons(changeRoot: string, ev: JsonMap): Reason[];
+export declare function strictRuntimeEvidenceReasons(ev: JsonMap): Reason[];

package/dist/src/hooks/validation.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { isObject, reason, safe_within, sha256_file } from "../util.js";
+import { superspec_dir } from "../paths.js";
+function runlogPath(changeRoot) {
+    return join(superspec_dir(changeRoot), "subagent-runlog.jsonl");
+}
+export function strictRoleRunlogReasons(changeRoot, ev) {
+    if (ev.trust !== "runtime-verified" && ev.requires_hook_runlog !== true)
+        return [];
+    const problems = [
+        reason("hook_runlog_strict_profile_unavailable", `${ev._path}: strict hook runlog validation is unavailable until R-1 deny and hook provenance pass`),
+    ];
+    const target = runlogPath(changeRoot);
+    if (!existsSync(target) || !statSync(target).isFile()) {
+        problems.push(reason("hook_runlog_missing", `${ev._path}: strict role evidence requires SuperSpec hook subagent runlog`));
+        return problems;
+    }
+    const records = readFileSync(target, "utf8").split(/\r?\n/u).filter(Boolean).flatMap((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            return isObject(parsed) ? [parsed] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    const agentId = String(ev.agent_id ?? "");
+    const role = String(ev.agent_role ?? "");
+    const starts = records.filter((item) => item.kind === "subagent_start" && item.agent_id === agentId && item.agent_type === role && item.trust === "trusted");
+    const stops = records.filter((item) => item.kind === "subagent_stop" && item.agent_id === agentId && item.agent_type === role && item.trust === "trusted");
+    if (starts.length === 0)
+        problems.push(reason("hook_runlog_start_missing", `${ev._path}: strict role evidence has no trusted matching SubagentStart`, [agentId]));
+    if (stops.length === 0)
+        problems.push(reason("hook_runlog_stop_missing", `${ev._path}: strict role evidence has no trusted matching SubagentStop`, [agentId]));
+    const outputRef = typeof ev.output_ref === "string" ? ev.output_ref : "";
+    const outputPath = outputRef ? safe_within(changeRoot, outputRef) : null;
+    const outputSha = outputPath && existsSync(outputPath) && statSync(outputPath).isFile() ? sha256_file(outputPath) : null;
+    if (outputSha && stops.length > 0 && !stops.some((item) => item.output_hash === outputSha || item.output_ref === outputRef)) {
+        problems.push(reason("hook_runlog_output_mismatch", `${ev._path}: strict role evidence output_ref does not match trusted SubagentStop output hash/ref`, [agentId]));
+    }
+    return problems;
+}
+export function strictRuntimeEvidenceReasons(ev) {
+    if (ev.trust !== "runtime-verified")
+        return [];
+    const problems = [
+        reason("runtime_evidence_strict_profile_unavailable", `${ev._path}: strict runtime evidence is unavailable until R-1 deny and hook provenance pass`),
+    ];
+    if (typeof ev.hook_event_id !== "string" || !ev.hook_event_id)
+        problems.push(reason("runtime_evidence_missing_hook_event", `${ev._path}: runtime-verified evidence requires hook_event_id`));
+    if (!isObject(ev.hook_provenance) || ev.hook_provenance.validation !== "trusted")
+        problems.push(reason("runtime_evidence_untrusted_provenance", `${ev._path}: runtime-verified evidence requires trusted hook_provenance`));
+    if (!isObject(ev.token_binding))
+        problems.push(reason("runtime_evidence_missing_token", `${ev._path}: runtime-verified evidence requires Guard token_binding`));
+    if (typeof ev.command_fingerprint !== "string" || !ev.command_fingerprint.startsWith("sha256:"))
+        problems.push(reason("runtime_evidence_missing_command_fingerprint", `${ev._path}: runtime-verified evidence requires command_fingerprint`));
+    if (!Array.isArray(ev.raw_log_pinned_refs) || ev.raw_log_pinned_refs.length === 0)
+        problems.push(reason("runtime_evidence_missing_raw_log_pin", `${ev._path}: runtime-verified evidence requires raw_log_pinned_refs`));
+    if (typeof ev.exit_code !== "number") {
+        problems.push(reason("runtime_evidence_missing_exit_code", `${ev._path}: runtime-verified evidence requires numeric exit_code`));
+    }
+    else if ((ev.kind === "final_test" || ev.semantic_status === "expected_success") && ev.exit_code !== 0) {
+        problems.push(reason("runtime_evidence_exit_code_mismatch", `${ev._path}: expected_success/final_test runtime evidence requires exit_code=0`));
+    }
+    else if (ev.semantic_status === "expected_failure" && ev.exit_code === 0) {
+        problems.push(reason("runtime_evidence_exit_code_mismatch", `${ev._path}: RED runtime evidence requires non-zero exit_code`));
+    }
+    return problems;
+}

package/dist/src/packet_measure.js

@@ -1,118 +1,119 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { load_install_map } from "./install_engine.js";
 import { dispatch_packet } from "./packet_render.js";
-import { GuardError, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, runtime, } from "./util.js";
+import { GuardError, runtime, } from "./util.js";
 import { file_blob_sha } from "./git.js";
 const REPRESENTATIVE_SCENARIOS = [
     {
         name: "explore_complete",
-        description: "Post-bridge runtime surface for discovery authoring plus proposal-entry critic review.",
+        description: "Package payload surface for discovery authoring plus proposal-entry critic review.",
         files: [
-            ".codex/skills/superspec-explore/SKILL.md",
-            ".codex/prompts/critic.md",
-            ".codex/agents/critic.toml",
+            "templates/workflow/skills/superspec-explore/SKILL.md",
+            "templates/workflow/prompts/critic.md",
+            "adapters/codex/agents/critic.toml",
         ],
     },
     {
         name: "proposal_reviewed",
-        description: "Post-bridge runtime surface for proposal authoring and proposal critic review.",
+        description: "Package payload surface for proposal authoring and proposal critic review.",
         files: [
-            ".codex/skills/superspec-propose/SKILL.md",
-            ".codex/prompts/critic.md",
-            ".codex/agents/critic.toml",
+            "templates/workflow/skills/superspec-propose/SKILL.md",
+            "templates/workflow/prompts/critic.md",
+            "adapters/codex/agents/critic.toml",
         ],
     },
     {
         name: "design_complete",
-        description: "Post-bridge runtime surface for design authoring and the architect/critic/test-engineer review bundle.",
+        description: "Package payload surface for design authoring and the architect/critic/test-engineer review bundle.",
         files: [
-            ".codex/skills/superspec-propose/SKILL.md",
-            ".codex/prompts/architect.md",
-            ".codex/prompts/critic.md",
-            ".codex/prompts/test-engineer.md",
-            ".codex/agents/architect.toml",
-            ".codex/agents/critic.toml",
-            ".codex/agents/test-engineer.toml",
+            "templates/workflow/skills/superspec-propose/SKILL.md",
+            "templates/workflow/prompts/architect.md",
+            "templates/workflow/prompts/critic.md",
+            "templates/workflow/prompts/test-engineer.md",
+            "adapters/codex/agents/architect.toml",
+            "adapters/codex/agents/critic.toml",
+            "adapters/codex/agents/test-engineer.toml",
         ],
     },
     {
         name: "test_contract_drafted",
-        description: "Post-bridge runtime surface for test-contract authoring and its review lanes.",
+        description: "Package payload surface for test-contract authoring and its review lanes.",
         files: [
-            ".codex/skills/superspec-propose/SKILL.md",
-            ".codex/prompts/critic.md",
-            ".codex/prompts/test-engineer.md",
-            ".codex/agents/critic.toml",
-            ".codex/agents/test-engineer.toml",
+            "templates/workflow/skills/superspec-propose/SKILL.md",
+            "templates/workflow/prompts/critic.md",
+            "templates/workflow/prompts/test-engineer.md",
+            "adapters/codex/agents/critic.toml",
+            "adapters/codex/agents/test-engineer.toml",
         ],
     },
     {
         name: "apply_ready",
-        description: "Post-bridge runtime surface for apply orchestration and bounded executor handoff.",
+        description: "Package payload surface for apply orchestration and bounded executor handoff.",
         files: [
-            ".codex/skills/superspec-apply/SKILL.md",
-            ".codex/prompts/executor.md",
-            ".codex/agents/executor.toml",
+            "templates/workflow/skills/superspec-apply/SKILL.md",
+            "templates/workflow/prompts/executor.md",
+            "adapters/codex/agents/executor.toml",
         ],
     },
     {
         name: "review_complete_allow",
-        description: "Post-bridge runtime surface for merged review + final verification on the allow path.",
+        description: "Package payload surface for merged review + final verification on the allow path.",
         files: [
-            ".codex/skills/superspec-review/SKILL.md",
-            ".codex/prompts/code-reviewer.md",
-            ".codex/prompts/architect.md",
-            ".codex/prompts/critic.md",
-            ".codex/prompts/verifier.md",
-            ".codex/agents/code-reviewer.toml",
-            ".codex/agents/architect.toml",
-            ".codex/agents/critic.toml",
-            ".codex/agents/verifier.toml",
+            "templates/workflow/skills/superspec-review/SKILL.md",
+            "templates/workflow/prompts/code-reviewer.md",
+            "templates/workflow/prompts/architect.md",
+            "templates/workflow/prompts/critic.md",
+            "templates/workflow/prompts/verifier.md",
+            "adapters/codex/agents/code-reviewer.toml",
+            "adapters/codex/agents/architect.toml",
+            "adapters/codex/agents/critic.toml",
+            "adapters/codex/agents/verifier.toml",
         ],
     },
     {
         name: "archive_ready",
-        description: "Post-bridge runtime surface for archive handoff after review passes.",
+        description: "Package payload surface for archive handoff after review passes.",
         files: [
-            ".codex/skills/superspec-archive/SKILL.md",
+            "templates/workflow/skills/superspec-archive/SKILL.md",
         ],
     },
     {
         name: "round2_reviewer_prompt",
-        description: "Post-bridge runtime surface for a round>1 reviewer lane.",
+        description: "Package payload surface for a round>1 reviewer lane.",
         files: [
-            ".codex/prompts/critic.md",
-            ".codex/agents/critic.toml",
+            "templates/workflow/prompts/critic.md",
+            "adapters/codex/agents/critic.toml",
         ],
     },
     {
         name: "request_changes_reopen_tasks",
-        description: "Post-bridge runtime surface for a review round that routes back to apply via reopen_tasks.",
+        description: "Package payload surface for a review round that routes back to apply via reopen_tasks.",
         files: [
-            ".codex/skills/superspec-review/SKILL.md",
-            ".codex/prompts/code-reviewer.md",
-            ".codex/prompts/architect.md",
-            ".codex/prompts/critic.md",
-            ".codex/agents/code-reviewer.toml",
-            ".codex/agents/architect.toml",
-            ".codex/agents/critic.toml",
+            "templates/workflow/skills/superspec-review/SKILL.md",
+            "templates/workflow/prompts/code-reviewer.md",
+            "templates/workflow/prompts/architect.md",
+            "templates/workflow/prompts/critic.md",
+            "adapters/codex/agents/code-reviewer.toml",
+            "adapters/codex/agents/architect.toml",
+            "adapters/codex/agents/critic.toml",
         ],
     },
     {
         name: "task_reopen_to_resolved",
-        description: "Post-bridge runtime surface for reopened apply work from revert through successor executor completion.",
+        description: "Package payload surface for reopened apply work from revert through successor executor completion.",
         files: [
-            ".codex/skills/superspec-apply/SKILL.md",
-            ".codex/prompts/executor.md",
-            ".codex/agents/executor.toml",
+            "templates/workflow/skills/superspec-apply/SKILL.md",
+            "templates/workflow/prompts/executor.md",
+            "adapters/codex/agents/executor.toml",
         ],
     },
     {
         name: "scope_expansion",
-        description: "Post-bridge runtime surface for apply-side user confirmation when task scope expands.",
+        description: "Package payload surface for apply-side user confirmation when task scope expands.",
         files: [
-            ".codex/skills/superspec-apply/SKILL.md",
+            "templates/workflow/skills/superspec-apply/SKILL.md",
         ],
     },
 ];
@@ -166,24 +167,6 @@ function ensureReadableTextFile(repoRoot, relPath) {
     if (existsSync(absPath) && statSync(absPath).isFile()) {
         return readFileSync(absPath, "utf8");
     }
-    const skillMatch = /^\.codex\/skills\/([^/]+)\/SKILL\.md$/u.exec(relPath);
-    if (skillMatch) {
-        const fallback = join(repoRoot, "templates", "workflow", "skills", skillMatch[1], "SKILL.md");
-        if (existsSync(fallback) && statSync(fallback).isFile())
-            return readFileSync(fallback, "utf8");
-    }
-    const promptMatch = /^\.codex\/prompts\/([^/]+)\.md$/u.exec(relPath);
-    if (promptMatch) {
-        const fallback = join(repoRoot, "templates", "workflow", "prompts", `${promptMatch[1]}.md`);
-        if (existsSync(fallback) && statSync(fallback).isFile())
-            return readFileSync(fallback, "utf8");
-    }
-    const agentMatch = /^\.codex\/agents\/([^/]+)\.toml$/u.exec(relPath);
-    if (agentMatch) {
-        const fallback = join(repoRoot, "adapters", "codex", "agents", `${agentMatch[1]}.toml`);
-        if (existsSync(fallback) && statSync(fallback).isFile())
-            return readFileSync(fallback, "utf8");
-    }
     throw new GuardError(`packet_measure_missing_file: ${relPath}`);
 }
 function dedupePaths(paths) {
@@ -365,39 +348,21 @@ function measureMaterializedSamples(specs) {
         ctx.cleanup();
     }
 }
-function templateWorkflowSkillPaths() {
-    return REQUIRED_SUPERSPEC_WORKFLOW_SKILLS.map((name) => `templates/workflow/skills/${name}/SKILL.md`);
-}
-function templatePromptPaths() {
-    return REQUIRED_SUPERSPEC_AGENT_ROLES.map((name) => `templates/workflow/prompts/${name}.md`);
-}
-function adapterAgentPaths() {
-    return REQUIRED_SUPERSPEC_AGENT_ROLES.map((name) => `adapters/codex/agents/${name}.toml`);
-}
-function repoLocalSkillPaths(repoRoot) {
-    return REQUIRED_SUPERSPEC_WORKFLOW_SKILLS
-        .map((name) => join(".codex", "skills", name, "SKILL.md"))
-        .filter((relPath) => existsSync(join(repoRoot, relPath)));
-}
-function runtimeBridgeSkillPaths() {
-    return [];
+function installPayloadSourcePaths(repoRoot) {
+    const { mappings, problems } = load_install_map(repoRoot);
+    if (problems.length > 0)
+        throw new GuardError(`packet_measure_install_map_invalid: ${problems.join("; ")}`);
+    return mappings
+        .filter((mapping) => mapping.kind === "skill" || mapping.kind === "prompt" || mapping.kind === "agent")
+        .map((mapping) => mapping.source);
 }
 export function representative_scenarios() {
     return REPRESENTATIVE_SCENARIOS;
 }
 export function measure_packet_surface_report(repoRoot) {
-    const fixedSurfaceInstallUpperBound = measureSurface(repoRoot, [
-        ...templateWorkflowSkillPaths(),
-        ...templatePromptPaths(),
-        ...adapterAgentPaths(),
-        ...repoLocalSkillPaths(repoRoot),
-    ]);
-    const fixedSurfaceRuntimeRequiredSubset = measureSurface(repoRoot, [
-        ...templateWorkflowSkillPaths(),
-        ...templatePromptPaths(),
-        ...adapterAgentPaths(),
-        ...runtimeBridgeSkillPaths(),
-    ]);
+    const packagePayloadSourcePaths = installPayloadSourcePaths(repoRoot);
+    const fixedSurfaceInstallUpperBound = measureSurface(repoRoot, packagePayloadSourcePaths);
+    const fixedSurfaceRuntimeRequiredSubset = measureSurface(repoRoot, packagePayloadSourcePaths);
     const scenarios = REPRESENTATIVE_SCENARIOS.map((scenario) => ({
         name: scenario.name,
         description: scenario.description,

package/dist/superspec_hook.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import "./src/core.ts";
+export * from "./src/hooks/adapter.ts";
+export declare function main_hook(argv?: string[]): number;

package/dist/superspec_hook.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import "./src/core.js";
+export * from "./src/hooks/adapter.js";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { runHookAdapter } from "./src/hooks/adapter.js";
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+const currentFile = realpathMaybe(process.argv[1] ?? "");
+export function main_hook(argv = process.argv.slice(2)) {
+    const stdin = readStdin();
+    const result = runHookAdapter(argv, stdin);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    return result.code;
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+if (currentFile === realpathMaybe(new URL(import.meta.url).pathname)) {
+    process.exitCode = main_hook();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",
@@ -21,6 +21,7 @@
   "bin": {
     "superspec": "bin/superspec.js",
     "superspec-guard": "bin/superspec-guard.js",
+    "superspec-hook": "bin/superspec-hook.js",
     "superspec-init": "bin/superspec-init.js"
   },
   "exports": {
@@ -32,6 +33,10 @@
       "types": "./dist/superspec_guard.d.ts",
       "default": "./dist/superspec_guard.js"
     },
+    "./superspec_hook": {
+      "types": "./dist/superspec_hook.d.ts",
+      "default": "./dist/superspec_hook.js"
+    },
     "./superspec_init": {
       "types": "./dist/superspec_init.d.ts",
       "default": "./dist/superspec_init.js"
@@ -51,7 +56,7 @@
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/test_install_engine.test.ts tests/test_packet_measure.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/test_install_engine.test.ts tests/test_packet_measure.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_hooks.test.ts tests/test_superspec_skills.test.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pack:dry-run": "npm pack --dry-run"

package/schemas/hook-event.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://superspec.local/schemas/hook-event.schema.json",
+  "title": "SuperSpec Codex Hook Event",
+  "type": "object",
+  "required": ["hook_event_name", "cwd"],
+  "properties": {
+    "session_id": { "type": "string" },
+    "turn_id": { "type": "string" },
+    "transcript_path": { "type": ["string", "null"] },
+    "cwd": { "type": "string" },
+    "hook_event_name": {
+      "type": "string",
+      "enum": ["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop"]
+    },
+    "permission_mode": { "type": "string" },
+    "tool_name": { "type": "string" },
+    "tool_use_id": { "type": "string" },
+    "tool_input": { "type": "object" },
+    "tool_response": { "type": ["object", "array", "string", "number", "boolean", "null"] },
+    "agent_id": { "type": "string" },
+    "agent_type": { "type": "string" },
+    "agent_transcript_path": { "type": ["string", "null"] },
+    "last_assistant_message": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true
+}

package/templates/hooks/codex-hooks.json

@@ -0,0 +1,61 @@
+{
+  "superspec": {
+    "managed": true,
+    "adapter_version": "superspec-hook@2",
+    "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": 10,
+            "statusMessage": "SuperSpec hook write policy"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
+            "timeout": 30,
+            "statusMessage": "SuperSpec hook runtime evidence"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
+            "timeout": 30,
+            "statusMessage": "SuperSpec hook subagent start"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
+            "timeout": 30,
+            "statusMessage": "SuperSpec hook subagent stop"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -26,6 +26,13 @@ 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,6 +26,13 @@ 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
 ```
@@ -60,6 +67,7 @@ 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,6 +26,13 @@ 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,6 +26,13 @@ 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
 ```