@deftai/directive-core 0.98.0 → 0.99.0

package/dist/swarm/pre-dispatch.js

@@ -0,0 +1,373 @@
+/**
+ * Swarm implement-leaf pre-dispatch gate (#3228).
+ *
+ * Wires #3143 delivery-attempt DENY_DUPLICATE_ACTIVE onto the swarm re-dispatch
+ * path: before starting a peer implement leaf on a unit, if a non-terminal
+ * attempt already exists → exit non-zero and do not spawn.
+ *
+ * Takeover is two steps: cancel (complete status=cancelled) the prior attempt,
+ * then pre-dispatch begin again — never concurrent dual active.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, normalize, resolve } from "node:path";
+import { activeAttempts, beginAttempt, completeAttemptOnDisk, evaluatePreDispatch, hasActiveAttempt, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, markBlocked, saveUnitLedger, withUnitLock, } from "../delivery-attempt/index.js";
+import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
+import { runText } from "./subprocess.js";
+/** Default workflow id for drive-to:merge-ready implement leaves. */
+export const IMPLEMENT_LEAF_WORKFLOW_ID = "drive-to:merge-ready";
+export const PRE_DISPATCH_ACTIONS = ["begin", "complete", "cancel"];
+export const COMPLETE_STATUSES = ["succeeded", "failed", "cancelled", "blocked"];
+export function resolveSourceRevision(projectRoot, explicit) {
+    if (explicit !== undefined && explicit.trim().length > 0) {
+        return explicit.trim();
+    }
+    const captured = runText(["git", "rev-parse", "HEAD"], { cwd: projectRoot });
+    if (captured.returncode === 0) {
+        const sha = captured.stdout.trim();
+        if (sha.length > 0)
+            return sha;
+    }
+    return "unknown";
+}
+/**
+ * True when targetId should be treated as a filesystem path (worktree), not an
+ * opaque branch/ref id. Branch names with `/` (e.g. `feat/foo`) stay opaque.
+ */
+export function looksLikeFilesystemTarget(targetId) {
+    const t = targetId.trim();
+    if (t.length === 0)
+        return false;
+    if (isAbsolute(t) || t.startsWith(".") || t.includes("\\"))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(t))
+        return true;
+    const lower = t.toLowerCase().replace(/\\/g, "/");
+    return (lower.includes(".deft-scratch/") ||
+        lower.includes("/worktrees/") ||
+        lower.startsWith("worktrees/"));
+}
+/**
+ * Canonical unit target for ledger keys so relative/absolute/separator/case
+ * variants of the same worktree do not split gate state (#3228 Greptile P1).
+ *
+ * Always resolve under projectRoot to a stable absolute lexical key (even
+ * before the path exists). Do **not** realpath: following a symlink that is
+ * created between dispatches would change the key and split ledgers.
+ * Case-fold prevents case-insensitive FS splits. Existence never changes
+ * the ledger key.
+ */
+export function normalizeTargetId(projectRoot, targetId) {
+    const trimmed = targetId.trim();
+    if (trimmed.length === 0)
+        return trimmed;
+    let pathKey = normalize(resolve(projectRoot, trimmed)).replace(/\\/g, "/").toLowerCase();
+    if (pathKey.length > 1 && pathKey.endsWith("/")) {
+        pathKey = pathKey.slice(0, -1);
+    }
+    return pathKey;
+}
+/**
+ * Best-effort physical identity for alias peer checks. Ledger keys stay lexical
+ * (stable); when a path exists, realpath groups symlink aliases that point at
+ * the same worktree so sequential begins still DENY.
+ */
+export function physicalTargetKey(projectRoot, targetId) {
+    const lexical = normalizeTargetId(projectRoot, targetId);
+    const candidates = [lexical, resolve(projectRoot, targetId.trim()), targetId.trim()];
+    for (const candidate of candidates) {
+        if (candidate.length === 0 || !existsSync(candidate))
+            continue;
+        try {
+            return normalize(realpathSync(candidate)).replace(/\\/g, "/").toLowerCase();
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    return lexical;
+}
+/** True when another unit (same scope+workflow, different target key) is active on same physical path. */
+export function hasActiveAliasPeer(projectRoot, scopeId, targetId, workflowId) {
+    const mine = physicalTargetKey(projectRoot, targetId);
+    for (const ledger of listUnitLedgers(projectRoot)) {
+        if (ledger.scopeId !== scopeId || ledger.workflowId !== workflowId)
+            continue;
+        if (ledger.targetId === targetId)
+            continue;
+        if (!hasActiveAttempt(ledger))
+            continue;
+        if (physicalTargetKey(projectRoot, ledger.targetId) === mine) {
+            return true;
+        }
+    }
+    return false;
+}
+function unitFields(input) {
+    return {
+        scopeId: input.scopeId.trim(),
+        targetId: normalizeTargetId(input.projectRoot, input.targetId),
+        workflowId: (input.workflowId ?? IMPLEMENT_LEAF_WORKFLOW_ID).trim(),
+    };
+}
+function baseResult(input, action, partial) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    return {
+        exitCode: partial.exitCode,
+        decision: partial.decision,
+        reason: partial.reason,
+        action,
+        scopeId,
+        targetId,
+        workflowId,
+        attempt: partial.attempt ?? null,
+        activeAttemptIds: partial.activeAttemptIds ?? [],
+    };
+}
+function listActiveIds(projectRoot, scopeId, targetId, workflowId) {
+    const ledger = loadUnitLedger(projectRoot, scopeId, targetId, workflowId);
+    if (ledger === null)
+        return [];
+    return activeAttempts(ledger).map((a) => a.attemptId);
+}
+/**
+ * Parse beginAttemptOnDisk-style error messages without a ReDoS-prone regex
+ * (CodeQL: polynomial regex on uncontrolled data).
+ */
+export function parseDecisionFromError(message) {
+    const prefix = "delivery-attempt ";
+    if (!message.startsWith(prefix)) {
+        return { decision: null, reason: message };
+    }
+    const rest = message.slice(prefix.length);
+    const colon = rest.indexOf(":");
+    if (colon <= 0) {
+        return { decision: null, reason: message };
+    }
+    const code = rest.slice(0, colon).trim();
+    // Bound check: decision codes are short fixed tokens (ALLOW_*/DENY_*/BLOCK_*).
+    if (code.length > 64 || code.length < 6) {
+        return { decision: null, reason: message };
+    }
+    if (!code.startsWith("ALLOW_") && !code.startsWith("DENY_") && !code.startsWith("BLOCK_")) {
+        return { decision: null, reason: message };
+    }
+    for (let i = 0; i < code.length; i += 1) {
+        const c = code.charCodeAt(i);
+        const ok = (c >= 65 && c <= 90) || // A-Z
+            (c >= 48 && c <= 57) || // 0-9
+            c === 95; // _
+        if (!ok) {
+            return { decision: null, reason: message };
+        }
+    }
+    const reason = rest.slice(colon + 1).trim();
+    return {
+        decision: code,
+        reason: reason.length > 0 ? reason : message,
+    };
+}
+function runBegin(input) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    const sourceRevision = resolveSourceRevision(input.projectRoot, input.sourceRevision);
+    const trigger = input.trigger ?? "automatic";
+    // Exclusive lock → reload → evaluate → begin+save (same decision under lock;
+    // no stale preview decision on the success path).
+    try {
+        return withUnitLock(input.projectRoot, scopeId, targetId, workflowId, () => {
+            // Symlink alias peer: different lexical keys, same physical worktree.
+            if (hasActiveAliasPeer(input.projectRoot, scopeId, targetId, workflowId)) {
+                return baseResult(input, "begin", {
+                    exitCode: EXIT_GATE_FAILED,
+                    decision: "DENY_DUPLICATE_ACTIVE",
+                    reason: "active attempt exists on alias/realpath peer of target",
+                    activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+                });
+            }
+            const current = loadOrCreateUnitLedger(input.projectRoot, {
+                scopeId,
+                targetId,
+                workflowId,
+                now: input.now,
+            });
+            const decision = evaluatePreDispatch(current, {
+                scopeId,
+                targetId,
+                workflowId,
+                sourceRevision,
+                trigger,
+                now: input.now,
+            });
+            if (!decision.allowed) {
+                if (decision.handoff !== null) {
+                    const blocked = markBlocked(current, decision.decision, decision.handoff.resumeCondition, input.now);
+                    saveUnitLedger(input.projectRoot, blocked);
+                }
+                return baseResult(input, "begin", {
+                    exitCode: EXIT_GATE_FAILED,
+                    decision: decision.decision,
+                    reason: decision.reason,
+                    activeAttemptIds: activeAttempts(current).map((a) => a.attemptId),
+                });
+            }
+            const { ledger, attempt } = beginAttempt(current, {
+                sourceRevision,
+                trigger,
+                status: "running",
+                workerId: input.workerId ?? null,
+                externalRunId: input.externalRunId ?? null,
+                now: input.now,
+                consumeOverride: decision.decision === "ALLOW_OVERRIDE",
+            });
+            saveUnitLedger(input.projectRoot, ledger);
+            return baseResult(input, "begin", {
+                exitCode: EXIT_OK,
+                decision: decision.decision,
+                reason: `allowed; attempt ${attempt.attemptId} begun`,
+                attempt,
+                activeAttemptIds: [attempt.attemptId],
+            });
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const parsed = parseDecisionFromError(message);
+        if (parsed.decision !== null) {
+            return baseResult(input, "begin", {
+                exitCode: EXIT_GATE_FAILED,
+                decision: parsed.decision,
+                reason: parsed.reason,
+                activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+            });
+        }
+        return baseResult(input, "begin", {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: message,
+            activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+        });
+    }
+}
+function runComplete(input, action) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    const status = action === "cancel" ? "cancelled" : (input.status ?? "succeeded");
+    const ledger = loadUnitLedger(input.projectRoot, scopeId, targetId, workflowId);
+    if (ledger === null) {
+        return baseResult(input, action, {
+            exitCode: EXIT_GATE_FAILED,
+            decision: null,
+            reason: "no delivery-attempt ledger for unit",
+            activeAttemptIds: [],
+        });
+    }
+    const actives = activeAttempts(ledger);
+    if (actives.length === 0 && input.attemptId === undefined && input.externalRunId === undefined) {
+        return baseResult(input, action, {
+            exitCode: EXIT_GATE_FAILED,
+            decision: null,
+            reason: "no active attempt to complete/cancel",
+            activeAttemptIds: [],
+        });
+    }
+    try {
+        const next = completeAttemptOnDisk(input.projectRoot, {
+            scopeId,
+            targetId,
+            workflowId,
+            attemptId: input.attemptId,
+            externalRunId: input.externalRunId ?? null,
+            status,
+            now: input.now,
+        });
+        const closed = next.attempts.find((a) => a.attemptId === input.attemptId) ??
+            next.attempts.filter((a) => a.endedAt !== null).at(-1) ??
+            null;
+        return baseResult(input, action, {
+            exitCode: EXIT_OK,
+            decision: null,
+            reason: `attempt ${closed?.attemptId ?? "?"} marked ${status}`,
+            attempt: closed,
+            activeAttemptIds: activeAttempts(next).map((a) => a.attemptId),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: message,
+            activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+        });
+    }
+}
+/**
+ * Swarm pre-dispatch gate for implement leaves.
+ *
+ * - begin (default): evaluate #3143 gate; on allow, beginAttempt; exit 0 / 1 / 2
+ * - complete: terminal success/fail/blocked
+ * - cancel: terminal cancel (takeover step 1)
+ */
+export function swarmPreDispatch(input) {
+    const action = input.action ?? "begin";
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    if (scopeId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--scope-id is required (story/issue or xBRIEF plan id)",
+        });
+    }
+    if (targetId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--target-id is required (worktree path or branch)",
+        });
+    }
+    if (workflowId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--workflow-id must be non-empty",
+        });
+    }
+    if (!PRE_DISPATCH_ACTIONS.includes(action)) {
+        return baseResult(input, "begin", {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: `--action must be one of: ${PRE_DISPATCH_ACTIONS.join(", ")}`,
+        });
+    }
+    if (action === "complete" &&
+        input.status !== undefined &&
+        !COMPLETE_STATUSES.includes(input.status)) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: `--status must be one of: ${COMPLETE_STATUSES.join(", ")}`,
+        });
+    }
+    if (action === "begin")
+        return runBegin(input);
+    return runComplete(input, action);
+}
+/** Human-readable one-line report for CLI stdout. */
+export function formatPreDispatchReport(result) {
+    const unit = `${result.scopeId} / ${result.targetId} / ${result.workflowId}`;
+    const decision = result.decision !== null ? result.decision : "n/a";
+    const active = result.activeAttemptIds.length > 0 ? result.activeAttemptIds.join(",") : "(none)";
+    const lines = [
+        `[swarm:pre-dispatch] action=${result.action} exit=${result.exitCode}`,
+        `  unit: ${unit}`,
+        `  decision: ${decision}`,
+        `  reason: ${result.reason}`,
+        `  active: ${active}`,
+    ];
+    if (result.attempt !== null) {
+        lines.push(`  attempt: ${result.attempt.attemptId} status=${result.attempt.status}`);
+    }
+    if (result.exitCode === EXIT_GATE_FAILED && result.decision === "DENY_DUPLICATE_ACTIVE") {
+        lines.push("  hint: do not spawn; resume the live leaf, or takeover = cancel then pre-dispatch begin");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=pre-dispatch.js.map

package/dist/vbrief-activate/activate.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unli
 import { basename, dirname, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { evaluateEffortActivateGate } from "../scope/effort-activate-gate.js";
 import { utcNowIso } from "../scope/vbrief-json.js";
 import { pythonJsonPretty } from "../vbrief-build/json.js";
 import { ACTIVE_FOLDER, ELIGIBLE_STATUSES_FOR_FLIP, formatEligibleStatusList, SOURCE_FOLDERS, TARGET_STATUS, } from "./constants.js";
@@ -121,6 +122,11 @@ export function activate(vbriefPath, options = {}) {
                 `'${TARGET_STATUS}'.`,
         };
     }
+    // #1581: fail closed when any plan item still has effort=XL (needs breakdown).
+    const effortGate = evaluateEffortActivateGate(planObj);
+    if (!effortGate.ok) {
+        return { exitCode: 1, message: effortGate.message };
+    }
     // Resolve destination early so containment can refuse before any mutation.
     // Parity with scope:activate / #2447: projectRoot is parent of the xbrief/ root.
     const vbriefDir = dirname(dirname(vbriefPath));

package/dist/vbrief-validate/constants.d.ts

@@ -9,6 +9,8 @@ export declare const VALID_VBRIEF_VERSIONS: Set<string>;
 export declare const VALID_INFO_ROOT_KEYS: Set<string>;
 /** v0.8 PlanItem.type enum values (optional field). */
 export declare const VALID_PLAN_ITEM_TYPES: Set<string>;
+/** Optional PlanItem.effort enum (#1581). Time anchors: S <2h, M 2-4h, L 1-2d, XL needs breakdown. */
+export declare const VALID_PLAN_ITEM_EFFORTS: Set<string>;
 /** D13: status-to-folder mapping (#533 adds ``failed`` in completed/). */
 export declare const FOLDER_ALLOWED_STATUSES: Readonly<Record<string, ReadonlySet<string>>>;
 export declare const LIFECYCLE_FOLDERS: string[];

package/dist/vbrief-validate/constants.js

@@ -19,6 +19,8 @@ export const VALID_VBRIEF_VERSIONS = new Set(["0.6", "0.8"]);
 export const VALID_INFO_ROOT_KEYS = new Set(["vBRIEFInfo", "xBRIEFInfo"]);
 /** v0.8 PlanItem.type enum values (optional field). */
 export const VALID_PLAN_ITEM_TYPES = new Set(["task", "group", "milestone", "epic"]);
+/** Optional PlanItem.effort enum (#1581). Time anchors: S <2h, M 2-4h, L 1-2d, XL needs breakdown. */
+export const VALID_PLAN_ITEM_EFFORTS = new Set(["S", "M", "L", "XL"]);
 /** D13: status-to-folder mapping (#533 adds ``failed`` in completed/). */
 export const FOLDER_ALLOWED_STATUSES = {
     proposed: new Set(["draft", "proposed"]),

package/dist/vbrief-validate/schema.js

@@ -1,5 +1,5 @@
 import { pyStrRepr, pythonTypeName } from "../triage/scope/python-repr.js";
-import { PROJECT_DEF_EXPECTED_NARRATIVES, VALID_INFO_ROOT_KEYS, VALID_ITEM_STATUSES, VALID_PLAN_ITEM_TYPES, VALID_PLAN_STATUSES, VALID_VBRIEF_VERSIONS, } from "./constants.js";
+import { PROJECT_DEF_EXPECTED_NARRATIVES, VALID_INFO_ROOT_KEYS, VALID_ITEM_STATUSES, VALID_PLAN_ITEM_EFFORTS, VALID_PLAN_ITEM_TYPES, VALID_PLAN_STATUSES, VALID_VBRIEF_VERSIONS, } from "./constants.js";
 function validateNarratives(narratives, path, errors) {
     if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
         errors.push(`${path} must be an object`);
@@ -50,6 +50,9 @@ function validatePlanItem(item, path, errors) {
     if ("type" in item && !VALID_PLAN_ITEM_TYPES.has(String(item.type))) {
         errors.push(`${itemPath} invalid type: ${pyStrRepr(String(item.type))}`);
     }
+    if ("effort" in item && !VALID_PLAN_ITEM_EFFORTS.has(String(item.effort))) {
+        errors.push(`${itemPath} invalid effort: ${pyStrRepr(String(item.effort))}`);
+    }
     if ("summary" in item && typeof item.summary !== "string") {
         errors.push(`${itemPath}.summary must be a string, got ${pythonTypeName(item.summary)}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -131,6 +131,14 @@
       "types": "./dist/value/readback.d.ts",
       "default": "./dist/value/readback.js"
     },
+    "./decision": {
+      "types": "./dist/decision/index.d.ts",
+      "default": "./dist/decision/index.js"
+    },
+    "./decision/index": {
+      "types": "./dist/decision/index.d.ts",
+      "default": "./dist/decision/index.js"
+    },
     "./events": {
       "types": "./dist/events/attribution-ledger.d.ts",
       "default": "./dist/events/attribution-ledger.js"
@@ -147,6 +155,10 @@
       "types": "./dist/eval/report.d.ts",
       "default": "./dist/eval/report.js"
     },
+    "./eval/version-pin": {
+      "types": "./dist/eval/version-pin.d.ts",
+      "default": "./dist/eval/version-pin.js"
+    },
     "./triage": {
       "types": "./dist/triage/index.d.ts",
       "default": "./dist/triage/index.js"
@@ -354,8 +366,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.98.0",
-    "@deftai/directive-types": "^0.98.0",
+    "@deftai/directive-content": "^0.99.0",
+    "@deftai/directive-types": "^0.99.0",
     "archiver": "^8.0.0"
   },
   "scripts": {