@deftai/directive-core 0.105.0 → 0.107.0

package/dist/policy/host-hooks.js

@@ -1,8 +1,36 @@
+import { readFileSync } from "node:fs";
 import { HOOK_HOSTS } from "../hooks/dispatcher.js";
-import { readPlanPolicy } from "./plan-extensions.js";
-import { loadProjectDefinition } from "./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";
+import { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
 export const FIELD_HOST_HOOKS = "plan.policy.hostHooks";
 export const FIELD_HOST_HOOKS_CLI_ALIAS = "hostHooks";
+export const DISABLE_HOST_HOOKS_SUBCOMMAND = "disable-host-hooks";
+/** Confirm-gated disable verb for unused-host recovery copy (#3571). CLI form: no go-task `--`. */
+export function disableHostHooksInvocation(trailing = " --host <host> --confirm") {
+    return policyColonInvocation(DISABLE_HOST_HOOKS_SUBCOMMAND, trailing);
+}
+export const HOST_HOOKS_DISABLE_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- disabling hostHooks for a host removes " +
+    "deft-hook pre-execution guardrails for anyone who later opens this repo in that host. " +
+    "The result is tracked.\n" +
+    "  \u2022 Opted-out hosts skip Directive hook deposit; leftover-free files write {}.\n" +
+    "  \u2022 This is not a timeout or live-probe fix. Retry the gated ritual when load is the cause.\n" +
+    "  \u2022 Inspect: `" +
+    policyColonInvocation("show", " --field=hostHooks") +
+    "`.\n" +
+    "  \u2022 Apply: `" +
+    disableHostHooksInvocation() +
+    "`.\n" +
+    "  \u2022 Reversible: set the host back to true and run `deft update`.\n" +
+    "  \u2022 Hand-edit of plan.policy.hostHooks plus `deft update` still strips " +
+    "(human high-trust bypass).\n" +
+    "  \u2022 Changes are recorded to meta/policy-changes.log for auditability.";
+export const UNUSED_HOST_HOOKS_RECOVERY = "If an affected host is unused, inspect `" +
+    policyColonInvocation("show", " --field=hostHooks") +
+    "`, then run `" +
+    disableHostHooksInvocation() +
+    "`. That removes deft-hook pre-execution guardrails for that host and the result is tracked.";
 export const DEFAULT_HOST_HOOKS_POLICY = {
     claude: true,
     cursor: true,
@@ -93,4 +121,95 @@ export function loadHostHooksPolicyFromProject(projectRoot) {
     }
     return resolveHostHooksPolicy(policyBlock.hostHooks);
 }
+export function parseHookHost(value) {
+    if (value === undefined)
+        return null;
+    return HOOK_HOSTS.includes(value) ? value : null;
+}
+/** Persist `hostHooks.<host>=false` after capability-cost disclosure (#3571). */
+export function disableHostHooks(projectRoot, options) {
+    if (!HOOK_HOSTS.includes(options.host)) {
+        return {
+            exitCode: 2,
+            stdout: `\u274c ${FIELD_HOST_HOOKS}.${String(options.host)} is not a deposited host (${HOOK_HOSTS.join(", ")}).\n`,
+            changed: false,
+        };
+    }
+    if (!options.confirm) {
+        return {
+            exitCode: 1,
+            stdout: `${HOST_HOOKS_DISABLE_CAPABILITY_COST_DISCLOSURE}\n\n` +
+                `Re-run with --confirm to apply: ${disableHostHooksInvocation(` --host ${options.host} --confirm`)}\n`,
+            changed: false,
+        };
+    }
+    const path = projectDefinitionPath(projectRoot);
+    try {
+        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
+            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+            }
+            const data = parsed;
+            if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+                if (data.plan === undefined) {
+                    data.plan = {};
+                }
+                else {
+                    throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+                }
+            }
+            const plan = data.plan;
+            const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
+            const existingPolicy = plan[PLAN_POLICY_KEY];
+            if (typeof existingPolicy !== "object" ||
+                existingPolicy === null ||
+                Array.isArray(existingPolicy)) {
+                if (existingPolicy === undefined) {
+                    plan[PLAN_POLICY_KEY] = {};
+                }
+                else {
+                    throw new Error("plan.policy is not an object");
+                }
+            }
+            const policyBlock = plan[PLAN_POLICY_KEY];
+            const previous = resolveHostHooksPolicy(policyBlock.hostHooks);
+            const next = { ...previous, [options.host]: false };
+            const changedFlag = previous[options.host] !== false || legacyKeyMigrated;
+            policyBlock.hostHooks = next;
+            if (changedFlag) {
+                atomicWriteProjectDefinition(path, data);
+            }
+            const actor = options.actor ?? disableHostHooksInvocation();
+            const note = options.note ?? "";
+            const parts = [
+                `actor=${actor}`,
+                `${FIELD_HOST_HOOKS}.${options.host}=false`,
+                `previous=${JSON.stringify(previous)}`,
+            ];
+            if (note) {
+                parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+            }
+            appendAuditLog(projectRoot, parts.join(" "), changedFlag);
+            return { changed: changedFlag };
+        });
+        const lines = [
+            `\u2713 ${FIELD_HOST_HOOKS}.${options.host}=false (deft-hook guardrails removed for ${options.host}; result is tracked).`,
+            changed ? "  audit: meta/policy-changes.log updated." : POLICY_AUDIT_NOOP_STDOUT,
+            "  Run `deft update` to strip Directive-managed hook entries for that host.",
+        ];
+        return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("ENOENT") || message.includes("PROJECT-DEFINITION not found")) {
+            return {
+                exitCode: 2,
+                stdout: `\u274c PROJECT-DEFINITION not found at ${path}\n`,
+                changed: false,
+            };
+        }
+        return { exitCode: 2, stdout: `\u274c Config error: ${message}\n`, changed: false };
+    }
+}
 //# sourceMappingURL=host-hooks.js.map

