@deftai/directive-core 0.60.0 → 0.61.0

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,4 +1,5 @@
 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";
@@ -7,6 +8,7 @@ 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";
 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,4 +1,5 @@
 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";
@@ -7,6 +8,7 @@ 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";
 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/scope-outlook.d.ts

@@ -0,0 +1,9 @@
+export interface ScopeOutlookOptions {
+    readonly includeProposed?: boolean;
+    readonly proposedLimit?: number;
+}
+/** Build Scope outlook section per #2013 Wave 0 §4. */
+export declare function buildScopeOutlookSection(vbriefDir: string, options?: ScopeOutlookOptions): string[];
+/** Legacy wrapper: stakeholder export (no proposed). */
+export declare function aggregateScopeSection(vbriefDir: string): string[];
+//# sourceMappingURL=scope-outlook.d.ts.map

package/dist/render/scope-outlook.js

@@ -0,0 +1,248 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PROPOSED_DISCLAIMER_LINES, PROPOSED_STATUS_FILTER } from "../spec-authority/constants.js";
+import { SCOPE_SUMMARY_NARRATIVES } from "./constants.js";
+function readEdgeEndpoints(edge) {
+    if (typeof edge !== "object" || edge === null || Array.isArray(edge))
+        return ["", ""];
+    const e = edge;
+    return [String(e.from ?? e.source ?? "") || "", String(e.to ?? e.target ?? "") || ""];
+}
+function loadScopeVbriefs(folder) {
+    if (!existsSync(folder))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(folder)
+            .filter((n) => n.endsWith(".vbrief.json"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        try {
+            const data = JSON.parse(readFileSync(join(folder, name), "utf8"));
+            const stem = name.endsWith(".vbrief.json") ? name.slice(0, -".vbrief.json".length) : name;
+            out.push([stem, data]);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+function scopeId(stem, vbrief) {
+    const plan = vbrief.plan;
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const planId = plan.id;
+        if (typeof planId === "string" && planId)
+            return planId;
+    }
+    return stem;
+}
+function crossScopeDepMap(scopes) {
+    const scopeIds = new Set(scopes.map(([stem, vb]) => scopeId(stem, vb)));
+    const depMap = {};
+    for (const [, vbrief] of scopes) {
+        const plan = vbrief.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+            continue;
+        const edges = plan.edges;
+        if (!Array.isArray(edges))
+            continue;
+        for (const edge of edges) {
+            const [frm, to] = readEdgeEndpoints(edge);
+            if (frm && to && scopeIds.has(frm) && scopeIds.has(to)) {
+                if (!depMap[to])
+                    depMap[to] = [];
+                depMap[to].push(frm);
+            }
+        }
+    }
+    return depMap;
+}
+function topoSortScopes(scopes, depMap) {
+    if (scopes.length === 0)
+        return [];
+    const idByIndex = scopes.map(([stem, vb]) => scopeId(stem, vb));
+    const idToIndex = new Map(idByIndex.map((sid, i) => [sid, i]));
+    const depths = {};
+    const depth = (sid, visited = null) => {
+        if (sid in depths)
+            return depths[sid] ?? 0;
+        const vis = visited ?? new Set();
+        if (vis.has(sid))
+            return 0;
+        vis.add(sid);
+        const deps = (depMap[sid] ?? []).filter((d) => idToIndex.has(d));
+        if (deps.length === 0) {
+            depths[sid] = 0;
+            return 0;
+        }
+        const result = Math.max(...deps.map((d) => depth(d, vis))) + 1;
+        depths[sid] = result;
+        return result;
+    };
+    for (const sid of idByIndex)
+        depth(sid);
+    const orderedIndices = [...idByIndex.keys()].sort((a, b) => (depths[idByIndex[a] ?? ""] ?? 0) - (depths[idByIndex[b] ?? ""] ?? 0) || a - b);
+    return orderedIndices.map((i) => scopes[i]);
+}
+function scopeSummaryNarrative(plan) {
+    const narratives = plan.narratives;
+    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives))
+        return "";
+    const narr = narratives;
+    for (const key of SCOPE_SUMMARY_NARRATIVES) {
+        const val = narr[key];
+        if (typeof val === "string" && val.trim())
+            return val.trim();
+    }
+    for (const val of Object.values(narr)) {
+        if (typeof val === "string" && val.trim())
+            return val.trim();
+    }
+    return "";
+}
+function splitAcceptance(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
+    }
+    if (typeof value !== "string")
+        return [];
+    const parts = [];
+    for (const line of value.split("\n")) {
+        let cleaned = line.trim();
+        if (!cleaned)
+            continue;
+        if (cleaned.startsWith("- ") || cleaned.startsWith("* "))
+            cleaned = cleaned.slice(2).trim();
+        if (cleaned)
+            parts.push(cleaned);
+    }
+    return parts;
+}
+function itemAcceptance(item) {
+    const narrative = item.narrative;
+    if (typeof narrative !== "object" || narrative === null || Array.isArray(narrative))
+        return [];
+    return splitAcceptance(narrative.Acceptance);
+}
+function renderScopeBlock(stem, vbrief) {
+    const plan = vbrief.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return [];
+    const planObj = plan;
+    const title = String(planObj.title ?? stem);
+    const status = String(planObj.status ?? "");
+    let heading = `### ${stem}: ${title}`;
+    if (status)
+        heading += `  \`[${status}]\``;
+    const lines = [`${heading}\n`];
+    const summary = scopeSummaryNarrative(planObj);
+    if (summary)
+        lines.push(`${summary}\n`);
+    const narratives = planObj.narratives;
+    if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+        const scopeAcceptance = splitAcceptance(narratives.Acceptance);
+        if (scopeAcceptance.length > 0) {
+            lines.push("**Scope Acceptance**:\n");
+            for (const criterion of scopeAcceptance)
+                lines.push(`- ${criterion}`);
+            lines.push("");
+        }
+    }
+    const items = planObj.items;
+    if (Array.isArray(items) && items.length > 0) {
+        lines.push("**Acceptance**:\n");
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+                continue;
+            const itemObj = item;
+            const itemTitle = String(itemObj.title ?? "Untitled");
+            const itemStatus = String(itemObj.status ?? "");
+            let bullet = `- ${itemTitle}`;
+            if (itemStatus)
+                bullet += ` \`[${itemStatus}]\``;
+            lines.push(bullet);
+            for (const criterion of itemAcceptance(itemObj)) {
+                if (criterion !== itemTitle)
+                    lines.push(`  - Acceptance: ${criterion}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+const COMMITTED_BUCKETS = [
+    ["pending", "Accepted backlog (pending)"],
+    ["active", "Active"],
+    [
+        "completed",
+        "Completed",
+        (vb) => {
+            const plan = vb.plan;
+            return (typeof plan === "object" &&
+                plan !== null &&
+                !Array.isArray(plan) &&
+                plan.status === "completed");
+        },
+    ],
+];
+function filterProposed(vb) {
+    const plan = vb.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return true;
+    const status = String(plan.status ?? "proposed").toLowerCase();
+    return PROPOSED_STATUS_FILTER.has(status);
+}
+/** Build Scope outlook section per #2013 Wave 0 §4. */
+export function buildScopeOutlookSection(vbriefDir, options = {}) {
+    const includeProposed = options.includeProposed ?? false;
+    const proposedLimit = options.proposedLimit ?? 0;
+    const buckets = [];
+    if (includeProposed) {
+        let proposed = loadScopeVbriefs(join(vbriefDir, "proposed")).filter(([, vb]) => filterProposed(vb));
+        if (proposedLimit > 0 && proposed.length > proposedLimit) {
+            const omitted = proposed.length - proposedLimit;
+            proposed = proposed.slice(0, proposedLimit);
+            buckets.push([
+                "proposed",
+                `Not yet accepted (proposed) — showing ${proposedLimit} of ${proposedLimit + omitted}`,
+                proposed,
+            ]);
+        }
+        else if (proposed.length > 0) {
+            buckets.push(["proposed", "Not yet accepted (proposed)", proposed]);
+        }
+    }
+    for (const [folder, heading, filter] of COMMITTED_BUCKETS) {
+        let scopes = loadScopeVbriefs(join(vbriefDir, folder));
+        if (filter)
+            scopes = scopes.filter(([, vb]) => filter(vb));
+        if (scopes.length > 0)
+            buckets.push([folder, heading, scopes]);
+    }
+    if (buckets.length === 0)
+        return [];
+    const lines = ["## Scope outlook\n"];
+    for (const [folder, heading, scopes] of buckets) {
+        const depMap = crossScopeDepMap(scopes);
+        const ordered = topoSortScopes(scopes, depMap);
+        lines.push(`### ${heading}\n`);
+        if (folder === "proposed") {
+            for (const line of PROPOSED_DISCLAIMER_LINES)
+                lines.push(line, "");
+        }
+        for (const [stem, vbrief] of ordered)
+            lines.push(...renderScopeBlock(stem, vbrief));
+    }
+    return lines;
+}
+/** Legacy wrapper: stakeholder export (no proposed). */
+export function aggregateScopeSection(vbriefDir) {
+    return buildScopeOutlookSection(vbriefDir, { includeProposed: false });
+}
+//# sourceMappingURL=scope-outlook.js.map

package/dist/render/spec-render.js

@@ -1,117 +1,8 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { LIFECYCLE_BUCKETS, RENDERABLE_SPEC_STATUSES, SCOPE_SUMMARY_NARRATIVES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
+import { RENDERABLE_SPEC_STATUSES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
+import { aggregateScopeSection } from "./scope-outlook.js";
 import { validateSpec } from "./spec-validate.js";
-function readEdgeEndpoints(edge) {
-    if (typeof edge !== "object" || edge === null || Array.isArray(edge))
-        return ["", ""];
-    const e = edge;
-    const frm = String(e.from ?? e.source ?? "") || "";
-    const to = String(e.to ?? e.target ?? "") || "";
-    return [frm, to];
-}
-function loadScopeVbriefs(folder) {
-    if (!existsSync(folder))
-        return [];
-    let entries;
-    try {
-        entries = readdirSync(folder)
-            .filter((n) => n.endsWith(".vbrief.json"))
-            .sort();
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const name of entries) {
-        const path = join(folder, name);
-        try {
-            const data = JSON.parse(readFileSync(path, "utf8"));
-            let stem = name;
-            if (stem.endsWith(".vbrief.json"))
-                stem = stem.slice(0, -".vbrief.json".length);
-            out.push([stem, data]);
-        }
-        catch {
-            /* skip malformed */
-        }
-    }
-    return out;
-}
-function scopeId(stem, vbrief) {
-    const plan = vbrief.plan;
-    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
-        const planId = plan.id;
-        if (typeof planId === "string" && planId)
-            return planId;
-    }
-    return stem;
-}
-function crossScopeDepMap(scopes) {
-    const scopeIds = new Set(scopes.map(([stem, vb]) => scopeId(stem, vb)));
-    const depMap = {};
-    for (const [, vbrief] of scopes) {
-        const plan = vbrief.plan;
-        if (typeof plan !== "object" || plan === null || Array.isArray(plan))
-            continue;
-        const edges = plan.edges;
-        if (!Array.isArray(edges))
-            continue;
-        for (const edge of edges) {
-            const [frm, to] = readEdgeEndpoints(edge);
-            if (frm && to && scopeIds.has(frm) && scopeIds.has(to)) {
-                if (!depMap[to])
-                    depMap[to] = [];
-                depMap[to].push(frm);
-            }
-        }
-    }
-    return depMap;
-}
-function topoSortScopes(scopes, depMap) {
-    if (scopes.length === 0)
-        return [];
-    const idByIndex = scopes.map(([stem, vb]) => scopeId(stem, vb));
-    const idToIndex = new Map(idByIndex.map((sid, i) => [sid, i]));
-    const depths = {};
-    const depth = (sid, visited = null) => {
-        if (sid in depths)
-            return depths[sid] ?? 0;
-        const vis = visited ?? new Set();
-        if (vis.has(sid))
-            return 0;
-        vis.add(sid);
-        const deps = (depMap[sid] ?? []).filter((d) => idToIndex.has(d));
-        if (deps.length === 0) {
-            depths[sid] = 0;
-            return 0;
-        }
-        const result = Math.max(...deps.map((d) => depth(d, vis))) + 1;
-        depths[sid] = result;
-        return result;
-    };
-    for (const sid of idByIndex)
-        depth(sid);
-    const orderedIndices = [...idByIndex.keys()].sort((a, b) => (depths[idByIndex[a] ?? ""] ?? 0) - (depths[idByIndex[b] ?? ""] ?? 0) || a - b);
-    return orderedIndices.map((i) => scopes[i]);
-}
-function scopeSummaryNarrative(plan) {
-    const narratives = plan.narratives;
-    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
-        return "";
-    }
-    const narr = narratives;
-    for (const key of SCOPE_SUMMARY_NARRATIVES) {
-        const val = narr[key];
-        if (typeof val === "string" && val.trim())
-            return val.trim();
-    }
-    for (const val of Object.values(narr)) {
-        if (typeof val === "string" && val.trim())
-            return val.trim();
-    }
-    return "";
-}
 function splitAcceptance(value) {
     if (Array.isArray(value)) {
         return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
@@ -131,86 +22,6 @@ function splitAcceptance(value) {
     }
     return parts;
 }
-function itemAcceptance(item) {
-    const narrative = item.narrative;
-    if (typeof narrative !== "object" || narrative === null || Array.isArray(narrative))
-        return [];
-    return splitAcceptance(narrative.Acceptance);
-}
-function renderScopeBlock(stem, vbrief) {
-    const plan = vbrief.plan;
-    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
-        return [];
-    const planObj = plan;
-    const title = String(planObj.title ?? stem);
-    const status = String(planObj.status ?? "");
-    let heading = `### ${stem}: ${title}`;
-    if (status)
-        heading += `  \`[${status}]\``;
-    const lines = [`${heading}\n`];
-    const summary = scopeSummaryNarrative(planObj);
-    if (summary)
-        lines.push(`${summary}\n`);
-    const narratives = planObj.narratives;
-    if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
-        const scopeAcceptance = splitAcceptance(narratives.Acceptance);
-        if (scopeAcceptance.length > 0) {
-            lines.push("**Scope Acceptance**:\n");
-            for (const criterion of scopeAcceptance)
-                lines.push(`- ${criterion}`);
-            lines.push("");
-        }
-    }
-    const items = planObj.items;
-    if (Array.isArray(items) && items.length > 0) {
-        lines.push("**Acceptance**:\n");
-        for (const item of items) {
-            if (typeof item !== "object" || item === null || Array.isArray(item))
-                continue;
-            const itemObj = item;
-            const itemTitle = String(itemObj.title ?? "Untitled");
-            const itemStatus = String(itemObj.status ?? "");
-            let bullet = `- ${itemTitle}`;
-            if (itemStatus)
-                bullet += ` \`[${itemStatus}]\``;
-            lines.push(bullet);
-            for (const criterion of itemAcceptance(itemObj)) {
-                if (criterion !== itemTitle)
-                    lines.push(`  - Acceptance: ${criterion}`);
-            }
-        }
-        lines.push("");
-    }
-    return lines;
-}
-function aggregateScopeSection(vbriefDir) {
-    const buckets = [];
-    for (const [folderName, heading] of LIFECYCLE_BUCKETS) {
-        let scopes = loadScopeVbriefs(join(vbriefDir, folderName));
-        if (folderName === "completed") {
-            scopes = scopes.filter(([, vb]) => {
-                const plan = vb.plan;
-                return (typeof plan === "object" &&
-                    plan !== null &&
-                    !Array.isArray(plan) &&
-                    plan.status === "completed");
-            });
-        }
-        if (scopes.length > 0)
-            buckets.push([folderName, heading, scopes]);
-    }
-    if (buckets.length === 0)
-        return [];
-    const lines = ["## Implementation Plan\n"];
-    for (const [, heading, scopes] of buckets) {
-        const depMap = crossScopeDepMap(scopes);
-        const ordered = topoSortScopes(scopes, depMap);
-        lines.push(`### ${heading}\n`);
-        for (const [stem, vbrief] of ordered)
-            lines.push(...renderScopeBlock(stem, vbrief));
-    }
-    return lines;
-}
 /** Render specification JSON to markdown (mirrors ``scripts/spec_render.render_spec``). */
 export function renderSpec(specPath, outPath, options = {}) {
     const includeScopes = options.includeScopes ?? true;

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

@@ -0,0 +1,12 @@
+/** Generated-spec banner tokens (lockstep with Python ``_precutover.py``). */
+export declare const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
+export declare const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+export declare const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
+export declare const EXPORT_SPEC_PD_BANNER: string;
+/** Narratives excluded from stakeholder SPEC/PRD exports (#2013 Wave 0 §5). */
+export declare const STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS: Set<string>;
+/** Product narrative keys used for migration-fidelity checks (#2005). */
+export declare const PRODUCT_NARRATIVE_KEYS: readonly ["ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "FunctionalRequirements", "NonFunctionalRequirements", "AcceptanceCriteria", "Architecture", "EdgeCases"];
+export declare const PROPOSED_DISCLAIMER_LINES: readonly ["_Scopes in this section are ideas, not approved backlog. Promotion to pending is required before work starts._", "_Nothing here is in-flight or committed delivery scope._"];
+export declare const PROPOSED_STATUS_FILTER: Set<string>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/spec-authority/constants.js

@@ -0,0 +1,34 @@
+/** Generated-spec banner tokens (lockstep with Python ``_precutover.py``). */
+export const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
+export const GENERATED_SPEC_SOURCE_SPEC = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+export const GENERATED_SPEC_SOURCE_PD = "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->";
+export const EXPORT_SPEC_PD_BANNER = "<!-- AUTO-GENERATED by task project:export-spec -- DO NOT EDIT MANUALLY -->\n" +
+    `${GENERATED_SPEC_PURPOSE}\n` +
+    `${GENERATED_SPEC_SOURCE_PD}\n` +
+    "<!-- Regenerate with: task project:export-spec -->\n";
+/** Narratives excluded from stakeholder SPEC/PRD exports (#2013 Wave 0 §5). */
+export const STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS = new Set([
+    "projectconfig",
+    "tech stack",
+    "techstack",
+    "configuration",
+]);
+/** Product narrative keys used for migration-fidelity checks (#2005). */
+export const PRODUCT_NARRATIVE_KEYS = [
+    "ProblemStatement",
+    "Goals",
+    "UserStories",
+    "Requirements",
+    "SuccessMetrics",
+    "FunctionalRequirements",
+    "NonFunctionalRequirements",
+    "AcceptanceCriteria",
+    "Architecture",
+    "EdgeCases",
+];
+export const PROPOSED_DISCLAIMER_LINES = [
+    "_Scopes in this section are ideas, not approved backlog. Promotion to pending is required before work starts._",
+    "_Nothing here is in-flight or committed delivery scope._",
+];
+export const PROPOSED_STATUS_FILTER = new Set(["draft", "proposed"]);
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,5 @@
+export * from "./constants.js";
+export * from "./migration-fidelity.js";
+export * from "./narratives.js";
+export * from "./resolver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/spec-authority/index.js

@@ -0,0 +1,5 @@
+export * from "./constants.js";
+export * from "./migration-fidelity.js";
+export * from "./narratives.js";
+export * from "./resolver.js";
+//# sourceMappingURL=index.js.map

package/dist/spec-authority/migration-fidelity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * #2005 migration-fidelity: when specification.vbrief.json is absent but a
+ * premigrate snapshot exists, require product narratives to land in PD or scopes.
+ */
+export declare function checkSpecMigrationFidelity(projectRoot: string): string[];
+//# sourceMappingURL=migration-fidelity.d.ts.map

package/dist/spec-authority/migration-fidelity.js

@@ -0,0 +1,96 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PRODUCT_NARRATIVE_KEYS } from "./constants.js";
+const LIFECYCLE_SCAN = ["proposed", "pending", "active", "completed", "cancelled"];
+function loadJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function planNarrativeKeys(doc) {
+    const keys = new Set();
+    const plan = doc.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return keys;
+    const narratives = plan.narratives;
+    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives))
+        return keys;
+    for (const [key, val] of Object.entries(narratives)) {
+        if (typeof val === "string" && val.trim())
+            keys.add(key.toLowerCase());
+    }
+    return keys;
+}
+function collectCanonicalNarrativeKeys(vbriefDir) {
+    const keys = new Set();
+    const pdPath = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+    const pd = loadJson(pdPath);
+    if (pd) {
+        for (const k of planNarrativeKeys(pd))
+            keys.add(k);
+    }
+    for (const folder of LIFECYCLE_SCAN) {
+        const dir = join(vbriefDir, folder);
+        if (!existsSync(dir))
+            continue;
+        let names;
+        try {
+            names = readdirSync(dir).filter((n) => n.endsWith(".vbrief.json"));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const doc = loadJson(join(dir, name));
+            if (doc) {
+                for (const k of planNarrativeKeys(doc))
+                    keys.add(k);
+            }
+        }
+    }
+    return keys;
+}
+function premigrateNarrativeKeys(vbriefDir) {
+    const keys = new Set();
+    const premigrate = join(vbriefDir, "specification.premigrate.vbrief.json");
+    const doc = loadJson(premigrate);
+    if (!doc)
+        return keys;
+    for (const k of planNarrativeKeys(doc))
+        keys.add(k);
+    return keys;
+}
+function isProductKey(keyLower) {
+    if (keyLower === "overview")
+        return false;
+    return PRODUCT_NARRATIVE_KEYS.some((p) => p.toLowerCase() === keyLower);
+}
+/**
+ * #2005 migration-fidelity: when specification.vbrief.json is absent but a
+ * premigrate snapshot exists, require product narratives to land in PD or scopes.
+ */
+export function checkSpecMigrationFidelity(projectRoot) {
+    const vbriefDir = join(projectRoot, "vbrief");
+    const specPath = join(vbriefDir, "specification.vbrief.json");
+    if (existsSync(specPath))
+        return [];
+    const premigratePath = join(vbriefDir, "specification.premigrate.vbrief.json");
+    if (!existsSync(premigratePath))
+        return [];
+    const premigrateKeys = premigrateNarrativeKeys(vbriefDir);
+    const productPremigrate = [...premigrateKeys].filter(isProductKey);
+    if (productPremigrate.length === 0)
+        return [];
+    const canonicalKeys = collectCanonicalNarrativeKeys(vbriefDir);
+    const missing = productPremigrate.filter((k) => !canonicalKeys.has(k));
+    if (missing.length === 0)
+        return [];
+    return [
+        `vbrief/specification.vbrief.json is absent but vbrief/specification.premigrate.vbrief.json retains product narratives not found in PROJECT-DEFINITION or lifecycle scope vBRIEFs: ${missing.join(", ")}. ` +
+            "Do not delete the legacy spec without migrating content. Run `task migrate:vbrief` or manually merge narratives into PROJECT-DEFINITION / scope vBRIEFs before removing the premigrate snapshot. See #2005.",
+    ];
+}
+//# sourceMappingURL=migration-fidelity.js.map

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

