@deftai/directive-core 0.84.0 → 0.86.0

package/dist/cache/fetch.d.ts

@@ -1,5 +1,22 @@
 import { type RunGhApiFn } from "../scm/gh-rest.js";
+import { type Clock } from "./time.js";
 import type { FetchAllReport, StateRefreshReport } from "./types.js";
+/** Repo-level stamp proving a successful open-only enumeration (#2826). */
+export declare const OPEN_INVENTORY_STAMP = "open-inventory.json";
+export interface OpenInventoryStamp {
+    readonly fetched_at: string;
+    readonly open_count: number;
+}
+export declare function openInventoryStampPath(cacheRoot: string, source: string, repo: string): string;
+export declare function readOpenInventoryStamp(cacheRoot: string, source: string, repo: string): OpenInventoryStamp | null;
+export declare function writeOpenInventoryStamp(options: {
+    cacheRoot: string;
+    source: string;
+    repo: string;
+    openCount: number;
+    fetchedAt?: Date;
+    clock?: Clock;
+}): void;
 export declare const REST_MAX_PER_PAGE = 100;
 export declare const REST_PAGINATION_MAX_PAGES = 100;
 export declare const DEFAULT_RETRY_AFTER_FALLBACK_S = 60;

package/dist/cache/fetch.js

@@ -4,9 +4,49 @@ import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/project
 import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
 import { CacheError, CacheFetchError } from "./errors.js";
+import { atomicWriteText } from "./io.js";
 import { pythonJsonLine } from "./json.js";
 import { cachePut, isFresh, validateRepo } from "./operations.js";
 import { entryDir } from "./paths.js";
