@deftai/directive-core 0.87.0 → 0.89.0

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

@@ -1,8 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { sortKeysDeep } from "../codebase/json.js";
 import { readCorePackageVersion } from "../engine-version.js";
-import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { isNoDeftDirectivePresent } from "./no-deft-directive.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
 import { detectOriginOrg, isTrustedOrgAutoEnable, } from "./value-feedback-autoenable.js";
@@ -20,6 +22,18 @@ const DEFAULT_PRODUCT_SIGNAL_SINK = "deftai/product-signal";
 function markerPath(projectRoot) {
     return resolve(projectRoot, ORG_FORCE_ON_MARKER_REL);
 }
+/** Normalize undefined → null and deep-sort keys so marker snapshots compare stably. */
+export function normalizePolicySnapshot(raw) {
+    return sortKeysDeep(raw === undefined ? null : raw);
+}
+/**
+ * Structural equality for policy snapshots (#2903).
+ * Key order independent via sortKeysDeep — discarded-PD recovery must not miss
+ * semantically equal blocks written with different JSON key order.
+ */
+export function deepEqualPolicySnapshot(a, b) {
+    return JSON.stringify(normalizePolicySnapshot(a)) === JSON.stringify(normalizePolicySnapshot(b));
+}
 function parseMarker(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         return null;
@@ -33,7 +47,7 @@ function parseMarker(raw) {
         typeof rec.directiveVersion !== "string") {
         return null;
     }
-    return {
+    const marker = {
         version: ORG_FORCE_ON_MARKER_VERSION,
         appliedAt: rec.appliedAt,
         originOrg: rec.originOrg,
@@ -41,6 +55,23 @@ function parseMarker(raw) {
         productSignal: rec.productSignal,
         directiveVersion: rec.directiveVersion,
     };
+    // Optional #2903 previous* snapshots — preserve when present (including null).
+    if ("previousValueFeedback" in rec) {
+        return {
+            ...marker,
+            previousValueFeedback: rec.previousValueFeedback,
+            ...("previousProductSignal" in rec
+                ? { previousProductSignal: rec.previousProductSignal }
+                : {}),
+        };
+    }
+    if ("previousProductSignal" in rec) {
+        return {
+            ...marker,
+            previousProductSignal: rec.previousProductSignal,
+        };
+    }
+    return marker;
 }
 /** Read the #2822 migration marker when present and valid. */
 export function readOrgForceOnMarker(projectRoot) {
@@ -57,9 +88,13 @@ export function readOrgForceOnMarker(projectRoot) {
 }
 function writeOrgForceOnMarker(projectRoot, marker) {
     const path = markerPath(projectRoot);
-    assertWriteTargetSafe(projectRoot, path);
-    mkdirSync(join(path, ".."), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+    // #2951 Phase 2: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify(marker, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 function readTypedBoolean(raw, key, fallback) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -81,6 +116,83 @@ function valueFeedbackNeedsForceOn(raw) {
 function productSignalNeedsForceOn(raw) {
     return !readTypedBoolean(raw, "enabled", false);
 }
+/**
+ * Sentinel previous* for an unforced field that had no stored baseline (legacy
+ * partial recovery). Must not deep-equal any real policy snapshot — including
+ * null/undefined after clear-value-feedback — or the next update would re-force.
+ */
+export const ORG_FORCE_ON_NO_BASELINE = {
+    "x-directive/org-force-on": "no-baseline",
+};
+/** Classic #2822 pre-migration all-false valueFeedback baseline (statusreport). */
+export const PRE_MIGRATION_VALUE_FEEDBACK_BASELINE = {
+    enabled: false,
+    emitEvents: false,
+    sessionLine: false,
+    upstreamPrompt: false,
+};
+/** True when current VF looks like discarded pre-migration state (legacy markers). */
+export function looksLikePreMigrationValueFeedback(raw) {
+    // Missing key (undefined/null) is NOT the classic baseline — that is the
+    // clear-value-feedback / never-typed shape. statusreport-class discard keeps
+    // an explicit all-false object in PROJECT-DEFINITION.
+    if (raw === undefined || raw === null) {
+        return false;
+    }
+    return deepEqualPolicySnapshot(raw, PRE_MIGRATION_VALUE_FEEDBACK_BASELINE);
+}
+/** True when current PS looks like discarded pre-migration state (legacy markers). */
+export function looksLikePreMigrationProductSignal(raw) {
+    if (raw === undefined || raw === null) {
+        return true;
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return false;
+    }
+    const block = raw;
+    if (block.enabled !== false) {
+        return false;
+    }
+    const keys = Object.keys(block);
+    // Bare {enabled:false} or default sink only — custom sinkRepo implies intent.
+    if (keys.length === 1) {
+        return true;
+    }
+    if (keys.length === 2 &&
+        typeof block.sinkRepo === "string" &&
+        block.sinkRepo.trim() === DEFAULT_PRODUCT_SIGNAL_SINK) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Incomplete migration (#2903): marker present, PD still needs force-on, and
+ * current typed block still equals the pre-migration snapshot (or legacy marker
+ * has no previous* field and current still looks like the classic baseline).
+ *
+ * Exact restore of the pre-migration snapshot is treated as incomplete by design
+ * (company policy #2376 / #2822 / #2903): discarded working-tree force-on and
+ * "put the old all-false block back" are not distinguishable without git history,
+ * and trusted-org local collection should stay ON. True intentional opt-out must
+ * use a shape that differs from previous*, `policy:clear-value-feedback`, or
+ * root `.no-deft-directive`. Outbound product-signal still requires D17 consent.
+ *
+ * Legacy markers without previous*: only re-apply fields that still look like the
+ * classic pre-migration baseline so a distinct intentional sibling opt-out is kept.
+ */
+export function isIncompleteForceOnField(needsForceOn, current, previousSnapshot, previousFieldPresent, field = "valueFeedback") {
+    if (!needsForceOn) {
+        return false;
+    }
+    // Legacy markers written before #2903 lack previous* — recover only classic
+    // baseline shapes (statusreport-class), not distinct intentional opt-outs.
+    if (!previousFieldPresent) {
+        return field === "valueFeedback"
+            ? looksLikePreMigrationValueFeedback(current)
+            : looksLikePreMigrationProductSignal(current);
+    }
+    return deepEqualPolicySnapshot(current, previousSnapshot);
+}
 function ensurePolicyBlock(plan) {
     migrateLegacyPolicyKey(plan);
     const existing = plan[PLAN_POLICY_KEY];
@@ -94,31 +206,97 @@ function ensurePolicyBlock(plan) {
     }
     return plan[PLAN_POLICY_KEY];
 }
-function writeMarkerForSkip(projectRoot, options, valueFeedback, productSignal) {
+function writeMarker(projectRoot, options, input) {
     const originOrg = detectOriginOrg(projectRoot, options.autoEnable) ?? "unknown";
     const now = options.now ?? new Date();
     writeOrgForceOnMarker(projectRoot, {
         version: ORG_FORCE_ON_MARKER_VERSION,
         appliedAt: now.toISOString().replace(/\.\d{3}Z$/, "Z"),
         originOrg,
-        valueFeedback,
-        productSignal,
+        valueFeedback: input.valueFeedback,
+        productSignal: input.productSignal,
         directiveVersion: readCorePackageVersion(),
+        previousValueFeedback: normalizePolicySnapshot(input.previousValueFeedback),
+        previousProductSignal: normalizePolicySnapshot(input.previousProductSignal),
     });
 }
+function readPolicyFieldSnapshots(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return { ok: false, skippedReason: err ?? "project-definition-missing" };
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    const policyObj = typeof policyBlock === "object" && policyBlock !== null && !Array.isArray(policyBlock)
+        ? policyBlock
+        : {};
+    const vfRaw = "valueFeedback" in policyObj ? policyObj.valueFeedback : undefined;
+    const psRaw = "productSignal" in policyObj ? policyObj.productSignal : undefined;
+    return {
+        ok: true,
+        vfRaw,
+        psRaw,
+        needsVf: valueFeedbackNeedsForceOn(vfRaw),
+        needsPs: productSignalNeedsForceOn(psRaw),
+    };
+}
 /**
  * One-time trusted-org install/upgrade force-on for valueFeedback + productSignal
  * (#2822). Idempotent via durable marker; non-trusted orgs are unchanged.
+ *
+ * #2903 verify-on-skip: when the marker is present but PROJECT-DEFINITION still
+ * matches the pre-migration snapshot (discarded / never-landed force-on write),
+ * re-apply. Intentional post-migration shapes that differ from both the previous
+ * snapshot and the force-on block keep the skip.
  */
 export function runOrgForceOnMigration(projectRoot, options = {}) {
-    if (readOrgForceOnMarker(projectRoot) !== null) {
+    // #2926: per-project opt-out wins over ambient trusted-org force-on (v1).
+    if (isNoDeftDirectivePresent(projectRoot)) {
         return {
             ran: false,
-            skippedReason: "marker-present",
+            skippedReason: "no-deft-directive",
             valueFeedbackChanged: false,
             productSignalChanged: false,
         };
     }
+    const existingMarker = readOrgForceOnMarker(projectRoot);
+    if (existingMarker !== null) {
+        const snapshots = readPolicyFieldSnapshots(projectRoot);
+        if (!snapshots.ok) {
+            return {
+                ran: false,
+                skippedReason: "marker-present",
+                valueFeedbackChanged: false,
+                productSignalChanged: false,
+            };
+        }
+        const previousVfPresent = "previousValueFeedback" in existingMarker;
+        const previousPsPresent = "previousProductSignal" in existingMarker;
+        const incompleteVf = isIncompleteForceOnField(snapshots.needsVf, snapshots.vfRaw, existingMarker.previousValueFeedback, previousVfPresent, "valueFeedback");
+        const incompletePs = isIncompleteForceOnField(snapshots.needsPs, snapshots.psRaw, existingMarker.previousProductSignal, previousPsPresent, "productSignal");
+        // Marker present and either already force-on shaped, or intentional opt-out
+        // (current differs from stored previous snapshot) → keep skip.
+        if (!incompleteVf && !incompletePs) {
+            return {
+                ran: false,
+                skippedReason: "marker-present",
+                valueFeedbackChanged: false,
+                productSignalChanged: false,
+            };
+        }
+        // Incomplete migration: fall through to trusted-org apply with only the
+        // incomplete fields re-forced.
+        if (!isTrustedOrgAutoEnable(projectRoot, options.autoEnable)) {
+            return {
+                ran: false,
+                skippedReason: "marker-present",
+                valueFeedbackChanged: false,
+                productSignalChanged: false,
+            };
+        }
+        // Pre-lock incomplete check is a fast path only; applyForceOn revalidates
+        // under the mutation lock against the latest PD (#2903 TOCTOU).
+        return applyForceOn(projectRoot, options, { existingMarker });
+    }
     if (!isTrustedOrgAutoEnable(projectRoot, options.autoEnable)) {
         return {
             ran: false,
@@ -127,25 +305,22 @@ export function runOrgForceOnMigration(projectRoot, options = {}) {
             productSignalChanged: false,
         };
     }
-    const [data, err] = loadProjectDefinition(projectRoot);
-    if (data === null) {
+    const snapshots = readPolicyFieldSnapshots(projectRoot);
+    if (!snapshots.ok) {
         return {
             ran: false,
-            skippedReason: err ?? "project-definition-missing",
+            skippedReason: snapshots.skippedReason,
             valueFeedbackChanged: false,
             productSignalChanged: false,
         };
     }
-    const policyBlock = readPlanPolicy(data.plan);
-    const policyObj = typeof policyBlock === "object" && policyBlock !== null && !Array.isArray(policyBlock)
-        ? policyBlock
-        : {};
-    const vfRaw = "valueFeedback" in policyObj ? policyObj.valueFeedback : undefined;
-    const psRaw = "productSignal" in policyObj ? policyObj.productSignal : undefined;
-    const needsVf = valueFeedbackNeedsForceOn(vfRaw);
-    const needsPs = productSignalNeedsForceOn(psRaw);
-    if (!needsVf && !needsPs) {
-        writeMarkerForSkip(projectRoot, options, false, false);
+    if (!snapshots.needsVf && !snapshots.needsPs) {
+        writeMarker(projectRoot, options, {
+            valueFeedback: false,
+            productSignal: false,
+            previousValueFeedback: snapshots.vfRaw,
+            previousProductSignal: snapshots.psRaw,
+        });
         return {
             ran: false,
             skippedReason: "already-enabled",
@@ -153,9 +328,15 @@ export function runOrgForceOnMigration(projectRoot, options = {}) {
             productSignalChanged: false,
         };
     }
+    return applyForceOn(projectRoot, options, { existingMarker: null });
+}
+function applyForceOn(projectRoot, options, intent) {
     const path = projectDefinitionPath(projectRoot);
     let valueFeedbackChanged = false;
     let productSignalChanged = false;
+    let ran = false;
+    let skippedReason = null;
+    const existing = intent.existingMarker;
     projectDefinitionMutationLock(projectRoot, () => {
         const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
         if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -176,6 +357,36 @@ export function runOrgForceOnMigration(projectRoot, options = {}) {
         const policy = ensurePolicyBlock(plan);
         const previousVf = policy.valueFeedback;
         const previousPs = policy.productSignal;
+        // Revalidate under lock so a concurrent intentional opt-out between the
+        // unlocked snapshot check and lock acquisition is not overwritten (#2903).
+        let needsVf;
+        let needsPs;
+        if (existing !== null) {
+            const previousVfPresent = "previousValueFeedback" in existing;
+            const previousPsPresent = "previousProductSignal" in existing;
+            needsVf = isIncompleteForceOnField(valueFeedbackNeedsForceOn(previousVf), previousVf, existing.previousValueFeedback, previousVfPresent, "valueFeedback");
+            needsPs = isIncompleteForceOnField(productSignalNeedsForceOn(previousPs), previousPs, existing.previousProductSignal, previousPsPresent, "productSignal");
+        }
+        else {
+            needsVf = valueFeedbackNeedsForceOn(previousVf);
+            needsPs = productSignalNeedsForceOn(previousPs);
+        }
+        if (!needsVf && !needsPs) {
+            // Under-lock state no longer needs force-on (concurrent opt-out or already ON).
+            if (existing === null) {
+                writeMarker(projectRoot, options, {
+                    valueFeedback: false,
+                    productSignal: false,
+                    previousValueFeedback: previousVf,
+                    previousProductSignal: previousPs,
+                });
+                skippedReason = "already-enabled";
+            }
+            else {
+                skippedReason = "marker-present";
+            }
+            return { changed: false };
+        }
         if (needsVf) {
             policy.valueFeedback = { ...FORCE_ON_VALUE_FEEDBACK_BLOCK };
             valueFeedbackChanged = valueFeedbackNeedsForceOn(previousVf);
@@ -193,18 +404,49 @@ export function runOrgForceOnMigration(projectRoot, options = {}) {
         if (valueFeedbackChanged || productSignalChanged) {
             atomicWriteProjectDefinition(path, rootData);
         }
+        // Marker previous*: forced fields record pre-apply current; unforced fields
+        // keep the prior marker snapshot so intentional opt-outs are not rewritten
+        // into the incomplete-migration equality path on the next update (#2903 P1).
+        // When the prior marker had no previous* (legacy) and the field was not forced,
+        // store ORG_FORCE_ON_NO_BASELINE — not null/live shape — so clear-value-feedback
+        // (undefined→null) and intentional opt-outs never deep-equal previous*.
+        const markerPreviousVf = needsVf
+            ? previousVf
+            : existing && "previousValueFeedback" in existing
+                ? existing.previousValueFeedback
+                : ORG_FORCE_ON_NO_BASELINE;
+        const markerPreviousPs = needsPs
+            ? previousPs
+            : existing && "previousProductSignal" in existing
+                ? existing.previousProductSignal
+                : ORG_FORCE_ON_NO_BASELINE;
         const actor = options.actor ?? "directive-update";
         appendAuditLog(projectRoot, [
             `actor=${actor}`,
             "org-force-on-v2822",
             `valueFeedback=${needsVf ? "forced-on" : "unchanged"}`,
             `productSignal=${needsPs ? "forced-on" : "unchanged"}`,
-            `previousValueFeedback=${JSON.stringify(previousVf ?? null)}`,
-            `previousProductSignal=${JSON.stringify(previousPs ?? null)}`,
+            `previousValueFeedback=${JSON.stringify(normalizePolicySnapshot(markerPreviousVf))}`,
+            `previousProductSignal=${JSON.stringify(normalizePolicySnapshot(markerPreviousPs))}`,
         ].join(" "));
-        writeMarkerForSkip(projectRoot, options, needsVf, needsPs);
+        writeMarker(projectRoot, options, {
+            // OR with existing so partial re-apply does not clear install-force-on source.
+            valueFeedback: needsVf || (existing?.valueFeedback ?? false),
+            productSignal: needsPs || (existing?.productSignal ?? false),
+            previousValueFeedback: markerPreviousVf,
+            previousProductSignal: markerPreviousPs,
+        });
+        ran = true;
         return { changed: valueFeedbackChanged || productSignalChanged };
     });
+    if (!ran) {
+        return {
+            ran: false,
+            skippedReason: skippedReason ?? "marker-present",
+            valueFeedbackChanged: false,
+            productSignalChanged: false,
+        };
+    }
     return {
         ran: true,
         skippedReason: null,

package/dist/policy/require-human-merge.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Human merge gate (#1193 R3 / Wave 2 of #2948).
+ *
+ * When requireHumanMerge is true, agents may open PRs but must not merge.
+ * Three enforcement surfaces (mirror #747):
+ *  (1) merge preflight refuses agent-initiated merge
+ *  (2) verify:branch aggregate surfaces the policy
+ *  (3) branch-protection / setup docs require ≥1 human reviewer
+ *
+ * Override: `task policy:allow-bot-merge -- --confirm` + `DEFT_ALLOW_BOT_MERGE=1`.
+ */
+export declare const FIELD_REQUIRE_HUMAN_MERGE = "plan.policy.requireHumanMerge";
+export declare const FIELD_REQUIRE_HUMAN_MERGE_CLI_ALIAS = "requireHumanMerge";
+export declare const FIELD_AUTO_DEPLOY_ON_MERGE = "plan.policy.autoDeployOnMerge";
+/** Emergency env-var bypass for agent merge (#1193). */
+export declare const ENV_ALLOW_BOT_MERGE = "DEFT_ALLOW_BOT_MERGE";
+/** Legacy narrative key recognized at read time with deprecation warning. */
+export declare const LEGACY_REQUIRE_HUMAN_MERGE_KEY = "Require human merge";
+export type HumanMergeSource = "typed" | "legacy-narrative" | "auto-deploy-default" | "env-bypass" | "default";
+export interface HumanMergePolicyResult {
+    /** True when agents must not merge. */
+    readonly requireHumanMerge: boolean;
+    readonly source: HumanMergeSource;
+    readonly deprecationWarning: string | null;
+    readonly error: string | null;
+    readonly autoDeployOnMerge: boolean;
+}
+/**
+ * Resolve effective human-merge policy (#1193).
+ *
+ * Order:
+ * 1. DEFT_ALLOW_BOT_MERGE=1 → requireHumanMerge effective false (env-bypass)
+ * 2. typed plan.policy.requireHumanMerge
+ * 3. legacy narrative "Require human merge"
+ * 4. autoDeployOnMerge true → default requireHumanMerge true
+ * 5. default false (no auto-deploy → agents may merge when other gates allow)
+ */
+export declare function resolveHumanMergePolicy(projectRoot: string, env?: NodeJS.ProcessEnv): HumanMergePolicyResult;
+/** Session-start / AGENTS disclosure line when the human merge gate is ON. */
+export declare function humanMergeDisclosureLine(result: HumanMergePolicyResult): string | null;
+export interface AgentMergeEvaluateResult {
+    readonly exitCode: 0 | 1;
+    readonly allowed: boolean;
+    readonly message: string;
+    readonly policy: HumanMergePolicyResult;
+}
+/**
+ * Merge preflight: refuse agent-initiated merge when requireHumanMerge is true.
+ * Surface (1) of the three-surface enforcement pattern.
+ */
+export declare function evaluateAgentMerge(projectRoot: string, env?: NodeJS.ProcessEnv): AgentMergeEvaluateResult;
+/**
+ * verify:branch aggregate surface (2): advisory line when gate is ON.
+ * Does not fail the branch gate on feature branches — merge refuse is surface (1).
+ */
+export declare function humanMergeBranchNote(result: HumanMergePolicyResult): string | null;
+export interface HumanMergePolicyField {
+    readonly name: string;
+    readonly current: boolean;
+    readonly default: boolean;
+    readonly source: string;
+}
+/** Inspector for policy:show --field=requireHumanMerge. */
+export declare function inspectRequireHumanMerge(data: Record<string, unknown> | null, projectRoot?: string): HumanMergePolicyField;
+export declare const ALLOW_BOT_MERGE_CAPABILITY_COST: string;
+/** Write requireHumanMerge=false (allow bot merge) with audit trail. */
+export declare function setRequireHumanMerge(projectRoot: string, options: {
+    requireHumanMerge: boolean;
+    actor?: string;
+    note?: string;
+}): {
+    changed: boolean;
+    auditEntry: string;
+};
+//# sourceMappingURL=require-human-merge.d.ts.map