@deftai/directive-core 0.67.0 → 0.68.0

package/dist/triage/welcome/writers.js

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renam
 import { dirname, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
     return resolveProjectDefinitionPath(projectRoot);
@@ -27,77 +28,91 @@ function atomicWrite(path, data) {
     renameSync(tmp, path);
 }
 export function writeTriageScope(projectRoot, rules, options = { presetLabel: "custom" }) {
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path))
-        throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-    const data = JSON.parse(readFileSync(path, "utf8"));
-    const plan = data.plan;
-    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-        throw new Error("PROJECT-DEFINITION 'plan' is not an object");
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    let policy = planRec[PLAN_POLICY_KEY];
-    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-        policy = {};
-        planRec[PLAN_POLICY_KEY] = policy;
-    }
-    const policyRec = policy;
-    const previous = policyRec.triageScope;
-    policyRec.triageScope = rules;
-    atomicWrite(path, data);
-    const changed = JSON.stringify(previous) !== JSON.stringify(rules);
-    const actor = options.actor ?? WELCOME_AUDIT_TAG;
-    const auditEntry = [
-        `actor=${actor}`,
-        "field=plan.policy.triageScope",
-        `preset=${options.presetLabel}`,
-        `rule_count=${rules.length}`,
-        `changed=${changed ? "true" : "false"}`,
-    ].join(" ");
-    appendAuditEntry(projectRoot, auditEntry);
-    return [changed, auditEntry];
+    // Serialise read-modify-write + audit append under the shared lock (#1260).
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const path = projectDefinitionPath(projectRoot);
+        if (!existsSync(path))
+            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+        }
+        const data = parsed;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        let policy = planRec[PLAN_POLICY_KEY];
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            policy = {};
+            planRec[PLAN_POLICY_KEY] = policy;
+        }
+        const policyRec = policy;
+        const previous = policyRec.triageScope;
+        policyRec.triageScope = rules;
+        atomicWrite(path, data);
+        const changed = JSON.stringify(previous) !== JSON.stringify(rules);
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        const auditEntry = [
+            `actor=${actor}`,
+            "field=plan.policy.triageScope",
+            `preset=${options.presetLabel}`,
+            `rule_count=${rules.length}`,
+            `changed=${changed ? "true" : "false"}`,
+        ].join(" ");
+        appendAuditEntry(projectRoot, auditEntry);
+        return [changed, auditEntry];
+    });
 }
 export function writeWipCap(projectRoot, wipCap, options = {}) {
     if (!Number.isInteger(wipCap) || wipCap < 1) {
         throw new Error(`wipCap must be a positive int, got ${JSON.stringify(wipCap)}`);
     }
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path))
-        throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-    const data = JSON.parse(readFileSync(path, "utf8"));
-    const plan = data.plan;
-    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-        throw new Error("PROJECT-DEFINITION 'plan' is not an object");
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    let policy = planRec[PLAN_POLICY_KEY];
-    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-        policy = {};
-        planRec[PLAN_POLICY_KEY] = policy;
-    }
-    const policyRec = policy;
-    const previous = policyRec.wipCap;
-    const actor = options.actor ?? WELCOME_AUDIT_TAG;
-    if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
-        return [false, ""];
-    }
-    if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
-        delete policyRec.wipCap;
+    // Serialise read-modify-write + audit append under the shared lock (#1260).
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const path = projectDefinitionPath(projectRoot);
+        if (!existsSync(path))
+            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+        }
+        const data = parsed;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        let policy = planRec[PLAN_POLICY_KEY];
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            policy = {};
+            planRec[PLAN_POLICY_KEY] = policy;
+        }
+        const policyRec = policy;
+        const previous = policyRec.wipCap;
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
+            return [false, ""];
+        }
+        if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
+            delete policyRec.wipCap;
+            atomicWrite(path, data);
+            const auditEntry = `actor=${actor} field=plan.policy.wipCap action=cleared-to-default value=${wipCap} ` +
+                `previous=${JSON.stringify(previous)} changed=true`;
+            appendAuditEntry(projectRoot, auditEntry);
+            return [true, auditEntry];
+        }
+        policyRec.wipCap = wipCap;
         atomicWrite(path, data);
-        const auditEntry = `actor=${actor} field=plan.policy.wipCap action=cleared-to-default value=${wipCap} ` +
-            `previous=${JSON.stringify(previous)} changed=true`;
+        const changed = previous !== wipCap;
+        const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
+            `changed=${changed ? "true" : "false"}`;
         appendAuditEntry(projectRoot, auditEntry);
