project-tiny-context-harness 0.2.70 → 0.2.72

package/dist/lib/plan-acceptance-evidence.js

@@ -0,0 +1,68 @@
+import { isOutOfScope } from "./plan-acceptance-json.js";
+import { isBlankish, primitiveText, valuesAsArray } from "./plan-validator-common.js";
+const BLOCKING_AUDITOR_STATUSES = new Set(["partial", "blocked", "invalidated"]);
+export function assertExternalReviewerFields(label, row, evidenceText, errors) {
+    if (hasUnresolvedMissingRequiredLayers(row)) {
+        errors.push(`${label} is complete but missing_required_layers is not empty`);
+    }
+    const driftSeverity = String(row.drift_severity ?? row.driftSeverity ?? "").trim().toLowerCase();
+    if (driftSeverity === "material" || driftSeverity === "critical") {
+        errors.push(`${label} is complete but drift_severity is ${driftSeverity}`);
+    }
+    if (siblingSubstitutionUsed(row) && !hasSiblingSubstitutionApproval(row)) {
+        errors.push(`${label} is complete but sibling_substitution_used without approval`);
+    }
+    const auditorStatus = String(row.auditor_status ?? row.auditorStatus ?? "").trim().toLowerCase();
+    if (BLOCKING_AUDITOR_STATUSES.has(auditorStatus)) {
+        errors.push(`${label} is complete but auditor_status is ${auditorStatus}`);
+    }
+    if (hasOnlySelfCertifyingEvidence(evidenceText)) {
+        errors.push(`${label} is complete but fresh_evidence contains only summary or self-certifying evidence`);
+    }
+}
+function hasUnresolvedMissingRequiredLayers(row) {
+    const value = row.missing_required_layers ?? row.missingRequiredLayers ?? row.missing_proof_layers;
+    if (isBlankish(value)) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => !isBlankish(item) && !isStructuredLayerNa(item));
+    }
+    return !isStructuredLayerNa(value);
+}
+function isStructuredLayerNa(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const object = value;
+    const text = primitiveText(object);
+    const hasNaStatus = isOutOfScope(object) || /\bout[_ -]?of[_ -]?scope[_ -]?NA\b/i.test(text);
+    const hasSource = !isBlankish(object.scope_source) ||
+        !isBlankish(object.approval_source) ||
+        !isBlankish(object.source_reference) ||
+        !isBlankish(object.sourceReference);
+    return hasNaStatus && hasSource;
+}
+function siblingSubstitutionUsed(row) {
+    const value = row.sibling_substitution_used ?? row.siblingSubstitutionUsed;
+    if (value === true) {
+        return true;
+    }
+    const text = primitiveText(value);
+    if (/\b(false|no|none|not used|not_used)\b/i.test(text)) {
+        return false;
+    }
+    return /\b(true|yes|used|present)\b/i.test(text);
+}
+function hasSiblingSubstitutionApproval(row) {
+    return (!isBlankish(row.sibling_substitution_approval_source) ||
+        !isBlankish(row.substitution_approval_source) ||
+        /\b(approved|explicitly allowed|out[_ -]?of[_ -]?scope[_ -]?NA)\b/i.test(primitiveText([row.sibling_substitution_approved, row.substitution_approval])));
+}
+function hasOnlySelfCertifyingEvidence(text) {
+    const entries = valuesAsArray(text);
+    return entries.length > 0 && entries.every(isSelfCertifyingEvidence);
+}
+function isSelfCertifyingEvidence(text) {
+    return /\b(local audit|audit says|plan[- ]conformance(?: matrix)?|matrix row|final[- ]acceptance[- ]verdict|final verdict|verdict row|subagent summary|agent summary|reviewer summary|validator pass|validate-plan-acceptance(?: passed| pass)?|green check|final result card)\b/i.test(text);
+}

package/dist/lib/plan-acceptance-json.d.ts

