@enwithai/product-check 0.2.0 → 0.3.0

package/dist/assurance/verification.d.ts

@@ -0,0 +1,30 @@
+import type { Finding, Results, Severity } from "../types.js";
+import { type RuleHit } from "./lanes.js";
+import type { DiffFile } from "./diff.js";
+import type { FindingVerification, VerificationCheck, VerificationState } from "./types.js";
+/** Rules evaluated over a whole changed file (re-checked with the file rules, not line by line). */
+export declare const FILE_RULES: Set<string>;
+/** True when a verified finding of this severity may block. P0 also blocks unverified under a fail-closed policy. */
+export declare function isBlocking(severity: Severity, state: VerificationState, failClosedP0: boolean): boolean;
+/** Re-checks a review hit against the file as it is at the head commit. */
+export declare function recheckHit(hit: RuleHit, headText: string | null, diffFile: DiffFile | undefined): VerificationCheck;
+/** Verifies a hit given the recheck and the other hits/claims of the same review. */
+export declare function verifyHit(hit: RuleHit, recheck: VerificationCheck, others: {
+    path: string;
+    line: number | null;
+    source: string;
+}[]): FindingVerification;
+/** An external reviewer's claim (for example an AI code reviewer's comment). */
+export interface ReviewerClaim {
+    reviewer: string;
+    type: "ai" | "human" | "imported";
+    path: string;
+    line: number | null;
+    title: string;
+    severity: Severity;
+    body: string;
+}
+/** Verifies an external claim: it can be disproven by the code, corroborated by a deterministic hit, or triaged. */
+export declare function verifyClaim(claim: ReviewerClaim, headText: string | null, hits: RuleHit[]): FindingVerification;
+/** Verifies a finding from a Product Check results document (baseline whole-product scan). */
+export declare function verifyResultsFinding(f: Finding, results: Results, repo: string | null): FindingVerification;

