@deftai/directive-runtime 0.129.6 → 0.129.8

package/vendor/directive-core/dist/swarm/finalize-cohort.js

@@ -12,13 +12,36 @@ import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { ENV_ALLOW_BOT_MERGE, evaluateAgentMerge, resolveHumanMergePolicy, } from "../policy/require-human-merge.js";
 import { parseAllDeftStoryMarks } from "../pr-closing-keywords/main.js";
 import { defaultRunGh, fetchClosingIssuesReferences } from "../pr-protected-issues/gh.js";
-import { classifyStoredDeliveryDisposition, evidenceFromPrPayload, verifyDeliveryAncestry, } from "../scope/delivery-evidence.js";
+import { classifyStoredDeliveryDisposition, defaultFetchPrChangedFiles, evidenceFromPrPayload, isDeliveryBriefLandPath, SPEC_DRIFT_LEDGER_REL, verifyDeliveryAncestry, } from "../scope/delivery-evidence.js";
 import { materializeRetainedBrief, SOURCE_RECOVERY_REMEDIATION } from "./brief-transport.js";
 import { completeCohort } from "./complete-cohort.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_INCOMPLETE, EXIT_OK } from "./constants.js";
 import { cancelledBriefReferencesIssue, completedBriefReferencesIssue, resolveStories, terminalBriefReferencesIssue, } from "./launch.js";
 import { evaluateLifecycleDiff, expectedLifecycleRels, parseStagedXbriefPaths, } from "./lifecycle-diff.js";
 import { runText } from "./subprocess.js";