@@ -0,0 +1,15 @@
+export declare const MATRIX_STATUSES: Set<string>;
+export declare const AC_STATUSES: Set<string>;
+export declare const NON_COMPLETE_MATRIX: Set<string>;
+export declare const NON_COMPLETE_AC: Set<string>;
+export declare function findJsonFile(targetDir: string, marker: string): Promise<string | undefined>;
+export declare function readJson(file: string, errors: string[]): Promise<unknown>;
+export declare function findRows(value: unknown, preferredKeys: string[]): Record<string, unknown>[];
+export declare function overallStatus(value: unknown): string;
+export declare function statusOf(row: Record<string, unknown>): string;
+export declare function isOutOfScope(row: Record<string, unknown>): boolean;
+export declare function contextDeltaRequired(value: unknown): boolean;
+export declare function isSurfaceConformanceRow(row: Record<string, unknown>): boolean;
+export declare function hasExplicitNoTestScope(row: Record<string, unknown>): boolean;
+export declare function assertSurfaceConformance(row: Record<string, unknown>, label: string, errors: string[]): void;
+export declare function assertStructuredNa(row: Record<string, unknown>, label: string, errors: string[]): void;

package/dist/lib/plan-acceptance-json.js

@@ -0,0 +1,129 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readText } from "./fs.js";
+import { isBlankish, primitiveText, valuesAsArray } from "./plan-validator-common.js";
+export const MATRIX_STATUSES = new Set([
+    "complete",
+    "partial",
+    "sampled_only",
+    "not_implemented",
+    "blocked",
+    "scope_changed_requires_user_approval",
+    "contradicted_by_current_state",
+    "out_of_scope_NA"
+]);
+export const AC_STATUSES = new Set(["complete", "partial", "blocked", "not_run", "invalidated", "out_of_scope_NA"]);
+export const NON_COMPLETE_MATRIX = new Set([
+    "partial",
+    "sampled_only",
+    "not_implemented",
+    "blocked",
+    "scope_changed_requires_user_approval",
+    "contradicted_by_current_state"
+]);
+export const NON_COMPLETE_AC = new Set(["partial", "blocked", "not_run", "invalidated"]);
+export async function findJsonFile(targetDir, marker) {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json") && entry.name.includes(marker))
+        .map((entry) => path.join(targetDir, entry.name))
+        .sort()[0];
+}
+export async function readJson(file, errors) {
+    try {
+        return JSON.parse(await readText(file));
+    }
+    catch (error) {
+        errors.push(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+export function findRows(value, preferredKeys) {
+    if (Array.isArray(value) && value.every((item) => item && typeof item === "object" && !Array.isArray(item))) {
+        return value;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [];
+    }
+    const object = value;
+    for (const key of preferredKeys) {
+        const rows = findRows(object[key], []);
+        if (rows.length > 0) {
+            return rows;
+        }
+    }
+    return Object.values(object).map((item) => findRows(item, [])).sort((a, b) => b.length - a.length)[0] ?? [];
+}
+export function overallStatus(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return "";
+    }
+    const object = value;
+    return String(object.overall_status ?? object.overallStatus ?? object.status ?? "").trim();
+}
+export function statusOf(row) {
+    return String(row.status ?? "").trim();
+}
+export function isOutOfScope(row) {
+    return statusOf(row) === "out_of_scope_NA" || /out[_ -]?of[_ -]?scope|n\/a|not applicable/i.test(primitiveText(row));
+}
+export function contextDeltaRequired(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const object = value;
+    return [
+        object.context_delta,
+        object.contextDelta,
+        object.product_context_delta,
+        object.productContextDelta,
+        object.technical_context_delta,
+        object.technicalContextDelta
+    ].some((item) => /\brequired\b/i.test(primitiveText(item)));
+}
+export function isSurfaceConformanceRow(row) {
+    return (/\b(product[_ -]?surface|surface|ia|information[_ -]?architecture|architecture[_ -]?migration|ui)\b/i.test(primitiveText(row.conformance_type)) ||
+        !isBlankish(row.owner_surface) ||
+        !isBlankish(row.forbidden_primary_surfaces) ||
+        !isBlankish(row.required_user_paths));
+}
+export function hasExplicitNoTestScope(row) {
+    return /\b(no[- ]?test|no automated test|test out of scope|tests? not required)\b/i.test(primitiveText([row.test_scope, row.no_test_scope, row.tests]));
+}
+export function assertSurfaceConformance(row, label, errors) {
+    if (isBlankish(row.owner_surface)) {
+        errors.push(`${label} is surface/architecture conformance but owner_surface is empty`);
+    }
+    if (isBlankish(row.required_user_paths)) {
+        errors.push(`${label} is surface/architecture conformance but required_user_paths is empty`);
+    }
+    if (isBlankish(row.real_page_evidence)) {
+        errors.push(`${label} is surface/architecture conformance but real_page_evidence is empty`);
+    }
+    if (isBlankish(row.context_fact_refs)) {
+        errors.push(`${label} is surface/architecture conformance but context_fact_refs is empty`);
+    }
+    if (!isBlankish(row.forbidden_primary_surfaces) && isBlankish(row.negative_surface_checks)) {
+        errors.push(`${label} declares forbidden_primary_surfaces but negative_surface_checks is empty`);
+    }
+    const userPathText = primitiveText([row.required_user_paths, row.primary_user_paths]);
+    for (const forbiddenSurface of valuesAsArray(row.forbidden_primary_surfaces)) {
+        if (userPathText.toLowerCase().includes(forbiddenSurface.toLowerCase())) {
+            errors.push(`${label} routes a required/primary user path through forbidden surface: ${forbiddenSurface}`);
+        }
+    }
+    if (row.default_visibility_required === true && !mentionsDefaultVisibility(primitiveText(row.real_page_evidence))) {
+        errors.push(`${label} requires default visibility but real_page_evidence does not record default-visible proof`);
+    }
+}
+export function assertStructuredNa(row, label, errors) {
+    if (isBlankish(row.na_reason) && isBlankish(row.out_of_scope_reason)) {
+        errors.push(`${label} is out_of_scope_NA but lacks na_reason or out_of_scope_reason`);
+    }
+    if (isBlankish(row.scope_source) && isBlankish(row.approval_source) && isBlankish(row.source_reference)) {
+        errors.push(`${label} is out_of_scope_NA but lacks scope_source, approval_source or source_reference`);
+    }
+}
+function mentionsDefaultVisibility(value) {
+    return /\b(default[- ]?visible|visible by default|primary entry|first-level|top-level|main entry)\b/i.test(value);
+}

package/dist/lib/plan-acceptance-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorReport } from "./validators.js";
+export declare function validatePlanAcceptance(projectRoot: string, args?: string[]): Promise<ValidatorReport>;

package/dist/lib/plan-acceptance-validator.js

@@ -0,0 +1,190 @@
+import { pathExists } from "./fs.js";
+import { assertExternalReviewerFields } from "./plan-acceptance-evidence.js";
+import { AC_STATUSES, MATRIX_STATUSES, NON_COMPLETE_AC, NON_COMPLETE_MATRIX, assertStructuredNa, assertSurfaceConformance, contextDeltaRequired, findJsonFile, findRows, hasExplicitNoTestScope, isOutOfScope, isSurfaceConformanceRow, overallStatus, readJson, statusOf } from "./plan-acceptance-json.js";
+import { assertReferencedPathsExist, hasRealPageEvidence, isBlankish, isUiFacing, primitiveText, repoRelative, resolveInputDir, valuesAsArray, weakProofHit } from "./plan-validator-common.js";
+export async function validatePlanAcceptance(projectRoot, args = []) {
+    const info = [];
+    const errors = [];
+    const targetDir = await resolveInputDir(projectRoot, args[0], "tmp/ty-context/plan-acceptance");
+    if (!(await pathExists(targetDir))) {
+        return { info, errors: [`plan acceptance directory is missing: ${repoRelative(projectRoot, targetDir)}`] };
+    }
+    const matrixFile = await findJsonFile(targetDir, "plan-conformance-matrix");
+    const verdictFile = await findJsonFile(targetDir, "final-acceptance-verdict");
+    if (!matrixFile) {
+        errors.push(`plan acceptance directory is missing *-plan-conformance-matrix.json`);
+    }
+    if (!verdictFile) {
+        errors.push(`plan acceptance directory is missing *-final-acceptance-verdict.json`);
+    }
+    if (!matrixFile || !verdictFile) {
+        return { info, errors };
+    }
+    const matrix = await readJson(matrixFile, errors);
+    const verdict = await readJson(verdictFile, errors);
+    if (matrix === undefined || verdict === undefined) {
+        return { info, errors };
+    }
+    const matrixRows = findRows(matrix, ["plan_items", "items", "matrix", "entries", "plan_conformance"]);
+    const verdictRows = findRows(verdict, ["acceptance_items", "ac_verdicts", "verdicts", "items", "entries", "acs"]);
+    await validateMatrixRows(projectRoot, matrixRows, overallStatus(matrix), errors);
+    await validateVerdictRows(projectRoot, verdictRows, overallStatus(verdict), errors);
+    validateCrossReferences(matrixRows, verdictRows, errors);
+    validateContextFactReferences(matrix, verdict, matrixRows, verdictRows, errors);
+    info.push(`checked plan acceptance ${repoRelative(projectRoot, targetDir)} matrix_rows=${matrixRows.length} verdict_rows=${verdictRows.length}`);
+    if (errors.length === 0) {
+        info.push("Plan acceptance artifact consistency passed");
+    }
+    return { info, errors };
+}
+async function validateMatrixRows(projectRoot, rows, overall, errors) {
+    if (rows.length === 0) {
+        errors.push("plan-conformance matrix has no trace rows");
+    }
+    for (const [index, row] of rows.entries()) {
+        const label = `plan-conformance matrix row ${index + 1}`;
+        const status = statusOf(row);
+        if (!MATRIX_STATUSES.has(status)) {
+            errors.push(`${label} has unsupported status: ${status || "<empty>"}`);
+        }
+        if (status === "out_of_scope_NA") {
+            assertStructuredNa(row, label, errors);
+        }
+        if (overall === "complete" && NON_COMPLETE_MATRIX.has(status)) {
+            errors.push(`${label} is ${status} but overall_status is complete`);
+        }
+        if (status === "complete" && !isBlankish(row.missing_paths)) {
+            errors.push(`${label} is complete but missing_paths is not empty`);
+        }
+        if (status === "complete") {
+            if (isBlankish(row.plan_requirement)) {
+                errors.push(`${label} is complete but plan_requirement is empty`);
+            }
+            if (isBlankish(row.expected_surfaces)) {
+                errors.push(`${label} is complete but expected_surfaces is empty`);
+            }
+            if (isBlankish(row.implemented_paths)) {
+                errors.push(`${label} is complete but implemented_paths is empty`);
+            }
+            if (isBlankish(row.tests) && !hasExplicitNoTestScope(row)) {
+                errors.push(`${label} is complete but tests is empty and no explicit no-test scope is recorded`);
+            }
+            if (isBlankish(row.runtime_evidence) && isBlankish(row.artifact_evidence) && isBlankish(row.real_page_evidence)) {
+                errors.push(`${label} is complete but has no runtime, artifact or real-page evidence`);
+            }
+            if (isBlankish(row.scope_assessment)) {
+                errors.push(`${label} is complete but scope_assessment is empty`);
+            }
+            if (isBlankish(row.drift)) {
+                errors.push(`${label} is complete but drift is empty`);
+            }
+            assertExternalReviewerFields(label, row, primitiveText([row.runtime_evidence, row.artifact_evidence, row.real_page_evidence, row.fresh_evidence]), errors);
+            const weak = weakProofHit(primitiveText(row));
+            if (weak) {
+                errors.push(`${label} is complete but contains weak-proof language matching /${weak}/`);
+            }
+            if (isUiFacing(primitiveText([row.expected_surfaces, row.plan_requirement, row.conformance_type]))) {
+                const realPageEvidence = primitiveText([
+                    row.real_page_evidence,
+                    row.user_path_evidence,
+                    row.fresh_evidence,
+                    row.runtime_evidence,
+                    row.artifact_evidence
+                ]);
+                if (!hasRealPageEvidence(realPageEvidence)) {
+                    errors.push(`${label} is UI/surface-facing but lacks real_page_evidence`);
+                }
+            }
+            if (isSurfaceConformanceRow(row)) {
+                assertSurfaceConformance(row, label, errors);
+            }
+            await assertReferencedPathsExist(projectRoot, label, primitiveText([
+                row.implemented_paths,
+                row.tests,
+                row.runtime_evidence,
+                row.artifact_evidence,
+                row.real_page_evidence,
+                row.negative_surface_checks,
+                row.context_fact_refs
+            ]), errors);
+        }
+    }
+}
+async function validateVerdictRows(projectRoot, rows, overall, errors) {
+    if (rows.length === 0) {
+        errors.push("final acceptance verdict has no AC rows");
+    }
+    for (const [index, row] of rows.entries()) {
+        const label = `final acceptance verdict row ${index + 1}`;
+        const status = statusOf(row);
+        if (!AC_STATUSES.has(status)) {
+            errors.push(`${label} has unsupported status: ${status || "<empty>"}`);
+        }
+        if (status === "out_of_scope_NA") {
+            assertStructuredNa(row, label, errors);
+        }
+        if (overall === "complete" && NON_COMPLETE_AC.has(status)) {
+            errors.push(`${label} is ${status} but overall_status is complete`);
+        }
+        if (status === "complete" && isBlankish(row.fresh_evidence)) {
+            errors.push(`${label} is complete but fresh_evidence is empty`);
+        }
+        if (status === "complete" && isBlankish(row.required_evidence)) {
+            errors.push(`${label} is complete but required_evidence is empty`);
+        }
+        if (status === "complete" && isBlankish(row.decision)) {
+            errors.push(`${label} is complete but decision is empty`);
+        }
+        if (status === "complete" && !isBlankish(row.missing_evidence)) {
+            errors.push(`${label} is complete but missing_evidence is not empty`);
+        }
+        if (status === "complete" && !isBlankish(row.contradictions)) {
+            errors.push(`${label} is complete but contradictions is not empty`);
+        }
+        if (status === "complete") {
+            const text = primitiveText(row);
+            assertExternalReviewerFields(label, row, primitiveText(row.fresh_evidence), errors);
+            const weak = weakProofHit(text);
+            if (weak) {
+                errors.push(`${label} is complete but contains weak-proof language matching /${weak}/`);
+            }
+            if (isUiFacing(text) && !isOutOfScope(row) && !hasRealPageEvidence(primitiveText(row.fresh_evidence))) {
+                errors.push(`${label} is UI-facing but lacks fresh real-page evidence or explicit N/A`);
+            }
+            await assertReferencedPathsExist(projectRoot, label, primitiveText([row.fresh_evidence, row.context_fact_refs]), errors);
+        }
+    }
+}
+function validateCrossReferences(matrixRows, verdictRows, errors) {
+    const planIds = new Set(matrixRows.map((row) => String(row.plan_item_id ?? row.id ?? "")).filter(Boolean));
+    const acIds = new Set(verdictRows.map((row) => String(row.ac_id ?? row.id ?? row.acceptance_item ?? "")).filter(Boolean));
+    let checked = 0;
+    for (const [index, row] of matrixRows.entries()) {
+        for (const acId of valuesAsArray(row.acceptance_ids ?? row.ac_ids)) {
+            checked += 1;
+            if (!acIds.has(acId)) {
+                errors.push(`plan-conformance matrix row ${index + 1} references unknown AC id: ${acId}`);
+            }
+        }
+    }
+    for (const [index, row] of verdictRows.entries()) {
+        for (const planId of valuesAsArray(row.related_plan_item_ids ?? row.plan_item_ids)) {
+            checked += 1;
+            if (!planIds.has(planId)) {
+                errors.push(`final acceptance verdict row ${index + 1} references unknown plan item id: ${planId}`);
+            }
+        }
+    }
+    if (matrixRows.length > 0 && verdictRows.length > 0 && checked === 0) {
+        errors.push("plan acceptance artifacts must include acceptance_ids or related_plan_item_ids cross references");
+    }
+}
+function validateContextFactReferences(matrix, verdict, matrixRows, verdictRows, errors) {
+    if (!contextDeltaRequired(matrix) && !contextDeltaRequired(verdict)) {
+        return;
+    }
+    const rows = [...matrixRows, ...verdictRows];
+    if (!rows.some((row) => !isBlankish(row.context_fact_refs))) {
+        errors.push("Context Delta is required but matrix/verdict rows do not cite context_fact_refs");
+    }
+}

package/dist/lib/plan-contract-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorReport } from "./validators.js";
+export declare function validatePlanContract(projectRoot: string, args?: string[]): Promise<ValidatorReport>;

