@deftai/directive-core 0.107.0 → 0.109.0

package/dist/release/pipeline.js

@@ -1,17 +1,21 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { assertProjectionContained } from "../fs/projection-containment.js";
+import { restIssueListOpenInventory } from "../scm/gh-rest.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 { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
 import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
 import { checkTagAvailable, createGithubRelease, readTextFile, verifyReleaseDraft } from "./gh.js";
 import { checkGitClean, commitReleaseArtifacts, createTag, currentBranch, pushRelease, releaseCommitSubject, runGit, } from "./git.js";
 import { checkVbriefLifecycleSyncNative, refreshRoadmapNative, runBuildNative, } from "./native-steps.js";
 import { todayIso } from "./paths.js";
 import { runReleaseCheck } from "./preflight.js";
+import { evaluateReleaseConsumerReadiness, issuesFromInventory } from "./run-consumer-readiness.js";
 import { formatSkipCiIncidentWarning } from "./skip-ci-incident.js";
 import { evaluateSuiteStamp, writeSuiteStamp } from "./suite-stamp.js";
 import { isPrereleaseTag } from "./version.js";
@@ -289,6 +293,58 @@ export function runPipeline(config, seams = {}) {
             }
         }
     }
+    // #3900: check 4 fail-closed (title/label census); checks 5-6 disclosure never block.
+    {
+        const crLabel = "Consumer-readiness census";
+        let changelogText = "";
+        try {
+            changelogText = readFile(changelogPath);
+        }
+        catch {
+            changelogText = "";
+        }
+        const disclosure = formatConsumerReadinessDisclosure(changelogText);
+        if (config.dryRun) {
+            emit(5, crLabel, "DRYRUN (would enumerate open privileged hard-stop labels; disclosure does not block)");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else if (seams.consumerHardStops) {
+            const [ok, msg] = seams.consumerHardStops(config.repo, projectRoot);
+            if (!ok) {
+                emit(5, crLabel, "FAIL (" + msg + ")");
+                process.stderr.write(disclosure.text + "\n");
+                return EXIT_VIOLATION;
+            }
+            emit(5, crLabel, "OK (" + msg + ")");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else if (seams.runCi !== undefined || seams.spawnText !== undefined) {
+            emit(5, crLabel, "SKIP (injected seam; run task verify:consumer-hard-stops at a real cut)");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else {
+            try {
+                const rows = restIssueListOpenInventory(config.repo);
+                const result = evaluateReleaseConsumerReadiness({
+                    changelogText,
+                    issues: issuesFromInventory(rows),
+                });
+                process.stderr.write(result.disclosure.text + "\n");
+                if (result.hardStops.code !== 0) {
+                    emit(5, crLabel, "FAIL (" + result.hardStops.message + ")");
+                    return result.hardStops.code === 2 ? EXIT_CONFIG_ERROR : EXIT_VIOLATION;
+                }
+                emit(5, crLabel, "OK (" + result.hardStops.message + ")");
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                emit(5, crLabel, "FAIL (could not list open issues. Recovery: check gh auth and REST quota. " +
+                    reason +
+                    ")");
+                return EXIT_CONFIG_ERROR;
+            }
+        }
+    }
     // Step 6: CHANGELOG promotion.
     label = "CHANGELOG promotion";
     if (!fileExists(changelogPath)) {
@@ -472,6 +528,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/run-consumer-readiness.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Release pre-flight consumer-readiness: check 4 fail-closed, checks 5-6 disclosure (#3900).
+ */
+import { evaluateConsumerHardStopCensus, type HardStopIssue } from "./consumer-hard-stops.js";
+import { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
+export interface ConsumerReadinessInput {
+    readonly changelogText: string;
+    readonly issues: readonly HardStopIssue[];
+}
+export declare function evaluateReleaseConsumerReadiness(input: ConsumerReadinessInput): {
+    readonly hardStops: ReturnType<typeof evaluateConsumerHardStopCensus>;
+    readonly disclosure: ReturnType<typeof formatConsumerReadinessDisclosure>;
+};
+export declare function issuesFromInventory(rows: readonly Record<string, unknown>[]): HardStopIssue[];
+//# sourceMappingURL=run-consumer-readiness.d.ts.map

package/dist/release/run-consumer-readiness.js

@@ -0,0 +1,24 @@
+/**
+ * Release pre-flight consumer-readiness: check 4 fail-closed, checks 5-6 disclosure (#3900).
+ */
+import { evaluateConsumerHardStopCensus, issueFromInventoryRow, parseClosesSet, } from "./consumer-hard-stops.js";
+import { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
+export function evaluateReleaseConsumerReadiness(input) {
+    return {
+        hardStops: evaluateConsumerHardStopCensus({
+            issues: input.issues,
+            closesSet: parseClosesSet(input.changelogText),
+        }),
+        disclosure: formatConsumerReadinessDisclosure(input.changelogText),
+    };
+}
+export function issuesFromInventory(rows) {
+    const issues = [];
+    for (const row of rows) {
+        const issue = issueFromInventoryRow(row);
+        if (issue !== null)
+            issues.push(issue);
+    }
+    return issues;
+}
+//# sourceMappingURL=run-consumer-readiness.js.map

package/dist/release/types.d.ts

@@ -54,6 +54,12 @@ export interface ReleaseSeams {
     readonly writeFile?: (path: string, content: string) => void;
     readonly readFile?: (path: string) => string;
     readonly fileExists?: (path: string) => boolean;
+    /**
+     * #3900 check 4 -- consumer hard-stop census. When omitted, production lists
+     * open issues via REST. Tests inject a [ok, message] tuple so they do not
+     * hit GitHub.
+     */
+    readonly consumerHardStops?: (repo: string, projectRoot: string) => [boolean, string];
     readonly runCi?: (projectRoot: string, allowCoverageDebtIssue: number | null) => [boolean, string];
     readonly refreshRoadmap?: (projectRoot: string) => [boolean, string];
     readonly checkVbriefLifecycleSync?: (projectRoot: string, repo: string) => [boolean, number, string];
@@ -89,5 +95,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");

package/dist/resolution/package-manager.d.ts

@@ -16,8 +16,9 @@
  *      gitignored / package-manager-invisible). Only the global, project-local,
  *      ephemeral, and upgrade command forms vary by package manager.
  *
- * Every function here is PURE (no I/O): detection consumes an injected fact-set
- * so the whole surface is unit-testable without touching the filesystem or env.
+ * Detection from an injected fact-set remains pure. The project resolver is the
+ * single filesystem boundary used by consumer gates so package.json and lockfile
+ * precedence cannot drift across callers (#3610).
  */
 export type PackageManager = "npm" | "pnpm";
 export declare const PACKAGE_MANAGERS: readonly PackageManager[];
@@ -32,10 +33,38 @@ export interface DetectPackageManagerInput {
     /** Whether a `pnpm-lock.yaml` is present at the project root. */
     readonly pnpmLockPresent?: boolean;
 }
+export type PackageManagerResolutionSource = "env-override" | "package-manager-field" | "pnpm-lock" | "user-agent" | "default";
+export type PackageManagerResolutionErrorSource = "env-override" | "package-manager-field" | "package-json" | "project-filesystem";
+export type PackageManagerResolution = {
+    readonly ok: true;
+    readonly packageManager: PackageManager;
+    readonly source: PackageManagerResolutionSource;
+} | {
+    readonly ok: false;
+    readonly source: PackageManagerResolutionErrorSource;
+    readonly message: string;
+};
+export interface ResolveProjectPackageManagerOptions {
+    /** Consumer project root. Defaults to the current working directory. */
+    readonly projectRoot?: string;
+    /** Environment map used for override and user-agent precedence. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Text-read seam. `null` means the file is absent. */
+    readonly readText?: (path: string) => string | null;
+    /** File-existence seam used for pnpm-lock.yaml. */
+    readonly isFile?: (path: string) => boolean;
+}
+/** Human-readable, non-executable label for a resolution source. */
+export declare function packageManagerSourceLabel(source: PackageManagerResolutionSource): string;
+export declare function resolvePackageManager(input?: DetectPackageManagerInput): PackageManagerResolution;
+/** Render untrusted diagnostic text as one bounded terminal-safe line. */
+export declare function sanitizeSingleLineDiagnostic(text: string): string;
+/** Resolve a consumer project's package manager from package.json and lockfile facts. */
+export declare function resolveProjectPackageManager(options?: ResolveProjectPackageManagerOptions): PackageManagerResolution;
 /**
  * Detect the active package manager. Precedence (first match wins):
- *   1. `DEFT_PACKAGE_MANAGER` env override
- *   2. `packageManager` field / Corepack shim
+ *   1. `packageManager` field / Corepack shim (authoritative when present)
+ *   2. `DEFT_PACKAGE_MANAGER` env override
  *   3. `pnpm-lock.yaml` present
  *   4. `npm_config_user_agent` (set by the manager that spawned the process)
  *   5. default: npm