@peterxiaoyang/superspec 0.1.5 → 0.1.6

package/dist/src/cli_args.d.ts

@@ -7,9 +7,17 @@ export type ParsedArgs = {
     artifact?: string;
     gate?: string;
     task_id?: string;
+    test_id?: string;
+    phase?: "red" | "characterization" | "green";
     role?: string;
     evidence_kind?: string;
     round?: number;
+    executor_report_refs?: string[];
+    task_code_review_report_refs?: string[];
+    apply_worker_chain_refs?: string[];
+    green_test_run_evidence_refs?: string[];
+    red_test_run_evidence_refs?: string[];
+    characterization_test_run_evidence_refs?: string[];
     create?: boolean;
     force_unlock?: boolean;
     rebuild_corrupt?: boolean;

package/dist/src/cli_args.js

@@ -22,12 +22,22 @@ const COMMANDS = [
     "check-task-complete",
     "workflow-packet",
     "review-packet",
+    "apply-test-packet",
+    "apply-executor-packet",
+    "apply-code-review-packet",
+    "apply-verify-packet",
     "ledger-render",
 ];
 const COMMAND_LIST = COMMANDS.join(",");
 const COMMAND_CHOICES = COMMANDS.map((item) => `'${item}'`).join(", ");
 function isPacketCommand(command) {
-    return command === "workflow-packet" || command === "review-packet" || command === "ledger-render";
+    return command === "workflow-packet"
+        || command === "review-packet"
+        || command === "apply-test-packet"
+        || command === "apply-executor-packet"
+        || command === "apply-code-review-packet"
+        || command === "apply-verify-packet"
+        || command === "ledger-render";
 }
 function requiredValueFlags(command) {
     const flags = ["--change"];
@@ -41,6 +51,14 @@ function requiredValueFlags(command) {
         flags.push("--gate");
     if (command === "review-packet")
         flags.push("--gate", "--role", "--round");
+    if (command === "apply-test-packet")
+        flags.push("--task-id", "--test-id", "--phase");
+    if (command === "apply-executor-packet")
+        flags.push("--task-id");
+    if (command === "apply-code-review-packet")
+        flags.push("--task-id", "--executor-report-ref");
+    if (command === "apply-verify-packet")
+        flags.push("--task-id", "--executor-report-ref", "--task-code-review-report-ref", "--green-test-run-evidence-ref");
     if (command === "ledger-render")
         flags.push("--gate");
     return flags;
@@ -58,6 +76,12 @@ function optionalValueFlags(command) {
         return ["--task-id"];
     if (command === "review-packet")
         return ["--kind"];
+    if (command === "apply-test-packet")
+        return ["--task-code-review-report-ref"];
+    if (command === "apply-executor-packet")
+        return ["--apply-worker-chain-ref"];
+    if (command === "apply-verify-packet")
+        return ["--red-test-run-evidence-ref", "--characterization-test-run-evidence-ref"];
     if (command === "ledger-render")
         return ["--round"];
     return [];
@@ -65,14 +89,23 @@ function optionalValueFlags(command) {
 function formatUsage(command) {
     if (command === "workflow-packet")
         return "--format {agent}";
-    if (command === "review-packet")
+    if (command === "review-packet"
+        || command === "apply-test-packet"
+        || command === "apply-executor-packet"
+        || command === "apply-code-review-packet"
+        || command === "apply-verify-packet")
         return "--format {agent,prompt}";
     if (command === "ledger-render")
         return null;
     return "[--format {json,agent,user}]";
 }
 function requiresFormat(command) {
-    return command === "workflow-packet" || command === "review-packet";
+    return command === "workflow-packet"
+        || command === "review-packet"
+        || command === "apply-test-packet"
+        || command === "apply-executor-packet"
+        || command === "apply-code-review-packet"
+        || command === "apply-verify-packet";
 }
 function rootUsage() {
     return `usage: superspec_guard [-h]\n                     {${COMMAND_LIST}}\n                     ...\n`;
@@ -173,14 +206,19 @@ export function parse_argv(argv) {
     };
     const getValue = (flag) => getValues(flag)[0];
     const formatValues = getValues("--format");
-    const isPacketOutputCommand = command === "workflow-packet" || command === "review-packet";
+    const isPacketOutputCommand = command === "workflow-packet"
+        || command === "review-packet"
+        || command === "apply-test-packet"
+        || command === "apply-executor-packet"
+        || command === "apply-code-review-packet"
+        || command === "apply-verify-packet";
     const isPacketCommand = isPacketOutputCommand || command === "ledger-render";
     const selectedPacketFormat = formatValues.length > 0 ? formatValues[formatValues.length - 1] : undefined;
     if (isPacketOutputCommand) {
         if (!selectedPacketFormat)
             throw new GuardError("缺少必填参数 --format");
         for (const value of formatValues)
-            parsePacketOutputFormat(value, { allowPrompt: command === "review-packet" });
+            parsePacketOutputFormat(value, { allowPrompt: command !== "workflow-packet" });
     }
     else {
         for (const value of formatValues)
@@ -248,6 +286,84 @@ export function parse_argv(argv) {
             packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
         };
     }
+    if (command === "apply-test-packet") {
+        const taskId = getValue("--task-id");
+        const testId = getValue("--test-id");
+        const phase = getValue("--phase");
+        if (!taskId)
+            throw new GuardError("apply-test-packet 缺少必填参数 --task-id");
+        if (!testId)
+            throw new GuardError("apply-test-packet 缺少必填参数 --test-id");
+        if (phase !== "red" && phase !== "characterization" && phase !== "green") {
+            throw new GuardError("--phase 只允许 red、characterization 或 green");
+        }
+        return {
+            command,
+            change,
+            task_id: taskId,
+            test_id: testId,
+            phase,
+            task_code_review_report_refs: getValues("--task-code-review-report-ref"),
+            packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
+        };
+    }
+    if (command === "apply-executor-packet") {
+        const taskId = getValue("--task-id");
+        if (!taskId)
+            throw new GuardError("apply-executor-packet 缺少必填参数 --task-id");
+        return {
+            command,
+            change,
+            task_id: taskId,
+            apply_worker_chain_refs: getValues("--apply-worker-chain-ref"),
+            packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
+        };
+    }
+    if (command === "apply-code-review-packet") {
+        const taskId = getValue("--task-id");
+        const executorRefs = getValues("--executor-report-ref");
+        if (!taskId)
+            throw new GuardError("apply-code-review-packet 缺少必填参数 --task-id");
+        if (executorRefs.length === 0)
+            throw new GuardError("apply-code-review-packet 缺少必填参数 --executor-report-ref");
+        return {
+            command,
+            change,
+            task_id: taskId,
+            executor_report_refs: executorRefs,
+            packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
+        };
+    }
+    if (command === "apply-verify-packet") {
+        const taskId = getValue("--task-id");
+        const executorRefs = getValues("--executor-report-ref");
+        const codeReviewRefs = getValues("--task-code-review-report-ref");
+        const greenRefs = getValues("--green-test-run-evidence-ref");
+        const redRefs = getValues("--red-test-run-evidence-ref");
+        const characterizationRefs = getValues("--characterization-test-run-evidence-ref");
+        if (!taskId)
+            throw new GuardError("apply-verify-packet 缺少必填参数 --task-id");
+        if (executorRefs.length === 0)
+            throw new GuardError("apply-verify-packet 缺少必填参数 --executor-report-ref");
+        if (codeReviewRefs.length === 0)
+            throw new GuardError("apply-verify-packet 缺少必填参数 --task-code-review-report-ref");
+        if (greenRefs.length === 0)
+            throw new GuardError("apply-verify-packet 缺少必填参数 --green-test-run-evidence-ref");
+        if (redRefs.length === 0 && characterizationRefs.length === 0) {
+            throw new GuardError("apply-verify-packet requires --red-test-run-evidence-ref or --characterization-test-run-evidence-ref");
+        }
+        return {
+            command,
+            change,
+            task_id: taskId,
+            executor_report_refs: executorRefs,
+            task_code_review_report_refs: codeReviewRefs,
+            green_test_run_evidence_refs: greenRefs,
+            red_test_run_evidence_refs: redRefs,
+            characterization_test_run_evidence_refs: characterizationRefs,
+            packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
+        };
+    }
     if (command === "ledger-render") {
         const gate = getValue("--gate");
         const roundValue = getValue("--round");

package/dist/src/core.d.ts

@@ -9,6 +9,7 @@ export * from "./invariants.ts";
 export * from "./git.ts";
 export * from "./state.ts";
 export * from "./archive.ts";
+export * from "./apply_worker_chain.ts";
 export * from "./gates.ts";
 export * from "./install_engine.ts";
 import type { ParsedArgs } from "./cli_args.ts";

package/dist/src/core.js

@@ -9,6 +9,7 @@ export * from "./invariants.js";
 export * from "./git.js";
 export * from "./state.js";
 export * from "./archive.js";
+export * from "./apply_worker_chain.js";
 export * from "./gates.js";
 export * from "./install_engine.js";
 import { existsSync, readFileSync, statSync } from "node:fs";

package/dist/src/evidence.js

@@ -4,6 +4,7 @@ import { CLAIM_ADJUDICATION_DECISIONS, EVIDENCE_KINDS, EVIDENCE_STATUSES, FINAL_
 import { normalize_gate } from "./openspec.js";
 import { superspec_dir } from "./paths.js";
 import { findings_schema_reasons, review_digest_schema_reasons, standing_authorization_schema_reasons, user_decision_schema_reasons, } from "./disclosure.js";
+import { pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, worker_test_run_reasons, } from "./apply_worker_chain.js";
 function file_ref_reasons(baseRoot, ev, field, code) {
     const problems = [];
     const raw = ev[field];
@@ -29,6 +30,46 @@ function file_ref_reasons(baseRoot, ev, field, code) {
     }
     return problems;
 }
+function contractField(line) {
+    const match = line.match(/^\s*-\s+`?([A-Za-z0-9_-]+)`?\s*:\s*(.*)$/);
+    if (!match)
+        return null;
+    return { key: match[1], value: match[2].trim() };
+}
+function test_contract_section_lines(changeRoot, testId) {
+    const pathValue = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    if (!existsSync(pathValue) || !statSync(pathValue).isFile())
+        return [];
+    const lines = readFileSync(pathValue, "utf8").split(/\r?\n/);
+    const out = [];
+    let inSection = false;
+    for (const line of lines) {
+        const heading = line.match(/^###\s+(.+?)\s*$/);
+        if (heading) {
+            if (inSection)
+                break;
+            inSection = heading[1].trim() === testId;
+            continue;
+        }
+        if (inSection)
+            out.push(line);
+    }
+    return out;
+}
+function expected_failure_contract(changeRoot, testId) {
+    const fields = new Map();
+    for (const line of test_contract_section_lines(changeRoot, testId)) {
+        const field = contractField(line);
+        if (!field)
+            continue;
+        const values = fields.get(field.key) ?? [];
+        values.push(field.value);
+        fields.set(field.key, values);
+    }
+    const signature = (fields.get("expected_failure_signature") ?? [])[0];
+    const classifier = (fields.get("expected_failure_classifier") ?? [])[0];
+    return { signature, classifier };
+}
 function pinned_ref_list_reasons(ev, field, baseRoot, staleCode, opts = {}) {
     const problems = [];
     const raw = ev[field];
@@ -94,6 +135,30 @@ function pinned_ref_reasons(ev, field, baseRoot, staleCode) {
     }
     return problems;
 }
+function string_list_field_reasons(ev, field, code, opts = {}) {
+    const raw = ev[field];
+    if (!Array.isArray(raw) || (!opts.allowEmpty && raw.length === 0) || !raw.every((item) => typeof item === "string" && item.length > 0)) {
+        return [reason(code, `${ev._path}: ${field} must be a non-empty string list`)];
+    }
+    return [];
+}
+function fingerprint_field_reasons(ev, field, code) {
+    const raw = ev[field];
+    if (typeof raw === "string") {
+        return raw.startsWith("sha256:") ? [] : [reason(code, `${ev._path}: ${field} must be a sha256 fingerprint`)];
+    }
+    if (isObject(raw) && typeof raw.fingerprint_digest === "string" && raw.fingerprint_digest.startsWith("sha256:"))
+        return [];
+    return [reason(code, `${ev._path}: ${field} must be a sha256 fingerprint or fingerprint object`)];
+}
+function pinned_artifact_ref_item_reasons(refItem, field, changeRoot, expected = {}) {
+    return shared_pinned_artifact_ref_reasons(changeRoot, refItem, field, {
+        kind: expected.kind,
+        role: expected.role,
+        taskId: expected.task_id,
+        chainId: expected.chain_id,
+    });
+}
 export function role_target_ref_reasons(ev, targetRoot) {
     return pinned_ref_reasons(ev, "target_refs", targetRoot, "stale_review");
 }
@@ -328,6 +393,26 @@ function test_run_reasons(ev, changeRoot) {
     if (typeof ev.result_summary !== "string" || !ev.result_summary.trim()) {
         problems.push(reason("test_run_summary_missing", `${ev._path}: test_run requires non-empty result_summary`));
     }
+    const runnerOrigin = ev.runner_origin;
+    const executorWorkerRun = ev.apply_execution_chain === "executor_worker";
+    if (runnerOrigin !== undefined && runnerOrigin !== "main-thread" && runnerOrigin !== "test-runner") {
+        problems.push(reason("test_run_runner_origin_invalid", `${ev._path}: runner_origin must be main-thread or test-runner`));
+    }
+    if (runnerOrigin === "test-runner" && (typeof ev.phase !== "string" || !ev.phase)) {
+        problems.push(reason("test_run_runner_origin_invalid", `${ev._path}: runner_origin=test-runner requires phase`));
+    }
+    if (runnerOrigin === "test-runner" && ev.gate === "task_complete" && ev.semantic_status === "expected_success" && !executorWorkerRun) {
+        problems.push(reason("test_run_runner_origin_invalid", `${ev._path}: test-runner GREEN evidence must belong to apply_execution_chain=executor_worker`));
+    }
+    if (executorWorkerRun && runnerOrigin !== "test-runner") {
+        problems.push(reason("test_run_runner_origin_invalid", `${ev._path}: apply_execution_chain=executor_worker requires runner_origin=test-runner`));
+    }
+    if (executorWorkerRun && (typeof ev.apply_worker_chain_id !== "string" || !ev.apply_worker_chain_id)) {
+        problems.push(reason("test_run_worker_ref_missing", `${ev._path}: apply_execution_chain=executor_worker requires apply_worker_chain_id`));
+    }
+    if (runnerOrigin === "test-runner" || executorWorkerRun) {
+        problems.push(...worker_test_run_reasons(changeRoot, ev, typeof ev.task_id === "string" ? ev.task_id : "", executorWorkerRun && typeof ev.apply_worker_chain_id === "string" ? ev.apply_worker_chain_id : null));
+    }
     if (logTexts.length > 0) {
         const claimed = [
             ...(typeof ev.test_id === "string" && ev.test_id.trim() ? [ev.test_id.trim()] : []),
@@ -339,6 +424,71 @@ function test_run_reasons(ev, changeRoot) {
             }
         }
     }
+    if (ev.semantic_status === "expected_failure" && typeof ev.test_id === "string" && ev.test_id.trim()) {
+        const expected = expected_failure_contract(changeRoot, ev.test_id.trim());
+        if (expected.signature) {
+            if (ev.expected_failure_signature !== expected.signature) {
+                problems.push(reason("test_run_wrong_failure_reason", `${ev._path}: RED evidence expected_failure_signature must match test contract for ${ev.test_id}`, [ev.test_id]));
+            }
+            if (!logTexts.some((text) => text.includes(String(expected.signature)))) {
+                problems.push(reason("test_run_wrong_failure_reason", `${ev._path}: RED raw_log_refs do not contain expected_failure_signature for ${ev.test_id}`, [ev.test_id]));
+            }
+        }
+        if (expected.classifier && ev.expected_failure_classifier !== expected.classifier) {
+            problems.push(reason("test_run_wrong_failure_reason", `${ev._path}: RED evidence expected_failure_classifier must match test contract for ${ev.test_id}`, [ev.test_id]));
+        }
+    }
+    return problems;
+}
+function apply_worker_chain_reasons(ev, changeRoot) {
+    const problems = [];
+    const state = String(ev.chain_state ?? "");
+    if (!["active", "closed", "abandoned"].includes(state)) {
+        problems.push(reason("apply_worker_chain_invalid", `${ev._path}: apply_worker_chain chain_state must be active, closed, or abandoned`));
+    }
+    for (const field of ["task_id", "apply_worker_chain_id"]) {
+        if (typeof ev[field] !== "string" || !ev[field])
+            problems.push(reason("apply_worker_chain_invalid", `${ev._path}: apply_worker_chain requires ${field}`));
+    }
+    if (state === "active") {
+        problems.push(...fingerprint_field_reasons(ev, "executor_packet_fingerprint", "apply_worker_chain_invalid"));
+        problems.push(...fingerprint_field_reasons(ev, "source_implementation_fingerprint", "apply_worker_chain_invalid"));
+        problems.push(...string_list_field_reasons(ev, "declared_task_write_scope", "apply_worker_chain_invalid"));
+        problems.push(...string_list_field_reasons(ev, "pre_edit_evidence_refs", "apply_worker_chain_invalid"));
+    }
+    if (state === "closed") {
+        const taskId = typeof ev.task_id === "string" ? ev.task_id : undefined;
+        const chainId = typeof ev.apply_worker_chain_id === "string" ? ev.apply_worker_chain_id : undefined;
+        const refProblems = [
+            ...pinned_artifact_ref_item_reasons(ev.executor_report_ref, "executor_report_ref", changeRoot, { kind: "worker_report", role: "executor", task_id: taskId, chain_id: chainId }),
+            ...pinned_artifact_ref_item_reasons(ev.task_code_review_report_ref, "task_code_review_report_ref", changeRoot, { kind: "worker_report", role: "code-reviewer", task_id: taskId, chain_id: chainId }),
+            ...pinned_artifact_ref_item_reasons(ev.verifier_report_ref, "verifier_report_ref", changeRoot, { kind: "worker_report", role: "verifier", task_id: taskId, chain_id: chainId }),
+        ];
+        problems.push(...refProblems);
+        if (refProblems.length > 0)
+            problems.push(reason("apply_worker_chain_invalid", `${ev._path}: closed apply_worker_chain report refs must be pinned same-chain worker reports`));
+        if (!isObject(ev.green_test_run_evidence_ref) && typeof ev.green_test_run_evidence_ref !== "string") {
+            problems.push(reason("apply_worker_chain_invalid", `${ev._path}: closed apply_worker_chain requires green_test_run_evidence_ref`));
+        }
+        problems.push(...fingerprint_field_reasons(ev, "observed_freshness_fingerprint", "apply_worker_chain_invalid"));
+    }
+    if (state === "abandoned") {
+        const taskId = typeof ev.task_id === "string" ? ev.task_id : undefined;
+        const chainId = typeof ev.apply_worker_chain_id === "string" ? ev.apply_worker_chain_id : undefined;
+        if ("restored_implementation_fingerprint" in ev) {
+            problems.push(...fingerprint_field_reasons(ev, "restored_implementation_fingerprint", "apply_worker_chain_invalid"));
+        }
+        if (!("restored_implementation_fingerprint" in ev) && !("serial_takeover_baseline_ref" in ev)) {
+            problems.push(reason("apply_worker_chain_invalid", `${ev._path}: abandoned apply_worker_chain requires restored_implementation_fingerprint or serial_takeover_baseline_ref`));
+        }
+        if ("serial_takeover_baseline_ref" in ev) {
+            const baselineProblems = pinned_artifact_ref_item_reasons(ev.serial_takeover_baseline_ref, "serial_takeover_baseline_ref", changeRoot, { kind: "status_report", role: "verifier", task_id: taskId, chain_id: chainId });
+            problems.push(...baselineProblems);
+            if (baselineProblems.length > 0)
+                problems.push(reason("apply_worker_chain_invalid", `${ev._path}: abandoned apply_worker_chain serial_takeover_baseline_ref must be a pinned same-chain status_report`));
+            problems.push(...string_list_field_reasons(ev, "successor_green_evidence_refs", "apply_worker_chain_invalid"));
+        }
+    }
     return problems;
 }
 export function validate_evidence_schema(ev, change, changeRoot, repoRoot) {
@@ -359,6 +509,8 @@ export function validate_evidence_schema(ev, change, changeRoot, repoRoot) {
         problems.push(...human_confirmation_reasons(ev));
     if (ev.kind === "test_run")
         problems.push(...test_run_reasons(ev, changeRoot));
+    if (ev.kind === "apply_worker_chain")
+        problems.push(...apply_worker_chain_reasons(ev, changeRoot));
     // DISC Phase 1: disclosure evidence kinds and reviewer findings[] are schema-checked fail-closed.
     if (ev.kind === "main_review_digest")
         problems.push(...review_digest_schema_reasons(ev));

package/dist/src/gates.d.ts

@@ -10,6 +10,7 @@ export declare function check_artifact(change: string, status: JsonMap, changeRo
 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 apply_worker_chain_lifecycle_reasons(repoRoot: string, changeRoot: string, evidences: JsonMap[], taskId: string): Reason[];
 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;
 export declare function check_review_complete(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;