@deftai/directive-core 0.91.0 → 0.92.0

package/dist/policy/deft-directive-disable.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Temporary test/local kill-switch for Directive enforcement (#3039).
+ *
+ * Presence of root `.deft-directive-disable` means Directive **enforcement** is
+ * OFF (hooks, session ritual, automation) while the deposit may remain — **only
+ * when the file is not tracked by git**. A committed flag is misconfig: doctor
+ * warns and enforcement stays ON (repository-controlled content must not disable
+ * hooks for downstream clones).
+ *
+ * Distinct from `.no-deft-directive` (#2926 permanent opt-out): flag+deposit is
+ * **not** inconsistent here.
+ *
+ * Product choices (v1):
+ * - Flag is **root-only** (workspace root the tool opened).
+ * - Flag **must be gitignored** (canonical baseline); committed flag → doctor
+ *   warns and does **not** short-circuit enforcement.
+ * - Deposit presence is **OK**.
+ * - Full re-enable requires: delete the file **and** start a **new** agent session.
+ * - Precedence: active kill-switch first, then `.no-deft-directive`, else normal.
+ */
+/** Canonical root-only filename (lowercase). Presence = candidate flag. */
+export declare const DEFT_DIRECTIVE_DISABLE_FLAG_NAME = ".deft-directive-disable";
+/** Gitignore entry the deposit must ensure (same as flag name). */
+export declare const DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE = ".deft-directive-disable";
+/**
+ * Canonical recovery message when Directive is disabled by the test kill-switch.
+ * Surfaces (doctor, agent, CLI, hooks) share this wording.
+ */
+export declare const DEFT_DIRECTIVE_DISABLE_RECOVERY_MESSAGE: string;
+/** One-line summary for log lines and short CLI output. */
+export declare const DEFT_DIRECTIVE_DISABLE_ONE_LINE = "Directive disabled via `.deft-directive-disable` (test/local kill-switch; deposit OK)";
+/** Doctor/status label when the kill-switch is active (local / untracked). */
+export declare const DEFT_DIRECTIVE_DISABLE_STATUS: "disabled-test-kill-switch";
+/**
+ * Warning when the kill-switch file is tracked by git (should be gitignored).
+ * Tracked flags do **not** disable enforcement.
+ */
+export declare const DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING = "Misconfig: `.deft-directive-disable` is tracked by git. The flag must be gitignored (local kill-switch only). Untrack it and ensure `.gitignore` covers the path. Enforcement is NOT disabled while the flag is tracked.";
+export interface DeftDirectiveDisableSeams {
+    readonly isFile?: (path: string) => boolean;
+    readonly isDir?: (path: string) => boolean;
+    /** Return true when `git ls-files` lists the flag (tracked). */
+    readonly isGitTracked?: (projectRoot: string, relPath: string) => boolean;
+    /** Skip tracked probe + cache (tests / doctor full re-check). */
+    readonly skipTrackedCache?: boolean;
+}
+export interface DeftDirectiveDisableState {
+    readonly present: boolean;
+    readonly flagPath: string;
+    readonly depositPresent: boolean;
+    /**
+     * True when the flag file is tracked by git (misconfig — should be gitignored).
+     * Always false when the flag is absent or when the probe cannot run.
+     */
+    readonly trackedByGit: boolean;
+    /**
+     * True when the kill-switch is **active** for enforcement short-circuit:
+     * present and **not** tracked by git.
+     */
+    readonly active: boolean;
+}
+/** Absolute path to the root kill-switch flag file. */
+export declare function deftDirectiveDisableFlagPath(projectRoot: string): string;
+/**
+ * Detect root `.deft-directive-disable`. Presence is file-existence only
+ * (empty or short comment OK). Deposit presence is reported but never treated
+ * as inconsistent (#3039 vs #2926).
+ *
+ * Enforcement short-circuit uses `state.active` (present && !trackedByGit).
+ */
+export declare function detectDeftDirectiveDisable(projectRoot: string, seams?: DeftDirectiveDisableSeams): DeftDirectiveDisableState;
+/**
+ * True when the local (untracked) kill-switch is active for enforcement
+ * short-circuit. Tracked flags return false so hooks stay enforced.
+ */
+export declare function isDeftDirectiveDisableActive(projectRoot: string, seams?: DeftDirectiveDisableSeams): boolean;
+/**
+ * Full operator-facing message for the kill-switch, optionally combined with
+ * permanent opt-out when both flags are present.
+ */
+export declare function formatDeftDirectiveDisableMessage(options?: {
+    readonly permanentOptOutAlsoPresent?: boolean;
+    readonly trackedByGit?: boolean;
+    readonly oneLine?: boolean;
+}): string;
+//# sourceMappingURL=deft-directive-disable.d.ts.map

package/dist/policy/deft-directive-disable.js

@@ -0,0 +1,167 @@
+/**
+ * Temporary test/local kill-switch for Directive enforcement (#3039).
+ *
+ * Presence of root `.deft-directive-disable` means Directive **enforcement** is
+ * OFF (hooks, session ritual, automation) while the deposit may remain — **only
+ * when the file is not tracked by git**. A committed flag is misconfig: doctor
+ * warns and enforcement stays ON (repository-controlled content must not disable
+ * hooks for downstream clones).
+ *
+ * Distinct from `.no-deft-directive` (#2926 permanent opt-out): flag+deposit is
+ * **not** inconsistent here.
+ *
+ * Product choices (v1):
+ * - Flag is **root-only** (workspace root the tool opened).
+ * - Flag **must be gitignored** (canonical baseline); committed flag → doctor
+ *   warns and does **not** short-circuit enforcement.
+ * - Deposit presence is **OK**.
+ * - Full re-enable requires: delete the file **and** start a **new** agent session.
+ * - Precedence: active kill-switch first, then `.no-deft-directive`, else normal.
+ */
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
+/** Canonical root-only filename (lowercase). Presence = candidate flag. */
+export const DEFT_DIRECTIVE_DISABLE_FLAG_NAME = ".deft-directive-disable";
+/** Gitignore entry the deposit must ensure (same as flag name). */
+export const DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE = DEFT_DIRECTIVE_DISABLE_FLAG_NAME;
+/**
+ * Canonical recovery message when Directive is disabled by the test kill-switch.
+ * Surfaces (doctor, agent, CLI, hooks) share this wording.
+ */
+export const DEFT_DIRECTIVE_DISABLE_RECOVERY_MESSAGE = "Directive is DISABLED for this project via root `.deft-directive-disable` (test/local kill-switch).\n" +
+    "Deposit may still be present; enforcement (hooks, session ritual, automation) will not run.\n" +
+    "\n" +
+    "To fully re-enable Directive:\n" +
+    "  1. Delete the file:  rm .deft-directive-disable   (or equivalent)\n" +
+    "  2. Start a NEW agent session (reload AGENTS / host skills / hooks)\n" +
+    "Until both are done, Directive is not fully operational.";
+/** One-line summary for log lines and short CLI output. */
+export const DEFT_DIRECTIVE_DISABLE_ONE_LINE = "Directive disabled via `.deft-directive-disable` (test/local kill-switch; deposit OK)";
+/** Doctor/status label when the kill-switch is active (local / untracked). */
+export const DEFT_DIRECTIVE_DISABLE_STATUS = "disabled-test-kill-switch";
+/**
+ * Warning when the kill-switch file is tracked by git (should be gitignored).
+ * Tracked flags do **not** disable enforcement.
+ */
+export const DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING = "Misconfig: `.deft-directive-disable` is tracked by git. The flag must be gitignored (local kill-switch only). Untrack it and ensure `.gitignore` covers the path. Enforcement is NOT disabled while the flag is tracked.";
+/** Cap git probe so hot-path hooks never hang on a slow VCS call. */
+const GIT_TRACKED_PROBE_TIMEOUT_MS = 1500;
+/** Process-local cache: avoid re-spawning git on every PreToolUse while the flag is present. */
+const trackedProbeCache = new Map();
+const TRACKED_PROBE_CACHE_TTL_MS = 30_000;
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsGitTracked(projectRoot, relPath) {
+    const cacheKey = `${projectRoot}\0${relPath}`;
+    const now = Date.now();
+    const cached = trackedProbeCache.get(cacheKey);
+    if (cached !== undefined && now - cached.atMs < TRACKED_PROBE_CACHE_TTL_MS) {
+        return cached.tracked;
+    }
+    let tracked = false;
+    try {
+        const out = execFileSync("git", ["ls-files", "--", relPath], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TRACKED_PROBE_TIMEOUT_MS,
+        });
+        tracked = out.trim().length > 0;
+    }
+    catch {
+        tracked = false;
+    }
+    trackedProbeCache.set(cacheKey, { tracked, atMs: now });
+    return tracked;
+}
+/** Absolute path to the root kill-switch flag file. */
+export function deftDirectiveDisableFlagPath(projectRoot) {
+    return resolve(projectRoot, DEFT_DIRECTIVE_DISABLE_FLAG_NAME);
+}
+/**
+ * Detect root `.deft-directive-disable`. Presence is file-existence only
+ * (empty or short comment OK). Deposit presence is reported but never treated
+ * as inconsistent (#3039 vs #2926).
+ *
+ * Enforcement short-circuit uses `state.active` (present && !trackedByGit).
+ */
+export function detectDeftDirectiveDisable(projectRoot, seams = {}) {
+    const flagPath = deftDirectiveDisableFlagPath(projectRoot);
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const isGitTracked = seams.isGitTracked ?? defaultIsGitTracked;
+    const present = isFile(flagPath);
+    const depositPresent = isDir(join(projectRoot, CANONICAL_INSTALL_ROOT));
+    let trackedByGit = false;
+    if (present) {
+        if (seams.skipTrackedCache && seams.isGitTracked === undefined) {
+            // Fresh probe without reading process cache (doctor / one-shot CLI).
+            try {
+                const out = execFileSync("git", ["ls-files", "--", DEFT_DIRECTIVE_DISABLE_FLAG_NAME], {
+                    cwd: projectRoot,
+                    encoding: "utf8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                    timeout: GIT_TRACKED_PROBE_TIMEOUT_MS,
+                });
+                trackedByGit = out.trim().length > 0;
+            }
+            catch {
+                trackedByGit = false;
+            }
+        }
+        else {
+            trackedByGit = isGitTracked(projectRoot, DEFT_DIRECTIVE_DISABLE_FLAG_NAME);
+        }
+    }
+    return {
+        present,
+        flagPath,
+        depositPresent,
+        trackedByGit,
+        active: present && !trackedByGit,
+    };
+}
+/**
+ * True when the local (untracked) kill-switch is active for enforcement
+ * short-circuit. Tracked flags return false so hooks stay enforced.
+ */
+export function isDeftDirectiveDisableActive(projectRoot, seams = {}) {
+    return detectDeftDirectiveDisable(projectRoot, seams).active;
+}
+/**
+ * Full operator-facing message for the kill-switch, optionally combined with
+ * permanent opt-out when both flags are present.
+ */
+export function formatDeftDirectiveDisableMessage(options = {}) {
+    const parts = [];
+    if (options.oneLine) {
+        parts.push(DEFT_DIRECTIVE_DISABLE_ONE_LINE);
+    }
+    else {
+        parts.push(DEFT_DIRECTIVE_DISABLE_RECOVERY_MESSAGE);
+    }
+    if (options.permanentOptOutAlsoPresent) {
+        parts.push("Also present: root `.no-deft-directive` (permanent opt-out). Install/update fail-closed semantics still apply for that flag.");
+    }
+    if (options.trackedByGit) {
+        parts.push(DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING);
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=deft-directive-disable.js.map

package/dist/policy/delivery-branch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Typed plan.policy.deliveryBranch (#3041).
+ *
+ * Distinct from swarm/PR `baseBranch` (integration target for PRs / finalize
+ * sweep PRs). deliveryBranch is where shipped work must land for a delivered
+ * completion disposition.
+ */
+import { type GitRunner } from "../session/git.js";
+export declare const FIELD_DELIVERY_BRANCH = "plan.policy.deliveryBranch";
+export declare const FIELD_DELIVERY_BRANCH_CLI_ALIAS = "deliveryBranch";
+/** Framework fallback when neither policy nor git default can be resolved. */
+export declare const DEFAULT_DELIVERY_BRANCH_FALLBACK = "master";
+export type DeliveryBranchSource = "typed" | "git-default" | "default-fallback" | "default-on-error";
+export interface DeliveryBranchResult {
+    readonly branch: string;
+    readonly source: DeliveryBranchSource;
+    readonly error: string | null;
+}
+/**
+ * Resolve the project's delivery branch (#3041).
+ *
+ * Order: typed plan.policy.deliveryBranch → git remote default → local main/master → "master".
+ */
+export declare function resolveDeliveryBranch(projectRoot: string, runGit?: GitRunner): DeliveryBranchResult;
+export interface DeliveryBranchPolicyField {
+    readonly name: string;
+    readonly current: string;
+    readonly default: string;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=deliveryBranch` (#3041). */
+export declare function inspectDeliveryBranch(_data: Record<string, unknown> | null, projectRoot?: string): DeliveryBranchPolicyField;
+//# sourceMappingURL=delivery-branch.d.ts.map

package/dist/policy/delivery-branch.js

@@ -0,0 +1,124 @@
+/**
+ * Typed plan.policy.deliveryBranch (#3041).
+ *
+ * Distinct from swarm/PR `baseBranch` (integration target for PRs / finalize
+ * sweep PRs). deliveryBranch is where shipped work must land for a delivered
+ * completion disposition.
+ */
+import { defaultGitRunner } from "../session/git.js";
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+export const FIELD_DELIVERY_BRANCH = "plan.policy.deliveryBranch";
+export const FIELD_DELIVERY_BRANCH_CLI_ALIAS = "deliveryBranch";
+/** Framework fallback when neither policy nor git default can be resolved. */
+export const DEFAULT_DELIVERY_BRANCH_FALLBACK = "master";
+function defaultBranchCandidates(projectRoot, runGit) {
+    const sym = runGit(projectRoot, ["symbolic-ref", "refs/remotes/origin/HEAD", "--short"]);
+    if (sym.code === 0 && sym.stdout) {
+        const trimmed = sym.stdout.trim();
+        // origin/main → main
+        const parts = trimmed.split("/");
+        const name = (parts.slice(1).join("/") || parts[0] || "").trim();
+        if (name.length > 0) {
+            return [name];
+        }
+    }
+    const candidates = [];
+    for (const branch of ["main", "master"]) {
+        const check = runGit(projectRoot, [
+            "show-ref",
+            "--verify",
+            "--quiet",
+            `refs/remotes/origin/${branch}`,
+        ]);
+        if (check.code === 0) {
+            candidates.push(branch);
+        }
+    }
+    if (candidates.length === 0) {
+        for (const branch of ["main", "master"]) {
+            const local = runGit(projectRoot, [
+                "show-ref",
+                "--verify",
+                "--quiet",
+                `refs/heads/${branch}`,
+            ]);
+            if (local.code === 0) {
+                candidates.push(branch);
+            }
+        }
+    }
+    return candidates;
+}
+/**
+ * Resolve the project's delivery branch (#3041).
+ *
+ * Order: typed plan.policy.deliveryBranch → git remote default → local main/master → "master".
+ */
+export function resolveDeliveryBranch(projectRoot, runGit = defaultGitRunner) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        const gitDefault = defaultBranchCandidates(projectRoot, runGit)[0];
+        if (gitDefault !== undefined) {
+            return { branch: gitDefault, source: "git-default", error: err };
+        }
+        return {
+            branch: DEFAULT_DELIVERY_BRANCH_FALLBACK,
+            source: "default-fallback",
+            error: err,
+        };
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        const gitDefault = defaultBranchCandidates(projectRoot, runGit)[0];
+        return {
+            branch: gitDefault ?? DEFAULT_DELIVERY_BRANCH_FALLBACK,
+            source: gitDefault !== undefined ? "git-default" : "default-fallback",
+            error: "PROJECT-DEFINITION 'plan' is not an object",
+        };
+    }
+    const policyBlock = readPlanPolicy(plan);
+    if (typeof policyBlock === "object" &&
+        policyBlock !== null &&
+        !Array.isArray(policyBlock) &&
+        "deliveryBranch" in policyBlock) {
+        const raw = policyBlock.deliveryBranch;
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            const gitDefault = defaultBranchCandidates(projectRoot, runGit)[0];
+            return {
+                branch: gitDefault ?? DEFAULT_DELIVERY_BRANCH_FALLBACK,
+                source: "default-on-error",
+                error: `plan.policy.deliveryBranch must be a non-empty string; got ${typeof raw}`,
+            };
+        }
+        return { branch: raw.trim(), source: "typed", error: null };
+    }
+    const gitDefault = defaultBranchCandidates(projectRoot, runGit)[0];
+    if (gitDefault !== undefined) {
+        return { branch: gitDefault, source: "git-default", error: null };
+    }
+    return {
+        branch: DEFAULT_DELIVERY_BRANCH_FALLBACK,
+        source: "default-fallback",
+        error: null,
+    };
+}
+/** Inspector row for `task policy:show --field=deliveryBranch` (#3041). */
+export function inspectDeliveryBranch(_data, projectRoot) {
+    if (projectRoot === undefined || projectRoot.length === 0) {
+        return {
+            name: FIELD_DELIVERY_BRANCH,
+            current: DEFAULT_DELIVERY_BRANCH_FALLBACK,
+            default: DEFAULT_DELIVERY_BRANCH_FALLBACK,
+            source: "default",
+        };
+    }
+    const resolved = resolveDeliveryBranch(projectRoot);
+    return {
+        name: FIELD_DELIVERY_BRANCH,
+        current: resolved.branch,
+        default: DEFAULT_DELIVERY_BRANCH_FALLBACK,
+        source: resolved.source,
+    };
+}
+//# sourceMappingURL=delivery-branch.js.map

package/dist/policy/index.d.ts

@@ -2,6 +2,8 @@ export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
 export * from "./capacity.js";
 export * from "./decisions.js";
+export * from "./deft-directive-disable.js";
+export * from "./delivery-branch.js";
 export * from "./disclosure.js";
 export * from "./host-hooks.js";
 export * from "./hotfix-criteria.js";

package/dist/policy/index.js

@@ -1,3 +1,4 @@
+import { FIELD_DELIVERY_BRANCH, FIELD_DELIVERY_BRANCH_CLI_ALIAS, inspectDeliveryBranch, } from "./delivery-branch.js";
 import { FIELD_HOST_HOOKS, FIELD_HOST_HOOKS_CLI_ALIAS, inspectHostHooks } from "./host-hooks.js";
 import { FIELD_HOTFIX_CRITERIA, FIELD_HOTFIX_CRITERIA_CLI_ALIAS, inspectHotfixCriteria, } from "./hotfix-criteria.js";
 import { readPlanPolicy } from "./plan-extensions.js";
@@ -12,6 +13,8 @@ export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
 export * from "./capacity.js";
 export * from "./decisions.js";
+export * from "./deft-directive-disable.js";
+export * from "./delivery-branch.js";
 export * from "./disclosure.js";
 export * from "./host-hooks.js";
 export * from "./hotfix-criteria.js";
@@ -38,6 +41,7 @@ export const FIELD_TRIAGE_RANKING_LABELS = "plan.policy.triageRankingLabels";
 export const FIELD_TRIAGE_AUTO_CLASSIFY = "plan.policy.triageAutoClassify";
 export const FIELD_TRIAGE_HOLD_MARKERS = "plan.policy.triageHoldMarkers";
 export const FIELD_SWARM_SUBAGENT_BACKEND = "plan.policy.swarmSubagentBackend";
+// deliveryBranch also exported from delivery-branch.js via export *
 export const DEFAULT_SESSION_RITUAL_STALENESS_HOURS = 4;
 export const DEFAULT_TRIAGE_SCOPE_VALUE = [
     { rule: "all-open" },
@@ -296,6 +300,15 @@ function inspectHotfixCriteriaField(data) {
         source: field.source,
     };
 }
+function inspectDeliveryBranchField(data, projectRoot) {
+    const field = inspectDeliveryBranch(data, projectRoot);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
 const REGISTERED_POLICIES = [
     inspectAllowDirectCommits,
     inspectWipCap,
@@ -308,6 +321,7 @@ const REGISTERED_POLICIES = [
         emptyIsTyped: true,
     }),
     inspectSwarmSubagentBackend,
+    inspectDeliveryBranchField,
     inspectHostHooksField,
     inspectStalenessTicklerField,
     inspectRuntimeAuthorityField,
@@ -337,7 +351,9 @@ export function inspectOnePolicy(name, projectRoot) {
                             ? FIELD_REQUIRE_HUMAN_MERGE
                             : name === FIELD_HOTFIX_CRITERIA_CLI_ALIAS
                                 ? FIELD_HOTFIX_CRITERIA
-                                : name;
+                                : name === FIELD_DELIVERY_BRANCH_CLI_ALIAS
+                                    ? FIELD_DELIVERY_BRANCH
+                                    : name;
     for (const field of inspectAllPolicies(projectRoot)) {
         if (field.name === normalized)
             return field;

package/dist/scope/brief-io.d.ts

@@ -22,5 +22,7 @@ export type AtomicWriteBriefResult = {
     readonly message: string;
 };
 /** Validate then atomically persist a brief (temp file + rename). */
-export declare function atomicWriteBrief(filePath: string, data: JsonObject, vbriefRoot: string): AtomicWriteBriefResult;
+export declare function atomicWriteBrief(filePath: string, data: JsonObject, vbriefRoot: string, options?: {
+    readonly projectRoot?: string;
+}): AtomicWriteBriefResult;
 //# sourceMappingURL=brief-io.d.ts.map

package/dist/scope/brief-io.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { atomicWriteText } from "../cache/io.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { pythonJsonPretty } from "../vbrief-build/json.js";
@@ -60,13 +60,15 @@ export function validateBriefForPersist(filePath, data, vbriefRoot) {
     return errors.join("; ");
 }
 /** Validate then atomically persist a brief (temp file + rename). */
-export function atomicWriteBrief(filePath, data, vbriefRoot) {
+export function atomicWriteBrief(filePath, data, vbriefRoot, options = {}) {
     const validationError = validateBriefForPersist(filePath, data, vbriefRoot);
     if (validationError !== null) {
         return { ok: false, message: validationError };
     }
+    // #3042: contain against projectRoot (parent of xbrief/), not dirname(filePath).
+    const projectRoot = options.projectRoot ?? dirname(resolve(vbriefRoot));
     try {
-        atomicWriteText(filePath, formatBriefJson(data));
+        atomicWriteText(filePath, formatBriefJson(data), { projectRoot });
         return { ok: true };
     }
     catch (err) {

package/dist/scope/delivery-evidence.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 { type GitRunner } from "../session/git.js";
+/** Handoff states that Git delivery can assert (deploy/UAT never inferred). */
+export declare const HANDOFF_STATES: readonly ["implemented", "pr_open", "merged_to_integration", "delivered"];
+export type HandoffState = (typeof HANDOFF_STATES)[number];
+/** Explicit non-delivery terminal dispositions (never render as shipped). */
+export declare const NON_DELIVERY_DISPOSITIONS: readonly ["cancelled", "superseded", "experiment_archived", "accepted_not_delivered"];
+export type NonDeliveryDisposition = (typeof NON_DELIVERY_DISPOSITIONS)[number];
+/** Delivery verification outcome for completion provenance. */
+export type DeliveryDisposition = "delivered" | "merged_to_integration" | "not_delivered" | NonDeliveryDisposition | "unknown" | "unverified";
+export interface CompletionProvenance {
+    readonly repository: string | null;
+    readonly implementationCommit: string | null;
+    readonly prNumber: number | null;
+    readonly prBase: string | null;
+    readonly mergeCommit: string | null;
+    readonly deliveryBranch: string;
+    readonly deliveryCommit: string | null;
+    readonly verifiedAt: string;
+    readonly verifier: string;
+    readonly disposition: DeliveryDisposition;
+    readonly handoffState: HandoffState | "unknown";
+    /** Always null unless explicitly supplied — never inferred from Git (#3041). */
+    readonly deployed: boolean | null;
+    /** Always null unless explicitly supplied — never inferred from Git (#3041). */
+    readonly uatVerified: boolean | null;
+}
+export interface DeliveryEvidenceInput {
+    readonly repository?: string | null;
+    readonly implementationCommit?: string | null;
+    readonly prNumber?: number | null;
+    readonly prBase?: string | null;
+    readonly mergeCommit?: string | null;
+    readonly deliveryBranch?: string | null;
+    readonly deliveryCommit?: string | null;
+    readonly mergedAt?: string | null;
+    /** Explicit deploy/UAT (optional; never auto-filled from Git). */
+    readonly deployed?: boolean | null;
+    readonly uatVerified?: boolean | null;
+    readonly verifier?: string | null;
+}
+export interface DeliveryGateOptions {
+    readonly projectRoot: string;
+    readonly plan: Record<string, unknown>;
+    readonly nowIso: string;
+    readonly evidence?: DeliveryEvidenceInput | null;
+    readonly nonDeliveryDisposition?: NonDeliveryDisposition | null;
+    readonly runGit?: GitRunner;
+    readonly verifier?: string;
+    /**
+     * When true, skip remote refresh + ancestry (tests only that inject pre-validated
+     * evidence). Production callers leave this false.
+     */
+    readonly assumeEvidenceValidated?: boolean;
+}
+export interface DeliveryGateResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly provenance: CompletionProvenance | null;
+    readonly codeBearing: boolean;
+}
+export declare function isNonDeliveryDisposition(value: unknown): value is NonDeliveryDisposition;
+/** True when the brief is treated as code-bearing for the delivery gate (#3041). */
+export declare function isCodeBearingScope(plan: Record<string, unknown>): boolean;
+export declare function hasGithubIssueRef(plan: Record<string, unknown>): boolean;
+/**
+ * Classify stored completion provenance for read paths.
+ * Legacy completed records without provenance → unknown/unverified (not delivered).
+ */
+export declare function classifyStoredDeliveryDisposition(plan: Record<string, unknown>): DeliveryDisposition;
+/**
+ * Refresh the remote delivery ref. Failure blocks delivered completion (#3041).
+ */
+export declare function refreshRemoteDeliveryRef(projectRoot: string, deliveryBranch: string, runGit?: GitRunner): {
+    ok: boolean;
+    error: string | null;
+    remoteRef: string;
+};
+/**
+ * Validate that mergeCommit is an ancestor of the refreshed remote delivery ref.
+ */
+export declare function verifyDeliveryAncestry(projectRoot: string, mergeCommit: string, deliveryBranch: string, runGit?: GitRunner): {
+    ok: boolean;
+    error: string | null;
+    remoteTip: string | 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 declare function evaluateDeliveryGate(options: DeliveryGateOptions): DeliveryGateResult;
+/** Stamp completion provenance onto plan.metadata (mutates plan). */
+export declare function stampDeliveryProvenance(plan: Record<string, unknown>, provenance: CompletionProvenance): void;
+/**
+ * Parse a PR REST payload into delivery evidence fields.
+ * Expects GitHub pulls API shape (merged_at, base.ref, merge_commit_sha, …).
+ */
+export declare function evidenceFromPrPayload(payload: Record<string, unknown>, prNumber: number, repository: string | null, deliveryBranch?: string | null): DeliveryEvidenceInput;
+//# sourceMappingURL=delivery-evidence.d.ts.map