@deftai/directive-core 0.106.0 → 0.108.0

package/dist/release/issue-state-fetch.js

@@ -1,9 +1,11 @@
 /**
  * Release Step 3 issue-state fetch with capped rate-limit retry (#2577).
+ * Open-issue inventory via one paginated REST subprocess (#3752).
  */
 import { detectRateLimit } from "../cache/fetch.js";
-import { fetchIssueStates } from "../intake/reconcile-issues.js";
+import { IssueState } from "../intake/reconcile-issues.js";
 import { call } from "../scm/call.js";
+import { GhRestError, restIssueListOpenInventory } from "../scm/gh-rest.js";
 /** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
 export const MAX_RATE_LIMIT_RETRY_SLEEP_S = 120;
 const X_RATE_LIMIT_RESET_RE = /X-RateLimit-Reset:\s*(\d+)/i;
@@ -15,6 +17,71 @@ function defaultSleep(seconds) {
     const shared = new Int32Array(new SharedArrayBuffer(4));
     Atomics.wait(shared, 0, 0, ms);
 }
+function scmCallToRunGhApi(scmCall, cwd) {
+    return (args, options) => {
+        const result = scmCall("github-issue", "api", args, {
+            timeout: options?.timeout ?? 120,
+            cwd,
+        });
+        return {
+            returncode: result.returncode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    };
+}
+function buildStatesFromOpenInventory(issueNumbers, openInventory) {
+    const openNumbers = new Set();
+    for (const row of openInventory) {
+        const n = row.number;
+        if (typeof n === "number" && Number.isInteger(n)) {
+            openNumbers.add(n);
+        }
+    }
+    const states = new Map();
+    for (const n of [...issueNumbers].sort((a, b) => a - b)) {
+        states.set(n, openNumbers.has(n) ? new IssueState("OPEN") : new IssueState("NOT_FOUND"));
+    }
+    return states;
+}
+function fetchOpenInventoryAttempt(repo, runGhApiFn) {
+    let sawRateLimit = false;
+    let rateLimitStderr = "";
+    const trackingFn = (args, options) => {
+        const result = runGhApiFn(args, options);
+        if (result.returncode !== 0 && detectRateLimit(result.stderr)[0]) {
+            sawRateLimit = true;
+            rateLimitStderr = result.stderr;
+        }
+        return result;
+    };
+    try {
+        return {
+            inventory: restIssueListOpenInventory(repo, { runGhApiFn: trackingFn }),
+            sawRateLimit,
+            rateLimitStderr,
+            failureReason: null,
+        };
+    }
+    catch (err) {
+        const stderr = err instanceof GhRestError ? err.stderr : "";
+        if (stderr.length > 0 && detectRateLimit(stderr)[0]) {
+            sawRateLimit = true;
+            rateLimitStderr = stderr;
+        }
+        const reason = err instanceof GhRestError
+            ? `open-issue inventory fetch failed: ${err.message}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return {
+            inventory: null,
+            sawRateLimit,
+            rateLimitStderr,
+            failureReason: reason,
+        };
+    }
+}
 function parseRateLimitProbe(stdout) {
     try {
         const body = JSON.parse(stdout);
@@ -101,37 +168,34 @@ export function formatRateLimitFailureDetails(probe, rateLimitRelated) {
     return lines.join("\n");
 }
 export function fetchIssueStatesForRelease(repo, issueNumbers, options = {}) {
+    if (issueNumbers.size === 0) {
+        return { ok: true, states: new Map() };
+    }
+    process.stderr.write(`[release Step 3] checking ${issueNumbers.size} unique anchored issue(s) via open-issue inventory\n`);
     const sleepFn = options.sleep ?? defaultSleep;
     const nowFn = options.now ?? (() => Math.floor(Date.now() / 1000));
     const baseScmCall = options.scmCall ?? call;
     const cwd = options.cwd ?? undefined;
-    let sawRateLimit = false;
-    let lastRateLimitStderr = "";
-    const trackingScmCall = (source, verb, args, callOptions) => {
-        const result = baseScmCall(source, verb, args, callOptions);
-        if (result.returncode !== 0 && detectRateLimit(result.stderr)[0]) {
-            sawRateLimit = true;
-            lastRateLimitStderr = result.stderr;
-        }
-        return result;
+    const runGhApiFn = scmCallToRunGhApi(baseScmCall, cwd);
+    const finishSuccess = (inventory) => {
+        process.stderr.write(`[release Step 3] open-issue inventory: ${inventory.length} open issue(s)\n`);
+        return { ok: true, states: buildStatesFromOpenInventory(issueNumbers, inventory) };
     };
-    let states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
-    if (states !== null) {
-        return { ok: true, states };
+    let attempt = fetchOpenInventoryAttempt(repo, runGhApiFn);
+    if (attempt.inventory !== null) {
+        return finishSuccess(attempt.inventory);
     }
-    if (sawRateLimit) {
+    if (attempt.sawRateLimit) {
         const probe = probeGithubRateLimit(baseScmCall, cwd);
-        const sleepS = computeRateLimitSleepSeconds(lastRateLimitStderr, probe, nowFn());
+        const sleepS = computeRateLimitSleepSeconds(attempt.rateLimitStderr, probe, nowFn());
         process.stderr.write(`[release Step 3] GitHub REST rate limit hit; sleeping ${sleepS}s before one retry\n`);
         sleepFn(sleepS);
-        sawRateLimit = false;
-        lastRateLimitStderr = "";
-        states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
-        if (states !== null) {
-            return { ok: true, states };
+        attempt = fetchOpenInventoryAttempt(repo, runGhApiFn);
+        if (attempt.inventory !== null) {
+            return finishSuccess(attempt.inventory);
         }
     }
-    const rateLimitRelated = sawRateLimit || lastRateLimitStderr.length > 0;
+    const rateLimitRelated = attempt.sawRateLimit || attempt.rateLimitStderr.length > 0;
     if (rateLimitRelated) {
         const probe = probeGithubRateLimit(baseScmCall, cwd);
         const details = formatRateLimitFailureDetails(probe, true);
@@ -141,6 +205,7 @@ export function fetchIssueStatesForRelease(repo, issueNumbers, options = {}) {
             reason: "GitHub REST rate limit exhausted (see stderr for recovery steps)",
         };
     }
+    process.stderr.write(`${attempt.failureReason ?? "open-issue inventory fetch failed"}\n`);
     return { ok: false, reason: "failed to fetch issue states from gh" };
 }
 //# sourceMappingURL=issue-state-fetch.js.map

package/dist/release/native-steps.js

@@ -43,6 +43,7 @@ export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
                 anchorIssueNumbers.add(num);
             }
         }
+        process.stderr.write(`[release Step 3] ${anchors.length} lifecycle anchor(s), ${anchorIssueNumbers.size} unique issue number(s) to evaluate\n`);
         const fetchResult = fetchIssueStatesForRelease(repo, anchorIssueNumbers, {
             cwd: projectRoot,
         });

package/dist/release/pipeline.js

@@ -4,6 +4,7 @@ import { assertProjectionContained } from "../fs/projection-containment.js";
 import { readCoverageTotalsFromReport } from "../vitest-runner/coverage-debt.js";
 import { buildCoverageDebtIssueDraft, classifyStep5FailureWithFreshness, evaluateAutoHatch, formatAutoHatchBanner, parseExitCodeFromReason, reasonLooksLikeTimeout, } from "./auto-hatch.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
+import { emitCliDriftReportBestEffort, shouldSkipRegistryPoll, } from "./cli-drift-report.js";
 import { assertTagPushClosedVerb } from "./closed-verb-gate.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, RELEASE_CHECK_TIMEOUT_MINUTES, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
 import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
@@ -472,6 +473,24 @@ export function runPipeline(config, seams = {}) {
         }
     }
     process.stderr.write(`Release v${version} pipeline complete (dry_run=${config.dryRun ? "True" : "False"}, skip_tag=${config.skipTag ? "True" : "False"}, skip_release=${config.skipRelease ? "True" : "False"}).\n`);
+    // #3753 — report-only. Never runs npm i -g. Never fails the cut.
+    // Single-shot registry probe (no wait): Step 13 returns before npm-publish.yml
+    // is green; Phase 7 of the release skill owns the bounded wait.
+    emitCliDriftReportBestEffort(version, {
+        skipRegistryPoll: shouldSkipRegistryPoll(config),
+        pollTimeoutMs: 0,
+        checkActiveCli: seams.checkActiveCli,
+        viewPackage: seams.viewWorkspacePackage
+            ? (name, ver) => {
+                const probe = seams.viewWorkspacePackage?.(name, ver);
+                return {
+                    name: name,
+                    visible: probe?.visible ?? false,
+                    version: probe?.version ?? null,
+                };
+            }
+            : undefined,
+    });
     return EXIT_OK;
 }
 //# sourceMappingURL=pipeline.js.map

package/dist/release/types.d.ts

@@ -89,5 +89,19 @@ export interface ReleaseSeams {
      * Tests inject `{}` so a host env bypass cannot leak into fail-closed cases.
      */
     readonly closedVerbEnv?: EnvMap;
