ai-foreman 1.7.28 → 2.0.0

package/dist/qaHostTransformation.d.ts

@@ -0,0 +1,26 @@
+export type QaHostTransformationRule = "assessment-host-bindings-v1" | "depth-host-bindings-v1" | "draft-host-bindings-v1";
+export interface QaHostTransformationV1 {
+    version: 1;
+    ruleVersion: QaHostTransformationRule;
+    operation: string;
+    tupleDigest: string;
+    inputDigest: string;
+    outputDigest: string;
+    authorityClass: "host-binding-and-observation";
+    justification: string;
+    effects: Array<{
+        path: string;
+        beforeDigest: string;
+        afterDigest: string;
+    }>;
+}
+/** Records only approved host effects; provider/user requirements remain immutable. */
+export declare function qaHostTransformation(input: {
+    rule: QaHostTransformationRule;
+    operation: string;
+    tupleDigest: string;
+    before: unknown;
+    after: unknown;
+    workspacePaths?: Record<string, string>;
+}): QaHostTransformationV1;
+export declare function verifyQaHostTransformation(record: QaHostTransformationV1, before: unknown, after: unknown, workspacePaths?: Record<string, string>): void;

package/dist/qaHostTransformation.js

@@ -0,0 +1,100 @@
+import { canonicalJson, structuredDigest } from "rafi-spec";
+const hashValue = (value, present) => structuredDigest({ present, ...(present ? { value } : {}) });
+/** Records only approved host effects; provider/user requirements remain immutable. */
+export function qaHostTransformation(input) {
+    if (!["assessment-host-bindings-v1", "depth-host-bindings-v1", "draft-host-bindings-v1"].includes(input.rule))
+        throw new Error("Unknown QA host transformation rule");
+    if (!/^[a-f0-9]{64}$/.test(input.tupleDigest) || !input.operation)
+        throw new Error("QA transformation requires native tuple provenance");
+    const effects = [];
+    const original = input.before, transformed = input.after;
+    const ids = new Map();
+    if (input.rule === "draft-host-bindings-v1") {
+        if (transformed.checks.length < original.checks.length)
+            throw new Error("QA transformation cannot remove provider checks");
+        original.checks.forEach((check, index) => ids.set(check.id, transformed.checks[index].id));
+    }
+    const labelIds = [...ids.keys()].filter(id => id.startsWith("check-")).sort((a, b) => b.length - a.length);
+    const labelPattern = labelIds.length ? new RegExp(`(^|[^A-Za-z0-9_-])(${labelIds.map(id => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?![A-Za-z0-9_-])`, "g") : undefined;
+    const relabel = (value) => typeof value === "string" && labelPattern
+        ? value.replace(labelPattern, (_match, prefix, id) => `${prefix}${ids.get(id)}`) : value;
+    const walk = (before, after, path, beforePresent = true, afterPresent = true) => {
+        if (beforePresent === afterPresent && canonicalJson(before ?? null) === canonicalJson(after ?? null))
+            return;
+        if (input.rule === "draft-host-bindings-v1" && path === "baseline" && Array.isArray(before) && Array.isArray(after)) {
+            for (const prior of before)
+                if (!after.some(row => row.id === prior.id))
+                    throw new Error("QA transformation cannot remove provider observations");
+            for (const [index, row] of after.entries()) {
+                const prior = before.find(item => item.id === row.id);
+                walk(prior, row, `baseline.${index}`, prior !== undefined, true);
+            }
+            return;
+        }
+        if (before && after && typeof before === "object" && typeof after === "object" && Array.isArray(before) === Array.isArray(after)) {
+            for (const key of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort())
+                walk(before[key], after[key], path ? `${path}.${key}` : key, Object.hasOwn(before, key), Object.hasOwn(after, key));
+            return;
+        }
+        const assessment = /^(draftPayloadDigest|inventoryDigest|policyVersion|authorSessionId|sessionId|operationId)$/.test(path);
+        const depth = /^(plannerOperationId|plannerIdentity|minimumReasons(?:\.\d+)?)$/.test(path);
+        let draft = false;
+        if (input.rule === "draft-host-bindings-v1") {
+            const check = /^checks\.(\d+)\.(.+)$/.exec(path);
+            const originalCheck = check && original.checks[Number(check[1])];
+            const idReference = /^(checks\.\d+\.(id|dependsOnChecks\.\d+)|coverage\.\d+\.checkIds\.\d+|unresolved\.\d+\.checkIds\.\d+)$/.test(path);
+            draft = idReference && ids.get(before) === after;
+            if (check?.[2] === "obligation" && originalCheck && after === "mandatory") {
+                draft = original.requirements.some((requirement) => requirement.obligation === "mandatory" &&
+                    original.coverage.some((row) => row.requirementId === requirement.id && row.checkIds.includes(originalCheck.id)));
+            }
+            if (check && /^requirementRefs\.\d+$/.test(check[2]) && !beforePresent && originalCheck) {
+                draft = original.coverage.some((row) => row.requirementId === after && row.checkIds.includes(originalCheck.id));
+            }
+            if (/^checks\.\d+\.hostKind$/.test(path) && !beforePresent)
+                draft = after === "source-scope" || after === "graph-maintenance";
+            if (/^checks\.\d+$/.test(path) && !beforePresent)
+                draft = after && (after.hostKind === "source-scope" || after.hostKind === "graph-maintenance") &&
+                    after.origin === "invariant" && after.obligation === "mandatory" && after.requirementRefs.every((id) => original.requirements.some((requirement) => requirement.id === id));
+            if (/^baseline\.\d+$/.test(path) && !beforePresent)
+                draft = after && /^[a-f0-9]{64}$/.test(after.evidenceDigest) && typeof after.observedAt === "string";
+            if (/^baseline\.\d+\.(sourceDigest|observedAt|phase|evidenceDigest)$/.test(path))
+                draft = true;
+            if (/^baseline\.\d+\.checkId$/.test(path)) {
+                const row = transformed.baseline[Number(path.split(".")[1])];
+                const checks = transformed.checks.filter((item) => item.prerequisiteRefs.includes(row.id));
+                draft = ids.get(before) === after || checks.length === 1 && checks[0].id === after;
+            }
+            if (/^preparationEvidence\.\d+\.(operationId|sessionId|graphReceiptRefs(?:\.\d+)?|evidenceDigest)$/.test(path) ||
+                /^preparationEvidence\.\d+\.references\.\d+\.digest$/.test(path))
+                draft = true;
+            if (/^(checks\.\d+\.verification\.\d+\.cwd|preparationEvidence\.\d+\.references\.\d+\.path)$/.test(path))
+                draft = typeof before === "string" && input.workspacePaths?.[before] === after;
+            // The only permitted prose edit substitutes exact provider check identifiers.
+            if (/^(checks\.\d+\.(expectedBehavior|expectedEvidence\.\d+|expectedBaseline|applicability\.(predicate|requiredEvidence\.\d+)|verification\.\d+\.(expectedOutcome|steps\.\d+))|baseline\.\d+\.(procedure|relevance|expectedTransition|predicateEvidence\.\d+)|preparationEvidence\.\d+\.analysis|unresolved\.\d+\.(reason|nextAction))$/.test(path) &&
+                typeof before === "string" && before !== after && relabel(before) === after)
+                draft = true;
+        }
+        if (!(input.rule === "assessment-host-bindings-v1" ? assessment : input.rule === "depth-host-bindings-v1" ? depth : draft))
+            throw new Error(`QA host transformation cannot change provider requirements or semantic fields: ${path}`);
+        effects.push({ path, beforeDigest: hashValue(before, beforePresent), afterDigest: hashValue(after, afterPresent) });
+        if (effects.length > 10000)
+            throw new Error("QA host transformation exceeds effect budget");
+    };
+    walk(input.before, input.after, "");
+    if (input.rule === "depth-host-bindings-v1") {
+        const before = input.before;
+        const after = input.after;
+        const expected = [...before.minimumReasons, ...before.riskFactors.map(risk => risk.category).filter(category => !before.minimumReasons.includes(category))];
+        if (canonicalJson(expected) !== canonicalJson(after.minimumReasons))
+            throw new Error("Depth labels must be exactly derivable from provider risk factors");
+    }
+    return { version: 1, ruleVersion: input.rule, operation: input.operation, tupleDigest: input.tupleDigest,
+        inputDigest: structuredDigest(input.before), outputDigest: structuredDigest(input.after), effects,
+        authorityClass: "host-binding-and-observation", justification: "Bind native dispatch identities and retained host observations; preserve provider/user requirements" };
+}
+export function verifyQaHostTransformation(record, before, after, workspacePaths) {
+    const expected = qaHostTransformation({ rule: record.ruleVersion, operation: record.operation, tupleDigest: record.tupleDigest, before, after, workspacePaths });
+    if (canonicalJson(expected) !== canonicalJson(record))
+        throw new Error("QA host transformation replay mismatch");
+}

