@deftai/directive-core 0.66.1 → 0.67.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/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/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,6 @@ 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";
 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,6 @@ 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";
 export const CLEAN_WINDOW_HOURS = 24;
 export const DIRTY_WINDOW_HOURS = 4;
 export const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/flags.js

@@ -5,6 +5,7 @@ export function parseDoctorFlags(args) {
     let json = false;
     let quiet = false;
     let full = false;
+    let network = false;
     let help = false;
     let projectRoot = null;
     const unknown = [];
@@ -26,6 +27,9 @@ export function parseDoctorFlags(args) {
         else if (token === "--full") {
             full = true;
         }
+        else if (token === "--network") {
+            network = true;
+        }
         else if (token === "-h" || token === "--help") {
             help = true;
         }
@@ -52,7 +56,7 @@ export function parseDoctorFlags(args) {
         }
         i += 1;
     }
-    return { session, fix, json, quiet, full, help, projectRoot, unknown };
+    return { session, fix, json, quiet, full, network, help, projectRoot, unknown };
 }
 export function formatUnknownFlagsError(unknown) {
     return `Unknown flag(s): ${unknown.join(", ")}`;

package/dist/doctor/main.js

@@ -1,9 +1,10 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { contentRoot } from "../content-root.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.js";
-import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
+import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
 import { pythonJsonDump } from "./json.js";
@@ -130,13 +131,38 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
-    sink.info("Checking payload staleness from install manifest...");
-    runPayloadStalenessCheck(projectRoot, sink, addFinding, {
-        frameworkRoot,
-        readText: seams.readText,
-        isFile: seams.isFile,
-        runGitLsRemote: seams.runGitLsRemote,
-    });
+    sink.info("Checking AGENTS.md legibility (advisory)...");
+    runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
+    // #2182: payload-staleness is the only doctor check that can reach a
+    // registry (git remote, then npm as a fallback). It stays in the OFFLINE
+    // tier (skipped) unless the operator explicitly opts into the NETWORK tier
+    // via `--network`, and the tool + registry class is disclosed BEFORE the
+    // check runs -- never silently, never as a side effect of a read-only
+    // `deft doctor` invocation (e.g. from the gated session-ritual step).
+    if (flags.network) {
+        sink.info(NETWORK_DISCLOSURE_LINE);
+        sink.info("Checking payload staleness from install manifest...");
+        runPayloadStalenessCheck(projectRoot, sink, addFinding, {
+            frameworkRoot,
+            readText: seams.readText,
+            isFile: seams.isFile,
+            runGitLsRemote: seams.runGitLsRemote,
+            runNpmViewVersion: seams.runNpmViewVersion,
+        });
+    }
+    else {
+        sink.info(`payload-staleness: ${PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE}`);
+        addFinding({
+            severity: "skip",
+            message: PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE,
+            check: "payload-staleness",
+            status: "skip",
+            reason: "offline-tier",
+        });
+    }
     if (!jsonMode) {
         sink.blank();
     }
@@ -346,6 +372,71 @@ function runAgentsMdFreshnessCheck(projectRoot, sink, addFinding, seams) {
         addFinding({ severity: "warning", message, check: checkName });
     }
 }
+/**
+ * Advisory (never-failing) consumer AGENTS.md legibility signal (#2155).
+ *
+ * Reports the unmanaged (project-authored) region size against the soft budget
+ * (`plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines`, generous by default).
+ * The managed section is EXCLUDED. This is the consumer companion to the
+ * maintainer-only #645 ratchet and follows the advise -> observe -> enforce
+ * posture (#1419): it emits at most a `warning` finding, NEVER an `error`, so
+ * `deft doctor` (and the `check:consumer` aggregate that depends on it) can
+ * never fail-close on a judgment call about the consumer's own file.
+ */
+function runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "agents-md-advisory";
+    // Only meaningful for consumer installs (managed markers present). In the
+    // maintainer repo the #645 ratchet owns this file, so skip -- mirrors the
+    // freshness check's guard above.
+    if (runningInsideDeftRepo(projectRoot, seams) ||
+        !hasV3ManagedMarker(projectRoot, seams.readText)) {
+        const skipReason = "no managed-section markers (likely maintainer repo)";
+        sink.info(`${checkName}: skip -- ${skipReason}`);
+        addFinding({ severity: "skip", message: skipReason, check: checkName, status: "skip" });
+        return;
+    }
+    try {
+        const evalFn = seams.agentsMdAdvisoryEvaluate ?? ((root) => evaluateAgentsMdAdvisory(root));
+        const result = evalFn(projectRoot);
+        if (result.over && result.counts !== null) {
+            const message = `AGENTS.md unmanaged (project-authored) region is ${result.counts.unmanaged} lines, ` +
+                `over the soft budget of ${result.softMaxLines} (advisory only -- your build is NOT ` +
+                "affected). AGENTS.md is a map, not a manual (#1882): push detail into a reference doc " +
+                "and leave a pointer (see content/docs/good-agents-md.md). Raise " +
+                "plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines to accept the growth and silence this.";
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: "over-soft-budget",
+                suggestion: "content/docs/good-agents-md.md",
+            });
+            return;
+        }
+        if (result.counts !== null) {
+            sink.success(`${checkName}: unmanaged region ${result.counts.unmanaged}/${result.softMaxLines} lines (within soft budget)`);
+            return;
+        }
+        // No counts (missing / unreadable / malformed AGENTS.md): advisory stays
+        // silent-but-informational; never a doctor error.
+        sink.info(`${checkName}: skip -- AGENTS.md not measurable`);
+        addFinding({
+            severity: "skip",
+            message: "AGENTS.md not measurable",
+            check: checkName,
+            status: "skip",
+        });
+    }
+    catch (exc) {
+        // Sanitize newlines so an error string can't break out of the markdown
+        // bullet when findings are rendered (CWE-116).
+        const detail = `${exc instanceof Error ? exc.name : "Error"}: ${exc}`.replace(/\r?\n/g, " ");
+        const message = `${checkName}: probe failed -- ${detail}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
 function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams) {
     if (runningInsideDeftRepo(projectRoot, seams)) {
         sink.info("Skipping Taskfile include check -- running inside the deft framework repo (the repo's own Taskfile.yml is the surface).");

package/dist/doctor/paths.d.ts

@@ -2,6 +2,7 @@
 export declare function resolvePath(pathStr: string, cwd?: string): string;
 /** Best-effort version string (mirrors Python `_resolve_version`). */
 export declare function resolveVersion(frameworkRoot?: string): string;
+export declare function resolveFrameworkRootForProject(projectRoot: string, explicitRoot?: string | null): string;
 /** Return the deft framework repo root (the directory containing `main.md`). */
 export declare function resolveDefaultFrameworkRoot(): string;
 /** Directory containing doctor implementation (Python: scripts/). */