@peterxiaoyang/superspec 0.1.1 → 0.1.3

package/dist/src/doctor.js

@@ -0,0 +1,230 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PACKAGE_ROOT } from "./install_engine.js";
+import { openspec_cli_probe } from "./openspec.js";
+import { commandExists, runCommand } from "./util.js";
+function readPackageJson(packageRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function superspec_package_version(packageRoot = PACKAGE_ROOT) {
+    const version = readPackageJson(packageRoot).version;
+    return typeof version === "string" && version ? version : "0.0.0";
+}
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+function pathInfo(filePath) {
+    if (!filePath)
+        return null;
+    const info = { path: filePath, exists: existsSync(filePath) };
+    if (!info.exists)
+        return info;
+    try {
+        const stat = lstatSync(filePath);
+        info.kind = stat.isSymbolicLink() ? "symlink" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+        if (stat.isSymbolicLink())
+            info.link_target = readlinkSync(filePath);
+        info.realpath = realpathMaybe(filePath);
+    }
+    catch (err) {
+        info.error = err.message;
+    }
+    return info;
+}
+function firstNonEmptyLine(text) {
+    return text.split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0) ?? null;
+}
+function commandPath(cmd, opts) {
+    if (!opts.commandExistsFn(cmd, { cwd: opts.cwd }))
+        return null;
+    const proc = opts.platform === "win32"
+        ? opts.run("where.exe", [cmd], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform })
+        : opts.run("sh", ["-c", `command -v ${cmd}`], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0)
+        return null;
+    return firstNonEmptyLine(proc.stdout);
+}
+function npmValue(args, opts) {
+    if (!opts.commandExistsFn("npm", { cwd: opts.cwd }))
+        return { available: false, value: null, error: "npm not found on PATH" };
+    const proc = opts.run("npm", args, { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0) {
+        return {
+            available: true,
+            value: null,
+            error: (proc.error?.message ?? (proc.stderr || proc.stdout)).trim(),
+        };
+    }
+    return { available: true, value: firstNonEmptyLine(proc.stdout), error: null };
+}
+function containsUnscopedSuperspecNodeModule(value) {
+    if (!value)
+        return false;
+    return /[/\\]node_modules[/\\]superspec[/\\]/u.test(value);
+}
+function add(checks, status, name, detail, refs) {
+    checks.push({ status, name, detail, refs });
+}
+export function build_doctor_report(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+    const platform = opts.platform ?? process.platform;
+    const run = opts.run ?? runCommand;
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd, platform }));
+    const packageJson = readPackageJson(packageRoot);
+    const version = superspec_package_version(packageRoot);
+    const packageName = typeof packageJson.name === "string" ? packageJson.name : "unknown";
+    const expectedBin = join(packageRoot, "bin", "superspec.js");
+    const resolvedCommand = commandPath("superspec", { cwd, platform, commandExistsFn, run });
+    const command = pathInfo(resolvedCommand);
+    const prefix = npmValue(["prefix", "-g"], { cwd, platform, commandExistsFn, run });
+    const root = npmValue(["root", "-g"], { cwd, platform, commandExistsFn, run });
+    const npmRoot = typeof root.value === "string" ? root.value : null;
+    const scopedPackage = npmRoot ? pathInfo(join(npmRoot, "@peterxiaoyang", "superspec")) : null;
+    const unscopedPackage = npmRoot ? pathInfo(join(npmRoot, "superspec")) : null;
+    const openspecProbe = openspec_cli_probe({ cwd, commandExistsFn, run });
+    const checks = [];
+    const nextActions = [];
+    if (packageName === "@peterxiaoyang/superspec" && version !== "0.0.0") {
+        add(checks, "ok", "package metadata", `${packageName}@${version}`);
+    }
+    else {
+        add(checks, "fail", "package metadata", `could not identify @peterxiaoyang/superspec package metadata under ${packageRoot}`);
+    }
+    if (openspecProbe.ok) {
+        add(checks, "ok", "OpenSpec CLI", openspecProbe.message);
+    }
+    else {
+        add(checks, "fail", "OpenSpec CLI", openspecProbe.message);
+        nextActions.push("npm install -g @fission-ai/openspec@latest");
+    }
+    if (!command) {
+        add(checks, "warn", "superspec command", "`superspec` is not resolvable from PATH in this shell");
+    }
+    else {
+        const commandRealpath = typeof command.realpath === "string" ? command.realpath : undefined;
+        const commandTarget = typeof command.link_target === "string" ? command.link_target : undefined;
+        if (containsUnscopedSuperspecNodeModule(commandRealpath) || containsUnscopedSuperspecNodeModule(commandTarget)) {
+            add(checks, "fail", "superspec command owner", "`superspec` points at the unscoped `superspec` package, which conflicts with @peterxiaoyang/superspec", [String(command.path)]);
+            nextActions.push("npm uninstall -g superspec");
+            nextActions.push("npm install -g @peterxiaoyang/superspec@latest");
+        }
+        else if (existsSync(expectedBin) && commandRealpath && realpathMaybe(expectedBin) !== commandRealpath) {
+            add(checks, "warn", "superspec command owner", "`superspec` on PATH does not point at this package root", [String(command.path), expectedBin]);
+        }
+        else {
+            add(checks, "ok", "superspec command owner", "`superspec` resolves to this package");
+        }
+    }
+    if (root.error) {
+        add(checks, "warn", "npm global root", String(root.error));
+    }
+    else if (npmRoot) {
+        add(checks, "ok", "npm global root", npmRoot);
+    }
+    if (unscopedPackage?.exists) {
+        add(checks, "warn", "unscoped superspec package", "global package `superspec` is installed and can claim the same `superspec` binary", [String(unscopedPackage.path)]);
+        nextActions.push("npm uninstall -g superspec");
+    }
+    if (scopedPackage && !scopedPackage.exists) {
+        add(checks, "warn", "scoped superspec package", "@peterxiaoyang/superspec is not present under npm global root", [String(scopedPackage.path)]);
+    }
+    const dedupedNextActions = [...new Set(nextActions)];
+    return {
+        ok: !checks.some((check) => check.status === "fail"),
+        cwd,
+        superspec: {
+            name: packageName,
+            version,
+            package_root: packageRoot,
+            expected_bin: expectedBin,
+            entry: opts.argv0 ?? process.argv[1] ?? null,
+            command,
+            scoped_global_package: scopedPackage,
+            unscoped_global_package: unscopedPackage,
+        },
+        node: {
+            version: process.versions.node,
+            exec_path: process.execPath,
+            platform,
+        },
+        npm: {
+            prefix,
+            root,
+        },
+        openspec: {
+            ok: openspecProbe.ok,
+            state: openspecProbe.state,
+            version: openspecProbe.version,
+            message: openspecProbe.message,
+        },
+        checks,
+        next_actions: dedupedNextActions,
+    };
+}
+export function render_doctor_report(report) {
+    const lines = [
+        "SuperSpec doctor",
+        "",
+        `SuperSpec: ${report.superspec.name}@${report.superspec.version}`,
+        `Package root: ${report.superspec.package_root}`,
+        `Command path: ${report.superspec.command?.path ?? "not found"}`,
+        `OpenSpec: ${report.openspec.message}`,
+        `Node: ${report.node.version} (${report.node.platform})`,
+        `npm prefix: ${report.npm.prefix.value ?? "unknown"}`,
+        `npm root: ${report.npm.root.value ?? "unknown"}`,
+        "",
+        "Checks:",
+        ...report.checks.map((check) => {
+            const refs = check.refs && check.refs.length > 0 ? ` (${check.refs.join(", ")})` : "";
+            return `  [${check.status}] ${check.name}: ${check.detail}${refs}`;
+        }),
+    ];
+    if (report.next_actions.length > 0) {
+        lines.push("", "Next actions:", ...report.next_actions.map((action) => `  ${action}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function doctorHelp() {
+    return [
+        "usage: superspec doctor [--json]",
+        "",
+        "diagnoses SuperSpec, OpenSpec, npm global package, and PATH wiring.",
+        "",
+        "options:",
+        "  --json      print machine-readable JSON",
+        "  -h, --help  show this help",
+        "",
+    ].join("\n");
+}
+export function main_doctor(argv = process.argv.slice(2)) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(doctorHelp());
+        return 0;
+    }
+    const unknown = argv.filter((arg) => arg !== "--json");
+    if (unknown.length > 0) {
+        process.stderr.write(`superspec doctor: unknown option ${JSON.stringify(unknown[0])}\n\n${doctorHelp()}`);
+        return 2;
+    }
+    const report = build_doctor_report();
+    if (argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(render_doctor_report(report));
+    }
+    return report.ok ? 0 : 1;
+}

package/dist/src/evidence.d.ts

@@ -26,3 +26,4 @@ export declare function live_pass(evidences: JsonMap[], filters?: {
     kind?: string | null;
     task_id?: string | null;
 }): JsonMap[];
+export declare function live_user_confirmations(evidences: JsonMap[], gate: string): JsonMap[];

package/dist/src/evidence.js

@@ -272,6 +272,9 @@ function finding_string_list_reasons(ev, finding, field, opts = {}) {
 function human_confirmation_reasons(ev) {
     const problems = [];
     const gate = normalize_gate(String(ev.gate ?? ""));
+    if (String(ev.created_by ?? "") !== "user") {
+        problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation must be created_by user`));
+    }
     if (!HUMAN_CONFIRMATION_GATES.has(gate)) {
         problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation gate=${repr(ev.gate)} is not consumed by any guard gate; expected one of ${renderList([...HUMAN_CONFIRMATION_GATES].sort())}`));
     }
@@ -847,3 +850,7 @@ export function live_pass(evidences, filters = {}) {
     const dead = superseded_ids(evidences);
     return find_pass(evidences, filters).filter((ev) => !dead.has(ev.evidence_id));
 }
+export function live_user_confirmations(evidences, gate) {
+    return live_pass(evidences, { gate, kind: "human_confirmation" })
+        .filter((ev) => String(ev.created_by ?? "") === "user");
+}

package/dist/src/gates.d.ts

@@ -8,6 +8,7 @@ export declare function check_init(change: string, status: JsonMap, repoRoot: st
 export declare function check_superspec_gate(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], gateRaw: string): Decision;
 export declare function check_artifact(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], artifact: string): Decision;
 export declare function check_task_reopen(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
+export declare function check_apply_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;
 export declare function check_task_edit(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_task_complete(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_review_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;

package/dist/src/gates.js

@@ -1,11 +1,11 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REQUIRED_OPENSPEC_CLI_SURFACES, REQUIRED_OPENSPEC_CODEX_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, commandExists, isObject, reason, renderList, repr, pinned_ref_key, safe_within, runCommand, sha256_text, runtime, toPosix, } from "./util.js";
-import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate } from "./openspec.js";
+import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REQUIRED_OPENSPEC_CODEX_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
+import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
 import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
-import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
+import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
 function action_list(...items) {
@@ -311,7 +311,7 @@ function archive_ready_actions(change, reasons, review) {
 function default_gate_next_actions(gate) {
     switch (gate) {
         case "explore_complete":
-            return ["write .superspec/artifacts/discovery.md and record native_subagent critic evidence"];
+            return ["write .superspec/artifacts/discovery.md, record native_subagent critic evidence, and record explore_complete human confirmation"];
         case "proposal_reviewed":
             return ["run the proposal critic review (round-tagged, findings[]) and record a main_review_digest disclosing every finding"];
         case "design_complete":
@@ -356,7 +356,7 @@ export function superspec_workflow_skill_reasons(repoRoot) {
     const skillsRoot = join(repoRoot, ".codex", "skills");
     const missing = REQUIRED_SUPERSPEC_WORKFLOW_SKILLS.filter((name) => !existsSync(join(skillsRoot, name, "SKILL.md")));
     if (missing.length > 0) {
-        reasons.push(reason("superspec_init_missing", "SuperSpec workflow skills are missing; run superspec init --scope project to (re)install them", missing));
+        reasons.push(reason("superspec_init_missing", "SuperSpec workflow skills are missing; run `superspec init --scope project` to (re)install them", missing));
     }
     for (const name of REQUIRED_SUPERSPEC_WORKFLOW_SKILLS) {
         const skillPath = join(skillsRoot, name, "SKILL.md");
@@ -401,19 +401,14 @@ export function superspec_agent_reasons(repoRoot) {
     return reasons;
 }
 export function openspec_cli_capability_reasons() {
-    if (!commandExists("openspec"))
-        return [reason("openspec_cli_unavailable", "openspec CLI is not available in PATH")];
-    const problems = [];
-    for (const args of REQUIRED_OPENSPEC_CLI_SURFACES) {
-        const proc = runCommand("openspec", [...args], { timeout: 15_000 });
-        if (proc.error) {
-            problems.push(reason("openspec_native_surface_missing", `\`openspec ${args.join(" ")}\` failed: ${proc.error.message}`));
-        }
-        else if (proc.status !== 0) {
-            problems.push(reason("openspec_native_surface_missing", `\`openspec ${args.join(" ")}\` failed: ${(proc.stderr || proc.stdout).trim()}`));
-        }
-    }
-    return problems;
+    const probe = openspec_cli_probe();
+    if (probe.ok)
+        return [];
+    if (probe.state === "missing")
+        return [reason("openspec_cli_unavailable", probe.message)];
+    if (probe.state === "too_old")
+        return [reason("openspec_cli_too_old", probe.message)];
+    return [reason("openspec_native_surface_missing", probe.message)];
 }
 export function evidence_schema_guard(change, changeRoot, repoRoot, evidences) {
     return [
@@ -483,6 +478,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
                 reasons.push(reason("missing_native_subagent_evidence", `explore_complete requires native_subagent ${role} report`));
         }
         reasons.push(...stale_artifact_review_reasons(exploreReviews, changeRoot, ".superspec/artifacts/discovery.md", "stale_explore_review", "explore_complete"));
+        if (live_user_confirmations(evidences, "explore_complete").length === 0) {
+            reasons.push(reason("missing_human_confirmation", "explore_complete requires human confirmation before entering propose"));
+        }
         // DISC Phase 1: material findings raised by explore reviews must be disclosed to the user
         // (main_review_digest + user_review_decision) before the gate can pass.
         reasons.push(...review_disclosure_reasons("explore_complete", changeRoot, evidences));
@@ -515,7 +513,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             if (!designReviews.some((ev) => ev.agent_role === role))
                 reasons.push(reason(`missing_${role}_review`, `design_complete requires native_subagent ${role} report`));
         }
-        if (live_pass(evidences, { kind: "human_confirmation", gate: "design_complete" }).length === 0)
+        if (live_user_confirmations(evidences, "design_complete").length === 0)
             reasons.push(reason("missing_human_confirmation", "design_complete requires human confirmation"));
         reasons.push(...stale_artifact_review_reasons(designReviews, changeRoot, "design.md", "stale_design_review", "design_complete"));
         // DISC Phase 2: design reviews carrying round-tagged findings enter the disclosure loop
@@ -541,7 +539,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
         const humanRequired = human_confirmation_business_invariant_ids(changeRoot);
         if (humanRequired.size > 0) {
             const confirmed = new Set();
-            for (const ev of live_pass(evidences, { gate: "invariants_reviewed", kind: "human_confirmation" })) {
+            for (const ev of live_user_confirmations(evidences, "invariants_reviewed")) {
                 for (const id of evidence_invariant_refs(ev))
                     confirmed.add(id);
             }
@@ -659,6 +657,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             }
         }
     }
+    else if (gate === "apply_ready") {
+        return check_apply_ready(change, status, changeRoot, evidences);
+    }
     else {
         return block(change, gate, [reason("unknown_gate", `unknown superspec gate: ${gate}`)]);
     }
@@ -1034,6 +1035,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
         reasons.push(reason("propose_not_complete", "task_reopen requires propose_complete"));
         reasons.push(...propose.block_reasons);
     }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
     const tasks = parse_tasks(changeRoot);
     const task = tasks[taskId];
     if (!task)