package/dist/assurance/verification.js

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 EnWithAI Technologies
+/**
+ * Independent verification of alleged findings before they may influence a block decision.
+ *
+ * Checks (each recorded with its result):
+ *  - evidence-present     the finding links evidence that exists;
+ *  - independent-reread   the cited file is read again at the exact commit and the observation still holds
+ *                         (a different code path from the reviewer that raised it);
+ *  - runtime-observation  the evidence is a runtime response or an executed test;
+ *  - second-signal        another independent reviewer/lane points at the same place.
+ *
+ * States: fact + reread/runtime → CONFIRMED; inference + reread → CORROBORATED (CONFIRMED with a second signal);
+ * hypothesis → NEEDS_HUMAN_TRIAGE unless a second signal → CORROBORATED; reread contradicts → DISPROVEN; nothing
+ * re-checkable → EVIDENCE_COLLECTED; no evidence at all → SUSPECTED. Speculative or unverified reviewer claims are
+ * never treated as proven defects.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { sha256 } from "../util/hash.js";
+import { fileHits, lineHits } from "./lanes.js";
+/** Rules evaluated over a whole changed file (re-checked with the file rules, not line by line). */
+export const FILE_RULES = new Set([
+    "VC-TR-AUTHZ-REMOVED",
+    "VC-TR-OBJECT-AUTHZ",
+    "VC-OP-MIGRATION-NO-DOWN",
+    "VC-CR-MOCK-ONLY-TEST",
+    "VC-CR-NO-TESTS",
+]);
+const BLOCKING_STATES = ["CONFIRMED", "CORROBORATED", "REPRODUCED"];
+/** True when a verified finding of this severity may block. P0 also blocks unverified under a fail-closed policy. */
+export function isBlocking(severity, state, failClosedP0) {
+    if (severity !== "P0" && severity !== "P1")
+        return false;
+    if (BLOCKING_STATES.includes(state))
+        return true;
+    return severity === "P0" && failClosedP0 && state !== "DISPROVEN";
+}
+function decide(epistemic, checks) {
+    const r = (name) => checks.find((c) => c.check === name)?.result;
+    if (r("evidence-present") === "fail")
+        return "SUSPECTED";
+    if (r("independent-reread") === "fail")
+        return "DISPROVEN";
+    const reread = r("independent-reread") === "pass";
+    const runtime = r("runtime-observation") === "pass";
+    const second = r("second-signal") === "pass";
+    if (epistemic === "fact")
+        return reread || runtime ? "CONFIRMED" : "EVIDENCE_COLLECTED";
+    if (epistemic === "inference") {
+        if ((reread || runtime) && second)
+            return "CONFIRMED";
+        if (reread || runtime || second)
+            return "CORROBORATED";
+        return "EVIDENCE_COLLECTED";
+    }
+    return second || runtime ? "CORROBORATED" : "NEEDS_HUMAN_TRIAGE";
+}
+/** Re-checks a review hit against the file as it is at the head commit. */
+export function recheckHit(hit, headText, diffFile) {
+    if (hit.rule_id === "VC-CR-NO-TESTS")
+        return {
+            check: "independent-reread",
+            result: "not-run",
+            detail: "Change-level inference; no single file to re-read.",
+        };
+    if (headText === null)
+        return {
+            check: "independent-reread",
+            result: "not-run",
+            detail: "Head content unavailable (diff supplied as a file or file deleted).",
+        };
+    if (hit.rule_id === "VC-TR-AUTHZ-REMOVED") {
+        const still = headText.includes(hit.excerpt);
+        return still
+            ? {
+                check: "independent-reread",
+                result: "fail",
+                detail: "The removed auth line is still present at head (moved, not removed).",
+            }
+            : { check: "independent-reread", result: "pass", detail: "Re-read at head: the auth check is absent." };
+    }
+    const again = FILE_RULES.has(hit.rule_id) && diffFile
+        ? fileHits(diffFile, headText).filter((h) => h.rule_id === hit.rule_id)
+        : lineHits(hit.path, headText.split("\n").map((text, i) => ({ line: i + 1, text }))).filter((h) => h.rule_id === hit.rule_id && h.signature === hit.signature);
+    return again.length > 0
+        ? {
+            check: "independent-reread",
+            result: "pass",
+            detail: `Re-read ${hit.path} at head: the condition holds${hit.line !== null ? ` (line ${again.map((h) => h.line).join(", ")})` : ""}.`,
+        }
+        : {
+            check: "independent-reread",
+            result: "fail",
+            detail: `Re-read ${hit.path} at head: the condition does not hold.`,
+        };
+}
+/** Verifies a hit given the recheck and the other hits/claims of the same review. */
+export function verifyHit(hit, recheck, others) {
+    const near = others.filter((o) => o.path === hit.path && (hit.line === null || o.line === null || Math.abs(o.line - hit.line) <= 5));
+    const checks = [
+        { check: "evidence-present", result: "pass", detail: "Diff line(s) recorded as evidence." },
+        recheck,
+        near.length > 0
+            ? {
+                check: "second-signal",
+                result: "pass",
+                detail: `Also raised by: ${[...new Set(near.map((n) => n.source))].join(", ")}.`,
+            }
+            : { check: "second-signal", result: "not-run", detail: "No other reviewer points at this location." },
+    ];
+    return { state: decide(hit.epistemic, checks), checks };
+}
+/** Verifies an external claim: it can be disproven by the code, corroborated by a deterministic hit, or triaged. */
+export function verifyClaim(claim, headText, hits) {
+    const checks = [];
+    if (headText === null) {
+        checks.push({
+            check: "independent-reread",
+            result: "fail",
+            detail: `${claim.path} does not exist at head.`,
+        });
+        return { state: "DISPROVEN", checks };
+    }
+    const lines = headText.split("\n").length;
+    if (claim.line !== null && (claim.line < 1 || claim.line > lines)) {
+        checks.push({
+            check: "independent-reread",
+            result: "fail",
+            detail: `${claim.path} has ${lines} lines; line ${claim.line} does not exist.`,
+        });
+        return { state: "DISPROVEN", checks };
+    }
+    checks.push({
+        check: "independent-reread",
+        result: "pass",
+        detail: "The cited location exists at head; the claim itself is not machine-checked.",
+    });
+    const near = hits.filter((h) => h.path === claim.path && (claim.line === null || h.line === null || Math.abs(h.line - claim.line) <= 5));
+    checks.push(near.length > 0
+        ? {
+            check: "second-signal",
+            result: "pass",
+            detail: `Deterministic rule(s) agree: ${near.map((h) => h.rule_id).join(", ")}.`,
+        }
+        : { check: "second-signal", result: "not-run", detail: "No deterministic rule corroborates the claim." });
+    return { state: near.length > 0 ? "CORROBORATED" : "NEEDS_HUMAN_TRIAGE", checks };
+}
+/** Candidate absolute paths for an evidence locator. */
+function locate(locator, repo, repoLabel) {
+    const root = resolve(repo);
+    const cands = isAbsolute(locator)
+        ? [locator]
+        : [
+            resolve(root, locator),
+            ...(repoLabel && locator.startsWith(`${repoLabel}/`)
+                ? [resolve(root, locator.slice(repoLabel.length + 1))]
+                : []),
+        ];
+    return cands.find((c) => c.startsWith(root + sep) && existsSync(c)) ?? null;
+}
+/** Verifies a finding from a Product Check results document (baseline whole-product scan). */
+export function verifyResultsFinding(f, results, repo) {
+    const ev = f.evidence_ids
+        .map((id) => results.evidence.find((e) => e.id === id))
+        .filter((e) => e !== undefined);
+    const checks = [
+        ev.length > 0 && ev.length === f.evidence_ids.length
+            ? { check: "evidence-present", result: "pass", detail: `${ev.length} evidence record(s) linked.` }
+            : { check: "evidence-present", result: "fail", detail: "Linked evidence is missing from the results." },
+    ];
+    const runtime = ev.filter((e) => e.strength === "runtime" || e.strength === "executed-test");
+    checks.push(runtime.length > 0
+        ? {
+            check: "runtime-observation",
+            result: "pass",
+            detail: `Observed at runtime or by an executed test (${runtime.map((e) => e.id).join(", ")}).`,
+        }
+        : { check: "runtime-observation", result: "not-run", detail: "No runtime or executed-test evidence." });
+    const files = ev.filter((e) => e.kind === "source-location" && e.checksum !== null);
+    if (repo === null || files.length === 0) {
+        checks.push({
+            check: "independent-reread",
+            result: "not-run",
+            detail: repo === null
+                ? "Repository not available for a re-read."
+                : "No checksummed source evidence to re-read.",
+        });
+    }
+    else {
+        const label = results.contract.target.repository?.path ?? null;
+        const outcomes = files.map((e) => {
+            const p = locate(e.source.locator, repo, label);
+            if (!p)
+                return "missing";
+            return sha256(readFileSync(p)) === e.checksum?.value ? "match" : "changed";
+        });
+        if (outcomes.every((o) => o === "match"))
+            checks.push({
+                check: "independent-reread",
+                result: "pass",
+                detail: `Re-read ${files.length} cited file(s); checksums match the evidence.`,
+            });
+        else
+            checks.push({
+                check: "independent-reread",
+                result: "not-run",
+                detail: `Cited file(s) ${outcomes.includes("missing") ? "missing" : "changed"} since the scan; re-read is inconclusive (not a disproof).`,
+            });
+    }
+    return { state: decide(f.epistemic, checks), checks };
+}

