@deftai/directive-core 0.87.0 → 0.89.0

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;
@@ -51,4 +64,45 @@ export interface RuntimeAuthorityDirectWriteResult {
  * Unclassifiable paths (null) pass — host gap documented for Shell/MCP.
  */
 export declare function evaluateRuntimeAuthorityDirectWrite(input: RuntimeAuthorityDirectWriteInput): RuntimeAuthorityDirectWriteResult;
+/** Classifiable shell/MCP operation for scopes.push / scopes.merge (#2711). */
+export type RuntimeAuthorityShellOp = "push" | "merge";
+/**
+ * List all classifiable push/merge ops in a shell command (#2711).
+ * Scans every list/pipeline/newline segment so compound commands like
+ * `gh pr merge 1 && git push` surface both ops (dispatcher evaluates each).
+ * Newlines are delimiters so multi-line scripts cannot hide a later push/merge.
+ */
+export declare function listShellOps(command: string): RuntimeAuthorityShellOp[];
+/**
+ * Classify a shell command string for push/merge scopes (#2711).
+ * Unclassifiable commands return null (fail open at the gate).
+ * When a compound command has multiple ops, returns the first of listShellOps
+ * (push before merge); prefer listShellOps + evaluate-each for enforcement.
+ *
+ * Patterns (intentionally narrow; prefer false-open over false-deny):
+ * - push: `git push`, `git.exe push`, with optional env / -C / -c prefixes
+ * - merge: `gh pr merge`, `gh.exe pr merge`
+ */
+export declare function classifyShellCommand(command: string): RuntimeAuthorityShellOp | null;
+/**
+ * Classify an MCP (or MCP-like) tool name + optional argument blob for push/merge (#2711).
+ * Returns null when the tool is not a known push/merge mutation (fail open).
+ */
+export declare function classifyMcpTool(toolName: string, argsText?: string | null): RuntimeAuthorityShellOp | null;
+export interface RuntimeAuthorityShellOpInput {
+    readonly policy: RuntimeAuthorityPolicy;
+    readonly op: RuntimeAuthorityShellOp | null;
+}
+export interface RuntimeAuthorityShellOpResult {
+    readonly allowed: boolean;
+    readonly reason: string | null;
+    readonly code: "runtime-policy-deny-scope" | null;
+    /** True when op was null — gate should fail open. */
+    readonly unclassifiable: boolean;
+}
+/**
+ * Evaluate scopes.push / scopes.merge for a classifiable shell/MCP operation (#2711).
+ * null op → allow (unclassifiable fail-open). disabled policy → allow.
+ */
+export declare function evaluateRuntimeAuthorityShellOp(input: RuntimeAuthorityShellOpInput): RuntimeAuthorityShellOpResult;
 //# sourceMappingURL=runtime-authority.d.ts.map