package/dist/policy/org-force-on-migration.js

@@ -421,6 +421,7 @@ function applyForceOn(projectRoot, options, intent) {
                 ? existing.previousProductSignal
                 : ORG_FORCE_ON_NO_BASELINE;
         const actor = options.actor ?? "directive-update";
+        const changed = valueFeedbackChanged || productSignalChanged;
         appendAuditLog(projectRoot, [
             `actor=${actor}`,
             "org-force-on-v2822",
@@ -428,7 +429,7 @@ function applyForceOn(projectRoot, options, intent) {
             `productSignal=${needsPs ? "forced-on" : "unchanged"}`,
             `previousValueFeedback=${JSON.stringify(normalizePolicySnapshot(markerPreviousVf))}`,
             `previousProductSignal=${JSON.stringify(normalizePolicySnapshot(markerPreviousPs))}`,
-        ].join(" "));
+        ].join(" "), changed);
         writeMarker(projectRoot, options, {
             // OR with existing so partial re-apply does not clear install-force-on source.
             valueFeedback: needsVf || (existing?.valueFeedback ?? false),

package/dist/policy/plan-extensions.d.ts

@@ -41,7 +41,7 @@ export declare function readPlanOnboarding(plan: unknown): unknown;
  * policy key is present. Used by writers so a mutation never strands a legacy
  * bare block alongside the namespaced one.
  */
-export declare function migrateLegacyPolicyKey(plan: Record<string, unknown>): void;
+export declare function migrateLegacyPolicyKey(plan: Record<string, unknown>): boolean;
 /** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
 export declare const SHADOWABLE_PLAN_EXTENSIONS: ReadonlyArray<{
     readonly namespacedKey: string;

package/dist/policy/plan-extensions.js

@@ -68,7 +68,9 @@ export function migrateLegacyPolicyKey(plan) {
     if (plan[PLAN_POLICY_KEY] === undefined && plan[LEGACY_PLAN_POLICY_KEY] !== undefined) {
         plan[PLAN_POLICY_KEY] = plan[LEGACY_PLAN_POLICY_KEY];
         delete plan[LEGACY_PLAN_POLICY_KEY];
+        return true;
     }
+    return false;
 }
 /** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
 export const SHADOWABLE_PLAN_EXTENSIONS = [

package/dist/policy/product-signal.js

@@ -3,7 +3,7 @@ import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "..
 import { productSignalInstallForceOnSource } from "./org-force-on-migration.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 { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
 /** Canonical registered policy field name (#2693). */
 export const FIELD_PRODUCT_SIGNAL = "plan.policy.productSignal";
 /** Short alias for `policy:show --field=productSignal`. */
@@ -157,7 +157,7 @@ export function enableProductSignal(projectRoot, options) {
                 }
             }
             const plan = data.plan;
-            migrateLegacyPolicyKey(plan);
+            const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
             const existingPolicy = plan[PLAN_POLICY_KEY];
             if (typeof existingPolicy !== "object" ||
                 existingPolicy === null ||
@@ -181,7 +181,8 @@ export function enableProductSignal(projectRoot, options) {
             const nextBlock = { enabled: true, sinkRepo };
             const previousNormalized = resolveProductSignalFromTypedBlock(previous);
             const changedFlag = previousNormalized.enabled !== nextBlock.enabled ||
-                previousNormalized.sinkRepo !== nextBlock.sinkRepo;
+                previousNormalized.sinkRepo !== nextBlock.sinkRepo ||
+                legacyKeyMigrated;
             policyBlock.productSignal = nextBlock;
             if (changedFlag) {
                 atomicWriteProjectDefinition(path, data);
@@ -197,15 +198,13 @@ export function enableProductSignal(projectRoot, options) {
             if (note) {
                 parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
             }
-            appendAuditLog(projectRoot, parts.join(" "));
+            appendAuditLog(projectRoot, parts.join(" "), changedFlag);
             return { changed: changedFlag };
         });
         const resolved = resolveProductSignal(projectRoot);
         const lines = [
             `\u2713 ${FIELD_PRODUCT_SIGNAL}.enabled=true (product-signal ON).`,
-            changed
-                ? "  audit: meta/policy-changes.log updated."
-                : "  no-op: value already matched (audit entry still appended for trail).",
+            changed ? "  audit: meta/policy-changes.log updated." : POLICY_AUDIT_NOOP_STDOUT,
             formatProductSignalStatusLine(resolved),
         ];
         return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };

package/dist/policy/require-human-merge.js

@@ -18,7 +18,7 @@ import { existsSync, 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 { appendAuditLog, loadProjectDefinition, projectDefinitionPath, stampChangedToken, } from "./resolve.js";
 export const FIELD_REQUIRE_HUMAN_MERGE = "plan.policy.requireHumanMerge";
 export const FIELD_REQUIRE_HUMAN_MERGE_CLI_ALIAS = "requireHumanMerge";
 export const FIELD_AUTO_DEPLOY_ON_MERGE = "plan.policy.autoDeployOnMerge";
@@ -285,7 +285,7 @@ export function setRequireHumanMerge(projectRoot, options) {
             }
         }
         const plan = data.plan;
-        migrateLegacyPolicyKey(plan);
+        const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
         const existingPolicy = plan[PLAN_POLICY_KEY];
         if (typeof existingPolicy !== "object" ||
             existingPolicy === null ||
@@ -309,8 +309,7 @@ export function setRequireHumanMerge(projectRoot, options) {
             delete narratives[LEGACY_REQUIRE_HUMAN_MERGE_KEY];
             legacyDropped = true;
         }
-        atomicWriteProjectDefinition(path, data);
-        const changed = previous !== Boolean(requireHumanMerge) || legacyDropped;
+        const changed = previous !== Boolean(requireHumanMerge) || legacyDropped || legacyKeyMigrated;
         const parts = [
             `actor=${actor}`,
             `requireHumanMerge=${requireHumanMerge ? "true" : "false"}`,
@@ -321,8 +320,11 @@ export function setRequireHumanMerge(projectRoot, options) {
         if (note) {
             parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
         }
-        const auditEntry = parts.join(" ");
-        appendAuditLog(projectRoot, auditEntry);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            atomicWriteProjectDefinition(path, data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };
     });
 }

package/dist/policy/resolve.d.ts

@@ -6,6 +6,10 @@ export declare const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export declare const LEGACY_NARRATIVE_KEY = "Allow direct commits to master";
 /** Audit log relative path (#746). */
 export declare const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
+/** Operator line when a policy writer matches current state and does not append (#3528). */
+export declare const POLICY_AUDIT_NOOP_STDOUT = "  no-op: value already matched (ledger unchanged).";
+/** Stamp a machine-readable `changed=true|false` token (#3528 / UPGRADING.md). */
+export declare function stampChangedToken(entry: string, changed: boolean): string;
 export type PolicySource = "typed" | "legacy-narrative" | "env-bypass" | "default-fail-closed";
 export interface PolicyResult {
     readonly allowDirectCommits: boolean;
@@ -28,8 +32,9 @@ export declare function coerceLegacyNarrative(value: unknown): {
 export declare function loadProjectDefinition(projectRoot: string): [Record<string, unknown> | null, string | null];
 /** Resolve the effective branch-commit policy (#746 / #747). */
 export declare function resolvePolicy(projectRoot: string): PolicyResult;
-/** Append a one-line audit entry to meta/policy-changes.log (#746). */
-export declare function appendAuditLog(projectRoot: string, entry: string): string;
+/** Append a one-line audit entry to meta/policy-changes.log (#746).
+ * No-op (`changed=false`) does not create or modify the tracked file (#3528). */
+export declare function appendAuditLog(projectRoot: string, entry: string, changed?: boolean): string;
 /** Write the typed policy flag back to PROJECT-DEFINITION (#746). */
 export declare function setPolicy(projectRoot: string, options: {
     allowDirectCommits: boolean;

package/dist/policy/resolve.js

@@ -13,6 +13,16 @@ export const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export const LEGACY_NARRATIVE_KEY = "Allow direct commits to master";
 /** Audit log relative path (#746). */
 export const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
+/** Operator line when a policy writer matches current state and does not append (#3528). */
+export const POLICY_AUDIT_NOOP_STDOUT = "  no-op: value already matched (ledger unchanged).";
+const CHANGED_TOKEN_RE = /(?:^|\s)changed=(?:true|false)(?:\s|$)/;
+/** Stamp a machine-readable `changed=true|false` token (#3528 / UPGRADING.md). */
+export function stampChangedToken(entry, changed) {
+    if (CHANGED_TOKEN_RE.test(entry)) {
+        return entry;
+    }
+    return `${entry} changed=${changed ? "true" : "false"}`;
+}
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 /**
  * Resolve absolute path to PROJECT-DEFINITION. Layout-aware (#2109 part 2a):
@@ -176,10 +186,15 @@ export function resolvePolicy(projectRoot) {
 function nowIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-/** Append a one-line audit entry to meta/policy-changes.log (#746). */
-export function appendAuditLog(projectRoot, entry) {
+/** Append a one-line audit entry to meta/policy-changes.log (#746).
+ * No-op (`changed=false`) does not create or modify the tracked file (#3528). */
+export function appendAuditLog(projectRoot, entry, changed = true) {
     const root = pathResolve(projectRoot);
     const logPath = join(root, AUDIT_LOG_REL_PATH);
+    const stamped = stampChangedToken(entry, changed);
+    if (!changed) {
+        return logPath;
+    }
     // #2980 wave D: product write sink routes through containedWrite.
     if (!existsSync(logPath)) {
         const header = "# meta/policy-changes.log -- audit trail for " +
@@ -194,7 +209,7 @@ export function appendAuditLog(projectRoot, entry) {
     containedWrite({
         root,
         target: AUDIT_LOG_REL_PATH,
-        data: `${nowIso()} ${entry}\n`,
+        data: `${nowIso()} ${stamped}\n`,
         mode: "append",
     });
     return logPath;
@@ -224,7 +239,7 @@ export function setPolicy(projectRoot, options) {
             }
         }
         const plan = data.plan;
-        migrateLegacyPolicyKey(plan);
+        const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
         const existingPolicy = plan[PLAN_POLICY_KEY];
         if (typeof existingPolicy !== "object" ||
             existingPolicy === null ||
@@ -248,8 +263,7 @@ export function setPolicy(projectRoot, options) {
             delete narratives[LEGACY_NARRATIVE_KEY];
             legacyDropped = true;
         }
-        atomicWriteProjectDefinition(path, data);
-        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
+        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped || legacyKeyMigrated;
         const parts = [
             `actor=${actor}`,
             `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
@@ -261,8 +275,11 @@ export function setPolicy(projectRoot, options) {
         if (note) {
             parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
         }
-        const auditEntry = parts.join(" ");
-        appendAuditLog(projectRoot, auditEntry);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            atomicWriteProjectDefinition(path, data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };
     });
 }

package/dist/policy/runtime-authority.d.ts

@@ -11,6 +11,22 @@ export interface RuntimeAuthorityScopes {
 }
 /** Layers that contribute to a resolved write fence (#516 / #2443 / #2948 Wave 3). */
 export type WriteFenceSource = "project" | "story";
+/**
+ * Whether recognized Shell dest-forms are enforced (#3438 / #3594).
+ *
+ * `off` (default) leaves Shell mutations exactly as they were before #3438:
+ * unrecognized and fail-open. `enforce` routes recognized dest-forms through
+ * `inspectMutationGates` and fail-closes targets it cannot prove.
+ *
+ * ! Default is `off` on purpose. Before #3438 Bash mutations were not gated at
+ * all, so defaulting to `enforce` would land new denials on every consumer with
+ * no opt-out. Opting IN via tracked project policy is a narrowing, which this
+ * fence model permits; a tracked switch that DISABLED enforcement would not be
+ * (see policy/deft-directive-disable.ts — repository-controlled content must
+ * not disable hooks for downstream clones).
+ */
+export type ShellDestFormsMode = "off" | "enforce";
+export declare const SHELL_DEST_FORMS_MODES: readonly ShellDestFormsMode[];
 export interface RuntimeAuthorityPolicy {
     readonly enabled: boolean;
     /** When non-empty, write targets must match at least one pattern. Empty = allow all paths. */
@@ -18,6 +34,8 @@ export interface RuntimeAuthorityPolicy {
     /** Deny wins over allow. */
     readonly denyPaths: readonly string[];
     readonly scopes: RuntimeAuthorityScopes;
+    /** Shell dest-form enforcement (#3438 / #3594). Default `off`. */
+    readonly shellDestForms: ShellDestFormsMode;
     /**
      * Optional story-layer allow globs from `plan.metadata.swarm.file_scope`
      * (populated by `resolveWriteFence` only). When non-empty, path must match

package/dist/policy/runtime-authority.js

@@ -3,6 +3,7 @@ import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 export const FIELD_RUNTIME_AUTHORITY = "plan.policy.runtimeAuthority";
 export const FIELD_RUNTIME_AUTHORITY_CLI_ALIAS = "runtimeAuthority";
+export const SHELL_DEST_FORMS_MODES = ["off", "enforce"];
 export const DEFAULT_RUNTIME_AUTHORITY_SCOPES = {
     edits: true,
     push: false,
@@ -14,6 +15,7 @@ export const DEFAULT_RUNTIME_AUTHORITY_POLICY = {
     allowPaths: [],
     denyPaths: [],
     scopes: DEFAULT_RUNTIME_AUTHORITY_SCOPES,
+    shellDestForms: "off",
 };
 function readBoolean(rec, key, fallback) {
     if (key in rec && typeof rec[key] === "boolean") {
@@ -37,6 +39,11 @@ function readScopes(raw) {
         merge: readBoolean(rec, "merge", DEFAULT_RUNTIME_AUTHORITY_SCOPES.merge),
     };
 }
+function readShellDestForms(raw) {
+    // Unknown / malformed resolves to the safe default rather than throwing, but
+    // validateRuntimeAuthority reports it so a typo is not silent (#3594).
+    return raw === "enforce" ? "enforce" : DEFAULT_RUNTIME_AUTHORITY_POLICY.shellDestForms;
+}
 export function resolveRuntimeAuthorityPolicy(raw) {
     if (raw === null || raw === undefined) {
         return DEFAULT_RUNTIME_AUTHORITY_POLICY;
@@ -50,6 +57,7 @@ export function resolveRuntimeAuthorityPolicy(raw) {
         allowPaths: readStringArray(rec.allowPaths),
         denyPaths: readStringArray(rec.denyPaths),
         scopes: readScopes(rec.scopes),
+        shellDestForms: readShellDestForms(rec.shellDestForms),
     };
 }
 export function validateRuntimeAuthority(value) {
@@ -69,6 +77,9 @@ export function validateRuntimeAuthority(value) {
             errors.push(`${FIELD_RUNTIME_AUTHORITY}.${key} must be an array of path globs`);
         }
     }
+    if ("shellDestForms" in rec && !SHELL_DEST_FORMS_MODES.includes(rec.shellDestForms)) {
+        errors.push(`${FIELD_RUNTIME_AUTHORITY}.shellDestForms must be one of ${SHELL_DEST_FORMS_MODES.join(" | ")}`);
+    }
     if ("scopes" in rec) {
         const scopes = rec.scopes;
         if (typeof scopes !== "object" || scopes === null || Array.isArray(scopes)) {

package/dist/policy/value-feedback.js

@@ -3,7 +3,7 @@ import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "..
 import { valueFeedbackInstallForceOnSource } from "./org-force-on-migration.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 { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
 import { isTrustedOrgAutoEnable } from "./value-feedback-autoenable.js";
 /** Canonical registered policy field name (matches other FIELD_* dotted paths). */
 export const FIELD_VALUE_FEEDBACK = "plan.policy.valueFeedback";
@@ -236,7 +236,7 @@ export function enableValueFeedback(projectRoot, options) {
                 }
             }
             const plan = data.plan;
-            migrateLegacyPolicyKey(plan);
+            const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
             const existingPolicy = plan[PLAN_POLICY_KEY];
             if (typeof existingPolicy !== "object" ||
                 existingPolicy === null ||
@@ -273,7 +273,8 @@ export function enableValueFeedback(projectRoot, options) {
             const changedFlag = previousNormalized.enabled !== nextBlock.enabled ||
                 previousNormalized.emitEvents !== nextBlock.emitEvents ||
                 previousNormalized.sessionLine !== nextBlock.sessionLine ||
-                previousNormalized.upstreamPrompt !== nextBlock.upstreamPrompt;
+                previousNormalized.upstreamPrompt !== nextBlock.upstreamPrompt ||
+                legacyKeyMigrated;
             policyBlock.valueFeedback = nextBlock;
             if (changedFlag) {
                 atomicWriteProjectDefinition(path, data);
@@ -291,15 +292,13 @@ export function enableValueFeedback(projectRoot, options) {
             if (note) {
                 parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
             }
-            appendAuditLog(projectRoot, parts.join(" "));
+            appendAuditLog(projectRoot, parts.join(" "), changedFlag);
             return { changed: changedFlag };
         });
         const resolved = resolveValueFeedback(projectRoot);
         const lines = [
             `\u2713 ${FIELD_VALUE_FEEDBACK}.enabled=true (value-feedback ON).`,
-            changed
-                ? "  audit: meta/policy-changes.log updated."
-                : "  no-op: value already matched (audit entry still appended for trail).",
+            changed ? "  audit: meta/policy-changes.log updated." : POLICY_AUDIT_NOOP_STDOUT,
             formatValueFeedbackStatusLine(resolved),
         ];
         return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };
@@ -354,7 +353,7 @@ export function clearValueFeedback(projectRoot, options = {}) {
             if (note) {
                 parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
             }
-            appendAuditLog(projectRoot, parts.join(" "));
+            appendAuditLog(projectRoot, parts.join(" "), true);
             return { changed: true };
         });
         const resolved = resolveValueFeedback(projectRoot);

package/dist/policy/write-fence.js

@@ -140,6 +140,9 @@ export function resolveWriteFence(projectPolicy, storyFileScope, options) {
         allowPaths,
         denyPaths,
         scopes,
+        // Carry the project setting through: resolving a write fence must not
+        // silently enable Shell dest-form enforcement for a story (#3438 / #3594).
+        shellDestForms: projectPolicy.shellDestForms,
         storyAllowPaths: storyAllow,
         fenceSources: sources,
     };

package/dist/preflight-cache/evaluate.d.ts

@@ -32,6 +32,12 @@ export interface EvaluateOptions {
     forIssue?: number | null;
     allowStale?: boolean;
     allowMissingBootstrap?: boolean;
+    /**
+     * Skip the live GitHub drift probe only (#3507). Age staleness stays hard.
+     * Explicit flag — never inferred from a missing `--for-issue`.
+     * `--for-issue` (work selection) wins over this skip.
+     */
+    skipDriftProbe?: boolean;
     /** Injectable clock for tests. */
     nowFn?: () => Date;
     /** Injectable drift probe for tests. */
@@ -40,6 +46,12 @@ export interface EvaluateOptions {
     autoPopulateEmpty?: boolean;
 }
 export declare function normaliseRepoUrl(url: string): string | null;
+/**
+ * Drift skip is an explicit `--skip-drift-probe` request (#3507).
+ * Presence of `--for-issue` is work selection and re-arms the probe.
+ * Absence of `--for-issue` is not a skip signal.
+ */
+export declare function shouldSkipDriftProbe(options: EvaluateOptions): boolean;
 /**
  * Evaluate cache freshness for the given project root.
  *

package/dist/preflight-cache/evaluate.js

@@ -300,16 +300,32 @@ function formatDriftFailure(repo, drift) {
     };
 }
 function runDriftProbe(resolvedRepo, cacheRoot, source, options) {
-    if (options.probeDriftFn) {
-        return options.probeDriftFn(resolvedRepo, cacheRoot, source);
-    }
     try {
+        if (options.probeDriftFn) {
+            return options.probeDriftFn(resolvedRepo, cacheRoot, source);
+        }
         return probeCacheDrift({ repo: resolvedRepo, source, cacheRoot });
     }
     catch {
+        // Deliberate fail-open (#3738 / #3422): a thrown probe (429 after retry,
+        // 502/503, DNS, auth) returns null; evaluate treats null as pass.
+        // Work-selection / session:start still inherit this. The write path no
+        // longer executes cache_fresh, so this is not a write-authorization bypass.
+        // Do not silently convert to fail-closed without revisiting #3422 (local
+        // work MAY continue when it does not need the forge).
         return null;
     }
 }
+/**
+ * Drift skip is an explicit `--skip-drift-probe` request (#3507).
+ * Presence of `--for-issue` is work selection and re-arms the probe.
+ * Absence of `--for-issue` is not a skip signal.
+ */
+export function shouldSkipDriftProbe(options) {
+    if (options.forIssue !== undefined && options.forIssue !== null)
+        return false;
+    return options.skipDriftProbe === true;
+}
 const REMEDIATION_NO_CANDIDATES = [
     "  Recovery: run `deft triage:bootstrap` to initialise the triage log.",
 ].join("\n");
@@ -471,7 +487,8 @@ function evaluateWithContext(projectRoot, options, ctx) {
             ].join("\n"),
         };
     }
-    if (resolvedRepo !== null && !allowStale) {
+    const skipDrift = shouldSkipDriftProbe(options);
+    if (resolvedRepo !== null && !allowStale && !skipDrift) {
         const drift = runDriftProbe(resolvedRepo, cacheRoot, source, options);
         if (drift !== null &&
             (drift.stateDriftNumbers.length > 0 || drift.contentDriftNumbers.length > 0)) {
@@ -506,6 +523,9 @@ function evaluateWithContext(projectRoot, options, ctx) {
     if (options.forIssue !== undefined && options.forIssue !== null) {
         msg += ` Issue #${options.forIssue} latest decision = accept; in subscription scope.`;
     }
+    if (skipDrift) {
+        msg += " Drift probe skipped (no work selection).";
+    }
     return { code: 0, message: msg };
 }
 function evaluateForIssue(repo, issueNumber, candidatesPath, cacheRoot, source, scopeRules, _projectRoot) {

package/dist/preflight-cache/index.d.ts

@@ -1,3 +1,3 @@
 export type { EvaluateOptions, GateResult } from "./evaluate.js";
-export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
+export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, shouldSkipDriftProbe, } from "./evaluate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/preflight-cache/index.js

@@ -1,2 +1,2 @@
-export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
+export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, shouldSkipDriftProbe, } from "./evaluate.js";
 //# sourceMappingURL=index.js.map

package/dist/product-first-done-gate/evaluate.d.ts

@@ -23,6 +23,10 @@ export interface VerifyAcResult extends LiteralAcceptanceGateResult {
     readonly clauseWalked?: boolean;
     /** How the result was obtained (#3387). */
     readonly servedFrom?: AcServedFrom;
+    /** Config-error cause when resolution is config (#3559). */
+    readonly cause?: string;
+    /** Reuse-gate miss cause when servedFrom is executed (#3558). */
+    readonly missReason?: string;
 }
 export interface EvaluateVerifyAcOptions extends EvaluateLiteralAcceptanceOptions {
     /**