@deftai/directive-core 0.105.0 → 0.106.0

package/dist/lifecycle-visible/index.d.ts

@@ -0,0 +1,2 @@
+export { type CheckIgnoreMatch, displayIgnoreSource, evaluateLifecycleVisible, formatLifecycleVisibleSessionLines, indexFlagKind, isSelectiveLifecyclePath, LIFECYCLE_ROOT_PREFIXES, LIFECYCLE_STAGE_DIRS, type LifecycleHideFinding, type LifecycleHideKind, type LifecycleVisibleOptions, type LifecycleVisibleResult, type LsFilesVerboseRecord, lifecycleRootRelPaths, parseCheckIgnoreVerboseLine, parseLsFilesVerboseRecord, } from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle-visible/index.js

@@ -0,0 +1,2 @@
+export { displayIgnoreSource, evaluateLifecycleVisible, formatLifecycleVisibleSessionLines, indexFlagKind, isSelectiveLifecyclePath, LIFECYCLE_ROOT_PREFIXES, LIFECYCLE_STAGE_DIRS, lifecycleRootRelPaths, parseCheckIgnoreVerboseLine, parseLsFilesVerboseRecord, } from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/literal-acceptance/capture.js

@@ -167,12 +167,12 @@ function matchLabeledCommand(line) {
         return null;
     return line.slice(i).trimEnd();
 }