+import { systemClock, utcIso } from "./time.js";
+/** Repo-level stamp proving a successful open-only enumeration (#2826). */
+export const OPEN_INVENTORY_STAMP = "open-inventory.json";
+export function openInventoryStampPath(cacheRoot, source, repo) {
+    const [owner, name] = repo.split("/", 2);
+    return join(cacheRoot, source, owner, name, OPEN_INVENTORY_STAMP);
+}
+export function readOpenInventoryStamp(cacheRoot, source, repo) {
+    const path = openInventoryStampPath(cacheRoot, source, repo);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const fetchedAt = raw.fetched_at;
+        const openCount = raw.open_count;
+        if (typeof fetchedAt !== "string")
+            return null;
+        if (typeof openCount !== "number" || openCount !== 0)
+            return null;
+        return { fetched_at: fetchedAt, open_count: openCount };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeOpenInventoryStamp(options) {
+    if (options.openCount !== 0)
+        return;
+    validateRepo(options.repo);
+    const clock = options.clock ?? systemClock;
+    const fetchedAt = options.fetchedAt ?? clock.now();
+    const payload = {
+        fetched_at: utcIso(clock, fetchedAt),
+        open_count: 0,
+    };
+    atomicWriteText(openInventoryStampPath(options.cacheRoot, options.source, options.repo), `${JSON.stringify(payload)}\n`);
+}
 export const REST_MAX_PER_PAGE = 100;
 export const REST_PAGINATION_MAX_PAGES = 100;
 export const DEFAULT_RETRY_AFTER_FALLBACK_S = 60;
@@ -308,6 +348,16 @@ export function runFetchAll(options) {
         if (processed % batchSize === 0)
             maybeSleep(delayMs);
     }
+    // #2826: zero open issues is a successful inventory answer — persist freshness
+    // metadata so preflight-cache does not treat minFetchedAt=null as Infinity stale.
+    if (total === 0 && report.issuesFailed === 0) {
+        writeOpenInventoryStamp({
+            cacheRoot,
+            source,
+            repo: options.repo,
+            openCount: 0,
+        });
+    }
     return report;
 }
 export function cacheFetchAll(options) {

package/dist/doctor/checks.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { CANONICAL_GITIGNORE_BASELINE } from "../init-deposit/gitignore.js";
-import { detectLegacyLayout, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
+import { detectDualLayout, detectLegacyLayout, dualLayoutSignpostLine, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
 import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
@@ -300,6 +300,21 @@ export function checkLegacyLayout(projectRoot, seams = {}) {
         ...(seams.isFile ? { isFile: seams.isFile } : {}),
         ...(seams.isDir ? { isDir: seams.isDir } : {}),
     };
+    const dualLayout = detectDualLayout(projectRoot, legacySeams);
+    if (dualLayout !== null) {
+        return {
+            name: "legacy-layout",
+            status: "fail",
+            detail: dualLayoutSignpostLine(dualLayout),
+            data: {
+                legacy_layout: true,
+                legacy_layout_kind: dualLayout.kind,
+                evidence: [...dualLayout.evidence],
+                upgrading_doc_url: UPGRADING_DOC_URL,
+                go_bridge_releases_url: GO_BRIDGE_RELEASES_URL,
+            },
+        };
+    }
     const detection = detectLegacyLayout(projectRoot, legacySeams);
     if (!detection.legacy) {
         return {

package/dist/doctor/constants.d.ts

@@ -10,11 +10,13 @@ export declare const TASKFILE_INCLUDE_SNIPPET = "version: '3'\n\nincludes:\n  de
 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 PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+export declare const NPM_REGISTRY_MIRROR_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md#corporate-or-mirrored-npm-registry";
 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"];
+export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "xbrief"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
-export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "vbrief"];
+export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "xbrief"];
 export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/agents-entry.md", "content/skills/deft-directive-build/SKILL.md"];
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */

package/dist/doctor/constants.js

@@ -28,12 +28,16 @@ export const DOCTOR_ALLOWED_FLAGS = [
 ];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
 export const NPM_PACKAGE_NAME = "@deftai/directive";
+export const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+export const NPM_REGISTRY_MIRROR_DOC_URL = `${UPGRADING_DOC_URL}#corporate-or-mirrored-npm-registry`;
 // #2182: payload-staleness is the only doctor check that can reach a network
 // endpoint (git ls-remote verifies the pinned ref and `npm view` compares a
-// release-tag install with the latest stable package). 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.
+// release-tag install with the latest stable package). The #2808 baseline
+// registry-routing check uses only offline `npm config get` reads.
+// Payload-staleness 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 the npm registry (registry.npmjs.org) to " +
     `look up the latest ${NPM_PACKAGE_NAME} version.`;
@@ -42,9 +46,9 @@ export const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE = "skip -- offline tier (def
     "(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"];
+export const EXPECTED_FRAMEWORK_DIRS = ["tasks", "scripts", "xbrief"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
-export const CONSUMER_FRAMEWORK_DIRS = ["tasks", "vbrief"];
+export const CONSUMER_FRAMEWORK_DIRS = ["tasks", "xbrief"];
 // Post-#1875 content/ move: these framework-internal markers now live under
 // content/ in the SOURCE repo. They identify a deft source checkout (a consumer
 // would never reproduce them); the C1 flatten means a consumer deposit has no

package/dist/doctor/index.d.ts

@@ -6,6 +6,7 @@ export * from "./flags.js";
 export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
+export * from "./npm-registry.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/index.js

@@ -6,6 +6,7 @@ export * from "./flags.js";
 export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
+export * from "./npm-registry.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/main.d.ts

@@ -2,7 +2,8 @@ import { type ResolutionFacts } from "../resolution/index.js";
 import { createPlainSink } from "./output.js";
 import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
-export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
+export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): boolean;
+export declare function runAgentHooksLiveProbeCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
  * (#2267). The `directive` surface always works; `task deft:X` is optional and

package/dist/doctor/main.js

@@ -7,6 +7,7 @@ import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
+import { probeAgentHooksLive } from "../verify-env/agent-hooks-live-probe.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.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";
@@ -14,8 +15,9 @@ import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeSta
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
 import { pythonJsonDump } from "./json.js";
 import { parseInstallRootFromAgentsMd } from "./manifest.js";
+import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
 import { createPlainSink } from "./output.js";
-import { readTextSafe, resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
+import { readTextSafe, resolveFrameworkRootForProject, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
 import { runLocalSignpostChecks } from "./signpost-checks.js";
 import { classifyTaskfileInclude, formatMissingIncludeSnippet, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
@@ -56,7 +58,7 @@ export function cmdDoctor(args, seams = {}) {
     const quietMode = flags.quiet;
     const fullMode = flags.full;
     const projectRoot = resolvePath(flags.projectRoot ?? process.cwd());
-    const frameworkRoot = seams.frameworkRoot ?? resolveDefaultFrameworkRoot();
+    const frameworkRoot = seams.frameworkRoot ?? resolveFrameworkRootForProject(projectRoot);
     const consumerContext = resolve(projectRoot) !== resolve(frameworkRoot);
     const whichFn = seams.whichFn ?? defaultWhich;
     const nowFn = seams.now ?? (() => new Date());
@@ -90,7 +92,7 @@ export function cmdDoctor(args, seams = {}) {
             }
             const signpostWarnings = throttleFindings.filter((f) => f.severity === "warning").length;
             if (signpostWarnings > 0 && !jsonMode) {
-                throttleSink.finalWarn(`Signpost advisory: ${signpostWarnings} local layout / npm-migration note(s) above (throttle-skipped full probe).`);
+                throttleSink.finalWarn(`Signpost advisory: ${signpostWarnings} local configuration / layout note(s) above (throttle-skipped full probe).`);
             }
             return decision.dirty ? 1 : 0;
         }
@@ -164,13 +166,31 @@ export function cmdDoctor(args, seams = {}) {
         sink.blank();
     }
     sink.info("Checking agent-host hook registration...");
-    runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams);
+    const findingCountBeforeHooks = findings.length;
+    const hooksHealthy = runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams);
+    if (fullMode && hooksHealthy) {
+        const lastFinding = findings[findings.length - 1];
+        if (findings.length > findingCountBeforeHooks &&
+            lastFinding?.check === "agent-hooks-registration" &&
+            lastFinding?.status === "registered") {
+            findings.pop();
+        }
+        runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams);
+    }
+    if (consumerContext) {
+        if (!jsonMode) {
+            sink.blank();
+        }
+        sink.info("Checking npm registry routing...");
+        runNpmRegistryMirrorCheck(projectRoot, sink, addFinding, seams);
+    }
     if (!jsonMode) {
         sink.blank();
     }
-    // #2182: payload-staleness is the only doctor check that can reach a
-    // registry (git verifies the pin; npm compares stable release availability).
-    // It stays in the OFFLINE
+    // #2182: payload-staleness is the only doctor check that can reach a network
+    // endpoint (git verifies the pin; npm compares stable release availability).
+    // The baseline #2808 registry-routing diagnostic above is an offline
+    // `npm config get` read. Payload-staleness 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
@@ -344,40 +364,81 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
         const reason = "maintainer source checkout; project hook deposit is consumer-only";
         sink.info(`${checkName}: skip -- ${reason}`);
         addFinding({ severity: "skip", message: reason, check: checkName, status: "skip" });
-        return;
+        return false;
     }
     try {
         const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
-        if (result.code === 0) {
-            const message = `${checkName}: registered and structurally valid; ` +
-                "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
-            sink.success(message);
+        if (result.code !== 0) {
+            const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
             addFinding({
-                severity: "skip",
+                severity: "warning",
                 message,
                 check: checkName,
-                status: "registered",
+                status: result.code === 2 ? "unavailable" : "incomplete",
                 registrations: result.registrations,
-                trust_status: "not-verifiable",
-                trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+                suggestion: "deft update",
             });
-            return;
+            return false;
         }
-        const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
-        sink.warn(message);
+        const message = `${checkName}: registered and structurally valid; ` +
+            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        sink.success(message);
         addFinding({
-            severity: "warning",
+            severity: "skip",
             message,
             check: checkName,
-            status: result.code === 2 ? "unavailable" : "incomplete",
+            status: "registered",
             registrations: result.registrations,
-            suggestion: "deft update",
+            trust_status: "not-verifiable",
+            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
         });
+        return true;
     }
     catch (cause) {
         const message = `${checkName}: probe failed -- ${String(cause)}`;
         sink.warn(message);
         addFinding({ severity: "warning", message, check: checkName, suggestion: "deft update" });
+        return false;
+    }
+}
+export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "agent-hooks-registration";
+    const liveCheckName = "agent-hooks-live-probe";
+    try {
+        const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
+        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot);
+        if (liveResult.code !== 0) {
+            const message = `${liveCheckName}: ${liveResult.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: liveCheckName,
+                status: liveResult.code === 2 ? "unavailable" : "non-functional",
+                cases: liveResult.cases,
+                suggestion: "npm i -g @deftai/directive@latest && deft update",
+            });
+            return;
+        }
+        const message = `${checkName}: registered, structurally valid, and live probe passed; ` +
+            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        sink.success(message);
+        addFinding({
+            severity: "skip",
+            message,
+            check: liveCheckName,
+            status: "registered-and-functional",
+            registrations: result.registrations,
+            trust_status: "not-verifiable",
+            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            live_probe: "passed",
+        });
+    }
+    catch (cause) {
+        const message = `${liveCheckName}: probe failed -- ${String(cause)}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: liveCheckName, suggestion: "deft update" });
     }
 }
 function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {

package/dist/doctor/npm-registry.d.ts

@@ -0,0 +1,23 @@
+import type { OutputSink } from "./output.js";
+import type { Finding, NpmConfigGet, NpmConfigGetResult } from "./types.js";
+/** Seams for the read-only npm registry routing diagnostic. */
+export interface NpmRegistryMirrorSeams {
+    readonly runNpmConfigGet?: NpmConfigGet;
+}
+/**
+ * Read one npm configuration key without a shell.
+ *
+ * `npm config get` reads local/user configuration only; it does not resolve a
+ * package or contact a registry. Failures are returned explicitly so doctor can
+ * skip this advisory without turning a missing npm binary into a hard error.
+ */
+export declare function defaultNpmConfigGet(key: string, cwd: string): NpmConfigGetResult;
+/**
+ * Warn when `@deftai/*` resolves through a non-public npm registry.
+ *
+ * The finding intentionally records only whether the scoped or default key won
+ * precedence. It never includes the configured URL, which may contain internal
+ * hostnames or credentials.
+ */
+export declare function runNpmRegistryMirrorCheck(projectRoot: string, sink: OutputSink, addFinding: (finding: Finding) => void, seams?: NpmRegistryMirrorSeams): void;
+//# sourceMappingURL=npm-registry.d.ts.map

package/dist/doctor/npm-registry.js

@@ -0,0 +1,128 @@
+import { spawnSync } from "node:child_process";
+import { NPM_REGISTRY_MIRROR_DOC_URL, PUBLIC_NPM_REGISTRY } from "./constants.js";
+const CHECK_NAME = "npm-registry-mirror";
+const DEFT_SCOPE_REGISTRY_KEY = "@deftai:registry";
+const DEFAULT_REGISTRY_KEY = "registry";
+const UNSET_NPM_VALUES = new Set(["", "null", "undefined"]);
+/**
+ * Read one npm configuration key without a shell.
+ *
+ * `npm config get` reads local/user configuration only; it does not resolve a
+ * package or contact a registry. Failures are returned explicitly so doctor can
+ * skip this advisory without turning a missing npm binary into a hard error.
+ */
+export function defaultNpmConfigGet(key, cwd) {
+    try {
+        const proc = spawnSync("npm", ["config", "get", key], {
+            cwd,
+            encoding: "utf8",
+            shell: false,
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return {
+            ok: proc.status === 0,
+            value: typeof proc.stdout === "string" ? proc.stdout.trim() : "",
+        };
+    }
+    catch {
+        return { ok: false, value: "" };
+    }
+}
+function configuredValue(value) {
+    const trimmed = value.trim();
+    return UNSET_NPM_VALUES.has(trimmed.toLowerCase()) ? null : trimmed;
+}
+function effectiveRegistry(runConfigGet, projectRoot) {
+    let scoped;
+    try {
+        scoped = runConfigGet(DEFT_SCOPE_REGISTRY_KEY, projectRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!scoped.ok) {
+        return null;
+    }
+    const scopedValue = configuredValue(scoped.value);
+    if (scopedValue !== null) {
+        return { source: "scoped", value: scopedValue };
+    }
+    let fallback;
+    try {
+        fallback = runConfigGet(DEFAULT_REGISTRY_KEY, projectRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!fallback.ok) {
+        return null;
+    }
+    const fallbackValue = configuredValue(fallback.value);
+    return fallbackValue === null ? null : { source: "default", value: fallbackValue };
+}
+function isValidRegistryUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return (parsed.protocol === "https:" || parsed.protocol === "http:") && parsed.hostname !== "";
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalPublicRegistry(value) {
+    try {
+        const parsed = new URL(value);
+        return (parsed.protocol === "https:" &&
+            parsed.hostname === "registry.npmjs.org" &&
+            parsed.port === "" &&
+            (parsed.pathname === "" || parsed.pathname === "/") &&
+            parsed.username === "" &&
+            parsed.password === "" &&
+            parsed.search === "" &&
+            parsed.hash === "");
+    }
+    catch {
+        return false;
+    }
+}
+function skipFinding(addFinding) {
+    addFinding({
+        severity: "skip",
+        message: `${CHECK_NAME}: skip -- npm registry configuration is unavailable or invalid`,
+        check: CHECK_NAME,
+        status: "skip",
+    });
+}
+/**
+ * Warn when `@deftai/*` resolves through a non-public npm registry.
+ *
+ * The finding intentionally records only whether the scoped or default key won
+ * precedence. It never includes the configured URL, which may contain internal
+ * hostnames or credentials.
+ */
+export function runNpmRegistryMirrorCheck(projectRoot, sink, addFinding, seams = {}) {
+    const selected = effectiveRegistry(seams.runNpmConfigGet ?? defaultNpmConfigGet, projectRoot);
+    if (selected === null || !isValidRegistryUrl(selected.value)) {
+        skipFinding(addFinding);
+        return;
+    }
+    if (isCanonicalPublicRegistry(selected.value)) {
+        return;
+    }
+    const message = `${CHECK_NAME}: @deftai packages resolve through a non-public npm registry. ` +
+        "Corporate mirrors can return E404/ETARGET or silently serve stale @latest metadata. " +
+        `Where organization policy permits, retry with \`npm i -g @deftai/directive@latest --registry=${PUBLIC_NPM_REGISTRY}\` ` +
+        `or add \`@deftai:registry=${PUBLIC_NPM_REGISTRY}\` to \`.npmrc\`. ` +
+        `Otherwise ask your registry administrator to sync the @deftai packages. See ${NPM_REGISTRY_MIRROR_DOC_URL}.`;
+    sink.warn(message);
+    addFinding({
+        severity: "warning",
+        message,
+        check: CHECK_NAME,
+        status: "non-public",
+        registry_source: selected.source,
+        suggestion: NPM_REGISTRY_MIRROR_DOC_URL,
+    });
+}
+//# sourceMappingURL=npm-registry.js.map

package/dist/doctor/npm-view.d.ts

@@ -0,0 +1,10 @@
+export interface NpmViewVersionResult {
+    readonly ok: boolean;
+    readonly version: string;
+}
+/**
+ * Query the canonical public registry for the latest published Directive
+ * version, independent of the consumer's configured corporate mirror.
+ */
+export declare function defaultNpmViewVersion(): NpmViewVersionResult;
+//# sourceMappingURL=npm-view.d.ts.map

package/dist/doctor/npm-view.js

@@ -0,0 +1,31 @@
+import { spawnSync } from "node:child_process";
+import { NPM_PACKAGE_NAME, PUBLIC_NPM_REGISTRY } from "./constants.js";
+/**
+ * Query the canonical public registry for the latest published Directive
+ * version, independent of the consumer's configured corporate mirror.
+ */
+export function defaultNpmViewVersion() {
+    try {
+        const proc = spawnSync("npm", [
+            "view",
+            NPM_PACKAGE_NAME,
+            "version",
+            `--registry=${PUBLIC_NPM_REGISTRY}`,
+            "--ignore-scripts",
+        ], {
+            encoding: "utf8",
+            shell: false,
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        if (proc.error !== undefined || proc.status !== 0) {
+            return { ok: false, version: "" };
+        }
+        const version = (typeof proc.stdout === "string" ? proc.stdout : "").trim().split("\n")[0]?.trim() ?? "";
+        return { ok: version.length > 0, version };
+    }
+    catch {
+        return { ok: false, version: "" };
+    }
+}
+//# sourceMappingURL=npm-view.js.map

package/dist/doctor/payload-staleness.js

@@ -2,8 +2,9 @@ import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/migrate.js";
 import { isPublishable } from "../release/version.js";
-import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, upgradeCommandFor, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
+import { CANONICAL_UPGRADE_COMMAND, upgradeCommandFor, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
+import { defaultNpmViewVersion } from "./npm-view.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
 import { evaluateReleaseAvailability } from "./release-availability.js";
 function isDeftFrameworkRepo(projectRoot, readText = readTextSafe) {
@@ -40,14 +41,6 @@ function parseRemoteSha(stdout) {
     const firstLine = stdout.split("\n").find((ln) => ln.trim()) ?? "";
     return firstLine.trim().split(/\s+/)[0] ?? "";
 }
-function defaultNpmViewVersion() {
-    const proc = spawnSync("npm", ["view", NPM_PACKAGE_NAME, "version"], {
-        encoding: "utf8",
-        timeout: 15_000,
-    });
-    const version = (proc.stdout ?? "").trim().split("\n")[0]?.trim() ?? "";
-    return { ok: proc.status === 0 && version.length > 0, version };
-}
 function emitReleaseAvailable(checkName, installedVersion, latestVersion, ref, upgradeCommand, sink, addFinding) {
     const msg = `Newer framework release available (installed v${installedVersion}; ` +
         `latest v${latestVersion} from npm registry). ` +

package/dist/doctor/signpost-checks.d.ts

@@ -1,7 +1,8 @@
 import { type CheckSeams } from "./checks.js";
+import { type NpmRegistryMirrorSeams } from "./npm-registry.js";
 import type { OutputSink } from "./output.js";
 import type { Finding } from "./types.js";
-export interface LocalSignpostSeams extends CheckSeams {
+export interface LocalSignpostSeams extends CheckSeams, NpmRegistryMirrorSeams {
     readonly runningInsideDeftRepo?: (root: string) => boolean;
 }
 /** Lightweight, local-only signpost probes for the throttle-skip path (#1997). */

package/dist/doctor/signpost-checks.js

@@ -1,4 +1,5 @@
 import { checkCanonicalVendoredNpmSignpost, checkLegacyLayout } from "./checks.js";
+import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
 import { runningInsideDeftRepo } from "./paths.js";
 /** Lightweight, local-only signpost probes for the throttle-skip path (#1997). */
 export function runLocalSignpostChecks(projectRoot, sink, addFinding, seams = {}) {
@@ -6,6 +7,7 @@ export function runLocalSignpostChecks(projectRoot, sink, addFinding, seams = {}
     if (insideDeft) {
         return;
     }
+    runNpmRegistryMirrorCheck(projectRoot, sink, addFinding, seams);
     for (const result of [
         checkLegacyLayout(projectRoot, seams),
         checkCanonicalVendoredNpmSignpost(projectRoot, seams),