@deftai/directive-core 0.105.0 → 0.107.0

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

@@ -1,3 +1,4 @@
+import { type LifecycleVisibleResult } from "../lifecycle-visible/evaluate.js";
 import { type HostContentSurfaceSeams } from "../platform/host-content-surface.js";
 import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type CeremonyDialInputs, type CeremonyDialSelection, type ProvisionalCeremonyEstimateHints } from "../policy/ceremony-dial.js";
@@ -23,8 +24,20 @@ export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
 export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
 export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome", "verify_tools"];
+/** Session / full gated ritual set. Write dispatch uses a per-surface subset (#3738). */
 export declare const GATED_STEPS: readonly ["agent_hooks", "doctor", "cache_fresh"];
 export type GatedStepName = (typeof GATED_STEPS)[number];
+/**
+ * Gated steps a write/spawn mutation must prove from recorded ritual state (#3738).
+ * `cache_fresh` is a work-selection precondition, not a write-authorization one.
+ */
+export declare const WRITE_GATED_REQUIRED_STEPS: readonly ["agent_hooks", "doctor"];
+/**
+ * Gated steps the write path may execute (#3738).
+ * Hook readiness is deliberately non-cacheable; doctor and cache_fresh stay
+ * session-surface only.
+ */
+export declare const WRITE_GATED_EXECUTE_STEPS: readonly ["agent_hooks"];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export declare const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */
@@ -117,6 +130,11 @@ export interface SessionStartOptions {
      * network is enabled. Inject in tests.
      */
     readonly probeScm?: (options: ProbeScmReadinessOptions) => ScmReadinessReport;
+    /**
+     * #3505: per-clone lifecycle-root visibility (ignore / skip-worktree).
+     * Warn-only; never blocks session:start. Inject in tests.
+     */
+    readonly probeLifecycleVisible?: (projectRoot: string, runGit: GitRunner) => LifecycleVisibleResult;
     /**
      * #3214: ceremony dial inputs (task size × model tier × project shape).
      * Missing fields are filled by the headless provisional classifier

package/dist/session/session-start.js

@@ -3,6 +3,7 @@ import { emitSessionEvalReadback } from "../eval/readback.js";
 import { bindSessionGeneration } from "../freshness/bind.js";
 import { readLiveGeneration } from "../freshness/generation.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { evaluateLifecycleVisible, formatLifecycleVisibleSessionLines, } from "../lifecycle-visible/evaluate.js";
 import { hostContentSurfaceToDict, maybeFormatHostContentSurfaceLines, } from "../platform/host-content-surface.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { ceremonyDialToDict, formatCeremonyDialStatusLine, mergeCeremonyDialDeferrals, resolveCeremonyDial, resolveSessionCeremonyDialInputs, } from "../policy/ceremony-dial.js";
@@ -26,8 +27,8 @@ import { ceremonyDialEvidenceToDict, collectCeremonyDialConsumerEvidence, format
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
 import { applyWorktreeOccupancy, } from "./occupancy.js";
-import { runOrientationCompression, } from "./orientation-compression.js";
-import { emitSessionStartProcessCost } from "./process-cost.js";
+import { resolveSessionCompact, runOrientationCompression, } from "./orientation-compression.js";
+import { emitSessionStartProcessCost, formatSessionStartCeremonyCostLine } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { timestampIso } from "./time.js";
@@ -49,7 +50,36 @@ export const QUICK_STEPS = [
     "triage_welcome",
     "verify_tools",
 ];
+/** Session / full gated ritual set. Write dispatch uses a per-surface subset (#3738). */
 export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
+/**
+ * Gated steps a write/spawn mutation must prove from recorded ritual state (#3738).
+ * `cache_fresh` is a work-selection precondition, not a write-authorization one.
+ */
+export const WRITE_GATED_REQUIRED_STEPS = [
+    "agent_hooks",
+    "doctor",
+];
+/**
+ * Gated steps the write path may execute (#3738).
+ * Hook readiness is deliberately non-cacheable; doctor and cache_fresh stay
+ * session-surface only.
+ */
+export const WRITE_GATED_EXECUTE_STEPS = [
+    "agent_hooks",
+];
+/** Per-clone ignore/index hide of lifecycle roots — warn-only (#3505). */
+function pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit) {
+    try {
+        const probe = options.probeLifecycleVisible ??
+            ((root, git) => evaluateLifecycleVisible({ projectRoot: root, runGit: git }));
+        const result = probe(projectRoot, runGit);
+        lines.push(...formatLifecycleVisibleSessionLines(result));
+    }
+    catch {
+        // best-effort — session:start must not abort on a clone-local advisory
+    }
+}
 /** Standing one-liner when coverageDebt/checkResume is non-default (#3314). */
 function pushCoverageCheckResumeDisclosure(lines, projectRoot) {
     try {
@@ -494,6 +524,8 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     lines.push(...formatScmReadinessLines(scm));
     lines.push(...hostSurface.lines);
     lines.push(...effortBudget.lines);
+    const runGit = options.runGit ?? defaultGitRunner;
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -576,6 +608,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         ...effortBudget.lines,
         REARM_SKIPPED_FAT_PATH_MESSAGE,
     ];
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
     // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
     const policyResult = resolvePolicy(projectRoot);
     const policyMessage = disclosureLine(policyResult);
@@ -739,6 +772,10 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         optionalNetwork: false,
         steps: stepTimings,
     }, { projectRoot });
