@deftai/directive-core 0.88.0 → 0.90.0

package/dist/policy/index.js

@@ -1,6 +1,8 @@
 import { FIELD_HOST_HOOKS, FIELD_HOST_HOOKS_CLI_ALIAS, inspectHostHooks } from "./host-hooks.js";
+import { FIELD_HOTFIX_CRITERIA, FIELD_HOTFIX_CRITERIA_CLI_ALIAS, inspectHotfixCriteria, } from "./hotfix-criteria.js";
 import { readPlanPolicy } from "./plan-extensions.js";
 import { FIELD_PRODUCT_SIGNAL, FIELD_PRODUCT_SIGNAL_CLI_ALIAS, inspectProductSignal, } from "./product-signal.js";
+import { FIELD_REQUIRE_HUMAN_MERGE, FIELD_REQUIRE_HUMAN_MERGE_CLI_ALIAS, inspectRequireHumanMerge, } from "./require-human-merge.js";
 import { coerceLegacyNarrative, LEGACY_NARRATIVE_KEY, loadProjectDefinition } from "./resolve.js";
 import { FIELD_RUNTIME_AUTHORITY, FIELD_RUNTIME_AUTHORITY_CLI_ALIAS, inspectRuntimeAuthority, } from "./runtime-authority.js";
 import { FIELD_STALENESS_TICKLER, FIELD_STALENESS_TICKLER_CLI_ALIAS, inspectStalenessTickler, } from "./staleness-tickler.js";
@@ -12,17 +14,21 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./host-hooks.js";
+export * from "./hotfix-criteria.js";
+export * from "./intent-ceiling.js";
 export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";
 export * from "./plan-extensions.js";
 export * from "./policy-invocation.js";
 export * from "./product-signal.js";
+export * from "./require-human-merge.js";
 export * from "./resolve.js";
 export * from "./runtime-authority.js";
 export * from "./staleness-tickler.js";
 export * from "./value-feedback.js";
 export * from "./value-feedback-autoenable.js";
 export * from "./wip.js";
+export * from "./write-fence.js";
 export const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
 export const FIELD_WIP_CAP = "plan.policy.wipCap";
 export const FIELD_SESSION_RITUAL_STALENESS_HOURS = "plan.policy.sessionRitualStalenessHours";
@@ -272,6 +278,24 @@ function inspectHostHooksField(data) {
         source: field.source,
     };
 }
