@peterxiaoyang/superspec 0.1.6 → 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/src/packet_render.js

@@ -5,13 +5,14 @@ import {} from "./cli_args.js";
 import { CLAIM_ADJUDICATION_DECISIONS, FINDING_ADJUDICATION_DECISIONS, fingerprint_obj, GuardError, MAIN_ADJUDICATION_REQUIRED_FIELDS, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, REVIEW_EVIDENCE_REQUIRED_FIELDS, ROLE_EVIDENCE_FIELDS, SOURCE_GUIDANCE_REQUIRED_FIELDS, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, deepEqual, isObject, reason, renderList, runtime, safe_within, sha256_text, } from "./util.js";
 import { artifact_status_map, gate_route_phase, get_change_root, get_repo_root, normalize_gate, openspec_status, openspec_status_shape_reasons, } from "./openspec.js";
 import { build_finding_ledger, enumerate_review_targets, render_finding_ledger, REVIEW_TARGETS_BY_GATE, review_round_number, } from "./disclosure.js";
-import { evidence_schema_guard, check_apply_ready, check_archive_ready, check_review_complete, check_superspec_gate, check_task_complete, check_task_edit, check_task_reopen, apply_worker_chain_lifecycle_reasons, } from "./gates.js";
+import { evidence_schema_guard, check_apply_ready, check_archive_ready, check_review_complete, check_superspec_gate, check_task_complete, check_task_edit, check_task_reopen, } from "./gates.js";
 import { final_verification_evidences, index_evidence, live_pass, live_user_confirmations } from "./evidence.js";
 import { file_blob_sha, dirty_worktree_paths } from "./git.js";
 import { preset_upgrade_reasons, preset_upgrade_required_from_context } from "./archive.js";
 import { state_corrupt_reasons, state_stale_reasons } from "./state.js";
 import { parse_tasks, resolve_test_contract_command, splitList, test_contract_invariant_refs_by_test } from "./tasks.js";
 import { APPLY_CODE_REVIEW_REPORT_REQUIRED_FIELDS, APPLY_EXECUTOR_REPORT_REQUIRED_FIELDS, APPLY_TEST_RUNNER_REPORT_REQUIRED_FIELDS, APPLY_VERIFIER_REPORT_REQUIRED_FIELDS, apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, apply_worker_protected_path_refs, compute_apply_worker_freshness, fingerprint_digest, fingerprint_matches, pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, pre_edit_evidence_ref_reasons, read_pinned_artifact_json, worker_input_ref_digest, worker_test_run_reasons, } from "./apply_worker_chain.js";