@@ -0,0 +1,6 @@
+import type { ResolvedSpecAuthority } from "./resolver.js";
+/** Merge product narratives per Wave 0 locked precedence. */
+export declare function resolveExportNarratives(authority: ResolvedSpecAuthority): Record<string, string>;
+export declare function renderNarrativeSections(narratives: Record<string, string>): string[];
+export declare function greenfieldOverviewNonEmpty(authority: ResolvedSpecAuthority): boolean;
+//# sourceMappingURL=narratives.d.ts.map

package/dist/spec-authority/narratives.js

@@ -0,0 +1,84 @@
+import { readFileSync } from "node:fs";
+import { SPECIFICATION_NARRATIVE_KEY_ORDER } from "../render/constants.js";
+import { STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS } from "./constants.js";
+function loadJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function planNarratives(doc) {
+    const plan = doc.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return {};
+    const narratives = plan.narratives;
+    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives))
+        return {};
+    const out = {};
+    for (const [key, val] of Object.entries(narratives)) {
+        if (typeof val === "string")
+            out[key] = val;
+    }
+    return out;
+}
+function isExcludedNarrativeKey(key) {
+    return STAKEHOLDER_EXCLUDED_NARRATIVE_KEYS.has(key.toLowerCase().replace(/\s+/g, ""));
+}
+/** Merge product narratives per Wave 0 locked precedence. */
+export function resolveExportNarratives(authority) {
+    const pd = loadJson(authority.projectDefPath);
+    const pdNarratives = planNarratives(pd);
+    if (authority.kind === "greenfield") {
+        const filtered = {};
+        for (const [key, val] of Object.entries(pdNarratives)) {
+            if (!isExcludedNarrativeKey(key) && val.trim())
+                filtered[key] = val;
+        }
+        return filtered;
+    }
+    const specPath = authority.specPath;
+    if (!specPath)
+        return pdNarratives;
+    const spec = loadJson(specPath);
+    const specNarratives = planNarratives(spec);
+    const merged = {};
+    for (const [key, val] of Object.entries(specNarratives)) {
+        if (!isExcludedNarrativeKey(key) && val.trim())
+            merged[key] = val;
+    }
+    // PD identity additive when missing from spec.
+    const identityHints = ["overview", "architecture", "risksandunknowns", "risks", "unknowns"];
+    for (const [key, val] of Object.entries(pdNarratives)) {
+        if (!val.trim() || isExcludedNarrativeKey(key))
+            continue;
+        const lower = key.toLowerCase().replace(/\s+/g, "");
+        const isIdentity = identityHints.some((h) => lower.includes(h)) || lower === "overview";
+        if (!isIdentity)
+            continue;
+        const specHasKey = Object.keys(merged).some((k) => k.toLowerCase() === lower);
+        if (!specHasKey)
+            merged[key] = val;
+    }
+    return merged;
+}
+export function renderNarrativeSections(narratives) {
+    const lines = [];
+    const rendered = new Set();
+    for (const key of SPECIFICATION_NARRATIVE_KEY_ORDER) {
+        const val = narratives[key];
+        if (val?.trim()) {
+            lines.push(`## ${key}\n`, `${val}\n`);
+            rendered.add(key);
+        }
+    }
+    for (const key of Object.keys(narratives).sort()) {
+        if (rendered.has(key) || !narratives[key]?.trim())
+            continue;
+        lines.push(`## ${key}\n`, `${narratives[key]}\n`);
+    }
+    return lines;
+}
+export function greenfieldOverviewNonEmpty(authority) {
+    const pd = loadJson(authority.projectDefPath);
+    const narratives = planNarratives(pd);
+    const overview = Object.entries(narratives).find(([k]) => k.toLowerCase() === "overview");
+    return overview !== undefined && overview[1].trim().length > 0;
+}
+//# sourceMappingURL=narratives.js.map

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

