@deftai/directive-core 0.99.0 → 0.100.0

package/dist/policy/ceremony-dial.js

@@ -1,5 +1,5 @@
 /**
- * Ceremony dial (#3214): ritual depth = f(task size × model tier × project shape).
+ * Ceremony dial (#3214 / #3263): ritual depth = f(task size × model tier × project shape).
  *
  * Selection policy over existing pieces — not a new subsystem.
  * Composes:
@@ -7,11 +7,15 @@
  *   - #3014 minimal consumer AGENTS profile (research pointer; not yet a shipped deposit)
  *   - effort estimate (#1581), model routing (#1976/#818), host capability (#1461)
  *
- * Two-stage dial (#3214 design note / #1581 ordering):
- *   cold-start / incomplete inputs → **rapid** (start light; no plan-item deadlock)
- *   escalate when evidence arrives (provisional M/L, mid/low tier, full matrix)
+ * Two-stage dial (#3214 design note / #1581 ordering) with tier-conditional cold-start (#3263):
+ *   cold-start / incomplete size → **tier-conditional**:
+ *     frontier (or unknown tier) → rapid; mid/low → standard (not rapid)
+ *   escalate when evidence arrives (provisional M/L size, full matrix)
  * Full matrix: S × frontier → rapid; non-project → minimal; else scales up.
  * Override always available via plan.policy.ceremonyDial.override; audited on write.
+ *
+ * Audit path (#3263): session:start records depth + provisional reasons on
+ * `.deft/ritual-state.json` under `ceremony_dial` — use `readCeremonyDialAudit`.
  */
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -45,6 +49,9 @@ export const CEREMONY_MINIMAL_AGENTS_PROFILE_POINTER = "docs/analysis/2026-07-31
  *   (`verify:session-ritual --tier=gated`). Gated verify treats
  *   `deferred_reason` as satisfied, so dial-driven deferral would skip gates.
  * ! `verify_tools` also remains required on every dial depth (not skipFatPath).
