@deftai/directive-core 0.59.0 → 0.61.0

package/dist/migrate-preflight/index.js

@@ -0,0 +1,193 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { defaultWhich } from "../scm/binary.js";
+import { detectPreCutoverLegacy, isCurrentGeneratedSpecification, isGeneratedSpecificationExport, missingLifecycleFolders, } from "../vbrief-validate/precutover.js";
+function resolveContentRoot(frameworkRoot) {
+    const nested = join(frameworkRoot, "content");
+    try {
+        if (statSync(nested).isDirectory())
+            return nested;
+    }
+    catch {
+        // consumer deposit: content lives directly under framework root
+    }
+    return frameworkRoot;
+}
+export function checkUv(which = defaultWhich) {
+    if (which("uv") !== null) {
+        return { name: "uv", status: "PASS", message: "uv is on PATH." };
+    }
+    return {
+        name: "uv",
+        status: "FAIL",
+        message: "uv is not on PATH. Install from https://docs.astral.sh/uv/ and re-run.",
+    };
+}
+export function checkLayout(deftRoot, projectRoot) {
+    const migrator = join(deftRoot, "scripts", "migrate_vbrief.py");
+    if (!existsSync(migrator) || !statSync(migrator).isFile()) {
+        return {
+            name: "layout",
+            status: "FAIL",
+            message: `Migrator script missing at ${migrator}. The framework checkout appears incomplete or pre-v0.20; refresh per deft/QUICK-START.md.`,
+        };
+    }
+    const schemasDir = join(resolveContentRoot(deftRoot), "vbrief", "schemas");
+    if (!existsSync(schemasDir) || !statSync(schemasDir).isDirectory()) {
+        return {
+            name: "layout",
+            status: "FAIL",
+            message: `Framework schemas dir missing at ${schemasDir}. Refresh the deft checkout (see deft/QUICK-START.md).`,
+        };
+    }
+    const projectVbrief = join(projectRoot, "vbrief");
+    if (!existsSync(projectVbrief)) {
+        return {
+            name: "layout",
+            status: "WARN",
+            message: `Project vbrief/ not present at ${projectVbrief} -- migrator will create it on first run; this is expected for greenfield projects.`,
+        };
+    }
+    return {
+        name: "layout",
+        status: "PASS",
+        message: `Framework migrator + schemas present; project vbrief/ at ${projectVbrief}.`,
+    };
+}
+export function checkGitClean(projectRoot) {
+    try {
+        const stdout = execFileSync("git", ["status", "--porcelain"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+        });
+        if (stdout.trim()) {
+            return {
+                name: "git-clean",
+                status: "WARN",
+                message: "Working tree is dirty. The migrator will refuse to run without --force; preview with `task migrate:vbrief -- --dry-run` first.",
+            };
+        }
+        return { name: "git-clean", status: "PASS", message: "Working tree is clean." };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                name: "git-clean",
+                status: "WARN",
+                message: "git executable not on PATH; skipping working-tree check. Migrator's dirty-tree guard will still fire if applicable.",
+            };
+        }
+        return {
+            name: "git-clean",
+            status: "WARN",
+            message: `Not a git repository at ${projectRoot}; skipping working-tree check.`,
+        };
+    }
+}
+export function checkDocumentModel(projectRoot) {
+    const legacy = detectPreCutoverLegacy(projectRoot);
+    if (legacy.length > 0) {
+        return {
+            name: "document-model",
+            status: "PASS",
+            message: `Legacy root artifact(s) detected: ${legacy.join(", ")}.`,
+        };
+    }
+    const specPath = join(projectRoot, "SPECIFICATION.md");
+    if (existsSync(specPath) && statSync(specPath).isFile()) {
+        let content = "";
+        try {
+            content = readFileSync(specPath, "utf8");
+        }
+        catch {
+            content = "";
+        }
+        if (isGeneratedSpecificationExport(projectRoot, content)) {
+            const missing = missingLifecycleFolders(projectRoot);
+            if (missing.length > 0) {
+                return {
+                    name: "document-model",
+                    status: "FAIL",
+                    message: `Generated SPECIFICATION.md detected (source: vbrief/specification.vbrief.json); repair missing lifecycle folder(s) instead of migrating: ${missing.join(", ")}.`,
+                };
+            }
+        }
+        if (isCurrentGeneratedSpecification(projectRoot, content)) {
+            return {
+                name: "document-model",
+                status: "FAIL",
+                message: "Current generated SPECIFICATION.md detected (source: vbrief/specification.vbrief.json); `task migrate:vbrief` is not needed.",
+            };
+        }
+    }
+    const vbriefRoot = join(projectRoot, "vbrief");
+    if (existsSync(vbriefRoot)) {
+        const missing = missingLifecycleFolders(projectRoot);
+        if (missing.length > 0) {
+            return {
+                name: "document-model",
+                status: "PASS",
+                message: `Partial vBRIEF layout detected; missing lifecycle folder(s): ${missing.join(", ")}.`,
+            };
+        }
+    }
+    return {
+        name: "document-model",
+        status: "WARN",
+        message: "No legacy root SPECIFICATION.md/PROJECT.md artifacts detected. Migration may have nothing to do.",
+    };
+}
+export function evaluate(deftRoot, projectRoot, which = defaultWhich) {
+    const results = [
+        checkUv(which),
+        checkLayout(deftRoot, projectRoot),
+        checkDocumentModel(projectRoot),
+        checkGitClean(projectRoot),
+    ];
+    if (results.some((r) => r.status === "FAIL")) {
+        return { exitCode: 1, results };
+    }
+    return { exitCode: 0, results };
+}
+export function formatCheckLine(result) {
+    return `CHECK ${result.name}: ${result.status} ${result.message}`;
+}
+export function runMigratePreflight(args) {
+    const projectRoot = resolve(args.projectRoot);
+    const deftRoot = resolve(args.deftRoot);
+    if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+        return {
+            kind: "config",
+            message: `--project-root must be an existing directory: ${args.projectRoot}`,
+        };
+    }
+    if (!existsSync(deftRoot) || !statSync(deftRoot).isDirectory()) {
+        return {
+            kind: "config",
+            message: `--deft-root must be an existing directory: ${args.deftRoot}`,
+        };
+    }
+    const { exitCode, results } = evaluate(deftRoot, projectRoot);
+    return { kind: "ready", exitCode, results };
+}
+export function emitMigratePreflight(outcome, io, quiet) {
+    for (const result of outcome.results) {
+        if (quiet && result.status === "PASS")
+            continue;
+        const line = `${formatCheckLine(result)}\n`;
+        if (result.status === "FAIL")
+            io.writeErr(line);
+        else
+            io.writeOut(line);
+    }
+    if (outcome.exitCode === 1) {
+        io.writeErr("migrate:preflight FAILED -- resolve the FAIL line(s) above before running `task migrate:vbrief`.\n");
+    }
+    else {
+        io.writeOut("migrate:preflight OK -- environment ready for `task migrate:vbrief`.\n");
+    }
+    return outcome.exitCode;
+}
+//# sourceMappingURL=index.js.map