+    /**
+     * #3753 — override the active-CLI probe used by the local-vs-released report.
+     * When omitted, production calls `checkActiveCliAgainstTarget`.
+     */
+    readonly checkActiveCli?: (targetVersion: string) => import("../session/active-cli.js").ActiveCliCheckResult;
+    /**
+     * #3753 — override one `npm view <pkg>@<ver> --prefer-online` (tests).
+     * When omitted, production spawns npm. Never used to install.
+     */
+    readonly viewWorkspacePackage?: (name: string, version: string) => {
+        readonly name: string;
+        readonly visible: boolean;
+        readonly version: string | null;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/render/constants.d.ts

@@ -13,8 +13,12 @@ export declare const DEFAULT_INCLUDE_SCOPES_MODE: "off";
 /** Lifecycle scope aggregation modes for rendered specs (#1566). */
 export type IncludeScopesMode = "off" | "current" | "all";
 export declare const LIFECYCLE_BUCKETS: ReadonlyArray<readonly [string, string]>;
+/** Build a specification banner from the actual specification artifact path. */
+export declare function buildSpecRenderBanner(specPath: string): string;
 export declare const SPEC_RENDER_BANNER: string;
 export declare const PRD_NARRATIVE_KEY_ORDER: readonly ["Overview", "ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "Architecture"];
+/** Build a PRD banner from the actual resolved authority path. */
+export declare function buildPrdBanner(sourcePath: string): string;
 export declare const PRD_BANNER: string;
 export declare const PRD_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render";
 /** Max completed scopes listed under ## Completed in ROADMAP.md (#2653). */

package/dist/render/constants.js

@@ -12,6 +12,7 @@ export const VALID_STATUSES = new Set([
 ]);
 export { VALID_VBRIEF_VERSIONS } from "../vbrief-validate/constants.js";
 export { resolveInfoBlock } from "../vbrief-validate/schema.js";
+import { buildGeneratedArtifactBanner } from "../spec-authority/constants.js";
 export const SPECIFICATION_NARRATIVE_KEY_ORDER = [
     "Overview",
     "ProblemStatement",
@@ -37,10 +38,11 @@ export const LIFECYCLE_BUCKETS = [
     ["active", "Active"],
     ["completed", "Completed"],
 ];
-export const SPEC_RENDER_BANNER = "<!-- AUTO-GENERATED by task spec:render -- DO NOT EDIT MANUALLY -->\n" +
-    "<!-- Purpose: rendered specification -->\n" +
-    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n" +
-    "<!-- Regenerate with: task spec:render -->\n";
+/** Build a specification banner from the actual specification artifact path. */
+export function buildSpecRenderBanner(specPath) {
+    return buildGeneratedArtifactBanner("task spec:render", "rendered specification", specPath);
+}
+export const SPEC_RENDER_BANNER = buildSpecRenderBanner("xbrief/specification.xbrief.json");
 export const PRD_NARRATIVE_KEY_ORDER = [
     "Overview",
     "ProblemStatement",
@@ -50,10 +52,11 @@ export const PRD_NARRATIVE_KEY_ORDER = [
     "SuccessMetrics",
     "Architecture",
 ];
-export const PRD_BANNER = "<!-- AUTO-GENERATED by task prd:render -- DO NOT EDIT MANUALLY -->\n" +
-    "<!-- Purpose: rendered PRD -->\n" +
-    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n" +
-    "<!-- Regenerate with: task prd:render -->\n";
+/** Build a PRD banner from the actual resolved authority path. */
+export function buildPrdBanner(sourcePath) {
+    return buildGeneratedArtifactBanner("task prd:render", "rendered PRD", sourcePath);
+}
+export const PRD_BANNER = buildPrdBanner("xbrief/specification.xbrief.json");
 export const PRD_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render";
 /** Max completed scopes listed under ## Completed in ROADMAP.md (#2653). */
 export const ROADMAP_COMPLETED_CAP = 25;

package/dist/render/export-spec.js

@@ -7,6 +7,32 @@ import { buildScopeOutlookSection } from "./scope-outlook.js";
 import { normalizeIncludeScopesMode, tryParseIncludeScopesMode, tryParseOnOffFlag, } from "./spec-render.js";
 import { validateSpec } from "./spec-validate.js";
 import { stripTrailingWhitespace } from "./text-utils.js";
+function resolveExportScopePolicy(audience, includeScopes) {
+    const includeProposed = audience === "internal";
+    if (includeScopes === undefined) {
+        return {
+            render: includeProposed,
+            includeProposed,
+            includeCurrent: false,
+            includeCompleted: false,
+        };
+    }
+    const mode = normalizeIncludeScopesMode(includeScopes);
+    if (mode === "off") {
+        return {
+            render: false,
+            includeProposed: false,
+            includeCurrent: false,
+            includeCompleted: false,
+        };
+    }
+    return {
+        render: true,
+        includeProposed,
+        includeCurrent: true,
+        includeCompleted: mode === "all",
+    };
+}
 function loadPlanTitle(path, fallback) {
     try {
         const doc = JSON.parse(readFileSync(path, "utf8"));
@@ -36,9 +62,8 @@ export function exportSpec(options = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
     const outPath = options.outPath ?? join(projectRoot, "SPECIFICATION.md");
     const audience = options.audience ?? "stakeholder";
-    const includeScopesMode = normalizeIncludeScopesMode(options.includeScopes);
+    const scopePolicy = resolveExportScopePolicy(audience, options.includeScopes);
     const includeLegacyArtifacts = options.includeLegacyArtifacts ?? false;
-    const includeProposed = audience === "internal";
     const authority = resolveSpecAuthority(projectRoot);
     if (!authority) {
         return [false, "✗ Missing xbrief/PROJECT-DEFINITION.xbrief.json — cannot export spec."];
@@ -63,11 +88,12 @@ export function exportSpec(options = {}) {
         `# ${title}\n`,
         ...renderNarrativeSections(narratives),
     ];
-    if (includeScopesMode !== "off") {
+    if (scopePolicy.render) {
         const scopeLines = buildScopeOutlookSection(authority.vbriefDir, {
-            includeProposed,
+            includeProposed: scopePolicy.includeProposed,
             proposedLimit: options.proposedLimit,
-            includeCompleted: includeScopesMode === "all",
+            includeCurrent: scopePolicy.includeCurrent,
+            includeCompleted: scopePolicy.includeCompleted,
         });
         if (scopeLines.length > 0)
             lines.push(...scopeLines);

package/dist/render/index.d.ts

@@ -3,7 +3,7 @@ export { type ExportAudience, type ExportSpecOptions, exportSpec, exportSpecMain
 export * as frameworkCommands from "./framework-commands.js";
 export { availableCommands, cmdCoreValidate, formatFrameworkCommand, hasCommand, main as frameworkCommandsMain, normalizeTaskSeparator, runFrameworkCommand, } from "./framework-commands.js";
 export * as prdRender from "./prd-render.js";
-export { main as prdRenderMain, parsePrdArgv, renderPrd } from "./prd-render.js";
+export { main as prdRenderMain, parsePrdArgv, renderPrd, renderProjectPrd, } from "./prd-render.js";
 export * as projectRender from "./project-render.js";
 export { acknowledgeProjectDefinitionStaleness, buildStalenessAcknowledgement, computeStalenessFlags, flagStaleNarratives, main as projectRenderMain, parseStalenessReview, renderProjectDefinition, scanLifecycleFolders, unacknowledgedCompletedItems, } from "./project-render.js";
 export * as roadmapRender from "./roadmap-render.js";

package/dist/render/index.js

@@ -3,7 +3,7 @@ export { exportSpec, exportSpecMain, parseExportSpecArgv, } from "./export-spec.
 export * as frameworkCommands from "./framework-commands.js";
 export { availableCommands, cmdCoreValidate, formatFrameworkCommand, hasCommand, main as frameworkCommandsMain, normalizeTaskSeparator, runFrameworkCommand, } from "./framework-commands.js";
 export * as prdRender from "./prd-render.js";
-export { main as prdRenderMain, parsePrdArgv, renderPrd } from "./prd-render.js";
+export { main as prdRenderMain, parsePrdArgv, renderPrd, renderProjectPrd, } from "./prd-render.js";
 export * as projectRender from "./project-render.js";
 export { acknowledgeProjectDefinitionStaleness, buildStalenessAcknowledgement, computeStalenessFlags, flagStaleNarratives, main as projectRenderMain, parseStalenessReview, renderProjectDefinition, scanLifecycleFolders, unacknowledgedCompletedItems, } from "./project-render.js";
 export * as roadmapRender from "./roadmap-render.js";

package/dist/render/prd-render.d.ts

@@ -1,10 +1,13 @@
 export interface RenderPrdOptions {
     readonly force?: boolean;
 }
-/** Read specification.vbrief.json and write PRD.md (mirrors ``scripts/prd_render.render_prd``). */
+/** Read an explicit specification artifact and write PRD.md. */
 export declare function renderPrd(specPath: string, outputPath: string, options?: RenderPrdOptions): void;
+/** Resolve full-spec or greenfield project authority and write a stakeholder-safe PRD. */
+export declare function renderProjectPrd(projectRoot: string, outputPath: string, options?: RenderPrdOptions): void;
 export interface PrdCliArgs {
     readonly spec?: string;
+    readonly projectRoot?: string;
     readonly output?: string;
     readonly force?: boolean;
 }

package/dist/render/prd-render.js

@@ -1,5 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { PRD_BANNER, PRD_GENERATED_SENTINEL, PRD_NARRATIVE_KEY_ORDER } from "./constants.js";
+import { resolve } from "node:path";
+import { resolveSpecArtifactPath } from "../layout/resolve.js";
+import { generatedSourcePath } from "../spec-authority/constants.js";
+import { greenfieldOverviewNonEmpty, resolveExportNarratives, } from "../spec-authority/narratives.js";
+import { resolveSpecAuthority } from "../spec-authority/resolver.js";
+import { buildPrdBanner, PRD_GENERATED_SENTINEL, PRD_NARRATIVE_KEY_ORDER } from "./constants.js";
+import { validateSpec } from "./spec-validate.js";
 function isDeftGenerated(path) {
     if (!existsSync(path))
         return true;
@@ -12,31 +18,20 @@ function isDeftGenerated(path) {
         return false;
     }
 }
-/** Read specification.vbrief.json and write PRD.md (mirrors ``scripts/prd_render.render_prd``). */
-export function renderPrd(specPath, outputPath, options = {}) {
-    const force = options.force ?? false;
-    if (!existsSync(specPath)) {
-        process.stderr.write(`Error: specification file not found: ${specPath}\n`);
-        process.exit(1);
-    }
+function writePrd(title, narratives, sourcePath, outputPath, force) {
     if (!force && !isDeftGenerated(outputPath)) {
         process.stderr.write(`Error: refusing to overwrite non-generated PRD at ${outputPath}. ` +
             `This file lacks the "${PRD_GENERATED_SENTINEL}" banner -- it was likely hand-authored. ` +
             "Re-run with --force to overwrite, or point --output at a different file (#539).\n");
         process.exit(2);
     }
-    const data = JSON.parse(readFileSync(specPath, "utf8"));
-    const plan = (data.plan ?? {});
-    const title = String(plan.title ?? "Project");
-    const narratives = typeof plan.narratives === "object" &&
-        plan.narratives !== null &&
-        !Array.isArray(plan.narratives)
-        ? plan.narratives
-        : {};
     if (Object.keys(narratives).length === 0) {
-        process.stderr.write(`Warning: no narratives found in ${specPath}\n`);
+        process.stderr.write(`Warning: no narratives found in ${sourcePath}\n`);
     }
-    const lines = [PRD_BANNER, `# ${title} -- Product Requirements Document\n`];
+    const lines = [
+        buildPrdBanner(sourcePath),
+        `# ${title} -- Product Requirements Document\n`,
+    ];
     const renderedKeys = new Set();
     for (const key of PRD_NARRATIVE_KEY_ORDER) {
         if (key in narratives) {
@@ -52,16 +47,80 @@ export function renderPrd(specPath, outputPath, options = {}) {
         }
     }
     lines.push("---\n" +
-        "*This document is auto-generated from the specification artifact " +
-        "(e.g. `xbrief/specification.xbrief.json`) via `task prd:render`. Do not edit directly.*\n");
+        `*This document is auto-generated from \`${generatedSourcePath(sourcePath)}\` ` +
+        "via `task prd:render`. Do not edit directly.*\n");
     writeFileSync(outputPath, lines.join("\n"), "utf8");
     process.stdout.write(`PRD.md written to ${outputPath}\n`);
 }
+function loadTitleAndNarratives(sourcePath) {
+    const payload = JSON.parse(readFileSync(sourcePath, "utf8"));
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        process.stderr.write(`Error: ${sourcePath} root must be a JSON object\n`);
+        process.exit(1);
+    }
+    const data = payload;
+    const plan = (data.plan ?? {});
+    const narratives = typeof plan.narratives === "object" &&
+        plan.narratives !== null &&
+        !Array.isArray(plan.narratives)
+        ? plan.narratives
+        : {};
+    return { title: String(plan.title ?? "Project"), narratives };
+}
+/** Read an explicit specification artifact and write PRD.md. */
+export function renderPrd(specPath, outputPath, options = {}) {
+    if (!existsSync(specPath)) {
+        process.stderr.write(`Error: specification file not found: ${specPath}\n`);
+        process.exit(1);
+    }
+    const { title, narratives } = loadTitleAndNarratives(specPath);
+    writePrd(title, narratives, specPath, outputPath, options.force ?? false);
+}
+/** Resolve full-spec or greenfield project authority and write a stakeholder-safe PRD. */
+export function renderProjectPrd(projectRoot, outputPath, options = {}) {
+    const root = resolve(projectRoot);
+    const authority = resolveSpecAuthority(root);
+    if (!authority) {
+        try {
+            const compatibilitySpecPath = resolveSpecArtifactPath(root);
+            if (existsSync(compatibilitySpecPath)) {
+                renderPrd(compatibilitySpecPath, outputPath, options);
+                return;
+            }
+        }
+        catch {
+            // The stable error below covers projects without a resolvable lifecycle layout.
+        }
+        process.stderr.write("Error: xbrief/PROJECT-DEFINITION.xbrief.json not found; PRD authority is unavailable.\n");
+        process.exit(1);
+    }
+    if (authority.kind === "full-spec" && authority.specPath) {
+        const [ok, message] = validateSpec(authority.specPath);
+        if (!ok) {
+            process.stderr.write(`${message}\n`);
+            process.exit(1);
+        }
+    }
+    else if (!greenfieldOverviewNonEmpty(authority)) {
+        process.stderr.write("Error: PROJECT-DEFINITION.xbrief.json Overview narrative is empty; cannot render PRD.\n");
+        process.exit(1);
+    }
+    const { title } = loadTitleAndNarratives(authority.sourcePath);
+    writePrd(title, resolveExportNarratives(authority), authority.sourcePath, outputPath, options.force ?? false);
+}
 /** CLI entry (mirrors ``scripts/prd_render.main``). */
 export function main(args = {}) {
-    renderPrd(args.spec ?? "vbrief/specification.vbrief.json", args.output ?? "PRD.md", {
-        force: args.force ?? false,
-    });
+    const outputPath = args.output ?? "PRD.md";
+    const options = { force: args.force ?? false };
+    if (args.spec !== undefined) {
+        renderPrd(args.spec, outputPath, options);
+    }
+    else if (args.projectRoot !== undefined) {
+        renderProjectPrd(args.projectRoot, outputPath, options);
+    }
+    else {
+        renderPrd("vbrief/specification.vbrief.json", outputPath, options);
+    }
 }
 export function parsePrdArgv(argv) {
     const out = {};

package/dist/render/project-render.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLayoutRootOrCanonical, 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 { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.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";
@@ -192,11 +192,15 @@ export function renderProjectDefinition(vbriefDir, options = {}) {
     // 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 projectRoot = resolve(vbriefDir, "..");
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
         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);
+        // Read and write the artifact the lock captured, not a second independent
+        // resolution of the same file (#3796). Resolving it again here is how a
+        // render could lock one identity and materialise items into another.
+        const projectDefPath = mutation.artifactPath;
         const items = scanLifecycleFolders(vbriefDir);
         const createdNew = !existsSync(projectDefPath);
         let projectDef;
@@ -242,7 +246,7 @@ export function renderProjectDefinition(vbriefDir, options = {}) {
         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);
+        mutation.persist(projectDef);
         const itemCount = items.length;
         const planMeta = (projectDef.plan?.metadata ?? {});
         const flagCount = Array.isArray(planMeta.staleness_flags) ? planMeta.staleness_flags.length : 0;
@@ -262,11 +266,14 @@ export function renderProjectDefinition(vbriefDir, options = {}) {
 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 projectRoot = resolve(vbriefDir, "..");
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
         const nowDate = options.now ?? new Date();
         const now = isoTimestamp(nowDate);
         const layout = resolveProjectDefinitionLayout(vbriefDir);
-        const projectDefPath = join(vbriefDir, layout.filename);
+        // Read and write the artifact the lock captured (#3796) -- see the note in
+        // `renderProjectDefinition`.
+        const projectDefPath = mutation.artifactPath;
         if (!existsSync(projectDefPath)) {
             return [false, `✗ ${projectDefPath} not found — run project:render first`];
         }
@@ -309,7 +316,7 @@ export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
         projectDef.plan = plan;
         // Atomic temp+rename write under the lock so external readers never observe
         // a partially-written PROJECT-DEFINITION (#1260).
-        atomicWriteProjectDefinition(projectDefPath, projectDef);
+        mutation.persist(projectDef);
         const ackCount = completedItems.length;
         return [
             true,

package/dist/render/scope-outlook.d.ts

@@ -1,6 +1,8 @@
 export interface ScopeOutlookOptions {
     readonly includeProposed?: boolean;
     readonly proposedLimit?: number;
+    /** When false, omit pending and active lifecycle buckets. Default true. */
+    readonly includeCurrent?: boolean;
     /**
      * When false, omit the completed lifecycle bucket (#1566 compact render).
      * Default true so callers that opt into full aggregation keep prior behavior.

package/dist/render/scope-outlook.js

@@ -203,6 +203,7 @@ function filterProposed(vb) {
 export function buildScopeOutlookSection(vbriefDir, options = {}) {
     const includeProposed = options.includeProposed ?? false;
     const proposedLimit = options.proposedLimit ?? 0;
+    const includeCurrent = options.includeCurrent ?? true;
     const includeCompleted = options.includeCompleted ?? true;
     const buckets = [];
     if (includeProposed) {
@@ -221,6 +222,8 @@ export function buildScopeOutlookSection(vbriefDir, options = {}) {
         }
     }
     for (const [folder, heading, filter] of COMMITTED_BUCKETS) {
+        if ((folder === "pending" || folder === "active") && !includeCurrent)
+            continue;
         if (folder === "completed" && !includeCompleted)
             continue;
         let scopes = loadScopeVbriefs(join(vbriefDir, folder));

package/dist/render/spec-render.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { DEFAULT_INCLUDE_SCOPES_MODE, LEGACY_ARTIFACTS_NARRATIVE_KEY, RENDERABLE_SPEC_STATUSES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
+import { buildSpecRenderBanner, DEFAULT_INCLUDE_SCOPES_MODE, LEGACY_ARTIFACTS_NARRATIVE_KEY, RENDERABLE_SPEC_STATUSES, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
 import { buildScopeOutlookSection } from "./scope-outlook.js";
 import { validateSpec } from "./spec-validate.js";
 import { stripTrailingWhitespace } from "./text-utils.js";
@@ -100,7 +100,7 @@ export function renderSpec(specPath, outPath, options = {}) {
                 "  Have the user review and set status to one of the renderable statuses before rendering.",
         ];
     }
-    const lines = [SPEC_RENDER_BANNER];
+    const lines = [buildSpecRenderBanner(specPath)];
     let title = "Specification";
     if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
         title = String(plan.title ?? "Specification");