package/dist/qaPreparation.d.ts

@@ -1,6 +1,12 @@
+import { type OutputContract, type SelectedDispatchTupleV2, type StructuredResponse } from "rafi-spec";
 import type { QaContractCandidateV1, QaSemanticAssessmentV1, RequirementRef, QaVerificationContractV1 } from "rafi-spec";
 import type { QaPreparationStore, LogicalPreparationBudget } from "./qaPreparationStore.js";
+/** Compatibility re-exports; canonical contract ownership is rafi-spec. */
+export { draftOutput, assessmentOutput, challengeOutput, depthOutput } from "rafi-spec";
 export interface PreparationProviderResult {
+    output?: OutputContract;
+    structured?: StructuredResponse;
+    selectedDispatch?: SelectedDispatchTupleV2;
     operationId?: string;
     text: string;
     sessionId: string;
@@ -14,7 +20,7 @@ export interface PreparationDependencies {
     /** Provider-specific wording is allowed; contract ownership is not. */
     provider?: "claude" | "codex";
     /** Each dispatch is a fresh, confined conversation, with a persisted reservation. */
-    dispatch(phase: "planner" | "prepare" | "assess" | "challenge" | "repair", instruction: string, operationId: string, remainingMs: number): Promise<PreparationProviderResult>;
+    dispatch(phase: "planner" | "prepare" | "assess" | "challenge" | "repair", instruction: string, operationId: string, remainingMs: number, output: OutputContract): Promise<PreparationProviderResult>;
     inputsCurrent(candidate: QaContractCandidateV1): boolean;
     normalizeDraft?(draft: QaContractCandidateV1, response: PreparationProviderResult): QaContractCandidateV1;
     hostFacts?: string;
@@ -29,22 +35,11 @@ export type PreparationOutcome = {
 };
 export declare const FILE_SCOPE_GUIDANCE = "File lists in plans and tickets, including likely_files and generated file-only diff expectations, are estimates of implementation, not exhaustive boundaries. Different named files or an extra relevant file do not by themselves create a material conflict or block the build. Retain and assess every original requirement; for file-list checks verify that changes serve the approved work rather than requiring an exact file list or a pre-edit snapshot proving no other files changed. Rafi owns tracker lifecycle updates. Generated instructions to mark a ticket done in a document are bookkeeping, not a Builder acceptance criterion or a material conflict; do not require the Builder to perform them, and do not require the host to amend the plan before building. Do not disregard explicit user-established security, privacy, access, or other safety restrictions, or expand the approved product functionality. Report genuine substantive or safety conflicts.";
 export declare const ROLLBACK_VERIFICATION_GUIDANCE = "When an original requirement explicitly asks to verify that rollback restores behavior, specify concrete future verification evidence rather than only inspecting rollback prose. A rollback plan alone does not require a rollback execution or mutation-testing rehearsal. For an npm test project where current uncommitted product changes represent the change to rehearse, the Builder may run rafi qa-rehearse-rollback alone from the project root; it runs npm test before and after reverting a synthetic commit of all uncommitted product changes in an independent temporary repository. It also runs git diff --exit-code against the captured pre-change HEAD after the revert and tests; success proves the tracked files match that baseline. For a requirement that a particular string be absent after rollback, inspecting its absence in the captured baseline plus that successful whole-tree comparison is concrete evidence of absence in the reverted tracked file. The rehearsal cannot use installed dependencies or symbolic links and does not prove ticket isolation or that an actual existing ticket commit was reverted. Assess whether this evidence satisfies the original requirement; do not claim it does when the original explicitly requires the actual ticket commit. Do not assume copying files to external scratch, arbitrary scripts or mutation experiments are allowed. If actual rollback execution is explicitly required but no permitted method satisfies it, report the limitation. Never perform destructive rollback in the source workspace or claim a rehearsal has already happened.";
-export declare const EXECUTABLE_CHECK_GUIDANCE = "Choose verification procedures compatible with the Builder's project permissions and workspace. Documentation is disabled unless the host-bound contract documentation.required is true. When it is false, do not invent documentation checks merely because a docs directory or API-looking path exists; an absent documentation surface is not a failure. When it is true, use only the contract's exact targets and criteria, and define an actionable absent-target outcome. Do not invent mandatory inline node -e or node --eval commands: the Builder policy may refuse them. For a JavaScript behavior or export check, prefer a project-local test file executed with the project's existing test command, or a permitted node --test invocation. Do not invent a mandatory test-first RED phase or other historical sequence merely because a plan requires tests before and after implementation: a passing baseline test is not a failing new test. When an original requirement actually requires a historical sequence, preserve it and specify concrete independently reviewable evidence paths or retained host events for each required step; a generic statement that sequencing evidence exists is not actionable, and a later passing test does not prove past events. If the project policy makes raw stdout redirection or scratch-log creation unavailable, do not turn log-file capture into a blocker: use the retained bounded tool output and host events instead, and never cite a scratch path unless that exact file was successfully created and inspected. The independent QA snapshot may have a detached HEAD even when the Builder source workspace is on a branch; do not use its branch name to infer the Builder source branch. Diff and scope checks must compare the current snapshot with the captured pre-implementation baseline, not blindly with repository HEAD: previously approved or completed ticket changes are part of that baseline and must not be reported as new work. A scope check must first enumerate every changed path outside the explicit bookkeeping/evidence exclusions, then compare that complete host-observed set with the approved product/ticket scope; do not pre-filter the list to expected filenames, because that would hide accidental extra product edits. Bounded evidence-only paths such as scratch/ are not product scope and must be excluded from product-path scope checks while their retained evidence remains subject to QA review. For a current-branch multi-ticket build, do not invent a mandatory branch-alone execution check merely to prove ticket independence; use baseline-aware source/test inspection and the permitted project tests unless the original requirement explicitly requires an actual isolated execution. For additive tickets in a current-branch multi-ticket build, \u201Cacceptable on its own\u201D is satisfied by showing that each ticket's own tests import and exercise only its own feature, pass with the shared baseline and required project tests, and do not depend on the sibling feature; do not require removing another additive feature or perform a destructive rollback experiment unless the approved requirement explicitly requires absence testing or an isolated branch. Preserve explicitly requested procedures and substantive requirements; if a required procedure cannot be run, identify the limitation rather than claiming it was executed. Independently assess whether proposed evidence actually tests the required behavior.";
+export declare const EXECUTABLE_CHECK_GUIDANCE = "Choose verification procedures compatible with the Builder's project permissions and workspace. Keep applicability and verification instructions consistent: an unconditional check must always be reported applicable, including a check whose predicate confirms an absent feature, disabled documentation, or an unrequested skill. For such a check require passed evidence of the absence, never an instruction to report the check not-applicable. If execution itself depends on a condition, encode conditional applicability with a concrete predicate and evidence. The independent assessor must flag contradictory applicability instructions before readiness. Documentation is disabled unless the host-bound contract documentation.required is true. When it is false, do not invent documentation checks merely because a docs directory or API-looking path exists; an absent documentation surface is not a failure. When it is true, use only the contract's exact targets and criteria, and define an actionable absent-target outcome. Do not invent mandatory inline node -e or node --eval commands: the Builder policy may refuse them. For a JavaScript behavior or export check, prefer a project-local test file executed with the project's existing test command, or a permitted node --test invocation. Do not invent a mandatory test-first RED phase or other historical sequence merely because a plan requires tests before and after implementation: a passing baseline test is not a failing new test. When an original requirement actually requires a historical sequence, preserve it and specify concrete independently reviewable evidence paths or retained host events for each required step; a generic statement that sequencing evidence exists is not actionable, and a later passing test does not prove past events. If the project policy makes raw stdout redirection or scratch-log creation unavailable, do not turn log-file capture into a blocker: use the retained bounded tool output and host events instead, and never cite a scratch path unless that exact file was successfully created and inspected. The independent QA snapshot may have a detached HEAD even when the Builder source workspace is on a branch; do not use its branch name to infer the Builder source branch. Diff and scope checks must compare the current snapshot with the captured pre-implementation baseline, not blindly with repository HEAD: previously approved or completed ticket changes are part of that baseline and must not be reported as new work. A scope check must first enumerate every changed path outside the explicit bookkeeping/evidence exclusions, then compare that complete host-observed set with the approved product/ticket scope; do not pre-filter the list to expected filenames, because that would hide accidental extra product edits. Bounded evidence-only paths such as scratch/ are not product scope and must be excluded from product-path scope checks while their retained evidence remains subject to QA review. For a current-branch multi-ticket build, do not invent a mandatory branch-alone execution check merely to prove ticket independence; use baseline-aware source/test inspection and the permitted project tests unless the original requirement explicitly requires an actual isolated execution. For additive tickets in a current-branch multi-ticket build, \u201Cacceptable on its own\u201D is satisfied by showing that each ticket's own tests import and exercise only its own feature, pass with the shared baseline and required project tests, and do not depend on the sibling feature; do not require removing another additive feature or perform a destructive rollback experiment unless the approved requirement explicitly requires absence testing or an isolated branch. Preserve explicitly requested procedures and substantive requirements; if a required procedure cannot be run, identify the limitation rather than claiming it was executed. Independently assess whether proposed evidence actually tests the required behavior.";
 /** Baseline bookkeeping must not block ordinary approved implementation work. */
 export declare const APPROVED_PATH_BASELINE_GUIDANCE = "Baseline membership is host-owned bookkeeping, not a Builder requirement. An approved product path, export, or test file is not a material QA concern merely because the provider cannot prove whether it was present before implementation. Do not reconstruct or disclose the full baseline, and do not turn that uncertainty into an unresolved concern. Rafi performs the exact host comparison. Do not author a provider-executed check that asks for Rafi's host postimplementation path manifest, complete changed-path inventory, or unchanged-file comparison; that host-owned comparison is already performed outside the provider snapshot and must be represented by the retained host observation, not by raw manifest disclosure or a provider check. For current-branch additive tickets, a provider-authored or inferred request to test the branch with an already-completed sibling feature removed is not an applicable requirement when the approved scope says not to remove or reconstruct that sibling; verify the ticket's own behavior and tests against the shared baseline instead. Treat sibling-absence testing as binding only when the user explicitly approved that absence requirement. Escalate only an actual host-observed out-of-scope, destructive, protected-file, or requirement-relevant change.";
 /** Ignore known non-authoritative annotations; the original provider response remains retained. */
 export declare function normalizeAssessmentMetadata<T extends QaSemanticAssessmentV1>(assessment: T): T;
-/** Accept only an exact known obligation label when a provider wraps it in a
- * descriptive object. This is a representation repair, not a host decision:
- * unknown or ambiguous objects remain unchanged and fail schema validation. */
-export declare function normalizeAssessmentObligations<T extends QaSemanticAssessmentV1>(assessment: T, allowed: string[]): T;
-/** A preparation assessor must not block on the expected absence of future
- * Builder work. Keep the concern for auditability, but make it non-material
- * only when every referenced check is postimplementation and the concern is
- * explicitly asking the Builder to implement/rerun that check. Concerns tied
- * to preimplementation checks, missing procedures, or other semantic gaps
- * remain blocking. */
-export declare function normalizeExpectedFutureAssessment<T extends QaSemanticAssessmentV1>(assessment: T, candidate: QaContractCandidateV1): T;
 /**
  * A mandatory requirement must have at least one mandatory verification check.
  * Providers occasionally return a concrete check with the weaker advisory
@@ -53,11 +48,4 @@ export declare function normalizeExpectedFutureAssessment<T extends QaSemanticAs
  * enforce readiness and independent-QA requirements for the promoted check.
  */
 export declare function enforceMandatoryCoverage(candidate: QaContractCandidateV1): QaContractCandidateV1;
-/**
- * Codex occasionally appends a made-up requirement ID to an otherwise valid
- * check. Remove only those extraneous annotations when the check still has an
- * exact authoritative reference. Never invent or remap an ID, and leave a
- * check with no valid references untouched so normal validation fails closed.
- */
-export declare function removeExtraneousRequirementReferences(candidate: QaContractCandidateV1, inventory: RequirementRef[]): QaContractCandidateV1;
 export declare function prepareVerificationContract(initial: QaContractCandidateV1, inventory: RequirementRef[], deps: PreparationDependencies): Promise<PreparationOutcome>;