@deftai/directive-core 0.66.2 → 0.68.0

package/dist/agents-md-advisory/evaluate.d.ts

@@ -0,0 +1,44 @@
+import { type RegionCounts } from "../agents-md-budget/evaluate.js";
+import { type AgentsMdAdvisorySource } from "../policy/agents-md-advisory.js";
+export type OutputStream = "stdout" | "stderr" | "none";
+/**
+ * Result of the consumer AGENTS.md advisory evaluation (#2155).
+ *
+ * `code` is 0 in the DEFAULT advisory posture no matter what -- the advisory
+ * MUST NEVER fail-close a consumer build. Non-zero codes are only ever produced
+ * in the explicit `--enforce` opt-in posture (1 = over the hard cap the
+ * consumer asked for; 2 = a config problem that blocks an enforced check).
+ */
+export interface AdvisoryEvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    /** True when the unmanaged region exceeds the soft budget. */
+    readonly over: boolean;
+    /** Region counts, or null when AGENTS.md was missing / unreadable / malformed. */
+    readonly counts: RegionCounts | null;
+    /** The resolved soft budget the unmanaged region was compared against. */
+    readonly softMaxLines: number;
+    /** Provenance of the soft budget (typed / default / default-on-error). */
+    readonly source: AgentsMdAdvisorySource;
+}
+export interface AdvisoryEvaluateOptions {
+    /**
+     * Opt-in hard-cap posture (#1419 enforce tier). When true, an over-budget
+     * unmanaged region exits 1 and a config problem exits 2. Default (false) is
+     * the advisory posture that always exits 0.
+     */
+    readonly enforce?: boolean;
+    /** Suppress the within-budget "OK" line (used by aggregate callers). */
+    readonly quiet?: boolean;
+}
+/**
+ * Evaluate the consumer AGENTS.md against its soft, unmanaged-focused budget.
+ *
+ * Reuses the #645 region counter (`countRegions`) so the framework-owned
+ * managed section is EXCLUDED from the comparison -- only the consumer-authored
+ * unmanaged region is measured. In the default advisory posture the result code
+ * is always 0; `--enforce` promotes over-budget / config problems to non-zero.
+ */
+export declare function evaluate(projectRoot: string, options?: AdvisoryEvaluateOptions): AdvisoryEvaluateResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/agents-md-advisory/evaluate.js

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { countRegions } from "../agents-md-budget/evaluate.js";
+import { resolveAgentsMdAdvisory, } from "../policy/agents-md-advisory.js";
+const GUIDANCE_LINE = "  AGENTS.md is a map, not a manual (#1882): push project detail into a\n" +
+    "  reference doc and leave a pointer, rather than growing AGENTS.md. See\n" +
+    "  content/docs/good-agents-md.md.";
+function overMessage(counts, softMax, enforce, fieldName) {
+    const over = counts.unmanaged - softMax;
+    if (enforce) {
+        return (`❌ agents-md-advisory: AGENTS.md unmanaged (project-authored) region is ` +
+            `${counts.unmanaged} lines, over the enforced cap of ${softMax} (OVER by ${over}).\n` +
+            `${GUIDANCE_LINE}\n` +
+            `  Raise ${fieldName} in PROJECT-DEFINITION to accept the growth.`);
+    }
+    return (`⚠ agents-md-advisory: AGENTS.md unmanaged (project-authored) region is ` +
+        `${counts.unmanaged} lines, over the soft budget of ${softMax} (OVER by ${over}). ` +
+        "This is advisory only -- your build is NOT affected.\n" +
+        `${GUIDANCE_LINE}\n` +
+        `  This is your knob: raise ${fieldName} in PROJECT-DEFINITION to accept the\n` +
+        "  growth and silence this note.");
+}
+const FIELD_NAME = "plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines";
+/**
+ * Evaluate the consumer AGENTS.md against its soft, unmanaged-focused budget.
+ *
+ * Reuses the #645 region counter (`countRegions`) so the framework-owned
+ * managed section is EXCLUDED from the comparison -- only the consumer-authored
+ * unmanaged region is measured. In the default advisory posture the result code
+ * is always 0; `--enforce` promotes over-budget / config problems to non-zero.
+ */
+export function evaluate(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const enforce = options.enforce ?? false;
+    const quiet = options.quiet ?? false;
+    const advisory = resolveAgentsMdAdvisory(root);
+    const softMax = advisory.config.unmanagedSoftMaxLines;
+    const agentsPath = join(root, "AGENTS.md");
+    if (!existsSync(agentsPath)) {
+        const message = `agents-md-advisory: no AGENTS.md found at ${agentsPath}`;
+        return {
+            code: enforce ? 2 : 0,
+            message: enforce ? `❌ ${message}` : quiet ? "" : `${message} (advisory; skipped).`,
+            stream: enforce ? "stderr" : quiet ? "none" : "stdout",
+            over: false,
+            counts: null,
+            softMaxLines: softMax,
+            source: advisory.source,
+        };
+    }
+    let text;
+    try {
+        text = readFileSync(agentsPath, { encoding: "utf8" });
+    }
+    catch (err) {
+        const message = `agents-md-advisory: AGENTS.md at ${agentsPath} cannot be read: ${String(err)}`;
+        return {
+            code: enforce ? 2 : 0,
+            message: enforce ? `❌ ${message}` : quiet ? "" : `${message} (advisory; skipped).`,
+            stream: enforce ? "stderr" : quiet ? "none" : "stdout",
+            over: false,
+            counts: null,
+            softMaxLines: softMax,
+            source: advisory.source,
+        };
+    }
+    const regionResult = countRegions(text);
+    if ("error" in regionResult) {
+        const message = `agents-md-advisory: ${regionResult.error}`;
+        return {
+            code: enforce ? 2 : 0,
+            message: enforce ? `❌ ${message}` : quiet ? "" : `${message} (advisory; skipped).`,
+            stream: enforce ? "stderr" : quiet ? "none" : "stdout",
+            over: false,
+            counts: null,
+            softMaxLines: softMax,
+            source: advisory.source,
+        };
+    }
+    const counts = regionResult.counts;
+    const over = counts.unmanaged > softMax;
+    if (!over) {
+        if (quiet) {
+            return {
+                code: 0,
+                message: "",
+                stream: "none",
+                over: false,
+                counts,
+                softMaxLines: softMax,
+                source: advisory.source,
+            };
+        }
+        return {
+            code: 0,
+            message: `✓ agents-md-advisory: AGENTS.md unmanaged region ${counts.unmanaged}/${softMax} lines ` +
+                `within soft budget (managed ${counts.managed} excluded; advisory).`,
+            stream: "stdout",
+            over: false,
+            counts,
+            softMaxLines: softMax,
+            source: advisory.source,
+        };
+    }
+    return {
+        code: enforce ? 1 : 0,
+        message: overMessage(counts, softMax, enforce, FIELD_NAME),
+        stream: "stderr",
+        over: true,
+        counts,
+        softMaxLines: softMax,
+        source: advisory.source,
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/agents-md-advisory/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agents-md-advisory/index.js

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/agents-md-budget/evaluate.d.ts

@@ -0,0 +1,38 @@
+export type OutputStream = "stdout" | "stderr" | "none";
+/** Result of verify:agents-md-budget evaluation; three-state exit contract. */
+export interface EvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+}
+export interface EvaluateOptions {
+    readonly quiet?: boolean;
+}
+/** Per-region line counts of an AGENTS.md file. */
+export interface RegionCounts {
+    readonly total: number;
+    readonly managed: number;
+    readonly unmanaged: number;
+}
+/**
+ * Split AGENTS.md into managed / unmanaged line counts.
+ *
+ * Returns `{ counts }` on success, or `{ error }` when the managed markers are
+ * malformed (exactly one marker present, or close-before-open). A file with no
+ * markers at all is valid: the whole file counts as unmanaged.
+ */
+export declare function countRegions(text: string): {
+    counts: RegionCounts;
+} | {
+    error: string;
+};
+/**
+ * Pure evaluator for the AGENTS.md line-budget ratchet gate (#645).
+ *
+ * Counts the managed section and the unmanaged region separately (the #1309
+ * propagation duplicates content across the marker) and fails when either
+ * region exceeds its typed per-region budget. Ships green because the budget is
+ * seeded at current size; growth past the ratchet fails.
+ */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/agents-md-budget/evaluate.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { AGENTS_MANAGED_CLOSE } from "../platform/constants.js";
+import { resolveAgentsMdBudget } from "../policy/agents-md-budget.js";
+const OPEN_MARKER_PREFIX = "<!-- deft:managed-section";
+/**
+ * Split AGENTS.md into managed / unmanaged line counts.
+ *
+ * Returns `{ counts }` on success, or `{ error }` when the managed markers are
+ * malformed (exactly one marker present, or close-before-open). A file with no
+ * markers at all is valid: the whole file counts as unmanaged.
+ */
+export function countRegions(text) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    // Ignore the trailing empty element produced by a final newline.
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    const total = lines.length;
+    const openLine = lines.findIndex((l) => l.startsWith(OPEN_MARKER_PREFIX));
+    const closeLine = lines.findIndex((l) => l.trim().startsWith(AGENTS_MANAGED_CLOSE));
+    const openCount = lines.filter((l) => l.startsWith(OPEN_MARKER_PREFIX)).length;
+    const closeCount = lines.filter((l) => l.trim().startsWith(AGENTS_MANAGED_CLOSE)).length;
+    if (openLine === -1 && closeLine === -1) {
+        return { counts: { total, managed: 0, unmanaged: total } };
+    }
+    // Malformed if a marker is missing, close precedes open, or either marker is
+    // duplicated -- the contract promises exactly one open/close pair.
+    if (openLine === -1 ||
+        closeLine === -1 ||
+        closeLine < openLine ||
+        openCount > 1 ||
+        closeCount > 1) {
+        return {
+            error: "AGENTS.md managed-section markers are malformed " +
+                `(open@${openLine === -1 ? "none" : openLine + 1}×${openCount}, ` +
+                `close@${closeLine === -1 ? "none" : closeLine + 1}×${closeCount}); ` +
+                "expected a single <!-- deft:managed-section ... --> ... " +
+                "<!-- /deft:managed-section --> pair.",
+        };
+    }
+    const managed = closeLine - openLine + 1;
+    return { counts: { total, managed, unmanaged: total - managed } };
+}
+function formatRefusal(counts, managedMax, unmanagedMax, projectRoot) {
+    const over = [];
+    if (counts.managed > managedMax) {
+        over.push(`   managed region:   ${counts.managed}/${managedMax} lines (OVER by ${counts.managed - managedMax})`);
+    }
+    if (counts.unmanaged > unmanagedMax) {
+        over.push(`   unmanaged region: ${counts.unmanaged}/${unmanagedMax} lines (OVER by ${counts.unmanaged - unmanagedMax})`);
+    }
+    return (`❌ verify:agents-md-budget: AGENTS.md grew past its ratchet ` +
+        `(project_root=${projectRoot}).\n` +
+        `${over.join("\n")}\n` +
+        "   AGENTS.md is a map, not a manual (#1882): push detail into a\n" +
+        "   reference doc (main.md / a pack / docs/) and leave a pointer,\n" +
+        "   rather than expanding AGENTS.md. See REFERENCES.md.\n" +
+        "   If the growth is deliberate, raise the matching line in\n" +
+        "   plan.policy.agentsMdBudget in PROJECT-DEFINITION (a reviewed diff). (#645)");
+}
+/**
+ * Pure evaluator for the AGENTS.md line-budget ratchet gate (#645).
+ *
+ * Counts the managed section and the unmanaged region separately (the #1309
+ * propagation duplicates content across the marker) and fails when either
+ * region exceeds its typed per-region budget. Ships green because the budget is
+ * seeded at current size; growth past the ratchet fails.
+ */
+export function evaluate(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const quiet = options.quiet ?? false;
+    const budgetResult = resolveAgentsMdBudget(root);
+    if (budgetResult.source === "default-on-error") {
+        return {
+            code: 2,
+            message: `❌ verify:agents-md-budget: PROJECT-DEFINITION malformed: ${budgetResult.error}`,
+            stream: "stderr",
+        };
+    }
+    const agentsPath = join(root, "AGENTS.md");
+    if (!existsSync(agentsPath)) {
+        return {
+            code: 2,
+            message: `❌ verify:agents-md-budget: AGENTS.md not found at ${agentsPath}`,
+            stream: "stderr",
+        };
+    }
+    let text;
+    try {
+        text = readFileSync(agentsPath, { encoding: "utf8" });
+    }
+    catch (err) {
+        return {
+            code: 2,
+            message: `❌ verify:agents-md-budget: AGENTS.md at ${agentsPath} cannot be read: ${String(err)}`,
+            stream: "stderr",
+        };
+    }
+    const regionResult = countRegions(text);
+    if ("error" in regionResult) {
+        return {
+            code: 2,
+            message: `❌ verify:agents-md-budget: ${regionResult.error}`,
+            stream: "stderr",
+        };
+    }
+    const counts = regionResult.counts;
+    if (budgetResult.source === "unset") {
+        if (quiet) {
+            return { code: 0, message: "", stream: "none" };
+        }
+        return {
+            code: 0,
+            message: "⚠ verify:agents-md-budget: no plan.policy.agentsMdBudget configured " +
+                `(managed=${counts.managed}, unmanaged=${counts.unmanaged} lines).\n` +
+                "  Seed a ratchet at current size to freeze growth (#645): set\n" +
+                "  plan.policy.agentsMdBudget.{managedMaxLines,unmanagedMaxLines} in " +
+                "PROJECT-DEFINITION.",
+            stream: "stderr",
+        };
+    }
+    /* v8 ignore start -- defensive: source "typed" always carries a non-null budget. */
+    if (budgetResult.budget === null) {
+        return {
+            code: 2,
+            message: "❌ verify:agents-md-budget: unexpected null budget for typed source",
+            stream: "stderr",
+        };
+    }
+    /* v8 ignore stop */
+    const budget = budgetResult.budget;
+    const overManaged = counts.managed > budget.managedMaxLines;
+    const overUnmanaged = counts.unmanaged > budget.unmanagedMaxLines;
+    if (!overManaged && !overUnmanaged) {
+        if (quiet) {
+            return { code: 0, message: "", stream: "none" };
+        }
+        return {
+            code: 0,
+            message: `✓ verify:agents-md-budget: managed ${counts.managed}/${budget.managedMaxLines}, ` +
+                `unmanaged ${counts.unmanaged}/${budget.unmanagedMaxLines} lines (within ratchet).`,
+            stream: "stdout",
+        };
+    }
+    return {
+        code: 1,
+        message: formatRefusal(counts, budget.managedMaxLines, budget.unmanagedMaxLines, root),
+        stream: "stderr",
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/agents-md-budget/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agents-md-budget/index.js

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/check/index.d.ts

@@ -1,3 +1,3 @@
 export type { CheckOrchestratorSeams } from "./orchestrator.js";
-export { dispatchTaskCheck, isFrameworkSourceContext, resolveCheckTarget } from "./orchestrator.js";
+export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/check/index.js

@@ -1,2 +1,2 @@
-export { dispatchTaskCheck, isFrameworkSourceContext, resolveCheckTarget } from "./orchestrator.js";
+export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 //# sourceMappingURL=index.js.map

package/dist/check/orchestrator.d.ts

@@ -24,13 +24,23 @@ export interface CheckOrchestratorSeams {
         error?: Error;
     };
 }
+/**
+ * True when `path` is the directive framework source checkout root (not a
+ * vendored `.deft/core` content deposit). Used to distinguish a maintainer
+ * running `task check` from a subdirectory (#2220) from a consumer install.
+ */
+export declare function isFrameworkRepoRoot(path: string): boolean;
 /**
  * Return true when running in the framework's own source checkout (#1519).
  *
- * Mirrors `is_framework_source_context` from _project_context.py:
- * equality of lexical absolute roots is the stable distinction. We do NOT
- * resolve symlinks here -- a consumer project may symlink `.deft/core` to a
- * local framework checkout and should still run the consumer-safe gate.
+ * Mirrors `is_framework_source_context` from _project_context.py with one
+ * extension (#2220): when the Taskfile lives at the framework repo root,
+ * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
+ * `TASKFILE_DIR`). Those invocations must still route to
+ * `check:framework-source` so the biome lane runs. We do NOT resolve
+ * symlinks on the framework root -- a consumer project may symlink
+ * `.deft/core` to a local framework checkout and should still run the
+ * consumer-safe gate (the deposit path lacks `packages/cli`).
  */
 export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
 /**

package/dist/check/orchestrator.js

@@ -12,17 +12,41 @@
  *   2 -- config error (missing args, task spawn error, etc.)
  */
 import { spawnSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/**
+ * True when `path` is the directive framework source checkout root (not a
+ * vendored `.deft/core` content deposit). Used to distinguish a maintainer
+ * running `task check` from a subdirectory (#2220) from a consumer install.
+ */
+export function isFrameworkRepoRoot(path) {
+    const root = resolve(path);
+    return (existsSync(join(root, "packages", "cli", "package.json")) &&
+        existsSync(join(root, "biome.json")) &&
+        existsSync(join(root, "Taskfile.yml")));
+}
 /**
  * Return true when running in the framework's own source checkout (#1519).
  *
- * Mirrors `is_framework_source_context` from _project_context.py:
- * equality of lexical absolute roots is the stable distinction. We do NOT
- * resolve symlinks here -- a consumer project may symlink `.deft/core` to a
- * local framework checkout and should still run the consumer-safe gate.
+ * Mirrors `is_framework_source_context` from _project_context.py with one
+ * extension (#2220): when the Taskfile lives at the framework repo root,
+ * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
+ * `TASKFILE_DIR`). Those invocations must still route to
+ * `check:framework-source` so the biome lane runs. We do NOT resolve
+ * symlinks on the framework root -- a consumer project may symlink
+ * `.deft/core` to a local framework checkout and should still run the
+ * consumer-safe gate (the deposit path lacks `packages/cli`).
  */
 export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
-    return resolve(frameworkRoot) === resolve(projectRoot);
+    const fw = resolve(frameworkRoot);
+    const pr = resolve(projectRoot);
+    if (fw === pr) {
+        return true;
+    }
+    if (!isFrameworkRepoRoot(fw)) {
+        return false;
+    }
+    return pr.startsWith(`${fw}${sep}`);
 }
 /**
  * Select the Taskfile target for the given context.

package/dist/codebase/map.d.ts

@@ -1,6 +1,7 @@
 export declare const GENERATED_SENTINEL = "AUTO-GENERATED by task codebase:map";
 export declare const DEFAULT_OUTPUT_PATH = ".planning/codebase/MAP.md";
 export declare const BANNER_TEMPLATE: string;
+export declare function markdownText(value: unknown): string;
 export declare function projectionOutputPath(projectRoot: string, explicitOutput?: string | null): string;
 export declare function renderCodebaseMap(artifact: Record<string, unknown>): string;
 export declare function isDeftGenerated(path: string): boolean;

package/dist/codebase/map.js

@@ -13,9 +13,12 @@ export const BANNER_TEMPLATE = "<!-- AUTO-GENERATED by task codebase:map -- DO N
     "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json " +
     "plan.architecture.codeStructure -->\n" +
     "<!-- Regenerate with: task codebase:map -->\n";
-function markdownText(value) {
+export function markdownText(value) {
     const text = value === null || value === undefined ? "" : String(value);
-    return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
+    // Escape the backslash escape character FIRST, then the `|` table delimiter.
+    // Escaping `|` alone lets a pre-existing backslash bypass the delimiter
+    // escape (CodeQL js/incomplete-sanitization).
+    return text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
 }
 function code(value) {
     const text = markdownText(value);

package/dist/doctor/checks.js

@@ -34,14 +34,14 @@ export function checkQuickStartResolves(projectRoot, installRoot, seams = {}) {
             `install root is '${installRoot}' but the file is missing. ` +
             "Run `.deft/core/run agents:refresh` (Unix) / " +
             "`.deft\\core\\run agents:refresh` (Windows) to align AGENTS.md " +
-            "with the on-disk install root, OR run `task upgrade` to " +
+            "with the on-disk install root, OR run `deft update` to " +
             "re-pull the framework if the on-disk install is missing. " +
             "See UPGRADING.md for the canonical drift-repair walkthrough.",
         data: {
             path: qsPath,
             install_root: installRoot,
             suggested_fix: ".deft/core/run agents:refresh",
-            suggested_fix_alt: "task upgrade",
+            suggested_fix_alt: "deft update",
         },
     };
 }
@@ -89,13 +89,13 @@ export function checkSkillPathsResolve(projectRoot, agentsMdText, seams = {}) {
         status: "fail",
         detail: `${missing.length} skill path(s) do not resolve; ${redirectStubs.length} stub redirect(s). ` +
             `${parts.join("; ")}. Run \`.deft/core/run agents:refresh\` (Unix) / ` +
-            "`.deft\\core\\run agents:refresh` (Windows) to rewrite the managed AGENTS.md block so skill paths match the on-disk framework, OR run `task upgrade` if the on-disk skills are missing entirely. See UPGRADING.md for the drift-repair walkthrough.",
+            "`.deft\\core\\run agents:refresh` (Windows) to rewrite the managed AGENTS.md block so skill paths match the on-disk framework, OR run `deft update` if the on-disk skills are missing entirely. See UPGRADING.md for the drift-repair walkthrough.",
         data: {
             referenced,
             missing,
             redirect_stubs: redirectStubs,
             suggested_fix: ".deft/core/run agents:refresh",
-            suggested_fix_alt: "task upgrade",
+            suggested_fix_alt: "deft update",
         },
     };
 }
@@ -111,7 +111,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
             return {
                 name: "manifest-agreement",
                 status: "fail",
-                detail: `Two install manifests disagree: .deft/core/VERSION (tag='${coreVer}') vs legacy .deft/VERSION (tag='${legacyVer}'). The canonical manifest is .deft/core/VERSION -- run \`task upgrade\` to migrate the stale .deft/VERSION (backed up as .deft/VERSION.premigrate). See UPGRADING.md for the canonical drift-repair walkthrough.`,
+                detail: `Two install manifests disagree: .deft/core/VERSION (tag='${coreVer}') vs legacy .deft/VERSION (tag='${legacyVer}'). The canonical manifest is .deft/core/VERSION -- run \`deft update\` to migrate the stale .deft/VERSION (backed up as .deft/VERSION.premigrate). See UPGRADING.md for the canonical drift-repair walkthrough.`,
                 data: {
                     dual_manifest_drift: true,
                     core_manifest_path: coreManifest,
@@ -119,7 +119,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
                     core_version: coreVer,
                     legacy_version: legacyVer,
                     authoritative: "manifest",
-                    suggested_fix: "task upgrade",
+                    suggested_fix: "deft update",
                 },
             };
         }
@@ -149,13 +149,13 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
         return {
             name: "manifest-agreement",
             status: "fail",
-            detail: `Bare .deft-version exists at ${barePath} but YAML manifest is missing at ${expectedManifestPath}. Run \`task upgrade\` to write the canonical manifest (#1046 PR-B AC-4). See UPGRADING.md for the v0.27.x -> v0.28 transition walkthrough.`,
+            detail: `Bare .deft-version exists at ${barePath} but YAML manifest is missing at ${expectedManifestPath}. Run \`deft update\` to write the canonical manifest (#1046 PR-B AC-4). See UPGRADING.md for the v0.27.x -> v0.28 transition walkthrough.`,
             data: {
                 manifest_path: manifestPath,
                 expected_manifest_path: expectedManifestPath,
                 bare_path: barePath,
                 bare_value: bareText?.trim() ?? null,
-                suggested_fix: "task upgrade",
+                suggested_fix: "deft update",
             },
         };
     }
@@ -165,7 +165,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
         return {
             name: "manifest-agreement",
             status: "pass",
-            detail: `YAML manifest at ${manifestPath} present; bare .deft-version absent (derived value: '${derived}' from manifest tag). Run \`task upgrade\` to regenerate the derivative.`,
+            detail: `YAML manifest at ${manifestPath} present; bare .deft-version absent (derived value: '${derived}' from manifest tag). Run \`deft update\` to regenerate the derivative.`,
             data: {
                 manifest_path: manifestPath,
                 manifest,
@@ -205,14 +205,14 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
     return {
         name: "manifest-agreement",
         status: "fail",
-        detail: `Drift detected: YAML manifest tag='${derived}' does NOT agree with bare .deft-version='${bareValue}'. Per #1046 PR-B AC-4 the YAML manifest is the canonical source -- run \`task upgrade\` to regenerate the bare derivative from the manifest, OR manually update ${manifestPath} if the bare value is correct. See UPGRADING.md for the canonical drift-repair walkthrough.`,
+        detail: `Drift detected: YAML manifest tag='${derived}' does NOT agree with bare .deft-version='${bareValue}'. Per #1046 PR-B AC-4 the YAML manifest is the canonical source -- run \`deft update\` to regenerate the bare derivative from the manifest, OR manually update ${manifestPath} if the bare value is correct. See UPGRADING.md for the canonical drift-repair walkthrough.`,
         data: {
             manifest_path: manifestPath,
             bare_path: barePath,
             derived_version: derived,
             bare_value: bareValue,
             authoritative: "manifest",
-            suggested_fix: "task upgrade",
+            suggested_fix: "deft update",
         },
     };
 }

package/dist/doctor/constants.d.ts

@@ -6,7 +6,11 @@ export declare const DEPRECATED_REDIRECT_SENTINEL = "<!-- deft:deprecated-redire
 export declare const DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->";
 export declare const REDIRECT_STUB_HEADER_LINES = 8;
 export declare const TASKFILE_INCLUDE_SNIPPET = "version: '3'\n\nincludes:\n  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
-export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--repair", "--repair-taskfile", "--json", "--quiet", "--full", "--project-root", "-h", "--help"];
+export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--repair", "--repair-taskfile", "--json", "--quiet", "--full", "--network", "--project-root", "-h", "--help"];
+/** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
+export declare const NPM_PACKAGE_NAME = "@deftai/directive";
+export declare const NETWORK_DISCLOSURE_LINE: string;
+export declare const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE: string;
 export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "vbrief"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
 export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "vbrief"];
@@ -14,7 +18,8 @@ export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/ag
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export declare const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
-export declare const NPM_PACKAGE_NAME = "@deftai/directive";
+/** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
+export declare const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest && deft update";
 export declare const CLEAN_WINDOW_HOURS = 24;
 export declare const DIRTY_WINDOW_HOURS = 4;
 export declare const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/constants.js

@@ -20,10 +20,25 @@ export const DOCTOR_ALLOWED_FLAGS = [
     "--json",
     "--quiet",
     "--full",
+    "--network",
     "--project-root",
     "-h",
     "--help",
 ];
+/** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
+export const NPM_PACKAGE_NAME = "@deftai/directive";
+// #2182: payload-staleness is the only doctor check that can reach a network
+// endpoint (git ls-remote against the framework's git remote, falling back to
+// `npm view` against the npm registry). It is OFF by default (offline tier)
+// and requires the explicit `--network` flag; this line discloses exactly
+// which tool + registry class it may contact BEFORE the check runs, and the
+// skip line tells an offline run how to opt in.
+export const NETWORK_DISCLOSURE_LINE = "[deft doctor] --network: this run may contact your git remote (framework " +
+    "repo host) and, as a fallback, the npm registry (registry.npmjs.org) to " +
+    `look up the latest ${NPM_PACKAGE_NAME} version.`;
+export const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE = "skip -- offline tier (default). Run `deft doctor --network` to check " +
+    "framework currency against your git remote and the npm registry " +
+    "(discloses tool + registry before contacting either).";
 // Engine / lifecycle dirs that stay at the framework root (NOT relocated by
 // #1875). Shippable-content dirs moved under content/ -- see EXPECTED_CONTENT_DIRS.
 export const EXPECTED_FRAMEWORK_DIRS = ["tasks", "scripts", "vbrief"];
@@ -45,7 +60,8 @@ export const DEFT_REPO_POSITIVE_MARKERS = [
 export const EXPECTED_CONTENT_DIRS = ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
-export const NPM_PACKAGE_NAME = "@deftai/directive";
+/** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
+export const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = `${CANONICAL_UPGRADE_COMMAND} && deft update`;
 export const CLEAN_WINDOW_HOURS = 24;
 export const DIRTY_WINDOW_HOURS = 4;
 export const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";