@deftai/directive-core 0.88.0 → 0.89.0

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

@@ -1,8 +1,8 @@
-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";
@@ -88,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)) {

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

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

@@ -0,0 +1,324 @@
+/**
+ * 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`.
+ */
+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";
+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";
+/** Emergency env-var bypass for agent merge (#1193). */
+export const ENV_ALLOW_BOT_MERGE = "DEFT_ALLOW_BOT_MERGE";
+/** Legacy narrative key recognized at read time with deprecation warning. */
+export const LEGACY_REQUIRE_HUMAN_MERGE_KEY = "Require human merge";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function envBypassActive(env = process.env) {
+    const raw = env[ENV_ALLOW_BOT_MERGE] ?? "";
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
+function coerceLegacyNarrative(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value !== "string")
+        return false;
+    const low = value.trim().toLowerCase();
+    if (["true", "yes", "on", "1"].includes(low))
+        return true;
+    if (/:\s*(true|yes|on|1)\b/.test(low))
+        return true;
+    return false;
+}
+function readAutoDeploy(policyBlock) {
+    const raw = policyBlock.autoDeployOnMerge;
+    return typeof raw === "boolean" ? raw : false;
+}
+/**
+ * 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 function resolveHumanMergePolicy(projectRoot, env = process.env) {
+    if (envBypassActive(env)) {
+        return {
+            requireHumanMerge: false,
+            source: "env-bypass",
+            deprecationWarning: null,
+            error: null,
+            autoDeployOnMerge: false,
+        };
+    }
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return {
+            requireHumanMerge: false,
+            source: "default",
+            deprecationWarning: null,
+            error: err,
+            autoDeployOnMerge: false,
+        };
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return {
+            requireHumanMerge: false,
+            source: "default",
+            deprecationWarning: null,
+            error: "PROJECT-DEFINITION 'plan' is not an object",
+            autoDeployOnMerge: false,
+        };
+    }
+    const planObj = plan;
+    const policyRaw = readPlanPolicy(planObj);
+    const policyBlock = typeof policyRaw === "object" && policyRaw !== null && !Array.isArray(policyRaw)
+        ? policyRaw
+        : {};
+    const autoDeployOnMerge = readAutoDeploy(policyBlock);
+    if ("requireHumanMerge" in policyBlock) {
+        const raw = policyBlock.requireHumanMerge;
+        if (typeof raw !== "boolean") {
+            return {
+                requireHumanMerge: true, // fail closed on malformed flag when present
+                source: "typed",
+                deprecationWarning: null,
+                error: `plan.policy.requireHumanMerge must be a boolean; got ${typeof raw}`,
+                autoDeployOnMerge,
+            };
+        }
+        return {
+            requireHumanMerge: raw,
+            source: "typed",
+            deprecationWarning: null,
+            error: null,
+            autoDeployOnMerge,
+        };
+    }
+    const narratives = planObj.narratives;
+    if (typeof narratives === "object" &&
+        narratives !== null &&
+        !Array.isArray(narratives) &&
+        LEGACY_REQUIRE_HUMAN_MERGE_KEY in narratives) {
+        const allow = coerceLegacyNarrative(narratives[LEGACY_REQUIRE_HUMAN_MERGE_KEY]);
+        const warn = `DEPRECATED: PROJECT-DEFINITION uses the legacy narrative key ` +
+            `'${LEGACY_REQUIRE_HUMAN_MERGE_KEY}'. Migrate to typed ` +
+            `plan.policy.requireHumanMerge (#1193).`;
+        return {
+            requireHumanMerge: allow,
+            source: "legacy-narrative",
+            deprecationWarning: warn,
+            error: null,
+            autoDeployOnMerge,
+        };
+    }
+    if (autoDeployOnMerge) {
+        return {
+            requireHumanMerge: true,
+            source: "auto-deploy-default",
+            deprecationWarning: null,
+            error: null,
+            autoDeployOnMerge: true,
+        };
+    }
+    return {
+        requireHumanMerge: false,
+        source: "default",
+        deprecationWarning: null,
+        error: null,
+        autoDeployOnMerge: false,
+    };
+}
+/** Session-start / AGENTS disclosure line when the human merge gate is ON. */
+export function humanMergeDisclosureLine(result) {
+    if (result.source === "env-bypass") {
+        return (`[deft policy] ${ENV_ALLOW_BOT_MERGE} is set -- ` +
+            "human merge gate bypassed for this session (agent may merge).");
+    }
+    if (!result.requireHumanMerge) {
+        return null;
+    }
+    return (`[deft policy] Human merge gate is ON for this project (source: ${result.source}); ` +
+        "agent may open PRs, may not merge.");
+}
+/**
+ * Merge preflight: refuse agent-initiated merge when requireHumanMerge is true.
+ * Surface (1) of the three-surface enforcement pattern.
+ */
+export function evaluateAgentMerge(projectRoot, env = process.env) {
+    const policy = resolveHumanMergePolicy(projectRoot, env);
+    if (!policy.requireHumanMerge) {
+        return {
+            exitCode: 0,
+            allowed: true,
+            message: policy.source === "env-bypass"
+                ? `✓ human-merge gate: ${ENV_ALLOW_BOT_MERGE}=1 bypass -- agent merge allowed.`
+                : "✓ human-merge gate: requireHumanMerge is off -- agent merge allowed by policy.",
+            policy,
+        };
+    }
+    const parts = [
+        "❌ deft human-merge gate: refusing agent-initiated merge (#1193).",
+        "",
+        `  Source: policy=${policy.source}`,
+        "  plan.policy.requireHumanMerge is true — agents may open PRs, may not merge.",
+    ];
+    if (policy.error !== null) {
+        parts.push(`  Error: ${policy.error}`);
+    }
+    if (policy.deprecationWarning !== null) {
+        parts.push(`  Note: ${policy.deprecationWarning}`);
+    }
+    parts.push("", "  How to proceed:", "    • Ask a human to review and merge the PR.", "    • Or opt out via the typed surface (capability cost):", `        ${policyColonInvocation("allow-bot-merge", " -- --confirm")}`, `    • Or set the emergency-escape env-var:  ${ENV_ALLOW_BOT_MERGE}=1`);
+    return {
+        exitCode: 1,
+        allowed: false,
+        message: parts.join("\n"),
+        policy,
+    };
+}
+/**
+ * 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 function humanMergeBranchNote(result) {
+    if (result.source === "env-bypass") {
+        return humanMergeDisclosureLine(result);
+    }
+    if (!result.requireHumanMerge)
+        return null;
+    return (`ℹ deft human-merge: requireHumanMerge=true (source: ${result.source}) — ` +
+        "agent-initiated merge will be refused; human must merge.");
+}
+/** Inspector for policy:show --field=requireHumanMerge. */
+export function inspectRequireHumanMerge(data, projectRoot) {
+    if (projectRoot !== undefined && projectRoot.length > 0) {
+        const resolved = resolveHumanMergePolicy(projectRoot);
+        return {
+            name: FIELD_REQUIRE_HUMAN_MERGE,
+            current: resolved.requireHumanMerge,
+            default: false,
+            source: resolved.source,
+        };
+    }
+    if (data === null) {
+        return {
+            name: FIELD_REQUIRE_HUMAN_MERGE,
+            current: false,
+            default: false,
+            source: "default",
+        };
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock === "object" &&
+        policyBlock !== null &&
+        !Array.isArray(policyBlock) &&
+        "requireHumanMerge" in policyBlock) {
+        const raw = policyBlock.requireHumanMerge;
+        return {
+            name: FIELD_REQUIRE_HUMAN_MERGE,
+            current: typeof raw === "boolean" ? raw : true,
+            default: false,
+            source: "typed",
+        };
+    }
+    if (typeof policyBlock === "object" &&
+        policyBlock !== null &&
+        !Array.isArray(policyBlock) &&
+        policyBlock.autoDeployOnMerge === true) {
+        return {
+            name: FIELD_REQUIRE_HUMAN_MERGE,
+            current: true,
+            default: false,
+            source: "auto-deploy-default",
+        };
+    }
+    return {
+        name: FIELD_REQUIRE_HUMAN_MERGE,
+        current: false,
+        default: false,
+        source: "default",
+    };
+}
+export const ALLOW_BOT_MERGE_CAPABILITY_COST = "\u26a0 Capability-cost disclosure -- allowing bot/agent merge turns OFF the " +
+    "deft human merge gate (#1193).\n" +
+    "  \u2022 Agents may call `gh pr merge` / `task pr:wait-mergeable-and-merge`.\n" +
+    "  \u2022 If autoDeployOnMerge is true, agent merges can reach production unattended.\n" +
+    "  \u2022 Reversible: set plan.policy.requireHumanMerge=true or re-run setup.\n" +
+    "  \u2022 Change is recorded to meta/policy-changes.log for auditability.";
+/** Write requireHumanMerge=false (allow bot merge) with audit trail. */
+export function setRequireHumanMerge(projectRoot, options) {
+    const { requireHumanMerge, actor = "agent", note = "" } = options;
+    const path = projectDefinitionPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`PROJECT-DEFINITION not found at ${path}`);
+    }
+    return 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;
+        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 = policyBlock.requireHumanMerge;
+        policyBlock.requireHumanMerge = Boolean(requireHumanMerge);
+        let legacyDropped = false;
+        const narratives = plan.narratives;
+        if (typeof narratives === "object" &&
+            narratives !== null &&
+            !Array.isArray(narratives) &&
+            LEGACY_REQUIRE_HUMAN_MERGE_KEY in narratives) {
+            delete narratives[LEGACY_REQUIRE_HUMAN_MERGE_KEY];
+            legacyDropped = true;
+        }
+        atomicWriteProjectDefinition(path, data);
+        const changed = previous !== Boolean(requireHumanMerge) || legacyDropped;
+        const parts = [
+            `actor=${actor}`,
+            `requireHumanMerge=${requireHumanMerge ? "true" : "false"}`,
+            `previous=${previous === undefined ? "None" : String(previous)}`,
+        ];
+        if (legacyDropped)
+            parts.push("legacy-narrative-migrated=true");
+        if (note) {
+            parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+        }
+        const auditEntry = parts.join(" ");
+        appendAuditLog(projectRoot, auditEntry);
+        return { changed, auditEntry };
+    });
+}
+//# sourceMappingURL=require-human-merge.js.map