-        return [true, auditEntry];
-    }
-    policyRec.wipCap = wipCap;
-    atomicWrite(path, data);
-    const changed = previous !== wipCap;
-    const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
-        `changed=${changed ? "true" : "false"}`;
-    appendAuditEntry(projectRoot, auditEntry);
-    return [changed, auditEntry];
+        return [changed, auditEntry];
+    });
 }
 function daysInPending(path, now) {
     try {

package/dist/vbrief-build/project-definition-io.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
@@ -18,8 +19,12 @@ function defaultSleep(ms) {
 export function projectDefinitionMutationLock(projectRoot, fn, deps = {}) {
     const sleepMs = deps.sleepMs ?? defaultSleep;
     const now = deps.now ?? Date.now;
-    const path = projectDefinitionPath(projectRoot);
-    const lockPath = join(dirname(path), `${path.split(/[/\\]/).pop()}.lock`);
+    // Derive the sidecar lock path from the layout-aware resolved PROJECT-DEFINITION
+    // path (xbrief/ when migrated, else vbrief/) so the lock lives next to the real
+    // artifact and every mutator sharing a project root contends on the same lock,
+    // instead of the constant vbrief/ path which would strand a stray lock (#1260).
+    const path = resolveProjectDefinitionPath(resolve(projectRoot));
+    const lockPath = `${path}.lock`;
     mkdirSync(dirname(lockPath), { recursive: true });
     if (mutationThreadLock.held) {
         throw new Error("project definition mutation lock is not reentrant");

package/dist/vbrief-validate/paths.js

@@ -1,4 +1,5 @@
 import { basename, relative, resolve, sep } from "node:path";
+import { resolveLifecycleArtifactRef } from "../layout/lifecycle-ref.js";
 import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
 /** Return true when ``child`` resolves under ``parent``. */
 export function isRelativeTo(child, parent) {
@@ -15,14 +16,17 @@ export function resolveRefPath(uri, vbriefDir) {
     if (typeof uri !== "string") {
         return null;
     }
+    let rel;
     if (uri.startsWith("file://")) {
-        const rel = uri.slice("file://".length);
-        return resolve(vbriefDir, rel);
+        rel = uri.slice("file://".length);
     }
-    if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("#")) {
+    else if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("#")) {
         return null;
     }
-    return resolve(vbriefDir, uri);
+    else {
+        rel = uri;
+    }
+    return resolveLifecycleArtifactRef(rel, vbriefDir);
 }
 /** Split like Python ``str.split(sep, maxsplit)`` (maxsplit splits, not result length). */
 function splitMax(value, sep, maxsplit) {

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

@@ -4,7 +4,7 @@ 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). */
+/** Full-spec generated export (layout-resolved specification artifact source line). */
 export declare function isGeneratedSpecificationExport(projectRoot: string, content: string): boolean;
 /** Return true for a fully current generated spec export (full-spec or greenfield). */
 export declare function isCurrentGeneratedSpecification(projectRoot: string, content: string): boolean;

package/dist/vbrief-validate/precutover.js

@@ -1,15 +1,15 @@
 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 { resolveLifecycleLayout, resolveLifecycleRoot, resolveSpecArtifactPath, } from "../layout/resolve.js";
+import { contentHasGeneratedSpecSource, GENERATED_SPEC_PURPOSE, } 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 SPEC_SOURCE_RELPATH = join("vbrief", "specification.vbrief.json");
 const LIFECYCLE_FOLDERS = ["proposed", "pending", "active", "completed", "cancelled"];
 export function missingLifecycleFolders(projectRoot) {
-    const vbriefRoot = join(projectRoot, "vbrief");
-    return LIFECYCLE_FOLDERS.filter((folder) => !existsSync(join(vbriefRoot, folder)));
+    const lifecycleRoot = resolveLifecycleRoot(projectRoot);
+    return LIFECYCLE_FOLDERS.filter((folder) => !existsSync(join(lifecycleRoot, folder)));
 }
 function hasCompleteLifecycle(projectRoot) {
     return missingLifecycleFolders(projectRoot).length === 0;
@@ -18,11 +18,11 @@ 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). */
+/** Full-spec generated export (layout-resolved specification artifact source line). */
 export function isGeneratedSpecificationExport(projectRoot, content) {
     return (content.includes(GENERATED_SPEC_PURPOSE) &&
-        content.includes(GENERATED_SPEC_SOURCE_SPEC) &&
-        existsSync(join(projectRoot, SPEC_SOURCE_RELPATH)));
+        contentHasGeneratedSpecSource(content) &&
+        existsSync(resolveSpecArtifactPath(projectRoot)));
 }
 /** Return true for a fully current generated spec export (full-spec or greenfield). */
 export function isCurrentGeneratedSpecification(projectRoot, content) {
@@ -56,6 +56,8 @@ function rootMarkdownIsLegacy(projectRoot, filename, content) {
             return false;
         if (isGreenfieldSpecExport(projectRoot))
             return false;
+        if (isFullSpecState(projectRoot))
+            return false;
     }
     return filename === "SPECIFICATION.md" || filename === "PROJECT.md";
 }
@@ -89,11 +91,11 @@ export function detectPreCutover(projectRoot) {
             reasons.push("PROJECT.md is a pre-v0.20 hand-authored doc (not a deprecation redirect)");
         }
     }
-    const vbriefRoot = join(projectRoot, "vbrief");
-    if (existsSync(vbriefRoot)) {
+    const layout = resolveLifecycleLayout(projectRoot);
+    if (existsSync(layout.root)) {
         const missing = missingLifecycleFolders(projectRoot);
         if (missing.length > 0) {
-            reasons.push(`vbrief/ is missing lifecycle folder(s): ${missing.join(", ")}`);
+            reasons.push(`${layout.artifactDir}/ is missing lifecycle folder(s): ${missing.join(", ")}`);
         }
     }
     return { preCutover: reasons.length > 0, reasons };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -110,6 +110,10 @@
       "types": "./dist/pr-wait-mergeable/index.d.ts",
       "default": "./dist/pr-wait-mergeable/index.js"
     },
+    "./pr-watch": {
+      "types": "./dist/pr-watch/index.d.ts",
+      "default": "./dist/pr-watch/index.js"
+    },
     "./vbrief-build": {
       "types": "./dist/vbrief-build/index.d.ts",
       "default": "./dist/vbrief-build/index.js"
@@ -218,10 +222,6 @@
       "types": "./dist/umbrella-current-shape/index.d.ts",
       "default": "./dist/umbrella-current-shape/index.js"
     },
-    "./install-upgrade": {
-      "types": "./dist/install-upgrade/index.d.ts",
-      "default": "./dist/install-upgrade/index.js"
-    },
     "./task-surface": {
       "types": "./dist/task-surface/index.d.ts",
       "default": "./dist/task-surface/index.js"
@@ -245,8 +245,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.67.0",
-    "@deftai/directive-types": "^0.67.0",
+    "@deftai/directive-content": "^0.68.0",
+    "@deftai/directive-types": "^0.68.0",
     "archiver": "^8.0.0"
   },
   "scripts": {

package/dist/install-upgrade/index.d.ts

@@ -1,13 +0,0 @@
-export interface InstallUpgradeArgs {
-    readonly projectRoot: string;
-    readonly frameworkRoot: string;
-    readonly migrate?: boolean;
-    readonly force?: boolean;
-}
-export interface InstallUpgradeIo {
-    writeOut: (text: string) => void;
-    writeErr: (text: string) => void;
-}
-/** Port of ``run upgrade`` / ``task install:upgrade`` for the consumer task surface (#1061 / #2022). */
-export declare function runInstallUpgrade(args: InstallUpgradeArgs, io: InstallUpgradeIo): number;
-//# sourceMappingURL=index.d.ts.map

package/dist/install-upgrade/index.js

@@ -1,251 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-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 { resolveLifecycleRoot } from "../layout/resolve.js";
-import { agentsRefreshPlan } from "../platform/agents-md.js";
-import { DEV_FALLBACK } from "../platform/constants.js";
-import { resolveVersion } from "../platform/resolve-version.js";
-import { detectPreCutoverLegacy, frozenPreCutoverMigrationGuidance, } from "../vbrief-validate/precutover.js";
-import { detectLegacyVbriefLayout, emitXbriefMigration, isPatchOnlyUpgrade, renderXbriefMigrationLine, runXbriefMigration, } from "../xbrief-migrate/index.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(resolveLifecycleRoot(projectRoot), ".deft-version"),
-        join(projectRoot, ".deft-version"),
-    ];
-}
-function readVersionMarker(projectRoot) {
-    for (const candidate of versionMarkerPaths(projectRoot)) {
-        if (!existsSync(candidate) || !statSync(candidate).isFile())
-            continue;
-        try {
-            const value = readFileSync(candidate, "utf8").trim();
-            if (value)
-                return value;
-        }
-        catch {
-            // try next candidate
-        }
-    }
-    return null;
-}
-function writeVersionMarker(targetDir, version) {
-    if (version === DEV_FALLBACK)
-        return;
-    try {
-        mkdirSync(targetDir, { recursive: true });
-        writeFileSync(join(targetDir, ".deft-version"), `${version}\n`, "utf8");
-    }
-    catch {
-        // best-effort, mirrors Python
-    }
-}
-function deriveInstallRootString(installRoot, projectRoot) {
-    try {
-        return relative(projectRoot, installRoot).split("\\").join("/") || CANONICAL_INSTALL_ROOT;
-    }
-    catch {
-        return resolve(installRoot).split("\\").join("/");
-    }
-}
-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",
-        tag: version.startsWith("v") ? version : `v${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 });
-        const body = buildInstallManifestText(fields);
-        const path = join(installRoot, "VERSION");
-        writeFileSync(path, body, "utf8");
-        return path;
-    }
-    catch {
-        return null;
-    }
-}
-function migrateLegacyInstallManifest(projectRoot, canonicalManifestPath) {
-    if (canonicalManifestPath === null)
-        return;
-    const canonical = resolve(canonicalManifestPath);
-    const expectedParent = resolve(projectRoot, ".deft", "core");
-    if (resolve(canonical, "..") !== expectedParent)
-        return;
-    const legacy = join(projectRoot, ".deft", "VERSION");
-    if (!existsSync(legacy) || !statSync(legacy).isFile())
-        return;
-    try {
-        const legacyVersion = manifestTagToVersion(parseInstallManifest(readFileSync(legacy, "utf8")));
-        const canonicalVersion = manifestTagToVersion(parseInstallManifest(readFileSync(canonical, "utf8")));
-        if (legacyVersion !== null && legacyVersion === canonicalVersion)
-            return;
-        renameSync(legacy, join(projectRoot, ".deft", "VERSION.premigrate"));
-    }
-    catch {
-        // best-effort
-    }
-}
-function runAgentsRefresh(projectRoot, frameworkRoot, io) {
-    const plan = agentsRefreshPlan(projectRoot, { frameworkRoot });
-    const state = String(plan.state ?? "unknown");
-    if (state === "current") {
-        io.writeOut("AGENTS.md managed section is current — no changes.\n");
-        return 0;
-    }
-    if (state === "template-missing" || state === "template-malformed" || state === "unreadable") {
-        io.writeErr(`agents:refresh failed: ${state}\n`);
-        return 2;
-    }
-    const newContent = plan.new_content;
-    if (typeof newContent !== "string") {
-        io.writeErr("agents:refresh failed: plan produced no new_content\n");
-        return 2;
-    }
-    const path = String(plan.path ?? join(projectRoot, "AGENTS.md"));
-    writeFileSync(path, newContent, "utf8");
-    io.writeOut(`AGENTS.md updated (state=${state}).\n`);
-    return 0;
-}
-function handleLegacyXbriefLayout(args, io, recorded, normalizedVersion) {
-    const detection = detectLegacyVbriefLayout(args.projectRoot);
-    if (!detection.legacyLayout) {
-        return 0;
-    }
-    io.writeOut(`${renderXbriefMigrationLine(args.projectRoot)}\n`);
-    const patchInert = isPatchOnlyUpgrade(recorded, normalizedVersion);
-    if (!args.migrate || patchInert) {
-        return 0;
-    }
-    const outcome = runXbriefMigration({
-        projectRoot: args.projectRoot,
-        frameworkRoot: args.frameworkRoot,
-        force: args.force,
-    }, io);
-    const code = emitXbriefMigration(outcome, io, { projectRoot: args.projectRoot });
-    return code;
-}
-/** Port of ``run upgrade`` / ``task install:upgrade`` for the consumer task surface (#1061 / #2022). */
-export function runInstallUpgrade(args, io) {
-    const projectRoot = resolve(args.projectRoot);
-    const frameworkRoot = resolve(args.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`);
-        const xbriefCode = handleLegacyXbriefLayout(args, io, recorded, normalizedVersion);
-        if (xbriefCode !== 0)
-            return xbriefCode;
-        return runAgentsRefresh(projectRoot, agentsRoot, io);
-    }
-    const legacy = detectPreCutoverLegacy(projectRoot);
-    if (legacy.length > 0) {
-        io.writeOut(`Pre-v0.20 document model detected (${legacy.join(", ")}). ${frozenPreCutoverMigrationGuidance()}\n`);
-    }
-    const vbriefDir = resolveLifecycleRoot(projectRoot);
-    const targetDir = existsSync(vbriefDir) && statSync(vbriefDir).isDirectory() ? vbriefDir : projectRoot;
-    writeVersionMarker(targetDir, normalizedVersion);
-    const writtenManifestPath = installRoot !== null
-        ? writeInstallManifestAt(installRoot, projectRoot, normalizedVersion)
-        : null;
-    migrateLegacyInstallManifest(projectRoot, writtenManifestPath);
-    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, see UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).\n`);
-    const xbriefCode = handleLegacyXbriefLayout(args, io, recorded, normalizedVersion);
-    if (xbriefCode !== 0)
-        return xbriefCode;
-    return runAgentsRefresh(projectRoot, agentsRoot, io);
-}
-//# sourceMappingURL=index.js.map