-/** `$ cmd` or `> cmd` prompt lines. */
+/** `$ cmd` prompt lines. Markdown blockquote `>` is not a prompt (#3572). */
 function matchPromptCommand(line) {
     let i = skipWs(line, 0);
     if (i >= line.length)
         return null;
-    if (line[i] !== "$" && line[i] !== ">")
+    if (line[i] !== "$")
         return null;
     i = skipWs(line, i + 1);
     if (i >= line.length)
@@ -259,7 +259,7 @@ function flushFenceBody(body, fenceLang, fenceStartLine, requireRegion, regionAc
         return;
     if (!isShellFenceLang(fenceLang))
         return;
-    // Transcript lines are skipped. `$`/`>` prompts inside a transcript fence are
+    // Transcript lines are skipped. `$` prompts inside a transcript fence are
     // suggested-fixes (biome migrate), not stated AC (#3511). Comments do not
     // mark a fence as transcript, so a genuine command next to `# Error:` still
     // captures.

package/dist/orchestration/judgment-policy.d.ts

@@ -2,6 +2,19 @@ export declare const GATE_CLASSES: Set<string>;
 export declare const GATE_TIERS: Set<string>;
 export declare const GATE_MATCH_PREDICATES: Set<string>;
 export declare const GATE_MATCH_STATES: Set<string>;
+/** ADR-005 / #3434 Story 1 -- author-stamped marker vocabulary. */
+export declare const DESIGN_CRITIQUE_GATE_ID = "design-critique";
+/** List-visible mirror; this is what judgmentGates predicates match. */
+export declare const DESIGN_CRITIQUE_MARKER_LABEL = "design-critique:mechanism-shaped";
+/** Authoritative body-text field in the #1423 triage write-back comment. */
+export declare const DESIGN_CRITIQUE_MARKER_FIELD = "mechanism-shaped: true";
+/**
+ * Clearance line shape (ADR-005). Presence and shape only -- a non-empty
+ * because-clause is required; its semantic content is never evaluated.
+ */
+export declare const DESIGN_CRITIQUE_CLEARANCE_SHAPE: RegExp;
+/** True when `line` has clearance presence+shape. Never scores the reason text. */
+export declare function designCritiqueClearanceShapeOk(line: string): boolean;
 export interface JudgmentGate {
     readonly gate_id: string;
     readonly gate_class: string;

package/dist/orchestration/judgment-policy.js

@@ -7,6 +7,21 @@ export const GATE_CLASSES = new Set(["mechanical", "declared"]);
 export const GATE_TIERS = new Set(["auto", "review", "block"]);
 export const GATE_MATCH_PREDICATES = new Set(["labels", "body-text", "paths", "state", "age-days"]);
 export const GATE_MATCH_STATES = new Set(["open", "closed"]);
+/** ADR-005 / #3434 Story 1 -- author-stamped marker vocabulary. */
+export const DESIGN_CRITIQUE_GATE_ID = "design-critique";
+/** List-visible mirror; this is what judgmentGates predicates match. */
+export const DESIGN_CRITIQUE_MARKER_LABEL = "design-critique:mechanism-shaped";
+/** Authoritative body-text field in the #1423 triage write-back comment. */
+export const DESIGN_CRITIQUE_MARKER_FIELD = "mechanism-shaped: true";
+/**
+ * Clearance line shape (ADR-005). Presence and shape only -- a non-empty
+ * because-clause is required; its semantic content is never evaluated.
+ */
+export const DESIGN_CRITIQUE_CLEARANCE_SHAPE = /^design-critique:\s*(warranted|not warranted),\s*because\s+\S/i;
+/** True when `line` has clearance presence+shape. Never scores the reason text. */
+export function designCritiqueClearanceShapeOk(line) {
+    return DESIGN_CRITIQUE_CLEARANCE_SHAPE.test(line.trim());
+}
 function validateStrList(value, prefix, key) {
     if (!Array.isArray(value) || value.length === 0) {
         return [`${prefix}.${key} must be a non-empty list of strings`];

package/dist/orchestration/probe-session.js

@@ -12,6 +12,11 @@ export const SESSION_RELPATH = [".deft", "probe-session.json"];
 export const STATE_INTERROGATE = "interrogate";
 export const STATE_COMPLETE = "complete";
 export const VALID_DECISION_STATUSES = new Set(["locked", "deferred", "risk-accepted"]);
+/** Live CLI teach-string (#3556). The Python helper was deleted. */
+const PROBE_SESSION_START = "`deft probe-session start --target <scope>`";
+const PROBE_SESSION_RECORD = "`deft probe-session record ...`";
+const PROBE_SESSION_COMPLETE = "`deft probe-session complete`";
+const NO_SESSION_START = `No active probe session. Start one with ${PROBE_SESSION_START}.`;
 export class ProbeHandoffBlockedError extends Error {
     session;
     constructor(message, session = null) {
@@ -249,7 +254,7 @@ export function startSession(projectRoot, options) {
 export function recordDecision(projectRoot, options) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state !== STATE_INTERROGATE) {
         throw new ProbeHandoffBlockedError("Probe session is already complete; decisions cannot be appended.", session);
@@ -275,7 +280,7 @@ export function recordDecision(projectRoot, options) {
 export function setCurrentBranch(projectRoot, branch) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state !== STATE_INTERROGATE) {
         throw new ProbeHandoffBlockedError("Probe session is already complete; current branch cannot change.", session);
@@ -287,7 +292,7 @@ export function setCurrentBranch(projectRoot, branch) {
 export function markComplete(projectRoot, now) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state === STATE_COMPLETE) {
         return session;
@@ -307,7 +312,7 @@ function pythonRepr(value) {
 function blockedMessage(session, action) {
     if (session === null) {
         return (`Probe handoff blocked for ${action}: no active probe session. ` +
-            "Start interrogation with `uv run python scripts/probe_session.py start --target <scope>` " +
+            `Start interrogation with ${PROBE_SESSION_START} ` +
             "and finish with `... complete` only after transition criteria are met.");
     }
     return (`Probe handoff blocked for ${action}: session state is ` +
@@ -315,9 +320,9 @@ function blockedMessage(session, action) {
         `currentBranch=${pythonRepr(session.current_branch)}, ` +
         `resolvedDecisions=${session.resolved_decisions.length}). ` +
         "Continue interrogation until transition criteria are met, record decisions " +
-        "with `uv run python scripts/probe_session.py record ...`, then run " +
-        "`uv run python scripts/probe_session.py complete` before writing artifacts " +
-        "or updating completedStrategies.probe in plan.vbrief.json.");
+        `with ${PROBE_SESSION_RECORD}, then run ` +
+        `${PROBE_SESSION_COMPLETE} before writing artifacts ` +
+        "or updating completedStrategies.probe in plan.xbrief.json.");
 }
 export function requireHandoffAllowed(projectRoot, action) {
     const session = readSession(projectRoot);
@@ -330,7 +335,7 @@ export function guardProbeArtifact(projectRoot, artifactPath) {
     return requireHandoffAllowed(projectRoot, `probe artifact write (${artifactPath})`);
 }
 export function guardPlanProbeRegistration(projectRoot) {
-    return requireHandoffAllowed(projectRoot, "completedStrategies.probe registration in plan.vbrief.json");
+    return requireHandoffAllowed(projectRoot, "completedStrategies.probe registration in plan.xbrief.json");
 }
 export function sessionSummary(session) {
     return {

package/dist/orchestration/verify-judgment-gates.d.ts

@@ -2,6 +2,10 @@
  * Risk-tiered judgment-gate engine (#1419 Slice 3). Port of scripts/verify_judgment_gates.py.
  */
 import { type JudgmentGatesPolicy } from "./judgment-policy.js";
+/** Thrown when a design-critique clearance reason fails presence/shape (never content). */
+export declare class JudgmentClearanceShapeError extends Error {
+    constructor(message: string);
+}
 /** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export declare const AUDIT_DIR_REL = "vbrief/.audit";
 export declare const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";

package/dist/orchestration/verify-judgment-gates.js

@@ -7,8 +7,15 @@ import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, statSyn
 import { join, resolve } from "node:path";
 import { assertProjectionContained, assertWriteTargetSafe, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { resolveAuditDir } from "../layout/resolve.js";
-import { resolveJudgmentGates } from "./judgment-policy.js";
+import { DESIGN_CRITIQUE_GATE_ID, designCritiqueClearanceShapeOk, resolveJudgmentGates, } from "./judgment-policy.js";
 import { matchAny } from "./pathspec.js";
+/** Thrown when a design-critique clearance reason fails presence/shape (never content). */
+export class JudgmentClearanceShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JudgmentClearanceShapeError";
+    }
+}
 /** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export const AUDIT_DIR_REL = "vbrief/.audit";
 export const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";
@@ -163,6 +170,12 @@ export function readClearances(projectRoot, logPath) {
     return out;
 }
 export function recordClearance(projectRoot, options) {
+    if (options.gate_id === DESIGN_CRITIQUE_GATE_ID &&
+        !designCritiqueClearanceShapeOk(options.reason ?? "")) {
+        throw new JudgmentClearanceShapeError("design-critique clearance reason must match shape " +
+            "'design-critique: warranted | not warranted, because ...' " +
+            "(presence and shape only; the because-clause is not scored)");
+    }
     const path = options.log_path ?? clearanceLogPath(projectRoot);
     const auditDir = resolveAuditDir(projectRoot);
     assertProjectionContained(projectRoot, auditDir);
@@ -202,6 +215,15 @@ export function fingerprintScope(evidence) {
     const payload = JSON.stringify(sorted);
     return createHash("sha256").update(payload, "utf8").digest("hex");
 }
+function acceptClearanceShape(gateId, clearance) {
+    if (clearance === null) {
+        return null;
+    }
+    if (gateId !== DESIGN_CRITIQUE_GATE_ID) {
+        return clearance;
+    }
+    return designCritiqueClearanceShapeOk(String(clearance.reason ?? "")) ? clearance : null;
+}
 function lookupClearance(clearances, gateId, scope) {
     let valid = null;
     let stale = null;
@@ -383,7 +405,8 @@ export function buildReport(projectRoot, candidate, options = {}) {
             continue;
         }
         const scope = fingerprintScope(evidence);
-        const [valid, stale] = lookupClearance(records, String(gate.id), scope);
+        const [validRaw, stale] = lookupClearance(records, String(gate.id), scope);
+        const valid = acceptClearanceShape(String(gate.id), validRaw);
         outcomes.push({
             gate_id: String(gate.id),
             gate_class: String(gate.class),
@@ -605,15 +628,24 @@ function clearMain(argv) {
     if (args.updatedAt !== null)
         evidence["age-days"] = args.updatedAt;
     const scope = fingerprintScope(evidence);
-    const entry = recordClearance(projectRoot, {
-        gate_id: args.gateId,
-        cleared_scope: scope,
-        reviewers: args.reviewers,
-        actor: args.actor,
-        reason: args.reason,
-    });
-    process.stdout.write(`recorded clearance ${String(entry.clearance_id)} for gate ${JSON.stringify(args.gateId)} (cleared_scope=${scope.slice(0, 12)}...)\n`);
-    return 0;
+    try {
+        const entry = recordClearance(projectRoot, {
+            gate_id: args.gateId,
+            cleared_scope: scope,
+            reviewers: args.reviewers,
+            actor: args.actor,
+            reason: args.reason,
+        });
+        process.stdout.write(`recorded clearance ${String(entry.clearance_id)} for gate ${JSON.stringify(args.gateId)} (cleared_scope=${scope.slice(0, 12)}...)\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof JudgmentClearanceShapeError) {
+            process.stderr.write(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
 }
 function parseEvalArgs(argv) {
     const parsed = {

package/dist/policy/ceremony-dial.js

@@ -23,7 +23,7 @@ import { RunSummaryEmitter } from "../run-summary/emit.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, projectDefinitionPath } from "./resolve.js";
+import { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
 /** Canonical dotted policy field name. */
 export const FIELD_CEREMONY_DIAL = "plan.policy.ceremonyDial";
 /** Short alias for `policy:show --field=ceremonyDial`. */
@@ -527,7 +527,7 @@ export function setCeremonyDial(projectRoot, options) {
                 }
             }
             const plan = data.plan;
-            migrateLegacyPolicyKey(plan);
+            const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
             const existingPolicy = plan[PLAN_POLICY_KEY];
             if (typeof existingPolicy !== "object" ||
                 existingPolicy === null ||
@@ -564,7 +564,9 @@ export function setCeremonyDial(projectRoot, options) {
                 override: nextOverride,
             };
             const prevParsed = parseConfig(previous).config;
-            const changedFlag = prevParsed.enabled !== nextBlock.enabled || prevParsed.override !== nextBlock.override;
+            const changedFlag = prevParsed.enabled !== nextBlock.enabled ||
+                prevParsed.override !== nextBlock.override ||
+                legacyKeyMigrated;
             policyBlock.ceremonyDial = nextBlock;
             if (changedFlag) {
                 atomicWriteProjectDefinition(path, data);
@@ -580,15 +582,13 @@ export function setCeremonyDial(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 = resolveCeremonyDial(projectRoot);
         const lines = [
             `\u2713 ${FIELD_CEREMONY_DIAL} updated.`,
-            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,
             formatCeremonyDialStatusLine(resolved),
         ];
         return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };

package/dist/policy/host-hooks.d.ts

@@ -1,6 +1,12 @@
 import type { HookHost } from "../hooks/dispatcher.js";
+export type { HookHost };
 export declare const FIELD_HOST_HOOKS = "plan.policy.hostHooks";
 export declare const FIELD_HOST_HOOKS_CLI_ALIAS = "hostHooks";
+export declare const DISABLE_HOST_HOOKS_SUBCOMMAND = "disable-host-hooks";
+/** Confirm-gated disable verb for unused-host recovery copy (#3571). CLI form: no go-task `--`. */
+export declare function disableHostHooksInvocation(trailing?: string): string;
+export declare const HOST_HOOKS_DISABLE_CAPABILITY_COST_DISCLOSURE: string;
+export declare const UNUSED_HOST_HOOKS_RECOVERY: string;
 /** Per-host Directive hook deposit toggles (#2752). */
 export type HostHooksPolicy = Record<HookHost, boolean>;
 export declare const DEFAULT_HOST_HOOKS_POLICY: HostHooksPolicy;
@@ -18,4 +24,18 @@ export declare function isHostHookDepositEnabled(host: HookHost, policy?: HostHo
 export declare function inspectHostHooks(data: Record<string, unknown> | null): HostHooksPolicyField;
 /** Resolve host hook deposit policy from PROJECT-DEFINITION on disk. */
 export declare function loadHostHooksPolicyFromProject(projectRoot: string): HostHooksPolicy;
+export declare function parseHookHost(value: string | undefined): HookHost | null;
+export interface DisableHostHooksOptions {
+    readonly host: HookHost;
+    readonly confirm: boolean;
+    readonly actor?: string;
+    readonly note?: string;
+}
+export interface DisableHostHooksResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/** Persist `hostHooks.<host>=false` after capability-cost disclosure (#3571). */
+export declare function disableHostHooks(projectRoot: string, options: DisableHostHooksOptions): DisableHostHooksResult;
 //# sourceMappingURL=host-hooks.d.ts.map

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;