@@ -1043,8 +1045,13 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
     reasons.push(...request_changes_round_reasons(evidences));
     const reopenCheck = active_task_reopen_reasons(changeRoot, evidences, task, taskId, "pre_revert");
     reasons.push(...reopenCheck.reasons);
-    if (reasons.length > 0)
-        return block(change, gate, reasons, { task_id: taskId, next_actions: [`keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`] });
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            task_id: taskId,
+            next_actions: action_list(reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null, `keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`),
+        });
+    }
     return allow(change, gate, { task_id: taskId });
 }
 // FIX-8 (audit A-5): apply work requires the user's explicit isolation/execution-mode choice,
@@ -1053,7 +1060,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
 // apply-phase scope expansion (SPEC §14.7) and demands explicit user re-approval — redesign,
 // split into a new change, or record a scope_expansion confirmation re-pinning the structure.
 function apply_scope_confirmation_reasons(changeRoot, evidences) {
-    const isolation = live_pass(evidences, { gate: "apply_isolation", kind: "human_confirmation" });
+    const isolation = live_user_confirmations(evidences, "apply_isolation");
     const currentHash = tasks_structure_hash(changeRoot);
     if (isolation.length === 0) {
         const hashHint = currentHash ? ` with tasks_structure_hash=${currentHash}` : "";
@@ -1061,11 +1068,28 @@ function apply_scope_confirmation_reasons(changeRoot, evidences) {
     }
     if (currentHash === null)
         return [];
-    const approvals = [...isolation, ...live_pass(evidences, { gate: "scope_expansion", kind: "human_confirmation" })];
+    const approvals = [...isolation, ...live_user_confirmations(evidences, "scope_expansion")];
     if (approvals.some((ev) => String(ev.tasks_structure_hash ?? "") === currentHash))
         return [];
     return [reason("scope_expansion_unconfirmed", `tasks.md structure changed after the last user-approved apply scope; ask the user to redesign/split the change or re-approve by recording gate="scope_expansion" human_confirmation with tasks_structure_hash=${currentHash}`)];
 }
+export function check_apply_ready(change, status, changeRoot, evidences) {
+    const gate = "apply_ready";
+    const reasons = [];
+    const propose = check_superspec_gate(change, status, changeRoot, evidences, "propose_complete");
+    if (!propose.allowed) {
+        reasons.push(reason("propose_not_complete", "apply_ready requires propose_complete"));
+        reasons.push(...propose.block_reasons);
+    }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            next_actions: action_list(!propose.allowed ? "pass propose_complete before apply" : null, reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null),
+        });
+    }
+    return allow(change, gate, { openspec_summary: artifact_status_map(status) });
+}
 export function check_task_edit(change, status, changeRoot, evidences, taskId) {
     const gate = "task_edit";
     const reasons = [];
@@ -1383,7 +1407,7 @@ export function check_review_complete(change, status, changeRoot, evidences) {
         && (ev.kind === "verification_review" || ev.kind === "final_test")
         && ev.status === "fail");
     if (failedVerifications.length > 0) {
-        const dispositions = new Set(live_pass(evidences, { gate: "verify_failure_handling", kind: "human_confirmation" })
+        const dispositions = new Set(live_user_confirmations(evidences, "verify_failure_handling")
             .flatMap((ev) => (Array.isArray(ev.confirmed_refs) ? ev.confirmed_refs.map((item) => String(item)) : [])));
         const unhandled = failedVerifications
             .map((ev) => String(ev.evidence_id ?? ev._path ?? "unknown"))
@@ -1461,7 +1485,7 @@ export function check_archive_ready(change, status, changeRoot, evidences) {
     if (!ok && !reviewCodes.has("validate_failed")) {
         reasons.push(reason("validate_failed", "openspec validate did not pass"));
     }
-    if (live_pass(evidences, { gate: "archive_ready", kind: "human_confirmation" }).length === 0) {
+    if (live_user_confirmations(evidences, "archive_ready").length === 0) {
         reasons.push(reason("missing_final_confirmation", "archive_ready requires human confirmation evidence"));
     }
     if (reasons.length > 0)

package/dist/src/git.js

@@ -2,7 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { dirname, isAbsolute, relative } from "node:path";
 import { GuardError, reason, renderList, runCommand, runtime } from "./util.js";
 import { splitList, task_test_evidence } from "./tasks.js";
-import { live_pass } from "./evidence.js";
+import { live_user_confirmations } from "./evidence.js";
 export function file_blob_sha(filePath) {
     if (!existsSync(filePath) || !statSync(filePath).isFile())
         throw new GuardError(`git_blob_inspection_failure: reviewed target missing: ${filePath}`);
@@ -50,7 +50,7 @@ export function dirty_worktree_reasons(repoRoot, changeRoot, evidences) {
     const unknown = dirty.filter((item) => !(changeRel && item.startsWith(`${changeRel}/`)));
     if (unknown.length === 0)
         return [];
-    const confirmations = live_pass(evidences, { gate: "branch_handling", kind: "human_confirmation" });
+    const confirmations = live_user_confirmations(evidences, "branch_handling");
     const confirmedScopes = confirmations.flatMap((ev) => (Array.isArray(ev.confirmed_paths) ? ev.confirmed_paths.map((item) => String(item)).filter(Boolean) : []));
     const unconfirmed = unknown.filter((item) => !confirmedScopes.some((scope) => pathInScope(item, scope)));
     if (unconfirmed.length === 0)