package/dist/release-e2e/greenfield-python-free-smoke-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=greenfield-python-free-smoke-cli.d.ts.map

package/dist/release-e2e/greenfield-python-free-smoke-cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { rehearseGreenfieldPythonFreeSmoke } from "./greenfield-python-free-smoke.js";
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+const skipWorkspacePrep = process.env.DEFT_GREENFIELD_SKIP_PREP === "1";
+const [ok, reason] = rehearseGreenfieldPythonFreeSmoke(repoRoot, {}, { skipWorkspacePrep });
+process.stdout.write(`${reason}\n`);
+process.exit(ok ? 0 : 1);
+//# sourceMappingURL=greenfield-python-free-smoke-cli.js.map

package/dist/release-e2e/greenfield-python-free-smoke.d.ts

@@ -0,0 +1,12 @@
+import type { E2ESeams } from "./types.js";
+export interface GreenfieldSmokeSeams extends E2ESeams {
+}
+export interface GreenfieldSmokeOptions {
+    skipWorkspacePrep?: boolean;
+}
+/**
+ * Greenfield npm smoke (#2022 Phase 3): pack/install directive, run init +
+ * task check in a Python-free PATH, and assert the deposit carries no Python.
+ */
+export declare function rehearseGreenfieldPythonFreeSmoke(repoRoot: string, seams?: GreenfieldSmokeSeams, options?: GreenfieldSmokeOptions): [boolean, string];
+//# sourceMappingURL=greenfield-python-free-smoke.d.ts.map

