@deftai/directive-core 0.67.0 → 0.68.1

package/dist/render/project-render.js

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { deriveRegistryItemStatus, registryMetadataReferencesFromScope, } from "../vbrief-validate/registry-status.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { PROJECT_LIFECYCLE_FOLDERS, SKELETON_NARRATIVES } from "./constants.js";
@@ -188,109 +189,133 @@ export function createSkeleton(items, now, layout) {
  * (Mirrors ``scripts/project_render.render_project_definition``.)
  */
 export function renderProjectDefinition(vbriefDir, options = {}) {
-    const nowDate = options.now ?? new Date();
-    const now = nowDate.toISOString().replace(/\.\d{3}Z$/, "Z");
-    const layout = resolveProjectDefinitionLayout(vbriefDir);
-    const projectDefPath = join(vbriefDir, layout.filename);
-    const items = scanLifecycleFolders(vbriefDir);
-    const createdNew = !existsSync(projectDefPath);
-    let projectDef;
-    if (existsSync(projectDefPath)) {
+    // Serialise the whole read-modify-write of PROJECT-DEFINITION under the shared
+    // mutation lock so a concurrent policy/triage mutator cannot be clobbered by the
+    // materialised items/metadata write (or vice versa) (#1260).
+    return projectDefinitionMutationLock(resolve(vbriefDir, ".."), () => {
+        const nowDate = options.now ?? new Date();
+        const now = nowDate.toISOString().replace(/\.\d{3}Z$/, "Z");
+        const layout = resolveProjectDefinitionLayout(vbriefDir);
+        const projectDefPath = join(vbriefDir, layout.filename);
+        const items = scanLifecycleFolders(vbriefDir);
+        const createdNew = !existsSync(projectDefPath);
+        let projectDef;
+        if (existsSync(projectDefPath)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(projectDefPath, "utf8"));
+            }
+            catch (exc) {
+                return [false, `✗ Failed to read ${projectDefPath}: ${String(exc)}`];
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return [false, `✗ ${projectDefPath} top-level value is not a JSON object`];
+            }
+            projectDef = parsed;
+            const plan = (projectDef.plan ?? {});
+            plan.items = items;
+            if (typeof projectDef[layout.infoRootKey] !== "object" ||
+                projectDef[layout.infoRootKey] === null) {
+                projectDef[layout.infoRootKey] = {};
+            }
+            projectDef[layout.infoRootKey].updated = now;
+            const narratives = typeof plan.narratives === "object" &&
+                plan.narratives !== null &&
+                !Array.isArray(plan.narratives)
+                ? plan.narratives
+                : {};
+            const completedItems = items.filter((i) => i.status === "completed");
+            if (typeof plan.metadata !== "object" ||
+                plan.metadata === null ||
+                Array.isArray(plan.metadata)) {
+                plan.metadata = {};
+            }
+            const planMetadata = plan.metadata;
+            const review = parseStalenessReview(planMetadata);
+            const flags = computeStalenessFlags(narratives, completedItems, review);
+            planMetadata.staleness_flags = flags;
+            projectDef.plan = plan;
+        }
+        else {
+            projectDef = createSkeleton(items, now, layout);
+        }
+        mkdirSync(vbriefDir, { recursive: true });
+        // Atomic temp+rename write under the lock so external readers never observe
+        // a partially-written PROJECT-DEFINITION (#1260).
+        atomicWriteProjectDefinition(projectDefPath, projectDef);
+        const itemCount = items.length;
+        const planMeta = (projectDef.plan?.metadata ?? {});
+        const flagCount = Array.isArray(planMeta.staleness_flags) ? planMeta.staleness_flags.length : 0;
+        const action = createdNew ? "created" : "updated";
+        const parts = [`✓ ${layout.filename} ${action} (${itemCount} scope items)`];
+        if (flagCount > 0)
+            parts.push(`⚠ ${flagCount} staleness flag(s) -- agent review recommended`);
+        return [true, parts.join("\n")];
+    });
+}
+/**
+ * Mark current completed scopes as reviewed for PROJECT-DEFINITION narratives.
+ *
+ * Distinct from `task reconcile:issues`, which reconciles origin freshness on scope
+ * vBRIEFs — this path only clears narrative staleness heuristics on render.
+ */
+export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
+    // Serialise the read-modify-write of PROJECT-DEFINITION under the shared
+    // mutation lock so a concurrent policy/triage mutator is not clobbered (#1260).
+    return projectDefinitionMutationLock(resolve(vbriefDir, ".."), () => {
+        const nowDate = options.now ?? new Date();
+        const now = isoTimestamp(nowDate);
+        const layout = resolveProjectDefinitionLayout(vbriefDir);
+        const projectDefPath = join(vbriefDir, layout.filename);
+        if (!existsSync(projectDefPath)) {
+            return [false, `✗ ${projectDefPath} not found — run project:render first`];
+        }
+        let parsed;
         try {
-            projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
+            parsed = JSON.parse(readFileSync(projectDefPath, "utf8"));
         }
         catch (exc) {
             return [false, `✗ Failed to read ${projectDefPath}: ${String(exc)}`];
         }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return [false, `✗ ${projectDefPath} top-level value is not a JSON object`];
+        }
+        const projectDef = parsed;
         const plan = (projectDef.plan ?? {});
-        plan.items = items;
-        if (typeof projectDef[layout.infoRootKey] !== "object" ||
-            projectDef[layout.infoRootKey] === null) {
-            projectDef[layout.infoRootKey] = {};
+        if (typeof plan.metadata !== "object" ||
+            plan.metadata === null ||
+            Array.isArray(plan.metadata)) {
+            plan.metadata = {};
         }
-        projectDef[layout.infoRootKey].updated = now;
+        const planMetadata = plan.metadata;
+        const items = scanLifecycleFolders(vbriefDir);
+        const completedItems = items.filter((i) => i.status === "completed");
+        const existing = parseStalenessReview(planMetadata);
+        planMetadata.staleness_review = buildStalenessAcknowledgement(completedItems, {
+            now: nowDate,
+            existing,
+        });
         const narratives = typeof plan.narratives === "object" &&
             plan.narratives !== null &&
             !Array.isArray(plan.narratives)
             ? plan.narratives
             : {};
-        const completedItems = items.filter((i) => i.status === "completed");
-        if (typeof plan.metadata !== "object" ||
-            plan.metadata === null ||
-            Array.isArray(plan.metadata)) {
-            plan.metadata = {};
+        planMetadata.staleness_flags = computeStalenessFlags(narratives, completedItems, parseStalenessReview(planMetadata));
+        if (typeof projectDef[layout.infoRootKey] !== "object" ||
+            projectDef[layout.infoRootKey] === null) {
+            projectDef[layout.infoRootKey] = {};
         }
-        const planMetadata = plan.metadata;
-        const review = parseStalenessReview(planMetadata);
-        const flags = computeStalenessFlags(narratives, completedItems, review);
-        planMetadata.staleness_flags = flags;
+        projectDef[layout.infoRootKey].updated = now;
         projectDef.plan = plan;
-    }
-    else {
-        projectDef = createSkeleton(items, now, layout);
-    }
-    mkdirSync(vbriefDir, { recursive: true });
-    writeFileSync(projectDefPath, `${JSON.stringify(projectDef, null, 2)}\n`, "utf8");
-    const itemCount = items.length;
-    const planMeta = (projectDef.plan?.metadata ?? {});
-    const flagCount = Array.isArray(planMeta.staleness_flags) ? planMeta.staleness_flags.length : 0;
-    const action = createdNew ? "created" : "updated";
-    const parts = [`✓ ${layout.filename} ${action} (${itemCount} scope items)`];
-    if (flagCount > 0)
-        parts.push(`⚠ ${flagCount} staleness flag(s) -- agent review recommended`);
-    return [true, parts.join("\n")];
-}
-/**
- * Mark current completed scopes as reviewed for PROJECT-DEFINITION narratives.
- *
- * Distinct from `task reconcile:issues`, which reconciles origin freshness on scope
- * vBRIEFs — this path only clears narrative staleness heuristics on render.
- */
-export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
-    const nowDate = options.now ?? new Date();
-    const now = isoTimestamp(nowDate);
-    const layout = resolveProjectDefinitionLayout(vbriefDir);
-    const projectDefPath = join(vbriefDir, layout.filename);
-    if (!existsSync(projectDefPath)) {
-        return [false, `✗ ${projectDefPath} not found — run project:render first`];
-    }
-    let projectDef;
-    try {
-        projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
-    }
-    catch (exc) {
-        return [false, `✗ Failed to read ${projectDefPath}: ${String(exc)}`];
-    }
-    const plan = (projectDef.plan ?? {});
-    if (typeof plan.metadata !== "object" || plan.metadata === null || Array.isArray(plan.metadata)) {
-        plan.metadata = {};
-    }
-    const planMetadata = plan.metadata;
-    const items = scanLifecycleFolders(vbriefDir);
-    const completedItems = items.filter((i) => i.status === "completed");
-    const existing = parseStalenessReview(planMetadata);
-    planMetadata.staleness_review = buildStalenessAcknowledgement(completedItems, {
-        now: nowDate,
-        existing,
+        // Atomic temp+rename write under the lock so external readers never observe
+        // a partially-written PROJECT-DEFINITION (#1260).
+        atomicWriteProjectDefinition(projectDefPath, projectDef);
+        const ackCount = completedItems.length;
+        return [
+            true,
+            `✓ PROJECT-DEFINITION staleness acknowledged (${ackCount} completed scope(s) watermarked)`,
+        ];
     });
-    const narratives = typeof plan.narratives === "object" &&
-        plan.narratives !== null &&
-        !Array.isArray(plan.narratives)
-        ? plan.narratives
-        : {};
-    planMetadata.staleness_flags = computeStalenessFlags(narratives, completedItems, parseStalenessReview(planMetadata));
-    if (typeof projectDef[layout.infoRootKey] !== "object" ||
-        projectDef[layout.infoRootKey] === null) {
-        projectDef[layout.infoRootKey] = {};
-    }
-    projectDef[layout.infoRootKey].updated = now;
-    projectDef.plan = plan;
-    writeFileSync(projectDefPath, `${JSON.stringify(projectDef, null, 2)}\n`, "utf8");
-    const ackCount = completedItems.length;
-    return [
-        true,
-        `✓ PROJECT-DEFINITION staleness acknowledged (${ackCount} completed scope(s) watermarked)`,
-    ];
 }
 /** CLI entry (mirrors ``scripts/project_render.main``). */
 export function main(argv) {

package/dist/scope/capacity-stamp.d.ts

@@ -1,3 +1,25 @@
-/** Stamp completedAt + capacityBucket onto a completing vBRIEF (#1419). */
-export declare function stampCompletionMetadata(plan: Record<string, unknown>, projectRoot: string, timestamp: string): void;
+/** Read the labels for an issue reference. Returns null when they cannot be resolved. */
+export type LabelReader = (repo: string, issueNumber: number) => ReadonlySet<string> | null;
+export interface StampCompletionOptions {
+    /**
+     * Explicit label set for the completing brief. When provided it takes precedence
+     * over any linked-issue lookup, keeping bucket resolution pure and network-free.
+     */
+    readonly labels?: Iterable<string>;
+    /**
+     * Injectable reader used to resolve labels from the brief's linked issue when no
+     * explicit `labels` are supplied. Defaults to a cached-issue lookup (no network).
+     * A `null` return signals a cache MISS and triggers the live fallback below.
+     */
+    readonly labelReader?: LabelReader;
+    /**
+     * Injectable fail-open fallback used ONLY on a cache miss (`labelReader` returned
+     * `null`). Defaults to a single REST read via the scm shim (PRs excluded, #2246).
+     * A `null` return leaves resolution on the `defaultBucket` fallback. Injected in
+     * tests so the fallback path is exercised without a network call.
+     */
+    readonly liveLabelReader?: LabelReader;
+}
+/** Stamp completedAt + label-matched capacityBucket onto a completing vBRIEF (#1419, #2237). */
+export declare function stampCompletionMetadata(plan: Record<string, unknown>, projectRoot: string, timestamp: string, options?: StampCompletionOptions): void;
 //# sourceMappingURL=capacity-stamp.d.ts.map

package/dist/scope/capacity-stamp.js

@@ -1,33 +1,84 @@
-import { readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { readPlanPolicy } from "../policy/plan-extensions.js";
-import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
-function resolveDefaultCapacityBucket(projectRoot) {
-    try {
-        const path = join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
-        const raw = readFileSync(path, "utf8");
-        const data = JSON.parse(raw);
-        const plan = data.plan;
-        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            return "";
+import { resolve } from "node:path";
+import { cachedIssueLabels, extractIssueRef } from "../capacity/backfill.js";
+import { classifyBucket, loadBucketMatchers } from "../policy/capacity.js";
+import { restIssueView } from "../scm/gh-rest.js";
+function normalizeLabels(labels) {
+    const out = new Set();
+    for (const label of labels) {
+        if (typeof label === "string" && label.trim().length > 0) {
+            out.add(label);
         }
-        const policy = readPlanPolicy(plan);
-        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-            return "";
+    }
+    return out;
+}
+/** Extract label name strings from a raw REST/cache `labels` array. */
+function labelsFromRaw(raw) {
+    const out = new Set();
+    if (!Array.isArray(raw)) {
+        return out;
+    }
+    for (const label of raw) {
+        if (typeof label === "string" && label.length > 0) {
+            out.add(label);
         }
-        const allocation = policy.capacityAllocation;
-        if (typeof allocation !== "object" || allocation === null || Array.isArray(allocation)) {
-            return "";
+        else if (typeof label === "object" && label !== null && !Array.isArray(label)) {
+            const name = label.name;
+            if (typeof name === "string" && name.length > 0) {
+                out.add(name);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Fail-open live label read for a cache miss: a single REST GET through the scm
+ * shim (`restIssueView`), with PRs excluded. Any error (or a PR ref) yields `null`
+ * so resolution falls through to `defaultBucket` instead of crashing (#2246).
+ */
+function liveIssueLabels(repo, issueNumber) {
+    try {
+        const issue = restIssueView(repo, issueNumber);
+        // The issues endpoint also returns PRs; a PR object carries `pull_request`.
+        // Exclude PRs from label-based bucket resolution.
+        if (issue.pull_request !== undefined) {
+            return null;
         }
-        const defaultBucket = allocation.defaultBucket;
-        return typeof defaultBucket === "string" ? defaultBucket : "";
+        return labelsFromRaw(issue.labels);
     }
     catch {
-        return "";
+        return null;
     }
 }
-/** Stamp completedAt + capacityBucket onto a completing vBRIEF (#1419). */
-export function stampCompletionMetadata(plan, projectRoot, timestamp) {
+/**
+ * Resolve the capacityBucket for a completing brief by matching its issue labels
+ * against `capacityAllocation.buckets[].match.labels` (first declared match wins),
+ * falling back to `defaultBucket` when nothing matches (#2237).
+ */
+function resolveCapacityBucket(plan, projectRoot, options) {
+    const root = resolve(projectRoot);
+    const { matchers, default_bucket: defaultBucket } = loadBucketMatchers(root);
+    let labels = null;
+    if (options.labels !== undefined) {
+        labels = normalizeLabels(options.labels);
+    }
+    else {
+        const [repo, issueNumber] = extractIssueRef(plan);
+        if (repo !== null && issueNumber !== null) {
+            const reader = options.labelReader ?? ((r, n) => cachedIssueLabels(root, r, n));
+            labels = reader(repo, issueNumber);
+            // Cache MISS (null) -- take the fail-open live fallback. A cache HIT (even an
+            // empty set) stays the fast path and makes NO network call (#2246).
+            if (labels === null) {
+                const live = options.liveLabelReader ?? liveIssueLabels;
+                labels = live(repo, issueNumber);
+            }
+        }
+    }
+    const [bucket] = classifyBucket(labels ?? new Set(), matchers, defaultBucket);
+    return bucket;
+}
+/** Stamp completedAt + label-matched capacityBucket onto a completing vBRIEF (#1419, #2237). */
+export function stampCompletionMetadata(plan, projectRoot, timestamp, options = {}) {
     let metadata = plan.metadata;
     if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
         metadata = {};
@@ -36,11 +87,12 @@ export function stampCompletionMetadata(plan, projectRoot, timestamp) {
     const meta = metadata;
     meta.completedAt = timestamp;
     const existing = meta.capacityBucket;
-    if (!(typeof existing === "string" && existing.trim().length > 0)) {
-        const bucket = resolveDefaultCapacityBucket(projectRoot);
-        if (bucket.length > 0) {
-            meta.capacityBucket = bucket;
-        }
+    if (typeof existing === "string" && existing.trim().length > 0) {
+        return;
+    }
+    const bucket = resolveCapacityBucket(plan, projectRoot, options);
+    if (bucket.length > 0) {
+        meta.capacityBucket = bucket;
     }
 }
 //# sourceMappingURL=capacity-stamp.js.map

package/dist/scope/decomposed-refs.js

@@ -7,7 +7,7 @@ function rewriteOnePlanRef(value, oldParentResolved, newParentRel, vbriefDir) {
     if (typeof value !== "string" || value.length === 0) {
         return [value, false];
     }
-    const resolved = resolveVbriefRef(value, vbriefDir);
+    const resolved = resolveVbriefRef(value, vbriefDir, { allowCrossFolderSearch: false });
     if (resolved === null || resolve(resolved) !== resolve(oldParentResolved)) {
         return [value, false];
     }
@@ -40,7 +40,7 @@ function rewriteParentChildReference(parentPath, oldChildResolved, newChildRel,
         if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
             continue;
         }
-        const resolved = resolveVbriefRef(r.uri, vbriefDir);
+        const resolved = resolveVbriefRef(r.uri, vbriefDir, { allowCrossFolderSearch: false });
         if (resolved === null || resolve(resolved) !== resolve(oldChildResolved)) {
             continue;
         }

package/dist/scope/project-definition-sync.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
-import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { formatVbriefJson } from "./vbrief-json.js";
 import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
 function rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot) {
@@ -95,7 +95,7 @@ export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath,
         return;
     }
     const projectRoot = dirname(resolve(vbriefRoot));
-    const projectDefPath = join(projectRoot, PROJECT_DEFINITION_REL_PATH);
+    const projectDefPath = resolveProjectDefinitionPath(projectRoot);
     if (!existsSync(projectDefPath)) {
         return;
     }

package/dist/scope/vbrief-ref.d.ts

@@ -1,5 +1,6 @@
+import { type ResolveLifecycleArtifactRefOptions } from "../layout/lifecycle-ref.js";
 /** Resolve a vBRIEF reference URI to an absolute path, or null. */
-export declare function resolveVbriefRef(uri: unknown, vbriefDir: string): string | null;
+export declare function resolveVbriefRef(uri: unknown, vbriefDir: string, options?: ResolveLifecycleArtifactRefOptions): string | null;
 /** Collect planRef values from the plan root and top-level items. */
 export declare function collectPlanRefs(plan: Record<string, unknown>): string[];
 /** Collect x-vbrief/plan child reference uris from a parent plan. */

package/dist/scope/vbrief-ref.js

@@ -1,8 +1,9 @@
 import { resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { resolveLifecycleArtifactRef, } from "../layout/lifecycle-ref.js";
 import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
 /** Resolve a vBRIEF reference URI to an absolute path, or null. */
-export function resolveVbriefRef(uri, vbriefDir) {
+export function resolveVbriefRef(uri, vbriefDir, options = {}) {
     if (typeof uri !== "string" || uri.length === 0) {
         return null;
     }
@@ -16,7 +17,7 @@ export function resolveVbriefRef(uri, vbriefDir) {
     else {
         rel = uri;
     }
-    return resolve(vbriefDir, rel);
+    return resolveLifecycleArtifactRef(rel, vbriefDir, options);
 }
 /** Collect planRef values from the plan root and top-level items. */
 export function collectPlanRefs(plan) {

package/dist/spec-authority/constants.d.ts

@@ -1,7 +1,13 @@
 /** Generated-spec banner tokens (lockstep with Python ``_precutover.py``). */
 export declare const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
 export declare const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+export declare const GENERATED_SPEC_SOURCE_SPEC_XBRIEF = "<!-- Source of truth: xbrief/specification.xbrief.json -->";
 export declare const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
+export declare const GENERATED_SPEC_SOURCE_PD_XBRIEF = "<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->";
+/** True when markdown carries a generated-spec source marker for either layout. */
+export declare function contentHasGeneratedSpecSource(content: string): boolean;
+/** True when markdown carries a generated greenfield PD source marker for either layout. */
+export declare function contentHasGeneratedPdSource(content: string): boolean;
 export declare const EXPORT_SPEC_PD_BANNER: string;
 /** Narratives excluded from stakeholder SPEC/PRD exports (#2013 Wave 0 §5). */
 export declare const STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS: Set<string>;

package/dist/spec-authority/constants.js

@@ -1,7 +1,18 @@
 /** Generated-spec banner tokens (lockstep with Python ``_precutover.py``). */
 export const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
 export const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+export const GENERATED_SPEC_SOURCE_SPEC_XBRIEF = "<!-- Source of truth: xbrief/specification.xbrief.json -->";
 export const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
+export const GENERATED_SPEC_SOURCE_PD_XBRIEF = "<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->";
+/** True when markdown carries a generated-spec source marker for either layout. */
+export function contentHasGeneratedSpecSource(content) {
+    return (content.includes(GENERATED_SPEC_SOURCE_SPEC) ||
+        content.includes(GENERATED_SPEC_SOURCE_SPEC_XBRIEF));
+}
+/** True when markdown carries a generated greenfield PD source marker for either layout. */
+export function contentHasGeneratedPdSource(content) {
+    return (content.includes(GENERATED_SPEC_SOURCE_PD) || content.includes(GENERATED_SPEC_SOURCE_PD_XBRIEF));
+}
 export const EXPORT_SPEC_PD_BANNER = "<!-- AUTO-GENERATED by task project:export-spec -- DO NOT EDIT MANUALLY -->\n" +
     `${GENERATED_SPEC_PURPOSE}\n` +
     `${GENERATED_SPEC_SOURCE_PD}\n` +

package/dist/spec-authority/resolver.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../layout/resolve.js";
 import { SPEC_RENDER_BANNER } from "../render/constants.js";
-import { EXPORT_SPEC_PD_BANNER, GENERATED_SPEC_PURPOSE, GENERATED_SPEC_SOURCE_PD, GENERATED_SPEC_SOURCE_SPEC, } from "./constants.js";
+import { contentHasGeneratedPdSource, contentHasGeneratedSpecSource, EXPORT_SPEC_PD_BANNER, GENERATED_SPEC_PURPOSE, } from "./constants.js";
 export function resolveSpecAuthority(projectRoot) {
     const root = projectRoot;
     const layout = resolveLifecycleLayout(root);
@@ -37,14 +37,14 @@ export function isFullSpecState(projectRoot) {
     if (authority?.kind !== "full-spec")
         return false;
     const specMd = readSpecMarkdown(projectRoot);
-    return specMd.includes(GENERATED_SPEC_PURPOSE) && specMd.includes(GENERATED_SPEC_SOURCE_SPEC);
+    return specMd.includes(GENERATED_SPEC_PURPOSE) && contentHasGeneratedSpecSource(specMd);
 }
 export function isGreenfieldSpecExport(projectRoot) {
     const authority = resolveSpecAuthority(projectRoot);
     if (authority?.kind !== "greenfield")
         return false;
     const specMd = readSpecMarkdown(projectRoot);
-    return specMd.includes(GENERATED_SPEC_PURPOSE) && specMd.includes(GENERATED_SPEC_SOURCE_PD);
+    return specMd.includes(GENERATED_SPEC_PURPOSE) && contentHasGeneratedPdSource(specMd);
 }
 export function isCurrentGeneratedSpecification(projectRoot) {
     return isFullSpecState(projectRoot) || isGreenfieldSpecExport(projectRoot);

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { finalizeCohort } from "./finalize-cohort.js";
+export declare function parseFinalizeCohortArgv(argv: readonly string[]): Parameters<typeof finalizeCohort>[0];
+export declare function finalizeCohortMain(argv?: string[]): number;
+//# sourceMappingURL=finalize-cohort-cli.d.ts.map

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { finalizeCohort } from "./finalize-cohort.js";
+export function parseFinalizeCohortArgv(argv) {
+    const prNumbers = [];
+    const storyTokens = [];
+    let repo = null;
+    let projectRoot = ".";
+    let baseBranch = "master";
+    let label = null;
+    let dryRun = false;
+    let noCommit = false;
+    let noOpenPr = false;
+    let emitJson = false;
+    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));
+                }
+            }
+            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));
+                }
+            }
+        }
+        else if (arg === "--stories" && next !== undefined) {
+            storyTokens.push(next);
+            i += 1;
+        }
+        else if (arg === "--repo" && next !== undefined) {
+            repo = next;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--project-root" && next !== undefined) {
+            projectRoot = next;
+            i += 1;
+        }
+        else if (arg === "--base-branch" && next !== undefined) {
+            baseBranch = next;
+            i += 1;
+        }
+        else if (arg === "--label" && next !== undefined) {
+            label = next;
+            i += 1;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--no-commit") {
+            noCommit = true;
+        }
+        else if (arg === "--no-open-pr") {
+            noOpenPr = true;
+        }
+        else if (arg === "--json") {
+            emitJson = true;
+        }
+        else if (arg !== undefined && !arg.startsWith("-")) {
+            storyTokens.push(arg);
+        }
+    }
+    return {
+        prNumbers,
+        storyTokens,
+        repo,
+        projectRoot,
+        baseBranch,
+        label,
+        dryRun,
+        noCommit,
+        noOpenPr,
+        emitJson,
+    };
+}
+export function finalizeCohortMain(argv = process.argv.slice(2)) {
+    const result = finalizeCohort(parseFinalizeCohortArgv(argv));
+    if (result.stdout.length > 0) {
+        process.stdout.write(result.stdout);
+    }
+    if (result.stderr.length > 0) {
+        process.stderr.write(result.stderr);
+    }
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(finalizeCohortMain());
+}
+//# sourceMappingURL=finalize-cohort-cli.js.map