package/dist/assurance/verify.d.ts

@@ -0,0 +1,26 @@
+import type { Results, ScanContract } from "../types.js";
+import type { ExecPermission } from "../exec/process.js";
+import type { EvidenceLog } from "./evidence-log.js";
+import { type AssurancePolicy, type ClosureRegister, type EnvironmentRecord, type VerificationRun } from "./types.js";
+export interface VerifyInput {
+    register: ClosureRegister;
+    findingIds: string[];
+    repo: string;
+    head: string;
+    clean: boolean | null;
+    baseline: {
+        results: Results;
+        sha256: string;
+    };
+    contract: ScanContract | null;
+    extraTestResults: string[];
+    policy: AssurancePolicy;
+    permission: ExecPermission;
+    env: EnvironmentRecord;
+    log: EvidenceLog;
+    now: () => Date;
+    baseDir: string;
+    writeAfterResults: (verificationId: string, results: Results) => string;
+}
+/** Runs one verification and returns the run (the caller applies it to the register). */
+export declare function verifyFindings(input: VerifyInput): Promise<VerificationRun>;

package/dist/assurance/verify.js

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 EnWithAI Technologies
+/**
+ * Closure verification (VC-P5) against the exact fix commit.
+ *
+ * Targeted reproduction, per finding:
+ *  - baseline-scan findings: Product Check re-assesses the repository at the fix commit (offline; same contract,
+ *    imports cleared unless re-supplied) and the finding's control must no longer produce the finding or any
+ *    finding of equal or higher severity. A control that cannot be evaluated is NOT_TESTED, never PASS.
+ *  - change-review findings: the rule is re-run over the whole file at the fix commit; it must no longer match.
+ *  - the implementer's declared reproduction commands must exit 0.
+ * Regression: the policy's required checks and the regression corpus must pass; the re-assessment must show no new
+ * P0/P1 finding and no regressed control compared with the baseline.
+ *
+ * Preconditions: the repository HEAD is the fix commit, the working tree is clean, and the finding is
+ * RETEST_REQUIRED. Before/after results are retained (the after-results are written next to the register).
+ */
+import { readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { defaultContract } from "../contract/contract.js";
+import { runAssessment } from "../run.js";
+import { sha256 } from "../util/hash.js";
+import { CONTROL_BY_ID } from "../validation/catalog.js";
+import { lineHits } from "./lanes.js";
+import { FILE_RULES } from "./verification.js";
+import { overall, runCommands } from "./proof.js";
+import { ASSURANCE_SCHEMA_VERSION, } from "./types.js";
+import { seqId } from "./util.js";
+const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
+/** Runs one verification and returns the run (the caller applies it to the register). */
+export async function verifyFindings(input) {
+    const reg = input.register;
+    const started = input.now().toISOString();
+    const verificationId = seqId("VR", reg.verification_runs.length + 1);
+    const entries = input.findingIds.map((id) => reg.entries.find((e) => e.finding_id === id));
+    const reasons = [];
+    const limitations = [];
+    const checks = [];
+    const fixIds = [...new Set(entries.map((e) => e?.fix_ids.at(-1) ?? null))];
+    const fix = reg.fixes.find((f) => f.fix_id === fixIds[0]) ?? null;
+    let executions = [];
+    let afterResults = null;
+    const precondition = (msg) => {
+        reasons.push(msg);
+    };
+    if (entries.some((e) => e === undefined))
+        precondition("Unknown finding ID.");
+    else if (entries.some((e) => e?.state !== "RETEST_REQUIRED"))
+        precondition(`Every finding must be RETEST_REQUIRED (got ${entries.map((e) => `${e?.finding_id}=${e?.state}`).join(", ")}).`);
+    if (fixIds.length !== 1 || fix === null)
+        precondition("The findings must share one recorded fix.");
+    else if (fix.change_sha !== input.head)
+        precondition(`HEAD ${input.head.slice(0, 12)} is not the fix commit ${fix.change_sha.slice(0, 12)}; verification must run against the exact fix SHA.`);
+    if (input.clean !== true)
+        precondition(input.clean === false
+            ? "The working tree is not clean; results would not describe the fix commit."
+            : "Could not determine whether the working tree is clean.");
+    const run = () => ({
+        schema_version: ASSURANCE_SCHEMA_VERSION,
+        kind: "verification-run",
+        verification_id: verificationId,
+        purpose: "closure",
+        finding_ids: input.findingIds,
+        fix_id: fix?.fix_id ?? null,
+        exact_sha: input.head,
+        worktree_clean: input.clean,
+        environment: input.env,
+        started_at: started,
+        finished_at: input.now().toISOString(),
+        checks,
+        executions,
+        before_evidence_ids: [],
+        after_evidence_ids: [],
+        after_results: afterResults,
+        result: "INCONCLUSIVE",
+        reasons,
+        limitations,
+        actor: { id: "product-check", type: "system" },
+    });
+    if (reasons.length > 0) {
+        const r = run();
+        r.result = "INCONCLUSIVE";
+        reasons.unshift("Preconditions not met; nothing was verified.");
+        return r;
+    }
+    const es = entries;
+    // Re-assessment at the fix commit (offline) -----------------------------------------------------------------------
+    const base = input.baseline.results;
+    const contract = input.contract ?? structuredClone(base.contract);
+    if (!input.contract) {
+        contract.imports = defaultContract().imports;
+        limitations.push("Imported artifacts from the baseline (test results, reports, observations) were not reused; controls that need them are NOT_TESTED unless re-supplied.");
+    }
+    contract.target.repository = { path: input.repo };
+    contract.imports.test_results = [...contract.imports.test_results, ...input.extraTestResults];
+    const { results: after } = await runAssessment({
+        contract,
+        permissions: {
+            network: false,
+            exposureProbe: false,
+            origin: null,
+            appBlockedReason: contract.target.application
+                ? "Closure verification runs offline; supply recorded observations with --contract to re-check application controls."
+                : null,
+        },
+        baseline: input.baseline,
+        baseDir: input.baseDir,
+        now: input.now,
+    });
+    const path = input.writeAfterResults(verificationId, after);
+    const afterSha = sha256(`${JSON.stringify(after, null, 2)}\n`);
+    const afterEvidence = input.log.append({
+        type: "results-artifact",
+        subject: verificationId,
+        commit_sha: input.head,
+        environment_id: input.env.environment_id,
+        summary: `Re-assessment ${after.run.run_id} at ${input.head.slice(0, 12)}: ${after.verdict.verdict}`,
+        locator: path,
+        line: null,
+        payload: {
+            run_id: after.run.run_id,
+            results_sha256: afterSha,
+            verdict: after.verdict.verdict,
+            open: after.scorecard.open_findings,
+        },
+    });
+    afterResults = {
+        run_id: after.run.run_id,
+        results_path: path,
+        results_sha256: afterSha,
+        verdict: after.verdict.verdict,
+        open: after.scorecard.open_findings,
+    };
+    for (const e of es) {
+        if (e.source === "baseline-scan") {
+            const v = after.validations.find((x) => x.control_id === e.rule_or_control);
+            const still = after.findings.find((f) => f.id === e.source_finding_id && f.status !== "RESOLVED");
+            const sameOrWorse = after.findings.filter((f) => f.control_id === e.rule_or_control &&
+                (f.status === "OPEN" || f.status === "UNVERIFIED") &&
+                RANK[f.severity] <= RANK[e.severity]);
+            let status;
+            let detail;
+            if (!v || v.status === "NOT_TESTED" || v.status === "BLOCKED") {
+                status = "NOT_TESTED";
+                detail = `${e.rule_or_control} could not be evaluated at the fix commit${v?.reason ? `: ${v.reason}` : ""}.`;
+            }
+            else if (still) {
+                status = "FAIL";
+                detail = `${e.rule_or_control} still reports the original finding (${still.location}).`;
+            }
+            else if (sameOrWorse.length > 0) {
+                status = "FAIL";
+                detail = `The original location is gone but ${e.rule_or_control} still fails at ${sameOrWorse
+                    .map((f) => f.location)
+                    .slice(0, 3)
+                    .join(", ")} (${sameOrWorse[0]?.severity}): the fix moved the problem.`;
+            }
+            else {
+                status = "PASS";
+                detail = `${e.rule_or_control} is ${v.status} at the fix commit and no longer reports the finding.`;
+            }
+            checks.push({
+                check_id: `targeted:${e.finding_id}:control`,
+                kind: "control-reassessment",
+                role: "targeted",
+                status,
+                detail,
+                execution_id: null,
+                evidence_ids: [afterEvidence],
+            });
+            const gate = CONTROL_BY_ID.get(e.rule_or_control)?.gate ?? null;
+            if (gate) {
+                const g = after.scorecard.gates.find((x) => x.gate_id === gate);
+                checks.push({
+                    check_id: `targeted:${e.finding_id}:gate`,
+                    kind: "gate-recheck",
+                    role: "targeted",
+                    status: g === undefined ? "NOT_TESTED" : g.status === "FAIL" ? "FAIL" : "PASS",
+                    detail: g === undefined
+                        ? `Associated hard gate ${gate} was not evaluated.`
+                        : g.status === "UNVERIFIED"
+                            ? `Associated hard gate ${gate} no longer fails; it stays UNVERIFIED overall because other gate controls were not testable here (disclosed by the release gate).`
+                            : `Associated hard gate ${gate}: ${g.status}.`,
+                    execution_id: null,
+                    evidence_ids: [afterEvidence],
+                });
+            }
+        }
+        else {
+            const [path0, lineStr] = e.location.split(/:(?=\d+$)/);
+            const filePath = path0 ?? e.location;
+            let text;
+            try {
+                const root = resolve(input.repo);
+                const abs = resolve(root, filePath);
+                text = abs.startsWith(root + sep) ? readFileSync(abs, "utf8") : null;
+            }
+            catch {
+                text = null;
+            }
+            const still = text === null
+                ? []
+                : lineHits(filePath, text.split("\n").map((t, i) => ({ line: i + 1, text: t }))).filter((h) => h.rule_id === e.rule_or_control);
+            const fileRule = FILE_RULES.has(e.rule_or_control) ||
+                e.rule_or_control.startsWith("VC-EXT") ||
+                e.rule_or_control.startsWith("VC-SP");
+            checks.push(fileRule
+                ? {
+                    check_id: `targeted:${e.finding_id}:rule`,
+                    kind: "rule-recheck",
+                    role: "targeted",
+                    status: "NOT_TESTED",
+                    detail: `${e.rule_or_control} is a change-level or external finding; a declared reproduction command is the targeted check.`,
+                    execution_id: null,
+                    evidence_ids: [],
+                }
+                : {
+                    check_id: `targeted:${e.finding_id}:rule`,
+                    kind: "rule-recheck",
+                    role: "targeted",
+                    status: still.length === 0 ? "PASS" : "FAIL",
+                    detail: still.length === 0
+                        ? `${e.rule_or_control} no longer matches ${filePath} at the fix commit${lineStr ? ` (was line ${lineStr})` : ""}.`
+                        : `${e.rule_or_control} still matches ${filePath} at line(s) ${still.map((h) => h.line).join(", ")}.`,
+                    execution_id: null,
+                    evidence_ids: [],
+                });
+        }
+    }
+    // Commands --------------------------------------------------------------------------------------------------------
+    const ctx = {
+        repo: input.repo,
+        permission: input.permission,
+        policy: input.policy,
+        env: input.env,
+        sha: input.head,
+        log: input.log,
+        now: input.now,
+    };
+    const repro = runCommands(fix?.reproduction ?? [], "targeted", ctx);
+    const corpus = reg.regression_corpus.map((c) => c.command);
+    const regression = runCommands([...input.policy.required_checks, ...corpus], "regression", ctx);
+    executions = [...repro.executions, ...regression.executions];
+    checks.push(...repro.checks, ...regression.checks);
+    // A change-level finding with no reproduction command cannot be verified.
+    for (const c of checks.filter((x) => x.kind === "rule-recheck" && x.status === "NOT_TESTED")) {
+        if (repro.checks.some((r) => r.status === "PASS") && !repro.checks.some((r) => r.status !== "PASS")) {
+            c.status = "PASS";
+            c.detail += " Declared reproduction command(s) passed.";
+        }
+    }
+    // Regression vs baseline ------------------------------------------------------------------------------------------
+    const cmp = after.comparison;
+    const newCritical = (cmp?.findings_new ?? []).filter((id) => {
+        const f = after.findings.find((x) => x.id === id);
+        return f !== undefined && (f.severity === "P0" || f.severity === "P1");
+    });
+    checks.push({
+        check_id: "regression:no-new-critical",
+        kind: "no-new-critical",
+        role: "regression",
+        status: newCritical.length === 0 ? "PASS" : "FAIL",
+        detail: newCritical.length === 0
+            ? "No new P0/P1 finding compared with the baseline."
+            : `New P0/P1 finding(s): ${newCritical.join(", ")}.`,
+        execution_id: null,
+        evidence_ids: [afterEvidence],
+    });
+    const regressed = cmp?.regressed_controls ?? [];
+    checks.push({
+        check_id: "regression:controls",
+        kind: "no-regressed-controls",
+        role: "regression",
+        status: regressed.length === 0 ? "PASS" : "FAIL",
+        detail: regressed.length === 0
+            ? "No control regressed compared with the baseline."
+            : `Regressed control(s): ${regressed.join(", ")}.`,
+        execution_id: null,
+        evidence_ids: [afterEvidence],
+    });
+    if (input.policy.required_checks.length === 0 && corpus.length === 0)
+        limitations.push("No executable regression suite is declared (policy required_checks / corpus); regression rests on Product Check's re-assessment only.");
+    const r = run();
+    r.after_evidence_ids = [
+        afterEvidence,
+        ...executions.map((x) => x.evidence_id).filter((x) => x !== null),
+    ];
+    r.before_evidence_ids = es.flatMap((e) => {
+        const f = base.findings.find((x) => x.id === e.source_finding_id);
+        return f ? f.evidence_ids : [];
+    });
+    r.result = overall(checks);
+    const failed = checks.filter((c) => c.status === "FAIL");
+    const notRun = checks.filter((c) => c.status === "NOT_TESTED" || c.status === "BLOCKED");
+    if (failed.length > 0)
+        reasons.push(`Failed: ${failed.map((c) => `${c.check_id} — ${c.detail}`).join(" | ")}`);
+    if (notRun.length > 0)
+        reasons.push(`Not run: ${notRun.map((c) => `${c.check_id} — ${c.detail}`).join(" | ")}`);
+    if (r.result === "PASS")
+        reasons.push(`All ${checks.length} targeted and regression check(s) passed at ${input.head.slice(0, 12)}.`);
+    r.finished_at = input.now().toISOString();
+    r.verification_id = verificationId;
+    return r;
+}

package/dist/cli/run.js

@@ -26,6 +26,7 @@ import { relativize } from "../util/paths.js";
 import { CONTROLS } from "../validation/catalog.js";
 import { checkResults } from "../validation/integrity.js";
 import { STAGES, TIER_INFO } from "../validation/tiers.js";
+import { ASSURANCE_COMMANDS, ASSURANCE_HELP, runAssurance } from "../assurance/cli.js";
 import { TOOL_VERSION } from "../version.js";
 /** Text printed by `product-check --help`. */
 export const HELP = `Product Check ${TOOL_VERSION} — does this software work, can it be trusted, and what needs to improve?
@@ -74,6 +75,8 @@ Output:
   --fail-on <verdicts>      Exit 6 when the verdict is one of these (e.g. NOT_READY,INCONCLUSIVE)
   --no-dashboard  --no-branding  --quiet
 
+${ASSURANCE_HELP}
+
 Exit codes: 0 ok · 1 internal error · 2 usage/config · 3 input · 4 safety refusal · 5 invalid artifact · 6 --fail-on matched
 Local-first: no telemetry, no account, no model calls. Network only to an authorized origin with passive GETs.
 `;
@@ -472,6 +475,10 @@ function commandValidate(files, io) {
 }
 /** Parses arguments and runs one command. */
 async function main(argv, io) {
+    const first = argv[0] ?? "";
+    if (ASSURANCE_COMMANDS.includes(first) ||
+        ((first === "dashboard" || first === "blueprint") && argv.includes("--from")))
+        return runAssurance(first, argv.slice(1), io);
     const { values, positionals } = (() => {
         try {
             return parseArgs({ args: argv, allowPositionals: true, strict: true, options: OPTIONS });
@@ -581,7 +588,7 @@ async function main(argv, io) {
             return ExitCode.Ok;
         }
         default:
-            throw usageError(`Unknown command: ${command}`, "Commands: run, retest, scan, spec, init, validate, report, blueprint, dashboard, controls, schema.");
+            throw usageError(`Unknown command: ${command}`, `Commands: run, retest, scan, spec, init, validate, report, blueprint, dashboard, controls, schema, ${ASSURANCE_COMMANDS.join(", ")}.`);
     }
 }
 /** Runs the CLI and returns the process exit code. Never throws. */

package/dist/exec/process.d.ts

@@ -0,0 +1,27 @@
+import type { CommandExecution, CommandSpec } from "../assurance/types.js";
+/** Result of a git read. */
+export interface GitResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a read-only git subcommand in `repo`. */
+export declare function gitRead(repo: string, args: string[], maxBuffer?: number): GitResult;
+/** Authorization for command execution, decided once per CLI invocation. */
+export interface ExecPermission {
+    allowed: boolean;
+    reason: string;
+}
+/** Inputs to one execution. */
+export interface ExecInput {
+    spec: CommandSpec;
+    repo: string;
+    permission: ExecPermission;
+    envAllowlist: readonly string[];
+    maxOutputBytes: number;
+    environmentId: string;
+    commitSha: string | null;
+    now: () => Date;
+}
+/** Executes one declared command (argv, no shell). Never throws for command failures. */
+export declare function execCommand(input: ExecInput): CommandExecution;