+    // #3508: operator-visible CLI process time. ⊗ not #3286 Later graduation input.
+    if (!resolveSessionCompact({ compact: options.compact, env: options.env })) {
+        lines.push(formatSessionStartCeremonyCostLine(REARM_CEREMONY_TIER, totalMs));
+    }
     return {
         code,
         payload: {
@@ -976,6 +1013,12 @@ export function runSessionStart(projectRoot, options = {}) {
         name: "effort_budget",
         duration_ms: elapsedMs(effortBudgetStepStarted),
     });
+    const lifecycleVisibleStarted = performance.now();
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
+    stepTimings.push({
+        name: "lifecycle_visible",
+        duration_ms: elapsedMs(lifecycleVisibleStarted),
+    });
     if (!quickSteps.branch_policy) {
         const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
@@ -1461,6 +1504,10 @@ export function runSessionStart(projectRoot, options = {}) {
         optionalNetwork: allowOptionalNetwork,
         steps: stepTimings,
     }, { projectRoot });
+    // #3508: operator-visible CLI process time. ⊗ not #3286 Later graduation input.
+    if (!resolveSessionCompact({ compact: options.compact, env: options.env })) {
+        lines.push(formatSessionStartCeremonyCostLine(COLD_CEREMONY_TIER, totalMs));
+    }
     return { code, payload: resultPayload, lines };
 }
 export { ritualStatePath };

package/dist/session/verify-session-ritual.d.ts

@@ -1,11 +1,32 @@
 import { type ActiveCliCheckResult, type ActiveCliCheckSeams } from "./active-cli.js";
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
-import { type GatedStepName, type SessionCeremonyTier } from "./session-start.js";
+import { type GatedStepName, type SessionCeremonyTier, WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS } from "./session-start.js";
 export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
