@deftai/directive-core 0.59.0 → 0.60.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/index.d.ts

@@ -4,7 +4,7 @@ export { availableCommands, cmdCoreValidate, formatFrameworkCommand, hasCommand,
 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 * as specRender from "./spec-render.js";

package/dist/render/index.js

@@ -4,7 +4,7 @@ export { availableCommands, cmdCoreValidate, formatFrameworkCommand, hasCommand,
 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 * as specRender from "./spec-render.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 {};

package/dist/render/project-render.js

@@ -87,9 +87,57 @@ export function flagStaleNarratives(narratives, completedItems) {
     }
     return flags.sort();
 }
+function isoTimestamp(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Parse `plan.metadata.staleness_review` when present and well-formed. */
+export function parseStalenessReview(metadata) {
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+        return null;
+    }
+    const review = metadata.staleness_review;
+    if (typeof review !== "object" || review === null || Array.isArray(review)) {
+        return null;
+    }
+    const acknowledgedAt = review.acknowledged_at;
+    const scopeIds = review.acknowledged_completed_scope_ids;
+    if (typeof acknowledgedAt !== "string" || acknowledgedAt.length === 0) {
+        return null;
+    }
+    if (!Array.isArray(scopeIds) || !scopeIds.every((id) => typeof id === "string")) {
+        return null;
+    }
+    return {
+        acknowledged_at: acknowledgedAt,
+        acknowledged_completed_scope_ids: [...scopeIds].sort(),
+    };
+}
+/** Completed scopes not yet covered by the acknowledgement watermark. */
+export function unacknowledgedCompletedItems(completedItems, review) {
+    if (!review)
+        return [...completedItems];
+    const acknowledged = new Set(review.acknowledged_completed_scope_ids);
+    return completedItems.filter((item) => !acknowledged.has(item.id));
+}
+/** Build acknowledgement metadata for the current completed-scope set. */
+export function buildStalenessAcknowledgement(completedItems, options = {}) {
+    const now = isoTimestamp(options.now ?? new Date());
+    const mergedIds = new Set([
+        ...(options.existing?.acknowledged_completed_scope_ids ?? []),
+        ...completedItems.map((item) => item.id),
+    ]);
+    return {
+        acknowledged_at: now,
+        acknowledged_completed_scope_ids: [...mergedIds].sort(),
+    };
+}
+export function computeStalenessFlags(narratives, completedItems, review = null) {
+    const pending = unacknowledgedCompletedItems(completedItems, review);
+    return flagStaleNarratives(narratives, pending);
+}
 export function createSkeleton(items, now) {
     const completedItems = items.filter((i) => i.status === "completed");
-    const stalenessFlags = flagStaleNarratives({ ...SKELETON_NARRATIVES }, completedItems);
+    const stalenessFlags = computeStalenessFlags({ ...SKELETON_NARRATIVES }, completedItems);
     return {
         vBRIEFInfo: {
             version: EMITTED_VBRIEF_VERSION,
@@ -133,13 +181,15 @@ export function renderProjectDefinition(vbriefDir, options = {}) {
             ? plan.narratives
             : {};
         const completedItems = items.filter((i) => i.status === "completed");
-        const flags = flagStaleNarratives(narratives, completedItems);
         if (typeof plan.metadata !== "object" ||
             plan.metadata === null ||
             Array.isArray(plan.metadata)) {
             plan.metadata = {};
         }
-        plan.metadata.staleness_flags = flags;
+        const planMetadata = plan.metadata;
+        const review = parseStalenessReview(planMetadata);
+        const flags = computeStalenessFlags(narratives, completedItems, review);
+        planMetadata.staleness_flags = flags;
         projectDef.plan = plan;
     }
     else {
@@ -156,14 +206,68 @@ export function renderProjectDefinition(vbriefDir, options = {}) {
         parts.push(`⚠ ${flagCount} staleness flag(s) -- agent review recommended`);
     return [true, parts.join("\n")];
 }
+/**
+ * Mark current completed scopes as reviewed for PROJECT-DEFINITION narratives.
+ *
+ * Distinct from `task reconcile:issues`, which reconciles origin freshness on scope
+ * vBRIEFs — this path only clears narrative staleness heuristics on render.
+ */
+export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
+    const nowDate = options.now ?? new Date();
+    const now = isoTimestamp(nowDate);
+    const projectDefPath = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+    if (!existsSync(projectDefPath)) {
+        return [false, `✗ ${projectDefPath} not found — run project:render first`];
+    }
+    let projectDef;
+    try {
+        projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
+    }
+    catch (exc) {
+        return [false, `✗ Failed to read ${projectDefPath}: ${String(exc)}`];
+    }
+    const plan = (projectDef.plan ?? {});
+    if (typeof plan.metadata !== "object" || plan.metadata === null || Array.isArray(plan.metadata)) {
+        plan.metadata = {};
+    }
+    const planMetadata = plan.metadata;
+    const items = scanLifecycleFolders(vbriefDir);
+    const completedItems = items.filter((i) => i.status === "completed");
+    const existing = parseStalenessReview(planMetadata);
+    planMetadata.staleness_review = buildStalenessAcknowledgement(completedItems, {
+        now: nowDate,
+        existing,
+    });
+    const narratives = typeof plan.narratives === "object" &&
+        plan.narratives !== null &&
+        !Array.isArray(plan.narratives)
+        ? plan.narratives
+        : {};
+    planMetadata.staleness_flags = computeStalenessFlags(narratives, completedItems, parseStalenessReview(planMetadata));
+    if (typeof projectDef.vBRIEFInfo !== "object" || projectDef.vBRIEFInfo === null) {
+        projectDef.vBRIEFInfo = {};
+    }
+    projectDef.vBRIEFInfo.updated = now;
+    projectDef.plan = plan;
+    writeFileSync(projectDefPath, `${JSON.stringify(projectDef, null, 2)}\n`, "utf8");
+    const ackCount = completedItems.length;
+    return [
+        true,
+        `✓ PROJECT-DEFINITION staleness acknowledged (${ackCount} completed scope(s) watermarked)`,
+    ];
+}
 /** CLI entry (mirrors ``scripts/project_render.main``). */
 export function main(argv) {
-    if (argv.length > 1) {
-        process.stderr.write("Usage: project_render.py [vbrief_dir]\n");
+    const acknowledge = argv[0] === "--acknowledge-staleness";
+    const rest = acknowledge ? argv.slice(1) : argv;
+    if (rest.length > 1) {
+        process.stderr.write("Usage: project_render.py [--acknowledge-staleness] [vbrief_dir]\n");
         return 2;
     }
-    const vbriefDir = argv[0] ?? "vbrief";
-    const [ok, message] = renderProjectDefinition(vbriefDir);
+    const vbriefDir = rest[0] ?? "vbrief";
+    const [ok, message] = acknowledge
+        ? acknowledgeProjectDefinitionStaleness(vbriefDir)
+        : renderProjectDefinition(vbriefDir);
     process.stdout.write(`${message}\n`);
     return ok ? 0 : 1;
 }

package/dist/task-surface/index.d.ts

@@ -0,0 +1,13 @@
+export interface TaskSurfaceIo {
+    writeOut: (text: string) => void;
+    writeErr: (text: string) => void;
+}
+/** Port of ``task change:changelog:check`` inline Python (#2022 Phase 2). */
+export declare function runChangelogCheck(projectRoot: string, io: TaskSurfaceIo): number;
+/** Port of ``task change:init`` inline Python (#2022 Phase 2). */
+export declare function runChangeInit(projectRoot: string, name: string, io: TaskSurfaceIo): number;
+/** Port of ``task commit:lint`` inline Python (#2022 Phase 2). */
+export declare function runCommitLint(projectRoot: string, io: TaskSurfaceIo): number;
+/** Port of ``task install:uninstall`` inline Python (#2022 Phase 2). */
+export declare function runInstallUninstall(projectRoot: string, io: TaskSurfaceIo): number;
+//# sourceMappingURL=index.d.ts.map