@deftai/directive-core 0.73.0 → 0.74.0

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.d.ts

@@ -61,6 +61,27 @@ export interface GitHooksSeams {
     setHooksPath?: (projectDir: string, value: string) => boolean;
 }
 export declare function writeConsumerGitHooks(projectDir: string, deftDir: string, io: InitDepositIo, seams?: GitHooksSeams): boolean;
+/** Commit SHA for `actions/checkout` deposited in deft-core-guard.yml (#1672 / #1072). */
+export declare const CORE_GUARD_CHECKOUT_SHA = "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0";
+/** Tag comment paired with {@link CORE_GUARD_CHECKOUT_SHA}. */
+export declare const CORE_GUARD_CHECKOUT_TAG = "v7.0.0";
+/**
+ * Extract the `uses: actions/checkout@…` step line from a guard workflow, if present.
+ * Uses linear string scanning (no regex) to avoid CodeQL js/polynomial-redos (#1672).
+ */
+export declare function extractCoreGuardCheckoutUsesLine(content: string): string | null;
+/**
+ * Whether refresh should keep the existing checkout pin instead of the template pin.
+ * Legacy framework-deposited `@v4` tags migrate forward; consumer/Dependabot bumps do not.
+ */
+export declare function shouldPreserveCoreGuardCheckoutPin(existingUsesLine: string, desiredUsesLine: string): boolean;
+/** Canonical SHA-pinned checkout step for the deposited deft-core-guard workflow. */
+export declare function coreGuardCheckoutUsesLine(sha?: string, tag?: string): string;
+/**
+ * On refresh, preserve an existing consumer `actions/checkout@…` pin while updating
+ * the managed guard script / allowlist body (#1672 option 1).
+ */
+export declare function mergeCoreGuardWorkflowRefresh(existing: string, desired: string): string;
 export declare function ensureGitattributes(projectDir: string, io: InitDepositIo): boolean;
 export declare function ensureGreptileIgnore(projectDir: string, io: InitDepositIo): boolean;
 export declare function ensureCodeqlPathsIgnore(projectDir: string, io: InitDepositIo): boolean;

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`,
 ];
@@ -537,6 +538,78 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
 function githubActionsExpr(expression) {
     return ["$", "{{ ", expression, " }}"].join("");
 }
+/** Commit SHA for `actions/checkout` deposited in deft-core-guard.yml (#1672 / #1072). */
+export const CORE_GUARD_CHECKOUT_SHA = "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0";
+/** Tag comment paired with {@link CORE_GUARD_CHECKOUT_SHA}. */
+export const CORE_GUARD_CHECKOUT_TAG = "v7.0.0";
+const CHECKOUT_USES_PREFIX = "- uses: actions/checkout@";
+/**
+ * Extract the `uses: actions/checkout@…` step line from a guard workflow, if present.
+ * Uses linear string scanning (no regex) to avoid CodeQL js/polynomial-redos (#1672).
+ */
+export function extractCoreGuardCheckoutUsesLine(content) {
+    for (const line of content.split("\n")) {
+        const trimmed = line.trimStart();
+        if (!trimmed.startsWith(CHECKOUT_USES_PREFIX))
+            continue;
+        // YAML step lines are indented; a bare top-level match is not a step.
+        if (trimmed.length === line.length)
+            continue;
+        return line;
+    }
+    return null;
+}
+/** Ref after `actions/checkout@` (tag, SHA, or major), stopping at whitespace. */
+function checkoutActionRef(usesLine) {
+    const idx = usesLine.indexOf(CHECKOUT_USES_PREFIX);
+    if (idx < 0)
+        return null;
+    const after = usesLine.slice(idx + CHECKOUT_USES_PREFIX.length);
+    let end = after.length;
+    for (let i = 0; i < after.length; i += 1) {
+        const c = after[i];
+        if (c === " " || c === "\t" || c === "\r") {
+            end = i;
+            break;
+        }
+    }
+    const ref = after.slice(0, end);
+    return ref.length > 0 ? ref : null;
+}
+/**
+ * Whether refresh should keep the existing checkout pin instead of the template pin.
+ * Legacy framework-deposited `@v4` tags migrate forward; consumer/Dependabot bumps do not.
+ */
+export function shouldPreserveCoreGuardCheckoutPin(existingUsesLine, desiredUsesLine) {
+    if (existingUsesLine === desiredUsesLine)
+        return false;
+    const existingRef = checkoutActionRef(existingUsesLine);
+    if (!existingRef)
+        return false;
+    // Stale framework-deposited floating major tag — migrate to SHA template (#1672).
+    return existingRef !== "v4";
+}
+/** Canonical SHA-pinned checkout step for the deposited deft-core-guard workflow. */
+export function coreGuardCheckoutUsesLine(sha = CORE_GUARD_CHECKOUT_SHA, tag = CORE_GUARD_CHECKOUT_TAG) {
+    return `      - uses: actions/checkout@${sha} # ${tag}`;
+}
+/**
+ * On refresh, preserve an existing consumer `actions/checkout@…` pin while updating
+ * the managed guard script / allowlist body (#1672 option 1).
+ */
+export function mergeCoreGuardWorkflowRefresh(existing, desired) {
+    const existingCheckout = extractCoreGuardCheckoutUsesLine(existing);
+    if (!existingCheckout)
+        return desired;
+    const desiredCheckout = extractCoreGuardCheckoutUsesLine(desired);
+    if (!desiredCheckout || !shouldPreserveCoreGuardCheckoutPin(existingCheckout, desiredCheckout)) {
+        return desired;
+    }
+    const idx = desired.indexOf(desiredCheckout);
+    if (idx < 0)
+        return desired;
+    return desired.slice(0, idx) + existingCheckout + desired.slice(idx + desiredCheckout.length);
+}
 function coreGuardWorkflowContent() {
     const baseSha = githubActionsExpr("github.event.pull_request.base.sha");
     const headSha = githubActionsExpr("github.event.pull_request.head.sha");
@@ -554,7 +627,7 @@ function coreGuardWorkflowContent() {
         "  no-mixed-core-and-app:\n" +
         "    runs-on: ubuntu-latest\n" +
         "    steps:\n" +
-        "      - uses: actions/checkout@v4\n" +
+        `${coreGuardCheckoutUsesLine()}\n` +
         "        with:\n" +
         "          fetch-depth: 0\n" +
         "      - name: Refuse PRs that mix .deft/core/** with non-framework paths\n" +
@@ -584,7 +657,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 +667,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) {
@@ -714,15 +787,16 @@ export function ensureCoreGuardWorkflow(projectDir, io) {
     const desired = coreGuardWorkflowContent();
     if (existsSync(path)) {
         const existing = readFileSync(path, "utf8");
-        if (existing === desired) {
-            io.printf(`${CORE_GUARD_WORKFLOW_REL} already current — skipping.\n`);
-            return false;
-        }
         if (!existing.includes("name: deft-core-guard")) {
             io.printf(`${CORE_GUARD_WORKFLOW_REL} present but not deft-managed — leaving unchanged.\n`);
             return false;
         }
-        writeFileSync(path, desired, "utf8");
+        const refreshed = mergeCoreGuardWorkflowRefresh(existing, desired);
+        if (existing === refreshed) {
+            io.printf(`${CORE_GUARD_WORKFLOW_REL} already current — skipping.\n`);
+            return false;
+        }
+        writeFileSync(path, refreshed, "utf8");
         io.printf(`${CORE_GUARD_WORKFLOW_REL} refreshed: deft-core-guard allowlist updated (#1478).\n`);
         return true;
     }

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/pr-merge-readiness/constants.d.ts

@@ -3,6 +3,10 @@ export declare const EXIT_MERGE_BLOCKED = 1;
 export declare const EXIT_EXTERNAL_ERROR = 2;
 export declare const GREPTILE_LOGIN = "greptile-apps[bot]";
 export declare const GREPTILE_ERRORED_SENTINEL = "Greptile encountered an error while reviewing this PR";
+/** Greptile status marker on excluded-author skip comments (#2375). */
+export declare const GREPTILE_STATUS_MARKER = "<!-- greptile-status -->";
+/** Substring Greptile posts when the PR author is on the excluded-authors list (#2375). */
+export declare const GREPTILE_EXCLUDED_AUTHOR_PHRASE = "excluded authors list";
 export declare const LAST_REVIEWED_RE: RegExp;
 export declare const CONFIDENCE_RE: RegExp;
 export declare const P0_BADGE = "<img alt=\"P0\"";

package/dist/pr-merge-readiness/constants.js

@@ -3,6 +3,10 @@ export const EXIT_MERGE_BLOCKED = 1;
 export const EXIT_EXTERNAL_ERROR = 2;
 export const GREPTILE_LOGIN = "greptile-apps[bot]";
 export const GREPTILE_ERRORED_SENTINEL = "Greptile encountered an error while reviewing this PR";
+/** Greptile status marker on excluded-author skip comments (#2375). */
+export const GREPTILE_STATUS_MARKER = "<!-- greptile-status -->";
+/** Substring Greptile posts when the PR author is on the excluded-authors list (#2375). */
+export const GREPTILE_EXCLUDED_AUTHOR_PHRASE = "excluded authors list";
 export const LAST_REVIEWED_RE = /Last reviewed commit:\s*\[[^\]]*\]\(https?:\/\/github\.com\/[^/]+\/[^/]+\/commit\/(?<sha>[0-9a-f]{7,40})/g;
 export const CONFIDENCE_RE = /Confidence Score:\s*(?<score>\d+)\s*\/\s*5/i;
 export const P0_BADGE = '<img alt="P0"';

package/dist/pr-merge-readiness/evaluate.js

@@ -8,6 +8,9 @@ export function evaluateGates(_prNumber, headSha, verdict) {
             "Wait for the review to land before merging (see #796 late-bot-review re-check).");
         return failures;
     }
+    if (verdict.excludedAuthor) {
+        return failures;
+    }
     if (verdict.errored) {
         failures.push("Greptile review is in the ERRORED state on the current HEAD (#526). " +
             "Retry via @greptileai or escalate per " +

package/dist/pr-merge-readiness/mergeability.d.ts

@@ -31,13 +31,15 @@ export declare function verdictShaIsStale(verdict: GreptileVerdict, headSha: str
  * Classify whether the verdict-based merge block is ONLY "soft" (#2260).
  *
  * A soft block means the review verdict is absent or pinned to a prior head
- * SHA (rebased staleness) -- i.e. the review has not spoken about the CURRENT
- * head. It is safe to reconcile a soft block against GitHub mergeability.
+ * SHA without carrying real blocker-class findings (rebased staleness with no
+ * P0/P1/errored/low-confidence) -- i.e. the review has not spoken about the
+ * CURRENT head in a blocking way. It is safe to reconcile a soft block against
+ * GitHub mergeability.
  *
- * A HARD block -- a genuine P0/P1 finding, an ERRORED review, or a low
- * confidence score on the current head -- is NEVER soft; those must keep
- * blocking regardless of GitHub mergeability (guardrail: do not merge a PR
- * with a real P0/P1 review finding).
+ * A HARD block -- a genuine P0/P1 finding (even on a stale SHA), an ERRORED
+ * review, or a low confidence score -- is NEVER soft; those must keep blocking
+ * regardless of GitHub mergeability (guardrail: do not merge a PR with a real
+ * P0/P1 review finding).
  */
 export declare function verdictBlockIsSoftOnly(verdict: GreptileVerdict, headSha: string | null): boolean;
 //# sourceMappingURL=mergeability.d.ts.map