@deftai/directive-core 0.91.0 → 0.92.0

package/dist/scope/transition.js

@@ -8,6 +8,7 @@ import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief
 import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
+import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { utcNowIso } from "./vbrief-json.js";
@@ -48,7 +49,7 @@ function stampEnvelopeUpdated(data, nowIso) {
         }
     }
 }
-export function runTransition(action, filePath, now = new Date()) {
+export function runTransition(action, filePath, now = new Date(), options = {}) {
     if (!(action in TRANSITIONS)) {
         const valid = Object.keys(TRANSITIONS).sort().join(", ");
         return { ok: false, message: `Unknown action '${action}'. Valid actions: ${valid}` };
@@ -95,9 +96,15 @@ export function runTransition(action, filePath, now = new Date()) {
     const requiredStatus = STATUS_PRECONDITIONS[act];
     if (requiredStatus !== undefined) {
         if (currentStatus === targetStatus) {
+            // Surface legacy delivery disposition on already-completed briefs (#3041).
+            let dispositionSuffix = "";
+            if (act === "complete" && currentFolder === "completed") {
+                const disposition = classifyStoredDeliveryDisposition(planObj);
+                dispositionSuffix = ` (deliveryDisposition=${disposition})`;
+            }
             return {
                 ok: true,
-                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/`,
+                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/${dispositionSuffix}`,
             };
         }
         if (currentStatus !== requiredStatus) {
@@ -131,6 +138,25 @@ export function runTransition(action, filePath, now = new Date()) {
         }
     }
     const nowIso = utcNowIso(now);
+    // #3041: fail closed before mutating a code-bearing complete without delivery evidence.
+    if (act === "complete") {
+        const gate = evaluateDeliveryGate({
+            projectRoot,
+            plan: planObj,
+            nowIso,
+            evidence: options.deliveryEvidence,
+            nonDeliveryDisposition: options.nonDeliveryDisposition,
+            runGit: options.runGit,
+            verifier: options.verifier ?? "scope:complete",
+            assumeEvidenceValidated: options.assumeEvidenceValidated,
+        });
+        if (!gate.ok) {
+            return { ok: false, message: gate.message };
+        }
+        if (gate.provenance !== null) {
+            stampDeliveryProvenance(planObj, gate.provenance);
+        }
+    }
     planObj.status = targetStatus;
     planObj.updated = nowIso;
     // Keep the envelope clock aligned with plan.updated on every mutating transition (#2862).
@@ -153,7 +179,7 @@ export function runTransition(action, filePath, now = new Date()) {
         }
         // #2578: stamp terminal status at the destination path in the same write as
         // folder placement — never leave a non-terminal status under completed/.
-        const writeResult = atomicWriteBrief(destPath, data, vbriefRoot);
+        const writeResult = atomicWriteBrief(destPath, data, vbriefRoot, { projectRoot });
         if (!writeResult.ok) {
             return { ok: false, message: writeResult.message };
         }
@@ -193,7 +219,7 @@ export function runTransition(action, filePath, now = new Date()) {
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
-    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot);
+    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot, { projectRoot });
     if (!writeResult.ok) {
         return { ok: false, message: writeResult.message };
     }

package/dist/session/ritual-sentinel.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
 import { stableJson } from "./json.js";
 import { RITUAL_STATE_CONTRACT } from "./posture.js";
@@ -95,21 +96,29 @@ function validateSteps(raw, key) {
     }
     return [steps, null];
 }
-function atomicWriteJson(targetPath, payload, prefix) {
-    const dir = join(targetPath, "..");
-    mkdirSync(dir, { recursive: true });
-    const tmpBase = `${prefix}${process.pid}.json.tmp`;
+/**
+ * Contained atomic JSON write for ritual/sentinel state (#3042).
+ * Containment root is projectRoot (not dirname(target)) so a force-added `.deft`
+ * directory symlink fails closed before temp+rename.
+ */
+function atomicWriteJson(projectRoot, targetPath, payload, prefix) {
+    const root = resolve(projectRoot);
+    const abs = resolve(targetPath);
+    // Refuse leaf/parent symlinks on the final path before temp+rename publish.
+    assertWriteTargetSafe(root, abs);
+    const dir = dirname(abs);
+    const tmpBase = `${prefix}${process.pid}.${basename(abs)}.tmp`;
     const tmpName = join(dir, tmpBase);
     const text = `${stableJson(payload, 2)}\n`;
     try {
-        // #2980 wave D: ritual-state product write routes through containedWrite.
+        // #2980 wave D / #3042: product write routes through containedWrite under projectRoot.
         containedWrite({
-            root: resolve(dir),
-            target: tmpBase,
+            root,
+            target: tmpName,
             data: text,
             mode: "create",
         });
-        renameSync(tmpName, targetPath);
+        renameSync(tmpName, abs);
     }
     catch (err) {
         try {
@@ -191,7 +200,7 @@ export function readRitualState(projectRoot) {
 }
 export function writeRitualState(projectRoot, payload) {
     const stateFile = ritualStatePath(projectRoot);
-    atomicWriteJson(stateFile, payload, ".ritual-state.");
+    atomicWriteJson(projectRoot, stateFile, payload, ".ritual-state.");
     return stateFile;
 }
 /** Instant guaranteed to fail `evaluateLoadedState` age checks on any policy horizon. */
@@ -303,7 +312,7 @@ export function writeSentinel(projectRoot, input) {
             .replace(`${LEGACY_ARTIFACT_DIR}/active/`, `${MIGRATED_ARTIFACT_DIR}/active/`),
         lastBranch: input.lastBranch,
     };
-    atomicWriteJson(sentinelFile, payload, ".last-session.");
+    atomicWriteJson(projectRoot, sentinelFile, payload, ".last-session.");
     return sentinelFile;
 }
 function formatElapsed(deltaMs) {

package/dist/session/session-start-hook.d.ts

@@ -1,3 +1,4 @@
+import { detectDeftDirectiveDisable } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective } from "../policy/no-deft-directive.js";
 import { writeSentinel } from "./ritual-sentinel.js";
 export interface SessionStartHookOptions {
@@ -7,6 +8,8 @@ export interface SessionStartHookOptions {
     readonly writeSentinelFn?: typeof writeSentinel;
     /** Test seam for #2926 opt-out detection. */
     readonly detectNoDeftDirectiveFn?: typeof detectNoDeftDirective;
+    /** Test seam for #3039 test kill-switch detection. */
+    readonly detectDeftDirectiveDisableFn?: typeof detectDeftDirectiveDisable;
 }
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export declare function runSessionStartHookWrite(projectRoot: string, options?: SessionStartHookOptions): {

package/dist/session/session-start-hook.js

@@ -1,9 +1,30 @@
 import { resolveVersion } from "../doctor/paths.js";
+import { detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
 import { detectBranch } from "./git.js";
 import { detectLatestActiveVbrief, writeSentinel } from "./ritual-sentinel.js";
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export function runSessionStartHookWrite(projectRoot, options = {}) {
+    const detectKill = options.detectDeftDirectiveDisableFn ?? detectDeftDirectiveDisable;
+    // #3039: local (untracked) kill-switch — skip ritual bookkeeping (deposit OK).
+    // Tracked flags do not short-circuit (enforcement stays on).
+    const kill = detectKill(projectRoot);
+    const killActive = options.detectDeftDirectiveDisableFn !== undefined
+        ? kill.active
+        : isDeftDirectiveDisableActive(projectRoot);
+    if (killActive) {
+        const detectOptOut = options.detectNoDeftDirectiveFn ?? detectNoDeftDirective;
+        const optOut = detectOptOut(projectRoot);
+        const message = formatDeftDirectiveDisableMessage({
+            permanentOptOutAlsoPresent: optOut.present,
+            trackedByGit: false,
+        });
+        return {
+            code: 0,
+            stdout: `${message}\n`,
+            stderr: "",
+        };
+    }
     const detectOptOut = options.detectNoDeftDirectiveFn ?? detectNoDeftDirective;
     // #2926: root opt-out wins — host SessionStart must not write ritual bookkeeping.
     const optOut = detectOptOut(projectRoot);

package/dist/session/session-start.js

@@ -3,6 +3,7 @@ import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
+import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/require-human-merge.js";
@@ -543,6 +544,36 @@ export function runSessionStart(projectRoot, options = {}) {
     const runGit = options.runGit ?? defaultGitRunner;
     const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
     const ceremonyTier = options.ceremonyTier ?? COLD_CEREMONY_TIER;
+    // #3039: local (untracked) test kill-switch — skip ritual write; deposit may remain.
+    // Recovery requires delete + new session. Tracked flags do not short-circuit.
+    if (isDeftDirectiveDisableActive(projectRoot)) {
+        const killSwitch = detectDeftDirectiveDisable(projectRoot);
+        const optOutAlso = detectNoDeftDirective(projectRoot);
+        const message = formatDeftDirectiveDisableMessage({
+            permanentOptOutAlsoPresent: optOutAlso.present,
+            trackedByGit: false,
+        });
+        const lines = message.split("\n");
+        return {
+            code: 0,
+            payload: {
+                ready: false,
+                exit_code: 0,
+                disabled: true,
+                disabled_via: DEFT_DIRECTIVE_DISABLE_FLAG_NAME,
+                status: DEFT_DIRECTIVE_DISABLE_STATUS,
+                kill_switch: true,
+                inconsistent: false,
+                deposit_present: killSwitch.depositPresent,
+                tracked_by_git: false,
+                permanent_opt_out_also_present: optOutAlso.present,
+                posture,
+                environment: environmentContextToDict(environment),
+                message,
+            },
+            lines,
+        };
+    }
     // #2926: official root opt-out wins locally — skip Directive session ritual.
     // disabled = skip ritual (exit 0 clean / 1 inconsistent). ready stays false so
     // automation does not treat opt-out as "session fully initialized for work".

package/dist/swarm/complete-cohort.d.ts

@@ -1,3 +1,14 @@
+import { type DeliveryEvidenceInput, type NonDeliveryDisposition } from "../scope/delivery-evidence.js";
+/** Per-story or default delivery evidence for cohort completion (#3041). */
+export interface CohortDeliveryContext {
+    /** Evidence keyed by absolute story path (preferred). */
+    readonly evidenceByPath?: ReadonlyMap<string, DeliveryEvidenceInput> | null;
+    /** Shared evidence applied to every story when per-path map misses. */
+    readonly defaultEvidence?: DeliveryEvidenceInput | null;
+    readonly nonDeliveryDisposition?: NonDeliveryDisposition | null;
+    readonly assumeEvidenceValidated?: boolean;
+    readonly verifier?: string;
+}
 export interface TransitionRecord {
     kind: "story" | "epic";
     path: string;
@@ -17,7 +28,13 @@ export declare function resolveCohortPaths(positional: readonly string[], cohort
     paths: string[];
     errors: string[];
 };
-export declare function sweepCohort(storyPaths: readonly string[], projectRoot: string, dryRun: boolean): SweepResult;
+export interface SweepCohortArgs {
+    readonly storyPaths: readonly string[];
+    readonly projectRoot: string;
+    readonly dryRun: boolean;
+    readonly delivery?: CohortDeliveryContext | null;
+}
+export declare function sweepCohort(storyPaths: readonly string[], projectRoot: string, dryRun: boolean, delivery?: CohortDeliveryContext | null): SweepResult;
 export declare function sweepResultToDict(result: SweepResult): Record<string, unknown>;
 export declare function renderSweepText(result: SweepResult): string;
 export declare function completeCohort(args: {
@@ -26,6 +43,8 @@ export declare function completeCohort(args: {
     projectRoot: string;
     dryRun?: boolean;
     emitJson?: boolean;
+    /** Per-story delivery evidence; without it code-bearing stories fail closed (#3041). */
+    delivery?: CohortDeliveryContext | null;
 }): {
     exitCode: number;
     stdout: string;

package/dist/swarm/complete-cohort.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectLifecycleFolder } from "../scope/decomposed-refs.js";
+import { classifyStoredDeliveryDisposition, } from "../scope/delivery-evidence.js";
 import { runTransition } from "../scope/transition.js";
 import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "../scope/vbrief-ref.js";
 import { MAX_FIXPOINT_PASSES, TERMINAL_FOLDERS } from "./constants.js";
@@ -115,17 +116,38 @@ function parentCandidatesFrom(plan, vbriefDir) {
     }
     return out;
 }
-function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
+function transitionOptionsFor(storyPath, delivery) {
+    if (delivery === null || delivery === undefined) {
+        return { verifier: "swarm:complete-cohort" };
+    }
+    const pathKey = resolve(storyPath);
+    const evidence = delivery.evidenceByPath?.get(pathKey) ??
+        delivery.evidenceByPath?.get(storyPath) ??
+        delivery.defaultEvidence ??
+        null;
+    return {
+        deliveryEvidence: evidence,
+        nonDeliveryDisposition: delivery.nonDeliveryDisposition,
+        assumeEvidenceValidated: delivery.assumeEvidenceValidated,
+        verifier: delivery.verifier ?? "swarm:complete-cohort",
+    };
+}
+function completeStory(args) {
+    const { storyPath, vbriefDir, projectRoot, settled, dryRun, delivery } = args;
     const folder = detectLifecycleFolder(storyPath);
     const relpath = rel(storyPath, projectRoot);
     if (folder !== null && TERMINAL_FOLDERS.includes(folder)) {
         settled.add(resolve(storyPath));
+        const plan = loadPlan(storyPath);
+        const disposition = folder === "completed" && plan !== null ? classifyStoredDeliveryDisposition(plan) : "unknown";
         return {
             kind: "story",
             path: relpath,
             action: "noop",
             ok: true,
-            detail: `already in ${folder}/`,
+            detail: folder === "completed"
+                ? `already in ${folder}/ (deliveryDisposition=${disposition})`
+                : `already in ${folder}/`,
         };
     }
     if (folder !== "active") {
@@ -147,7 +169,7 @@ function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
             detail: "would complete active/ -> completed/",
         };
     }
-    const result = runTransition("complete", storyPath);
+    const result = runTransition("complete", storyPath, new Date(), transitionOptionsFor(storyPath, delivery));
     if (result.ok) {
         settled.add(resolve(join(vbriefDir, "completed", storyPath.split(/[/\\]/).pop() ?? "")));
     }
@@ -159,7 +181,8 @@ function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
         detail: result.message,
     };
 }
-function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
+function completeParent(args) {
+    const { parentPath, vbriefDir, projectRoot, settled, dryRun, delivery } = args;
     const folder = detectLifecycleFolder(parentPath);
     const relpath = rel(parentPath, projectRoot);
     if (folder !== null && TERMINAL_FOLDERS.includes(folder)) {
@@ -217,7 +240,7 @@ function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
         }
         current = join(vbriefDir, "active", parentPath.split(/[/\\]/).pop() ?? "");
     }
-    const completeResult = runTransition("complete", current);
+    const completeResult = runTransition("complete", current, new Date(), transitionOptionsFor(current, delivery));
     if (completeResult.ok) {
         settled.add(resolve(join(vbriefDir, "completed", parentPath.split(/[/\\]/).pop() ?? "")));
     }
@@ -229,7 +252,12 @@ function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
         detail: completeResult.message,
     };
 }
-export function sweepCohort(storyPaths, projectRoot, dryRun) {
+export function sweepCohort(storyPaths, projectRoot, dryRun, delivery) {
+    return sweepCohortWithArgs({ storyPaths, projectRoot, dryRun, delivery: delivery ?? null });
+}
+function sweepCohortWithArgs(args) {
+    const { storyPaths, projectRoot, dryRun } = args;
+    const delivery = args.delivery ?? null;
     let vbriefDir;
     try {
         vbriefDir = resolveLifecycleRoot(projectRoot);
@@ -275,7 +303,14 @@ export function sweepCohort(storyPaths, projectRoot, dryRun) {
                 }
             }
         }
-        result.stories.push(completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun));
+        result.stories.push(completeStory({
+            storyPath,
+            vbriefDir,
+            projectRoot,
+            settled,
+            dryRun,
+            delivery,
+        }));
     }
     const finalized = new Set();
     let passes = 0;
@@ -294,7 +329,14 @@ export function sweepCohort(storyPaths, projectRoot, dryRun) {
             if (!allChildrenSettled(parentPlan, vbriefDir, settled, dryRun)) {
                 continue;
             }
-            const record = completeParent(candidate, vbriefDir, projectRoot, settled, dryRun);
+            const record = completeParent({
+                parentPath: candidate,
+                vbriefDir,
+                projectRoot,
+                settled,
+                dryRun,
+                delivery,
+            });
             result.parents.push(record);
             finalized.add(candidate);
             progressed = true;
@@ -403,7 +445,12 @@ export function completeCohort(args) {
         }
         return { exitCode: 2, stdout: "", stderr };
     }
-    const result = sweepCohort(paths, projectRoot, args.dryRun ?? false);
+    const result = sweepCohortWithArgs({
+        storyPaths: paths,
+        projectRoot,
+        dryRun: args.dryRun ?? false,
+        delivery: args.delivery ?? null,
+    });
     result.errors.push(...errors);
     if (args.emitJson) {
         return {

package/dist/swarm/finalize-cohort-cli.js

@@ -7,6 +7,7 @@ export function parseFinalizeCohortArgv(argv) {
     let repo = null;
     let projectRoot = ".";
     let baseBranch = "master";
+    let deliveryBranch = null;
     let label = null;
     let dryRun = false;
     let noCommit = false;
@@ -51,6 +52,13 @@ export function parseFinalizeCohortArgv(argv) {
             baseBranch = next;
             i += 1;
         }
+        else if (arg === "--delivery-branch" && next !== undefined) {
+            deliveryBranch = next;
+            i += 1;
+        }
+        else if (arg?.startsWith("--delivery-branch=")) {
+            deliveryBranch = arg.slice("--delivery-branch=".length);
+        }
         else if (arg === "--label" && next !== undefined) {
             label = next;
             i += 1;
@@ -77,6 +85,7 @@ export function parseFinalizeCohortArgv(argv) {
         repo,
         projectRoot,
         baseBranch,
+        deliveryBranch,
         label,
         dryRun,
         noCommit,

package/dist/swarm/finalize-cohort.d.ts

@@ -12,6 +12,8 @@ export interface FinalizeCohortResult {
     readonly commit_sha: string | null;
     readonly branch: string | null;
     readonly pr_url: string | null;
+    readonly delivery_branch: string | null;
+    readonly delivery_errors: readonly string[];
     readonly errors: readonly string[];
     readonly warnings: readonly string[];
     readonly ok: boolean;
@@ -21,7 +23,13 @@ export interface FinalizeCohortArgs {
     readonly storyTokens?: readonly string[];
     readonly repo?: string | null;
     readonly projectRoot?: string;
+    /**
+     * Swarm/PR base for the post-merge lifecycle sweep PR only.
+     * Distinct from plan.policy.deliveryBranch (#3041).
+     */
     readonly baseBranch?: string;
+    /** Override delivery branch for this run (defaults to policy/git default). */
+    readonly deliveryBranch?: string | null;
     readonly label?: string | null;
     readonly dryRun?: boolean;
     readonly noCommit?: boolean;