project-tiny-context-harness 0.2.82 → 0.2.84

package/dist/lib/superpowers-task-evidence-kernel.js

@@ -0,0 +1,347 @@
+import { deriveRequiredCommandSpecs } from "./superpowers-task-command-specs.js";
+import { validateCommandRunsForSpec, validateRequiredCommandCorrelation } from "./superpowers-task-command-run-correlation.js";
+import { evaluateAc010Bootstrap } from "./superpowers-task-ac010.js";
+import { evaluateCurrentAttemptArtifact } from "./superpowers-task-current-evidence.js";
+import { scanSuperpowersContradictions } from "./superpowers-task-contradictions.js";
+import { detectHarnessDrift } from "./superpowers-task-harness-drift.js";
+import { evaluateProtectedBaseline } from "./superpowers-task-protected-baseline.js";
+import { validateScopeConflicts } from "./superpowers-task-delivery.js";
+import { evaluateProofLayerAssertions, isMachineVerifiableLayer } from "./superpowers-task-assertions.js";
+import { scanUnregisteredAssertionEvidence } from "./superpowers-task-unregistered-evidence.js";
+import { findUnderSpecifiedAcs } from "./superpowers-task-under-specified.js";
+import { loadSuperpowersState, sourceRecords } from "./superpowers-task-state.js";
+export const TRUSTED_EVIDENCE_KERNEL_ORDER = [
+    "load_three_inputs",
+    "recompute_source_hashes",
+    "load_task_state",
+    "resolve_current_attempt",
+    "load_required_command_specs",
+    "load_command_run_records",
+    "load_registered_evidence_records",
+    "discard_stale_evidence",
+    "scan_unregistered_assertion_json",
+    "scan_contradictions",
+    "run_ac010_bootstrap_prevention",
+    "run_under_specified_ac_checks",
+    "run_harness_drift_lock",
+    "run_protected_baseline_guard",
+    "validate_scope_conflicts",
+    "recompute_every_ac",
+    "recompute_every_pi",
+    "recompute_acceptance_target_status",
+    "recompute_product_goal_complete",
+    "regenerate_derived",
+    "append_final_gate_event"
+];
+export async function evaluateTrustedEvidenceKernel(workdir, providedState) {
+    const state = providedState ?? (await loadSuperpowersState(workdir));
+    const errors = [];
+    const acStatuses = {};
+    const acFindings = {};
+    const staleEvidenceIds = new Set();
+    const invalidatedEvidenceIds = new Set();
+    const attempt = currentAttempt(state);
+    const currentSources = await sourceRecords(workdir);
+    if (!attempt) {
+        errors.push("missing current attempt: final-gate requires current_attempt_id with ExecutionAttempt");
+    }
+    else {
+        validateAttemptAgainstSources(state, attempt, currentSources, errors);
+    }
+    const expectedSpecs = deriveRequiredCommandSpecs(state);
+    const commandCorrelation = validateRequiredCommandCorrelation(state, attempt, expectedSpecs);
+    errors.push(...commandCorrelation.errors);
+    commandCorrelation.invalidated_evidence_ids.forEach((id) => invalidatedEvidenceIds.add(id));
+    const underSpecified = new Map(findUnderSpecifiedAcs(state).map((item) => [item.ac_id, item.reasons]));
+    for (const reasons of underSpecified.values()) {
+        errors.push(...reasons);
+    }
+    const contradictionScan = await scanSuperpowersContradictions(workdir, state);
+    errors.push(...contradictionScan.errors);
+    const drift = detectHarnessDrift(state);
+    errors.push(...drift.errors);
+    const baseline = evaluateProtectedBaseline(state);
+    errors.push(...baseline.errors);
+    validateScopeConflicts(state, errors);
+    const unregistered = await scanUnregisteredAssertionEvidence(workdir, state);
+    errors.push(...unregistered.errors);
+    const evidenceById = new Map((state.evidence ?? []).map((evidence) => [evidence.evidence_id, evidence]));
+    for (const [acId, ac] of Object.entries(state.graph?.acceptance_criteria ?? {})) {
+        const acErrors = [];
+        if (underSpecified.has(acId)) {
+            acStatuses[acId] = "under_specified";
+            acFindings[acId] = underSpecified.get(acId) ?? [];
+            continue;
+        }
+        const requiredLayers = ac.required_proof_layers ?? [];
+        const spec = specForAc(state, expectedSpecs, acId);
+        if ((ac.machine_blocking === true || ac.assertion_result_required === true) && !spec) {
+            acErrors.push(`${acId} missing required_command_spec`);
+        }
+        if (spec) {
+            acErrors.push(...validateCommandRunsForSpec(state, attempt, spec));
+        }
+        for (const layerName of requiredLayers) {
+            const layerId = `${acId}.${layerName}`;
+            const layer = state.graph.proof_layers?.[layerId];
+            if (!layer || layer.status !== "satisfied") {
+                acErrors.push(`${layerId} missing current satisfied proof layer`);
+                continue;
+            }
+            if (isMachineVerifiableLayer(layerId)) {
+                const evaluation = evaluateProofLayerAssertions(state, layerId);
+                acErrors.push(...evaluation.blocking_assertion_failures, ...evaluation.negative_evidence_findings);
+                for (const evidenceId of layer.evidence_ids ?? []) {
+                    const evidence = evidenceById.get(evidenceId);
+                    if (!evidence) {
+                        acErrors.push(`${layerId} references unregistered evidence ${evidenceId}`);
+                        continue;
+                    }
+                    acErrors.push(...validateEvidenceAgainstSpec(state, evidence, spec, layerId));
+                    acErrors.push(...(await evaluateCurrentAttemptArtifact(workdir, evidence, layerId)));
+                    if (invalidatedEvidenceIds.has(evidence.evidence_id)) {
+                        acErrors.push(`${layerId} evidence ${evidence.evidence_id} invalidated by newer failed command`);
+                    }
+                    if (isStaleEvidenceError(acErrors)) {
+                        staleEvidenceIds.add(evidence.evidence_id);
+                    }
+                }
+            }
+        }
+        errors.push(...acErrors);
+        acStatuses[acId] = statusForAcErrors(acErrors, requiredLayers.length);
+        acFindings[acId] = acErrors;
+    }
+    const ac010 = evaluateAc010Bootstrap(state, acStatuses);
+    for (const acId of ac010.invalidated_ac_ids) {
+        acStatuses[acId] = "invalidated";
+    }
+    errors.push(...ac010.errors);
+    const piStatuses = recomputePlanStatuses(state, acStatuses);
+    const piFindings = planFindings(state, acStatuses, piStatuses);
+    const allAcsComplete = Object.keys(state.graph?.acceptance_criteria ?? {}).length > 0 &&
+        Object.values(acStatuses).every((status) => status === "complete" || status === "out_of_scope_NA");
+    const allPisComplete = Object.keys(state.graph?.plan_items ?? {}).length > 0 &&
+        Object.values(piStatuses).every((status) => status === "complete" || status === "out_of_scope_NA");
+    const uniqueErrors = unique(errors);
+    const productComplete = uniqueErrors.length === 0 && allAcsComplete && allPisComplete && drift.product_goal_complete !== false && baseline.product_goal_complete !== false;
+    return {
+        product_goal_complete: productComplete,
+        acceptance_target_status: productComplete ? "complete" : statusForGlobalErrors(uniqueErrors, acStatuses),
+        errors: uniqueErrors,
+        ac_statuses: acStatuses,
+        pi_statuses: piStatuses,
+        stale_evidence_ids: [...staleEvidenceIds],
+        ignored_unregistered_evidence: unregistered.ignored,
+        invalidated_evidence_ids: [...invalidatedEvidenceIds],
+        kernel_order: [...TRUSTED_EVIDENCE_KERNEL_ORDER],
+        ac_findings: acFindings,
+        pi_findings: piFindings,
+        harness_task_final_verdict: drift.harness_task_final_verdict
+    };
+}
+export function applyTrustedEvidenceKernelResult(state, result) {
+    for (const [acId, status] of Object.entries(result.ac_statuses)) {
+        const ac = state.graph.acceptance_criteria[acId];
+        if (ac) {
+            ac.status = status;
+        }
+    }
+    for (const [piId, status] of Object.entries(result.pi_statuses)) {
+        const pi = state.graph.plan_items[piId];
+        if (pi) {
+            pi.status = status;
+        }
+    }
+    state.final.product_goal_complete = result.product_goal_complete;
+    state.meta.product_goal_complete = result.product_goal_complete;
+    state.final.acceptance_target_status = result.acceptance_target_status;
+    state.meta.acceptance_target_status = result.acceptance_target_status;
+    state.final.audit_task_complete = true;
+    state.meta.audit_task_complete = true;
+    state.final.completion_basis = result.product_goal_complete
+        ? ["trusted_evidence_kernel", "current_attempt_evidence", "negative_evidence_scan_passed", "harness_drift_lock_passed"]
+        : [];
+    state.final.next_required_actions = result.product_goal_complete ? [] : result.errors.slice(0, 12);
+    state.gates.final_gate = {
+        status: result.product_goal_complete ? "pass" : result.acceptance_target_status,
+        kernel: "trusted_evidence_kernel",
+        order: result.kernel_order,
+        errors: result.errors,
+        stale_evidence_ids: result.stale_evidence_ids,
+        ignored_unregistered_evidence: result.ignored_unregistered_evidence,
+        invalidated_evidence_ids: result.invalidated_evidence_ids,
+        ac_findings: result.ac_findings,
+        pi_findings: result.pi_findings,
+        harness_task_final_verdict: result.harness_task_final_verdict,
+        next_required_actions: state.final.next_required_actions
+    };
+}
+function validateAttemptAgainstSources(state, attempt, currentSources, errors) {
+    const productHash = currentSources.product_architecture_source?.sha256 ?? "";
+    const planHash = currentSources.technical_realization_plan?.sha256 ?? "";
+    const checklistHash = currentSources.acceptance_checklist?.sha256 ?? "";
+    for (const [key, source] of Object.entries(currentSources)) {
+        const expected = state.sources[key]?.sha256;
+        if (expected && source.sha256 !== expected) {
+            errors.push(`source hash mismatch for ${key}: expected ${expected}, actual ${source.sha256}; recompile graph before final-gate`);
+        }
+    }
+    if (attempt.product_source_hash !== productHash) {
+        errors.push("source hash mismatch: current attempt product_source_hash does not match product-architecture-source.md");
+    }
+    if (attempt.technical_plan_hash !== planHash) {
+        errors.push("source hash mismatch: current attempt technical_plan_hash does not match technical-realization-plan.md");
+    }
+    if (attempt.acceptance_checklist_hash !== checklistHash) {
+        errors.push("source hash mismatch: current attempt acceptance_checklist_hash does not match acceptance-checklist.md");
+    }
+    for (const field of [
+        "task_attempt_id",
+        "source_bundle_hash",
+        "product_source_hash",
+        "technical_plan_hash",
+        "acceptance_checklist_hash",
+        "git_head",
+        "git_status_short",
+        "tracked_diff_hash",
+        "relevant_untracked_hash",
+        "worktree_fingerprint",
+        "started_at",
+        "required_command_specs_hash",
+        "mode"
+    ]) {
+        if (!attempt[field]) {
+            errors.push(`current attempt missing required field ${field}`);
+        }
+    }
+}
+function validateEvidenceAgainstSpec(state, evidence, spec, layerId) {
+    if (!spec) {
+        return [];
+    }
+    const errors = [];
+    const assertion = evidence.assertion_result;
+    const label = `proof layer ${layerId} evidence ${evidence.evidence_id}`;
+    const expectedPiIds = state.graph.acceptance_criteria[spec.ac_id]?.related_plan_items ?? [];
+    const targetPiIds = evidence.target_pi_ids ?? assertion?.target_pi_ids ?? [];
+    for (const piId of expectedPiIds) {
+        if (!targetPiIds.includes(piId)) {
+            errors.push(`${label} target_pi_ids ${targetPiIds.join(", ") || "(none)"} do not include ${piId}`);
+        }
+    }
+    if (assertion) {
+        const assertionIds = new Set(assertion.positive_assertions.map((item) => item.id));
+        for (const id of spec.positive_assertions ?? []) {
+            if (!assertionIds.has(id)) {
+                errors.push(`${label} missing positive assertion ${id}`);
+            }
+        }
+        const negativeIds = new Set(assertion.negative_assertions.map((item) => item.id));
+        for (const id of spec.negative_assertions ?? []) {
+            if (!negativeIds.has(id)) {
+                errors.push(`${label} missing negative assertion ${id}`);
+            }
+        }
+        const requiredTests = new Set(assertion.required_test_ids ?? []);
+        for (const testId of spec.required_test_ids ?? []) {
+            if (!requiredTests.has(testId)) {
+                errors.push(`${label} assertion_result.required_test_ids missing ${testId}`);
+            }
+        }
+        const invalidChecks = [
+            ...((assertion.invalid_completion_signals ?? []).map((item) => `${item.id} ${item.forbidden_text ?? ""}`)),
+            ...((assertion.negative_evidence_scan?.invalid_completion_signals_checked ?? []).map((item) => String(item)))
+        ].join("\n");
+        for (const signal of spec.invalid_completion_signals ?? []) {
+            if (!invalidChecks.includes(signal)) {
+                errors.push(`${label} invalid_completion_signals did not check ${signal}`);
+            }
+        }
+    }
+    return errors;
+}
+function specForAc(state, expectedSpecs, acId) {
+    const actual = (state.required_command_specs ?? []).find((spec) => spec.ac_id === acId);
+    if (actual) {
+        return actual;
+    }
+    return expectedSpecs.find((spec) => spec.ac_id === acId);
+}
+function statusForAcErrors(errors, requiredLayerCount) {
+    if (requiredLayerCount === 0) {
+        return "not_run";
+    }
+    const text = errors.join("\n");
+    if (!text) {
+        return "complete";
+    }
+    if (/under_specified/i.test(text)) {
+        return "under_specified";
+    }
+    if (/stale|failed|invalid|contradiction|negative evidence|forbidden|bootstrap/i.test(text)) {
+        return "invalidated";
+    }
+    if (/blocked|harness_drift|protected_baseline|source hash mismatch/i.test(text)) {
+        return "blocked";
+    }
+    return "partial";
+}
+function recomputePlanStatuses(state, acStatuses) {
+    const statuses = {};
+    for (const [planId, item] of Object.entries(state.graph?.plan_items ?? {})) {
+        const relatedStatuses = (item.related_acs ?? []).map((acId) => acStatuses[acId] ?? state.graph.acceptance_criteria[acId]?.status ?? "not_run");
+        if (relatedStatuses.length > 0 && relatedStatuses.every((status) => status === "complete" || status === "out_of_scope_NA")) {
+            statuses[planId] = "complete";
+        }
+        else if (relatedStatuses.some((status) => status === "under_specified" || status === "blocked")) {
+            statuses[planId] = "blocked";
+        }
+        else if (relatedStatuses.some((status) => status === "invalidated")) {
+            statuses[planId] = "invalidated";
+        }
+        else if (relatedStatuses.some((status) => status === "partial")) {
+            statuses[planId] = "partial";
+        }
+        else {
+            statuses[planId] = "not_started";
+        }
+    }
+    return statuses;
+}
+function planFindings(state, acStatuses, piStatuses) {
+    const findings = {};
+    for (const [planId, item] of Object.entries(state.graph?.plan_items ?? {})) {
+        const related = item.related_acs ?? [];
+        findings[planId] = related
+            .filter((acId) => acStatuses[acId] && acStatuses[acId] !== "complete" && acStatuses[acId] !== "out_of_scope_NA")
+            .map((acId) => `${acId} status=${acStatuses[acId]}`)
+            .concat(piStatuses[planId] ? [`${planId} status=${piStatuses[planId]}`] : []);
+    }
+    return findings;
+}
+function statusForGlobalErrors(errors, acStatuses) {
+    const text = errors.join("\n");
+    if (Object.values(acStatuses).includes("under_specified") || /under_specified/i.test(text)) {
+        return "under_specified";
+    }
+    if (/harness_drift|protected_baseline|source hash mismatch|missing current attempt|required_command_specs_hash|harness_task_missing|scope_conflict_requires_decision/i.test(text)) {
+        return "blocked";
+    }
+    if (/stale|failed|invalid|contradiction|negative evidence|forbidden|bootstrap/i.test(text)) {
+        return "invalidated";
+    }
+    return "partial";
+}
+function currentAttempt(state) {
+    if (!state.current_attempt_id) {
+        return undefined;
+    }
+    return (state.attempts ?? []).find((item) => item.task_attempt_id === state.current_attempt_id);
+}
+function isStaleEvidenceError(errors) {
+    return errors.some((error) => /stale evidence|source_bundle_hash mismatch|artifact_sha256 mismatch|artifact_mtime/i.test(error));
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}