package/dist/lib/plan-contract-validator.js

@@ -0,0 +1,127 @@
+import { cell, hasRealPageEvidence, isBlankish, isRuntimeFacing, isUiFacing, parseRequiredTable, readRequiredFile, repoRelative, resolveInputFile, weakProofHit, assertReferencedPathsExist } from "./plan-validator-common.js";
+const SOURCE_HEADERS = [
+    "Source item",
+    "Durable constraint",
+    "Type",
+    "Existing Context Hit",
+    "Context action",
+    "Owning Context",
+    "Coverage status"
+];
+const BINDING_HEADERS = [
+    "Context fact",
+    "Implementation obligation",
+    "Expected surfaces",
+    "Implemented paths",
+    "Forbidden shortcuts",
+    "Verification path",
+    "Binding status"
+];
+const SOURCE_STATUSES = new Set([
+    "covered",
+    "new_context_required",
+    "context_updated",
+    "task_local_only",
+    "out_of_scope_explicit",
+    "needs_user_decision",
+    "under_scoped"
+]);
+const BINDING_STATUSES = new Set([
+    "bound",
+    "partial",
+    "missing",
+    "blocked",
+    "out_of_scope_explicit",
+    "needs_user_decision",
+    "contradicted_by_current_state"
+]);
+const UNRESOLVED_SOURCE = new Set(["new_context_required", "needs_user_decision", "under_scoped"]);
+const NON_BOUND = new Set(["partial", "missing", "blocked", "needs_user_decision", "contradicted_by_current_state"]);
+export async function validatePlanContract(projectRoot, args = []) {
+    const info = [];
+    const errors = [];
+    const planPath = await resolveInputFile(projectRoot, args[0], "plan.md");
+    const content = await readRequiredFile(projectRoot, planPath, "plan contract", errors);
+    if (content === undefined) {
+        return { info, errors };
+    }
+    const sourceTable = parseRequiredTable(content, "Source-to-Context Coverage", SOURCE_HEADERS, "Source-to-Context Coverage", errors);
+    if (sourceTable?.headers.includes("implementation constraint")) {
+        errors.push("Source-to-Context Coverage must not include Implementation constraint; use Context-to-Implementation Binding instead");
+    }
+    const bindingTable = parseRequiredTable(content, "Context-to-Implementation Binding", BINDING_HEADERS, "Context-to-Implementation Binding", errors);
+    if (sourceTable) {
+        for (const row of sourceTable.rows) {
+            const status = cell(row, "Coverage status");
+            const label = `Source-to-Context Coverage row ${row.index}`;
+            if (!SOURCE_STATUSES.has(status)) {
+                errors.push(`${label} has unsupported Coverage status: ${status || "<empty>"}`);
+            }
+            if (UNRESOLVED_SOURCE.has(status)) {
+                errors.push(`${label} is unresolved (${status}) and cannot pass final plan-contract validation`);
+            }
+            if (status === "covered" && isBlankish(cell(row, "Existing Context Hit"))) {
+                errors.push(`${label} is covered but has no Existing Context Hit`);
+            }
+            if (status === "context_updated" && isBlankish(cell(row, "Owning Context"))) {
+                errors.push(`${label} is context_updated but has no Owning Context`);
+            }
+            await assertReferencedPathsExist(projectRoot, label, `${cell(row, "Existing Context Hit")} ${cell(row, "Owning Context")}`, errors);
+        }
+    }
+    if (bindingTable) {
+        for (const row of bindingTable.rows) {
+            const status = cell(row, "Binding status");
+            const label = `Context-to-Implementation Binding row ${row.index}`;
+            const expectedSurfaces = cell(row, "Expected surfaces");
+            const implementedPaths = cell(row, "Implemented paths");
+            const verificationPath = cell(row, "Verification path");
+            const evidenceText = `${implementedPaths} ${verificationPath}`;
+            if (!BINDING_STATUSES.has(status)) {
+                errors.push(`${label} has unsupported Binding status: ${status || "<empty>"}`);
+            }
+            if (NON_BOUND.has(status)) {
+                errors.push(`${label} is ${status} and cannot pass final plan-contract validation`);
+            }
+            if (status === "bound") {
+                if (isBlankish(expectedSurfaces)) {
+                    errors.push(`${label} is bound but has no Expected surfaces`);
+                }
+                if (isBlankish(implementedPaths)) {
+                    errors.push(`${label} is bound but has no Implemented paths`);
+                }
+                if (isBlankish(verificationPath)) {
+                    errors.push(`${label} is bound but has no Verification path`);
+                }
+                const weak = weakProofHit(`${cell(row, "Context fact")} ${cell(row, "Implementation obligation")} ${expectedSurfaces} ${evidenceText}`);
+                if (weak) {
+                    errors.push(`${label} is bound but contains weak-proof language matching /${weak}/`);
+                }
+                if (isUiFacing(`${expectedSurfaces} ${cell(row, "Implementation obligation")}`) && !hasRealPageEvidence(evidenceText)) {
+                    errors.push(`${label} is UI/surface-facing but lacks real page, route, browser or screenshot evidence`);
+                }
+                if (isRuntimeFacing(expectedSurfaces) && !isRuntimeFacing(evidenceText)) {
+                    errors.push(`${label} expects runtime/API/worker coverage but implemented evidence does not name that surface`);
+                }
+                assertForbiddenShortcutsNotUsed(row, evidenceText, label, errors);
+            }
+            await assertReferencedPathsExist(projectRoot, label, `${cell(row, "Context fact")} ${implementedPaths} ${verificationPath}`, errors);
+        }
+    }
+    info.push(`checked plan contract ${repoRelative(projectRoot, planPath)} source_rows=${sourceTable?.rows.length ?? 0} binding_rows=${bindingTable?.rows.length ?? 0}`);
+    if (errors.length === 0) {
+        info.push("Plan contract validation passed");
+    }
+    return { info, errors };
+}
+function assertForbiddenShortcutsNotUsed(row, evidenceText, label, errors) {
+    const shortcuts = cell(row, "Forbidden shortcuts")
+        .split(/[,;\n]/)
+        .map((item) => item.trim())
+        .filter((item) => item && !isBlankish(item));
+    for (const shortcut of shortcuts) {
+        if (evidenceText.toLowerCase().includes(shortcut.toLowerCase())) {
+            errors.push(`${label} is bound but its evidence uses forbidden shortcut: ${shortcut}`);
+        }
+    }
+}