package/dist/release-e2e/greenfield-python-free-smoke.js

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { collectPythonArtifacts, isRepoRootPythonRunShim } from "../deposit/python-free.js";
+import { defaultWhich, spawnText } from "../release/spawn.js";
+import { NPM_PUBLISH_PACKAGES } from "./constants.js";
+import { alignNpmPackageVersions, resolvePnpm } from "./npm-ops.js";
+const SMOKE_VERSION = "9.9.9-smoke";
+function pythonFreePathEnv(base = process.env) {
+    const pathKey = base.PATH !== undefined ? "PATH" : base.Path !== undefined ? "Path" : "PATH";
+    const current = base[pathKey] ?? "";
+    const filtered = current
+        .split(":")
+        .filter((entry) => !/(^|\/)python[0-9]*(?:\.\d+)?$/.test(entry))
+        .filter((entry) => !entry.includes("/pyenv/"))
+        .join(":");
+    return {
+        ...base,
+        [pathKey]: filtered,
+        DEFT_PYTHON: "",
+        PYTHON: "",
+    };
+}
+function seedMinimalProjectDefinition(projectDir) {
+    const vbriefDir = join(projectDir, "vbrief");
+    mkdirSync(vbriefDir, { recursive: true });
+    writeFileSync(join(vbriefDir, "PROJECT-DEFINITION.vbrief.json"), `${JSON.stringify({
+        vBRIEFInfo: { version: "0.6", description: "greenfield smoke fixture (#2022 Phase 3)" },
+        plan: {
+            title: "PROJECT-DEFINITION",
+            status: "running",
+            items: [],
+            policy: {},
+            narratives: {
+                Overview: "Greenfield smoke fixture (#2022 Phase 3).",
+                "tech stack": "Node.js",
+            },
+        },
+    }, null, 2)}\n`, "utf8");
+}
+function packTarballPath(packDir, pkgDir) {
+    const manifest = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+    if (typeof manifest.name !== "string" || typeof manifest.version !== "string") {
+        return null;
+    }
+    const scoped = manifest.name.replaceAll("@", "").replaceAll("/", "-");
+    return join(packDir, `${scoped}-${manifest.version}.tgz`);
+}
+function runStep(spawn, label, cmd, args, options = {}) {
+    const result = spawn(cmd, args, options);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "").trim();
+        return [false, `${label} failed (exit ${result.status}): ${detail.slice(-800)}`];
+    }
+    return [true, `${label} OK`];
+}
+/**
+ * Greenfield npm smoke (#2022 Phase 3): pack/install directive, run init +
+ * task check in a Python-free PATH, and assert the deposit carries no Python.
+ */
+export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options = {}) {
+    const which = seams.which ?? seams.whichGh ?? defaultWhich;
+    const npm = which("npm");
+    if (!npm) {
+        return [true, "SKIP greenfield-python-free-smoke: npm not on PATH"];
+    }
+    const task = which("task");
+    if (!task) {
+        return [true, "SKIP greenfield-python-free-smoke: task (go-task) not on PATH"];
+    }
+    const pnpmPrefix = resolvePnpm(seams);
+    if (!pnpmPrefix || pnpmPrefix.length === 0) {
+        return [false, "greenfield-python-free-smoke FAIL: neither pnpm nor corepack on PATH"];
+    }
+    const [pnpmCmd, ...pnpmArgs] = pnpmPrefix;
+    if (pnpmCmd === undefined) {
+        return [false, "greenfield-python-free-smoke FAIL: pnpm command prefix is empty"];
+    }
+    const spawn = seams.spawnText ?? spawnText;
+    const work = mkdtempSync(join(tmpdir(), "deft-greenfield-smoke-"));
+    const packDir = join(work, "packs");
+    mkdirSync(packDir, { recursive: true });
+    const projectDir = join(work, "project");
+    const npmPrefix = join(work, "npm-prefix");
+    const envBase = { ...process.env, npm_config_prefix: npmPrefix };
+    const manifestBackup = new Map();
+    for (const pkg of NPM_PUBLISH_PACKAGES) {
+        const manifestPath = join(repoRoot, "packages", pkg, "package.json");
+        if (existsSync(manifestPath)) {
+            manifestBackup.set(manifestPath, readFileSync(manifestPath, "utf8"));
+        }
+    }
+    try {
+        let ok;
+        let reason;
+        if (!options.skipWorkspacePrep) {
+            [ok, reason] = runStep(spawn, "pnpm install", pnpmCmd, [...pnpmArgs, "install", "--frozen-lockfile"], {
+                cwd: repoRoot,
+                env: envBase,
+                timeoutMs: 120_000,
+            });
+            if (!ok)
+                return [false, `greenfield smoke: ${reason}`];
+            [ok, reason] = runStep(spawn, "pnpm build", pnpmCmd, [...pnpmArgs, "run", "build"], {
+                cwd: repoRoot,
+                env: envBase,
+                timeoutMs: 120_000,
+            });
+            if (!ok)
+                return [false, `greenfield smoke: ${reason}`];
+        }
+        [ok, reason] = alignNpmPackageVersions(repoRoot, SMOKE_VERSION);
+        if (!ok)
+            return [false, `greenfield smoke: ${reason}`];
+        const packed = [];
+        for (const pkg of NPM_PUBLISH_PACKAGES) {
+            const pkgDir = join(repoRoot, "packages", pkg);
+            [ok, reason] = runStep(spawn, `npm pack packages/${pkg}`, npm, ["pack", "--pack-destination", packDir], { cwd: pkgDir, env: envBase, timeoutMs: 120_000 });
+            if (!ok)
+                return [false, `greenfield smoke: ${reason}`];
+            const tgz = packTarballPath(packDir, pkgDir);
+            if (!tgz || !existsSync(tgz)) {
+                return [false, `greenfield smoke: missing pack tarball for ${pkg}`];
+            }
+            packed.push(tgz);
+        }
+        [ok, reason] = runStep(spawn, "npm install -g", npm, ["install", "-g", ...packed], {
+            env: envBase,
+            timeoutMs: 120_000,
+        });
+        if (!ok)
+            return [false, `greenfield smoke: ${reason}`];
+        const deft = join(npmPrefix, "bin", "deft");
+        if (!existsSync(deft)) {
+            return [false, `greenfield smoke: expected global deft at ${deft}`];
+        }
+        const pyFree = pythonFreePathEnv(envBase);
+        [ok, reason] = runStep(spawn, "directive init", deft, ["init", "--yes", "--repo-root", projectDir], {
+            cwd: work,
+            env: pyFree,
+            timeoutMs: 120_000,
+        });
+        if (!ok)
+            return [false, `greenfield smoke: ${reason}`];
+        seedMinimalProjectDefinition(projectDir);
+        const depositDir = join(projectDir, ".deft", "core");
+        const artifacts = collectPythonArtifacts(depositDir);
+        if (artifacts.length > 0) {
+            return [
+                false,
+                `greenfield smoke: deposit still contains Python artifacts: ${artifacts.map((a) => a.path).join(", ")}`,
+            ];
+        }
+        if (isRepoRootPythonRunShim(projectDir)) {
+            return [false, "greenfield smoke: repo-root Python run shim present after init"];
+        }
+        const checkEnv = {
+            ...pyFree,
+            PATH: `${join(npmPrefix, "bin")}:${pyFree.PATH ?? ""}`,
+            DEFT_SESSION_RITUAL_SKIP: "1",
+        };
+        [ok, reason] = runStep(spawn, "task deft:check", task, ["deft:check"], {
+            cwd: projectDir,
+            env: checkEnv,
+            timeoutMs: 180_000,
+        });
+        if (!ok)
+            return [false, `greenfield smoke: ${reason}`];
+        return [
+            true,
+            "greenfield-python-free-smoke: directive init + task deft:check passed with Python absent from PATH",
+        ];
+    }
+    finally {
+        for (const [manifestPath, contents] of manifestBackup) {
+            writeFileSync(manifestPath, contents, "utf8");
+        }
+        if (process.env.DEFT_GREENFIELD_KEEP_WORK !== "1") {
+            rmSync(work, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=greenfield-python-free-smoke.js.map

package/dist/render/export-spec.d.ts

@@ -0,0 +1,17 @@
+export type ExportAudience = "stakeholder" | "internal";
+export interface ExportSpecOptions {
+    readonly projectRoot?: string;
+    readonly outPath?: string;
+    readonly audience?: ExportAudience;
+    readonly includeScopes?: boolean;
+    readonly proposedLimit?: number;
+}
+export type ExportSpecResult = readonly [boolean, string];
+/** Unified spec export (#2013 / #1502). */
+export declare function exportSpec(options?: ExportSpecOptions): ExportSpecResult;
+export declare function parseExportSpecArgv(argv: readonly string[]): {
+    options: ExportSpecOptions;
+    errors: string[];
+};
+export declare function exportSpecMain(argv: readonly string[]): number;
+//# sourceMappingURL=export-spec.d.ts.map

package/dist/render/export-spec.js

@@ -0,0 +1,104 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { greenfieldOverviewNonEmpty, renderNarrativeSections, resolveExportNarratives, } from "../spec-authority/narratives.js";
+import { resolveSpecAuthority } from "../spec-authority/resolver.js";
+import { buildScopeOutlookSection } from "./scope-outlook.js";
+import { validateSpec } from "./spec-validate.js";
+function loadPlanTitle(path, fallback) {
+    try {
+        const doc = JSON.parse(readFileSync(path, "utf8"));
+        const plan = doc.plan;
+        if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+            return String(plan.title ?? fallback);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return fallback;
+}
+/** Unified spec export (#2013 / #1502). */
+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 includeScopes = options.includeScopes ?? true;
+    const includeProposed = audience === "internal";
+    const authority = resolveSpecAuthority(projectRoot);
+    if (!authority) {
+        return [false, "✗ Missing vbrief/PROJECT-DEFINITION.vbrief.json — cannot export spec."];
+    }
+    if (authority.kind === "full-spec" && authority.specPath) {
+        const [ok, msg] = validateSpec(authority.specPath);
+        if (!ok)
+            return [false, msg];
+    }
+    else if (!greenfieldOverviewNonEmpty(authority)) {
+        return [
+            false,
+            "⚠ PROJECT-DEFINITION.vbrief.json Overview narrative is empty (D3). Populate Overview before export.",
+        ];
+    }
+    const narratives = resolveExportNarratives(authority);
+    const title = authority.kind === "full-spec" && authority.specPath
+        ? loadPlanTitle(authority.specPath, "Specification")
+        : loadPlanTitle(authority.projectDefPath, "Specification");
+    const lines = [
+        authority.banner,
+        `# ${title}\n`,
+        ...renderNarrativeSections(narratives),
+    ];
+    if (includeScopes) {
+        const scopeLines = buildScopeOutlookSection(authority.vbriefDir, {
+            includeProposed,
+            proposedLimit: options.proposedLimit,
+        });
+        if (scopeLines.length > 0)
+            lines.push(...scopeLines);
+    }
+    writeFileSync(outPath, lines.join("\n"), "utf8");
+    return [true, `✓ Exported spec to ${outPath}`];
+}
+export function parseExportSpecArgv(argv) {
+    const options = {};
+    const errors = [];
+    const positional = [];
+    for (const arg of argv) {
+        if (arg === "--audience=stakeholder" || arg === "--audience=internal") {
+            options.audience = arg.split("=")[1];
+            continue;
+        }
+        if (arg.startsWith("--proposed-limit=")) {
+            const n = Number(arg.split("=", 2)[1]);
+            if (Number.isFinite(n) && n > 0)
+                options.proposedLimit = n;
+            continue;
+        }
+        if (arg === "--no-scopes") {
+            options.includeScopes = false;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            errors.push(`Unknown flag: ${arg}`);
+            continue;
+        }
+        positional.push(arg);
+    }
+    if (positional[0])
+        options.projectRoot = positional[0];
+    if (positional[1])
+        options.outPath = positional[1];
+    return { options: options, errors };
+}
+export function exportSpecMain(argv) {
+    const { options, errors } = parseExportSpecArgv(argv);
+    if (errors.length > 0) {
+        for (const e of errors)
+            console.error(e);
+        return 2;
+    }
+    const [ok, msg] = exportSpec(options);
+    console.log(msg);
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=export-spec.js.map

package/dist/render/index.d.ts

@@ -1,12 +1,14 @@
 export * from "./constants.js";
+export { type ExportAudience, type ExportSpecOptions, exportSpec, exportSpecMain, parseExportSpecArgv, } from "./export-spec.js";
 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 * as projectRender from "./project-render.js";
-export { flagStaleNarratives, main as projectRenderMain, renderProjectDefinition, scanLifecycleFolders, } 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";
 export { checkDrift, generateRoadmapContent, main as roadmapRenderMain, renderRoadmap, renderRoadmapToBuffer, } from "./roadmap-render.js";
+export { aggregateScopeSection, buildScopeOutlookSection } from "./scope-outlook.js";
 export * as specRender from "./spec-render.js";
 export { main as specRenderMain, parseIncludeScopesFlag, renderSpec } from "./spec-render.js";
 export * as specValidate from "./spec-validate.js";

package/dist/render/index.js

@@ -1,12 +1,14 @@
 export * from "./constants.js";
+export { exportSpec, exportSpecMain, parseExportSpecArgv, } from "./export-spec.js";
 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 * as projectRender from "./project-render.js";
-export { flagStaleNarratives, main as projectRenderMain, renderProjectDefinition, scanLifecycleFolders, } 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";
 export { checkDrift, generateRoadmapContent, main as roadmapRenderMain, renderRoadmap, renderRoadmapToBuffer, } from "./roadmap-render.js";
+export { aggregateScopeSection, buildScopeOutlookSection } from "./scope-outlook.js";
 export * as specRender from "./spec-render.js";
 export { main as specRenderMain, parseIncludeScopesFlag, renderSpec } from "./spec-render.js";
 export * as specValidate from "./spec-validate.js";

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

@@ -1,4 +1,11 @@
 type JsonObject = Record<string, unknown>;
+/** Durable review state for PROJECT-DEFINITION narrative staleness (#640). */
+export interface StalenessReviewMetadata {
+    /** ISO-8601 UTC when narratives were last reviewed/acknowledged. */
+    acknowledged_at: string;
+    /** Completed scope IDs incorporated at acknowledgement time (watermark). */
+    acknowledged_completed_scope_ids: readonly string[];
+}
 export interface LifecycleItem {
     id: string;
     title: string;
@@ -7,6 +14,16 @@ export interface LifecycleItem {
 }
 export declare function scanLifecycleFolders(vbriefDir: string): LifecycleItem[];
 export declare function flagStaleNarratives(narratives: Record<string, string>, completedItems: LifecycleItem[]): string[];
+/** Parse `plan.metadata.staleness_review` when present and well-formed. */
+export declare function parseStalenessReview(metadata: unknown): StalenessReviewMetadata | null;
+/** Completed scopes not yet covered by the acknowledgement watermark. */
+export declare function unacknowledgedCompletedItems(completedItems: readonly LifecycleItem[], review: StalenessReviewMetadata | null): LifecycleItem[];
+/** Build acknowledgement metadata for the current completed-scope set. */
+export declare function buildStalenessAcknowledgement(completedItems: readonly LifecycleItem[], options?: {
+    now?: Date;
+    existing?: StalenessReviewMetadata | null;
+}): StalenessReviewMetadata;
+export declare function computeStalenessFlags(narratives: Record<string, string>, completedItems: readonly LifecycleItem[], review?: StalenessReviewMetadata | null): string[];
 export declare function createSkeleton(items: LifecycleItem[], now: string): JsonObject;
 export interface RenderProjectOptions {
     readonly now?: Date;
@@ -14,6 +31,13 @@ export interface RenderProjectOptions {
 export type RenderProjectResult = readonly [boolean, string];
 /** Regenerate PROJECT-DEFINITION.vbrief.json (mirrors ``scripts/project_render.render_project_definition``). */
 export declare function renderProjectDefinition(vbriefDir: string, options?: RenderProjectOptions): RenderProjectResult;
+/**
+ * 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 declare function acknowledgeProjectDefinitionStaleness(vbriefDir: string, options?: RenderProjectOptions): RenderProjectResult;
 /** CLI entry (mirrors ``scripts/project_render.main``). */
 export declare function main(argv: readonly string[]): number;
 export {};