@deftai/directive-core 0.60.0 → 0.61.1

package/dist/init-deposit/refresh.js

@@ -7,13 +7,14 @@
  *
  * Refs #1942, #1430, #1671.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { DEV_FALLBACK } from "../platform/constants.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
@@ -67,6 +68,46 @@ function readRecordedDepositVersion(deftDir) {
         return null;
     }
 }
+/** Prior `managed_by` provenance sentinel from the deposit manifest, if any (#2056). */
+function readRecordedManagedBy(deftDir) {
+    const manifestPath = join(deftDir, "VERSION");
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const value = (parseInstallManifest(readFileSync(manifestPath, "utf8")).managed_by ?? "").trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Regenerate the bare `.deft-version` derivative from the deposited content
+ * version in the same transaction as the payload swap (#2055). The canonical
+ * marker lives at `vbrief/.deft-version`; fall back to the project root only
+ * when `vbrief/` is absent. Never persist the dev fallback.
+ */
+function syncBareVersionMarker(projectDir, version) {
+    const normalized = normalizeVersion(version);
+    if (!normalized || normalized === DEV_FALLBACK)
+        return;
+    const vbriefDir = join(projectDir, "vbrief");
+    let targetDir = projectDir;
+    try {
+        if (statSync(vbriefDir).isDirectory())
+            targetDir = vbriefDir;
+    }
+    catch {
+        // vbrief/ absent — write the root-level derivative instead
+    }
+    try {
+        mkdirSync(targetDir, { recursive: true });
+        writeFileSync(join(targetDir, ".deft-version"), `${normalized}\n`, "utf8");
+    }
+    catch {
+        // best-effort, mirrors install-upgrade marker write
+    }
+}
 function isInstallerManagedPath(path) {
     if (INSTALLER_MANAGED_EXACT.has(path))
         return true;
@@ -208,6 +249,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const readPackageVersion = seams.readPackageVersion ?? readCorePackageVersion;
     const contentRoot = await resolveContent();
     const previousDepositVersion = readRecordedDepositVersion(deftDir);
+    const previousManagedBy = readRecordedManagedBy(deftDir);
     const engineVersion = readEngine();
     const contentVersion = readContentPackageVersion(contentRoot, readPackageVersion);
     const versionSkewNotice = buildVersionSkewNotice(engineVersion, contentVersion, previousDepositVersion);
@@ -221,8 +263,13 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         installRoot: CANONICAL_INSTALL_ROOT,
         fetchedAt: nowIso(),
         fetchedBy: "directive-update",
+        ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
     };
     writeInstallManifest(projectDir, deftDir, manifestFields);
+    // #2055: regenerate the bare .deft-version derivative so it agrees with the
+    // freshly written manifest tag (otherwise doctor's manifest-agreement check
+    // fails and the operator must hand-edit the marker).
+    syncBareVersionMarker(projectDir, contentVersion);
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     await depositNeutralization(projectDir, io);
     const readPorcelain = seams.gitPorcelain ?? gitPorcelain;

package/dist/init-deposit/scaffold.d.ts

@@ -18,6 +18,13 @@ export interface InstallManifestFields {
     installRoot: string;
     fetchedAt: string;
     fetchedBy: string;
+    /**
+     * Provenance sentinel (#2056). When the prior manifest was stamped
+     * `managed_by: 'npm'` by the npm-migration path, callers thread it through a
+     * manifest rebuild so a routine `directive update` / `install-upgrade` does not
+     * regress provenance and re-arm the doctor signpost.
+     */
+    managedBy?: string;
 }
 export declare function buildInstallManifestText(fields: InstallManifestFields): string;
 export declare function writeInstallManifest(projectDir: string, deftDir: string, fields: InstallManifestFields): string;

package/dist/init-deposit/scaffold.js

@@ -187,12 +187,17 @@ export function buildInstallManifestText(fields) {
         effectiveTag = `v${effectiveTag}`;
     }
     const effectiveRef = fields.ref || effectiveTag;
-    return (`ref: '${effectiveRef}'\n` +
+    let body = `ref: '${effectiveRef}'\n` +
         `sha: '${fields.sha}'\n` +
         `tag: '${effectiveTag}'\n` +
         `install_root: '${fields.installRoot}'\n` +
         `fetched_at: '${fields.fetchedAt}'\n` +
-        `fetched_by: '${fields.fetchedBy}'\n`);
+        `fetched_by: '${fields.fetchedBy}'\n`;
+    const managedBy = fields.managedBy?.trim();
+    if (managedBy) {
+        body += `managed_by: '${managedBy}'\n`;
+    }
+    return body;
 }
 export function writeInstallManifest(projectDir, deftDir, fields) {
     const installRoot = fields.installRoot ||

package/dist/install-upgrade/index.js

@@ -1,11 +1,75 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { readCorePackageVersion } from "../engine-version.js";
 import { buildInstallManifestText, CANONICAL_INSTALL_ROOT, } from "../init-deposit/scaffold.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { resolveVersion } from "../platform/resolve-version.js";
 import { detectPreCutoverLegacy } from "../vbrief-validate/precutover.js";
+const ENGINE_PACKAGE_FALLBACK = "0.0.0";
+/**
+ * Resolve the framework version for an upgrade (#2053).
+ *
+ * `resolveVersion({ frameworkRoot })` reads env / install-manifest / .deft-version
+ * / git against the *engine* framework root. When `deft install-upgrade` runs from
+ * a global npm install, that root is the npm package directory — which carries no
+ * install manifest, no bare marker, and is not its own git repo — so the chain
+ * dead-ends at `0.0.0-dev`. Recover by auto-detecting the *consumer project's*
+ * deposited manifest, then fall back to the engine package.json version, before
+ * surrendering to the dev fallback.
+ */
+function resolveUpgradeVersion(frameworkRoot, projectRoot) {
+    const primary = resolveVersion({ frameworkRoot });
+    if (primary !== DEV_FALLBACK)
+        return primary;
+    const manifestPath = locateManifest(projectRoot, null);
+    if (manifestPath) {
+        try {
+            const tag = manifestTagToVersion(parseInstallManifest(readFileSync(manifestPath, "utf8")));
+            if (tag)
+                return tag;
+        }
+        catch {
+            // fall through to package.json fallback
+        }
+    }
+    const pkgVersion = readCorePackageVersion();
+    if (pkgVersion && pkgVersion !== ENGINE_PACKAGE_FALLBACK)
+        return pkgVersion;
+    return DEV_FALLBACK;
+}
+/**
+ * The consumer's deposited framework install root (`.deft/core`, then legacy
+ * `deft/`), if present. Used as the AGENTS.md render root and manifest target so
+ * the refresh renders from the *deposited* templates that match the installed
+ * payload -- not the (possibly newer) templates bundled in a global npm engine.
+ */
+function resolveInstallRoot(projectRoot) {
+    for (const candidate of [join(projectRoot, ".deft", "core"), join(projectRoot, "deft")]) {
+        try {
+            if (statSync(candidate).isDirectory())
+                return candidate;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+/** Prior `managed_by` provenance sentinel from an install manifest, if any (#2056). */
+function readManagedByAt(installRoot) {
+    const manifestPath = join(installRoot, "VERSION");
+    if (!existsSync(manifestPath) || !statSync(manifestPath).isFile())
+        return null;
+    try {
+        const value = (parseInstallManifest(readFileSync(manifestPath, "utf8")).managed_by ?? "").trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
 function versionMarkerPaths(projectRoot) {
     return [join(projectRoot, "vbrief", ".deft-version"), join(projectRoot, ".deft-version")];
 }
@@ -46,6 +110,7 @@ function deriveInstallRootString(installRoot, projectRoot) {
 function writeInstallManifestAt(installRoot, projectRoot, version) {
     if (version.replace(/^v/, "") === DEV_FALLBACK)
         return null;
+    const priorManagedBy = readManagedByAt(installRoot);
     const fields = {
         ref: version.startsWith("v") ? version : `v${version}`,
         sha: "content-package",
@@ -53,6 +118,7 @@ function writeInstallManifestAt(installRoot, projectRoot, version) {
         installRoot: deriveInstallRootString(installRoot, projectRoot),
         fetchedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
         fetchedBy: "deft-upgrade",
+        ...(priorManagedBy ? { managedBy: priorManagedBy } : {}),
     };
     try {
         mkdirSync(installRoot, { recursive: true });
@@ -111,13 +177,19 @@ function runAgentsRefresh(projectRoot, frameworkRoot, io) {
 export function runInstallUpgrade(args, io) {
     const projectRoot = resolve(args.projectRoot);
     const frameworkRoot = resolve(args.frameworkRoot);
-    const version = resolveVersion({ frameworkRoot });
+    const version = resolveUpgradeVersion(frameworkRoot, projectRoot);
     const normalizedVersion = version.startsWith("v") ? version.slice(1) : version;
+    // Render AGENTS.md from the deposited install root so the managed section
+    // matches the installed payload, not the engine's bundled templates (which a
+    // global npm `deft` may carry at a different version). Falls back to the engine
+    // framework root when no deposit is present.
+    const installRoot = resolveInstallRoot(projectRoot);
+    const agentsRoot = installRoot ?? frameworkRoot;
     io.writeOut(`Deft CLI v${normalizedVersion} - Upgrade\n\n`);
     const recorded = readVersionMarker(projectRoot);
     if (recorded === normalizedVersion) {
         io.writeOut(`Project already at ${normalizedVersion}. Nothing to do.\n`);
-        return runAgentsRefresh(projectRoot, frameworkRoot, io);
+        return runAgentsRefresh(projectRoot, agentsRoot, io);
     }
     const legacy = detectPreCutoverLegacy(projectRoot);
     if (legacy.length > 0) {
@@ -126,21 +198,25 @@ export function runInstallUpgrade(args, io) {
     const vbriefDir = join(projectRoot, "vbrief");
     const targetDir = existsSync(vbriefDir) && statSync(vbriefDir).isDirectory() ? vbriefDir : projectRoot;
     writeVersionMarker(targetDir, normalizedVersion);
-    let writtenManifestPath = null;
-    for (const installCandidate of [join(projectRoot, ".deft", "core"), join(projectRoot, "deft")]) {
-        if (existsSync(installCandidate) && statSync(installCandidate).isDirectory()) {
-            writtenManifestPath = writeInstallManifestAt(installCandidate, projectRoot, normalizedVersion);
-            break;
-        }
-    }
+    const writtenManifestPath = installRoot !== null
+        ? writeInstallManifestAt(installRoot, projectRoot, normalizedVersion)
+        : null;
     migrateLegacyInstallManifest(projectRoot, writtenManifestPath);
-    if (recorded === null) {
+    if (normalizedVersion === DEV_FALLBACK) {
+        // #2053: the marker + manifest writers above no-op on the dev fallback, so do
+        // not claim a marker update that never happened.
+        io.writeOut("Could not resolve a published framework version (resolved 0.0.0-dev); " +
+            ".deft-version marker and install manifest were left unchanged. On a consumer " +
+            "install, ensure <project>/.deft/core/VERSION carries a real tag, or upgrade the " +
+            "engine with `npm i -g @deftai/directive@latest`.\n");
+    }
+    else if (recorded === null) {
         io.writeOut(`Recorded framework version ${normalizedVersion} in .deft-version.\n`);
     }
     else {
         io.writeOut(`Updated .deft-version from ${recorded} to ${normalizedVersion}.\n`);
     }
     io.writeOut("If legacy SPECIFICATION.md or PROJECT.md content remains, run `task migrate:vbrief` to complete the upgrade.\n");
-    return runAgentsRefresh(projectRoot, frameworkRoot, io);
+    return runAgentsRefresh(projectRoot, agentsRoot, io);
 }
 //# sourceMappingURL=index.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,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