package/dist/lib/plan-validator-common.d.ts

@@ -0,0 +1,24 @@
+export interface PlanTableRow {
+    index: number;
+    line: number;
+    cells: Record<string, string>;
+    text: string;
+}
+export interface ParsedPlanTable {
+    rows: PlanTableRow[];
+    headers: string[];
+}
+export declare function resolveInputFile(projectRoot: string, value: string | undefined, defaultPath: string): Promise<string>;
+export declare function resolveInputDir(projectRoot: string, value: string | undefined, defaultPath: string): Promise<string>;
+export declare function repoRelative(projectRoot: string, file: string): string;
+export declare function readRequiredFile(projectRoot: string, file: string, label: string, errors: string[]): Promise<string | undefined>;
+export declare function parseRequiredTable(content: string, heading: string, expectedHeaders: string[], label: string, errors: string[]): ParsedPlanTable | undefined;
+export declare function cell(row: PlanTableRow, header: string): string;
+export declare function isBlankish(value: unknown): boolean;
+export declare function weakProofHit(text: string): string | undefined;
+export declare function assertReferencedPathsExist(projectRoot: string, label: string, text: string, errors: string[]): Promise<void>;
+export declare function primitiveText(value: unknown): string;
+export declare function valuesAsArray(value: unknown): string[];
+export declare function hasRealPageEvidence(text: string): boolean;
+export declare function isUiFacing(text: string): boolean;
+export declare function isRuntimeFacing(text: string): boolean;