@@ -0,0 +1,15 @@
+export type SpecAuthorityKind = "full-spec" | "greenfield";
+export interface ResolvedSpecAuthority {
+    readonly kind: SpecAuthorityKind;
+    readonly projectRoot: string;
+    readonly vbriefDir: string;
+    readonly projectDefPath: string;
+    readonly specPath: string | null;
+    readonly banner: string;
+}
+export declare function resolveSpecAuthority(projectRoot: string): ResolvedSpecAuthority | null;
+export declare function readSpecMarkdown(projectRoot: string): string;
+export declare function isFullSpecState(projectRoot: string): boolean;
+export declare function isGreenfieldSpecExport(projectRoot: string): boolean;
+export declare function isCurrentGeneratedSpecification(projectRoot: string): boolean;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/spec-authority/resolver.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SPEC_RENDER_BANNER } from "../render/constants.js";
+import { EXPORT_SPEC_PD_BANNER, GENERATED_SPEC_PURPOSE, GENERATED_SPEC_SOURCE_PD, GENERATED_SPEC_SOURCE_SPEC, } from "./constants.js";
+const SPEC_REL = join("vbrief", "specification.vbrief.json");
+const PD_REL = join("vbrief", "PROJECT-DEFINITION.vbrief.json");
+export function resolveSpecAuthority(projectRoot) {
+    const root = projectRoot;
+    const vbriefDir = join(root, "vbrief");
+    const projectDefPath = join(root, PD_REL);
+    if (!existsSync(projectDefPath))
+        return null;
+    const specPath = join(root, SPEC_REL);
+    const hasSpec = existsSync(specPath);
+    const kind = hasSpec ? "full-spec" : "greenfield";
+    const banner = kind === "full-spec" ? SPEC_RENDER_BANNER : EXPORT_SPEC_PD_BANNER;
+    return {
+        kind,
+        projectRoot: root,
+        vbriefDir,
+        projectDefPath,
+        specPath: hasSpec ? specPath : null,
+        banner,
+    };
+}
+export function readSpecMarkdown(projectRoot) {
+    const path = join(projectRoot, "SPECIFICATION.md");
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+export function isFullSpecState(projectRoot) {
+    const authority = resolveSpecAuthority(projectRoot);
+    if (authority?.kind !== "full-spec")
+        return false;
+    const specMd = readSpecMarkdown(projectRoot);
+    return specMd.includes(GENERATED_SPEC_PURPOSE) && specMd.includes(GENERATED_SPEC_SOURCE_SPEC);
+}
+export function isGreenfieldSpecExport(projectRoot) {
+    const authority = resolveSpecAuthority(projectRoot);
+    if (authority?.kind !== "greenfield")
+        return false;
+    const specMd = readSpecMarkdown(projectRoot);
+    return specMd.includes(GENERATED_SPEC_PURPOSE) && specMd.includes(GENERATED_SPEC_SOURCE_PD);
+}
+export function isCurrentGeneratedSpecification(projectRoot) {
+    return isFullSpecState(projectRoot) || isGreenfieldSpecExport(projectRoot);
+}
+//# sourceMappingURL=resolver.js.map

package/dist/validate-content/validate-strategy-output.js

@@ -1,17 +1,9 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { checkSpecMigrationFidelity } from "../spec-authority/migration-fidelity.js";
+import { isFullSpecState } from "../spec-authority/resolver.js";
 import { isDatePrefixedVbriefFilename } from "./filename.js";
-const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
-const GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
 const LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
-function readTextSafe(path) {
-    try {
-        return readFileSync(path, "utf8");
-    }
-    catch {
-        return "";
-    }
-}
 function isDirSafe(path) {
     try {
         return statSync(path).isDirectory();
@@ -30,20 +22,6 @@ function isDeftFrameworkRoot(projectRoot) {
         (isDirSafe(join(projectRoot, "content", "strategies")) ||
             isDirSafe(join(projectRoot, "strategies"))));
 }
-function hasCompleteLifecycle(vbriefDir) {
-    return LIFECYCLE_DIRS.every((folder) => {
-        const p = join(vbriefDir, folder);
-        return existsSync(p) && statSync(p).isDirectory();
-    });
-}
-function isPostCutoverFullSpecState(projectRoot) {
-    const vbriefDir = join(projectRoot, "vbrief");
-    const specMd = readTextSafe(join(projectRoot, "SPECIFICATION.md"));
-    return (existsSync(join(vbriefDir, "PROJECT-DEFINITION.vbrief.json")) &&
-        hasCompleteLifecycle(vbriefDir) &&
-        specMd.includes(GENERATED_SPEC_PURPOSE) &&
-        specMd.includes(GENERATED_SPEC_SOURCE));
-}
 /** Pure validator returning error strings (empty == pass). */
 export function validateStrategyOutput(projectRoot, strict = false) {
     const root = resolve(projectRoot);
@@ -63,7 +41,7 @@ export function validateStrategyOutput(projectRoot, strict = false) {
             "(see v0-20-contract.md and task project:render).");
     }
     const specLegacy = join(vbriefDir, "specification.vbrief.json");
-    if (existsSync(specLegacy) && !isDeftFrameworkRoot(root) && !isPostCutoverFullSpecState(root)) {
+    if (existsSync(specLegacy) && !isDeftFrameworkRoot(root) && !isFullSpecState(root)) {
         errors.push("Legacy artifact vbrief/specification.vbrief.json present. " +
             "v0.20 strategies MUST NOT dual-write the old specification.vbrief.json " +
             "alongside scope vBRIEFs in the lifecycle folders. " +
@@ -85,6 +63,7 @@ export function validateStrategyOutput(projectRoot, strict = false) {
             }
         }
     }
+    errors.push(...checkSpecMigrationFidelity(root));
     return errors;
 }
 const FAILURE_HEADER = "❌ Strategy output shape validation FAILED (v0.20 contract gate)";

package/dist/vbrief-validate/main.js

@@ -122,6 +122,11 @@ export function cmdVbriefValidate(argv) {
     if (argv[0] === "conformance") {
         return runConformance(argv.slice(1));
     }
+    if (argv.includes("--staged") ||
+        (argv.includes("--all") &&
+            !argv.some((a) => a === "--vbrief-dir" || a.startsWith("--vbrief-dir=")))) {
+        return runConformance(argv);
+    }
     return runValidate(argv);
 }
 //# sourceMappingURL=main.js.map

package/dist/vbrief-validate/precutover.d.ts

@@ -1,35 +1,21 @@
+import { isFullSpecState, isGreenfieldSpecExport } from "../spec-authority/resolver.js";
 import { DEPRECATION_SENTINEL } from "../vbrief-build/constants.js";
 export { DEPRECATION_SENTINEL as DEPRECATED_REDIRECT_SENTINEL };
 export declare function missingLifecycleFolders(projectRoot: string): string[];
 /** Return true when markdown content is a migration redirect stub. */
 export declare function isDeprecationRedirect(content: string): boolean;
+/** Full-spec generated export (specification.vbrief.json source line). */
 export declare function isGeneratedSpecificationExport(projectRoot: string, content: string): boolean;
-/** Return true for a fully current ``task spec:render`` root export. */
+/** Return true for a fully current generated spec export (full-spec or greenfield). */
 export declare function isCurrentGeneratedSpecification(projectRoot: string, content: string): boolean;
 /** Return root artifact filenames that are legacy pre-v0.20 inputs (#793 / migrate preflight). */
 export declare function detectPreCutoverLegacy(projectRoot: string): string[];
 /** Structured result of a pre-cutover (pre-v0.20 document model) probe. */
 export interface PrecutoverDetection {
-    /** True when any legacy pre-v0.20 artifact still needs migration. */
     preCutover: boolean;
-    /** Human-readable reasons; empty when the project is on the current model. */
     reasons: string[];
 }
-/**
- * Detect whether ``projectRoot`` still carries pre-v0.20 (pre-cutover) document-model
- * artifacts that need migration. Mirrors the AGENTS.md "Pre-Cutover Check" rule and the
- * legacy ``scripts/_precutover.py`` helper: a project is pre-cutover when any of the
- * following hold:
- *
- * - ``SPECIFICATION.md`` exists and is neither a deprecation redirect nor a current
- *   generated spec export;
- * - ``PROJECT.md`` exists and is not a deprecation redirect;
- * - ``vbrief/`` exists but is missing one or more lifecycle folders.
- */
 export declare function detectPreCutover(projectRoot: string): PrecutoverDetection;
-/**
- * Render the single-line pre-cutover status string surfaced by ``deft doctor``.
- * Flags the migration-needed state with reasons, or reports a clean current-model state.
- */
 export declare function renderPrecutoverLine(projectRoot: string): string;
+export { isFullSpecState, isGreenfieldSpecExport };
 //# sourceMappingURL=precutover.d.ts.map

package/dist/vbrief-validate/precutover.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { GENERATED_SPEC_PURPOSE, GENERATED_SPEC_SOURCE_SPEC } from "../spec-authority/constants.js";
+import { isFullSpecState, isGreenfieldSpecExport } from "../spec-authority/resolver.js";
 import { DEPRECATION_SENTINEL } from "../vbrief-build/constants.js";
 export { DEPRECATION_SENTINEL as DEPRECATED_REDIRECT_SENTINEL };
 const DEPRECATION_REDIRECT_PURPOSE = "<!-- Purpose: deprecation redirect -->";
-const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
-const GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
 const SPEC_SOURCE_RELPATH = join("vbrief", "specification.vbrief.json");
 const LIFECYCLE_FOLDERS = ["proposed", "pending", "active", "completed", "cancelled"];
 export function missingLifecycleFolders(projectRoot) {
@@ -18,14 +18,19 @@ function hasCompleteLifecycle(projectRoot) {
 export function isDeprecationRedirect(content) {
     return content.includes(DEPRECATION_SENTINEL) || content.includes(DEPRECATION_REDIRECT_PURPOSE);
 }
+/** Full-spec generated export (specification.vbrief.json source line). */
 export function isGeneratedSpecificationExport(projectRoot, content) {
     return (content.includes(GENERATED_SPEC_PURPOSE) &&
-        content.includes(GENERATED_SPEC_SOURCE) &&
+        content.includes(GENERATED_SPEC_SOURCE_SPEC) &&
         existsSync(join(projectRoot, SPEC_SOURCE_RELPATH)));
 }
-/** Return true for a fully current ``task spec:render`` root export. */
+/** Return true for a fully current generated spec export (full-spec or greenfield). */
 export function isCurrentGeneratedSpecification(projectRoot, content) {
-    return isGeneratedSpecificationExport(projectRoot, content) && hasCompleteLifecycle(projectRoot);
+    if (!hasCompleteLifecycle(projectRoot))
+        return false;
+    if (isGeneratedSpecificationExport(projectRoot, content))
+        return true;
+    return isGreenfieldSpecExport(projectRoot);
 }
 function isFile(path) {
     try {
@@ -46,8 +51,11 @@ function safeReadText(path) {
 function rootMarkdownIsLegacy(projectRoot, filename, content) {
     if (isDeprecationRedirect(content))
         return false;
-    if (filename === "SPECIFICATION.md" && isGeneratedSpecificationExport(projectRoot, content)) {
-        return false;
+    if (filename === "SPECIFICATION.md") {
+        if (isGeneratedSpecificationExport(projectRoot, content))
+            return false;
+        if (isGreenfieldSpecExport(projectRoot))
+            return false;
     }
     return filename === "SPECIFICATION.md" || filename === "PROJECT.md";
 }
@@ -65,17 +73,6 @@ export function detectPreCutoverLegacy(projectRoot) {
     }
     return legacy;
 }
-/**
- * Detect whether ``projectRoot`` still carries pre-v0.20 (pre-cutover) document-model
- * artifacts that need migration. Mirrors the AGENTS.md "Pre-Cutover Check" rule and the
- * legacy ``scripts/_precutover.py`` helper: a project is pre-cutover when any of the
- * following hold:
- *
- * - ``SPECIFICATION.md`` exists and is neither a deprecation redirect nor a current
- *   generated spec export;
- * - ``PROJECT.md`` exists and is not a deprecation redirect;
- * - ``vbrief/`` exists but is missing one or more lifecycle folders.
- */
 export function detectPreCutover(projectRoot) {
     const reasons = [];
     const specPath = join(projectRoot, "SPECIFICATION.md");
@@ -101,17 +98,14 @@ export function detectPreCutover(projectRoot) {
     }
     return { preCutover: reasons.length > 0, reasons };
 }
-/**
- * Render the single-line pre-cutover status string surfaced by ``deft doctor``.
- * Flags the migration-needed state with reasons, or reports a clean current-model state.
- */
 export function renderPrecutoverLine(projectRoot) {
     const { preCutover, reasons } = detectPreCutover(projectRoot);
     if (!preCutover) {
         return "Pre-cutover: none -- project is on the current vBRIEF document model.";
     }
-    // Collapse any embedded newlines so the status line stays a single line (CWE-116).
     const summary = reasons.join("; ").replace(/\r?\n/g, " ");
     return `Pre-cutover: migration needed -- ${summary}. Run \`deft migrate:vbrief\` to migrate.`;
 }
+// Re-export for classify callers (#2013).
+export { isFullSpecState, isGreenfieldSpecExport };
 //# sourceMappingURL=precutover.js.map

package/dist/verify-env/verify-hooks-installed.d.ts

@@ -5,9 +5,9 @@ export interface EvaluateResult {
     readonly stream: OutputStream;
 }
 export declare const REQUIRED_HOOKS: readonly ["pre-commit", "pre-push"];
-export declare const SCRIPTS_PROBE = "preflight_branch.py";
-export declare const GATE_SCRIPTS: readonly ["preflight_branch.py", "verify_encoding.py", "preflight_gh.py"];
-export declare const SCRIPTS_DIR_CANDIDATES: readonly ["scripts", ".deft/core/scripts", "deft/scripts"];
+/** Substrings each hook must contain when it dispatches through the deft CLI (#2049). */
+export declare const PRE_COMMIT_DEFT_COMMANDS: readonly ["verify:branch", "verify:encoding"];
+export declare const PRE_PUSH_DEFT_COMMANDS: readonly ["preflight-gh"];
 export type GitConfigReader = (projectRoot: string) => {
     hooksPath: string | null;
     error: string | null;

package/dist/verify-env/verify-hooks-installed.js

@@ -1,14 +1,18 @@
 import * as childProcess from "node:child_process";
-import { accessSync, constants, statSync } from "node:fs";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 export const REQUIRED_HOOKS = ["pre-commit", "pre-push"];
-export const SCRIPTS_PROBE = "preflight_branch.py";
-export const GATE_SCRIPTS = [
-    "preflight_branch.py",
-    "verify_encoding.py",
-    "preflight_gh.py",
+/** Substrings each hook must contain when it dispatches through the deft CLI (#2049). */
+export const PRE_COMMIT_DEFT_COMMANDS = ["verify:branch", "verify:encoding"];
+export const PRE_PUSH_DEFT_COMMANDS = ["preflight-gh"];
+/** Patterns that indicate legacy Python-dispatched hooks (pre-#2049). */
+const LEGACY_HOOK_PATTERNS = [
+    /\.py\b/i,
+    /\bpython\b/i,
+    /\bdeft_py\b/,
+    /\bSCRIPTS_DIR\b/,
+    /\bpreflight_branch\.py\b/,
 ];
-export const SCRIPTS_DIR_CANDIDATES = ["scripts", ".deft/core/scripts", "deft/scripts"];
 function defaultGitConfigReader(projectRoot) {
     try {
         const stdout = childProcess.execFileSync("git", ["-C", projectRoot, "config", "--get", "core.hooksPath"], {
@@ -45,15 +49,6 @@ function isDirectory(path) {
         return false;
     }
 }
-function resolveScriptsDir(projectRoot) {
-    for (const rel of SCRIPTS_DIR_CANDIDATES) {
-        const candidate = join(projectRoot, rel);
-        if (isFile(join(candidate, SCRIPTS_PROBE))) {
-            return candidate;
-        }
-    }
-    return null;
-}
 function isPosix(platform) {
     return platform !== "win32";
 }
@@ -66,6 +61,36 @@ function hookExecutable(hookPath) {
         return false;
     }
 }
+function readHookContent(hookPath) {
+    try {
+        return readFileSync(hookPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function usesLegacyPythonDispatch(content) {
+    return LEGACY_HOOK_PATTERNS.some((pattern) => pattern.test(content));
+}
+function hookInvokesDeftCli(content, requiredCommands) {
+    if (!/\bdeft\b/.test(content))
+        return false;
+    if (usesLegacyPythonDispatch(content))
+        return false;
+    return requiredCommands.every((cmd) => content.includes(cmd));
+}
+function validateHookContent(hookName, content, requiredCommands) {
+    if (content === null) {
+        return `${hookName}: unreadable hook file`;
+    }
+    if (usesLegacyPythonDispatch(content)) {
+        return `${hookName}: still dispatches through Python scripts (expected deft CLI only, #2049)`;
+    }
+    if (!hookInvokesDeftCli(content, requiredCommands)) {
+        return `${hookName}: missing required deft CLI gate(s): ${requiredCommands.join(", ")}`;
+    }
+    return null;
+}
 /** Pure evaluator mirroring scripts/verify_hooks_installed.py::evaluate. */
 export function evaluate(projectRoot, options = {}) {
     const root = resolve(projectRoot);
@@ -132,30 +157,37 @@ export function evaluate(projectRoot, options = {}) {
             };
         }
     }
-    const scriptsDir = resolveScriptsDir(root);
-    if (scriptsDir === null) {
+    const preCommitIssue = validateHookContent("pre-commit", readHookContent(join(hooksDir, "pre-commit")), PRE_COMMIT_DEFT_COMMANDS);
+    if (preCommitIssue) {
+        return {
+            code: 1,
+            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${preCommitIssue} (#2049).\n` +
+                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
+            stream: "stderr",
+        };
+    }
+    const prePushContent = readHookContent(join(hooksDir, "pre-push"));
+    const prePushIssue = validateHookContent("pre-push", prePushContent, PRE_PUSH_DEFT_COMMANDS);
+    if (prePushIssue) {
         return {
             code: 1,
-            message: "❌ deft hooks wired but NON-FUNCTIONAL: the gate scripts cannot be resolved.\n" +
-                `  Looked for ${SCRIPTS_PROBE} under: ${SCRIPTS_DIR_CANDIDATES.join(", ")} (relative to ${root}).\n` +
-                "  Recovery: re-run the deft installer so the payload is present.",
+            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${prePushIssue} (#2049).\n` +
+                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
             stream: "stderr",
         };
     }
-    const missingScripts = GATE_SCRIPTS.filter((s) => !isFile(join(scriptsDir, s)));
-    if (missingScripts.length > 0) {
+    if (prePushContent?.includes("verify:branch")) {
         return {
             code: 1,
-            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${scriptsDir} is missing ` +
-                `gate script(s): ${missingScripts.join(", ")} (#1463 false-green).\n` +
-                "  Recovery: re-run the deft installer to restore the payload.",
+            message: "❌ deft hooks wired but NON-FUNCTIONAL: pre-push must not invoke verify:branch (#1814).\n" +
+                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
             stream: "stderr",
         };
     }
     return {
         code: 0,
         message: `✓ deft hooks installed and functional: core.hooksPath=${hooksPath}, ` +
-            `hooks ${REQUIRED_HOOKS.join(", ")} present, gate scripts resolve under ${scriptsDir}.`,
+            `hooks ${REQUIRED_HOOKS.join(", ")} present and dispatch via deft CLI (#2049).`,
         stream: "stdout",
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -221,8 +221,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.60.0",
-    "@deftai/directive-types": "^0.60.0"
+    "@deftai/directive-content": "^0.61.0",
+    "@deftai/directive-types": "^0.61.0"
   },
   "scripts": {
     "build": "tsc -b",