@deftai/directive-core 0.89.0 → 0.91.0

package/dist/scope/main.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { canonicalLogPath, readAll } from "./audit-log.js";
+import { batchPromote } from "./batch-promote.js";
 import { TRANSITIONS } from "./constants.js";
 import { batchDemote, DEFAULT_OLDER_THAN_DAYS, demoteOne, resolveDemoteFilePath, resolveFilePath, resolveProjectRootStrict, } from "./demote.js";
 import { completedPathForScopeMove, findOpenUmbrellaReferences, renderOpenUmbrellaWarning, } from "./open-umbrella-warning.js";
@@ -10,12 +11,13 @@ import { resolveProjectRoot } from "./project-context.js";
 import { recordWipCapOverride, runTransition } from "./transition.js";
 import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoOne, } from "./undo.js";
 import { checkWipCap, formatWipCapRefusal } from "./wip-cap-check.js";
-const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force]\n" +
+const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force] [--batch]\n" +
     "                          {activate,block,cancel,complete,fail,promote,restore,unblock}\n" +
-    "                          file\n" +
-    "scope_lifecycle.py: error: the following arguments are required: action, file\n";
+    "                          [file ...]\n" +
+    "scope_lifecycle.py: error: the following arguments are required: action, file\n" +
+    "(promote --batch may omit file and promotes all proposed/ scopes; #3011)\n";
 function parseLifecycleArgv(argv) {
-    if (argv.length < 2) {
+    if (argv.length < 1) {
         return { args: null, error: "usage" };
     }
     const action = argv[0] ?? "";
@@ -25,6 +27,8 @@ function parseLifecycleArgv(argv) {
     let file = "";
     let projectRoot;
     let force = false;
+    let batch = false;
+    const batchFiles = [];
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === undefined) {
@@ -33,6 +37,9 @@ function parseLifecycleArgv(argv) {
         if (arg === "--force") {
             force = true;
         }
+        else if (arg === "--batch") {
+            batch = true;
+        }
         else if (arg === "--project-root") {
             projectRoot = argv[i + 1];
             i += 1;
@@ -40,13 +47,36 @@ function parseLifecycleArgv(argv) {
         else if (arg?.startsWith("--project-root=")) {
             projectRoot = arg.slice("--project-root=".length);
         }
-        else if (!arg.startsWith("-") && file.length === 0) {
-            file = arg;
+        else if (!arg.startsWith("-")) {
+            if (batch) {
+                batchFiles.push(arg);
+            }
+            else if (file.length === 0) {
+                file = arg;
+            }
+            else {
+                return { args: null, error: "usage" };
+            }
         }
         else {
             return { args: null, error: "usage" };
         }
     }
+    if (batch) {
+        if (action !== "promote") {
+            return { args: null, error: "usage" };
+        }
+        return {
+            args: {
+                action,
+                file: file.length > 0 ? file : "",
+                projectRoot,
+                force,
+                batch: true,
+                batchFiles: batchFiles.length > 0 ? batchFiles : file.length > 0 ? [file] : [],
+            },
+        };
+    }
     if (file.length === 0) {
         return { args: null, error: "usage" };
     }
@@ -61,7 +91,28 @@ export function lifecycleMain(argv) {
         }
         return 2;
     }
-    const { action, file, projectRoot, force } = parsed.args;
+    const { action, file, projectRoot, force, batch, batchFiles } = parsed.args;
+    if (batch === true && action === "promote") {
+        const result = batchPromote({
+            files: batchFiles && batchFiles.length > 0 ? batchFiles : undefined,
+            force: force === true,
+            projectRoot,
+        });
+        for (const line of result.messages) {
+            process.stdout.write(`${line}\n`);
+        }
+        for (const line of result.skipped) {
+            process.stdout.write(`  skipped: ${line}\n`);
+        }
+        if (!result.ok && result.exitCode !== 0) {
+            for (const line of result.messages) {
+                if (line.startsWith("ERROR:") || line.includes("WIP cap")) {
+                    process.stderr.write(`${line}\n`);
+                }
+            }
+        }
+        return result.exitCode;
+    }
     const [filePath, error] = resolveFilePath(file, projectRoot);
     if (error !== null || filePath === null) {
         process.stderr.write(`Error: ${error}\n`);

package/dist/scope/wip-cap-check.d.ts

@@ -7,5 +7,11 @@ export interface WipCapCheck {
 }
 /** Resolve WIP cap and decide if promotion is allowed (#1124). */
 export declare function checkWipCap(projectRoot: string, force?: boolean): WipCapCheck;
+/**
+ * WIP check for promoting `additional` scopes in one batch (#3011).
+ * Single promote is `additional = 1` (same as historic count >= cap refuse).
+ * Batch of N refuses when `count + N > cap` unless `--force`.
+ */
+export declare function checkWipCapForAdditional(projectRoot: string, additional: number, force?: boolean): WipCapCheck;
 export declare function formatWipCapRefusal(check: WipCapCheck): string;
 //# sourceMappingURL=wip-cap-check.d.ts.map

package/dist/scope/wip-cap-check.js

@@ -1,10 +1,21 @@
 import { countVbriefWip, resolveWipCap } from "../policy/wip.js";
 /** Resolve WIP cap and decide if promotion is allowed (#1124). */
 export function checkWipCap(projectRoot, force = false) {
+    return checkWipCapForAdditional(projectRoot, 1, force);
+}
+/**
+ * WIP check for promoting `additional` scopes in one batch (#3011).
+ * Single promote is `additional = 1` (same as historic count >= cap refuse).
+ * Batch of N refuses when `count + N > cap` unless `--force`.
+ */
+export function checkWipCapForAdditional(projectRoot, additional, force = false) {
     const capResult = resolveWipCap(projectRoot);
     const cap = capResult.cap;
     const count = countVbriefWip(projectRoot);
-    const overCap = count >= cap;
+    const add = Math.max(0, Math.floor(additional));
+    // Single-promote parity: refuse when already at/over cap before adding one.
+    // Batch: refuse when current + additional would exceed the cap.
+    const overCap = add <= 1 ? count >= cap : count + add > cap;
     if (!overCap) {
         return { allowed: true, cap, count, source: capResult.source, forceOverride: false };
     }
@@ -18,6 +29,7 @@ export function formatWipCapRefusal(check) {
         "Either:\n" +
         "  task scope:demote <existing>                              # return one to proposed/\n" +
         "  task scope:demote --batch --older-than-days 30            # bulk relief (D9 folded into D1)\n" +
-        "  task scope:promote <file> --force                          # override (logged)");
+        "  task scope:promote <file> --force                          # override (logged)\n" +
+        "  task scope:promote --batch --force                         # batch override (#3011)");
 }
 //# sourceMappingURL=wip-cap-check.js.map

package/dist/session/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./git.js";
 export * from "./json.js";
 export * from "./posture.js";
+export * from "./process-cost.js";
 export * from "./resume-conditions.js";
 export * from "./ritual-sentinel.js";
+export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";

package/dist/session/index.js

@@ -1,8 +1,10 @@
 export * from "./git.js";
 export * from "./json.js";
 export * from "./posture.js";
+export * from "./process-cost.js";
 export * from "./resume-conditions.js";
 export * from "./ritual-sentinel.js";
+export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";

package/dist/session/process-cost-constants.d.ts

@@ -0,0 +1,9 @@
+/** Canonical process-cost event names for ceremony observability (#2994). */
+export declare const PROCESS_COST_EVENT_NAMES: {
+    readonly sessionStart: "session:start";
+    readonly sessionRitualBlocked: "session:ritual-blocked";
+};
+export type ProcessCostEventName = (typeof PROCESS_COST_EVENT_NAMES)[keyof typeof PROCESS_COST_EVENT_NAMES];
+/** Required payload keys per process-cost event (merged into lifecycle/events). */
+export declare const PROCESS_COST_REQUIRED_PAYLOAD: Readonly<Record<string, readonly string[]>>;
+//# sourceMappingURL=process-cost-constants.d.ts.map

package/dist/session/process-cost-constants.js

@@ -0,0 +1,11 @@
+/** Canonical process-cost event names for ceremony observability (#2994). */
+export const PROCESS_COST_EVENT_NAMES = {
+    sessionStart: "session:start",
+    sessionRitualBlocked: "session:ritual-blocked",
+};
+/** Required payload keys per process-cost event (merged into lifecycle/events). */
+export const PROCESS_COST_REQUIRED_PAYLOAD = {
+    [PROCESS_COST_EVENT_NAMES.sessionStart]: ["ceremony_tier", "duration_ms", "exit_code"],
+    [PROCESS_COST_EVENT_NAMES.sessionRitualBlocked]: ["tool_name", "code"],
+};
+//# sourceMappingURL=process-cost-constants.js.map

package/dist/session/process-cost.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Local process-cost ceremony events (#2994).
+ *
+ * Always-on, best-effort appends to `.deft-cache/events.jsonl`.
+ * Not gated on valueFeedback (distinct from #1709 attribution).
+ * No remote / Product Insights upload (#2603 not required).
+ *
+ * Types are declared locally (not imported from session-start) so this module
+ * does not form an import cycle with session-start call sites.
+ */
+import { type BehavioralEventRecord } from "../lifecycle/events.js";
+export { PROCESS_COST_EVENT_NAMES, PROCESS_COST_REQUIRED_PAYLOAD, type ProcessCostEventName, } from "./process-cost-constants.js";
+/** Ceremony tier labels mirror session-start cold|rearm (#2992 / #2994). */
+export type ProcessCostCeremonyTier = "cold" | "rearm";
+export interface ProcessCostStepTiming {
+    readonly name: string;
+    readonly duration_ms: number;
+    readonly skipped?: boolean;
+}
+export interface EmitProcessCostOptions {
+    readonly projectRoot: string;
+    /**
+     * Optional explicit log path for tests.
+     * When omitted, `emit` resolves via DEFT_EVENT_LOG then `.deft-cache/events.jsonl`
+     * (must not pre-resolve the default here or DEFT_EVENT_LOG is bypassed).
+     */
+    readonly logPath?: string | null;
+}
+export interface SessionStartProcessCostInput {
+    readonly ceremonyTier: ProcessCostCeremonyTier;
+    readonly durationMs: number;
+    readonly exitCode: number;
+    readonly ready?: boolean;
+    readonly optionalNetwork?: boolean;
+    readonly steps?: readonly ProcessCostStepTiming[];
+}
+export interface SessionRitualBlockedProcessCostInput {
+    readonly toolName: string;
+    readonly code?: string;
+    readonly recoveryTier?: "cold" | "rearm";
+    readonly detail?: string;
+}
+/**
+ * Emit `session:start` after cold/re-arm ceremony completes (or fails early).
+ * Returns null on any failure (telemetry must not interrupt session:start).
+ */
+export declare function emitSessionStartProcessCost(input: SessionStartProcessCostInput, options: EmitProcessCostOptions): BehavioralEventRecord | null;
+/**
+ * Emit `session:ritual-blocked` on PreToolUse ritual-not-ready deny.
+ * Returns null on any failure (telemetry must not change deny verdict).
+ */
+export declare function emitSessionRitualBlockedProcessCost(input: SessionRitualBlockedProcessCostInput, options: EmitProcessCostOptions): BehavioralEventRecord | null;
+//# sourceMappingURL=process-cost.d.ts.map

package/dist/session/process-cost.js

@@ -0,0 +1,82 @@
+/**
+ * Local process-cost ceremony events (#2994).
+ *
+ * Always-on, best-effort appends to `.deft-cache/events.jsonl`.
+ * Not gated on valueFeedback (distinct from #1709 attribution).
+ * No remote / Product Insights upload (#2603 not required).
+ *
+ * Types are declared locally (not imported from session-start) so this module
+ * does not form an import cycle with session-start call sites.
+ */
+import { emit } from "../lifecycle/events.js";
+import { PROCESS_COST_EVENT_NAMES } from "./process-cost-constants.js";
+export { PROCESS_COST_EVENT_NAMES, PROCESS_COST_REQUIRED_PAYLOAD, } from "./process-cost-constants.js";
+/**
+ * Emit `session:start` after cold/re-arm ceremony completes (or fails early).
+ * Returns null on any failure (telemetry must not interrupt session:start).
+ */
+export function emitSessionStartProcessCost(input, options) {
+    try {
+        const payload = {
+            ceremony_tier: input.ceremonyTier,
+            duration_ms: input.durationMs,
+            exit_code: input.exitCode,
+        };
+        if (input.ready !== undefined) {
+            payload.ready = input.ready;
+        }
+        if (input.optionalNetwork !== undefined) {
+            payload.optional_network = input.optionalNetwork;
+        }
+        if (input.steps !== undefined) {
+            payload.steps = input.steps.map((step) => {
+                const entry = {
+                    name: step.name,
+                    duration_ms: step.duration_ms,
+                };
+                if (step.skipped === true) {
+                    entry.skipped = true;
+                }
+                return entry;
+            });
+        }
+        // Pass logPath only when caller overrides; otherwise emit honors DEFT_EVENT_LOG.
+        const emitOptions = { projectRoot: options.projectRoot };
+        if (options.logPath !== undefined) {
+            emitOptions.logPath = options.logPath;
+        }
+        return emit(PROCESS_COST_EVENT_NAMES.sessionStart, payload, emitOptions);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Emit `session:ritual-blocked` on PreToolUse ritual-not-ready deny.
+ * Returns null on any failure (telemetry must not change deny verdict).
+ */
+export function emitSessionRitualBlockedProcessCost(input, options) {
+    try {
+        const payload = {
+            tool_name: input.toolName,
+            code: input.code ?? "ritual-not-ready",
+        };
+        if (input.recoveryTier !== undefined) {
+            payload.recovery_tier = input.recoveryTier;
+        }
+        if (input.detail !== undefined && input.detail.length > 0) {
+            // Cap free-form detail so JSONL lines stay bounded.
+            payload.detail =
+                input.detail.length > 240 ? `${input.detail.slice(0, 237)}...` : input.detail;
+        }
+        const emitOptions = { projectRoot: options.projectRoot };
+        if (options.logPath !== undefined) {
+            emitOptions.logPath = options.logPath;
+        }
+        return emit(PROCESS_COST_EVENT_NAMES.sessionRitualBlocked, payload, emitOptions);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=process-cost.js.map

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

@@ -30,6 +30,8 @@ export interface RitualStepInput {
     readonly exitCode?: number | null;
     readonly message?: string | null;
     readonly command?: readonly string[] | null;
+    /** Wall-clock ms for this step when measured (#2991). */
+    readonly durationMs?: number | null;
 }
 export declare function ritualStatePath(projectRoot: string): string;
 export declare function ritualStep(input: RitualStepInput): Record<string, unknown>;
@@ -53,10 +55,13 @@ export interface MarkRitualStaleAfterCompactResult {
 /**
  * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
  * Reuses ritual-state age semantics — no parallel policy stack.
+ * Marks rearm_needed so recovery messaging prefers session:start --rearm when cold is unnecessary (#2992).
  */
 export declare function markRitualStaleAfterCompact(projectRoot: string, input?: {
     now?: Date;
 }): MarkRitualStaleAfterCompactResult;
+/** Whether ritual-state.json marks compact/age recovery as re-arm preferred (#2992). */
+export declare function ritualStateMarksRearmNeeded(state: RitualState): boolean;
 export declare function recordRitualStep(projectRoot: string, input: {
     tier: "quick" | "gated";
     stepName: string;

package/dist/session/ritual-sentinel.js

@@ -35,6 +35,9 @@ export function ritualStep(input) {
     if (input.command && input.command.length > 0) {
         payload.command = input.command.map(String);
     }
+    if (input.durationMs !== null && input.durationMs !== undefined) {
+        payload.duration_ms = Math.max(0, Math.round(input.durationMs));
+    }
     return payload;
 }
 export function newRitualStatePayload(input) {
@@ -196,6 +199,7 @@ export const RITUAL_STALE_EPOCH = new Date("1970-01-01T00:00:00Z");
 /**
  * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
  * Reuses ritual-state age semantics — no parallel policy stack.
+ * Marks rearm_needed so recovery messaging prefers session:start --rearm when cold is unnecessary (#2992).
  */
 export function markRitualStaleAfterCompact(projectRoot, input = {}) {
     const now = input.now ?? new Date();
@@ -211,14 +215,21 @@ export function markRitualStaleAfterCompact(projectRoot, input = {}) {
     const payload = { ...state.raw };
     payload.started_at = timestampIso(RITUAL_STALE_EPOCH);
     payload.compact_resume_at = timestampIso(now);
+    // #2992: compact invalidates the ritual clock only — prefer re-arm recovery when worktree/HEAD allow.
+    payload.rearm_needed = true;
     writeRitualState(projectRoot, payload);
     return {
         changed: true,
         statePath,
-        message: "Marked session ritual stale after context compaction; run session:start and " +
+        message: "Marked session ritual re-arm needed after context compaction; run " +
+            "session:start --rearm (or full session:start if worktree/HEAD changed) and " +
             "verify:session-ritual -- --tier=gated before direct writes.",
     };
 }
+/** Whether ritual-state.json marks compact/age recovery as re-arm preferred (#2992). */
+export function ritualStateMarksRearmNeeded(state) {
+    return state.raw.rearm_needed === true || typeof state.raw.compact_resume_at === "string";
+}
 export function recordRitualStep(projectRoot, input) {
     const [state, err] = readRitualState(projectRoot);
     if (state === null) {

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

@@ -0,0 +1,67 @@
+/**
+ * session:ready — one-shot mutation recovery (#2993).
+ *
+ * Composes existing APIs (does not reimplement session:start or gated verify):
+ *   1. Fast path when inspectSessionRitual(gated) is already green
+ *   2. session:start when quick-tier state is missing/stale
+ *   3. verifySessionRitual(--tier=gated) for doctor + cache_fresh
+ *   4. cache fetch-all recovery when cache_fresh is the remaining blocker
+ *   5. re-verify gated
+ *
+ * Exit 0 means a subsequent inspect/verify gated would pass (or the single
+ * remaining hard blocker is printed once).
+ */
+import type { GitRunner } from "./git.js";
+import { type SessionStartOptions, type SessionStartResult } from "./session-start.js";
+import { type InspectSessionRitualOptions, type RitualRunner, type VerifyResult, type VerifySessionRitualOptions } from "./verify-session-ritual.js";
+export declare const SESSION_READY_FAST_PATH = "fast";
+export declare const SESSION_READY_RECOVERED = "recovered";
+export declare const SESSION_READY_VERIFIED = "verified";
+export declare const SESSION_READY_FAILED = "failed";
+export type SessionReadyPath = typeof SESSION_READY_FAST_PATH | typeof SESSION_READY_RECOVERED | typeof SESSION_READY_VERIFIED | typeof SESSION_READY_FAILED;
+export interface SessionReadyResult {
+    readonly code: number;
+    readonly message: string;
+    readonly path: SessionReadyPath;
+    readonly lines: readonly string[];
+    /** Steps actually executed (for tests / --json). */
+    readonly steps: readonly string[];
+    readonly duration_ms: number;
+}
+export type CacheFetchAllSeam = (options: {
+    source: string;
+    repo: string;
+    force?: boolean;
+    cacheRoot?: string;
+}) => unknown;
+export interface SessionReadyOptions {
+    readonly now?: Date;
+    readonly runGit?: GitRunner;
+    readonly runner?: RitualRunner;
+    readonly env?: NodeJS.ProcessEnv;
+    /** When set, overrides DEFT_TRIAGE_REPO / git remote inference for cache recovery. */
+    readonly repo?: string | null;
+    readonly sessionStartOptions?: Omit<SessionStartOptions, "now" | "runGit" | "env">;
+    readonly inspectRitual?: (projectRoot: string, options: InspectSessionRitualOptions) => VerifyResult;
+    readonly verifyRitual?: (projectRoot: string, options: VerifySessionRitualOptions) => VerifyResult;
+    readonly runStart?: (projectRoot: string, options: SessionStartOptions) => SessionStartResult;
+    readonly fetchAll?: CacheFetchAllSeam;
+    readonly inferRepo?: (projectRoot: string) => string | null;
+    /** Skip cache recovery even when cache_fresh failed (tests). */
+    readonly skipCacheRecovery?: boolean;
+}
+/** True when a gated verify failure is attributable to the cache_fresh step. */
+export declare function isCacheFreshFailure(message: string): boolean;
+/**
+ * True readiness for PreToolUse: exit 0 without DEFT_SESSION_RITUAL_SKIP bypass.
+ * Bypassed code 0 does not make inspectSessionRitual green (#2993 Greptile P1).
+ */
+export declare function isGatedVerifyActuallyReady(result: VerifyResult): boolean;
+/** Infer OWNER/NAME from DEFT_TRIAGE_REPO or git remote origin. */
+export declare function inferSessionReadyRepo(projectRoot: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * One-shot recovery: leave the worktree PreToolUse-gated-inspect green, or
+ * print the single remaining blocker.
+ */
+export declare function runSessionReady(projectRoot: string, options?: SessionReadyOptions): SessionReadyResult;
+//# sourceMappingURL=session-ready.d.ts.map