+import { detectWorktreePm, installWorktreePackages, worktreeHasRuntimePin, } from "./worktree-pm-install.js";
+/**
+ * Install packages on the lifecycle checkout before the completion sweep (#5882).
+ * Gated by the runtime pin, as linked-worktree prep gates it. npm/pnpm failure is
+ * `failed`; Yarn/Bun is diagnosed-only (`skipped-unsupported-pm`).
+ */
+export function installLifecycleCheckoutPackages(checkout, runner) {
+    if (!worktreeHasRuntimePin(checkout)) {
+        return { kind: "not-pinned" };
+    }
+    if (detectWorktreePm(checkout) === null) {
+        return { kind: "skipped-unsupported-pm" };
+    }
+    const installed = installWorktreePackages(checkout, { runner });
+    if (!installed.ok) {
+        return { kind: "failed", pm: installed.pm, message: installed.message };
+    }
+    return { kind: "installed", pm: installed.pm };
+}
+export function formatLifecycleInstallDisposition(disposition) {
+    const pm = "pm" in disposition && disposition.pm !== null ? ` pm=${disposition.pm}` : "";
+    return `lifecycle install disposition=${disposition.kind}${pm}`;
+}
 function splitCsv(values) {
     const out = [];
     for (const value of values) {
@@ -342,9 +365,13 @@ function collectProductPullRequestOrigins(projectRoot, prNumbers) {
 /**
  * PR-body `deft-story: N` may bind only when this PR is delivery for N (#4864 / #4919):
  * TIP_NONTERMINAL or completed brief for N with metadata.productPullRequest === this PR.
- * Absent stamp never binds (unrelated completed issue must not close).
+ * Absent stamp never binds on its own (unrelated completed issue must not close).
+ * Also reports a stamp naming another PR and whether an unstamped active brief
+ * exists, for the operator-story bind at the call site (#6212).
  */
 function deftStoryMarkBindsDelivery(projectRoot, issue, prNumber) {
+    let otherPr = null;
+    let unstampedActive = false;
     for (const folder of MARK_READER_FOLDERS) {
         const dir = resolve(projectRoot, folder);
         if (!existsSync(dir)) {
@@ -367,8 +394,15 @@ function deftStoryMarkBindsDelivery(projectRoot, issue, prNumber) {
                 if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
                     continue;
                 }
-                if (productPullRequestFromPlan(plan) === prNumber) {
-                    return true;
+                const stamped = productPullRequestFromPlan(plan);
+                if (stamped === prNumber) {
+                    return { stampMatch: true, otherPr: null, unstampedActive: false };
+                }
+                if (stamped !== null) {
+                    otherPr ??= stamped;
+                }
+                else if (folder.endsWith("/active")) {
+                    unstampedActive = true;
                 }
             }
             catch {
@@ -376,7 +410,16 @@ function deftStoryMarkBindsDelivery(projectRoot, issue, prNumber) {
             }
         }
     }
-    return false;
+    return { stampMatch: false, otherPr, unstampedActive };
+}
+/**
+ * Lifecycle-shaped PR (#6212): every changed path is in the delivery-brief-land
+ * family (`isDeliveryBriefLandPath`, shared with the delivery gate, #680 F1).
+ * Activation and lifecycle PRs carry `deft-story` marks too, so they never bind
+ * as delivery. An empty list stays lifecycle-shaped, so it never binds either.
+ */
+export function isLifecycleShapedPr(files) {
+    return files.every((f) => isDeliveryBriefLandPath(f.filename));
 }
 /**
  * Persist productPullRequest on an active brief before leftover-complete so the
@@ -760,6 +803,11 @@ function derivedLifecycleRelsFromSweep(projectRoot, storyPaths, sweep) {
         out.push(posixProjectRel(projectRoot, resolvedPath));
     };
     if (sweep !== null) {
+        // scope:complete writes the spec-drift ledger as verb output; it travels in
+        // the same lifecycle commit as the completed briefs (#680 P5 / #6231).
+        if (sweep.stories.some((rec) => rec.ok)) {
+            out.push(SPEC_DRIFT_LEDGER_REL);
+        }
         for (const rec of [...sweep.stories, ...sweep.parents]) {
             if (!rec.ok || rec.path.trim().length === 0) {
                 continue;
@@ -1167,6 +1215,8 @@ function waitForLifecycleLand(args) {
 export function finalizeCohort(args) {
     const projectRoot = resolve(args.projectRoot ?? process.cwd());
     const runGh = args.runGh ?? defaultRunGh;
+    const fetchPrChangedFiles = args.fetchPrChangedFiles ??
+        ((prNumber, repository) => defaultFetchPrChangedFiles(prNumber, repository, runGh));
     const runGit = args.runGit ?? runText;
     const gitRunner = asGitRunner(runGit);
     const prNumbers = [...(args.prNumbers ?? [])].sort((a, b) => a - b);
@@ -1356,7 +1406,17 @@ export function finalizeCohort(args) {
     const validatedPrs = [];
     /** Full-story close intent from PR-body `deft-story: N` (#4864). Not Tracking/Refs scrape. */
     const fullStoryCloseIssues = new Set();
+    /**
+     * A failed changed-file lookup for a mark is a real forge error: it still stops
+     * the stamp and sweep for the whole batch in every write mode (#6212).
+     */
+    let deftStoryMarkLookupFailed = false;
+    /** Refused marks: non-fatal; only that story stays pending (#680 P3). */
+    const refusedMarks = [];
     let closingLookupFailed = false;
+    // Operator --stories issues: their deft-story marks may bind before the sweep stamp (#6212).
+    const operatorResolved = storyTokens.length > 0 ? resolveStories(projectRoot, storyTokens) : null;
+    const operatorStoryIssues = new Set(collectOriginIssueNumbers(operatorResolved?.resolved.map((story) => story.path) ?? [], storyTokens));
     if (prNumbers.length > 0 && errors.length === 0) {
         if (repo === null || repo.length === 0) {
             errors.push("--repo OWNER/REPO is required when --pr is supplied (or set $GH_REPO).");
@@ -1408,11 +1468,47 @@ export function finalizeCohort(args) {
                     evidenceByIssue.set(issue, prEvidence);
                 }
                 const prBody = typeof snap.payload.body === "string" ? snap.payload.body : "";
+                let prFiles;
                 for (const issue of parseAllDeftStoryMarks(prBody)) {
-                    if (!deftStoryMarkBindsDelivery(projectRoot, issue, prNumber)) {
-                        errors.push(`#${String(issue)}: deft-story mark on PR #${String(prNumber)} does not bind PR delivery ` +
-                            `(need active or completed brief #${String(issue)} with ` +
-                            `metadata.productPullRequest=${String(prNumber)}) (#4864).`);
+                    const mark = deftStoryMarkBindsDelivery(projectRoot, issue, prNumber);
+                    let bound = mark.stampMatch;
+                    let lookupFailed = false;
+                    let reason = `need active or completed brief #${String(issue)} with ` +
+                        `metadata.productPullRequest=${String(prNumber)}`;
+                    // Operator named N in --stories (#6212): an unstamped active brief binds this
+                    // validated PR, and the sweep stamps it. A lifecycle-shaped PR never binds.
+                    if (!bound && operatorStoryIssues.has(issue)) {
+                        if (mark.otherPr !== null) {
+                            reason =
+                                `brief #${String(issue)} is already stamped ` +
+                                    `metadata.productPullRequest=${String(mark.otherPr)}`;
+                        }
+                        else if (mark.unstampedActive) {
+                            if (prFiles === undefined) {
+                                prFiles = fetchPrChangedFiles(prNumber, repo);
+                            }
+                            if (prFiles === null) {
+                                reason = `changed-file lookup for PR #${String(prNumber)} failed`;
+                                lookupFailed = true;
+                            }
+                            else if (isLifecycleShapedPr(prFiles)) {
+                                reason = `PR #${String(prNumber)} changes only lifecycle paths: briefs, CHANGELOG.md, spec-drift ledger`;
+                            }
+                            else {
+                                bound = true;
+                            }
+                        }
+                    }
+                    if (!bound) {
+                        const detail = `#${String(issue)}: deft-story mark on PR #${String(prNumber)} does not bind PR delivery ` +
+                            `(${reason}) (#4864).`;
+                        if (lookupFailed) {
+                            deftStoryMarkLookupFailed = true;
+                            errors.push(detail);
+                        }
+                        else {
+                            refusedMarks.push({ issue, pr: prNumber, detail });
+                        }
                         continue;
                     }
                     fullStoryCloseIssues.add(issue);
@@ -1432,7 +1528,10 @@ export function finalizeCohort(args) {
             evidenceByIssue.set(issue, bound);
         }
     }
-    if (storyTokens.length === 0 && closingIssues.size === 0 && fullStoryCloseIssues.size === 0) {
+    if (storyTokens.length === 0 &&
+        closingIssues.size === 0 &&
+        fullStoryCloseIssues.size === 0 &&
+        refusedMarks.length === 0) {
         errors.push("empty cohort: pass --pr <numbers> and/or --stories <ids|paths> " +
             "(or record full-story close intent via deft-story: N / productPullRequest).");
     }
@@ -1448,8 +1547,8 @@ export function finalizeCohort(args) {
     };
     // Operator-supplied story tokens keep the hard-error contract: an explicit
     // --stories token that does not resolve to an active brief is a real error.
-    if (storyTokens.length > 0) {
-        const resolved = resolveStories(projectRoot, storyTokens);
+    if (operatorResolved !== null) {
+        const resolved = operatorResolved;
         for (const story of resolved.resolved) {
             addStory(story.path);
         }
@@ -1550,9 +1649,32 @@ export function finalizeCohort(args) {
             errors.push(`#${issue}: full-story close intent recorded but no active or completed brief references this issue (#4864).`);
         }
     }
+    // Refused marks (#680 P3): an issue no other PR bound stays pending. Its story
+    // leaves the batch before stamp/sweep (#6212: never single-PR defaultEvidence),
+    // and its origin is never closed. The other stories go on.
+    // A stray mark with no brief for its issue warns only; it leaves nothing pending.
+    // Selected story paths count too, so a nested brief path is never missed.
+    const pendingMarkIssues = new Set(refusedMarks
+        .map((m) => m.issue)
+        .filter((issue) => !fullStoryCloseIssues.has(issue) &&
+        !closingIssues.has(issue) &&
+        (storyPaths.some((p) => githubIssueFromBrief(p) === issue) ||
+            localBriefReferencesIssue(projectRoot, issue))));
+    for (let i = storyPaths.length - 1; i >= 0; i -= 1) {
+        const origin = githubIssueFromBrief(storyPaths[i] ?? "");
+        if (origin !== null && pendingMarkIssues.has(origin)) {
+            storyPaths.splice(i, 1);
+        }
+    }
+    for (const mark of refusedMarks) {
+        warnings.push(pendingMarkIssues.has(mark.issue)
+            ? `${mark.detail} Story left pending, not stamped or swept (#680).`
+            : mark.detail);
+    }
+    const markPending = pendingMarkIssues.size > 0;
     const originIssues = collectOriginIssueNumbers(storyPaths, storyTokens, [
         ...fullStoryCloseIssues,
-    ]);
+    ]).filter((issue) => !pendingMarkIssues.has(issue));
     if (storyPaths.length === 0) {
         if (errors.length === 0 && originIssues.length > 0) {
             const originClose = closeOriginsAfterLeftoverComplete({
@@ -1571,7 +1693,7 @@ export function finalizeCohort(args) {
                 ? originClosePendingState(originClose.pendingIssues, deliveryBranch)
                 : null;
             const originFailed = errors.length > 0;
-            const originPending = !originFailed && pending !== null;
+            const originPending = !originFailed && (pending !== null || markPending);
             return buildResponse({
                 projectRoot,
                 dryRun,
@@ -1589,6 +1711,7 @@ export function finalizeCohort(args) {
                 errors,
                 warnings,
                 pending,
+                refusedMarks,
                 ok: !originFailed && !originPending,
                 emitJson: args.emitJson ?? false,
                 exitCode: originFailed ? EXIT_GATE_FAILED : originPending ? EXIT_INCOMPLETE : EXIT_OK,
@@ -1614,10 +1737,13 @@ export function finalizeCohort(args) {
             errors,
             warnings,
             pending: null,
-            ok: cleanNoop,
+            refusedMarks,
+            ok: cleanNoop && !markPending,
             emitJson: args.emitJson ?? false,
             exitCode: cleanNoop
-                ? EXIT_OK
+                ? markPending
+                    ? EXIT_INCOMPLETE
+                    : EXIT_OK
                 : errors.some((e) => e.includes("not merged") || e.includes("delivery"))
                     ? EXIT_GATE_FAILED
                     : EXIT_CONFIG_ERROR,
@@ -1642,6 +1768,7 @@ export function finalizeCohort(args) {
             errors,
             warnings,
             pending: null,
+            refusedMarks,
             ok: false,
             emitJson: args.emitJson ?? false,
             exitCode: EXIT_GATE_FAILED,
@@ -1705,6 +1832,7 @@ export function finalizeCohort(args) {
     let pendingOrigin = null;
     let createdSweepBranch = null;
     let lifecycle = null;
+    let lifecycleInstall = null;
     // Closure assignment is invisible to finally control flow, so a bare let stays null.
     const held = { outcome: null };
     const respond = (partial) => {
@@ -1721,6 +1849,7 @@ export function finalizeCohort(args) {
             errors,
             warnings,
             pending: partial.pending ?? null,
+            refusedMarks,
             emitJson: args.emitJson ?? false,
             ...partial,
         });
@@ -1768,11 +1897,32 @@ export function finalizeCohort(args) {
                             if (branchResult.branch === branchName) {
                                 createdSweepBranch = branchName;
                             }
+                            // Sweep is required: install packages so Taskfile includes that
+                            // resolve through node_modules exist on this checkout (#5882).
+                            lifecycleInstall = installLifecycleCheckoutPackages(prepared.checkout, args.pmRunner);
+                            if (lifecycleInstall.kind === "failed") {
+                                errors.push(`environment/setup: ${formatLifecycleInstallDisposition(lifecycleInstall)}: ` +
+                                    `${oneLine(lifecycleInstall.message)}. The completion sweep did not run; ` +
+                                    "this is not an acceptance commands-failed result. Fix the package install " +
+                                    `on origin/${deliveryBranch}, then re-run swarm:finalize-cohort.`);
+                                skipSweep = true;
+                            }
+                            else if (lifecycleInstall.kind === "skipped-unsupported-pm") {
+                                warnings.push(`${formatLifecycleInstallDisposition(lifecycleInstall)}: Yarn/Bun lifecycle ` +
+                                    "checkout was not installed (AC5.7). Taskfile includes that resolve through " +
+                                    "node_modules can be missing during the completion sweep.");
+                            }
                         }
                     }
                 }
             }
         }
+        // --no-commit skips the error stop above, but a mark whose lookup failed must
+        // never let the single-PR default evidence stamp that PR; a retry would then
+        // bind it (#6212). Refused marks already left the batch above (#680 P3).
+        if (!dryRun && deftStoryMarkLookupFailed) {
+            skipSweep = true;
+        }
         let sweep = null;
         if (!skipSweep) {
             // Stamp on the sweep root (checkout or project) so leftover-complete preserves bind (#4864).
@@ -1824,7 +1974,9 @@ export function finalizeCohort(args) {
             });
             sweep = sweepResult.sweep;
             if (sweepResult.exitCode !== 0) {
-                errors.push("cohort completion sweep failed.");
+                errors.push(lifecycleInstall === null
+                    ? "cohort completion sweep failed."
+                    : `cohort completion sweep failed (${formatLifecycleInstallDisposition(lifecycleInstall)}).`);
                 if (sweep !== null) {
                     errors.push(...sweepDetailLines(sweep));
                 }
@@ -1977,7 +2129,7 @@ export function finalizeCohort(args) {
             pendingOrigin = originClosePendingState(originIssues, deliveryBranch);
         }
         const failed = errors.length > 0;
-        const incomplete = !failed && pendingOrigin !== null;
+        const incomplete = !failed && (pendingOrigin !== null || markPending);
         return respond({
             sweep,
             commitSha,
@@ -2025,6 +2177,7 @@ function withReportedFailure(previous, error, emitJson) {
         errors: [...result.errors, error],
         warnings: [...result.warnings],
         pending: result.pending,
+        refusedMarks: result.refused_marks ?? [],
         ok: false,
         emitJson,
         exitCode: EXIT_GATE_FAILED,
@@ -2048,6 +2201,7 @@ function buildResponse(input) {
         errors: input.errors,
         warnings: input.warnings,
         pending: input.pending,
+        refused_marks: input.refusedMarks ?? [],
         ok: input.ok,
     };
     if (input.emitJson) {
@@ -2126,7 +2280,9 @@ function buildResponse(input) {
         ? `Result: FINALIZE CLEAN -- cohort briefs swept to completed/.${skipNote}`
         : input.pending !== null
             ? "Result: FINALIZE INCOMPLETE -- origin-close pending."
-            : "Result: FINALIZE INCOMPLETE -- see errors above.");
+            : input.errors.length === 0 && (input.refusedMarks ?? []).length > 0
+                ? "Result: FINALIZE INCOMPLETE -- refused deft-story mark(s); see warnings above."
+                : "Result: FINALIZE INCOMPLETE -- see errors above.");
     return {
         exitCode: input.exitCode,
         stdout: `${lines.join("\n")}\n`,