+import { apply_worker_chain_lifecycle_state } from "./apply_worker_chain_lifecycle.js";
 function load_packet_context(change) {
     if (typeof runtime.load_context === "function") {
         const [status, repoRoot, changeRoot, evidences] = runtime.load_context(change);
@@ -688,91 +689,9 @@ function active_apply_worker_chain_id(ctx, taskId) {
     const active = active_apply_worker_chain(ctx, taskId).active;
     return active ? String(active.apply_worker_chain_id) : null;
 }
-function terminal_apply_worker_chain_valid(ctx, ev, taskId, chainId) {
-    const state = String(ev.chain_state ?? "");
-    if (state === "closed") {
-        return shared_pinned_artifact_ref_reasons(ctx.changeRoot, ev.executor_report_ref, "executor_report_ref", { kind: "worker_report", role: "executor", taskId, chainId }).length === 0
-            && shared_pinned_artifact_ref_reasons(ctx.changeRoot, ev.task_code_review_report_ref, "task_code_review_report_ref", { kind: "worker_report", role: "code-reviewer", taskId, chainId }).length === 0
-            && shared_pinned_artifact_ref_reasons(ctx.changeRoot, ev.verifier_report_ref, "verifier_report_ref", { kind: "worker_report", role: "verifier", taskId, chainId }).length === 0;
-    }
-    if (state === "abandoned") {
-        if ("restored_implementation_fingerprint" in ev && fingerprint_digest(ev.restored_implementation_fingerprint))
-            return true;
-        if ("serial_takeover_baseline_ref" in ev) {
-            return shared_pinned_artifact_ref_reasons(ctx.changeRoot, ev.serial_takeover_baseline_ref, "serial_takeover_baseline_ref", { kind: "status_report", role: "verifier", taskId, chainId }).length === 0
-                && Array.isArray(ev.successor_green_evidence_refs)
-                && ev.successor_green_evidence_refs.length > 0
-                && ev.successor_green_evidence_refs.every((item) => typeof item === "string" && item.length > 0);
-        }
-    }
-    return false;
-}
 function apply_worker_chain_packet_state(ctx, taskId) {
-    const chains = ctx.evidences
-        .filter((ev) => isObject(ev) && !ev._invalid && ev.status === "pass" && ev.gate === "task_complete" && ev.kind === "apply_worker_chain" && ev.task_id === taskId)
-        .filter((ev) => typeof ev.apply_worker_chain_id === "string" && ev.apply_worker_chain_id);
-    const blockers = [];
-    const activeByChain = new Map();
-    const terminalsByChain = new Map();
-    for (const ev of chains) {
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        if (String(ev.chain_state ?? "") === "active") {
-            const bucket = activeByChain.get(chainId) ?? [];
-            bucket.push(ev);
-            activeByChain.set(chainId, bucket);
-        }
-        if (String(ev.chain_state ?? "") === "closed" || String(ev.chain_state ?? "") === "abandoned") {
-            const bucket = terminalsByChain.get(chainId) ?? [];
-            bucket.push(ev);
-            terminalsByChain.set(chainId, bucket);
-        }
-    }
-    const validTerminalChainIds = new Set(chains
-        .filter((ev) => String(ev.chain_state ?? "") === "closed" || String(ev.chain_state ?? "") === "abandoned")
-        .filter((ev) => terminal_apply_worker_chain_valid(ctx, ev, taskId, String(ev.apply_worker_chain_id ?? "")))
-        .map((ev) => String(ev.apply_worker_chain_id ?? ""))
-        .filter(Boolean));
-    const duplicateActives = [...activeByChain.entries()]
-        .filter(([chainId]) => !validTerminalChainIds.has(chainId))
-        .map(([, items]) => items)
-        .filter((items) => items.length > 1)
-        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
-        .filter(Boolean)
-        .sort();
-    const activeCandidates = [...activeByChain.entries()]
-        .filter(([chainId]) => !validTerminalChainIds.has(chainId))
-        .map(([, items]) => items[0])
-        .filter(Boolean);
-    blockers.push(...apply_worker_chain_lifecycle_reasons(ctx.repoRoot, ctx.changeRoot, ctx.evidences, taskId).filter((item) => (item.code === "apply_worker_chain_active_conflict"
-        || item.code === "apply_worker_chain_terminal_conflict"
-        || item.code === "apply_worker_chain_terminal_invalid"
-        || item.code === "apply_worker_chain_missing_active")));
-    const parallelActives = activeCandidates.length > 1
-        ? activeCandidates.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")).filter(Boolean).sort()
-        : [];
-    const activeConflicts = [...new Set([...duplicateActives, ...parallelActives])].sort();
-    if (activeConflicts.length > 0) {
-        blockers.push(reason("apply_worker_chain_active_conflict", `task ${taskId} has conflicting active apply worker chain markers: ${renderList(activeConflicts)}`, activeConflicts));
-    }
-    const duplicateTerminals = [...terminalsByChain.values()]
-        .filter((items) => items.length > 1)
-        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
-        .filter(Boolean)
-        .sort();
-    if (duplicateTerminals.length > 0) {
-        blockers.push(reason("apply_worker_chain_terminal_conflict", `task ${taskId} has duplicate apply worker chain terminal markers: ${renderList(duplicateTerminals)}`, duplicateTerminals));
-    }
-    const invalidTerminals = chains
-        .filter((ev) => String(ev.chain_state ?? "") === "closed" || String(ev.chain_state ?? "") === "abandoned")
-        .filter((ev) => !terminal_apply_worker_chain_valid(ctx, ev, taskId, String(ev.apply_worker_chain_id ?? "")))
-        .map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? ""))
-        .filter(Boolean)
-        .sort();
-    if (invalidTerminals.length > 0) {
-        blockers.push(reason("apply_worker_chain_terminal_invalid", `task ${taskId} has invalid apply worker chain terminal markers: ${renderList(invalidTerminals)}`, invalidTerminals));
-    }
-    const active = activeCandidates[0] ?? null;
-    return { active: blockers.length === 0 ? active : null, blockers };
+    const state = apply_worker_chain_lifecycle_state(ctx.repoRoot, ctx.changeRoot, ctx.evidences, taskId);
+    return { active: state.active, blockers: state.packetBlockers };
 }
 function active_apply_worker_chain(ctx, taskId) {
     return apply_worker_chain_packet_state(ctx, taskId);

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.6",
+  "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
+}