package/dist/lib/superpowers-task-evidence-records.d.ts

@@ -0,0 +1,2 @@
+import { type SuperpowersEvidenceRecord } from "./superpowers-task-state-schema.js";
+export declare function readEvidenceRecords(value: unknown): SuperpowersEvidenceRecord[];

package/dist/lib/superpowers-task-evidence-records.js

@@ -0,0 +1,55 @@
+import { normalizeAssertionResult, normalizeNegativeEvidenceScan } from "./superpowers-task-assertion-normalizers.js";
+import { normalizeProofLayerId } from "./superpowers-task-fields.js";
+import { asStringArray, isRecord } from "./superpowers-task-state-schema.js";
+export function readEvidenceRecords(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isRecord).map((item) => ({
+        evidence_id: String(item.evidence_id ?? item.evidenceId ?? ""),
+        schema_version: item.schema_version === undefined ? undefined : String(item.schema_version),
+        task_attempt_id: item.task_attempt_id === undefined ? undefined : String(item.task_attempt_id),
+        source_bundle_hash: item.source_bundle_hash === undefined ? undefined : String(item.source_bundle_hash),
+        product_source_hash: item.product_source_hash === undefined ? undefined : String(item.product_source_hash),
+        technical_plan_hash: item.technical_plan_hash === undefined ? undefined : String(item.technical_plan_hash),
+        acceptance_checklist_hash: item.acceptance_checklist_hash === undefined ? undefined : String(item.acceptance_checklist_hash),
+        git_head: item.git_head === undefined ? undefined : String(item.git_head),
+        worktree_fingerprint: item.worktree_fingerprint === undefined ? undefined : String(item.worktree_fingerprint),
+        command_spec_id: item.command_spec_id === undefined ? undefined : String(item.command_spec_id),
+        command_run_id: item.command_run_id === undefined ? undefined : String(item.command_run_id),
+        command_line: item.command_line === undefined ? undefined : String(item.command_line),
+        artifact_path: item.artifact_path === undefined ? undefined : String(item.artifact_path),
+        artifact_sha256: item.artifact_sha256 === undefined ? undefined : String(item.artifact_sha256),
+        artifact_mtime: item.artifact_mtime === undefined ? undefined : String(item.artifact_mtime),
+        target_ac_ids: asStringArray(item.target_ac_ids),
+        target_pi_ids: asStringArray(item.target_pi_ids),
+        target_proof_layers: asStringArray(item.target_proof_layers).map(normalizeProofLayerId),
+        slice_id: String(item.slice_id ?? item.sliceId ?? ""),
+        type: String(item.type ?? ""),
+        freshness: isRecord(item.freshness)
+            ? {
+                created_at: String(item.freshness.created_at ?? ""),
+                valid_for: String(item.freshness.valid_for ?? ""),
+                stale_after: item.freshness.stale_after === null ? null : item.freshness.stale_after === undefined ? null : String(item.freshness.stale_after)
+            }
+            : { created_at: "", valid_for: "", stale_after: null },
+        command: item.command === undefined ? undefined : String(item.command),
+        command_exit_code: item.command_exit_code === undefined ? undefined : Number(item.command_exit_code),
+        artifact_paths: asStringArray(item.artifact_paths),
+        proves: asStringArray(item.proves).map(normalizeProofLayerId),
+        does_not_prove: asStringArray(item.does_not_prove).map((claim) => (claim.includes(".") ? normalizeProofLayerId(claim) : claim)),
+        redaction: isRecord(item.redaction)
+            ? { checked: item.redaction.checked === true, contains_secret: item.redaction.contains_secret === true }
+            : { checked: false, contains_secret: false },
+        reviewability: isRecord(item.reviewability)
+            ? {
+                external_reviewer_can_reproduce: item.reviewability.external_reviewer_can_reproduce === true,
+                reproduction_steps: String(item.reviewability.reproduction_steps ?? "")
+            }
+            : { external_reviewer_can_reproduce: false, reproduction_steps: "" },
+        assertion_result: normalizeAssertionResult(item.assertion_result),
+        negative_evidence_scan: normalizeNegativeEvidenceScan(item.negative_evidence_scan),
+        sibling_substitution_used: item.sibling_substitution_used === true,
+        sibling_substitution_approval_source: item.sibling_substitution_approval_source === undefined ? undefined : String(item.sibling_substitution_approval_source)
+    }));
+}

