@deftai/directive-core 0.73.0 → 0.73.1

package/dist/branch/evaluate.js

@@ -1,5 +1,6 @@
 import { recordBypassSignal, recordGateCatch } from "../events/attribution-ledger.js";
 import { disclosureLine } from "../policy/disclosure.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
 import { currentBranch, GitNotFoundError } from "./git.js";
 export const DEFAULT_BRANCHES = new Set(["master", "main"]);
@@ -32,7 +33,7 @@ function buildBlockMessage(branch, result) {
     if (result.deprecationWarning !== null) {
         parts.push(`  Note: ${result.deprecationWarning}`);
     }
-    parts.push("", "  How to proceed:", "    • Create a feature branch:  git switch -c feat/<name>", "    • Or opt out via the typed surface:", "        task policy:allow-direct-commits -- --confirm", `    • Or set the emergency-escape env-var:  ${ENV_BYPASS}=1`, "", "  See README.md (Branch policy) and skills/deft-directive-setup/", "  Phase 2 Step 9 (capability-cost disclosure).");
+    parts.push("", "  How to proceed:", "    • Create a feature branch:  git switch -c feat/<name>", "    • Or opt out via the typed surface:", `        ${policyColonInvocation("allow-direct-commits", " -- --confirm")}`, `    • Or set the emergency-escape env-var:  ${ENV_BYPASS}=1`, "", "  See README.md (Branch policy) and skills/deft-directive-setup/", "  Phase 2 Step 9 (capability-cost disclosure).");
     return parts.join("\n");
 }
 /**

package/dist/deposit/copy-tree.js

@@ -7,12 +7,29 @@
  *
  * Refs #1942 S1, #1477.
  */