package/dist/policy/resolve.js

@@ -1,5 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve as pathResolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 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";
@@ -177,15 +178,25 @@ function nowIso() {
 }
 /** Append a one-line audit entry to meta/policy-changes.log (#746). */
 export function appendAuditLog(projectRoot, entry) {
-    const logPath = join(pathResolve(projectRoot), AUDIT_LOG_REL_PATH);
-    mkdirSync(join(logPath, ".."), { recursive: true });
-    const line = `${nowIso()} ${entry}\n`;
+    const root = pathResolve(projectRoot);
+    const logPath = join(root, AUDIT_LOG_REL_PATH);
+    // #2980 wave D: product write sink routes through containedWrite.
     if (!existsSync(logPath)) {
         const header = "# meta/policy-changes.log -- audit trail for " +
             "policy.allowDirectCommitsToMaster transitions (#746)\n";
-        writeFileSync(logPath, header, { encoding: "utf8" });
+        containedWrite({
+            root,
+            target: AUDIT_LOG_REL_PATH,
+            data: header,
+            mode: "create",
+        });
     }
-    appendFileSync(logPath, line, { encoding: "utf8" });
+    containedWrite({
+        root,
+        target: AUDIT_LOG_REL_PATH,
+        data: `${nowIso()} ${entry}\n`,
+        mode: "append",
+    });
     return logPath;
 }
 /** Write the typed policy flag back to PROJECT-DEFINITION (#746). */

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

