@deftai/directive-core 0.91.0 → 0.93.0

package/dist/init-deposit/slash-deposit.js

@@ -0,0 +1,174 @@
+/**
+ * Multi-host init/update deposit for native slash command files (#3054 / epic #55).
+ *
+ * Wires #3053 emitters into the init/update deposit path:
+ * - Default enabled set = hosts with real emitters (L6)
+ * - Per-host opt-out via `plan.policy.hostSlashCommands`
+ * - Idempotent managed rewrite (no duplicate pile-up)
+ * - Prefer commit of **managed product paths only** (L8) — exact allowlist, not whole dirs
+ *
+ * Parallel to agent-hooks deposit; does not touch hook JSON configs.
+ *
+ * Ownership: only create/update/remove files that are missing or still look like
+ * Directive thin wrappers (`isThinWrapperMarkdown`). Consumer-customized content
+ * at a product filename is left untouched.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { assertDepositContained } from "../deposit/contain.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { isHostSlashCommandDepositEnabled, loadHostSlashCommandsPolicyFromProject, } from "../policy/host-slash-commands.js";
+import { emitHostCommandFiles, getHostCommandLayout, isThinWrapperMarkdown, listSlashEmitterHosts, } from "../slash/index.js";
+import { listProductCommands, logicalIdToFilename } from "../slash/product-set.js";
+/**
+ * Write thin-wrapper command/prompt files for every policy-enabled host.
+ *
+ * Idempotent: skips files whose on-disk bytes already match emission.
+ * Ownership-safe: never overwrites non-thin consumer customizations at product paths.
+ * Opt-out: removes managed thin wrappers only (leaves user customizations alone).
+ */
+export function writeSlashCommandDeposit(projectRoot, io = { printf: () => undefined }, policy = loadHostSlashCommandsPolicyFromProject(projectRoot)) {
+    const rootAbs = resolve(projectRoot);
+    const writtenPaths = [];
+    const removedPaths = [];
+    const preservedCustomPaths = [];
+    const depositedHosts = [];
+    const skippedHosts = [];
+    for (const hostId of listSlashEmitterHosts()) {
+        if (!isHostSlashCommandDepositEnabled(hostId, policy)) {
+            skippedHosts.push(hostId);
+            removedPaths.push(...stripManagedHostCommandFiles(rootAbs, hostId));
+            continue;
+        }
+        depositedHosts.push(hostId);
+        const files = emitHostCommandFiles(hostId);
+        for (const file of files) {
+            const outcome = writeHostCommandFileIfChanged(rootAbs, file);
+            if (outcome === "written")
+                writtenPaths.push(file.relativePath);
+            if (outcome === "preserved")
+                preservedCustomPaths.push(file.relativePath);
+        }
+    }
+    if (writtenPaths.length > 0) {
+        const hostSummary = depositedHosts.join(", ");
+        io.printf(`Installed Directive slash commands for hosts [${hostSummary}]: ${writtenPaths.length} file(s)\n`);
+    }
+    if (preservedCustomPaths.length > 0) {
+        io.printf(`Preserved non-managed slash command customizations: ${preservedCustomPaths.join(", ")}\n`);
+    }
+    if (removedPaths.length > 0) {
+        io.printf(`Removed Directive-managed slash commands (plan.policy.hostSlashCommands opt-out): ${removedPaths.join(", ")}\n`);
+    }
+    if (writtenPaths.length === 0 && removedPaths.length === 0) {
+        if (depositedHosts.length === 0) {
+            io.printf("Directive slash commands: all hosts opted out via plan.policy.hostSlashCommands.\n");
+        }
+        else {
+            io.printf("Directive slash commands already current.\n");
+        }
+    }
+    return {
+        changed: writtenPaths.length + removedPaths.length > 0,
+        writtenPaths,
+        removedPaths,
+        preservedCustomPaths,
+        depositedHosts,
+        skippedHosts,
+    };
+}
+/**
+ * Exact repo-relative product command paths (all emitter hosts).
+ * Used by installerManagedMatchers for L8 prefer-commit staging without
+ * claiming whole host command directories (consumer custom files stay app-owned).
+ */
+export function slashCommandManagedExactPaths() {
+    const paths = [];
+    for (const hostId of listSlashEmitterHosts()) {
+        const dir = getHostCommandLayout(hostId).relativeDir;
+        for (const cmd of listProductCommands()) {
+            paths.push(`${dir}/${logicalIdToFilename(cmd.logicalId)}`);
+        }
+    }
+    return paths;
+}
+function isManagedThinContent(raw, file) {
+    return raw === file.contents || isThinWrapperMarkdown(raw, file.dispatchPath);
+}
+function writeHostCommandFileIfChanged(projectRoot, file) {
+    const absolute = join(projectRoot, file.relativePath);
+    assertDepositContained(projectRoot, absolute);
+    if (existsSync(absolute)) {
+        let raw;
+        try {
+            raw = readFileSync(absolute, "utf8");
+        }
+        catch {
+            // Unreadable existing file: do not clobber consumer content.
+            return "preserved";
+        }
+        if (raw === file.contents)
+            return "unchanged";
+        // Ownership gate: only rewrite managed thin wrappers.
+        if (!isManagedThinContent(raw, file)) {
+            return "preserved";
+        }
+    }
+    const parent = dirname(absolute);
+    mkdirSync(parent, { recursive: true });
+    // Atomic replace via temp under project root (#2951).
+    const tmpName = `${basename(absolute)}.deft-${process.pid}.tmp`;
+    const temporary = join(parent, tmpName);
+    try {
+        containedWrite({
+            root: projectRoot,
+            target: temporary,
+            data: file.contents,
+            mode: "replace",
+        });
+        renameSync(temporary, absolute);
+    }
+    catch (err) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+    return "written";
+}
+/**
+ * On opt-out, remove only product-set managed thin wrappers for that host.
+ * User-authored or non-thin files under the host command dir are left untouched.
+ */
+function stripManagedHostCommandFiles(projectRoot, hostId) {
+    const removed = [];
+    const files = emitHostCommandFiles(hostId);
+    for (const file of files) {
+        const absolute = join(projectRoot, file.relativePath);
+        assertDepositContained(projectRoot, absolute);
+        if (!existsSync(absolute))
+            continue;
+        let raw;
+        try {
+            raw = readFileSync(absolute, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!isManagedThinContent(raw, file)) {
+            continue;
+        }
+        try {
+            rmSync(absolute, { force: true });
+            removed.push(file.relativePath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=slash-deposit.js.map

package/dist/orchestration/probe-session.d.ts

@@ -36,7 +36,11 @@ export declare function detectGitBranch(projectRoot: string, execGit?: (args: st
 }): string;
 /** Read probe session from project root. */
 export declare function readSession(projectRoot: string): ProbeSession | null;
-/** Atomically persist session to .deft/probe-session.json. */
+/**
+ * Atomically persist session to .deft/probe-session.json.
+ * #3042: contain against projectRoot; refuse escaping `.deft` symlink parents
+ * (no bare open/write/rename).
+ */
 export declare function writeSession(projectRoot: string, session: ProbeSession): string;
 export declare function startSession(projectRoot: string, options: {
     target: string;

package/dist/orchestration/probe-session.js

@@ -3,8 +3,10 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, } from "node:fs";
+import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 export const SCHEMA_VERSION = 1;
 export const SESSION_RELPATH = [".deft", "probe-session.json"];
 export const STATE_INTERROGATE = "interrogate";
@@ -188,11 +190,16 @@ export function readSession(projectRoot) {
         completed_at: completedAt,
     };
 }
-/** Atomically persist session to .deft/probe-session.json. */
+/**
+ * Atomically persist session to .deft/probe-session.json.
+ * #3042: contain against projectRoot; refuse escaping `.deft` symlink parents
+ * (no bare open/write/rename).
+ */
 export function writeSession(projectRoot, session) {
-    const sessionFile = sessionPath(projectRoot);
-    mkdirSync(join(projectRoot, ".deft"), { recursive: true });
-    const tmpName = join(projectRoot, ".deft", `.probe-session.${randomBytes(8).toString("hex")}.json.tmp`);
+    const root = resolve(projectRoot);
+    const sessionFile = sessionPath(root);
+    assertWriteTargetSafe(root, sessionFile);
+    const tmpName = join(root, ".deft", `.probe-session.${randomBytes(8).toString("hex")}.json.tmp`);
     const sortedPayload = sessionToDict(session);
     const sortedKeys = Object.keys(sortedPayload).sort();
     const sortedObj = {};
@@ -200,20 +207,24 @@ export function writeSession(projectRoot, session) {
         sortedObj[k] = sortedPayload[k];
     }
     const finalContent = `${JSON.stringify(sortedObj, null, 2)}\n`;
-    const fd = openSync(tmpName, "w");
     try {
-        writeSync(fd, finalContent, undefined, "utf8");
+        containedWrite({
+            root,
+            target: tmpName,
+            data: finalContent,
+            mode: "create",
+        });
+        renameSync(tmpName, sessionFile);
+    }
+    catch (err) {
         try {
-            fdatasyncSync(fd);
+            rmSync(tmpName, { force: true });
         }
         catch {
-            // best effort
+            /* best-effort cleanup */
         }
+        throw err;
     }
-    finally {
-        closeSync(fd);
-    }
-    renameSync(tmpName, sessionFile);
     return sessionFile;
 }
 export function startSession(projectRoot, options) {

package/dist/platform/agents-md.js

@@ -324,7 +324,7 @@ export function applyAgentsRefresh(projectRoot, options = {}, seams = {}, lockDe
             const writable = AGENTS_REFRESH_WRITABLE_STATES.has(state) && typeof newContent === "string";
             return { state, path, wrote: false, writable };
         }
-        atomicWriteText(path, newContent);
+        atomicWriteText(path, newContent, { projectRoot });
         return { state, path, wrote: true, writable: true };
     }, lockDeps);
 }

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