@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.e7b62d8fdd33

package/dist/session/phase-completion.validation.js

@@ -1,4 +1,4 @@
-import { qaBlockerReasons, qaCandidateBugActions, qaFindingScopes, qaFindingSeverities, qaGateToolNames, qaScopeAuthorities, qaScopeConfidence, qaScopeEvidence, qaScopeFields, qaScopeSources, qaScopeSurfaces } from "./phase-completion.js";
+import { qaBlockerReasons, qaCandidateBugActions, qaFindingScopes, qaFindingSeverities, qaGateToolNames, qaScopeAuthorities, qaScopeCapabilities, qaScopeConfidence, qaScopeEvidence, qaScopeFields, qaScopeSources, qaScopeSurfaces } from "./phase-completion.js";
 export function normalizeCompletionStatus(value, phase) {
     const normalized = value.trim().toLowerCase().replace(/-/g, "_");
     if (phase === "qa") {
@@ -51,6 +51,10 @@ export function validatePayloadShape(phase, payload) {
         requireNonPassEvidence(payload);
         return;
     }
+    if (phase === "ci_repair") {
+        validateCiRepairPayloadShape(payload);
+        return;
+    }
     if (isDebugCompletionPhase(phase)) {
         validateDebugPayloadShape(phase, payload);
         return;
@@ -97,6 +101,72 @@ export function validatePayloadShape(phase, payload) {
     requirePassingCommands(payload);
     requireSatisfiedAcceptanceCriteria(payload);
 }
+export function validateCiRepairPayloadShape(payload) {
+    requireArray(payload, "failed_checks");
+    requireNonEmptyArray(payload, "failed_checks");
+    for (const [index, failedCheck] of payload.failed_checks.entries()) {
+        requireEvidenceRecord(failedCheck, `failed_checks[${index}]`);
+        const record = failedCheck;
+        requireNonEmptyStringRecord(record, "name", `failed_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "provider_state", `failed_checks[${index}].`);
+    }
+    requireObject(payload, "root_cause");
+    const rootCause = requiredRecord(payload, "root_cause");
+    requireNonEmptyStringRecord(rootCause, "classification", "root_cause.");
+    requireNonEmptyStringRecord(rootCause, "summary", "root_cause.");
+    requireNonEmptyStringArrayRecord(rootCause, "evidence", "root_cause.");
+    requireArray(payload, "changed_files");
+    if (arrayLength(payload, "changed_files") === 0) {
+        requireObject(payload, "no_code_action");
+        const noCodeAction = requiredRecord(payload, "no_code_action");
+        requireNonEmptyStringRecord(noCodeAction, "action", "no_code_action.");
+        requireNonEmptyStringRecord(noCodeAction, "reason", "no_code_action.");
+    }
+    else {
+        for (const [index, changedFile] of payload.changed_files.entries()) {
+            requireEvidenceRecord(changedFile, `changed_files[${index}]`);
+            const record = changedFile;
+            requireNonEmptyStringRecord(record, "path", `changed_files[${index}].`);
+            requireNonEmptyStringRecord(record, "summary", `changed_files[${index}].`);
+        }
+    }
+    for (const key of ["narrow_validation", "broader_validation"]) {
+        requireArray(payload, key);
+        requireNonEmptyArray(payload, key);
+        validateQaGatePassingCommands(payload[key]);
+    }
+    requireArray(payload, "workflow_validation");
+    requireNonEmptyArray(payload, "workflow_validation");
+    for (const [index, entry] of payload.workflow_validation.entries()) {
+        requireEvidenceRecord(entry, `workflow_validation[${index}]`);
+        const record = entry;
+        requireNonEmptyStringRecord(record, "step", `workflow_validation[${index}].`);
+        requireKnownStringRecord(record, "equivalence", new Set(["supported", "substitute", "provider_only"]), `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `workflow_validation[${index}].`);
+        const equivalence = normalizedString(optionalString(record, "equivalence"));
+        if (equivalence === "provider_only") {
+            requireNonEmptyStringRecord(record, "reason", `workflow_validation[${index}].`);
+            continue;
+        }
+        requireNonEmptyStringRecord(record, "command", `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `workflow_validation[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`workflow_validation[${index}].exit_code is required for ${equivalence} evidence.`);
+        }
+        if (record.exit_code !== 0 || normalizedString(optionalString(record, "status")) !== "pass") {
+            throw new Error(`workflow_validation[${index}] must pass locally when equivalence is ${equivalence}.`);
+        }
+        if (equivalence === "substitute") {
+            requireNonEmptyStringRecord(record, "substitute", `workflow_validation[${index}].`);
+        }
+    }
+    requireArray(payload, "remaining_risks");
+    requireAllowedStatus(payload, "provider_state", ["ready_for_rerun", "rerun_requested", "checks_pending"]);
+    requireBoolean(payload, "ready_for_push");
+    if (payload.ready_for_push !== true) {
+        throw new Error("ci_repair pass requires ready_for_push: true.");
+    }
+}
 export function validateDebugPayloadShape(phase, payload) {
     if (phase === "debug_repro") {
         requireArray(payload, "repro_steps");
@@ -169,7 +239,9 @@ export function validateQaGatePayloadShape(gate, payload, status) {
         if (commands.length === 0) {
             throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
         }
-        validateQaGatePassingCommands(commands);
+        validateQaGatePassingCommands(commands, {
+            allowClassifiedNonBlockingFailures: gate === "qa_regression"
+        });
     }
     if (gate === "qa_manual_web" && status === "pass") {
         const browserChecks = qaArray(payload, "browser_checks");
@@ -179,23 +251,69 @@ export function validateQaGatePayloadShape(gate, payload, status) {
         }
     }
 }
-export function validateQaGatePassingCommands(commands) {
+export function validateQaGatePassingCommands(commands, options = {}) {
+    const issues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            issues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            issues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            issues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            issues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            issues.push(`commands[${index}].exit_code is required.`);
+            continue;
+        }
+        const passed = record.exit_code === 0 && normalizedString(record.status) === "pass";
+        if (!passed
+            && options.allowClassifiedNonBlockingFailures
+            && optionalString(record, "classification")) {
+            try {
+                validateClassifiedNonBlockingQaFailure(record, index);
+            }
+            catch (error) {
+                issues.push(error instanceof Error ? error.message : String(error));
+            }
+            continue;
         }
         if (record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+            issues.push(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
         }
         if (normalizedString(record.status) !== "pass") {
-            throw new Error(`commands[${index}].status must be pass when QA gate status is pass.`);
+            issues.push(`commands[${index}].status must be pass when QA gate status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(issues);
+}
+function validateClassifiedNonBlockingQaFailure(record, index) {
+    const classification = normalizedString(optionalString(record, "classification"));
+    if (classification !== "out_of_scope_failure" && classification !== "baseline_failure") {
+        throw new Error(`commands[${index}] is non-passing; QA regression pass requires classification out_of_scope_failure or baseline_failure with corroborating evidence.`);
+    }
+    requireNonEmptyStringRecord(record, "candidate_bug_id", `commands[${index}].`);
+    requireNonEmptyStringRecord(record, "scope_evidence", `commands[${index}].`);
+    if (record.acceptance_criteria_independent !== true) {
+        throw new Error(`commands[${index}].acceptance_criteria_independent must be true for a non-blocking QA regression failure.`);
+    }
+    if (classification === "out_of_scope_failure") {
+        requireNonEmptyStringRecord(record, "repro_command", `commands[${index}].`);
+        if (typeof record.repro_exit_code !== "number" || !Number.isFinite(record.repro_exit_code) || record.repro_exit_code === 0) {
+            throw new Error(`commands[${index}].repro_exit_code must be a non-zero number for an out-of-scope failure.`);
+        }
+        return;
+    }
+    requireNonEmptyStringRecord(record, "baseline_ref", `commands[${index}].`);
+    if (typeof record.baseline_exit_code !== "number" || !Number.isFinite(record.baseline_exit_code) || record.baseline_exit_code === 0) {
+        throw new Error(`commands[${index}].baseline_exit_code must be a non-zero number for a baseline failure.`);
+    }
+    if (record.failure_signature_match !== true) {
+        throw new Error(`commands[${index}].failure_signature_match must be true for a baseline failure.`);
+    }
 }
 export function validateArchitectPayloadShape(payload, status) {
     if (status !== "pass") {
@@ -214,18 +332,22 @@ export function validateArchitectPayloadShape(payload, status) {
         throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
     }
     const taskIds = new Set();
-    for (const task of implementationPlan.tasks) {
+    const taskIndexById = new Map();
+    for (const [taskIndex, task] of implementationPlan.tasks.entries()) {
         if (!task || typeof task !== "object" || Array.isArray(task)) {
             throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
         }
         const taskRecord = task;
         requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
         const taskId = optionalString(taskRecord, "id") ?? "";
-        if (taskIds.has(taskId)) {
-            throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
+        const firstTaskIndex = taskIndexById.get(taskId);
+        if (firstTaskIndex !== undefined) {
+            throw new Error(`implementation_plan.tasks[${taskIndex}].id duplicates implementation_plan.tasks[${firstTaskIndex}].id '${taskId}'; correction: assign the duplicate a unique stable task id, update every phase/dependency reference to that task, and resubmit forge.complete_architect_plan.`);
         }
         taskIds.add(taskId);
+        taskIndexById.set(taskId, taskIndex);
         validateArchitectTaskDevelopScope(taskRecord, taskId);
+        requireNonEmptyStringArrayRecord(taskRecord, "acceptance_criteria", `implementation_plan.tasks[${taskId}].`);
         validateArchitectVerificationScope(taskRecord, taskId);
         requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
         if (arrayLength(taskRecord, "tests") === 0) {
@@ -269,6 +391,7 @@ export function validateQaScopeRecord(scope, pathLabel) {
     }
     const surface = qaScopeStringArray(scope, "surface", pathLabel, qaScopeSurfaces);
     const requiredEvidence = qaScopeStringArray(scope, "required_evidence", pathLabel, qaScopeEvidence);
+    qaScopeStringArray(scope, "required_capabilities", pathLabel, qaScopeCapabilities);
     const notApplicable = qaScopeStringArray(scope, "not_applicable", pathLabel, qaScopeEvidence);
     const requiredSet = new Set(requiredEvidence);
     for (const evidence of notApplicable) {
@@ -611,22 +734,30 @@ export function validateQaPayloadShape(payload, status) {
             throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
         }
     }
+    const commandIssues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            commandIssues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            commandIssues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            commandIssues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            commandIssues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            commandIssues.push(`commands[${index}].exit_code is required.`);
         }
-        if (status === "pass" && record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA status is pass.`);
+        else if (status === "pass" && record.exit_code !== 0) {
+            commandIssues.push(`commands[${index}].exit_code must be 0 when QA status is pass.`);
         }
         if (status === "pass" && normalizedString(record.status) !== "pass") {
-            throw new Error(`commands[${index}].status must be pass when QA status is pass.`);
+            commandIssues.push(`commands[${index}].status must be pass when QA status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(commandIssues);
     for (const [index, browserCheck] of browserChecks.entries()) {
         requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
         const record = browserCheck;
@@ -720,5 +851,5 @@ export function validateOptionalWorkItemId(payload, expectedWorkItemId) {
         throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
     }
 }
-import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, } from "./phase-completion.helpers.js";
+import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, throwCompletionPayloadIssues, } from "./phase-completion.helpers.js";
 export * from "./phase-completion.helpers.js";

package/dist/session/pre-publication-validation.d.ts

@@ -0,0 +1,46 @@
+import type { ProviderProcessRunner } from "./provider-cli/provider-cli.process.js";
+import type { RunnerDispatchEvent } from "./session.types.js";
+export type PrePublicationProfile = "implementation" | "comment_repair" | "ci_repair" | "conflict_repair";
+interface ValidationStep {
+    readonly command: string;
+    readonly fallbackCommand?: string;
+    readonly args: readonly string[];
+    readonly fallbackArgs?: readonly string[];
+    readonly assertUnchangedPaths?: readonly string[];
+}
+interface ValidationCheck {
+    readonly id: string;
+    readonly profiles: readonly string[];
+    readonly changedPathPatterns: readonly string[];
+    readonly requiredCapability?: string;
+    readonly providerOnly?: boolean;
+    readonly steps: readonly ValidationStep[];
+}
+interface ValidationContract {
+    readonly schemaVersion: number;
+    readonly contractId: string;
+    readonly checks: readonly ValidationCheck[];
+}
+export interface PrePublicationCommandResult {
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export interface PrePublicationCommandRunner {
+    run(command: string, args: readonly string[], cwd: string, signal?: AbortSignal, environment?: Readonly<Record<string, string>>): Promise<PrePublicationCommandResult>;
+}
+export interface PrePublicationExecutionContext {
+    readonly environment?: Readonly<Record<string, string>>;
+    readonly processRunner?: ProviderProcessRunner;
+}
+export declare class PrePublicationValidator {
+    private readonly commands;
+    constructor(commands?: PrePublicationCommandRunner);
+    validate(worktreePath: string, profile: PrePublicationProfile, capabilities: ReadonlySet<string>, emit?: (event: RunnerDispatchEvent) => Promise<void>, signal?: AbortSignal, execution?: PrePublicationExecutionContext): Promise<readonly string[]>;
+    private changedPaths;
+    private runStep;
+    private runCommand;
+}
+export declare function applicableChecks(contract: ValidationContract, profile: PrePublicationProfile | "github_actions", changedPaths: readonly string[]): readonly ValidationCheck[];
+export declare function loadValidationContract(worktreePath: string): Promise<ValidationContract | null>;
+export {};

package/dist/session/pre-publication-validation.js

@@ -0,0 +1,208 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const contractRelativePath = ".forge/validation/ci-parity.v1.json";
+const requiredCheckIds = new Set([
+    "file-size-inventory",
+    "owned-suite-registration",
+    "dotnet-build-and-unit",
+    "openapi-and-generated-types",
+    "client",
+    "bridge",
+    "playwright-e2e",
+    "github-provider-policy",
+]);
+const approvedContractDigest = "014727b066b2b659b8772987650b85540f1bf70864c678187fde108a9b1d84d3";
+class ProcessPrePublicationCommandRunner {
+    async run(command, args, cwd, signal, environment) {
+        try {
+            const windowsBatch = process.platform === "win32" && (command === "npm" || command === "pnpm");
+            const executable = windowsBatch ? (process.env.ComSpec ?? "cmd.exe") : command;
+            const commandArgs = windowsBatch
+                ? ["/d", "/s", "/c", [`${command}.cmd`, ...args].map(quoteWindowsCommandArgument).join(" ")]
+                : [...args];
+            const result = await execFileAsync(executable, commandArgs, {
+                cwd,
+                encoding: "utf8",
+                maxBuffer: 4 * 1024 * 1024,
+                signal,
+                env: environment ? { ...process.env, ...environment } : process.env,
+            });
+            return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+        }
+        catch (error) {
+            const failure = error;
+            if (failure.name === "AbortError")
+                throw error;
+            if (failure.code === "ENOENT") {
+                return { exitCode: 127, stderr: `executable_not_found: ${command}` };
+            }
+            return {
+                exitCode: typeof failure.code === "number" ? failure.code : 1,
+                stdout: failure.stdout,
+                stderr: failure.stderr ?? failure.message,
+            };
+        }
+    }
+}
+function quoteWindowsCommandArgument(value) {
+    return /^[A-Za-z0-9_./:@=-]+$/u.test(value) ? value : `"${value.replaceAll('"', '""')}"`;
+}
+export class PrePublicationValidator {
+    commands;
+    constructor(commands = new ProcessPrePublicationCommandRunner()) {
+        this.commands = commands;
+    }
+    async validate(worktreePath, profile, capabilities, emit, signal, execution) {
+        const contract = await loadValidationContract(worktreePath);
+        if (contract === null) {
+            await emit?.(validationEvent("prepublication_validation_legacy_contract", "legacy-provider-validation", `This checkout predates ${contractRelativePath}; Bridge preserved legacy provider validation without source mutation.`));
+            return [];
+        }
+        const changedPaths = await this.changedPaths(worktreePath, signal, execution);
+        const selected = applicableChecks(contract, profile, changedPaths);
+        const completed = [];
+        for (const check of selected) {
+            if (check.providerOnly) {
+                await emit?.(validationEvent("prepublication_validation_provider_only", check.id, `Preserved provider-only validation '${check.id}' for the provider check run.`));
+                continue;
+            }
+            if (check.requiredCapability && !capabilities.has(check.requiredCapability)) {
+                throw new Error(`prepublication_capability_unavailable: ${check.id} requires ${check.requiredCapability}; publication is holding until a capable runner is available.`);
+            }
+            await emit?.(validationEvent("prepublication_validation_started", check.id, `Running pre-publication CI parity check '${check.id}'.`));
+            for (const step of check.steps) {
+                const result = await this.runStep(step, worktreePath, signal, execution);
+                if (result.exitCode !== 0) {
+                    const detail = `${result.stderr ?? result.stdout ?? ""}`.trim().slice(-1600);
+                    throw new Error(`prepublication_validation_failed: ${check.id} exited ${result.exitCode}${detail ? `: ${detail}` : ""}`);
+                }
+            }
+            completed.push(check.id);
+            await emit?.(validationEvent("prepublication_validation_passed", check.id, `Pre-publication CI parity check '${check.id}' passed.`));
+        }
+        return completed;
+    }
+    async changedPaths(worktreePath, signal, execution) {
+        const requests = [
+            ["diff", "--name-only", "HEAD", "--"],
+            ["diff", "--name-only", "HEAD^", "HEAD", "--"],
+            ["status", "--porcelain=v1", "--untracked-files=all"],
+        ];
+        const paths = new Set();
+        for (const args of requests) {
+            const result = await this.runCommand("git", args, worktreePath, signal, execution);
+            if (result.exitCode !== 0 && !isMissingParentRevision(args, result)) {
+                throw new Error(`prepublication_validation_failed: unable to inventory changed paths: ${result.stderr ?? result.stdout ?? "git failed"}`);
+            }
+            if (result.exitCode !== 0)
+                continue;
+            for (const line of `${result.stdout ?? ""}`.split(/\r?\n/u).filter(Boolean)) {
+                const raw = args[0] === "status" ? line.slice(3).split(" -> ").at(-1) ?? "" : line;
+                const normalized = raw.trim().replaceAll("\\", "/");
+                if (normalized)
+                    paths.add(normalized);
+            }
+        }
+        return [...paths];
+    }
+    async runStep(step, cwd, signal, execution) {
+        const before = await readValidationFiles(cwd, step.assertUnchangedPaths ?? []);
+        const result = await this.runCommand(step.command, step.args, cwd, signal, execution);
+        if (result.exitCode === 127 && step.fallbackCommand) {
+            const fallback = await this.runCommand(step.fallbackCommand, step.fallbackArgs ?? step.args, cwd, signal, execution);
+            return await assertValidationFilesUnchanged(cwd, before, fallback);
+        }
+        return await assertValidationFilesUnchanged(cwd, before, result);
+    }
+    async runCommand(command, args, cwd, signal, execution) {
+        if (execution?.processRunner) {
+            const result = await execution.processRunner.run({
+                command,
+                args,
+                cwd,
+                env: execution.environment,
+                captureOutput: true,
+            }, undefined, signal);
+            return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+        }
+        return await this.commands.run(command, args, cwd, signal, execution?.environment);
+    }
+}
+function isMissingParentRevision(args, result) {
+    if (args.length !== 5
+        || args[0] !== "diff"
+        || args[1] !== "--name-only"
+        || args[2] !== "HEAD^"
+        || args[3] !== "HEAD"
+        || args[4] !== "--") {
+        return false;
+    }
+    const detail = `${result.stderr ?? result.stdout ?? ""}`;
+    return /(?:ambiguous argument|bad revision|unknown revision|invalid object name).*HEAD\^/iu.test(detail);
+}
+async function readValidationFiles(cwd, relativePaths) {
+    const values = new Map();
+    for (const relativePath of relativePaths) {
+        values.set(relativePath, await fs.readFile(path.join(cwd, relativePath), "utf8"));
+    }
+    return values;
+}
+async function assertValidationFilesUnchanged(cwd, before, result) {
+    if (result.exitCode !== 0)
+        return result;
+    for (const [relativePath, original] of before) {
+        const current = await fs.readFile(path.join(cwd, relativePath), "utf8");
+        if (current !== original) {
+            return {
+                exitCode: 1,
+                stderr: `generated_drift: ${relativePath} changed during validation; regenerate and review it before publication.`,
+            };
+        }
+    }
+    return result;
+}
+export function applicableChecks(contract, profile, changedPaths) {
+    return contract.checks.filter(check => check.profiles.includes(profile)
+        && changedPaths.some(changedPath => check.changedPathPatterns.some(pattern => new RegExp(pattern, "u").test(changedPath))));
+}
+export async function loadValidationContract(worktreePath) {
+    let source;
+    try {
+        source = await fs.readFile(path.join(worktreePath, contractRelativePath), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const contract = JSON.parse(source);
+    const ids = new Set(contract.checks?.map(check => check.id));
+    const contractDigest = createHash("sha256")
+        .update(JSON.stringify(canonicalizeJson(contract)))
+        .digest("hex");
+    if (contract.schemaVersion !== 1
+        || contract.contractId !== "forge-ci-parity-v1"
+        || contractDigest !== approvedContractDigest
+        || requiredCheckIds.size !== ids.size
+        || [...requiredCheckIds].some(id => !ids.has(id))
+        || contract.checks.some(check => !check.id || !Array.isArray(check.steps) || !Array.isArray(check.changedPathPatterns))) {
+        throw new Error(`prepublication_contract_invalid: the Forge CI parity contract does not match the approved definition (digest ${contractDigest}, expected ${approvedContractDigest}).`);
+    }
+    return contract;
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalizeJson(record[key])]));
+    }
+    return value;
+}
+function validationEvent(eventType, checkId, content) {
+    return { role: "runner", kind: "checkpoint", content, eventType, data: JSON.stringify({ checkId, contractId: "forge-ci-parity-v1" }) };
+}

package/dist/session/provider-cli/ci-repair-readiness.d.ts

@@ -0,0 +1,16 @@
+import type { RunOnceDispatchPacket } from "../session.types.js";
+export declare const ciRepairProviderOnlySpecs: readonly ["**/bridge-dispatch.spec.ts", "**/develop-agent-run.spec.ts", "**/runner-availability.spec.ts"];
+export declare const ciRepairLocalPreflightCommands: readonly CiRepairLocalPreflightCommand[];
+export interface CiRepairLocalPreflightCommand {
+    readonly id: string;
+    readonly cwd: string;
+    readonly command: readonly string[];
+    readonly coverage: string;
+}
+export interface CiRepairReadinessResult {
+    readonly path: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly manifest: Readonly<Record<string, unknown>>;
+}
+export declare function writeCiRepairReadinessManifest(dispatch: RunOnceDispatchPacket, worktreePath: string, specPath: string, runtimeEnvironment: Readonly<Record<string, string>> | undefined): Promise<CiRepairReadinessResult>;
+export declare function assertCiRepairPreflightContract(providerOnlySpecs: readonly string[], localPreflightCommands: readonly CiRepairLocalPreflightCommand[]): void;

package/dist/session/provider-cli/ci-repair-readiness.js

@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+export const ciRepairProviderOnlySpecs = [
+    "**/bridge-dispatch.spec.ts",
+    "**/develop-agent-run.spec.ts",
+    "**/runner-availability.spec.ts",
+];
+export const ciRepairLocalPreflightCommands = [];
+export async function writeCiRepairReadinessManifest(dispatch, worktreePath, specPath, runtimeEnvironment) {
+    assertCiRepairPreflightContract(ciRepairProviderOnlySpecs, ciRepairLocalPreflightCommands);
+    const metadataRoot = path.dirname(specPath);
+    const manifestPath = path.join(metadataRoot, "ci-repair.readiness.json");
+    const workflowPath = path.join(worktreePath, ".github", "workflows", "ci.yml");
+    const browserReady = runtimeEnvironment?.FORGE_PLAYWRIGHT_BROWSER_READY === "true";
+    const providerOnlySpecsJson = JSON.stringify(ciRepairProviderOnlySpecs);
+    const apiUrl = runtimeEnvironment?.FORGE_E2E_API_URL ?? runtimeEnvironment?.FORGE_API_URL ?? null;
+    const webUrl = runtimeEnvironment?.FORGE_E2E_WEB_URL
+        ?? runtimeEnvironment?.FORGE_WEB_URL
+        ?? runtimeEnvironment?.FORGE_PLAYWRIGHT_BASE_URL
+        ?? null;
+    const environment = {
+        ...(runtimeEnvironment ?? {}),
+        ...(apiUrl ? { FORGE_E2E_API_URL: apiUrl } : {}),
+        ...(webUrl ? { FORGE_E2E_WEB_URL: webUrl } : {}),
+        FORGE_CI_REPAIR_READINESS_PATH: manifestPath,
+        FORGE_CI_REPAIR_HANDOFF_PATH: path.join(metadataRoot, "artifacts", "ci-repair.handoff.json"),
+        FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS: providerOnlySpecsJson,
+    };
+    const manifest = {
+        schema_version: 1,
+        generated_by: "forge-bridge",
+        work_item_id: dispatch.workItem.id,
+        session_id: dispatch.session.id,
+        spec: {
+            path: relativePath(worktreePath, specPath),
+            ready: await isFile(specPath),
+        },
+        handoff: {
+            path: relativePath(worktreePath, environment.FORGE_CI_REPAIR_HANDOFF_PATH),
+            completion_tool: "forge.complete_ci_repair",
+            required_before_commit_or_push: true,
+        },
+        pull_request: {
+            provider: dispatch.pullRequest?.provider ?? "unknown",
+            number: dispatch.pullRequest?.number ?? null,
+            url: dispatch.pullRequest?.url ?? null,
+            source_branch: dispatch.pullRequest?.sourceBranch ?? dispatch.cycleRun.baseBranch,
+            target_branch: dispatch.pullRequest?.targetBranch ?? dispatch.cycleRun.requestedBase,
+            check_state: dispatch.pullRequest?.checkState ?? "unknown",
+            required_checks_passed: dispatch.pullRequest?.requiredChecksPassed ?? 0,
+            required_checks_total: dispatch.pullRequest?.requiredChecksTotal ?? 0,
+            failed_job_discovery: "Inspect provider check runs and record exact job/step in the completion payload.",
+        },
+        workflow: {
+            path: relativePath(worktreePath, workflowPath),
+            ready: await isFile(workflowPath),
+            requirement: "Record the failed step and every earlier guard/drift step in workflow_validation.",
+        },
+        runtime: {
+            mode: runtimeEnvironment?.FORGE_RUNTIME_MODE ?? "unknown",
+            application_runtime_ready: Boolean(apiUrl || webUrl),
+            api_url: apiUrl,
+            web_url: webUrl,
+            playwright_config: runtimeEnvironment?.FORGE_PLAYWRIGHT_CONFIG ?? null,
+            playwright_browser_cache: runtimeEnvironment?.PLAYWRIGHT_BROWSERS_PATH ?? null,
+            playwright_browser_ready: browserReady,
+            playwright_browser_install_command: browserReady
+                ? null
+                : runtimeEnvironment?.FORGE_PLAYWRIGHT_BROWSER_INSTALL_COMMAND ?? "npx playwright install chromium",
+            attempt_database_schema: runtimeEnvironment?.FORGE_ATTEMPT_DATABASE_SCHEMA ?? null,
+            attempt_database_readiness_path: runtimeEnvironment?.FORGE_ATTEMPT_DATABASE_READINESS_PATH ?? null,
+        },
+        local_equivalence: {
+            default: "supported",
+            nested_bridge: "provider_only",
+            provider_only_specs: ciRepairProviderOnlySpecs,
+            provider_only_specs_fingerprint: `sha256:${createHash("sha256").update(providerOnlySpecsJson).digest("hex")}`,
+            local_preflight_commands: ciRepairLocalPreflightCommands,
+            reason: "A managed Forge attempt disables its hosted reconciler and cannot exercise specs that require the live Bridge/runner control plane. Those specs remain authoritative in provider CI; attempt-local unit, contract, API, and browser coverage remains supported.",
+            policy: "Run every listed local_preflight_command. Treat every provider_only_specs pattern as unavailable in the managed attempt, do not override its exclusion or weaken provider CI, and record the provider check that supplies that proof in workflow_validation.",
+        },
+    };
+    await fs.mkdir(metadataRoot, { recursive: true });
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return { path: manifestPath, environment, manifest };
+}
+export function assertCiRepairPreflightContract(providerOnlySpecs, localPreflightCommands) {
+    const providerOnlyFileNames = new Set(providerOnlySpecs.map(fileName));
+    for (const preflight of localPreflightCommands) {
+        const conflictingArgument = preflight.command.find(argument => providerOnlyFileNames.has(fileName(argument)));
+        if (conflictingArgument) {
+            throw new Error(`ci_repair_readiness_invalid: local preflight '${preflight.id}' references provider-only spec '${conflictingArgument}'.`);
+        }
+    }
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function relativePath(worktreePath, candidate) {
+    return path.relative(worktreePath, candidate).replaceAll(path.sep, "/");
+}
+function fileName(candidate) {
+    return path.posix.basename(candidate.replaceAll("\\", "/"));
+}