-import { createReadStream, createWriteStream } from "node:fs";
-import { chmod, lstat, mkdir, readdir, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, readFile, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { pipeline } from "node:stream/promises";
 const DEFAULT_FILE_MODE = 0o644;
 const DEFAULT_DIR_MODE = 0o755;
+async function assertDestinationIsNotSymlink(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            throw new Error(`copyTree: refusing to write through destination symlink ${path}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("copyTree: refusing")) {
+            throw err;
+        }
+        if (err.code === "ENOENT") {
+            // Missing paths are created by the caller; only pre-existing symlinks matter.
+            return;
+        }
+        throw err;
+    }
+}
 async function copyFilePreserveMode(src, dst) {
     let mode = DEFAULT_FILE_MODE;
     try {
@@ -23,12 +40,19 @@ async function copyFilePreserveMode(src, dst) {
         // Stat failure is non-fatal — fall back to 0o644 (mirrors Go copyFile).
     }
     await mkdir(dirname(dst), { recursive: true, mode: DEFAULT_DIR_MODE });
-    await pipeline(createReadStream(src), createWriteStream(dst, { mode }));
-    // createWriteStream mode applies on create; chmod ensures the final bits match
-    // the source even when the destination file already existed.
-    await chmod(dst, mode);
+    await assertDestinationIsNotSymlink(dst);
+    const handle = await open(dst, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, mode);
+    try {
+        await handle.writeFile(await readFile(src));
+        // Use the opened handle, not the path, so chmod cannot follow a swapped symlink.
+        await handle.chmod(mode);
+    }
+    finally {
+        await handle.close();
+    }
 }
 async function copyDirContents(src, dst) {
+    await assertDestinationIsNotSymlink(dst);
     await mkdir(dst, { recursive: true, mode: DEFAULT_DIR_MODE });
     const entries = await readdir(src, { withFileTypes: true });
     for (const entry of entries) {

package/dist/init-deposit/hygiene.d.ts

@@ -17,6 +17,12 @@ export declare function installerManagedMatchers(): InstallerManagedMatcher[];
 export declare function installerManagedGuardEre(): string;
 export declare function isInstallerManagedPath(path: string): boolean;
 export interface FrameworkStagePathsOptions {
+    /**
+     * Include the vendored `.deft/core` payload in the stage set. Defaults to
+     * `true` for init and real payload swaps. No-op updates set this to `false`
+     * so CRLF-only core noise cannot be staged while safe projections are repaired.
+     */
+    readonly includeCore?: boolean;
     /**
      * Include the project-root ``Taskfile.yml`` in the stage set. Defaults to
      * ``false``: unlike the other allowlisted paths, ``Taskfile.yml`` is a

package/dist/init-deposit/hygiene.js

@@ -82,7 +82,10 @@ export function frameworkStagePaths(projectDir, deftDir, options = {}) {
         paths.push(normalized);
     };
     const relDeft = relative(projectDir, deftDir);
-    if (relDeft && !relDeft.startsWith("..") && !relDeft.startsWith("/")) {
+    if (options.includeCore !== false &&
+        relDeft &&
+        !relDeft.startsWith("..") &&
+        !relDeft.startsWith("/")) {
         add(relDeft);
     }
     for (const matcher of installerManagedMatchers()) {
@@ -228,6 +231,7 @@ function actuallyStagedPaths(stagePaths, cachedNames) {
 export function depositStagePaths(projectDir, options = {}) {
     const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
     const stagePaths = frameworkStagePaths(projectDir, deftDir, {
+        includeCore: options.includeCore,
         includeTaskfile: options.includeTaskfile ?? false,
     });
     const { staged } = stageFrameworkPaths(projectDir, stagePaths, options);

package/dist/init-deposit/refresh.d.ts

@@ -22,12 +22,15 @@ export interface RefreshDepositResult {
     readonly contentVersion: string;
     readonly engineVersion: string;
     readonly previousDepositVersion: string | null;
+    readonly alreadyCurrent: boolean;
+    readonly strategy: RefreshDepositStrategy;
     readonly agentsMdUpdated: boolean;
     readonly versionSkewNotice: string | null;
     readonly legacyLayout: boolean;
     readonly taskfileWired: boolean;
     readonly stagedPaths: string[];
 }
+export type RefreshDepositStrategy = "file-swap" | "no-op";
 export interface RefreshDepositSeams {
     resolveContentRoot?: () => Promise<string>;
     copyContent?: (src: string, dst: string) => Promise<void>;
@@ -35,6 +38,7 @@ export interface RefreshDepositSeams {
     readEngineVersion?: () => string;
     nowIso?: () => string;
     gitPorcelain?: (projectRoot: string) => string | null;
+    gitSemanticDiffNames?: GitSemanticDiffNames;
     detectLegacy?: (projectDir: string) => LegacyLayoutDetection;
     /**
      * #2266: `git ls-files` probe threaded into the non-destructive `.gitignore`
@@ -101,9 +105,19 @@ export declare function buildDefaultLadderFacts(projectDir: string, facts: Resol
  * manual npm/PATH steps (#2266 a3).
  */
 export declare function selfHealEngine(projectDir: string, facts: ResolutionFacts, io: InitDepositIo, seams?: SelfHealSeams): EngineResolution;
+export type GitSemanticDiffNames = (projectRoot: string, paths: readonly string[]) => readonly string[] | null;
+export interface FrameworkRefreshSideEffectsOptions {
+    readonly readPorcelain?: (root: string) => string | null;
+    readonly readSemanticDiffNames?: GitSemanticDiffNames;
+}
+export interface RefreshSideEffects {
+    readonly files: string[];
+    readonly crlfOnlyCoreFiles: string[];
+    readonly payloadSwapped?: boolean;
+}
 /** Framework-managed uncommitted paths after refresh (#1671). */
-export declare function frameworkRefreshSideEffects(projectDir: string, readPorcelain?: (root: string) => string | null): string[];
-export declare function printRefreshSideEffects(io: InitDepositIo, files: readonly string[]): void;
+export declare function frameworkRefreshSideEffects(projectDir: string, options?: FrameworkRefreshSideEffectsOptions): RefreshSideEffects;
+export declare function printRefreshSideEffects(io: InitDepositIo, effects: RefreshSideEffects): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
 export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs, updateState?: UpdateState): Record<string, unknown>;
 export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;

package/dist/init-deposit/refresh.js

@@ -7,6 +7,7 @@
  *
  * Refs #1942, #1430, #1671.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
@@ -218,11 +219,12 @@ function unquoteGitPath(path) {
     }
     return path;
 }
-function porcelainStatusPaths(porcelain) {
-    const paths = [];
+function porcelainStatusEntries(porcelain) {
+    const entries = [];
     for (const line of porcelain.split("\n")) {
         if (line.length < 4)
             continue;
+        const status = line.slice(0, 2);
         let rest = line.slice(3);
         const arrow = rest.indexOf(" -> ");
         if (arrow >= 0)
@@ -230,43 +232,102 @@ function porcelainStatusPaths(porcelain) {
         const trimmed = unquoteGitPath(rest.trim());
         if (!trimmed)
             continue;
-        paths.push(trimmed.replace(/\\/g, "/"));
+        entries.push({ status, path: trimmed.replace(/\\/g, "/") });
     }
-    return paths;
+    return entries;
 }
-function classifyChangedPaths(changed) {
+function classifyChangedEntries(changed) {
     const core = [];
     const installerManaged = [];
-    for (const path of changed) {
+    for (const entry of changed) {
+        const { path } = entry;
         if (!path)
             continue;
         if (path.startsWith(".deft/core/") || path === ".deft/core") {
-            core.push(path);
+            core.push(entry);
         }
         else if (isInstallerManagedPath(path)) {
-            installerManaged.push(path);
+            installerManaged.push(entry);
         }
     }
     return { core, installerManaged };
 }
+function isCrlfNoiseCandidate(status) {
+    return status.includes("M") && /^[ M]+$/.test(status);
+}
+function normalizeGitNameList(output) {
+    return output
+        .split("\n")
+        .map((line) => line.trim().replace(/\\/g, "/"))
+        .filter(Boolean);
+}
+function gitSemanticDiffNames(projectRoot, paths) {
+    if (paths.length === 0)
+        return [];
+    try {
+        const args = ["diff", "--ignore-cr-at-eol", "--name-only", "--", ...paths];
+        const worktree = execFileSync("git", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const cached = execFileSync("git", ["diff", "--cached", "--ignore-cr-at-eol", "--name-only", "--", ...paths], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return [...new Set([...normalizeGitNameList(worktree), ...normalizeGitNameList(cached)])];
+    }
+    catch {
+        return null;
+    }
+}
 /** Framework-managed uncommitted paths after refresh (#1671). */
-export function frameworkRefreshSideEffects(projectDir, readPorcelain = gitPorcelain) {
+export function frameworkRefreshSideEffects(projectDir, options) {
+    const readPorcelain = options?.readPorcelain ?? gitPorcelain;
+    const readSemanticDiffNames = options?.readSemanticDiffNames ?? gitSemanticDiffNames;
     const porcelain = readPorcelain(projectDir);
     if (porcelain === null)
-        return [];
-    const changed = porcelainStatusPaths(porcelain);
-    const { core, installerManaged } = classifyChangedPaths(changed);
-    const files = [...core, ...installerManaged].sort();
-    return files.length > 0 ? files : [];
+        return { files: [], crlfOnlyCoreFiles: [] };
+    const changed = porcelainStatusEntries(porcelain);
+    const { core, installerManaged } = classifyChangedEntries(changed);
+    const semanticCoreNames = core.length > 0
+        ? readSemanticDiffNames(projectDir, core.map((entry) => entry.path))
+        : [];
+    const semanticCoreSet = semanticCoreNames === null ? null : new Set(semanticCoreNames);
+    const coreFiles = [];
+    const crlfOnlyCoreFiles = [];
+    for (const entry of core) {
+        if (semanticCoreSet !== null &&
+            isCrlfNoiseCandidate(entry.status) &&
+            !semanticCoreSet.has(entry.path)) {
+            crlfOnlyCoreFiles.push(entry.path);
+            continue;
+        }
+        coreFiles.push(entry.path);
+    }
+    const files = [...coreFiles, ...installerManaged.map((entry) => entry.path)].sort();
+    return { files, crlfOnlyCoreFiles: crlfOnlyCoreFiles.sort() };
 }
-export function printRefreshSideEffects(io, files) {
-    if (files.length === 0)
+export function printRefreshSideEffects(io, effects) {
+    if (effects.crlfOnlyCoreFiles.length > 0) {
+        io.printf("\nWindows line-ending note (#2118): suppressed .deft/core CRLF/LF-only noise; " +
+            "ensure .gitattributes contains `.deft/core/** text eol=lf`.\n");
+    }
+    if (effects.files.length === 0)
+        return;
+    if (effects.payloadSwapped === false) {
+        io.printf("\nFramework-managed files still have semantic uncommitted changes:\n");
+        for (const file of effects.files) {
+            io.printf(`  ${file}\n`);
+        }
         return;
+    }
     io.printf("\nAGENTS.md refresh side effects (#1671): the refresh and framework payload swap\n");
     io.printf("left these framework files with uncommitted changes -- they belong in the\n");
     io.printf("framework deposit commit (the installer stages them before printing the\n");
     io.printf("`git add` list below, so there are no post-stage stragglers):\n");
-    for (const file of files) {
+    for (const file of effects.files) {
         io.printf(`  ${file}\n`);
     }
 }
@@ -307,7 +368,8 @@ export function buildUpdateSummaryJson(result, options, updateState) {
         user_config_dir: "",
         skills_created: false,
         payload_layout: "vendored",
-        strategy: "file-swap",
+        strategy: result.strategy,
+        already_current: result.alreadyCurrent,
         dirty_tree: false,
         dirty_files: [],
         staged_paths: result.stagedPaths,
@@ -319,9 +381,12 @@ export function buildUpdateSummaryJson(result, options, updateState) {
     };
 }
 export function printUpdateComplete(result, io, updateState) {
-    io.printf("\n✓ Deft framework payload refreshed.\n\n");
+    io.printf(result.alreadyCurrent
+        ? "\nOK Deft framework payload already current.\n\n"
+        : "\nOK Deft framework payload refreshed.\n\n");
     io.printf(`  Location     : ${result.deftDir}\n`);
     io.printf(`  Content      : v${normalizeVersion(result.contentVersion)}\n`);
+    io.printf(`  Strategy     : ${result.strategy}\n`);
     if (updateState) {
         io.printf(`  State        : ${updateState}\n`);
     }
@@ -356,31 +421,41 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const engineVersion = readEngine();
     const contentVersion = readContentPackageVersion(contentRoot, readPackageVersion);
     const versionSkewNotice = buildVersionSkewNotice(engineVersion, contentVersion, previousDepositVersion);
-    await copyContent(contentRoot, deftDir);
-    await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
-    // #2347: prune framework-source paths that the content package does not ship.
-    // The additive file-swap never removes them, causing the deposit-hygiene
-    // advisory to persist across every upgrade until manually cleaned.
-    await pruneStrayDepositPaths(deftDir, contentRoot, io);
-    const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
-    const manifestFields = {
-        ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
-        sha: "content-package",
-        tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
-        installRoot: CANONICAL_INSTALL_ROOT,
-        fetchedAt: nowIso(),
-        fetchedBy: "directive-update",
-        ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
-    };
-    const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
-    // #2064: retire a stale legacy .deft/VERSION now that the canonical
-    // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
-    // manifest behavior is lost by the redirect). Best-effort; never fatal.
-    migrateLegacyInstallManifest(projectDir, writtenManifestPath);
-    // #2055: regenerate the bare .deft-version derivative so it agrees with the
-    // freshly written manifest tag (otherwise doctor's manifest-agreement check
-    // fails and the operator must hand-edit the marker).
-    syncBareVersionMarker(projectDir, contentVersion);
+    const alreadyCurrent = previousDepositVersion !== null &&
+        normalizeVersion(previousDepositVersion) === normalizeVersion(contentVersion);
+    const strategy = alreadyCurrent ? "no-op" : "file-swap";
+    if (alreadyCurrent) {
+        io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
+    }
+    else {
+        await copyContent(contentRoot, deftDir);
+        await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+        // #2347: prune framework-source paths that the content package does not ship.
+        // The additive file-swap never removes them, causing the deposit-hygiene
+        // advisory to persist across every upgrade until manually cleaned.
+        await pruneStrayDepositPaths(deftDir, contentRoot, io);
+        const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+        const manifestFields = {
+            ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
+            sha: "content-package",
+            tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
+            installRoot: CANONICAL_INSTALL_ROOT,
+            fetchedAt: nowIso(),
+            fetchedBy: "directive-update",
+            ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
+        };
+        const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
+        // #2064: retire a stale legacy .deft/VERSION now that the canonical
+        // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
+        // manifest behavior is lost by the redirect). Best-effort; never fatal.
+        migrateLegacyInstallManifest(projectDir, writtenManifestPath);
+        // #2055: regenerate the bare .deft-version derivative so it agrees with the
+        // freshly written manifest tag (otherwise doctor's manifest-agreement check
+        // fails and the operator must hand-edit the marker). No-op refreshes skip
+        // this projection because the manifest tag was not rewritten (#2118).
+        syncBareVersionMarker(projectDir, contentVersion);
+    }
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     // #2148: the deft-core-guard CI workflow is only meaningful when the deposit
     // is git-tracked (committed vendor layout). On an npm-managed (gitignored)
@@ -399,12 +474,27 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     if (args.nonInteractive) {
         taskfileWired = ensureTaskfile(projectDir, io);
     }
-    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
-        includeTaskfile: taskfileWired,
-    });
-    printCommitGuidance(io, stagePaths, staged);
     const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
-    printRefreshSideEffects(io, frameworkRefreshSideEffects(projectDir, readPorcelain));
+    const effects = frameworkRefreshSideEffects(projectDir, {
+        readPorcelain,
+        readSemanticDiffNames: seams.gitSemanticDiffNames ?? gitSemanticDiffNames,
+    });
+    let stagedPaths = [];
+    if (!alreadyCurrent || effects.files.length > 0) {
+        const stagedResult = depositStagePaths(projectDir, {
+            includeTaskfile: taskfileWired,
+            includeCore: !alreadyCurrent,
+        });
+        stagedPaths = stagedResult.stagedPaths;
+        if (!alreadyCurrent) {
+            printCommitGuidance(io, stagedResult.stagePaths, stagedResult.staged);
+        }
+        else if (stagedResult.stagedPaths.length > 0) {
+            io.printf("\nUpdated installer-managed projections for the current framework deposit:\n");
+            io.printf(`  git add ${stagedResult.stagedPaths.join(" ")}\n`);
+        }
+    }
+    printRefreshSideEffects(io, { ...effects, payloadSwapped: !alreadyCurrent });
     if (versionSkewNotice) {
         io.printf(`${versionSkewNotice}\n`);
     }
@@ -414,6 +504,8 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         contentVersion,
         engineVersion,
         previousDepositVersion,
+        alreadyCurrent,
+        strategy,
         agentsMdUpdated,
         versionSkewNotice,
         legacyLayout: false,
@@ -515,7 +607,9 @@ export async function runRefreshDepositCli(options) {
     }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
-        const state = classification?.state;
+        const state = result.alreadyCurrent
+            ? "current"
+            : classification?.state;
         if (options.jsonOut) {
             options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
             printUpdateComplete(result, { printf: options.writeErr }, state);

package/dist/init-deposit/scaffold.js

@@ -22,6 +22,7 @@ const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
 const VENDORED_TS_PACKAGES_REL = ".deft/core/packages";
 const VENDORED_TS_TEST_RE = /\.(test|spec)\.(c|m)?[jt]sx?$/i;
 const CORE_GITATTRIBUTES_LINES = [
+    `${CORE_GLOB} text eol=lf`,
     `${CORE_GLOB} linguist-generated=true`,
     `${CORE_GLOB} linguist-vendored=true`,
 ];
@@ -584,7 +585,7 @@ export function ensureGitattributes(projectDir, io) {
     const present = new Set(existing.split("\n").map((line) => line.trim()));
     const additions = CORE_GITATTRIBUTES_LINES.filter((line) => !present.has(line));
     if (additions.length === 0) {
-        io.printf(`.gitattributes already marks ${CORE_GLOB} as generated/vendored — skipping.\n`);
+        io.printf(`.gitattributes already marks ${CORE_GLOB} as LF-pinned/generated/vendored — skipping.\n`);
         return false;
     }
     let body = existing;
@@ -594,13 +595,13 @@ export function ensureGitattributes(projectDir, io) {
         body += "\n";
     body +=
         "# Deft framework: the vendored payload is packaged framework code, not\n" +
-            "# consumer source. Mark it generated + vendored so language stats and\n" +
-            "# diffs treat .deft/core/** as machine-managed (#1430).\n";
+            "# consumer source. Pin LF endings and mark it generated + vendored so\n" +
+            "# Git does not rewrite it and diffs treat .deft/core/** as machine-managed (#1430, #2118).\n";
     for (const add of additions) {
         body += `${add}\n`;
     }
     writeFileSync(path, body, "utf8");
-    io.printf(`.gitattributes updated with linguist markers: ${additions.join(", ")}\n`);
+    io.printf(`.gitattributes updated with Deft core markers: ${additions.join(", ")}\n`);
     return true;
 }
 function greptilePatternPresent(patterns, glob) {

package/dist/policy/disclosure.d.ts

@@ -1,4 +1,5 @@
 import type { PolicyResult } from "./resolve.js";
+export { policyColonInvocation, policySetInvocation } from "./policy-invocation.js";
 /** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
 export declare function disclosureLine(result: PolicyResult): string;
 //# sourceMappingURL=disclosure.d.ts.map

package/dist/policy/disclosure.js

@@ -1,4 +1,5 @@
 import { ENV_BYPASS } from "./resolve.js";
+export { policyColonInvocation, policySetInvocation } from "./policy-invocation.js";
 /** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
 export function disclosureLine(result) {
     if (result.allowDirectCommits) {

package/dist/policy/index.d.ts

@@ -4,6 +4,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
+export * from "./policy-invocation.js";
 export * from "./resolve.js";
 export * from "./value-feedback.js";
 export * from "./wip.js";

package/dist/policy/index.js

@@ -8,6 +8,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
+export * from "./policy-invocation.js";
 export * from "./resolve.js";
 export * from "./value-feedback.js";
 export * from "./wip.js";

package/dist/policy/policy-invocation.d.ts

@@ -0,0 +1,5 @@
+/** User-facing colon-form policy verb for consumer `deft` disclosures (#2367). */
+export declare function policyColonInvocation(subcommand: string, trailing?: string): string;
+/** User-facing `deft policy set <cmd>` form for policy-set disclosures (#2367). */
+export declare function policySetInvocation(subcommand: string, trailing?: string): string;
+//# sourceMappingURL=policy-invocation.d.ts.map

package/dist/policy/policy-invocation.js

@@ -0,0 +1,9 @@
+/** User-facing colon-form policy verb for consumer `deft` disclosures (#2367). */
+export function policyColonInvocation(subcommand, trailing = "") {
+    return `deft policy:${subcommand}${trailing}`;
+}
+/** User-facing `deft policy set <cmd>` form for policy-set disclosures (#2367). */
+export function policySetInvocation(subcommand, trailing = "") {
+    return `deft policy set ${subcommand}${trailing}`;
+}
+//# sourceMappingURL=policy-invocation.js.map

package/dist/policy/resolve.js

@@ -3,6 +3,7 @@ import { join, resolve as pathResolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
 /** Filesystem-relative location of the project-definition xBRIEF (display/back-compat). */
 export const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
 /** Environment variable emergency bypass for branch protection (#747). */
@@ -154,8 +155,9 @@ export function resolvePolicy(projectRoot) {
         const warn = `DEPRECATED: PROJECT-DEFINITION uses the legacy narrative key ` +
             `'${LEGACY_NARRATIVE_KEY}' (${pythonRepr(raw)}). Migrate to typed ` +
             `plan.policy.allowDirectCommitsToMaster (#746). Run ` +
-            `\`task policy:enforce-branches\` or \`task policy:allow-direct-commits ` +
-            `-- --confirm\` to set the typed flag explicitly.`;
+            `\`${policyColonInvocation("enforce-branches")}\` or ` +
+            `\`${policyColonInvocation("allow-direct-commits", " -- --confirm")}\` ` +
+            `to set the typed flag explicitly.`;
         return {
             allowDirectCommits: allow,
             source: "legacy-narrative",

package/dist/policy/value-feedback.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
 import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
 import { isTrustedOrgAutoEnable } from "./value-feedback-autoenable.js";
 /** Canonical registered policy field name (matches other FIELD_* dotted paths). */
@@ -21,7 +22,9 @@ export const VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost
     "  \u2022 A budgeted session one-liner may appear when concrete attributed value exists.\n" +
     "  \u2022 Upstream gap-escalation prompts stay OFF unless you explicitly enable " +
     "`upstreamPrompt` (GitHub attention + token cost).\n" +
-    "  \u2022 Inspect current state: `task policy:show --field=valueFeedback`.\n" +
+    "  \u2022 Inspect current state: `" +
+    policyColonInvocation("show", " --field=valueFeedback") +
+    "`.\n" +
     "  \u2022 Reversible: set `enabled: false` under the typed policy block in PROJECT-DEFINITION.\n" +
     "  \u2022 Changes are recorded to meta/policy-changes.log for auditability.";
 function defaultResolved(source, error = null) {
@@ -202,7 +205,7 @@ export function enableValueFeedback(projectRoot, options) {
         return {
             exitCode: 1,
             stdout: `${VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE}\n\n` +
-                "Re-run with --confirm to apply: task policy:enable-value-feedback -- --confirm\n",
+                `Re-run with --confirm to apply: ${policyColonInvocation("enable-value-feedback", " -- --confirm")}\n`,
             changed: false,
         };
     }
@@ -265,7 +268,7 @@ export function enableValueFeedback(projectRoot, options) {
             if (changedFlag) {
                 atomicWriteProjectDefinition(path, data);
             }
-            const actor = options.actor ?? "task policy:enable-value-feedback";
+            const actor = options.actor ?? policyColonInvocation("enable-value-feedback");
             const note = options.note ?? "";
             const parts = [
                 `actor=${actor}`,

package/dist/swarm/constants.d.ts

@@ -7,7 +7,7 @@ export declare const EXIT_UNCLEAN = 1;
 export declare const EXIT_EXTERNAL_ERROR = 2;
 export declare const DEFAULT_BASE_BRANCH = "master";
 export declare const LEAF_CODING_WORKER_ROLE = "leaf-implementation";
-export declare const SUBAGENT_BACKEND_SET_CMD = "task policy:subagent-backend -- --set {backend_id}";
+export declare const SUBAGENT_BACKEND_SET_CMD: string;
 export declare const GATE_ADVISE = "advise";
 export declare const GATE_ENFORCE = "enforce";
 export declare const READY = "ready";

package/dist/swarm/constants.js

@@ -1,3 +1,4 @@
+import { policySetInvocation } from "../policy/policy-invocation.js";
 export const EXIT_OK = 0;
 export const EXIT_GATE_FAILED = 1;
 export const EXIT_CONFIG_ERROR = 2;
@@ -7,7 +8,7 @@ export const EXIT_UNCLEAN = 1;
 export const EXIT_EXTERNAL_ERROR = 2;
 export const DEFAULT_BASE_BRANCH = "master";
 export const LEAF_CODING_WORKER_ROLE = "leaf-implementation";
-export const SUBAGENT_BACKEND_SET_CMD = "task policy:subagent-backend -- --set {backend_id}";
+export const SUBAGENT_BACKEND_SET_CMD = `${policySetInvocation("subagent-backend", " -- --set {backend_id}")}`;
 export const GATE_ADVISE = "advise";
 export const GATE_ENFORCE = "enforce";
 export const READY = "ready";

package/dist/swarm/subagent-backend.js

@@ -12,6 +12,7 @@
  * @see {@link https://github.com/deftai/directive/issues/1860} Hard deletion tracking
  */
 import { readPlanPolicy } from "../policy/plan-extensions.js";
+import { policySetInvocation } from "../policy/policy-invocation.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 import { LEAF_CODING_WORKER_ROLE, SUBAGENT_BACKEND_SET_CMD } from "./constants.js";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
@@ -132,7 +133,7 @@ export function enforceSubagentBackendPolicy(projectRoot, environ = process.env)
             error: `${detail}\n` +
                 "Select a coding sub-agent backend before headless dispatch:\n" +
                 `${listing}\n` +
-                "Probe harness availability: task policy:subagent-backends\n" +
+                `Probe harness availability: ${policySetInvocation("subagent-backends")}\n` +
                 `Persist a choice: ${SUBAGENT_BACKEND_SET_CMD.replace("{backend_id}", "<id>")}`,
         };
     }

package/dist/ts-check-lane/run-lane.d.ts

@@ -25,6 +25,8 @@ export declare const SKIP_NOTICE: string;
 /** Result of a single lane command invocation. Mirrors a subset of SpawnSyncReturns. */
 export interface RunnerResult {
     readonly status: number | null;
+    readonly signal?: NodeJS.Signals | null;
+    readonly error?: Error;
 }
 export type LaneRunner = (argv: readonly string[], cwd: string) => RunnerResult;
 export interface RunTsLaneOptions {
@@ -35,6 +37,8 @@ export interface RunTsLaneOptions {
     /** Injected sink for human-facing notices (defaults to stdout). */
     readonly out?: (message: string) => void;
 }
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;
 export interface ResolvePnpmOptions {
     readonly env?: NodeJS.ProcessEnv;
     readonly platform?: NodeJS.Platform;

package/dist/ts-check-lane/run-lane.js

@@ -18,7 +18,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { posix, win32 } from "node:path";
 /**
  * Run order is deliberate: lint (cheapest, catches the biome class first),
  * then build, then the test suite.
@@ -31,11 +31,20 @@ export const LANE_COMMANDS = [
 export const SKIP_NOTICE = "[ts:check-lane] pnpm not found on PATH -- skipping the TypeScript lane " +
     "(build/lint/test). The TS engine stays validated by the dedicated CI job. " +
     "Install the Node toolchain (pnpm) to run the TS lane locally.";
-/** Default runner: a non-shell, inherited-stdio pnpm invocation. */
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export function shouldUseShellForCommand(command, platform = process.platform) {
+    return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+/** Default runner: an inherited-stdio pnpm invocation. */
 function defaultRunner(argv, cwd) {
     const [command, ...rest] = argv;
-    const result = spawnSync(command ?? "", rest, { cwd, stdio: "inherit" });
-    return { status: result.status };
+    const commandPath = command ?? "";
+    const result = spawnSync(commandPath, rest, {
+        cwd,
+        stdio: "inherit",
+        shell: shouldUseShellForCommand(commandPath),
+    });
+    return { error: result.error, signal: result.signal, status: result.status };
 }
 /** Resolve the pnpm executable path, or null when it is not installed. */
 export function resolvePnpm(options = {}) {
@@ -49,11 +58,12 @@ export function resolvePnpm(options = {}) {
     const isWindows = platform === "win32";
     const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
     const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
     for (const dir of pathValue.split(sep)) {
         if (dir === "")
             continue;
         for (const ext of exts) {
-            const candidate = join(dir, `pnpm${ext}`);
+            const candidate = joinPath(dir, `pnpm${ext}`);
             if (exists(candidate)) {
                 return candidate;
             }
@@ -85,7 +95,11 @@ export function runTsLane(projectRoot, options) {
         // failure -- this mirrors the Python oracle, whose returncode is negative
         // (non-zero) for a signal-killed process.
         if (code === null) {
-            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` was killed by a signal before exit -- treating as failure.`);
+            if (result.error) {
+                out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` failed to start: ${result.error.message}`);
+                return 1;
+            }
+            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` was killed by ${result.signal ?? "a signal"} before exit -- treating as failure.`);
             return 1;
         }
         if (code !== 0) {

package/dist/value/feedback-file.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { isFrameworkRepoRoot } from "../check/orchestrator.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback } from "../policy/value-feedback.js";
 import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh-rest.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -146,8 +147,8 @@ export function runFeedbackFile(options) {
             body,
             repo,
             message: "[deft feedback] Blocked: plan.policy.valueFeedback upstreamPrompt is OFF. " +
-                "Enable with `task policy:enable-value-feedback -- --confirm` and set upstreamPrompt, " +
-                "or inspect via `task policy:show --field=valueFeedback`.\n",
+                `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\` and set upstreamPrompt, ` +
+                `or inspect via \`${policyColonInvocation("show", " --field=valueFeedback")}\`.\n`,
         };
     }
     const offline = isOffline();

package/dist/value/readback.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { ALL_ATTRIBUTION_EVENT_NAMES } from "../events/attribution-constants.js";
 import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
@@ -364,7 +365,7 @@ export function formatValueShowReport(trend) {
     if (trend.total === 0) {
         return (`[value] No attributed signals in the last ${trend.windowLabel} ` +
             "(ledger empty for this window).\n" +
-            "Inspect policy: `task policy:show --field=valueFeedback`.\n");
+            `Inspect policy: \`${policyColonInvocation("show", " --field=valueFeedback")}\`.\n`);
     }
     const classParts = ["value", "bypass", "adoption", "friction"]
         .filter((key) => trend.byClass[key] > 0)
@@ -409,7 +410,7 @@ export function runValueShow(options) {
             gated: true,
             empty: true,
             text: "[value] Blocked: plan.policy.valueFeedback is OFF. " +
-                "Enable with `task policy:enable-value-feedback -- --confirm`.\n",
+                `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\`.\n`,
             trend: null,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.73.0",
+  "version": "0.73.1",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -281,8 +281,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.73.0",
-    "@deftai/directive-types": "^0.73.0",
+    "@deftai/directive-content": "^0.73.1",
+    "@deftai/directive-types": "^0.73.1",
     "archiver": "^8.0.0"
   },
   "scripts": {