package/dist/lib/superpowers-task-evidence.d.ts

@@ -0,0 +1,10 @@
+import { type CommandRunRecord, type SuperpowersEvidenceRecord } from "./superpowers-task-state-schema.js";
+export declare function runSuperpowersAssertion(workdir: string, options: {
+    acId: string;
+    proofLayer: string;
+    commandArgs: string[];
+}): Promise<CommandRunRecord>;
+export declare function recordSuperpowersEvidence(workdir: string, options: {
+    artifactPath: string;
+    commandRunId: string;
+}): Promise<SuperpowersEvidenceRecord>;

package/dist/lib/superpowers-task-evidence.js

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathExists, readText } from "./fs.js";
+import { appendSuperpowersEvent } from "./superpowers-task-events.js";
+import { computeSourceBundleHash } from "./superpowers-task-attempt.js";
+import { normalizeAssertionResult, normalizeNegativeEvidenceScan } from "./superpowers-task-assertions.js";
+import { normalizeProofLayerId, normalizeProofLayerName } from "./superpowers-task-fields.js";
+import { loadSuperpowersState, saveSuperpowersState, sha256 } from "./superpowers-task-state.js";
+import { asStringArray, isRecord } from "./superpowers-task-state-schema.js";
+export async function runSuperpowersAssertion(workdir, options) {
+    if (!options.acId || !options.proofLayer) {
+        throw new Error("run-assertion requires --ac <AC-ID> and --proof-layer <layer>");
+    }
+    if (options.commandArgs.length === 0) {
+        throw new Error("run-assertion requires a command after --");
+    }
+    const state = await loadSuperpowersState(workdir);
+    const proofLayer = normalizeProofLayerName(options.proofLayer);
+    const spec = (state.required_command_specs ?? []).find((item) => item.ac_id === options.acId && item.proof_layers.map(normalizeProofLayerName).includes(proofLayer));
+    if (!spec) {
+        throw new Error(`no required command spec for ${options.acId}.${proofLayer}`);
+    }
+    const startedAt = new Date().toISOString();
+    const exitCode = await runCommand(options.commandArgs);
+    const endedAt = new Date().toISOString();
+    const commandLine = options.commandArgs.join(" ");
+    const commandRun = {
+        command_run_id: `CR-${compactDate(startedAt)}-${sha256(commandLine).slice(0, 8)}`,
+        task_attempt_id: state.current_attempt_id,
+        command_spec_id: spec.command_spec_id,
+        ac_id: options.acId,
+        proof_layer: proofLayer,
+        command_line: commandLine,
+        exit_code: exitCode,
+        started_at: startedAt,
+        completed_at: endedAt,
+        ended_at: endedAt,
+        artifact_paths: []
+    };
+    state.command_runs = [...(state.command_runs ?? []), commandRun];
+    await saveSuperpowersState(workdir, state);
+    await appendSuperpowersEvent(workdir, "assertion_command_run", {
+        command_run_id: commandRun.command_run_id,
+        command_spec_id: commandRun.command_spec_id,
+        exit_code: commandRun.exit_code
+    });
+    return commandRun;
+}
+export async function recordSuperpowersEvidence(workdir, options) {
+    const state = await loadSuperpowersState(workdir);
+    const commandRun = (state.command_runs ?? []).find((item) => item.command_run_id === options.commandRunId);
+    if (!commandRun) {
+        throw new Error(`command run not found: ${options.commandRunId}`);
+    }
+    const artifactPath = path.resolve(options.artifactPath);
+    if (!(await pathExists(artifactPath))) {
+        throw new Error(`evidence artifact not found: ${options.artifactPath}`);
+    }
+    const artifactText = await readText(artifactPath);
+    const artifact = JSON.parse(artifactText);
+    const artifactRecord = isRecord(artifact) ? artifact : {};
+    const assertion = normalizeAssertionResult(artifactRecord.assertion_result ?? artifactRecord);
+    if (!assertion) {
+        throw new Error(`evidence artifact is missing assertion_result: ${options.artifactPath}`);
+    }
+    const stats = await fs.stat(artifactPath);
+    const attempt = (state.attempts ?? []).find((item) => item.task_attempt_id === commandRun.task_attempt_id);
+    const commandSpec = (state.required_command_specs ?? []).find((item) => item.command_spec_id === commandRun.command_spec_id);
+    const layerId = normalizeProofLayerId(`${commandRun.ac_id}.${commandRun.proof_layer}`);
+    const relativeArtifactPath = slash(path.relative(workdir, artifactPath));
+    const targetPiIds = commandSpec ? (state.graph.acceptance_criteria[commandSpec.ac_id]?.related_plan_items ?? []) : [];
+    const negativeScan = normalizeNegativeEvidenceScan(artifactRecord.negative_evidence_scan);
+    if (assertion.schema_version === "assertion-result-v2") {
+        assertion.target_pi_ids = assertion.target_pi_ids ?? targetPiIds;
+        assertion.invalid_completion_signals = assertion.invalid_completion_signals ?? [];
+        assertion.required_test_ids = assertion.required_test_ids ?? commandSpec?.required_test_ids ?? [];
+        assertion.negative_evidence_scan = assertion.negative_evidence_scan ?? negativeScan;
+    }
+    const evidence = {
+        schema_version: "evidence-record-v2",
+        evidence_id: `EV2-${compactDate(new Date().toISOString())}-${sha256(options.commandRunId + artifactText).slice(0, 8)}`,
+        task_attempt_id: commandRun.task_attempt_id,
+        generated_at: new Date().toISOString(),
+        source_bundle_hash: attempt?.source_bundle_hash ?? computeSourceBundleHash(state),
+        product_source_hash: attempt?.product_source_hash ?? state.sources.product_architecture_source?.sha256 ?? "",
+        technical_plan_hash: attempt?.technical_plan_hash ?? state.sources.technical_realization_plan?.sha256 ?? "",
+        acceptance_checklist_hash: attempt?.acceptance_checklist_hash ?? state.sources.acceptance_checklist?.sha256 ?? "",
+        git_head: attempt?.git_head ?? "",
+        git_status_short: attempt?.git_status_short ?? "",
+        tracked_diff_hash: attempt?.tracked_diff_hash ?? "",
+        relevant_untracked_hash: attempt?.relevant_untracked_hash ?? "",
+        covers_dirty_worktree: Boolean(attempt?.git_status_short?.trim()),
+        worktree_fingerprint: attempt?.worktree_fingerprint ?? "",
+        command_spec_id: commandRun.command_spec_id,
+        command_run_id: commandRun.command_run_id,
+        command_line: commandRun.command_line,
+        command_exit_code: commandRun.exit_code,
+        artifact_path: relativeArtifactPath,
+        artifact_sha256: createHash("sha256").update(artifactText).digest("hex"),
+        artifact_mtime: stats.mtime.toISOString(),
+        target_ac_ids: [commandRun.ac_id],
+        target_pi_ids: targetPiIds,
+        target_proof_layers: [layerId],
+        slice_id: String(artifactRecord.slice_id ?? "attempt-evidence"),
+        type: String(artifactRecord.type ?? `${commandRun.proof_layer}_assertion`),
+        freshness: { created_at: commandRun.completed_at ?? commandRun.ended_at, valid_for: "current_attempt", stale_after: null },
+        command: commandRun.command_line,
+        artifact_paths: [relativeArtifactPath],
+        proves: [layerId],
+        does_not_prove: asStringArray(artifactRecord.does_not_prove).length > 0 ? asStringArray(artifactRecord.does_not_prove) : ["unrelated proof layer"],
+        redaction: isRecord(artifactRecord.redaction)
+            ? { checked: artifactRecord.redaction.checked === true, contains_secret: artifactRecord.redaction.contains_secret === true }
+            : { checked: true, contains_secret: false },
+        reviewability: isRecord(artifactRecord.reviewability)
+            ? {
+                external_reviewer_can_reproduce: artifactRecord.reviewability.external_reviewer_can_reproduce === true,
+                reproduction_steps: String(artifactRecord.reviewability.reproduction_steps ?? commandRun.command_line)
+            }
+            : { external_reviewer_can_reproduce: true, reproduction_steps: commandRun.command_line },
+        assertion_result: assertion,
+        negative_evidence_scan: negativeScan
+    };
+    state.evidence = [...(state.evidence ?? []), evidence];
+    const proofLayer = state.graph.proof_layers[layerId];
+    if (proofLayer && commandRun.exit_code === 0 && assertion.status === "passed") {
+        proofLayer.status = "satisfied";
+        proofLayer.evidence_ids = [...new Set([...(proofLayer.evidence_ids ?? []), evidence.evidence_id])];
+    }
+    await saveSuperpowersState(workdir, state);
+    await appendSuperpowersEvent(workdir, "evidence_recorded", { evidence_id: evidence.evidence_id, command_run_id: commandRun.command_run_id });
+    return evidence;
+}
+function runCommand(args) {
+    return new Promise((resolve) => {
+        const child = spawn(args[0], args.slice(1), { cwd: process.cwd(), stdio: "ignore", windowsHide: true });
+        child.on("error", () => resolve(1));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+function compactDate(value) {
+    return value.replace(/[-:.TZ]/g, "").slice(0, 17);
+}
+function slash(value) {
+    return value.split(path.sep).join("/");
+}

package/dist/lib/superpowers-task-final-card.d.ts

@@ -0,0 +1,3 @@
+import { type CompletionOutputContract } from "./superpowers-task-completion-output.js";
+import { type SuperpowersTaskState } from "./superpowers-task-state-schema.js";
+export declare function renderFinalCard(contract: CompletionOutputContract, state: SuperpowersTaskState): string;

package/dist/lib/superpowers-task-final-card.js

@@ -0,0 +1,24 @@
+export function renderFinalCard(contract, state) {
+    const reasons = contract.completion_output_status === "blocked" ? contract.blocked_reasons : contract.rejection_reasons;
+    const reasonBlock = reasons.length > 0 ? reasons.map((reason) => `- ${reason}`).join("\n") : "- none";
+    const gate = contract.completion_output_status === "accept" ? "Final answer: accept" : `Final answer: ${contract.completion_output_status}`;
+    const auditLine = contract.completion_output_status === "accept"
+        ? "Final-gate accepted the current attempt."
+        : "Audit workflow completed; acceptance target not complete.";
+    return `# Final Card
+
+completion_output_status: ${contract.completion_output_status}
+${gate}
+required_user_visible_status: ${contract.required_user_visible_status}
+final_answer_allowed: ${contract.final_answer_allowed}
+exit_code: ${contract.exit_code}
+product_goal_complete: ${contract.product_goal_complete}
+acceptance_target_status: ${contract.acceptance_target_status}
+audit_task_complete: ${state.final.audit_task_complete}
+
+${auditLine}
+
+Reasons:
+${reasonBlock}
+`;
+}

package/dist/lib/superpowers-task-gates.d.ts

@@ -1,3 +1,4 @@
+import { type CompletionOutputContract } from "./superpowers-task-completion-output.js";
 export declare function runSliceGate(workdir: string, sliceId: string): Promise<{
     passed: boolean;
     messages: string[];
@@ -6,7 +7,6 @@ export declare function runEpochGate(workdir: string, epochId: string): Promise<
     passed: boolean;
     messages: string[];
 }>;
-export declare function runFinalGate(workdir: string): Promise<{
-    product_goal_complete: boolean;
+export declare function runFinalGate(workdir: string): Promise<CompletionOutputContract & {
     errors: string[];
 }>;