ai-foreman 1.7.26 → 1.7.27

package/dist/qaVerificationContract.js

@@ -4,7 +4,12 @@ const contractAjv = new Ajv({ allErrors: true });
 const candidateSchema = contractAjv.compile(qaContractCandidateV1Schema);
 const assessmentSchema = contractAjv.compile(qaSemanticAssessmentV1Schema);
 const challengeSchema = contractAjv.compile(qaChallengeReceiptV1Schema);
+function schemaIssues(errors) {
+    return (errors ?? []).map(error => `${error.instancePath || "/"} ${error.message}${error.keyword === "additionalProperties" ? `: ${String(error.params.additionalProperty)}` : error.keyword === "required" ? `: ${String(error.params.missingProperty)}` : ""}`);
+}
 import { createHash } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
 import { canonicalJson } from "./qaProtocolV2.js";
 import { depthObligations, validateDepthDecision } from "./qaPreparationPolicy.js";
 export function canonicalContractJson(value) {
@@ -47,8 +52,24 @@ export function allocateStableCheckIds(candidate) {
         counts.set(fingerprint, occurrence + 1);
         mapping.set(check.id, `check-${fingerprint.slice(0, 24)}-${occurrence}`);
     }
-    const replace = (id) => { const replacement = mapping.get(id); if (!replacement)
-        throw new Error(`Unknown proposed check reference ${id}`); return replacement; };
+    // A provider may copy a host-assigned ID from an earlier draft into a
+    // baseline or repair response.  Treat an already allocated ID as
+    // idempotently normalized; never remap it through the provider-name map.
+    const allocatedIds = new Set(mapping.values());
+    const replace = (id) => {
+        const replacement = mapping.get(id);
+        if (replacement)
+            return replacement;
+        if (allocatedIds.has(id))
+            return id;
+        throw new Error(`Unknown proposed check reference ${id}; valid proposed check IDs: ${[...proposed.keys()].join(", ")}; valid allocated check IDs: ${[...allocatedIds].join(", ")}`);
+    };
+    // Rewrite exact provider-generated check identifiers in provider-authored prose as
+    // well as structured references. Never rewrite approved requirements, paths,
+    // commands, or generic IDs such as "check" that may also be ordinary words.
+    const proseIds = [...mapping.keys()].filter(id => id.startsWith("check-")).sort((a, b) => b.length - a.length);
+    const prosePattern = proseIds.length ? new RegExp(`(^|[^A-Za-z0-9_-])(${proseIds.map(id => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?![A-Za-z0-9_-])`, "g") : undefined;
+    const rewrite = (text) => prosePattern ? text.replace(prosePattern, (_match, prefix, id) => `${prefix}${replace(id)}`) : text;
     for (const check of draft.checks) {
         check.id = replace(check.id);
         check.dependsOnChecks = check.dependsOnChecks.map(replace);
@@ -58,11 +79,49 @@ export function allocateStableCheckIds(candidate) {
     for (const observation of draft.baseline)
         if (observation.checkId)
             observation.checkId = replace(observation.checkId);
-    for (const concern of draft.unresolved)
+    for (const check of draft.checks) {
+        check.expectedBehavior = rewrite(check.expectedBehavior);
+        check.expectedEvidence = check.expectedEvidence.map(rewrite);
+        if (check.expectedBaseline)
+            check.expectedBaseline = rewrite(check.expectedBaseline);
+        if (check.applicability.predicate)
+            check.applicability.predicate = rewrite(check.applicability.predicate);
+        check.applicability.requiredEvidence = check.applicability.requiredEvidence.map(rewrite);
+        for (const method of check.verification) {
+            method.expectedOutcome = rewrite(method.expectedOutcome);
+            if (method.steps)
+                method.steps = method.steps.map(rewrite);
+        }
+    }
+    for (const observation of draft.baseline) {
+        observation.procedure = rewrite(observation.procedure);
+        observation.relevance = rewrite(observation.relevance);
+        observation.expectedTransition = rewrite(observation.expectedTransition);
+        if (observation.predicateEvidence)
+            observation.predicateEvidence = observation.predicateEvidence.map(rewrite);
+    }
+    for (const evidence of draft.preparationEvidence)
+        evidence.analysis = rewrite(evidence.analysis);
+    for (const concern of draft.unresolved) {
         concern.checkIds = concern.checkIds.map(replace);
+        concern.reason = rewrite(concern.reason);
+        concern.nextAction = rewrite(concern.nextAction);
+    }
     return draft;
 }
 export function inventoryDigest(requirements) { return contractDigest("qa-requirement-inventory", requirements); }
+/** Derive a missing baseline binding only from an explicit, unique check prerequisite reference. */
+export function bindUniqueBaselineCheckIds(candidate) {
+    const draft = structuredClone(candidate);
+    for (const observation of draft.baseline) {
+        if (observation.checkId)
+            continue;
+        const matches = draft.checks.filter(check => check.prerequisiteRefs.includes(observation.id));
+        if (matches.length === 1)
+            observation.checkId = matches[0].id;
+    }
+    return draft;
+}
 export function authoritativeInventory(ticket, checklist, inputs) {
     const result = [];
     for (const [kind, entries] of [["acceptance", ticket.acceptance], ["required_tests", ticket.required_tests], ["checklist", checklist]]) {
@@ -84,16 +143,67 @@ export function parsePreparationArtifact(text, tag, maximum = 2 * 1024 * 1024) {
     if (Buffer.byteLength(text) > maximum)
         throw new Error("QA preparation response exceeds size limit");
     const start = `${tag}_START`, end = `${tag}_END`;
-    if (text.split(start).length !== 2 || text.split(end).length !== 2)
+    // Marker names can appear inline in provider prose or in a quoted repair
+    // instruction. Only a standalone marker line is an envelope boundary.
+    // This keeps the parser strict about malformed envelopes without treating
+    // explanatory text as a second/truncated artifact.
+    const markerOffsets = (marker) => {
+        const offsets = [];
+        const pattern = new RegExp(`^[ \\t]*${marker}[ \\t]*$`, "gm");
+        for (let match = pattern.exec(text); match; match = pattern.exec(text))
+            offsets.push(match.index);
+        return offsets;
+    };
+    const starts = markerOffsets(start), ends = markerOffsets(end);
+    if (!starts.length || starts.length !== ends.length)
         throw new Error(`Expected exactly one ${tag} artifact`);
-    const from = text.indexOf(start) + start.length, to = text.indexOf(end);
-    if (to < from)
-        throw new Error("Malformed preparation artifact envelope");
-    return JSON.parse(text.slice(from, to).trim());
+    const artifacts = starts.map((at, index) => {
+        const from = at + start.length, to = ends[index];
+        if (to < from)
+            throw new Error("Malformed preparation artifact envelope");
+        return text.slice(from, to).trim();
+    });
+    if (artifacts.length > 1) {
+        const normalized = artifacts.map(artifact => canonicalContractJson(JSON.parse(artifact)));
+        if (normalized.some(artifact => artifact !== normalized[0]))
+            throw new Error(`Expected exactly one unambiguous ${tag} artifact`);
+    }
+    return JSON.parse(artifacts[0]);
+}
+/** Capture safe absolute snapshot paths before the disposable snapshot is removed. */
+export function mapSnapshotWorkingDirectories(text, snapshotPath) {
+    const result = {};
+    try {
+        const draft = parsePreparationArtifact(text, "RAFI_QA_CANDIDATE");
+        const root = realpathSync(snapshotPath);
+        for (const check of draft.checks ?? [])
+            for (const method of check.verification ?? []) {
+                if (typeof method.cwd !== "string" || !isAbsolute(method.cwd))
+                    continue;
+                try {
+                    const target = realpathSync(method.cwd);
+                    const path = relative(root, target);
+                    if (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path) && statSync(target).isDirectory())
+                        result[method.cwd] = path || ".";
+                }
+                catch { /* Missing or inaccessible paths remain invalid. */ }
+            }
+    }
+    catch { /* Parsing and validation report malformed provider responses. */ }
+    return result;
+}
+/** Providers sometimes repeat an absolute disposable-snapshot path from an earlier
+ * conversation.  That path is host-owned and must not enter the durable contract;
+ * normalize only the bounded QA snapshot naming convention to stable relative
+ * locations before parsing the provider draft. */
+export function normalizeSnapshotPaths(text) {
+    return text
+        .replace(/(?:\/(?:private\/var|var|tmp)(?:\/[^\s"']+)*\/)?rafi-qa-[^\/\s"']+\/scratch(?=[\/"'\s}]|$)/g, "scratch")
+        .replace(/(?:\/(?:private\/var|var|tmp)(?:\/[^\s"']+)*\/)?rafi-qa-[^\/\s"']+(?=[\/"'\s}]|$)/g, ".");
 }
 export function validateCandidate(candidate, inventory, resolveEquivalent) {
     if (!candidateSchema(candidatePayload(candidate)))
-        return (candidateSchema.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+        return schemaIssues(candidateSchema.errors);
     const issues = validateDepthDecision(candidate.depthDecision);
     if (candidate.version !== 1 || !candidate.contractId || !candidate.runId || !candidate.workId || !candidate.admissionDigest || !Number.isSafeInteger(candidate.revision) || candidate.revision < 1)
         issues.push("Invalid contract identity");
@@ -102,6 +212,10 @@ export function validateCandidate(candidate, inventory, resolveEquivalent) {
             issues.push(`Missing ${field} array`);
     if (issues.length)
         return issues;
+    if (candidate.documentation && (!Array.isArray(candidate.documentation.targets) || !Array.isArray(candidate.documentation.criteria)))
+        issues.push("Invalid documentation policy");
+    if (candidate.documentation?.required && (!candidate.documentation.targets.length || !candidate.documentation.criteria.length))
+        issues.push("Documentation policy requires explicit targets and criteria");
     const unique = (items, label) => {
         const ids = new Set();
         for (const item of items) {
@@ -128,9 +242,12 @@ export function validateCandidate(candidate, inventory, resolveEquivalent) {
         const rows = candidate.coverage.filter(row => row.requirementId === req.id);
         if (rows.length !== 1 || !rows[0].checkIds.length || rows[0].dispositionRef)
             issues.push(`Requirement lacks concrete coverage ${req.id}`);
-        for (const id of rows[0]?.checkIds ?? [])
-            if (!checks.has(id) || !candidate.checks.find(check => check.id === id)?.requirementRefs.includes(req.id))
-                issues.push(`Invalid coverage ${req.id}/${id}`);
+        for (const id of rows[0]?.checkIds ?? []) {
+            if (!checks.has(id))
+                issues.push(`Invalid coverage ${req.id}/${id}: unknown check ID`);
+            else if (!candidate.checks.find(check => check.id === id)?.requirementRefs.includes(req.id))
+                issues.push(`Invalid coverage ${req.id}/${id}: that check's requirementRefs must include ${req.id}`);
+        }
         if (req.obligation === "mandatory" && !(rows[0]?.checkIds ?? []).some(id => candidate.checks.find(check => check.id === id)?.obligation === "mandatory"))
             issues.push(`Mandatory requirement only covered by advisory checks ${req.id}`);
     }
@@ -186,14 +303,16 @@ export function validateCandidate(candidate, inventory, resolveEquivalent) {
     for (const obligation of depthObligations(candidate.depthDecision.level))
         if (!candidate.preparationEvidence.some(evidence => evidence.obligation === obligation && evidence.analysis?.trim() && evidence.evidenceDigest && evidence.operationId && evidence.sessionId && evidence.references.length))
             issues.push(`Missing depth evidence ${obligation}`);
-    if (candidate.unresolved.some(concern => concern.material))
-        issues.push("Unresolved material concern");
+    for (const concern of candidate.unresolved.filter(item => item.material).slice(0, 5))
+        issues.push(`Unresolved material concern: ${concern.reason.slice(0, 500)}${concern.nextAction ? `; next action: ${concern.nextAction.slice(0, 300)}` : ""}`);
+    if (candidate.unresolved.filter(item => item.material).length > 5)
+        issues.push("Additional material concerns are retained in the preparation record");
     return [...new Set(issues)];
 }
 export function validateAssessment(candidate, assessment, authorSessionId) {
     const validator = "approach" in assessment ? challengeSchema : assessmentSchema;
     if (!validator(assessment))
-        return (validator.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+        return schemaIssues(validator.errors);
     const issues = [];
     if (assessment.version !== 1 || assessment.draftPayloadDigest !== draftDigest(candidate) || assessment.inventoryDigest !== inventoryDigest(candidate.requirements) || assessment.policyVersion !== candidate.depthDecision.policyVersion)
         issues.push("Assessment does not bind the exact draft/inventory/policy");
@@ -205,8 +324,14 @@ export function validateAssessment(candidate, assessment, authorSessionId) {
     for (const obligation of depthObligations(candidate.depthDecision.level))
         if (!assessment.assessedObligations?.includes(obligation))
             issues.push(`Obligation not assessed ${obligation}`);
-    if (!Array.isArray(assessment.concerns) || assessment.concerns.some(concern => concern.material))
+    if (!Array.isArray(assessment.concerns))
         issues.push("Semantic concerns unresolved");
+    else {
+        for (const concern of assessment.concerns.filter(item => item.material).slice(0, 5))
+            issues.push(`Semantic concerns unresolved: ${concern.reason.slice(0, 500)}${concern.nextAction ? `; next action: ${concern.nextAction.slice(0, 300)}` : ""}`);
+        if (assessment.concerns.filter(item => item.material).length > 5)
+            issues.push("Additional semantic concerns are retained in the preparation record");
+    }
     return issues;
 }
 export function assembleContract(candidate, inventory, assessment, authorSessionId, challenge, resolveEquivalent) {
@@ -231,6 +356,7 @@ export function verifyContractDigest(contract) {
         throw new Error("Corrupt verification contract");
 }
 export function renderVerificationContract(contract) {
-    return [`Verification contract ${contract.contractId}, revision ${contract.revision}`, `Work: ${contract.workId}; digest: ${contract.contentDigest}`, `Depth: ${contract.depthDecision.level}: ${contract.depthDecision.rationale}`,
+    const documentation = contract.documentation ?? { required: false, targets: [], criteria: [] };
+    return [`Verification contract ${contract.contractId}, revision ${contract.revision}`, `Work: ${contract.workId}; digest: ${contract.contentDigest}`, `Depth: ${contract.depthDecision.level}: ${contract.depthDecision.rationale}`, `Documentation required: ${documentation.required ? "yes" : "no"}${documentation.required ? `; targets: ${documentation.targets.join(", ")}; criteria: ${documentation.criteria.join("; ")}` : ""}`,
         ...contract.checks.map(check => [`${check.id}: ${check.obligation}; ${check.timing}; ${check.applicability.kind}`, check.expectedBehavior, check.applicability.predicate ?? "Always applicable", `Evidence: ${check.expectedEvidence.join("; ")}`, ...check.verification.map(method => JSON.stringify(method))].join("\n"))].join("\n\n");
 }

package/dist/sources/sourceRegistry.js

@@ -8,6 +8,7 @@ import { parse, stringify } from "yaml";
 import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
 import { withActivityPhase } from "../activity.js";
+import { structuredSourceRequestSchema, zodIssues } from "rafi-spec";
 const execFileAsync = promisify(execFile);
 export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
 export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
@@ -156,14 +157,24 @@ export function extractSourceRequests(output) {
             throw new Error(`source request is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
         }
         const values = Array.isArray(value) ? value : [value];
-        for (const item of values)
-            if (item && typeof item === "object" && !Array.isArray(item))
-                requests.push(item);
+        for (const item of values) {
+            const parsed = structuredSourceRequestSchema.safeParse(item);
+            if (!parsed.success)
+                throw new Error(`source request contract validation failed:\n${zodIssues(parsed.error).map((issue) => `- ${issue}`).join("\n")}`);
+            requests.push(parsed.data);
+        }
         cursor = end + SOURCE_REQUEST_END.length;
     }
     // Compatibility with the original single-line protocol. Preserve the complete remainder.
-    for (const match of output.matchAll(/^SOURCE_REQUEST:\s*(.+)$/gim))
-        requests.push({ description: match[1].trim() });
+    for (const match of output.matchAll(/^SOURCE_REQUEST:\s*(.+)$/gim)) {
+        const legacy = structuredSourceRequestSchema.safeParse({ description: match[1].trim() });
+        // Legacy lines are intentionally converted into the same typed contract;
+        // they remain description-only pending requests after registration, but
+        // they no longer bypass shape validation.
+        if (!legacy.success)
+            throw new Error(`legacy source request contract validation failed:\n${zodIssues(legacy.error).map((issue) => `- ${issue}`).join("\n")}`);
+        requests.push(legacy.data);
+    }
     return requests;
 }
 /** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */

package/dist/stateTransfer.d.ts

@@ -41,6 +41,20 @@ export interface StateInspectResult {
     manifest: StateBundleManifestV1;
     valid: boolean;
 }
+export interface BuildProjectIdentityStatus {
+    currentRoot: string;
+    storedRoot?: string;
+    matches: boolean;
+    recoveryDatabasePresent: boolean;
+}
+/** Read the immutable root binding without opening a normal workflow writer. */
+export declare function inspectBuildProjectIdentity(projectDir: string): BuildProjectIdentityStatus;
+/**
+ * Explicitly adopt copied local build state at its new canonical project root.
+ * This is intentionally separate from ordinary workflow writers and records an
+ * immutable audit row before changing the binding.
+ */
+export declare function rebindBuildProjectIdentity(projectDir: string): BuildProjectIdentityStatus;
 export declare function exportStateBundle(projectDir: string, outputFile: string, opts?: {
     now?: Date;
     packageVersion?: string;

package/dist/stateTransfer.js

@@ -17,6 +17,57 @@ import { OBSERVABILITY_DB_FILE } from "./observability.js";
 export const STATE_BUNDLE_FORMAT = "rafi-state-bundle.v1";
 export const STATE_MANIFEST_PATH = "rafi-state-manifest.v1.json";
 export const STATE_LINEAGE_PATH = ".rafi/state-transfer.json";
+/** Read the immutable root binding without opening a normal workflow writer. */
+export function inspectBuildProjectIdentity(projectDir) {
+    const root = realpathSync(projectDir);
+    const path = join(root, WORKFLOW_DB_FILE);
+    if (!existsSync(path))
+        return { currentRoot: root, matches: true, recoveryDatabasePresent: false };
+    const db = new Database(path, { readonly: true, fileMustExist: true });
+    try {
+        if (!tableExists(db, "build_project_identity"))
+            return { currentRoot: root, matches: true, recoveryDatabasePresent: true };
+        const row = db.prepare("SELECT canonical_root FROM build_project_identity WHERE singleton=1").get();
+        if (!row)
+            return { currentRoot: root, matches: true, recoveryDatabasePresent: true };
+        return { currentRoot: root, storedRoot: row.canonical_root, matches: row.canonical_root === root, recoveryDatabasePresent: true };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Explicitly adopt copied local build state at its new canonical project root.
+ * This is intentionally separate from ordinary workflow writers and records an
+ * immutable audit row before changing the binding.
+ */
+export function rebindBuildProjectIdentity(projectDir) {
+    const status = inspectBuildProjectIdentity(projectDir);
+    if (!status.recoveryDatabasePresent || !status.storedRoot || status.matches)
+        return status;
+    assertNoLiveLease(status.currentRoot, "rebind copied local state");
+    const path = join(status.currentRoot, WORKFLOW_DB_FILE);
+    const db = new Database(path, { fileMustExist: true });
+    try {
+        db.function("rafi_writer_protocol", () => 4);
+        db.transaction(() => {
+            db.exec("CREATE TABLE IF NOT EXISTS build_project_rebindings(sequence INTEGER PRIMARY KEY AUTOINCREMENT,project_id TEXT NOT NULL,previous_root TEXT NOT NULL,new_root TEXT NOT NULL,rebound_at TEXT NOT NULL)");
+            for (const action of ["INSERT", "UPDATE", "DELETE"])
+                db.exec(`CREATE TRIGGER IF NOT EXISTS rebinding_protocol_${action} BEFORE ${action} ON build_project_rebindings BEGIN SELECT CASE WHEN rafi_writer_protocol()<>4 THEN RAISE(ABORT,'incompatible project rebinding writer') END; END`);
+            for (const action of ["UPDATE", "DELETE"])
+                db.exec(`CREATE TRIGGER IF NOT EXISTS rebinding_immutable_${action} BEFORE ${action} ON build_project_rebindings BEGIN SELECT RAISE(ABORT,'Project rebinding history is immutable'); END`);
+            const identity = db.prepare("SELECT project_id,canonical_root FROM build_project_identity WHERE singleton=1").get();
+            if (identity.canonical_root !== status.storedRoot)
+                throw new Error("project identity changed before rebinding; inspect and retry");
+            db.prepare("INSERT INTO build_project_rebindings(project_id,previous_root,new_root,rebound_at) VALUES(?,?,?,?)").run(identity.project_id, identity.canonical_root, status.currentRoot, new Date().toISOString());
+            db.prepare("UPDATE build_project_identity SET canonical_root=? WHERE singleton=1").run(status.currentRoot);
+        })();
+        return inspectBuildProjectIdentity(status.currentRoot);
+    }
+    finally {
+        db.close();
+    }
+}
 const TRANSFER_ROOTS = [
     ".tickets/tickets.yaml",
     ".tickets/config.yaml",

package/dist/statusReporter.d.ts

@@ -76,6 +76,14 @@ export declare class RoleStatusAdapter implements BuilderAdapter {
     private readonly onClose;
     readonly agent: "claude" | "codex";
     constructor(adapter: BuilderAdapter, onActive: (adapter: BuilderAdapter) => void, onClose: () => void);
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
+    enableContractEnforcement(): void;
+    contractCompactionSequence(): number;
+    acceptContractDelivery(sequence: number): void;
+    configureQaContractReminder(reminder: string, onEvent?: Parameters<NonNullable<BuilderAdapter["configureQaContractReminder"]>>[1]): void;
     sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;

package/dist/statusReporter.js

@@ -171,6 +171,11 @@ export class RoleStatusAdapter {
         this.onClose = onClose;
         this.agent = adapter.agent;
     }
+    contractCapabilities() { return this.adapter.contractCapabilities?.() ?? { sameSessionAcceptance: false, nativeCompactionBarrier: false }; }
+    enableContractEnforcement() { this.adapter.enableContractEnforcement?.(); }
+    contractCompactionSequence() { return this.adapter.contractCompactionSequence?.() ?? 0; }
+    acceptContractDelivery(sequence) { this.adapter.acceptContractDelivery?.(sequence); }
+    configureQaContractReminder(reminder, onEvent) { this.adapter.configureQaContractReminder?.(reminder, onEvent); }
     async sendTurn(text, policy) { this.onActive(this.adapter); return this.adapter.sendTurn(text, policy); }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }