@deftai/directive-core 0.104.0 → 0.106.0

package/dist/swarm/complete-cohort.js

@@ -1,11 +1,13 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } 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 { readOccupancy, releaseSwarmOccupancy } from "../session/occupancy.js";
 import { MAX_FIXPOINT_PASSES, TERMINAL_FOLDERS } from "./constants.js";
+import { resolveLaunchOccupancySessionId } from "./launch.js";
 function loadPlan(path) {
     try {
         const data = JSON.parse(readFileSync(path, "utf8"));
@@ -21,6 +23,14 @@ function loadPlan(path) {
         return null;
     }
 }
+function storyIdFromPath(path) {
+    const plan = loadPlan(path);
+    const id = plan !== null && typeof plan.id === "string" ? plan.id.trim() : "";
+    if (id.length > 0)
+        return id;
+    const name = basename(path);
+    return hasArtifactSuffix(name) ? stripArtifactSuffix(name) : name.replace(/\.[^.]+$/, "");
+}
 function rel(path, projectRoot) {
     try {
         return resolve(path)
@@ -226,6 +236,7 @@ function completeParent(args) {
     }
     let current = parentPath;
     let action = "complete";
+    let activateNotice = "";
     if (folder === "pending") {
         action = "activate+complete";
         const activateResult = runTransition("activate", current);
@@ -238,18 +249,22 @@ function completeParent(args) {
                 detail: `activate failed: ${activateResult.message}`,
             };
         }
+        activateNotice = activateResult.message.trim();
         current = join(vbriefDir, "active", parentPath.split(/[/\\]/).pop() ?? "");
     }
     const completeResult = runTransition("complete", current, new Date(), transitionOptionsFor(current, delivery));
     if (completeResult.ok) {
         settled.add(resolve(join(vbriefDir, "completed", parentPath.split(/[/\\]/).pop() ?? "")));
     }
+    const detail = activateNotice.length > 0
+        ? `${activateNotice}\n${completeResult.message}`
+        : completeResult.message;
     return {
         kind: "epic",
         path: relpath,
         action: completeResult.ok ? action : "failed",
         ok: completeResult.ok,
-        detail: completeResult.message,
+        detail,
     };
 }
 export function sweepCohort(storyPaths, projectRoot, dryRun, delivery) {
@@ -412,6 +427,7 @@ export function completeCohort(args) {
             exitCode: 2,
             stdout: "",
             stderr: `Error: project root does not exist: ${projectRoot}\n`,
+            sweep: null,
         };
     }
     if (!existsSync(resolveLifecycleRoot(projectRoot))) {
@@ -419,31 +435,33 @@ export function completeCohort(args) {
             exitCode: 2,
             stdout: "",
             stderr: `Error: no vbrief/ directory under project root: ${projectRoot}\n`,
+            sweep: null,
         };
     }
     const { paths, errors } = resolveCohortPaths(args.stories ?? [], args.cohortGlobs ?? [], projectRoot);
     if (paths.length === 0) {
         const msg = "Error: empty cohort. Pass one or more story vBRIEF paths as positional arguments and/or --cohort <glob>.";
+        const empty = {
+            project_root: projectRoot,
+            dry_run: args.dryRun ?? false,
+            stories: [],
+            parents: [],
+            errors: errors.length > 0 ? errors : [msg],
+            ok: false,
+        };
         if (args.emitJson) {
-            const empty = {
-                project_root: projectRoot,
-                dry_run: args.dryRun ?? false,
-                stories: [],
-                parents: [],
-                errors: errors.length > 0 ? errors : [msg],
-                ok: false,
-            };
             return {
                 exitCode: 2,
                 stdout: `${JSON.stringify(sweepResultToDict(empty), null, 2)}\n`,
                 stderr: "",
+                sweep: empty,
             };
         }
         let stderr = `${msg}\n`;
         for (const err of errors) {
             stderr += `  - ${err}\n`;
         }
-        return { exitCode: 2, stdout: "", stderr };
+        return { exitCode: 2, stdout: "", stderr, sweep: empty };
     }
     const result = sweepCohortWithArgs({
         storyPaths: paths,
@@ -452,17 +470,47 @@ export function completeCohort(args) {
         delivery: args.delivery ?? null,
     });
     result.errors.push(...errors);
+    if (result.ok && args.dryRun !== true) {
+        const envSession = process.env.DEFT_SESSION_ID?.trim() ?? "";
+        let sessionId = envSession;
+        if (sessionId.length === 0) {
+            const resolved = resolveLaunchOccupancySessionId(projectRoot, {
+                allocationPlanId: args.allocationPlanId ?? null,
+                storyIds: paths.map(storyIdFromPath),
+            });
+            if (resolved.reason === "ok" && resolved.sessionId.length > 0) {
+                sessionId = resolved.sessionId;
+            }
+            else if (readOccupancy(projectRoot) !== null) {
+                result.ok = false;
+                result.errors.push("swarm close-out occupancy record is missing or belongs to a different cohort. " +
+                    "Steal with occupancy:steal --confirm --occupant <id>.");
+            }
+        }
+        if (result.ok && sessionId.length > 0) {
+            const released = releaseSwarmOccupancy(projectRoot, {
+                env: process.env,
+                sessionId,
+            });
+            if (released.code !== 0) {
+                result.ok = false;
+                result.errors.push(released.message);
+            }
+        }
+    }
     if (args.emitJson) {
         return {
             exitCode: result.ok ? 0 : 1,
             stdout: `${JSON.stringify(sweepResultToDict(result), null, 2)}\n`,
             stderr: "",
+            sweep: result,
         };
     }
     return {
         exitCode: result.ok ? 0 : 1,
         stdout: `${renderSweepText(result)}\n`,
         stderr: "",
+        sweep: result,
     };
 }
 //# sourceMappingURL=complete-cohort.js.map

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

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

@@ -1,67 +1,181 @@
 #!/usr/bin/env node
 import { fileURLToPath } from "node:url";
+import { EXIT_CONFIG_ERROR, EXIT_OK } from "./constants.js";
 import { finalizeCohort } from "./finalize-cohort.js";
+export const FINALIZE_COHORT_USAGE = `Usage: task swarm:finalize-cohort -- [--pr <n>[,<n>...]] [--stories <ids|paths>] [options]
+
+After cohort PRs merge, sweep story briefs active/ -> completed/ and open the lifecycle PR.
+
+Options:
+  --pr <n>[,<n>...]            Merged PR numbers (closing issues map to active stories)
+  --stories <ids|paths>        Explicit story tokens (repeatable)
+  --repo OWNER/REPO            GitHub repo (or $GH_REPO)
+  --project-root <path>        Project root (default: cwd)
+  --base-branch <name>         Sweep/PR base (default: resolved delivery branch)
+  --delivery-branch <name>     Delivery-branch override when policy is untyped
+  --label <name>               Feature-branch label
+  --dry-run                    Print plan; no git mutation
+  --no-commit                  Sweep without committing / opening a PR
+  --no-open-pr                 Commit without opening a PR
+  --json                       Machine-readable result
+  -h, --help                   Show this help
+`;
+function equalsValue(arg, flag) {
+    return arg.slice(flag.length + 1);
+}
+function parsePrList(raw, flag, prNumbers, reject) {
+    if (raw.trim().length === 0) {
+        reject(flag);
+        return;
+    }
+    for (const piece of raw.split(",")) {
+        const trimmed = piece.trim();
+        if (trimmed.length === 0) {
+            reject(flag);
+            return;
+        }
+        if (!/^\d+$/.test(trimmed)) {
+            reject(flag);
+            return;
+        }
+        prNumbers.push(Number.parseInt(trimmed, 10));
+    }
+}
 export function parseFinalizeCohortArgv(argv) {
     const prNumbers = [];
     const storyTokens = [];
     let repo = null;
     let projectRoot = ".";
-    let baseBranch = "master";
+    let baseBranch;
     let deliveryBranch = null;
     let label = null;
     let dryRun = false;
     let noCommit = false;
     let noOpenPr = false;
     let emitJson = false;
+    let help = false;
+    let error = null;
+    const reject = (arg) => {
+        error ??= `unrecognized argument: ${arg}`;
+    };
+    const takeValue = (flag, nextValue) => {
+        if (nextValue === undefined || nextValue.startsWith("-")) {
+            reject(flag);
+            return null;
+        }
+        return nextValue;
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         const next = argv[i + 1];
-        if (arg === "--pr" && next !== undefined) {
-            for (const piece of next.split(",")) {
-                const trimmed = piece.trim();
-                if (/^\d+$/.test(trimmed)) {
-                    prNumbers.push(Number.parseInt(trimmed, 10));
-                }
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--pr") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                parsePrList(value, arg, prNumbers, reject);
+                i += 1;
             }
-            i += 1;
         }
         else if (arg?.startsWith("--pr=")) {
-            for (const piece of arg.slice("--pr=".length).split(",")) {
-                const trimmed = piece.trim();
-                if (/^\d+$/.test(trimmed)) {
-                    prNumbers.push(Number.parseInt(trimmed, 10));
-                }
+            parsePrList(equalsValue(arg, "--pr"), arg, prNumbers, reject);
+        }
+        else if (arg === "--stories") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                storyTokens.push(value);
+                i += 1;
             }
         }
-        else if (arg === "--stories" && next !== undefined) {
-            storyTokens.push(next);
-            i += 1;
+        else if (arg?.startsWith("--stories=")) {
+            const value = equalsValue(arg, "--stories");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                storyTokens.push(value);
+            }
         }
-        else if (arg === "--repo" && next !== undefined) {
-            repo = next;
-            i += 1;
+        else if (arg === "--repo") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                repo = value;
+                i += 1;
+            }
         }
         else if (arg?.startsWith("--repo=")) {
-            repo = arg.slice("--repo=".length);
+            const value = equalsValue(arg, "--repo");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                repo = value;
+            }
+        }
+        else if (arg === "--project-root") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                projectRoot = value;
+                i += 1;
+            }
         }
-        else if (arg === "--project-root" && next !== undefined) {
-            projectRoot = next;
-            i += 1;
+        else if (arg?.startsWith("--project-root=")) {
+            const value = equalsValue(arg, "--project-root");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                projectRoot = value;
+            }
         }
-        else if (arg === "--base-branch" && next !== undefined) {
-            baseBranch = next;
-            i += 1;
+        else if (arg === "--base-branch") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                baseBranch = value;
+                i += 1;
+            }
         }
-        else if (arg === "--delivery-branch" && next !== undefined) {
-            deliveryBranch = next;
-            i += 1;
+        else if (arg?.startsWith("--base-branch=")) {
+            const value = equalsValue(arg, "--base-branch");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                baseBranch = value;
+            }
+        }
+        else if (arg === "--delivery-branch") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                deliveryBranch = value;
+                i += 1;
+            }
         }
         else if (arg?.startsWith("--delivery-branch=")) {
-            deliveryBranch = arg.slice("--delivery-branch=".length);
+            const value = equalsValue(arg, "--delivery-branch");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                deliveryBranch = value;
+            }
+        }
+        else if (arg === "--label") {
+            const value = takeValue(arg, next);
+            if (value !== null) {
+                label = value;
+                i += 1;
+            }
         }
-        else if (arg === "--label" && next !== undefined) {
-            label = next;
-            i += 1;
+        else if (arg?.startsWith("--label=")) {
+            const value = equalsValue(arg, "--label");
+            if (value.length === 0) {
+                reject(arg);
+            }
+            else {
+                label = value;
+            }
         }
         else if (arg === "--dry-run") {
             dryRun = true;
@@ -78,23 +192,37 @@ export function parseFinalizeCohortArgv(argv) {
         else if (arg !== undefined && !arg.startsWith("-")) {
             storyTokens.push(arg);
         }
+        else if (arg !== undefined) {
+            reject(arg);
+        }
     }
     return {
         prNumbers,
         storyTokens,
         repo,
         projectRoot,
-        baseBranch,
+        ...(baseBranch !== undefined ? { baseBranch } : {}),
         deliveryBranch,
         label,
         dryRun,
         noCommit,
         noOpenPr,
         emitJson,
+        help,
+        error,
     };
 }
 export function finalizeCohortMain(argv = process.argv.slice(2)) {
-    const result = finalizeCohort(parseFinalizeCohortArgv(argv));
+    const parsed = parseFinalizeCohortArgv(argv);
+    if (parsed.help) {
+        process.stdout.write(FINALIZE_COHORT_USAGE);
+        return EXIT_OK;
+    }
+    if (parsed.error !== null) {
+        process.stderr.write(`${parsed.error}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const result = finalizeCohort(parsed);
     if (result.stdout.length > 0) {
         process.stdout.write(result.stdout);
     }
@@ -103,7 +231,9 @@ export function finalizeCohortMain(argv = process.argv.slice(2)) {
     }
     return result.exitCode;
 }
+/* v8 ignore start -- entry guard */
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(finalizeCohortMain());
 }
+/* v8 ignore stop */
 //# sourceMappingURL=finalize-cohort-cli.js.map

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

@@ -13,6 +13,7 @@ export interface FinalizeCohortResult {
     readonly branch: string | null;
     readonly pr_url: string | null;
     readonly delivery_branch: string | null;
+    readonly sweep_base: string;
     readonly delivery_errors: readonly string[];
     readonly errors: readonly string[];
     readonly warnings: readonly string[];

package/dist/swarm/finalize-cohort.js

@@ -51,6 +51,18 @@ function safeSegment(text) {
 function oneLine(text) {
     return text.replace(/\r?\n/g, " ");
 }
+/** Existing sweep records already carry refused-stamp remediations (#3398). */
+function sweepDetailLines(sweep) {
+    const lines = [];
+    for (const rec of [...sweep.stories, ...sweep.parents]) {
+        const detail = rec.detail.trim();
+        if (detail.length > 0) {
+            lines.push(`${rec.path}: ${detail}`);
+        }
+    }
+    lines.push(...sweep.errors);
+    return lines;
+}
 function parseRepo(repo) {
     const slash = repo.indexOf("/");
     if (slash <= 0 || slash >= repo.length - 1) {
@@ -315,8 +327,6 @@ export function finalizeCohort(args) {
     const prNumbers = [...(args.prNumbers ?? [])].sort((a, b) => a - b);
     const storyTokens = splitCsv(args.storyTokens ?? []);
     const repo = args.repo ?? process.env.GH_REPO ?? null;
-    // baseBranch is for the lifecycle sweep PR only — not delivery proof (#3041).
-    const baseBranch = args.baseBranch ?? "master";
     const dryRun = args.dryRun ?? false;
     const noCommit = args.noCommit ?? false;
     const noOpenPr = args.noOpenPr ?? false;
@@ -339,6 +349,12 @@ export function finalizeCohort(args) {
     const deliveryBranch = policyDelivery.source === "typed"
         ? policyDelivery.branch
         : (cliDelivery ?? policyDelivery.branch);
+    // Sweep/PR base is distinct from delivery proof (#3041). Default via the resolved
+    // delivery branch — never a hardcoded "master". --base-branch remains the override.
+    const explicitSweepBase = args.baseBranch !== undefined && args.baseBranch !== null && args.baseBranch.trim().length > 0
+        ? args.baseBranch.trim()
+        : null;
+    const baseBranch = explicitSweepBase ?? deliveryBranch;
     if (!existsSync(projectRoot)) {
         return buildResponse({
             projectRoot,
@@ -352,6 +368,7 @@ export function finalizeCohort(args) {
             branch: null,
             prUrl: null,
             deliveryBranch,
+            sweepBase: baseBranch,
             deliveryErrors: [],
             errors: [`project root does not exist: ${projectRoot}`],
             warnings: [],
@@ -373,6 +390,7 @@ export function finalizeCohort(args) {
             branch: null,
             prUrl: null,
             deliveryBranch,
+            sweepBase: baseBranch,
             deliveryErrors: [],
             errors: [`no xbrief/ directory under project root: ${projectRoot}`],
             warnings: [],
@@ -534,6 +552,7 @@ export function finalizeCohort(args) {
             branch: null,
             prUrl: null,
             deliveryBranch,
+            sweepBase: baseBranch,
             deliveryErrors,
             errors,
             warnings,
@@ -560,6 +579,7 @@ export function finalizeCohort(args) {
             branch: null,
             prUrl: null,
             deliveryBranch,
+            sweepBase: baseBranch,
             deliveryErrors,
             errors,
             warnings,
@@ -640,8 +660,15 @@ export function finalizeCohort(args) {
             }
             : null,
     });
+    const sweep = sweepResult.sweep;
     if (sweepResult.exitCode !== 0) {
         errors.push("cohort completion sweep failed.");
+        if (sweep !== null) {
+            errors.push(...sweepDetailLines(sweep));
+        }
+        else if (sweepResult.stdout.trim().length > 0) {
+            errors.push(sweepResult.stdout.trim());
+        }
         return buildResponse({
             projectRoot,
             dryRun,
@@ -649,11 +676,12 @@ export function finalizeCohort(args) {
             prNumbers,
             storyPaths,
             closingIssues: [...closingIssues],
-            sweep: null,
+            sweep,
             commitSha: null,
             branch: null,
             prUrl: null,
             deliveryBranch,
+            sweepBase: baseBranch,
             deliveryErrors,
             errors,
             warnings,
@@ -688,11 +716,12 @@ export function finalizeCohort(args) {
         prNumbers,
         storyPaths,
         closingIssues: [...closingIssues],
-        sweep: null,
+        sweep,
         commitSha,
         branch,
         prUrl,
         deliveryBranch,
+        sweepBase: baseBranch,
         deliveryErrors,
         errors,
         warnings,
@@ -714,6 +743,7 @@ function buildResponse(input) {
         branch: input.branch,
         pr_url: input.prUrl,
         delivery_branch: input.deliveryBranch,
+        sweep_base: input.sweepBase,
         delivery_errors: input.deliveryErrors,
         errors: input.errors,
         warnings: input.warnings,
@@ -735,6 +765,7 @@ function buildResponse(input) {
     if (input.deliveryBranch !== null) {
         lines.push(`  Delivery branch: ${input.deliveryBranch}`);
     }
+    lines.push(`  Sweep base: ${input.sweepBase}`);
     if (input.prNumbers.length > 0) {
         lines.push(`  PRs: ${input.prNumbers.map((n) => `#${n}`).join(", ")}`);
     }
@@ -747,6 +778,18 @@ function buildResponse(input) {
             lines.push(`    - ${oneLine(path)}`);
         }
     }
+    if (input.sweep !== null) {
+        const records = [...input.sweep.stories, ...input.sweep.parents];
+        if (records.length > 0 || input.sweep.errors.length > 0) {
+            lines.push("  Sweep:");
+            for (const rec of records) {
+                lines.push(`    [${rec.ok ? "ok" : "FAILED"}] ${rec.action} ${rec.path} -- ${oneLine(rec.detail)}`);
+            }
+            for (const err of input.sweep.errors) {
+                lines.push(`    - ${oneLine(err)}`);
+            }
+        }
+    }
     if (input.branch !== null) {
         lines.push(`  Branch: ${input.branch}`);
     }

package/dist/swarm/launch.d.ts

@@ -37,6 +37,27 @@ export declare function enforceGates(resolved: readonly ResolvedStory[], project
     story: ResolvedStory;
     reason: string;
 } | null;
+export declare const SWARM_LAUNCH_MANIFEST_RELPATH: readonly [".deft", "swarm-launch-manifest.json"];
+export declare const SWARM_LAUNCH_OCCUPANCY_DIR: readonly [".deft", "swarm-launch-occupancy"];
+export declare function swarmLaunchManifestPath(projectRoot: string): string;
+export interface LaunchOccupancyRecord {
+    readonly allocation_plan_id: string | null;
+    readonly occupancy_session_id: string;
+    readonly story_ids: readonly string[];
+    readonly cohort_key: string;
+}
+export interface LaunchOccupancyQuery {
+    readonly allocationPlanId?: string | null;
+    readonly storyIds?: readonly string[];
+}
+export type LaunchOccupancyLookupReason = "ok" | "missing" | "wrong-cohort";
+export declare function occupancyCohortKey(allocationPlanId: string | null | undefined, storyIds?: readonly string[]): string;
+export declare function launchOccupancyRecordRelpath(cohortKey: string): string[];
+export declare function persistLaunchOccupancyRecord(projectRoot: string, record: LaunchOccupancyRecord): void;
+export declare function resolveLaunchOccupancySessionId(projectRoot: string, query?: LaunchOccupancyQuery): {
+    sessionId: string;
+    reason: LaunchOccupancyLookupReason;
+};
 export declare function buildManifest(resolved: readonly ResolvedStory[], options: {
     projectRoot: string;
     group?: string | null;
@@ -53,6 +74,7 @@ export declare function buildManifest(resolved: readonly ResolvedStory[], option
     modelSource?: string | null;
     runtimeMode?: string | null;
     githubAuthMode?: string | null;
+    occupancySessionId?: string | null;
 }): Record<string, unknown>[];
 export declare function orderCohort(resolved: readonly ResolvedStory[], _projectRoot: string): ResolvedStory[];
 export interface LaunchArgs {