@deftai/directive-core 0.91.0 → 0.93.0

package/dist/scope/delivery-evidence.js

@@ -0,0 +1,419 @@
+/**
+ * Delivery integrity for scope completion (#3041).
+ *
+ * A code-bearing scope must not acquire a delivered disposition unless the
+ * merge/delivered commit is an ancestor of the refreshed remote delivery ref,
+ * or an explicit auditable non-delivery disposition is recorded.
+ *
+ * Deploy / UAT are separate axes and MUST NOT be inferred from Git alone.
+ */
+import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
+import { defaultGitRunner, gitIsAncestor } from "../session/git.js";
+/** Handoff states that Git delivery can assert (deploy/UAT never inferred). */
+export const HANDOFF_STATES = [
+    "implemented",
+    "pr_open",
+    "merged_to_integration",
+    "delivered",
+];
+/** Explicit non-delivery terminal dispositions (never render as shipped). */
+export const NON_DELIVERY_DISPOSITIONS = [
+    "cancelled",
+    "superseded",
+    "experiment_archived",
+    "accepted_not_delivered",
+];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function isNonDeliveryDisposition(value) {
+    return (typeof value === "string" && NON_DELIVERY_DISPOSITIONS.includes(value));
+}
+/** True when the brief is treated as code-bearing for the delivery gate (#3041). */
+export function isCodeBearingScope(plan) {
+    const meta = asRecord(plan.metadata);
+    const delivery = asRecord(meta?.delivery);
+    if (delivery?.required === false) {
+        return false;
+    }
+    if (delivery?.required === true) {
+        return true;
+    }
+    const tags = Array.isArray(plan.tags) ? plan.tags : [];
+    for (const tag of tags) {
+        if (typeof tag !== "string")
+            continue;
+        const low = tag.trim().toLowerCase();
+        if (low === "docs-only" || low === "process-only" || low === "non-code") {
+            return false;
+        }
+    }
+    const kind = typeof meta?.kind === "string" ? meta.kind.trim().toLowerCase() : "";
+    if (kind === "docs" || kind === "process" || kind === "research") {
+        return false;
+    }
+    const swarm = asRecord(meta?.swarm);
+    if (Array.isArray(swarm?.file_scope) && swarm.file_scope.length > 0) {
+        return true;
+    }
+    if (hasGithubIssueRef(plan)) {
+        return true;
+    }
+    return false;
+}
+export function hasGithubIssueRef(plan) {
+    const refs = plan.references;
+    if (!Array.isArray(refs)) {
+        return false;
+    }
+    for (const ref of refs) {
+        const rec = asRecord(ref);
+        if (rec === null)
+            continue;
+        const type = typeof rec.type === "string" ? rec.type : "";
+        const uri = typeof rec.uri === "string" ? rec.uri : "";
+        if (type.includes("github-issue") || /github\.com\/[^/]+\/[^/]+\/issues\/\d+/i.test(uri)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Classify stored completion provenance for read paths.
+ * Legacy completed records without provenance → unknown/unverified (not delivered).
+ */
+export function classifyStoredDeliveryDisposition(plan) {
+    const meta = asRecord(plan.metadata);
+    if (meta === null) {
+        return "unknown";
+    }
+    const prov = asRecord(meta.completionProvenance) ?? asRecord(meta.deliveryProvenance);
+    if (prov === null) {
+        // completedAt alone is not delivery proof
+        if (typeof meta.completedAt === "string" && meta.completedAt.length > 0) {
+            return "unverified";
+        }
+        return "unknown";
+    }
+    const disposition = prov.disposition;
+    if (typeof disposition === "string" && disposition.length > 0) {
+        return disposition;
+    }
+    return "unverified";
+}
+function remoteDeliveryRef(branch) {
+    return `origin/${branch}`;
+}
+/**
+ * Refresh the remote delivery ref. Failure blocks delivered completion (#3041).
+ */
+export function refreshRemoteDeliveryRef(projectRoot, deliveryBranch, runGit = defaultGitRunner) {
+    const remoteRef = remoteDeliveryRef(deliveryBranch);
+    const fetch = runGit(projectRoot, ["fetch", "origin", deliveryBranch]);
+    if (fetch.code !== 0) {
+        return {
+            ok: false,
+            error: `git fetch origin ${deliveryBranch} failed: ` +
+                `${fetch.stderr.trim() || fetch.stdout.trim() || `exit ${fetch.code}`}`,
+            remoteRef,
+        };
+    }
+    const verify = runGit(projectRoot, ["rev-parse", "--verify", remoteRef]);
+    if (verify.code !== 0 || !verify.stdout.trim()) {
+        return {
+            ok: false,
+            error: `remote delivery ref ${remoteRef} is not resolvable after fetch: ` +
+                `${verify.stderr.trim() || verify.stdout.trim() || `exit ${verify.code}`}`,
+            remoteRef,
+        };
+    }
+    return { ok: true, error: null, remoteRef };
+}
+/**
+ * Validate that mergeCommit is an ancestor of the refreshed remote delivery ref.
+ */
+export function verifyDeliveryAncestry(projectRoot, mergeCommit, deliveryBranch, runGit = defaultGitRunner) {
+    const refresh = refreshRemoteDeliveryRef(projectRoot, deliveryBranch, runGit);
+    if (!refresh.ok) {
+        return { ok: false, error: refresh.error, remoteTip: null };
+    }
+    const tip = runGit(projectRoot, ["rev-parse", "--verify", refresh.remoteRef]);
+    if (tip.code !== 0 || !tip.stdout.trim()) {
+        return {
+            ok: false,
+            error: `could not resolve tip of ${refresh.remoteRef}`,
+            remoteTip: null,
+        };
+    }
+    const remoteTip = tip.stdout.trim();
+    const ancestor = gitIsAncestor(projectRoot, mergeCommit, remoteTip, runGit);
+    if (ancestor === null) {
+        return {
+            ok: false,
+            error: `could not determine whether ${mergeCommit} is an ancestor of ${refresh.remoteRef} ` +
+                `(git merge-base --is-ancestor failed)`,
+            remoteTip,
+        };
+    }
+    if (!ancestor) {
+        return {
+            ok: false,
+            error: `merge commit ${mergeCommit} is not an ancestor of refreshed remote delivery ref ` +
+                `${refresh.remoteRef} (${remoteTip}). Intermediate/integration-only merges are not delivery evidence (#3041).`,
+            remoteTip,
+        };
+    }
+    return { ok: true, error: null, remoteTip };
+}
+function buildProvenance(input) {
+    const e = input.evidence ?? {};
+    return {
+        repository: e.repository ?? null,
+        implementationCommit: e.implementationCommit ?? null,
+        prNumber: e.prNumber ?? null,
+        prBase: e.prBase ?? null,
+        mergeCommit: e.mergeCommit ?? null,
+        deliveryBranch: input.deliveryBranch,
+        deliveryCommit: input.deliveryCommit ?? e.deliveryCommit ?? null,
+        verifiedAt: input.nowIso,
+        verifier: input.verifier,
+        disposition: input.disposition,
+        handoffState: input.handoffState,
+        deployed: e.deployed ?? null,
+        uatVerified: e.uatVerified ?? null,
+    };
+}
+/**
+ * Gate delivered completion for a code-bearing scope (#3041).
+ *
+ * Returns ok=true with provenance when:
+ * - scope is not code-bearing (provenance may be null or non-code note), OR
+ * - explicit non-delivery disposition is provided, OR
+ * - durable delivery evidence validates (PR base == deliveryBranch, merge commit
+ *   ancestor of refreshed remote delivery ref).
+ */
+export function evaluateDeliveryGate(options) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const verifier = options.verifier ?? "scope:complete";
+    const codeBearing = isCodeBearingScope(options.plan);
+    if (!codeBearing) {
+        return {
+            ok: true,
+            message: "non-code-bearing scope; delivery evidence not required",
+            provenance: null,
+            codeBearing: false,
+        };
+    }
+    if (options.nonDeliveryDisposition !== null && options.nonDeliveryDisposition !== undefined) {
+        if (!isNonDeliveryDisposition(options.nonDeliveryDisposition)) {
+            return {
+                ok: false,
+                message: `Invalid non-delivery disposition ${JSON.stringify(options.nonDeliveryDisposition)}. ` +
+                    `Allowed: ${NON_DELIVERY_DISPOSITIONS.join(", ")}`,
+                provenance: null,
+                codeBearing: true,
+            };
+        }
+        const branchResult = resolveDeliveryBranch(options.projectRoot, runGit);
+        const provenance = buildProvenance({
+            evidence: options.evidence,
+            deliveryBranch: options.evidence?.deliveryBranch ?? branchResult.branch,
+            disposition: options.nonDeliveryDisposition,
+            handoffState: "implemented",
+            nowIso: options.nowIso,
+            verifier,
+        });
+        return {
+            ok: true,
+            message: `explicit non-delivery disposition: ${options.nonDeliveryDisposition}`,
+            provenance,
+            codeBearing: true,
+        };
+    }
+    const evidence = options.evidence ?? null;
+    const branchResult = resolveDeliveryBranch(options.projectRoot, runGit);
+    // Policy/git-default is SoT — evidence may not redefine deliveryBranch (#3041 Greptile P1).
+    const deliveryBranch = branchResult.branch;
+    if (evidence !== null &&
+        typeof evidence.deliveryBranch === "string" &&
+        evidence.deliveryBranch.trim().length > 0 &&
+        evidence.deliveryBranch.trim() !== deliveryBranch) {
+        return {
+            ok: false,
+            message: `Evidence deliveryBranch '${evidence.deliveryBranch.trim()}' does not match ` +
+                `configured delivery branch '${deliveryBranch}' (source: ${branchResult.source}). ` +
+                `Callers cannot redefine plan.policy.deliveryBranch via evidence (#3041).`,
+            provenance: null,
+            codeBearing: true,
+        };
+    }
+    if (evidence === null) {
+        return {
+            ok: false,
+            message: `Delivery evidence required for code-bearing scope completion (#3041). ` +
+                `Provide merge/PR delivery proof (merge commit ancestor of remote ` +
+                `'${deliveryBranch}') or an explicit --non-delivery disposition ` +
+                `(${NON_DELIVERY_DISPOSITIONS.join("|")}). ` +
+                `Merged-to-integration alone is not delivery.`,
+            provenance: null,
+            codeBearing: true,
+        };
+    }
+    const mergeCommit = typeof evidence.mergeCommit === "string" && evidence.mergeCommit.trim().length > 0
+        ? evidence.mergeCommit.trim()
+        : null;
+    const prBase = typeof evidence.prBase === "string" && evidence.prBase.trim().length > 0
+        ? evidence.prBase.trim()
+        : null;
+    const mergedAt = evidence.mergedAt;
+    if (mergedAt === null || mergedAt === undefined || String(mergedAt).length === 0) {
+        // Allow evidence without mergedAt only when assumeEvidenceValidated (unit tests)
+        // or when mergeCommit is present and will be ancestry-checked.
+        if (!options.assumeEvidenceValidated && mergeCommit === null) {
+            return {
+                ok: false,
+                message: "Delivery evidence missing merged_at / merge commit; cannot prove delivery (#3041).",
+                provenance: null,
+                codeBearing: true,
+            };
+        }
+    }
+    if (prBase !== null && prBase !== deliveryBranch) {
+        const provenance = buildProvenance({
+            evidence,
+            deliveryBranch,
+            disposition: "merged_to_integration",
+            handoffState: "merged_to_integration",
+            nowIso: options.nowIso,
+            verifier,
+        });
+        return {
+            ok: false,
+            message: `PR base '${prBase}' is not the configured delivery branch '${deliveryBranch}'. ` +
+                `A merge into an intermediate/feature/integration branch is not delivery evidence (#3041).`,
+            provenance,
+            codeBearing: true,
+        };
+    }
+    if (mergeCommit === null) {
+        return {
+            ok: false,
+            message: "Delivery evidence missing merge_commit_sha; cannot prove ancestry on delivery branch (#3041).",
+            provenance: null,
+            codeBearing: true,
+        };
+    }
+    if (options.assumeEvidenceValidated) {
+        const provenance = buildProvenance({
+            evidence,
+            deliveryBranch,
+            disposition: "delivered",
+            handoffState: "delivered",
+            nowIso: options.nowIso,
+            verifier,
+            deliveryCommit: evidence.deliveryCommit ?? mergeCommit,
+        });
+        return {
+            ok: true,
+            message: `delivery evidence accepted (pre-validated) on '${deliveryBranch}'`,
+            provenance,
+            codeBearing: true,
+        };
+    }
+    const ancestry = verifyDeliveryAncestry(options.projectRoot, mergeCommit, deliveryBranch, runGit);
+    if (!ancestry.ok) {
+        const integrationOnly = prBase !== null && prBase !== deliveryBranch;
+        return {
+            ok: false,
+            message: ancestry.error ?? "delivery ancestry check failed",
+            provenance: buildProvenance({
+                evidence,
+                deliveryBranch,
+                disposition: integrationOnly ? "merged_to_integration" : "not_delivered",
+                handoffState: integrationOnly ? "merged_to_integration" : "implemented",
+                nowIso: options.nowIso,
+                verifier,
+                deliveryCommit: ancestry.remoteTip,
+            }),
+            codeBearing: true,
+        };
+    }
+    const provenance = buildProvenance({
+        evidence,
+        deliveryBranch,
+        disposition: "delivered",
+        handoffState: "delivered",
+        nowIso: options.nowIso,
+        verifier,
+        deliveryCommit: ancestry.remoteTip,
+    });
+    return {
+        ok: true,
+        message: `merge commit ${mergeCommit} is an ancestor of origin/${deliveryBranch}`,
+        provenance,
+        codeBearing: true,
+    };
+}
+/** Stamp completion provenance onto plan.metadata (mutates plan). */
+export function stampDeliveryProvenance(plan, provenance) {
+    let metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+        metadata = {};
+        plan.metadata = metadata;
+    }
+    const meta = metadata;
+    meta.completionProvenance = {
+        repository: provenance.repository,
+        implementationCommit: provenance.implementationCommit,
+        prNumber: provenance.prNumber,
+        prBase: provenance.prBase,
+        mergeCommit: provenance.mergeCommit,
+        deliveryBranch: provenance.deliveryBranch,
+        deliveryCommit: provenance.deliveryCommit,
+        verifiedAt: provenance.verifiedAt,
+        verifier: provenance.verifier,
+        disposition: provenance.disposition,
+        handoffState: provenance.handoffState,
+        // Deploy/UAT are explicit-only; default null so readers never infer from Git.
+        deployed: provenance.deployed,
+        uatVerified: provenance.uatVerified,
+    };
+    meta.deliveryDisposition = provenance.disposition;
+    meta.handoffState = provenance.handoffState;
+}
+/**
+ * Parse a PR REST payload into delivery evidence fields.
+ * Expects GitHub pulls API shape (merged_at, base.ref, merge_commit_sha, …).
+ */
+export function evidenceFromPrPayload(payload, prNumber, repository, deliveryBranch) {
+    const base = asRecord(payload.base);
+    const head = asRecord(payload.head);
+    const prBase = typeof base?.ref === "string" ? base.ref : null;
+    const mergeCommit = typeof payload.merge_commit_sha === "string" && payload.merge_commit_sha.length > 0
+        ? payload.merge_commit_sha
+        : null;
+    const headSha = typeof head?.sha === "string" && head.sha.length > 0
+        ? head.sha
+        : typeof payload.head_sha === "string"
+            ? payload.head_sha
+            : null;
+    const mergedAt = payload.merged_at === null
+        ? null
+        : typeof payload.merged_at === "string"
+            ? payload.merged_at
+            : null;
+    return {
+        repository,
+        implementationCommit: headSha,
+        prNumber,
+        prBase,
+        mergeCommit,
+        deliveryBranch: deliveryBranch ?? null,
+        mergedAt,
+        verifier: "swarm:finalize-cohort",
+    };
+}
+//# sourceMappingURL=delivery-evidence.js.map

package/dist/scope/index.d.ts

@@ -2,6 +2,7 @@ export * from "./audit-log.js";
 export * from "./batch-promote.js";
 export * from "./constants.js";
 export * from "./decomposed-refs.js";
+export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";

package/dist/scope/index.js

@@ -2,6 +2,7 @@ export * from "./audit-log.js";
 export * from "./batch-promote.js";
 export * from "./constants.js";
 export * from "./decomposed-refs.js";
+export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";

package/dist/scope/main.d.ts

@@ -1,3 +1,4 @@
+import { type DeliveryEvidenceInput, type NonDeliveryDisposition } from "./delivery-evidence.js";
 export interface LifecycleArgs {
     action: string;
     file: string;
@@ -5,6 +6,10 @@ export interface LifecycleArgs {
     force?: boolean;
     batch?: boolean;
     batchFiles?: string[];
+    /** Explicit non-delivery disposition for code-bearing complete (#3041). */
+    nonDeliveryDisposition?: NonDeliveryDisposition;
+    /** Optional delivery evidence flags for complete (#3041). */
+    deliveryEvidence?: DeliveryEvidenceInput;
 }
 export interface DemoteArgs {
     file?: string;

package/dist/scope/main.js

@@ -5,6 +5,7 @@ import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/u
 import { canonicalLogPath, readAll } from "./audit-log.js";
 import { batchPromote } from "./batch-promote.js";
 import { TRANSITIONS } from "./constants.js";
+import { isNonDeliveryDisposition, } from "./delivery-evidence.js";
 import { batchDemote, DEFAULT_OLDER_THAN_DAYS, demoteOne, resolveDemoteFilePath, resolveFilePath, resolveProjectRootStrict, } from "./demote.js";
 import { completedPathForScopeMove, findOpenUmbrellaReferences, renderOpenUmbrellaWarning, } from "./open-umbrella-warning.js";
 import { resolveProjectRoot } from "./project-context.js";
@@ -29,6 +30,13 @@ function parseLifecycleArgv(argv) {
     let force = false;
     let batch = false;
     const batchFiles = [];
+    let nonDeliveryDisposition;
+    let prNumber;
+    let mergeCommit;
+    let prBase;
+    let deliveryBranch;
+    let repo;
+    let mergedAt;
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === undefined) {
@@ -47,6 +55,63 @@ function parseLifecycleArgv(argv) {
         else if (arg?.startsWith("--project-root=")) {
             projectRoot = arg.slice("--project-root=".length);
         }
+        else if (arg === "--non-delivery" || arg === "--non-delivery-disposition") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (raw === undefined || !isNonDeliveryDisposition(raw)) {
+                return { args: null, error: "usage" };
+            }
+            nonDeliveryDisposition = raw;
+        }
+        else if (arg?.startsWith("--non-delivery=")) {
+            const raw = arg.slice("--non-delivery=".length);
+            if (!isNonDeliveryDisposition(raw)) {
+                return { args: null, error: "usage" };
+            }
+            nonDeliveryDisposition = raw;
+        }
+        else if (arg === "--pr" && argv[i + 1] !== undefined) {
+            prNumber = Number.parseInt(argv[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg?.startsWith("--pr=")) {
+            prNumber = Number.parseInt(arg.slice("--pr=".length), 10);
+        }
+        else if (arg === "--merge-commit" && argv[i + 1] !== undefined) {
+            mergeCommit = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--merge-commit=")) {
+            mergeCommit = arg.slice("--merge-commit=".length);
+        }
+        else if (arg === "--pr-base" && argv[i + 1] !== undefined) {
+            prBase = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--pr-base=")) {
+            prBase = arg.slice("--pr-base=".length);
+        }
+        else if (arg === "--delivery-branch" && argv[i + 1] !== undefined) {
+            deliveryBranch = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--delivery-branch=")) {
+            deliveryBranch = arg.slice("--delivery-branch=".length);
+        }
+        else if (arg === "--repo" && argv[i + 1] !== undefined) {
+            repo = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--merged-at" && argv[i + 1] !== undefined) {
+            mergedAt = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--merged-at=")) {
+            mergedAt = arg.slice("--merged-at=".length);
+        }
         else if (!arg.startsWith("-")) {
             if (batch) {
                 batchFiles.push(arg);
@@ -62,6 +127,22 @@ function parseLifecycleArgv(argv) {
             return { args: null, error: "usage" };
         }
     }
+    const deliveryEvidence = prNumber !== undefined ||
+        mergeCommit !== undefined ||
+        prBase !== undefined ||
+        deliveryBranch !== undefined ||
+        repo !== undefined ||
+        mergedAt !== undefined
+        ? {
+            prNumber: prNumber !== undefined && Number.isFinite(prNumber) ? prNumber : null,
+            mergeCommit: mergeCommit ?? null,
+            prBase: prBase ?? null,
+            deliveryBranch: deliveryBranch ?? null,
+            repository: repo ?? null,
+            mergedAt: mergedAt ?? (mergeCommit !== undefined ? "supplied" : null),
+            verifier: "scope:complete",
+        }
+        : undefined;
     if (batch) {
         if (action !== "promote") {
             return { args: null, error: "usage" };
@@ -80,7 +161,16 @@ function parseLifecycleArgv(argv) {
     if (file.length === 0) {
         return { args: null, error: "usage" };
     }
-    return { args: { action, file, projectRoot, force } };
+    return {
+        args: {
+            action,
+            file,
+            projectRoot,
+            force,
+            nonDeliveryDisposition,
+            deliveryEvidence,
+        },
+    };
 }
 /** Main entry for scope_lifecycle.py parity. */
 export function lifecycleMain(argv) {
@@ -91,7 +181,7 @@ export function lifecycleMain(argv) {
         }
         return 2;
     }
-    const { action, file, projectRoot, force, batch, batchFiles } = parsed.args;
+    const { action, file, projectRoot, force, batch, batchFiles, nonDeliveryDisposition, deliveryEvidence, } = parsed.args;
     if (batch === true && action === "promote") {
         const result = batchPromote({
             files: batchFiles && batchFiles.length > 0 ? batchFiles : undefined,
@@ -129,7 +219,12 @@ export function lifecycleMain(argv) {
             }
         }
     }
-    const result = runTransition(action, filePath);
+    const transitionOptions = {
+        nonDeliveryDisposition,
+        deliveryEvidence,
+        verifier: "scope:complete",
+    };
+    const result = runTransition(action, filePath, new Date(), transitionOptions);
     if (result.ok) {
         if (action === "promote" && capCheck !== null && capCheck.forceOverride) {
             const rootForAudit = resolveProjectRoot(projectRoot);

package/dist/scope/registry-artifact-sync.js

@@ -164,7 +164,10 @@ export function syncRegistryArtifactAfterScopeMove(registryPath, scopeData, oldP
                 hooks.persist(registryPath, registry);
             }
             else {
-                atomicWriteText(registryPath, formatBriefJson(registry));
+                // #3042: contain registry stay-path write against project root (parent of xbrief/).
+                atomicWriteText(registryPath, formatBriefJson(registry), {
+                    projectRoot: dirname(resolve(vbriefRoot)),
+                });
             }
         }
     }

package/dist/scope/transition.d.ts

@@ -1,10 +1,20 @@
+import type { GitRunner } from "../session/git.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;
 }
-export declare function runTransition(action: string, filePath: string, now?: Date): TransitionResult;
+/** Optional completion evidence / disposition for the delivery gate (#3041). */
+export interface TransitionOptions {
+    readonly deliveryEvidence?: DeliveryEvidenceInput | null;
+    readonly nonDeliveryDisposition?: NonDeliveryDisposition | null;
+    readonly runGit?: GitRunner;
+    readonly verifier?: string;
+    readonly assumeEvidenceValidated?: 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;
 export { detectLifecycleFolder };
 //# sourceMappingURL=transition.d.ts.map