project-tiny-context-harness 0.2.70 → 0.2.71

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;

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

@@ -0,0 +1,196 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathExists, readText } from "./fs.js";
+const PATH_PATTERN = /(?:`([^`]+)`)|((?:\.\/)?(?:project_context|packages|tests|tmp|src|app|pages|components|\.codex|tools|examples)\/[A-Za-z0-9._@+/-]+(?:\.(?:md|ts|tsx|js|mjs|json|yaml|yml|toml|png|jpe?g|webp|html|css|scss|py|go|rs|java|cs|sh|ps1))?)/g;
+const WEAK_PROOF_PATTERNS = [
+    /\bchecked path(?:s)?\b/i,
+    /\bsampled(?:[_ -]?only)?\b/i,
+    /\bnot live-proven\b/i,
+    /\blacks?\b/i,
+    /\bmissing\b/i,
+    /\bgap\b/i,
+    /\bpartial\b/i,
+    /\bblocked\b/i,
+    /\bunconfigured\b/i,
+    /\bnot visible by default\b/i
+];
+export async function resolveInputFile(projectRoot, value, defaultPath) {
+    const raw = value ?? defaultPath;
+    const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(projectRoot, raw);
+    let candidate = absolute;
+    try {
+        const stat = await fs.stat(absolute);
+        if (stat.isDirectory()) {
+            candidate = path.join(absolute, defaultPath);
+        }
+    }
+    catch {
+        if (!path.extname(absolute)) {
+            candidate = path.join(absolute, defaultPath);
+        }
+    }
+    return candidate;
+}
+export async function resolveInputDir(projectRoot, value, defaultPath) {
+    return path.isAbsolute(value ?? defaultPath)
+        ? path.resolve(value ?? defaultPath)
+        : path.resolve(projectRoot, value ?? defaultPath);
+}
+export function repoRelative(projectRoot, file) {
+    return path.relative(projectRoot, file).split(path.sep).join("/");
+}
+export async function readRequiredFile(projectRoot, file, label, errors) {
+    if (!isInside(projectRoot, file)) {
+        errors.push(`${label} must stay inside the project root: ${file}`);
+        return undefined;
+    }
+    if (!(await pathExists(file))) {
+        errors.push(`${label} is missing: ${repoRelative(projectRoot, file)}`);
+        return undefined;
+    }
+    return readText(file);
+}
+export function parseRequiredTable(content, heading, expectedHeaders, label, errors) {
+    const section = sectionBody(content, heading);
+    if (section === undefined) {
+        errors.push(`plan contract is missing section: ${heading}`);
+        return undefined;
+    }
+    const lines = section.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!lines[index].includes("|")) {
+            continue;
+        }
+        const headers = splitTableLine(lines[index]);
+        const normalized = headers.map(normalizeHeader);
+        if (!expectedHeaders.every((header) => normalized.includes(normalizeHeader(header)))) {
+            continue;
+        }
+        const rows = [];
+        for (let rowIndex = index + 1; rowIndex < lines.length; rowIndex += 1) {
+            const line = lines[rowIndex];
+            if (!line.includes("|")) {
+                break;
+            }
+            if (isSeparatorLine(line)) {
+                continue;
+            }
+            const values = splitTableLine(line);
+            const cells = {};
+            for (const [cellIndex, header] of normalized.entries()) {
+                cells[header] = values[cellIndex]?.trim() ?? "";
+            }
+            rows.push({
+                index: rows.length + 1,
+                line: rowIndex + 1,
+                cells,
+                text: Object.values(cells).join(" ")
+            });
+        }
+        const missing = expectedHeaders.filter((header) => !normalized.includes(normalizeHeader(header)));
+        if (missing.length > 0) {
+            errors.push(`${label} table is missing column(s): ${missing.join(", ")}`);
+        }
+        return { rows, headers: normalized };
+    }
+    errors.push(`${label} section must include a markdown table with columns: ${expectedHeaders.join(" | ")}`);
+    return undefined;
+}
+export function cell(row, header) {
+    return row.cells[normalizeHeader(header)] ?? "";
+}
+export function isBlankish(value) {
+    if (Array.isArray(value)) {
+        return value.length === 0 || value.every(isBlankish);
+    }
+    if (value === undefined || value === null) {
+        return true;
+    }
+    const text = String(value).trim().toLowerCase();
+    return text === "" || text === "-" || text === "n/a" || text === "na" || text === "none" || text === "[]" || text === "not applicable";
+}
+export function weakProofHit(text) {
+    return WEAK_PROOF_PATTERNS.find((pattern) => pattern.test(text))?.source;
+}
+export async function assertReferencedPathsExist(projectRoot, label, text, errors) {
+    for (const reference of extractPathReferences(text)) {
+        const absolute = path.resolve(projectRoot, reference);
+        if (!isInside(projectRoot, absolute)) {
+            errors.push(`${label} references a path outside the project root: ${reference}`);
+            continue;
+        }
+        if (!(await pathExists(absolute))) {
+            errors.push(`${label} references missing path: ${reference}`);
+        }
+    }
+}
+export function primitiveText(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(primitiveText).join(" ");
+    }
+    if (typeof value === "object") {
+        return Object.values(value).map(primitiveText).join(" ");
+    }
+    return "";
+}
+export function valuesAsArray(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(valuesAsArray);
+    }
+    if (isBlankish(value)) {
+        return [];
+    }
+    return String(value)
+        .split(/[,;\n]/)
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+export function hasRealPageEvidence(text) {
+    return /\b(real[- ]page|browser|route|screen|screenshot|url|localhost|https?:\/\/|page)\b/i.test(text);
+}
+export function isUiFacing(text) {
+    return /\b(ui|browser|page|screen|console|frontend|route|surface)\b/i.test(text);
+}
+export function isRuntimeFacing(text) {
+    return /\b(runtime|worker|api|schema|endpoint|service|queue|daemon|runner)\b/i.test(text);
+}
+function sectionBody(content, heading) {
+    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`^##\\s+${escaped}\\s*$`, "im").exec(content);
+    if (!match) {
+        return undefined;
+    }
+    const rest = content.slice(match.index + match[0].length);
+    const next = /^##\s+/m.exec(rest);
+    return next ? rest.slice(0, next.index) : rest;
+}
+function splitTableLine(line) {
+    return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cellValue) => cellValue.trim());
+}
+function isSeparatorLine(line) {
+    return splitTableLine(line).every((value) => /^:?-{3,}:?$/.test(value.trim()));
+}
+function normalizeHeader(value) {
+    return value.replace(/`/g, "").trim().toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ");
+}
+function extractPathReferences(text) {
+    const references = new Set();
+    for (const match of text.matchAll(PATH_PATTERN)) {
+        const raw = (match[1] ?? match[2] ?? "").trim();
+        if (!raw || raw.includes("*") || /^https?:\/\//i.test(raw)) {
+            continue;
+        }
+        references.add(raw.replace(/\\/g, "/").replace(/^\.\//, "").replace(/[),.;:]+$/, ""));
+    }
+    return [...references];
+}
+function isInside(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/dist/lib/validators.d.ts

@@ -2,4 +2,4 @@ export interface ValidatorReport {
     info: string[];
     errors: string[];
 }
-export declare function runValidator(projectRoot: string, gate: string): Promise<ValidatorReport>;
+export declare function runValidator(projectRoot: string, gate: string, args?: string[]): Promise<ValidatorReport>;

package/dist/lib/validators.js

@@ -3,11 +3,15 @@ import { readConfig } from "./config.js";
 import { harnessPath, harnessRoot } from "./harness-root.js";
 import { listFiles, pathExists, readText } from "./fs.js";
 import { runModularityCheck } from "./modularity.js";
+import { validatePlanAcceptance } from "./plan-acceptance-validator.js";
+import { validatePlanContract } from "./plan-contract-validator.js";
 import { unsupportedSchemaMessage } from "./schema-guard.js";
 const VALIDATORS = {
     "validate-context": validateContext,
     "validate-code-modularity": validateCodeModularity,
-    "validate-harness": validateHarness
+    "validate-harness": validateHarness,
+    "validate-plan-contract": validatePlanContract,
+    "validate-plan-acceptance": validatePlanAcceptance
 };
 const GLOBAL_REQUIRED_SECTIONS = [
     ...sectionSpecs([
@@ -67,17 +71,17 @@ const FAKE_VERIFICATION_PATTERNS = [
     /\b验证(?:已)?通过\b/,
     /\b部署(?:已)?成功\b/
 ];
-export async function runValidator(projectRoot, gate) {
+export async function runValidator(projectRoot, gate, args = []) {
     const validator = VALIDATORS[gate];
     if (!validator) {
         return {
             info: [],
             errors: [
-                `unknown validator: ${gate}. Minimal Context Harness supports validate-context, validate-code-modularity and validate-harness only.`
+                `unknown validator: ${gate}. Minimal Context Harness supports validate-context, validate-code-modularity, validate-harness, validate-plan-contract and validate-plan-acceptance only.`
             ]
         };
     }
-    return validator(projectRoot);
+    return validator(projectRoot, args);
 }
 async function validateHarness(projectRoot) {
     const contextReport = await validateContext(projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-tiny-context-harness",
-  "version": "0.2.70",
+  "version": "0.2.71",
   "description": "Minimal project memory and validation harness for AI coding agents.",
   "license": "MIT",
   "author": "Seven128",