+function inspectRequireHumanMergeField(data, projectRoot) {
+    const field = inspectRequireHumanMerge(data, projectRoot);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
+function inspectHotfixCriteriaField(data) {
+    const field = inspectHotfixCriteria(data);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
 const REGISTERED_POLICIES = [
     inspectAllowDirectCommits,
     inspectWipCap,
@@ -289,6 +313,8 @@ const REGISTERED_POLICIES = [
     inspectRuntimeAuthorityField,
     inspectProductSignalField,
     inspectValueFeedbackField,
+    inspectRequireHumanMergeField,
+    inspectHotfixCriteriaField,
 ];
 /** Walk registered inspectors and return one row per field (#1148). */
 export function inspectAllPolicies(projectRoot) {
@@ -307,7 +333,11 @@ export function inspectOnePolicy(name, projectRoot) {
                     ? FIELD_RUNTIME_AUTHORITY
                     : name === FIELD_HOST_HOOKS_CLI_ALIAS
                         ? FIELD_HOST_HOOKS
-                        : name;
+                        : name === FIELD_REQUIRE_HUMAN_MERGE_CLI_ALIAS
+                            ? FIELD_REQUIRE_HUMAN_MERGE
+                            : name === FIELD_HOTFIX_CRITERIA_CLI_ALIAS
+                                ? FIELD_HOTFIX_CRITERIA
+                                : name;
     for (const field of inspectAllPolicies(projectRoot)) {
         if (field.name === normalized)
             return field;

package/dist/policy/intent-ceiling.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Slash-command intent containment (#1193 / extends #810).
+ *
+ * When a session inherits a slash command as its verb, that verb is the *only*
+ * authorized intent for the session. Non-implement verbs must not authorize
+ * implement / push / PR / merge / deploy tool paths.
+ *
+ * Provenance: set `DEFT_SESSION_SLASH_VERB` (e.g. `/github-issue`, `github-issue`,
+ * `/build`) for the session, or pass `sessionVerb` explicitly to pure evaluators.
+ */
+/** Env var carrying the session's slash-command verb (#1193). */
+export declare const ENV_SESSION_SLASH_VERB = "DEFT_SESSION_SLASH_VERB";
+/**
+ * Free-text action verbs that authorize implementation under #810.
+ * Parallel list for slash forms lives in IMPLEMENT_SLASH_VERBS.
+ */
+export declare const FREE_TEXT_IMPLEMENT_VERBS: readonly ["build", "implement", "ship", "swarm", "run agents", "start agent"];
+/**
+ * Slash-command stems that authorize implementation (#1193 R1).
+ * Matched after normalizing `/prefix` and `:namespace` forms.
+ */
+export declare const IMPLEMENT_SLASH_VERBS: Set<string>;
+/**
+ * Explicit non-implement slash stems — always contained.
+ * Unknown stems default to non-implement (fail closed for lifecycle escalation).
+ */
+export declare const NON_IMPLEMENT_SLASH_VERBS: Set<string>;
+/** Lifecycle ops gated by the intent ceiling. */
+export declare const INTENT_CEILING_OPS: readonly ["implement", "push", "pr", "merge", "deploy"];
+export type IntentCeilingOp = (typeof INTENT_CEILING_OPS)[number];
+export type IntentCeilingCode = "intent-allow-no-slash" | "intent-allow-implement-verb" | "intent-deny-non-implement" | "intent-deny-unknown-slash";
+export interface IntentCeilingDecision {
+    readonly allowed: boolean;
+    readonly code: IntentCeilingCode;
+    readonly reason: string;
+    /** Normalized slash stem (without leading `/`), or null when no slash provenance. */
+    readonly sessionVerb: string | null;
+    readonly requestedOp: IntentCeilingOp;
+}
+/**
+ * Normalize a slash command or free-text verb to a comparable stem.
+ * `/deft:directive:github-issue` → `github-issue`; `/build` → `build`.
+ */
+export declare function normalizeSessionVerb(raw: string | null | undefined): string | null;
+/** True when the normalized stem authorizes implementation. */
+export declare function isImplementSlashVerb(stem: string | null): boolean;
+/** True when the stem is an explicitly known non-implement command. */
+export declare function isNonImplementSlashVerb(stem: string | null): boolean;
+export interface EvaluateIntentCeilingInput {
+    readonly sessionVerb?: string | null;
+    readonly requestedOp: IntentCeilingOp;
+}
+/**
+ * Pure intent-ceiling evaluator (#1193 R1).
+ *
+ * - No slash verb → allow (free-text #810 action-verb remains agent/AGENTS gate).
+ * - Implement slash verb → allow all lifecycle ops.
+ * - Non-implement / unknown slash verb → deny implement/push/pr/merge/deploy.
+ */
+export declare function evaluateIntentCeiling(input: EvaluateIntentCeilingInput): IntentCeilingDecision;
+/** Read session slash verb from the environment. */
+export declare function readSessionSlashVerbFromEnv(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Evaluate intent ceiling for a lifecycle op using env-backed session verb.
+ * Convenience for preflight / hooks / merge gates.
+ */
+export declare function evaluateIntentCeilingFromEnv(requestedOp: IntentCeilingOp, env?: NodeJS.ProcessEnv): IntentCeilingDecision;
+/**
+ * Map classifiable shell/MCP lifecycle signals onto intent-ceiling ops.
+ * Returns null when the tool path is not a gated lifecycle op.
+ */
+export declare function intentOpFromShellSignals(signals: {
+    readonly isPush?: boolean;
+    readonly isMerge?: boolean;
+    readonly isPr?: boolean;
+    readonly isDeploy?: boolean;
+    readonly isImplement?: boolean;
+}): IntentCeilingOp | null;
+//# sourceMappingURL=intent-ceiling.d.ts.map

package/dist/policy/intent-ceiling.js

@@ -0,0 +1,181 @@
+/**
+ * Slash-command intent containment (#1193 / extends #810).
+ *
+ * When a session inherits a slash command as its verb, that verb is the *only*
+ * authorized intent for the session. Non-implement verbs must not authorize
+ * implement / push / PR / merge / deploy tool paths.
+ *
+ * Provenance: set `DEFT_SESSION_SLASH_VERB` (e.g. `/github-issue`, `github-issue`,
+ * `/build`) for the session, or pass `sessionVerb` explicitly to pure evaluators.
+ */
+/** Env var carrying the session's slash-command verb (#1193). */
+export const ENV_SESSION_SLASH_VERB = "DEFT_SESSION_SLASH_VERB";
+/**
+ * Free-text action verbs that authorize implementation under #810.
+ * Parallel list for slash forms lives in IMPLEMENT_SLASH_VERBS.
+ */
+export const FREE_TEXT_IMPLEMENT_VERBS = [
+    "build",
+    "implement",
+    "ship",
+    "swarm",
+    "run agents",
+    "start agent",
+];
+/**
+ * Slash-command stems that authorize implementation (#1193 R1).
+ * Matched after normalizing `/prefix` and `:namespace` forms.
+ */
+export const IMPLEMENT_SLASH_VERBS = new Set([
+    "build",
+    "implement",
+    "ship",
+    "ship-hotfix",
+    "swarm",
+    "start-agent",
+    "start_agent",
+    "run-agents",
+    "run_agents",
+]);
+/**
+ * Explicit non-implement slash stems — always contained.
+ * Unknown stems default to non-implement (fail closed for lifecycle escalation).
+ */
+export const NON_IMPLEMENT_SLASH_VERBS = new Set([
+    "github-issue",
+    "github_issue",
+    "issue",
+    "triage",
+    "refine",
+    "refinement",
+    "discuss",
+    "research",
+    "probe",
+    "glossary",
+    "sync",
+    "continue",
+    "checkpoint",
+    "feedback",
+    "article-review",
+    "cost",
+    "setup",
+    "interview",
+    "map",
+    "yolo",
+    "speckit",
+    "change",
+]);
+/** Lifecycle ops gated by the intent ceiling. */
+export const INTENT_CEILING_OPS = ["implement", "push", "pr", "merge", "deploy"];
+/**
+ * Normalize a slash command or free-text verb to a comparable stem.
+ * `/deft:directive:github-issue` → `github-issue`; `/build` → `build`.
+ */
+export function normalizeSessionVerb(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    let s = raw.trim().toLowerCase();
+    if (s.length === 0)
+        return null;
+    // Strip leading slashes.
+    while (s.startsWith("/"))
+        s = s.slice(1);
+    // Drop product namespaces: deft:directive:github-issue → github-issue
+    if (s.includes(":")) {
+        const parts = s.split(":").filter((p) => p.length > 0);
+        s = parts[parts.length - 1] ?? s;
+    }
+    // Normalize underscores to hyphens for allowlist matching.
+    s = s.replace(/_/g, "-");
+    return s.length > 0 ? s : null;
+}
+/** True when the normalized stem authorizes implementation. */
+export function isImplementSlashVerb(stem) {
+    if (stem === null)
+        return false;
+    if (IMPLEMENT_SLASH_VERBS.has(stem))
+        return true;
+    // Free-text multi-word forms already hyphenated by normalize (run agents → not here).
+    return false;
+}
+/** True when the stem is an explicitly known non-implement command. */
+export function isNonImplementSlashVerb(stem) {
+    if (stem === null)
+        return false;
+    return NON_IMPLEMENT_SLASH_VERBS.has(stem);
+}
+/**
+ * Pure intent-ceiling evaluator (#1193 R1).
+ *
+ * - No slash verb → allow (free-text #810 action-verb remains agent/AGENTS gate).
+ * - Implement slash verb → allow all lifecycle ops.
+ * - Non-implement / unknown slash verb → deny implement/push/pr/merge/deploy.
+ */
+export function evaluateIntentCeiling(input) {
+    const stem = normalizeSessionVerb(input.sessionVerb ?? null);
+    const op = input.requestedOp;
+    if (stem === null) {
+        return {
+            allowed: true,
+            code: "intent-allow-no-slash",
+            reason: "No slash-command session verb; free-text #810 action-verb rules apply.",
+            sessionVerb: null,
+            requestedOp: op,
+        };
+    }
+    if (isImplementSlashVerb(stem)) {
+        return {
+            allowed: true,
+            code: "intent-allow-implement-verb",
+            reason: `Slash verb '/${stem}' authorizes implementation lifecycle ops.`,
+            sessionVerb: stem,
+            requestedOp: op,
+        };
+    }
+    const knownNon = isNonImplementSlashVerb(stem);
+    const code = knownNon
+        ? "intent-deny-non-implement"
+        : "intent-deny-unknown-slash";
+    return {
+        allowed: false,
+        code,
+        reason: `Slash-command intent ceiling (#1193): session verb '/${stem}' does not authorize ` +
+            `${op}. Non-implement verbs terminate at their named outcome; file a follow-up issue ` +
+            `instead of escalating to implement/push/PR/merge/deploy. ` +
+            `Implement verbs: /build, /ship, /ship-hotfix, /swarm, /implement.`,
+        sessionVerb: stem,
+        requestedOp: op,
+    };
+}
+/** Read session slash verb from the environment. */
+export function readSessionSlashVerbFromEnv(env = process.env) {
+    return normalizeSessionVerb(env[ENV_SESSION_SLASH_VERB] ?? null);
+}
+/**
+ * Evaluate intent ceiling for a lifecycle op using env-backed session verb.
+ * Convenience for preflight / hooks / merge gates.
+ */
+export function evaluateIntentCeilingFromEnv(requestedOp, env = process.env) {
+    return evaluateIntentCeiling({
+        sessionVerb: readSessionSlashVerbFromEnv(env),
+        requestedOp,
+    });
+}
+/**
+ * Map classifiable shell/MCP lifecycle signals onto intent-ceiling ops.
+ * Returns null when the tool path is not a gated lifecycle op.
+ */
+export function intentOpFromShellSignals(signals) {
+    if (signals.isDeploy)
+        return "deploy";
+    if (signals.isMerge)
+        return "merge";
+    if (signals.isPr)
+        return "pr";
+    if (signals.isPush)
+        return "push";
+    if (signals.isImplement)
+        return "implement";
+    return null;
+}
+//# sourceMappingURL=intent-ceiling.js.map

package/dist/policy/no-deft-directive.js

@@ -13,8 +13,9 @@
  *   mutating install/update paths **fail closed**.
  * - Creating the flag does **not** delete an existing deposit.
  */
-import { existsSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, statSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
 /** Canonical root-only filename (lowercase). Presence = flag. */
@@ -75,13 +76,19 @@ export function isNoDeftDirectivePresent(projectRoot, seams = {}) {
  */
 export function createNoDeftDirectiveFlag(projectRoot, options = {}) {
     const path = noDeftDirectiveFlagPath(projectRoot);
-    assertWriteTargetSafe(projectRoot, path);
     if (defaultIsDir(path)) {
         throw new Error(`${NO_DEFT_DIRECTIVE_FLAG_NAME} exists as a directory at ${path}; remove it before creating the opt-out flag file.`);
     }
     const rationale = options.rationale?.trim() ?? "";
     const body = rationale.length > 0 ? `# ${rationale}\n` : "";
-    writeFileSync(path, body, "utf8");
+    // #2951: product write sinks route through containedWrite (create|replace).
+    // Use replace so re-running with a new rationale updates the flag file.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: body,
+        mode: "replace",
+    });
     return path;
 }
 /**

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