+ * ! Literal acceptance-command verification (#3267) is required at every depth
+ *   (`literalAcceptanceRequired: true`), including rapid/minimal — capture exact
+ *   stated commands at intake and run them verbatim before done. Extends #973.
  * ~ Rapid/minimal MAY lighten informational cold path only: triage welcome,
  *   optional network/release probe, staleness tickler.
  */
@@ -55,6 +62,7 @@ const PROFILES = {
         autoDeferSteps: ["triage_welcome"],
         skipFatPath: true,
         lifecycleWrites: "minimal",
+        literalAcceptanceRequired: true,
         label: "minimal (non-project / #3014 direction)",
     },
     rapid: {
@@ -62,6 +70,7 @@ const PROFILES = {
         autoDeferSteps: ["triage_welcome"],
         skipFatPath: true,
         lifecycleWrites: "light",
+        literalAcceptanceRequired: true,
         label: "rapid (strategies/rapid.md light path)",
     },
     standard: {
@@ -69,6 +78,7 @@ const PROFILES = {
         autoDeferSteps: [],
         skipFatPath: false,
         lifecycleWrites: "full",
+        literalAcceptanceRequired: true,
         label: "standard (full session ritual)",
     },
     elevated: {
@@ -76,6 +86,7 @@ const PROFILES = {
         autoDeferSteps: [],
         skipFatPath: false,
         lifecycleWrites: "full",
+        literalAcceptanceRequired: true,
         label: "elevated (full ritual; prefer more gates for weaker tiers / large tasks)",
     },
 };
@@ -186,11 +197,29 @@ export function normalizeCeremonyProjectShape(raw) {
     return null;
 }
 /**
- * Two-stage / partial-evidence selection when size or tier is missing (#3214 design note).
+ * Tier-conditional cold-start depth when task size is incomplete (#3263).
+ *
+ * Mid/low models benefit from structure on hard tasks and should not cold-start
+ * at rapid (start-light / escalate-too-late signature). Frontier recovers from a
+ * light start. Unknown tier stays rapid (optimistic cold default; pass
+ * `--model-tier` / `DEFT_CEREMONY_MODEL_TIER` to unlock the mid/low floor).
+ *
+ * Escalate-on-evidence still applies when size later arrives (full matrix).
+ */
+export function selectCeremonyColdStartDepth(modelTier) {
+    if (modelTier === "mid" || modelTier === "low") {
+        return "standard";
+    }
+    // frontier or unknown → rapid
+    return "rapid";
+}
+/**
+ * Two-stage / partial-evidence selection when size or tier is missing
+ * (#3214 design note / #3263 tier-conditional cold-start).
  *
- * Start light (rapid) on cold incomplete inputs; escalate when partial evidence already
- * implies heavier ceremony (apps-bank safety: hard/substantial work must not stay rapid).
- * Does not invent plan-item effort (#1581 post-planning only).
+ * Cold incomplete size is tier-conditional (#3263): mid/low → standard, frontier
+ * or unknown → rapid. When size is known without tier, escalate on substantial
+ * size (apps-bank safety). Does not invent plan-item effort (#1581 post-planning only).
  */
 export function selectCeremonyDepthFromPartialEvidence(inputs) {
     const size = inputs.taskSize;
@@ -203,26 +232,20 @@ export function selectCeremonyDepthFromPartialEvidence(inputs) {
             return "standard";
         return "elevated"; // L / XL
     }
-    // Tier known, size unknown — mid/low need structure; frontier can start light.
-    if (size === null && tier !== null) {
-        if (tier === "frontier")
-            return "rapid";
-        if (tier === "mid")
-            return "standard";
-        return "elevated"; // low
-    }
-    // Both unknown: two-stage cold default.
-    return "rapid";
+    // Size incomplete (null), any tier including unknown: tier-conditional cold-start (#3263).
+    // Callers with both size and tier set use the full matrix instead.
+    return selectCeremonyColdStartDepth(tier);
 }
 /**
- * Pure default matrix (#3214 acceptance + two-stage design note):
+ * Pure default matrix (#3214 acceptance + #3263 tier-conditional cold-start):
  * - non-project → minimal (#3014 direction)
  * - S × frontier → rapid (strategies/rapid.md)
  * - S × mid → standard (mid-tier gains from structure)
  * - S × low → elevated
  * - M × low → elevated; M otherwise → standard
  * - L/XL → elevated (except L × frontier stays standard)
- * - Incomplete size/tier → two-stage partial evidence (default rapid; escalate on M/L or mid/low)
+ * - Incomplete size → tier-conditional cold-start (#3263): mid/low → standard; frontier/unknown → rapid
+ * - Size known, tier missing → escalate on M/L (partial evidence)
  */
 export function selectCeremonyDepthFromMatrix(inputs) {
     const shape = inputs.projectShape ?? null;
@@ -279,7 +302,7 @@ function parseConfig(raw) {
  * Deterministic depth selection (pure; no IO).
  *
  * Precedence: disabled → standard; override → forced depth; else matrix on inputs;
- * empty inputs → **rapid** (two-stage cold default; escalate when evidence arrives).
+ * empty inputs → **rapid** (unknown-tier cold default; #3263 mid/low need modelTier set).
  */
 export function selectCeremonyDepth(options = {}) {
     const config = {
@@ -317,8 +340,8 @@ export function selectCeremonyDepth(options = {}) {
     }
     const hasAnyInput = inputs.taskSize !== null || inputs.modelTier !== null || inputs.projectShape !== null;
     if (!hasAnyInput) {
-        // Two-stage dial cold default (#3214 design note / #1581 ordering).
-        const depth = "rapid";
+        // Unknown-tier cold default (#3214 / #3263): rapid until modelTier or size arrives.
+        const depth = selectCeremonyColdStartDepth(null);
         return {
             depth,
             source: "default",
@@ -408,6 +431,7 @@ export function ceremonyDialToDict(selection) {
             autoDeferSteps: [...selection.profile.autoDeferSteps],
             skipFatPath: selection.profile.skipFatPath,
             lifecycleWrites: selection.profile.lifecycleWrites,
+            literalAcceptanceRequired: selection.profile.literalAcceptanceRequired,
             label: selection.profile.label,
         },
         composition: {
@@ -826,4 +850,131 @@ export function resolveSessionCeremonyDialInputs(projectRoot, explicit, options
         provisional,
     };
 }
+function asOptionalDepth(value) {
+    return isCeremonyDepth(value) ? value : null;
+}
+function asOptionalTaskSize(value) {
+    return isTaskSize(value) ? value : null;
+}
+function asOptionalModelTier(value) {
+    return isModelTier(value) ? value : null;
+}
+function asOptionalProjectShape(value) {
+    return isProjectShape(value) ? value : null;
+}
+/**
+ * Read ceremony dial depth + provisional reasons from ritual-state (#3263 audit path).
+ * session:start already writes `ceremony_dial` (incl. provisional) — this is the
+ * operator/read path so failed runs can confirm start-light vs escalate timing.
+ *
+ * Returns `error` when ritual-state is missing/unreadable or lacks `ceremony_dial`;
+ * does not throw.
+ */
+export function readCeremonyDialAudit(projectRoot) {
+    const path = join(projectRoot, ".deft", "ritual-state.json");
+    const empty = (error) => ({
+        path,
+        depth: null,
+        source: null,
+        inputs: null,
+        provisional: null,
+        raw: null,
+        error,
+    });
+    try {
+        if (!existsSync(path) || !statSync(path).isFile()) {
+            return empty(`ritual-state missing at ${path}`);
+        }
+    }
+    catch (exc) {
+        return empty(`ritual-state unreadable at ${path}: ${String(exc)}`);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+    }
+    catch (exc) {
+        if (exc instanceof SyntaxError) {
+            return empty(`ritual-state is not valid JSON: ${exc.message}`);
+        }
+        return empty(`ritual-state cannot be read: ${String(exc)}`);
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return empty("ritual-state top-level value must be an object");
+    }
+    const root = payload;
+    const dialRaw = root.ceremony_dial;
+    if (dialRaw === undefined || dialRaw === null) {
+        return empty("ritual-state has no ceremony_dial field (pre-#3214 or non-mutation session)");
+    }
+    if (typeof dialRaw !== "object" || Array.isArray(dialRaw)) {
+        return empty("ritual-state ceremony_dial must be an object");
+    }
+    const dial = dialRaw;
+    const depth = asOptionalDepth(dial.depth);
+    const source = typeof dial.source === "string" ? dial.source : null;
+    let inputs = null;
+    const inputsRaw = dial.inputs;
+    if (typeof inputsRaw === "object" && inputsRaw !== null && !Array.isArray(inputsRaw)) {
+        const rec = inputsRaw;
+        inputs = {
+            taskSize: asOptionalTaskSize(rec.taskSize),
+            modelTier: asOptionalModelTier(rec.modelTier),
+            projectShape: asOptionalProjectShape(rec.projectShape),
+        };
+    }
+    let provisional = null;
+    const provRaw = dial.provisional;
+    if (typeof provRaw === "object" && provRaw !== null && !Array.isArray(provRaw)) {
+        const rec = provRaw;
+        const reasons = Array.isArray(rec.reasons)
+            ? rec.reasons.filter((r) => typeof r === "string")
+            : [];
+        provisional = {
+            taskSize: asOptionalTaskSize(rec.taskSize),
+            modelTier: asOptionalModelTier(rec.modelTier),
+            projectShape: asOptionalProjectShape(rec.projectShape),
+            reasons,
+        };
+    }
+    return {
+        path,
+        depth,
+        source,
+        inputs,
+        provisional,
+        raw: { ...dial },
+        error: null,
+    };
+}
+/** Collapse whitespace so operator audit lines stay single-line (Greptile P2 #3263). */
+function oneLineAuditToken(value) {
+    return value
+        .replace(/[\r\n\t]+/g, " ")
+        .replace(/ {2,}/g, " ")
+        .trim();
+}
+/** One-line operator summary for audit tooling / failed-task forensics (#3263). */
+export function formatCeremonyDialAuditLine(audit) {
+    if (audit.error !== null) {
+        return `[deft ceremony-dial audit] error=${oneLineAuditToken(audit.error)}`;
+    }
+    const parts = [
+        `[deft ceremony-dial audit] depth=${audit.depth ?? "-"}`,
+        `source=${audit.source ?? "-"}`,
+        `taskSize=${audit.inputs?.taskSize ?? "-"}`,
+        `modelTier=${audit.inputs?.modelTier ?? "-"}`,
+        `projectShape=${audit.inputs?.projectShape ?? "-"}`,
+    ];
+    if (audit.provisional !== null) {
+        const reasons = audit.provisional.reasons.length > 0
+            ? audit.provisional.reasons
+                .map(oneLineAuditToken)
+                .filter((r) => r.length > 0)
+                .join("; ")
+            : "(none)";
+        parts.push(`provisional.reasons=${reasons.length > 0 ? reasons : "(none)"}`);
+    }
+    return parts.join(" ");
+}
 //# sourceMappingURL=ceremony-dial.js.map

package/dist/policy/index.d.ts

@@ -13,6 +13,7 @@ export * from "./host-hooks.js";
 export * from "./host-slash-commands.js";
 export * from "./hotfix-criteria.js";
 export * from "./intent-ceiling.js";
+export * from "./merge-approval-head.js";
 export * from "./min-greptile-confidence.js";
 export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";

package/dist/policy/index.js

@@ -31,6 +31,7 @@ export * from "./host-hooks.js";
 export * from "./host-slash-commands.js";
 export * from "./hotfix-criteria.js";
 export * from "./intent-ceiling.js";
+export * from "./merge-approval-head.js";
 export * from "./min-greptile-confidence.js";
 export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";

package/dist/policy/merge-approval-head.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Head-bound human merge approval (#3235).
+ *
+ * Phase 5 → 6 `plan:approved` events authorize one immutable PR head.
+ * When PR HEAD changes after approval (and GitHub auto-merge may still be
+ * enabled), Directive fails closed: treats the approval as stale, attempts to
+ * disable auto-merge, and emits recovery text requiring a fresh approval bound
+ * to the current head.
+ *
+ * Prefer this path from finish-loop / pr-wait-mergeable / require-human-merge
+ * consumers. Does not change consumer repository rulesets.
+ */
+import { type BehavioralEventRecord } from "../lifecycle/events.js";
+/** Event name recorded at Phase 5 → 6 approval. */
+export declare const PLAN_APPROVED_EVENT = "plan:approved";
+export type MergeApprovalHeadStatus = 
+/** approved_head_sha matches current_head_sha. */
+"ok"
+/** Approval bound to a different head than current. */
+ | "stale"
+/** Approval exists but was not bound to a head SHA. */
+ | "missing_binding"
+/** No plan:approved record for this PR. */
+ | "no_approval"
+/** Gate intentionally skipped (e.g. no PR / no current head). */
+ | "skipped";
+export interface PlanApprovedRecord {
+    readonly head_sha: string | null;
+    readonly pr_number: number | null;
+    readonly approver: string | null;
+    readonly plan_ref: string | null;
+    readonly detected_at: string | null;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+export interface MergeApprovalHeadResult {
+    readonly status: MergeApprovalHeadStatus;
+    /** False when merge must not proceed under head-bound contract. */
+    readonly allowed: boolean;
+    readonly approved_head_sha: string | null;
+    readonly current_head_sha: string | null;
+    readonly pr_number: number;
+    readonly require_human_merge: boolean;
+    readonly auto_merge_disabled: boolean | null;
+    readonly message: string;
+    readonly recovery: string | null;
+}
+export type DisableAutoMergeFn = (prNumber: number, repo: string | null) => {
+    readonly ok: boolean;
+    readonly stderr: string;
+};
+export type FetchPrHeadShaFn = (prNumber: number, repo: string | null) => string | null;
+export type ReadEventsFn = (logPath?: string | null) => BehavioralEventRecord[];
+/** Full Git object id length — approvals must bind to exact heads (#3235 / Greptile P1). */
+export declare const FULL_HEAD_SHA_LEN = 40;
+/**
+ * Exact full-SHA equality only (#3235).
+ * Prefix matching is forbidden: abbreviated approval SHAs must not authorize a later head.
+ */
+export declare function headShaMatches(a: string | null, b: string | null): boolean;
+/**
+ * Latest plan:approved for a PR (by log order; last write wins).
+ * When `repo` is set, prefer records whose repository/plan_ref matches (P2 #3235).
+ */
+export declare function findLatestPlanApprovalForPr(prNumber: number, options?: {
+    readonly logPath?: string | null;
+    readonly readEventsFn?: ReadEventsFn;
+    readonly records?: readonly BehavioralEventRecord[];
+    /** owner/repo — scopes lookup when multiple remotes share a PR number. */
+    readonly repo?: string | null;
+}): PlanApprovedRecord | null;
+/** Recovery instructions when approval is stale or unbound. */
+export declare function buildMergeApprovalRecovery(input: {
+    readonly prNumber: number;
+    readonly approvedHeadSha: string | null;
+    readonly currentHeadSha: string | null;
+    readonly status: MergeApprovalHeadStatus;
+    readonly autoMergeDisabled: boolean | null;
+}): string;
+export interface EvaluateMergeApprovalHeadInput {
+    readonly prNumber: number;
+    readonly currentHeadSha: string | null;
+    readonly projectRoot?: string;
+    readonly logPath?: string | null;
+    readonly requireHumanMerge?: boolean;
+    /** owner/repo for scoped approval lookup. */
+    readonly repo?: string | null;
+    /**
+     * When true (default), approval without head_sha fails closed under
+     * requireHumanMerge. When false, missing binding is advisory only.
+     */
+    readonly enforceStrictBinding?: boolean;
+    /**
+     * When true, run the gate whenever a plan:approved exists for the PR
+     * (default). When false, only under requireHumanMerge.
+     */
+    readonly enforceWhenApprovalPresent?: boolean;
+    readonly readEventsFn?: ReadEventsFn;
+    readonly records?: readonly BehavioralEventRecord[];
+    readonly approval?: PlanApprovedRecord | null;
+}
+/**
+ * Pure evaluation: compare recorded approval head to current PR HEAD.
+ */
+export declare function evaluateMergeApprovalHead(input: EvaluateMergeApprovalHeadInput): MergeApprovalHeadResult;
+/** Live `gh pr merge <N> --disable-auto` (best-effort). */
+export declare function disablePullRequestAutoMerge(prNumber: number, repo: string | null, options?: {
+    readonly timeoutSec?: number;
+}): {
+    readonly ok: boolean;
+    readonly stderr: string;
+};
+/** REST HEAD read via `gh api repos/.../pulls/N --jq .head.sha`. */
+export declare function fetchPrHeadShaRest(prNumber: number, repo: string | null, options?: {
+    readonly timeoutSec?: number;
+}): string | null;
+export interface EnforceMergeApprovalHeadInput extends EvaluateMergeApprovalHeadInput {
+    readonly repo?: string | null;
+    /** When true (default on deny), attempt gh --disable-auto. */
+    readonly disableAutoMergeOnDeny?: boolean;
+    readonly disableAutoMergeFn?: DisableAutoMergeFn;
+    readonly fetchHeadShaFn?: FetchPrHeadShaFn;
+}
+/**
+ * Evaluate + on deny attempt to disable GitHub auto-merge and attach recovery.
+ */
+export declare function enforceMergeApprovalHead(input: EnforceMergeApprovalHeadInput): MergeApprovalHeadResult;
+/** Default event log path relative to project root. */
+export declare function defaultMergeApprovalEventLog(projectRoot: string): string;
+//# sourceMappingURL=merge-approval-head.d.ts.map