@deftai/directive-core 0.99.0 → 0.101.0

package/dist/scope/parent-lineage.js

@@ -0,0 +1,626 @@
+/**
+ * Parent-lineage gates for story-ready and pre-PR/preflight (#3241 / epic #3237).
+ *
+ * After #3238 coverage artifacts exist, a green child can still contradict parent
+ * invariants unless build/review gates re-check structure. This module:
+ *   - resolves parent via plan.planRef (or plan references)
+ *   - when parent authors requirement IDs, requires child coverage artifacts
+ *   - reuses validateCoverageMap (structure-only; no LLM judgment)
+ *   - classifies defects: child_spec | parent_child_drift
+ *
+ * Backward compatible: no parent link, or parent with zero requirement IDs → N/A pass.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { extractParentRequirements, formatCoverageReportLine, validateCoverageMap, } from "./coverage-map.js";
+export const PARENT_LINEAGE_SCHEMA = "deft.scope.parent_lineage.v1";
+/** Lifecycle folders scanned for unique plan.id recovery of a moved parent. */
+const PARENT_LINEAGE_LIFECYCLE_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+/** Defect classes for gate output (#3241 AC: distinguish child-spec vs parent/child drift). */
+export const LINEAGE_DEFECT_CLASSES = ["child_spec", "parent_child_drift"];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Walk up from a child artifact path to find the lifecycle root (xbrief/ or vbrief/).
+ */
+export function findLifecycleRootFromArtifact(artifactPath) {
+    let current = resolve(dirname(artifactPath));
+    for (let i = 0; i < 8; i += 1) {
+        const base = current.split(/[/\\]/).pop()?.toLowerCase() ?? "";
+        if (base === "xbrief" || base === "vbrief") {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Resolve plan.planRef (or similar relative ref) against a lifecycle root.
+ * Rejects absolute paths and `..` traversal.
+ */
+export function resolveParentPathFromRef(planRef, lifecycleRoot) {
+    const trimmed = planRef.trim();
+    if (!trimmed) {
+        return { path: null, error: "empty planRef" };
+    }
+    if (isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return { path: null, error: `planRef must be relative to lifecycle root (got absolute)` };
+    }
+    const segments = trimmed.split(/[/\\]+/).filter((s) => s.length > 0);
+    if (segments.includes("..")) {
+        return { path: null, error: `planRef must not contain parent traversal (..)` };
+    }
+    // Strip leading xbrief/ or vbrief/ if present (planRef is often relative to lifecycle root).
+    const first = segments[0]?.toLowerCase();
+    const relSegments = first === "xbrief" || first === "vbrief" ? segments.slice(1) : segments;
+    const resolved = resolve(lifecycleRoot, ...relSegments);
+    const rootResolved = resolve(lifecycleRoot);
+    if (resolved !== rootResolved && !resolved.startsWith(rootResolved + sep)) {
+        return { path: null, error: `planRef escapes lifecycle root` };
+    }
+    return { path: resolved, error: null };
+}
+/**
+ * Extract coverage draft surface from a child xBRIEF for validateCoverageMap.
+ * Prefer plan.metadata.parent_lineage, then plan.metadata, then plan/root.
+ */
+export function extractChildCoverageDraft(child) {
+    const root = asRecord(child);
+    if (root === null) {
+        return { draft: null, source: null, hasCoverageMapKey: false };
+    }
+    const plan = asRecord(root.plan) ?? root;
+    const metadata = asRecord(plan.metadata);
+    const candidates = [];
+    if (metadata !== null) {
+        const lineage = asRecord(metadata.parent_lineage ?? metadata.parentLineage);
+        if (lineage !== null) {
+            candidates.push({ source: "plan.metadata.parent_lineage", obj: lineage });
+        }
+        candidates.push({ source: "plan.metadata", obj: metadata });
+    }
+    candidates.push({ source: "plan", obj: plan });
+    candidates.push({ source: "root", obj: root });
+    for (const c of candidates) {
+        const hasMap = "coverage_map" in c.obj ||
+            "coverageMap" in c.obj ||
+            asRecord(c.obj.coverage)?.coverage_map !== undefined;
+        if (!hasMap)
+            continue;
+        const coverageNested = asRecord(c.obj.coverage);
+        const coverage_map = c.obj.coverage_map ??
+            c.obj.coverageMap ??
+            coverageNested?.coverage_map ??
+            coverageNested?.coverageMap;
+        const behavioral_deltas = c.obj.behavioral_deltas ??
+            c.obj.behavioralDeltas ??
+            coverageNested?.behavioral_deltas ??
+            coverageNested?.behavioralDeltas;
+        return {
+            draft: {
+                coverage_map,
+                behavioral_deltas,
+            },
+            source: c.source,
+            hasCoverageMapKey: true,
+        };
+    }
+    return { draft: null, source: null, hasCoverageMapKey: false };
+}
+/**
+ * Build the parent_lineage metadata block stamped onto decomposed children (#3241).
+ */
+export function buildParentLineageArtifact(opts) {
+    const out = {
+        schema: PARENT_LINEAGE_SCHEMA,
+    };
+    if (opts.coverage_map !== undefined) {
+        out.coverage_map = opts.coverage_map;
+    }
+    if (opts.behavioral_deltas !== undefined) {
+        out.behavioral_deltas = opts.behavioral_deltas;
+    }
+    if (opts.parent_requirement_ids !== undefined) {
+        out.parent_requirement_ids = [...opts.parent_requirement_ids];
+    }
+    if (opts.negative_invariant_ids !== undefined) {
+        out.negative_invariant_ids = [...opts.negative_invariant_ids];
+    }
+    if (opts.parent_plan_id !== undefined && opts.parent_plan_id.trim().length > 0) {
+        out.parent_plan_id = opts.parent_plan_id.trim();
+    }
+    return out;
+}
+function resolveParentRefFromChild(child) {
+    const plan = asRecord(child.plan) ?? child;
+    if (isNonEmptyString(plan.planRef))
+        return plan.planRef.trim();
+    if (isNonEmptyString(plan.plan_ref))
+        return plan.plan_ref.trim();
+    const refs = plan.references;
+    if (Array.isArray(refs)) {
+        for (const ref of refs) {
+            const r = asRecord(ref);
+            if (r === null)
+                continue;
+            const type = String(r.type ?? "").toLowerCase();
+            // Parent plan provenance: x-xbrief/plan or x-vbrief/plan (or plain plan).
+            if (type === "plan" ||
+                type.endsWith("/plan") ||
+                type.includes("xbrief/plan") ||
+                type.includes("vbrief/plan")) {
+                if (isNonEmptyString(r.uri)) {
+                    const uri = r.uri.trim();
+                    // Skip issue/github URIs.
+                    if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("#")) {
+                        continue;
+                    }
+                    return uri.startsWith("file://") ? uri.slice("file://".length) : uri;
+                }
+            }
+        }
+    }
+    return null;
+}
+function loadJsonFile(path) {
+    try {
+        if (!existsSync(path)) {
+            return { ok: false, error: `parent not found at ${path}` };
+        }
+        const raw = readFileSync(path, "utf8");
+        const data = JSON.parse(raw);
+        const rec = asRecord(data);
+        if (rec === null) {
+            return { ok: false, error: `parent at ${path} is not a JSON object` };
+        }
+        return { ok: true, data: rec };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `could not load parent at ${path}: ${String(err.message ?? err)}`,
+        };
+    }
+}
+/** Read plan.id from a loaded parent document (plan.id or root id). */
+export function extractPlanId(doc) {
+    const root = asRecord(doc);
+    if (root === null)
+        return null;
+    const plan = asRecord(root.plan) ?? root;
+    const id = plan.id;
+    return typeof id === "string" && id.trim().length > 0 ? id.trim() : null;
+}
+/**
+ * Scan lifecycle folders for artifacts whose plan.id exactly equals parentPlanId.
+ * Returns every match (caller enforces uniqueness). Does not use basenames.
+ */
+export function findParentsByPlanId(lifecycleRoot, parentPlanId) {
+    const want = parentPlanId.trim();
+    if (!want)
+        return [];
+    const matches = [];
+    for (const folder of PARENT_LINEAGE_LIFECYCLE_FOLDERS) {
+        const dir = join(lifecycleRoot, folder);
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            const full = join(dir, name);
+            const loaded = loadJsonFile(full);
+            if (!loaded.ok)
+                continue;
+            const id = extractPlanId(loaded.data);
+            if (id === want) {
+                matches.push({ path: full, data: loaded.data });
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Load parent for lineage checks.
+ *
+ * 1. Prefer the exact planRef path when it exists; require plan.id match when
+ *    the child stamps parent_plan_id (path replacement with a different plan is rejected).
+ * 2. When the exact path is missing AND the child stamps parent_plan_id: recover by
+ *    scanning lifecycle folders for plan.id === parent_plan_id and accepting ONLY
+ *    when exactly one artifact matches. This handles lifecycle moves when child
+ *    planRef rewrite lagged — not silent basename recovery of unrelated files.
+ * 3. Without a durable stamp, stale/missing planRef fails closed (no basename guess).
+ */
+export function loadParentExact(parentPath, opts = {}) {
+    const expected = opts.expectedParentPlanId !== undefined &&
+        opts.expectedParentPlanId !== null &&
+        opts.expectedParentPlanId.trim().length > 0
+        ? opts.expectedParentPlanId.trim()
+        : null;
+    const primary = loadJsonFile(parentPath);
+    if (primary.ok) {
+        if (expected !== null) {
+            const actual = extractPlanId(primary.data) ?? "";
+            if (actual !== expected) {
+                return {
+                    ok: false,
+                    error: `parent at ${parentPath} has plan.id='${actual || "(missing)"}' but child stamps ` +
+                        `parent_plan_id='${expected}' — refuse identity mismatch (rewrite planRef or re-stamp)`,
+                    path: parentPath,
+                };
+            }
+        }
+        return { ok: true, data: primary.data, path: parentPath };
+    }
+    // Exact path missing: unique plan.id recovery only (no basename recovery).
+    // Documented intentional: when planRef is stale after a lifecycle move, a stamped
+    // parent_plan_id that matches exactly one active/completed/… artifact is the
+    // durable identity key — never recover by filename alone.
+    if (expected !== null && opts.lifecycleRoot !== undefined && opts.lifecycleRoot !== null) {
+        const matches = findParentsByPlanId(opts.lifecycleRoot, expected);
+        const unique = matches.length === 1 ? matches[0] : undefined;
+        if (unique !== undefined) {
+            return { ok: true, data: unique.data, path: unique.path };
+        }
+        if (matches.length > 1) {
+            const paths = matches.map((m) => m.path).join(", ");
+            return {
+                ok: false,
+                error: `parent planRef path missing at ${parentPath}; parent_plan_id='${expected}' matches ` +
+                    `${matches.length} lifecycle artifacts (ambiguous — rewrite planRef): ${paths}`,
+                path: parentPath,
+            };
+        }
+        return {
+            ok: false,
+            error: `${primary.error}. Parent planRef path missing and no unique lifecycle artifact with ` +
+                `plan.id='${expected}' (rewrite the child's planRef; no basename guess).`,
+            path: parentPath,
+        };
+    }
+    return {
+        ok: false,
+        error: `${primary.error}. Parent path must match planRef exactly — if the parent ` +
+            `moved lifecycle folders, stamp parent_plan_id (decompose) or rewrite planRef ` +
+            `(no basename guess).`,
+        path: parentPath,
+    };
+}
+/** Stamped parent_plan_id from child plan.metadata.parent_lineage (if any). */
+export function extractStampedParentPlanId(child) {
+    const root = asRecord(child);
+    if (root === null)
+        return null;
+    const plan = asRecord(root.plan) ?? root;
+    const metadata = asRecord(plan.metadata);
+    if (metadata === null)
+        return null;
+    const lineage = asRecord(metadata.parent_lineage ?? metadata.parentLineage);
+    if (lineage === null)
+        return null;
+    const raw = lineage.parent_plan_id ?? lineage.parentPlanId;
+    return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : null;
+}
+function classifyCoverageFailure(errors) {
+    // Missing map / parse shape issues are child-spec; uncovered/conflict vs parent is drift.
+    const childSpecHints = [
+        "coverage_map is required",
+        "coverage_map must be",
+        "disposition must be",
+        "missing/invalid fields",
+        "parent_requirement_id is required",
+        "missing delta_id",
+        "requires delta_id",
+        "requires provenance",
+        "requires split_group",
+        "requires part",
+        "behavioral_deltas must be",
+    ];
+    for (const e of errors) {
+        const lower = e.toLowerCase();
+        if (childSpecHints.some((h) => lower.includes(h.toLowerCase()))) {
+            return "child_spec";
+        }
+    }
+    return "parent_child_drift";
+}
+function okResult(partial) {
+    return {
+        ok: true,
+        defect_class: null,
+        errors: [],
+        coverage_report: partial.coverage_report,
+        applicable: partial.applicable,
+        parent_path: partial.parent_path,
+        parent_requirement_ids: partial.parent_requirement_ids,
+        negative_invariant_ids: partial.negative_invariant_ids,
+        message: partial.message,
+    };
+}
+function failResult(opts) {
+    return {
+        ok: false,
+        applicable: opts.applicable ?? true,
+        defect_class: opts.defect_class,
+        message: opts.message,
+        parent_path: opts.parent_path ?? null,
+        parent_requirement_ids: opts.parent_requirement_ids ?? [],
+        negative_invariant_ids: opts.negative_invariant_ids ?? [],
+        coverage_report: opts.coverage_report ?? null,
+        errors: opts.errors,
+    };
+}
+/**
+ * Pure parent-lineage evaluation for an in-memory child + optional parent.
+ * When parent is omitted, uses parentPath / project layout from options.
+ */
+export function evaluateParentLineage(opts) {
+    if (opts.skip === true) {
+        return okResult({
+            applicable: false,
+            parent_path: null,
+            parent_requirement_ids: [],
+            negative_invariant_ids: [],
+            coverage_report: null,
+            message: "parent lineage: skipped",
+        });
+    }
+    const child = asRecord(opts.child);
+    if (child === null) {
+        return failResult({
+            defect_class: "child_spec",
+            message: "parent lineage: child is not a JSON object",
+            errors: ["child is not a JSON object"],
+        });
+    }
+    const planRef = resolveParentRefFromChild(child);
+    if (planRef === null && opts.parent === undefined && opts.parentPath === undefined) {
+        return okResult({
+            applicable: false,
+            parent_path: null,
+            parent_requirement_ids: [],
+            negative_invariant_ids: [],
+            coverage_report: null,
+            message: "parent lineage: N/A (no planRef / parent link)",
+        });
+    }
+    let parentDoc = asRecord(opts.parent);
+    let parentPath = opts.parentPath ?? null;
+    const stampedParentPlanId = extractStampedParentPlanId(child);
+    if (parentDoc === null) {
+        let lifecycleRoot = null;
+        if (opts.childPath !== undefined) {
+            lifecycleRoot = findLifecycleRootFromArtifact(opts.childPath);
+        }
+        if (lifecycleRoot === null && opts.projectRoot !== undefined) {
+            const xbrief = join(opts.projectRoot, "xbrief");
+            const vbrief = join(opts.projectRoot, "vbrief");
+            if (existsSync(xbrief))
+                lifecycleRoot = xbrief;
+            else if (existsSync(vbrief))
+                lifecycleRoot = vbrief;
+        }
+        if (parentPath === null && planRef !== null) {
+            if (lifecycleRoot === null) {
+                return failResult({
+                    defect_class: "child_spec",
+                    message: "parent lineage: cannot resolve planRef (no lifecycle root from child path or project root)",
+                    errors: ["cannot resolve planRef: missing lifecycle root"],
+                });
+            }
+            const resolved = resolveParentPathFromRef(planRef, lifecycleRoot);
+            if (resolved.error !== null || resolved.path === null) {
+                return failResult({
+                    defect_class: "child_spec",
+                    message: `parent lineage: invalid planRef '${planRef}': ${resolved.error}`,
+                    errors: [resolved.error ?? "invalid planRef"],
+                });
+            }
+            parentPath = resolved.path;
+        }
+        if (parentPath === null) {
+            return failResult({
+                defect_class: "child_spec",
+                message: "parent lineage: parent path unresolved",
+                errors: ["parent path unresolved"],
+            });
+        }
+        // Exact planRef, else unique parent_plan_id recovery (no basename guess).
+        const loaded = loadParentExact(parentPath, {
+            expectedParentPlanId: stampedParentPlanId,
+            lifecycleRoot,
+        });
+        if (!loaded.ok) {
+            return failResult({
+                defect_class: "child_spec",
+                message: `parent lineage: ${loaded.error}`,
+                errors: [loaded.error],
+                parent_path: loaded.path,
+            });
+        }
+        parentDoc = loaded.data;
+        parentPath = loaded.path;
+    }
+    const requirements = extractParentRequirements(parentDoc);
+    const parentIds = requirements.map((r) => r.id);
+    const negativeIds = requirements.filter((r) => r.negativeInvariant).map((r) => r.id);
+    if (parentIds.length === 0) {
+        // Still refuse identity mismatch when child stamps a durable parent id.
+        if (stampedParentPlanId !== null) {
+            const actualId = extractPlanId(parentDoc) ?? "";
+            if (actualId !== stampedParentPlanId) {
+                return failResult({
+                    defect_class: "child_spec",
+                    message: `parent lineage: parent plan.id='${actualId || "(missing)"}' but child stamps ` +
+                        `parent_plan_id='${stampedParentPlanId}' — refuse identity mismatch`,
+                    errors: [
+                        `parent identity mismatch: plan.id='${actualId || "(missing)"}' vs parent_plan_id='${stampedParentPlanId}'`,
+                    ],
+                    parent_path: parentPath,
+                });
+            }
+        }
+        return okResult({
+            applicable: false,
+            parent_path: parentPath,
+            parent_requirement_ids: [],
+            negative_invariant_ids: [],
+            coverage_report: null,
+            message: "parent lineage: N/A (parent authors no requirement IDs)",
+        });
+    }
+    // When parent authors requirement IDs, durable parent identity is mandatory.
+    // Without parent_plan_id, an exact-path replacement can silently validate against
+    // the wrong parent (or N/A-pass an empty imposter). Decompose fails closed if the
+    // parent has no plan.id; hand-authored children must stamp the same field.
+    if (stampedParentPlanId === null) {
+        return failResult({
+            defect_class: "child_spec",
+            message: "parent lineage: child missing durable parent_plan_id stamp while parent authors " +
+                `requirement ID(s) (${parentIds.join(", ")}). Re-decompose from a parent with plan.id, ` +
+                "or stamp plan.metadata.parent_lineage.parent_plan_id to the parent's plan.id.",
+            errors: [
+                "missing parent_plan_id stamp on child",
+                `parent authors requirement IDs: ${parentIds.join(", ")}`,
+            ],
+            parent_path: parentPath,
+            parent_requirement_ids: parentIds,
+            negative_invariant_ids: negativeIds,
+        });
+    }
+    const actualParentId = extractPlanId(parentDoc) ?? "";
+    if (actualParentId !== stampedParentPlanId) {
+        return failResult({
+            defect_class: "child_spec",
+            message: `parent lineage: parent plan.id='${actualParentId || "(missing)"}' but child stamps ` +
+                `parent_plan_id='${stampedParentPlanId}' — refuse identity mismatch (rewrite planRef or re-stamp)`,
+            errors: [
+                `parent identity mismatch: plan.id='${actualParentId || "(missing)"}' vs parent_plan_id='${stampedParentPlanId}'`,
+            ],
+            parent_path: parentPath,
+            parent_requirement_ids: parentIds,
+            negative_invariant_ids: negativeIds,
+        });
+    }
+    const { draft, source, hasCoverageMapKey } = extractChildCoverageDraft(child);
+    if (!hasCoverageMapKey || draft === null) {
+        return failResult({
+            defect_class: "child_spec",
+            message: "parent lineage: child missing parent coverage artifacts " +
+                `(parent authors ${parentIds.length} requirement ID(s): ${parentIds.join(", ")}). ` +
+                "Stamp plan.metadata.parent_lineage.coverage_map (from #3238 decompose) or declare coverage_map.",
+            errors: [
+                "missing parent coverage artifacts on child",
+                `uncovered parent requirement IDs: ${parentIds.join(", ")}`,
+            ],
+            parent_path: parentPath,
+            parent_requirement_ids: parentIds,
+            negative_invariant_ids: negativeIds,
+        });
+    }
+    const validation = validateCoverageMap({
+        parent: parentDoc,
+        draft,
+    });
+    if (!validation.ok) {
+        const defect = classifyCoverageFailure(validation.errors);
+        const negHits = validation.errors.filter((e) => e.includes("negative invariant") || e.includes("silent removal"));
+        const summary = validation.errors.slice(0, 4).join("; ");
+        const kindLabel = defect === "child_spec" ? "child-spec defect" : "parent/child drift";
+        let message = `parent lineage: ${kindLabel} — ${summary}` +
+            (validation.errors.length > 4 ? ` (+${validation.errors.length - 4} more)` : "");
+        if (negHits.length > 0) {
+            message +=
+                " (negative invariant requires coverage or approved behavioral_delta; silent drop forbidden)";
+        }
+        message += ` [${source ?? "coverage"}] ${formatCoverageReportLine(validation.report)}`;
+        return failResult({
+            defect_class: defect,
+            message,
+            errors: validation.errors,
+            parent_path: parentPath,
+            parent_requirement_ids: parentIds,
+            negative_invariant_ids: negativeIds,
+            coverage_report: validation.report,
+        });
+    }
+    return okResult({
+        applicable: true,
+        parent_path: parentPath,
+        parent_requirement_ids: parentIds,
+        negative_invariant_ids: negativeIds,
+        coverage_report: validation.report,
+        message: `parent lineage: OK (${parentIds.length} parent requirement ID(s); ` +
+            `${negativeIds.length} negative invariant(s); source=${source ?? "coverage"})`,
+    });
+}
+/**
+ * Convenience: load child from path and evaluate lineage.
+ */
+export function evaluateParentLineageAtPath(childPath, options = {}) {
+    let raw;
+    try {
+        raw = readFileSync(childPath, "utf8");
+    }
+    catch (err) {
+        return failResult({
+            defect_class: "child_spec",
+            message: `parent lineage: could not read child at ${childPath}: ${String(err.message ?? err)}`,
+            errors: [`could not read child: ${String(err.message ?? err)}`],
+        });
+    }
+    let child;
+    try {
+        child = JSON.parse(raw);
+    }
+    catch (err) {
+        return failResult({
+            defect_class: "child_spec",
+            message: `parent lineage: child at ${childPath} is not valid JSON: ${String(err.message ?? err)}`,
+            errors: [`invalid child JSON: ${String(err.message ?? err)}`],
+        });
+    }
+    return evaluateParentLineage({
+        child,
+        childPath,
+        projectRoot: options.projectRoot,
+        skip: options.skip,
+    });
+}
+/** One-line machine-readable lineage summary for gate stdout. */
+export function formatParentLineageLine(result) {
+    const payload = {
+        schema: "deft.scope.parent_lineage_report.v1",
+        ok: result.ok,
+        applicable: result.applicable,
+        defect_class: result.defect_class,
+        parent_path: result.parent_path,
+        parent_requirement_ids: result.parent_requirement_ids,
+        negative_invariant_ids: result.negative_invariant_ids,
+        errors: result.errors,
+    };
+    return `PARENT_LINEAGE ${JSON.stringify(payload)}`;
+}
+//# sourceMappingURL=parent-lineage.js.map

package/dist/scope/transition.d.ts

@@ -1,10 +1,13 @@
 import type { GitRunner } from "../session/git.js";
+import { type CriterionAcceptanceReport } from "./acceptance-evidence.js";
 import { detectLifecycleFolder } from "./decomposed-refs.js";
 import { type DeliveryEvidenceInput, type NonDeliveryDisposition } from "./delivery-evidence.js";
 import type { WipCapCheck } from "./wip-cap-check.js";
 export interface TransitionResult {
     readonly ok: boolean;
     readonly message: string;
+    /** Per-criterion acceptance reports when complete ran the #3240 gate. */
+    readonly acceptanceReports?: readonly CriterionAcceptanceReport[];
 }
 /** Optional completion evidence / disposition for the delivery gate (#3041). */
 export interface TransitionOptions {
@@ -13,6 +16,11 @@ export interface TransitionOptions {
     readonly runGit?: GitRunner;
     readonly verifier?: string;
     readonly assumeEvidenceValidated?: boolean;
+    /**
+     * Test-only escape hatch: skip the #3240 per-item acceptance evidence gate.
+     * Production callers MUST leave this false/undefined.
+     */
+    readonly skipAcceptanceEvidenceGate?: boolean;
 }
 export declare function runTransition(action: string, filePath: string, now?: Date, options?: TransitionOptions): TransitionResult;
 export declare function recordWipCapOverride(filePath: string, projectRoot: string, check: WipCapCheck, now?: Date): void;