@deftai/directive-core 0.61.0 → 0.61.2

package/dist/init-deposit/init-deposit.js

@@ -14,6 +14,7 @@ import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
+import { printMigrateNudgeIfNeeded } from "./migrate.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeAgentsSkills, writeConsumerGitHooks, writeConsumerVbrief, writeInstallManifest, } from "./scaffold.js";
 export function parseInitArgv(canonicalArgv, userArgv = []) {
     const args = [...canonicalArgv, ...userArgv];
@@ -109,6 +110,7 @@ export function printNextSteps(result, io) {
     io.printf("  2. Deft skill auto-discovery is partially implemented — if your agent doesn't\n");
     io.printf('     start setup automatically, tell it: "Use AGENTS.md"\n');
     io.printf("  3. On first session, the agent will guide you through creating USER.md and PROJECT-DEFINITION.vbrief.json\n");
+    printMigrateNudgeIfNeeded(result.projectDir, io);
     io.printf("\n");
 }
 export async function runInitDeposit(args, io, seams = {}) {

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

@@ -85,4 +85,13 @@ export interface RunMigrateCliOptions {
  * stderr; config errors print to stderr; success prints to stdout.
  */
 export declare function runMigrateCli(options: RunMigrateCliOptions): number;
+/** One-line nudge for init/update/session completion when provenance is unstamped (#2059). */
+export declare const MIGRATE_COMPLETION_NUDGE = "[deft] One-time: run `directive migrate` to stamp npm provenance (idempotent). See content/UPGRADING.md.";
+/** True when a canonical-vendored deposit exists and lacks the npm-managed sentinel. */
+export declare function shouldEmitMigrateNudge(projectRoot: string, seams?: Pick<MigrateSeams, "isFile" | "readText">): boolean;
+export interface MigrateNudgeIo {
+    printf: (text: string) => void;
+}
+/** Prints {@link MIGRATE_COMPLETION_NUDGE} when {@link shouldEmitMigrateNudge} is true. */
+export declare function printMigrateNudgeIfNeeded(projectRoot: string, io: MigrateNudgeIo, seams?: Pick<MigrateSeams, "isFile" | "readText">): void;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/init-deposit/migrate.js

@@ -193,4 +193,27 @@ export function runMigrateCli(options) {
     }
     return result.exitCode;
 }
+/** One-line nudge for init/update/session completion when provenance is unstamped (#2059). */
+export const MIGRATE_COMPLETION_NUDGE = "[deft] One-time: run `directive migrate` to stamp npm provenance (idempotent). See content/UPGRADING.md.";
+/** True when a canonical-vendored deposit exists and lacks the npm-managed sentinel. */
+export function shouldEmitMigrateNudge(projectRoot, seams = {}) {
+    const isFile = seams.isFile ?? existsSync;
+    const readText = seams.readText ?? defaultReadText;
+    const manifestPath = detectCanonicalVendoredManifest(projectRoot, isFile);
+    if (manifestPath === null)
+        return false;
+    const text = readText(manifestPath);
+    if (text === null)
+        return false;
+    const manifest = parseInstallManifest(text);
+    if (Object.keys(manifest).length === 0)
+        return false;
+    return !isNpmManaged(manifest);
+}
+/** Prints {@link MIGRATE_COMPLETION_NUDGE} when {@link shouldEmitMigrateNudge} is true. */
+export function printMigrateNudgeIfNeeded(projectRoot, io, seams = {}) {
+    if (shouldEmitMigrateNudge(projectRoot, seams)) {
+        io.printf(`\n${MIGRATE_COMPLETION_NUDGE}\n`);
+    }
+}
 //# sourceMappingURL=migrate.js.map

package/dist/init-deposit/refresh.js

@@ -7,16 +7,18 @@
  *
  * 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";
+import { printMigrateNudgeIfNeeded } from "./migrate.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
 const INSTALLER_MANAGED_EXACT = new Set([
     "AGENTS.md",
@@ -67,6 +69,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;
@@ -190,6 +232,7 @@ export function printUpdateComplete(result, io) {
     if (result.versionSkewNotice) {
         io.printf(`\n${result.versionSkewNotice}\n`);
     }
+    printMigrateNudgeIfNeeded(result.projectDir, io);
     io.printf("\n");
 }
 export async function runRefreshDeposit(args, io, seams = {}) {
@@ -208,6 +251,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 +265,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/session/session-start.js

@@ -1,4 +1,6 @@
 import { randomUUID } from "node:crypto";
+import { runningInsideDeftRepo } from "../doctor/paths.js";
+import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -263,6 +265,9 @@ export function runSessionStart(projectRoot, options = {}) {
             lines.push(message);
         }
     }
+    if (!runningInsideDeftRepo(projectRoot) && shouldEmitMigrateNudge(projectRoot)) {
+        lines.push(MIGRATE_COMPLETION_NUDGE);
+    }
     const payload = newRitualStatePayload({
         sessionId: (options.newSessionId ?? randomUUID)(),
         gitHead: gitHeadValue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.61.0",
+  "version": "0.61.2",
   "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.61.0",
-    "@deftai/directive-types": "^0.61.0"
+    "@deftai/directive-content": "^0.61.2",
+    "@deftai/directive-types": "^0.61.2"
   },
   "scripts": {
     "build": "tsc -b",