@@ -9,6 +9,8 @@ export interface RuntimeAuthorityScopes {
     /** merge / close / release — enforced only when Shell payload is classifiable (host gap). */
     readonly merge: boolean;
 }
+/** Layers that contribute to a resolved write fence (#516 / #2443 / #2948 Wave 3). */
+export type WriteFenceSource = "project" | "story";
 export interface RuntimeAuthorityPolicy {
     readonly enabled: boolean;
     /** When non-empty, write targets must match at least one pattern. Empty = allow all paths. */
@@ -16,6 +18,17 @@ export interface RuntimeAuthorityPolicy {
     /** Deny wins over allow. */
     readonly denyPaths: readonly string[];
     readonly scopes: RuntimeAuthorityScopes;
+    /**
+     * Optional story-layer allow globs from `plan.metadata.swarm.file_scope`
+     * (populated by `resolveWriteFence` only). When non-empty, path must match
+     * project allowPaths (if any) **and** this layer. Empty/undefined = no story narrowing.
+     */
+    readonly storyAllowPaths?: readonly string[];
+    /**
+     * Which layers contributed to this policy (for stable deny reason codes).
+     * Set by `resolveWriteFence`; absent for bare project policy from disk.
+     */
+    readonly fenceSources?: readonly WriteFenceSource[];
 }
 export declare const DEFAULT_RUNTIME_AUTHORITY_SCOPES: RuntimeAuthorityScopes;
 /** Safe default: opt-in only — existing consumers see no runtime authority until enabled. */
@@ -34,8 +47,8 @@ export declare function inspectRuntimeAuthority(data: Record<string, unknown> |
 export declare function loadRuntimeAuthorityPolicy(data: Record<string, unknown> | null): RuntimeAuthorityPolicy;
 /** Load runtime authority from a project root (PROJECT-DEFINITION on disk). */
 export declare function loadRuntimeAuthorityFromProject(projectRoot: string): RuntimeAuthorityPolicy;
-export type RuntimeAuthorityPathVerdict = "allow" | "deny-allowlist" | "deny-denylist";
-/** Evaluate a project-relative POSIX path against allow/deny globs. */
+export type RuntimeAuthorityPathVerdict = "allow" | "deny-allowlist" | "deny-denylist" | "deny-story-scope";
+/** Evaluate a project-relative POSIX path against allow/deny globs (+ optional story layer). */
 export declare function evaluateRuntimeAuthorityPath(policy: RuntimeAuthorityPolicy, relPathPosix: string): RuntimeAuthorityPathVerdict;
 export interface RuntimeAuthorityDirectWriteInput {
     readonly policy: RuntimeAuthorityPolicy;

package/dist/policy/runtime-authority.js

@@ -127,7 +127,7 @@ export function loadRuntimeAuthorityFromProject(projectRoot) {
     const [data] = loadProjectDefinition(projectRoot);
     return loadRuntimeAuthorityPolicy(data);
 }
-/** Evaluate a project-relative POSIX path against allow/deny globs. */
+/** Evaluate a project-relative POSIX path against allow/deny globs (+ optional story layer). */
 export function evaluateRuntimeAuthorityPath(policy, relPathPosix) {
     if (!policy.enabled)
         return "allow";
@@ -136,8 +136,20 @@ export function evaluateRuntimeAuthorityPath(policy, relPathPosix) {
     if (policy.allowPaths.length > 0 && !matchAny(policy.allowPaths, relPathPosix)) {
         return "deny-allowlist";
     }
+    // Story file_scope layer (#516 / #2443): path must match when non-empty.
+    const storyAllow = policy.storyAllowPaths ?? [];
+    if (storyAllow.length > 0 && !matchAny(storyAllow, relPathPosix)) {
+        return "deny-story-scope";
+    }
     return "allow";
 }
+/** Human-readable fence source label for deny reasons. */
+function fenceSourceLabel(policy) {
+    const sources = policy.fenceSources;
+    if (sources === undefined || sources.length === 0)
+        return "project";
+    return sources.join("+");
+}
 /**
  * Evaluate direct-write runtime authority after ritual/scope gates (#1394).
  * Unclassifiable paths (null) pass — host gap documented for Shell/MCP.
@@ -164,7 +176,7 @@ export function evaluateRuntimeAuthorityDirectWrite(input) {
             allowed: false,
             code: "runtime-policy-deny-path",
             reason: `Directive denied this direct write: path ${relPathPosix} matches ` +
-                "plan.policy.runtimeAuthority.denyPaths.",
+                `write-fence denyPaths (source: ${fenceSourceLabel(policy)}).`,
         };
     }
     if (pathVerdict === "deny-allowlist") {
@@ -172,7 +184,15 @@ export function evaluateRuntimeAuthorityDirectWrite(input) {
             allowed: false,
             code: "runtime-policy-deny-path",
             reason: `Directive denied this direct write: path ${relPathPosix} is outside ` +
-                "plan.policy.runtimeAuthority.allowPaths.",
+                `write fence project allowPaths (source: ${fenceSourceLabel(policy)}).`,
+        };
+    }
+    if (pathVerdict === "deny-story-scope") {
+        return {
+            allowed: false,
+            code: "runtime-policy-deny-path",
+            reason: `Directive denied this direct write: path ${relPathPosix} is outside ` +
+                `write fence story file_scope (source: ${fenceSourceLabel(policy)}).`,
         };
     }
     return { allowed: true, reason: null, code: null };

package/dist/policy/write-fence.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Unified path write fence (#516 / #2443 / #2948 Wave 3).
+ *
+ * Single evaluation SoT: path checks always go through
+ * `evaluateRuntimeAuthorityPath` / `evaluateRuntimeAuthorityDirectWrite`.
+ * This module only **resolves** a RuntimeAuthorityPolicy by intersecting
+ * project `runtimeAuthority.allowPaths` / `denyPaths` with optional story
+ * `plan.metadata.swarm.file_scope` (and a read-time `writeScope` alias).
+ *
+ * There is no second independent writeScope evaluation engine.
+ */
+import { type RuntimeAuthorityPolicy, type WriteFenceSource } from "./runtime-authority.js";
+/**
+ * Normalize a legacy #2443 `writeScope` alias into `file_scope` + deny globs.
+ * Accepts:
+ * - `string[]` → allow list
+ * - `{ allow?: string[], deny?: string[] }`
+ * - `{ file_scope?: string[], denyPaths?: string[] }` (already-normalized shape)
+ *
+ * Callers MUST feed the result into {@link resolveWriteFence}; do not evaluate
+ * writeScope with a separate matcher.
+ */
+export declare function normalizeStoryWriteScope(raw: unknown): {
+    readonly fileScope: string[];
+    readonly denyPaths: string[];
+};
+/**
+ * Extract story write fence from an xBRIEF/vBRIEF document.
+ * Prefer `plan.metadata.swarm.file_scope`; fall back to normalized `writeScope`
+ * on `plan.metadata.swarm` or `plan.metadata` (read-time alias only).
+ */
+export declare function extractStoryFileScope(storyData: unknown): {
+    readonly fileScope: string[];
+    readonly denyPaths: string[];
+};
+/** Load story fence from an active xBRIEF path (fail-open on IO/parse errors). */
+export declare function loadStoryWriteFenceFromPath(scopePath: string | null | undefined): {
+    readonly fileScope: string[];
+    readonly denyPaths: string[];
+};
+export interface ResolveWriteFenceOptions {
+    /** Extra deny globs from normalized writeScope.deny (merged; deny always wins). */
+    readonly storyDenyPaths?: readonly string[] | null;
+}
+export interface ResolvedWriteFence {
+    /**
+     * Policy for `evaluateRuntimeAuthorityPath` / `evaluateRuntimeAuthorityDirectWrite`.
+     * This is the only evaluation shape — no parallel engine.
+     */
+    readonly policy: RuntimeAuthorityPolicy;
+    /** Layers that contribute to this fence (empty when inactive). */
+    readonly sources: readonly WriteFenceSource[];
+    /** True when project and/or story path fence is active. */
+    readonly fenceActive: boolean;
+    readonly storyAllowPaths: readonly string[];
+    readonly storyDenyPaths: readonly string[];
+}
+/**
+ * Intersect project `runtimeAuthority` with optional story `file_scope`.
+ *
+ * Rules:
+ * - Empty project `allowPaths` when enabled = all paths until story narrows.
+ * - Empty story scope = project policy only.
+ * - Story `file_scope` alone enables a fence even when project policy is disabled.
+ * - `denyPaths` always win (project + story-normalized denys).
+ * - When both project allowPaths and story file_scope are non-empty, a path must
+ *   match **both** layers (AND / intersection semantics via dual allow layers).
+ */
+export declare function resolveWriteFence(projectPolicy: RuntimeAuthorityPolicy, storyFileScope?: readonly string[] | null, options?: ResolveWriteFenceOptions): ResolvedWriteFence;
+/**
+ * Resolve the write fence for PreToolUse / product sinks.
+ * Composes project policy with story fence extracted from an active xBRIEF path.
+ */
+export declare function resolveWriteFenceForScope(projectPolicy: RuntimeAuthorityPolicy, scopePath: string | null | undefined, loadStory?: (path: string | null | undefined) => {
+    fileScope: readonly string[];
+    denyPaths: readonly string[];
+}): ResolvedWriteFence;
+//# sourceMappingURL=write-fence.d.ts.map