+export { WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS };
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<GatedStepName, readonly string[]>>;
+/** Explicit skip flag threaded through the gated `cache_fresh` argv (#3507). */
+export declare const SKIP_DRIFT_PROBE_FLAG = "--skip-drift-probe";
+/** Explicit work-selection flag threaded through the gated `cache_fresh` argv (#3507). */
+export declare const WORK_SELECTION_FLAG = "--work-selection";
+/** Distinct ritual-state field — never `deferred_reason` (#3507). */
+export declare const DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION = "skipped-no-work-selection";
+export type WorkSelectionKind = "none" | "active-story" | "triage-queue" | "ordered-plan" | "for-issue" | "explicit-flag";
+export interface WorkSelectionSignal {
+    readonly inPlay: boolean;
+    readonly kind: WorkSelectionKind;
+}
+export type DetectWorkSelection = (projectRoot: string) => WorkSelectionSignal;
+/**
+ * Default work-selection detector for the gated `cache_fresh` seam (#3507).
+ * Active story xBRIEF (scope:activate residue), unexhausted ordered-plan /
+ * triage sequence. `--for-issue` is a positive evaluate override, not this
+ * detector — the gated argv never carries it.
+ */
+export declare function detectWorkSelection(projectRoot: string): WorkSelectionSignal;
+export declare function resolveGatedEntrypointCommand(stepName: GatedStepName, projectRoot: string, detect?: DetectWorkSelection): string[];
 export interface VerifyResult {
     readonly code: number;
     readonly message: string;
@@ -30,7 +51,8 @@ export type RitualRunner = (command: readonly string[], projectRoot: string) =>
 export declare function formatRitualRecoveryInstruction(tier?: SessionCeremonyTier): string;
 /**
  * Sanctioned audited defer copy for gated `cache_fresh` failure (#3506 / #3507).
- * The gated argv is always `["verify:cache-fresh"]`, so this is unconditional.
+ * Independent of the #3507 work-selection argv seam — defer is still the
+ * operator-audited escape, not the drift-probe skip.
  */
 export declare function formatCacheFreshDeferSoftPath(): string;
 export interface VerifySessionRitualOptions {
@@ -58,7 +80,26 @@ export interface VerifySessionRitualOptions {
      * {@link checkActiveCliAgainstTarget}.
      */
     readonly checkActiveCli?: (targetVersion: string | null, seams?: ActiveCliCheckSeams) => ActiveCliCheckResult;
+    /** Injectable work-selection detector for gated `cache_fresh` (#3507). */
+    readonly detectWorkSelection?: DetectWorkSelection;
+    /**
+     * Required gated steps for this surface. Defaults to all {@link GATED_STEPS}
+     * (session / full gated verify). Write dispatch uses
+     * {@link WRITE_GATED_REQUIRED_STEPS} (#3738).
+     */
+    readonly requiredGatedSteps?: readonly GatedStepName[];
+    /**
+     * Gated steps this surface may execute. Defaults to all {@link GATED_STEPS}.
+     * Write dispatch uses {@link WRITE_GATED_EXECUTE_STEPS} so `cache_fresh` and
+     * `doctor` cannot run as write-path repair (#3738).
+     */
+    readonly executeGatedSteps?: readonly GatedStepName[];
 }
+/**
+ * Options for the write/spawn mutation verifier (#3738).
+ * Required set omits `cache_fresh`; execution authority is `agent_hooks` only.
+ */
+export declare function writeGateRitualOptions(extras?: Omit<VerifySessionRitualOptions, "requiredGatedSteps" | "executeGatedSteps" | "tier">): VerifySessionRitualOptions;
 export interface InspectSessionRitualOptions {
     readonly tier?: "quick" | "gated";
     readonly now?: Date;
@@ -71,8 +112,9 @@ export interface InspectSessionRitualOptions {
  * Read-only ritual-state inspection for host hooks.
  *
  * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
- * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
- * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ * and never rewrites `.deft/ritual-state.json`. Write dispatch does **not** use
+ * this function: it must still execute `agent_hooks` (#3738). A PreToolUse
+ * decision must not become a hidden `doctor` / cache-refresh mutation boundary.
  */
 export declare function inspectSessionRitual(projectRoot: string, options?: InspectSessionRitualOptions): VerifyResult;
 export declare function verifySessionRitual(projectRoot: string, options?: VerifySessionRitualOptions): VerifyResult;

package/dist/session/verify-session-ritual.js

@@ -1,5 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
 import { readCorePackageVersion } from "../engine-version.js";
+import { hasArtifactSuffix } from "../layout/resolve.js";
+import { readPlanSequence } from "../plan-sequence/store.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
 import { checkActiveCliAgainstTarget, } from "./active-cli.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
@@ -7,9 +10,10 @@ import { pythonJsonDump } from "./json.js";
 import { ENV_SESSION_POSTURE, readOnlyPostureMessage, resolveSessionPosture, ritualStateIsPostureAuthority, } from "./posture.js";
 import { defaultRitualRunner } from "./ritual-entrypoint.js";
 import { readRitualState, ritualStateMarksRearmNeeded, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
-import { formatSessionStartRecoveryCommand, GATED_STEPS, QUICK_STEPS, } from "./session-start.js";
+import { formatSessionStartRecoveryCommand, GATED_STEPS, QUICK_STEPS, WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS, } from "./session-start.js";
 import { resolveSessionRitualStalenessHours } from "./staleness.js";
 export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
+export { WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS };
 export const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export const GATED_ENTRYPOINT_COMMANDS = {
@@ -17,6 +21,64 @@ export const GATED_ENTRYPOINT_COMMANDS = {
     doctor: ["doctor"],
     cache_fresh: ["verify:cache-fresh"],
 };
+/** Explicit skip flag threaded through the gated `cache_fresh` argv (#3507). */
+export const SKIP_DRIFT_PROBE_FLAG = "--skip-drift-probe";
+/** Explicit work-selection flag threaded through the gated `cache_fresh` argv (#3507). */
+export const WORK_SELECTION_FLAG = "--work-selection";
+/** Distinct ritual-state field — never `deferred_reason` (#3507). */
+export const DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION = "skipped-no-work-selection";
+function hasActiveStoryArtifact(projectRoot) {
+    for (const dirName of ["xbrief", "vbrief"]) {
+        const activeDir = join(projectRoot, dirName, "active");
+        try {
+            for (const entry of readdirSync(activeDir, { withFileTypes: true })) {
+                if (entry.isFile() && hasArtifactSuffix(entry.name))
+                    return true;
+            }
+        }
+        catch {
+            /* missing or unreadable active folder is not work selection */
+        }
+    }
+    return false;
+}
+function hasUnexhaustedPlanSequence(projectRoot) {
+    try {
+        const sequence = readPlanSequence(projectRoot);
+        if (sequence === null || sequence.exhausted === true)
+            return null;
+        return sequence.sequence_kind === "triage" ? "triage-queue" : "ordered-plan";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Default work-selection detector for the gated `cache_fresh` seam (#3507).
+ * Active story xBRIEF (scope:activate residue), unexhausted ordered-plan /
+ * triage sequence. `--for-issue` is a positive evaluate override, not this
+ * detector — the gated argv never carries it.
+ */
+export function detectWorkSelection(projectRoot) {
+    if (hasActiveStoryArtifact(projectRoot)) {
+        return { inPlay: true, kind: "active-story" };
+    }
+    const planKind = hasUnexhaustedPlanSequence(projectRoot);
+    if (planKind !== null) {
+        return { inPlay: true, kind: planKind };
+    }
+    return { inPlay: false, kind: "none" };
+}
+export function resolveGatedEntrypointCommand(stepName, projectRoot, detect = detectWorkSelection) {
+    const base = [...GATED_ENTRYPOINT_COMMANDS[stepName]];
+    if (stepName !== "cache_fresh")
+        return base;
+    const selection = detect(projectRoot);
+    if (selection.inPlay) {
+        return [...base, WORK_SELECTION_FLAG];
+    }
+    return [...base, SKIP_DRIFT_PROBE_FLAG];
+}
 function truthy(raw) {
     return new Set(["1", "true", "yes", "on"]).has((raw ?? "").trim().toLowerCase());
 }
@@ -25,6 +87,7 @@ function stepPasses(step) {
         return false;
     if (step.deferred_reason)
         return true;
+    // `drift_probe` is a distinct diagnostic; it must never satisfy a step (#3507).
     return step.ok === true;
 }
 function failedStepMessage(tierName, stepName, step) {
@@ -52,14 +115,29 @@ export function formatRitualRecoveryInstruction(tier = "cold") {
 }
 /**
  * Sanctioned audited defer copy for gated `cache_fresh` failure (#3506 / #3507).
- * The gated argv is always `["verify:cache-fresh"]`, so this is unconditional.
+ * Independent of the #3507 work-selection argv seam — defer is still the
+ * operator-audited escape, not the drift-probe skip.
  */
 export function formatCacheFreshDeferSoftPath() {
     const cmd = formatFrameworkCommand(["session:start", "--", "--defer", "cache_fresh=<reason>"]);
     return `Soft path (audited): \`${cmd}\`.`;
 }
-function runGatedStep(projectRoot, payload, stepName, runner, now) {
-    const command = [...GATED_ENTRYPOINT_COMMANDS[stepName]];
+function applyCacheFreshDriftProbeField(payload, command) {
+    if (command.includes(SKIP_DRIFT_PROBE_FLAG)) {
+        payload.drift_probe = DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION;
+        return;
+    }
+    if (payload.drift_probe === DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION) {
+        delete payload.drift_probe;
+    }
+}
+function shouldRearmDriftProbe(payload, projectRoot, detect) {
+    if (payload.drift_probe !== DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION)
+        return false;
+    return detect(projectRoot).inPlay;
+}
+function runGatedStep(projectRoot, payload, stepName, runner, now, detect = detectWorkSelection) {
+    const command = resolveGatedEntrypointCommand(stepName, projectRoot, detect);
     const { code, stdout, stderr } = runner(command, projectRoot);
     const message = stdout.trim() || stderr.trim() || `${command[0]} exited ${code}`;
     const gated = payload.gated_steps ?? {};
@@ -71,6 +149,9 @@ function runGatedStep(projectRoot, payload, stepName, runner, now) {
         command,
     });
     payload.gated_steps = gated;
+    if (stepName === "cache_fresh") {
+        applyCacheFreshDriftProbeField(payload, command);
+    }
     try {
         writeRitualState(projectRoot, payload);
     }
@@ -164,7 +245,8 @@ function evaluateLoadedState(projectRoot, state, input) {
         }
     }
     if (input.tier === "gated") {
-        for (const stepName of GATED_STEPS) {
+        const requiredGated = input.requiredGatedSteps ?? GATED_STEPS;
+        for (const stepName of requiredGated) {
             const step = state.gatedSteps[stepName];
             if (!stepPasses(step)) {
                 return {
@@ -181,12 +263,31 @@ function evaluateLoadedState(projectRoot, state, input) {
         recoveryTier: null,
     };
 }
+/**
+ * Options for the write/spawn mutation verifier (#3738).
+ * Required set omits `cache_fresh`; execution authority is `agent_hooks` only.
+ */
+export function writeGateRitualOptions(extras = {}) {
+    return {
+        ...extras,
+        tier: "gated",
+        posture: extras.posture ?? "mutation",
+        requiredGatedSteps: WRITE_GATED_REQUIRED_STEPS,
+        executeGatedSteps: WRITE_GATED_EXECUTE_STEPS,
+        // Write dispatch already refuses skip (dispatcher passes bypass: false).
+        // Default the same here so CI DEFT_SESSION_RITUAL_SKIP=1 cannot empty
+        // the execute loop in tests that use this helper (#3738).
+        bypass: extras.bypass ?? false,
+        envSkip: extras.envSkip ?? "",
+    };
+}
 /**
  * Read-only ritual-state inspection for host hooks.
  *
  * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
- * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
- * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ * and never rewrites `.deft/ritual-state.json`. Write dispatch does **not** use
+ * this function: it must still execute `agent_hooks` (#3738). A PreToolUse
+ * decision must not become a hidden `doctor` / cache-refresh mutation boundary.
  */
 export function inspectSessionRitual(projectRoot, options = {}) {
     const tier = options.tier ?? "quick";
@@ -361,16 +462,22 @@ export function verifySessionRitual(projectRoot, options = {}) {
         payload.gated_steps = gated;
         const runCmd = options.runner ?? defaultRitualRunner;
         const forced = new Set(options.forceGatedSteps ?? []);
+        const detect = options.detectWorkSelection ?? detectWorkSelection;
+        const executable = new Set(options.executeGatedSteps ?? [...GATED_STEPS]);
         for (const stepName of GATED_STEPS) {
+            if (!executable.has(stepName))
+                continue;
             const step = gated[stepName];
             if (step?.deferred_reason && stepName !== "agent_hooks")
                 continue;
             // Hook readiness is a live mutation prerequisite, not a cacheable doctor
             // result. Re-run it at every gated boundary so registration/shim drift
             // cannot remain hidden behind an earlier green ritual record.
-            if (stepName !== "agent_hooks" && stepPasses(step) && !forced.has(stepName))
+            const rearmDrift = stepName === "cache_fresh" && shouldRearmDriftProbe(payload, projectRoot, detect);
+            if (stepName !== "agent_hooks" && stepPasses(step) && !forced.has(stepName) && !rearmDrift) {
                 continue;
-            const writeError = runGatedStep(projectRoot, payload, stepName, runCmd, instant);
+            }
+            const writeError = runGatedStep(projectRoot, payload, stepName, runCmd, instant, detect);
             if (writeError !== null) {
                 return {
                     code: 2,
@@ -436,6 +543,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
         now: instant,
         runGit: options.runGit,
         rebindForwardHead: true,
+        requiredGatedSteps: options.requiredGatedSteps,
     });
     if (isBypassed) {
         return {

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

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
-import { finalizeCohort } from "./finalize-cohort.js";
-export declare function parseFinalizeCohortArgv(argv: readonly string[]): Parameters<typeof finalizeCohort>[0];
+import { type FinalizeCohortArgs } from "./finalize-cohort.js";
+export interface ParsedFinalizeCohortArgv extends FinalizeCohortArgs {
+    readonly help: boolean;
+    readonly error: string | null;
+}
+export declare const FINALIZE_COHORT_USAGE = "Usage: task swarm:finalize-cohort -- [--pr <n>[,<n>...]] [--stories <ids|paths>] [options]\n\nAfter cohort PRs merge, sweep story briefs active/ -> completed/ and open the lifecycle PR.\n\nOptions:\n  --pr <n>[,<n>...]            Merged PR numbers (closing issues map to active stories)\n  --stories <ids|paths>        Explicit story tokens (repeatable)\n  --repo OWNER/REPO            GitHub repo (or $GH_REPO)\n  --project-root <path>        Project root (default: cwd)\n  --base-branch <name>         Sweep/PR base (default: resolved delivery branch)\n  --delivery-branch <name>     Delivery-branch override when policy is untyped\n  --label <name>               Feature-branch label\n  --dry-run                    Print plan; no git mutation\n  --no-commit                  Sweep without committing / opening a PR\n  --no-open-pr                 Commit without opening a PR\n  --json                       Machine-readable result\n  -h, --help                   Show this help\n";
+export declare function parseFinalizeCohortArgv(argv: readonly string[]): ParsedFinalizeCohortArgv;
 export declare function finalizeCohortMain(argv?: string[]): number;
 //# sourceMappingURL=finalize-cohort-cli.d.ts.map