@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/commands/migrate.ts

@@ -13,7 +13,8 @@ import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
-import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
+import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
   allowOptionFor,
   buildExpectedSchemaWithProvenance,
@@ -201,7 +202,8 @@ function warnIfLedgerRelocated(cwd: string, resolvedOutDir: string): void {
 }
 
 /**
- * Report what a declared `migrate.scope` left out (wording: `outOfScopeNote`).
+ * Report what this run did not govern — what a declared `migrate.scope` left out, and
+ * what a DEPENDENCY owns (wording: `exclusionNotes`).
  *
  * STDOUT in text format, STDERR otherwise. `--format json` / `--format toon` put a
  * single machine-readable document on stdout, and a prose line ahead of it breaks
@@ -210,11 +212,15 @@ function warnIfLedgerRelocated(cwd: string, resolvedOutDir: string): void {
  * (`resolveFormat`): suppressing it outright would silence the note for every
  * piped and CI run, which is most of them.
  */
-function logOutOfScope(names: readonly string[], fmt: OutputFormat): void {
-  if (names.length === 0) return;
-  const msg = outOfScopeNote("migrate", names);
-  if (fmt === "text") log.info(msg);
-  else log.warn(msg);
+function logOutOfScope(
+  names: readonly string[],
+  fromDependencies: readonly string[],
+  fmt: OutputFormat,
+): void {
+  for (const msg of exclusionNotes("migrate", names, fromDependencies)) {
+    if (fmt === "text") log.info(msg);
+    else log.warn(msg);
+  }
 }
 
 function emitStructuredError(error: string, hint: string, fmt: OutputFormat): void {
@@ -629,7 +635,7 @@ export async function migrateCommand(
   let metadata;
   try {
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...postgresLoadOptions,
     });
   } catch (err) {
@@ -679,9 +685,9 @@ export async function migrateCommand(
     // leave the expected schema here and are suppressed on the actual side below —
     // dropping them from `expected` ALONE would propose DROP TABLE for every one of
     // them that exists in the database.
-    const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+    const scoped = scopeExpectedSchema(built, collection.inMigrateScope, importedOption(collection));
     const expected = scoped.snapshot;
-    logOutOfScope(scoped.outOfScope, fmt);
+    logOutOfScope(scoped.outOfScope, scoped.importedOutOfScope ?? [], fmt);
     let actual;
     try {
       actual = await introspect(kysely.db, kysely.dialect);
@@ -1057,7 +1063,7 @@ export async function runBaseline(
     try {
       const collection = await resolveCollection(metaRoot);
       metadata = await loadMemory(collection.configDir, {
-        files: collection.files,
+        ...collectionLoadOptions(collection),
         ...baselineLoadOptions,
       });
     } catch (err) {
@@ -1196,7 +1202,7 @@ export async function runOfflineGenerate(
   try {
     collection = await resolveCollection(metaRoot);
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...offlineLoadOptions,
     });
   } catch (err) {
@@ -1256,6 +1262,10 @@ export async function runOfflineGenerate(
       views: offlineViews,
       // Per-command scope — narrows BOTH sides of the offline diff (see planOffline).
       ...(offlineScope !== undefined ? { inScope: offlineScope } : {}),
+      // ...and the import exclusion, which planOffline threads into the SAME call.
+      // Passing it only at the direct call sites would leave the offline pipeline —
+      // the default `meta migrate` — performing no import exclusion at all.
+      ...importedOption(collection),
       allow: tokensToAllowOptions(config.allow),
       onAmbiguous: async (a) => {
         collectedAmbiguous.push(a);
@@ -1280,7 +1290,7 @@ export async function runOfflineGenerate(
   // entries); `expected` is the governed side the emitter renders against. Equal
   // for an unscoped run.
   const { diff: diffResult, nextSnapshot, expected: governedExpected } = plan;
-  logOutOfScope(plan.outOfScope, fmt);
+  logOutOfScope(plan.outOfScope, plan.importedOutOfScope ?? [], fmt);
 
   if (diffResult.blocked.length > 0) {
     log.error(`migrate: ${diffResult.blocked.length} destructive change(s) blocked; re-run with --allow <tokens>`);
@@ -1461,7 +1471,7 @@ async function runD1Migrate(
   let metadata;
   try {
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...d1LoadOptions,
     });
   } catch (err) {
@@ -1482,9 +1492,9 @@ async function runD1Migrate(
   const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
   if (scopeRc !== undefined) return scopeRc;
   // Per-command scope — both-sided, exactly as on the Kysely path above.
-  const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+  const scoped = scopeExpectedSchema(built, collection.inMigrateScope, importedOption(collection));
   const expected = scoped.snapshot;
-  logOutOfScope(scoped.outOfScope, fmt);
+  logOutOfScope(scoped.outOfScope, scoped.importedOutOfScope ?? [], fmt);
   let actual;
   try {
     actual = await introspectD1({

package/src/commands/prompt-snapshot.ts

@@ -16,6 +16,7 @@ import { FileProvider } from "../lib/file-provider.js";
 import { snapshotPaths, unifiedDiff } from "../lib/snapshot.js";
 import { reportLoadError } from "../lib/load-error.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import { render, ESCAPERS, type RenderFormat } from "@metaobjectsdev/render";
@@ -75,7 +76,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
   let root;
   try {
     root = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...configLoadOptions,
     });
   } catch (err) {

package/src/commands/verify.ts

@@ -14,7 +14,9 @@ import { emitStructured, type OutputFormat } from "../lib/format.js";
 import {
   antiPatternRows, missingBaseUrlRows, removedPropRows, ranSection, skippedSection, warnCapped,
   type AdvisoryDiagnosticRow, type AdvisoryFindingRow, type AdvisorySection,
+  libraryPrefixRows,
 } from "../lib/advisory.js";
+import { scanForUnprovenancedLibraryPrefix } from "../lib/library-prefix-advisory.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
@@ -24,12 +26,15 @@ import { replayRemedy } from "../lib/replay-remedy.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
 import { computeDocsDrift } from "../lib/docs-drift.js";
 import {
   checkRequirements, summariseRequirements, scanRequirements, type Diagnostic,
 } from "../lib/requirement-check.js";
 import { lintRequirements } from "../lib/requirement-lint.js";
+import { lintOverlays } from "../lib/overlay-lint.js";
+import { FileSource } from "@metaobjectsdev/metadata/core";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import {
   buildWranglerExecuteArgs,
@@ -69,8 +74,15 @@ import {
   type D1Runner,
   type DriftResult,
 } from "@metaobjectsdev/migrate-ts";
-import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
-import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import {
+  DEFAULT_METAOBJECTS_DIR,
+  loadConfig,
+  loadMemory,
+  resolveCollection,
+  type DependencySpec,
+} from "@metaobjectsdev/sdk";
+import { checkDependencies, ERR_DEPENDENCY_UPSTREAM_DRIFT, formatCheckLine, readLockOrThrow } from "../lib/dependency-sync.js";
+import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_PROMPT,
@@ -163,11 +175,15 @@ export async function verifyCommand(
   // D1 has no URL connection); that check lives inside runSchemaVerify.
   const runCodegen = flags.codegen;
   const runDocs = flags.docs;
+  // Task 15 — same shape as --codegen/--docs: selected ONLY by its own flag,
+  // never folded into the bare-verify default (it needs the publisher
+  // reachable, which CI may not have — see the VerifyFlags doc on `deps`).
+  const runDeps = flags.deps;
   if (!flags.anyExplicit) {
     say(
       "meta verify — running --templates (default). Explicit subverbs: " +
         "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift), " +
-        "--docs (docs drift), " +
+        "--docs (docs drift), --deps (dependency drift), " +
         "--replay/--replay-snapshot (the committed migration chain replays from empty).",
     );
   }
@@ -248,7 +264,7 @@ export async function verifyCommand(
   let root: Awaited<ReturnType<typeof loadMemory>>;
   try {
     root = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...configLoadOptions,
       strict: !flags.lax,
     });
@@ -314,7 +330,7 @@ export async function verifyCommand(
   const promptsDir = join(projectRoot, flags.prompts ?? DEFAULT_PROMPTS_DIR);
   const provider = new FileProvider(promptsDir);
 
-  // The two advisory sections, captured as the gates run so the structured payload
+  // The advisory sections, captured as the gates run so the structured payload
   // can carry them IN FULL. They were previously formatted straight to stderr and
   // existed nowhere else, which is why 96% of a 239-finding report was unreachable
   // by any flag, env var or format.
@@ -322,6 +338,12 @@ export async function verifyCommand(
     skippedSection("the requirement pass did not run");
   let antiPatternSection: AdvisorySection<AdvisoryFindingRow> =
     skippedSection("the advisory anti-pattern pass did not run");
+  // FR-023 §11.1 item 4 (Task 17) — the overlay authoring lint. Its own section
+  // (never folded into `requirements`, which is about a different kind of node
+  // entirely) so the structured payload names what ran and what didn't the same
+  // way every other advisory pass does.
+  let overlaySection: AdvisorySection<AdvisoryDiagnosticRow> =
+    skippedSection("the overlay lint did not run");
   // The ledger counts `meta verify` prints on every run. Undefined for a project
   // declaring no requirement.* node at all (opt-in by declaration) — the payload
   // then omits the block rather than reporting zeroes that would read as an empty
@@ -341,6 +363,7 @@ export async function verifyCommand(
   const schemaExit = await runSchemaVerify();
   const codegenExit = runCodegen ? await runCodegenVerify() : 0;
   const docsExit = runDocs ? await runDocsVerify() : 0;
+  const depsExit = runDeps ? await runDepsVerify() : 0;
   // Requirements have no subverb: `requirement.*` nodes are metadata, so they
   // are checked on every `meta verify`. Opt-in by DECLARATION — a model with no
   // requirement nodes is silent, not in drift.
@@ -351,17 +374,24 @@ export async function verifyCommand(
   // would parse cleanly and do nothing at all.
   const replayExit = flags.replay || flags.replaySnapshot ? await runReplayVerify() : 0;
 
+  // FR-023 §11.1 item 4 (Task 17) — the overlay authoring lint. Runs on every
+  // `meta verify`, not gated on any subverb (an unflagged cross-file
+  // redeclaration is a risk regardless of which drift gates were selected).
+  // Warnings ONLY — never changes the exit code.
+  await runOverlayLintAdvisory();
+
   // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
   // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
   // Suppressed with --no-antipatterns or META_NO_ANTIPATTERNS=1 for the rare
   // noisy project (both opt-outs work on `meta verify` and `meta gen`).
-  runAntiPatternAdvisory();
+  await runAntiPatternAdvisory();
 
   const exitCode = Math.max(
     templateExit,
     schemaExit,
     codegenExit,
     docsExit,
+    depsExit,
     requirementExit,
     replayExit,
   );
@@ -378,6 +408,7 @@ export async function verifyCommand(
           { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
           { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
           { gate: "docs", ran: runDocs, ok: docsExit === 0 },
+          { gate: "deps", ran: runDeps, ok: depsExit === 0 },
           { gate: "requirements", ran: true, ok: requirementExit === 0 },
           { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
         ],
@@ -385,6 +416,7 @@ export async function verifyCommand(
         requirements: requirementSection,
         requirementCounts,
         antiPatterns: antiPatternSection,
+        overlays: overlaySection,
       }),
       fmt,
     );
@@ -553,7 +585,7 @@ export async function verifyCommand(
         columnNamingStrategy: viewStrategy,
         views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
       });
-      governed = scopeExpectedSchema(built, schemaScope);
+      governed = scopeExpectedSchema(built, schemaScope, importedOption(collection));
     }
 
     // `verifyReplay` calls `applyPending` itself. That is NOT a second replay: the
@@ -594,7 +626,7 @@ export async function verifyCommand(
     // ONE scan for all three passes. The gate and the summary each used to walk the
     // model AND resolve every @implementedBy claim for themselves — the resolution
     // being the expensive half — and the lint added a third walk on top.
-    const scan = scanRequirements(root);
+    const scan = scanRequirements(root, { coverable: collection.inScope });
     const diags = [...checkRequirements(root, scan)];
 
     // Printed on EVERY run, clean or not — a gate that says nothing when it
@@ -616,8 +648,20 @@ export async function verifyCommand(
       say(
         `meta verify — requirements: ${s.total} entries (${s.functional} functional, ` +
         `${s.architectural} architectural) — ${parts.join(", ")}; ` +
-        `${s.entitiesClaimed}/${s.entitiesTotal} entities claimed, ` +
-        `counted over ${collection.files.length} metadata file(s).`,
+        // FR-043 §5.4 — a project whose every requirement came from a shipped library
+        // is not measured, and says so rather than printing a ratio. Silence would be
+        // worse than either: a missing clause reads as a clean coverage result.
+        (s.entitiesTotal === undefined
+          ? `coverage: not measured (no project-authored requirements).`
+          : `${s.entitiesClaimed}/${s.entitiesTotal} entities claimed, ` +
+            `counted over ${collection.files.length} metadata file(s)` +
+            // FR-023 — only when there ARE dependencies. A project that declares none
+            // must print the sentence it printed before dependencies existed, to the
+            // byte: "0 from dependencies" is noise on every existing project, and this
+            // line is a SURFACE the no-dependency guarantee covers like any other.
+            (collection.dependencies.length > 0
+              ? `, ${collection.dependencies.length} from dependencies.`
+              : `.`)),
       );
       if (s.undecided > 0) {
         say(
@@ -637,26 +681,25 @@ export async function verifyCommand(
           .filter((k) => (s.byStatus[k] ?? 0) > 0)
           .map((k) => ({ status: k, count: s.byStatus[k] ?? 0 })),
         undecided: s.undecided,
-        entitiesClaimed: s.entitiesClaimed,
-        entitiesTotal: s.entitiesTotal,
+        // Absent when coverage was not measured (FR-043 §5.4), never zeroed: a reader
+        // cannot tell `0/0 claimed` from "not measured", and the two mean opposite
+        // things.
+        ...(s.entitiesTotal === undefined
+          ? {}
+          : { entitiesClaimed: s.entitiesClaimed ?? 0, entitiesTotal: s.entitiesTotal }),
         metadataFiles: collection.files.length,
       };
     }
 
     const errors = diags.filter((d) => d.severity === "error");
     const warns = diags.filter((d) => d.severity === "warn");
-    // Named `fmtDiag`, not `fmt`: `fmt` is this command's OUTPUT FORMAT parameter,
-    // and a shadow of it inside the one function that must not confuse the two is
-    // how a structured run quietly reverts to text.
-    const fmtDiag = (d: Diagnostic): string =>
-      `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
     // Capped per SECTION, never across them: a ledger of a few hundred entries can
     // produce hundreds of prose findings, and a shared budget would let the advisory
     // lint push every gate warning off the end. The cap VALUE is now one shared
     // constant (`--limit`), so raising it cannot miss a section — errors stay
     // uncapped, as they always were.
-    for (const d of errors) log.error(fmtDiag(d));
-    warnCapped(warns.map(fmtDiag), flags.limit, { structured });
+    for (const d of errors) log.error(formatDiagnostic(d));
+    warnCapped(warns.map(formatDiagnostic), flags.limit, { structured });
 
     // -- the authoring lint: its own section, its own cap ----------------------
     // Separate from the gate above because it makes a different claim. The gate
@@ -685,7 +728,7 @@ export async function verifyCommand(
         `meta verify — requirements: ${lint.length} authoring warning(s) ` +
         `(advisory — does not fail the build):`,
       );
-      warnCapped(lint.map(fmtDiag), flags.limit, { structured });
+      warnCapped(lint.map(formatDiagnostic), flags.limit, { structured });
     }
 
     // Everything this pass found, uncapped, for the structured payload — gate
@@ -703,11 +746,49 @@ export async function verifyCommand(
     return 0;
   }
 
+  // -- overlay authoring lint (FR-023 §11.1 item 4, Task 17) ------------------
+  // Its own section, its own cap — same discipline as the requirement lint
+  // above: a noisy section must not push another section's findings off the
+  // end of a capped run. This lint has NO gate half at all (no
+  // "ledger disagrees with the model" claim to make), so nothing here can
+  // ever reach the exit code — records its result either way, same as the
+  // anti-pattern pass below.
+  //
+  // Reads raw file content (via `lintOverlays` + `declaredTopLevelKeys`), never
+  // the loaded/merged model: the merge has already lost which FILE contributed
+  // which declaration, and that is exactly what this lint needs to name.
+  async function runOverlayLintAdvisory(): Promise<void> {
+    if (flags.noOverlayLint) {
+      overlaySection = skippedSection("suppressed by --no-overlay-lint");
+      return;
+    }
+    if (process.env.META_NO_OVERLAY_LINT === "1") {
+      overlaySection = skippedSection("suppressed by META_NO_OVERLAY_LINT=1");
+      return;
+    }
+    let findings: Diagnostic[];
+    try {
+      findings = await lintOverlays(collection, (path) => new FileSource(path));
+    } catch (err) {
+      // Never let an advisory scan break verify — and never report it as clean.
+      overlaySection = skippedSection(`the overlay lint failed: ${(err as Error).message}`);
+      return;
+    }
+    overlaySection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — overlays: ${findings.length} unflagged cross-file redeclaration(s) ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
+    }
+  }
+
   // -- verify-as-teacher (advisory) ------------------------------------------
   // Records its result EITHER WAY — a skip carries its reason rather than looking
   // like a clean scan. Warnings only; nothing here reaches the exit code (the
   // scanner's own header: bias to under-flagging, never a non-zero exit).
-  function runAntiPatternAdvisory(): void {
+  async function runAntiPatternAdvisory(): Promise<void> {
     if (flags.noAntipatterns) {
       antiPatternSection = skippedSection("suppressed by --no-antipatterns");
       return;
@@ -746,10 +827,23 @@ export async function verifyCommand(
       // advisory only — never breaks verify.
     }
 
+    // FR-043 §3.5 — `metaobjects::` in this project's own metadata with no ejection
+    // provenance. Advisory because with the library NOT opted in nothing is broken; the
+    // opted-in case is refused at load instead.
+    let libraryPrefix: Awaited<ReturnType<typeof scanForUnprovenancedLibraryPrefix>> = [];
+    try {
+      libraryPrefix = await scanForUnprovenancedLibraryPrefix(
+        root, collection.ownFiles, collection.configDir,
+      );
+    } catch {
+      // Same discipline as its siblings: an advisory scan never breaks verify.
+    }
+
     antiPatternSection = ranSection([
       ...antiPatternRows(findings),
       ...missingBaseUrlRows(baseUrl),
       ...removedPropRows(removedProps),
+      ...libraryPrefixRows(libraryPrefix),
     ]);
     if (findings.length > 0) {
       log.warn(
@@ -772,6 +866,13 @@ export async function verifyCommand(
       );
       warnCapped(removedProps.map((f) => `  ${f.message}`), flags.limit, { structured });
     }
+    if (libraryPrefix.length > 0) {
+      log.warn(
+        `meta verify — ${libraryPrefix.length} node(s) declared under "metaobjects::" with ` +
+          `no ejection provenance (advisory — does not fail the build):`,
+      );
+      warnCapped(libraryPrefix.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
   }
 
   // -- template (prompt / output) drift --------------------------------------
@@ -994,6 +1095,9 @@ export async function verifyCommand(
           allow,
           views: expectedViews,
           ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+          // The import exclusion reaches scopeExpectedSchema through this option bag —
+          // there is no direct call on this path to attach it to.
+          ...importedOption(collection),
         });
       } catch (err) {
         log.error(`verify: failed to introspect ${kysely.displayUrl}: ${(err as Error).message}`);
@@ -1080,6 +1184,8 @@ export async function verifyCommand(
         allow,
         views: expectedViews,
         ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+        // Same option bag on the D1 path, for the same reason.
+        ...importedOption(collection),
       });
     } catch (err) {
       log.error(`verify: ${(err as Error).message}`);
@@ -1192,11 +1298,12 @@ export async function verifyCommand(
       );
     }
 
-    // Same reasoning for the per-command scope: an object `migrate.scope` excluded
-    // was NOT checked, and silence would misreport it as checked-and-clean. Shared
-    // wording with `meta migrate` — one declaration, one sentence about it.
-    if (driftResult.outOfScope.length > 0) {
-      say(outOfScopeNote("verify", driftResult.outOfScope));
+    // Same reasoning for the per-command scope and for imported metadata: an object
+    // excluded either way was NOT checked, and silence would misreport it as
+    // checked-and-clean. Shared wording with `meta migrate` — one declaration, one
+    // sentence about it — and each object named once (`exclusionNotes`).
+    for (const note of exclusionNotes("verify", driftResult.outOfScope, driftResult.importedOutOfScope ?? [])) {
+      say(note);
     }
 
     const changes = driftResult.changes;
@@ -1249,7 +1356,7 @@ export async function verifyCommand(
     if (genCollection !== collection) {
       try {
         codegenRoot = await loadMemory(genCollection.configDir, {
-          files: genCollection.files,
+          ...collectionLoadOptions(genCollection),
           ...configLoadOptions,
           strict: !flags.lax,
         });
@@ -1390,6 +1497,55 @@ export async function verifyCommand(
     }
     return 1;
   }
+
+  // -- dependency drift (Task 15, FR-023) --------------------------------------
+  // Gated on --deps. Re-resolves each declared dependency exactly as `meta deps
+  // check` does — never part of the bare-verify default (it needs the publisher
+  // reachable, which CI may not have).
+  async function runDepsVerify(): Promise<number> {
+    // Read RAW declared specs (never `collection.dependencies`, which is the
+    // already-`ResolvedDependency[]` the LOCK produced — it carries no
+    // transport info, so it cannot be re-resolved). A project with no
+    // config.json at all declares no dependencies.
+    let depSpecs: readonly DependencySpec[] = [];
+    try {
+      const cfg = await loadConfig(join(collection.configDir, DEFAULT_METAOBJECTS_DIR));
+      depSpecs = cfg.dependencies;
+    } catch {
+      depSpecs = [];
+    }
+
+    if (depSpecs.length === 0) {
+      say("verify --deps: no dependencies declared — nothing to check.");
+      return 0;
+    }
+
+    let lock: Awaited<ReturnType<typeof readLockOrThrow>>;
+    try {
+      lock = await readLockOrThrow(collection.configDir);
+    } catch (err) {
+      log.error(`verify --deps: ${(err as Error).message}`);
+      return 2;
+    }
+
+    const results = await checkDependencies(collection.configDir, depSpecs, lock);
+    const failing = results.filter((r) => r.status !== "current");
+
+    for (const r of results) {
+      if (r.status === "current") say(formatCheckLine(r));
+      else log.error(formatCheckLine(r));
+    }
+
+    if (failing.length > 0) {
+      log.error(
+        `verify --deps: ${failing.length} of ${results.length} dependenc` +
+          `${results.length === 1 ? "y" : "ies"} drifted or unresolved (${ERR_DEPENDENCY_UPSTREAM_DRIFT}).`,
+      );
+      return 1;
+    }
+    say("verify --deps: every dependency's installed artifact matches the lock.");
+    return 0;
+  }
 }
 
 /**
@@ -1447,8 +1603,9 @@ interface RequirementCounts {
   architectural: number;
   byStatus: { status: string; count: number }[];
   undecided: number;
-  entitiesClaimed: number;
-  entitiesTotal: number;
+  /** Absent when coverage was not measured — FR-043 §5.4. */
+  entitiesClaimed?: number;
+  entitiesTotal?: number;
   /** How many metadata files the two entity counts were taken over. */
   metadataFiles: number;
 }
@@ -1460,6 +1617,17 @@ interface VerifyGateRow {
   ok: boolean;
 }
 
+/**
+ * Format one `Diagnostic` as a printed TEXT line. Named `formatDiagnostic`, not
+ * `fmt`: `fmt` is this command's OUTPUT FORMAT parameter, and a shadow of it
+ * anywhere near this code is how a structured run quietly reverts to text.
+ * Shared by the requirement gate/lint AND the overlay lint — every advisory or
+ * gate pass that speaks in `Diagnostic` prints it identically.
+ */
+function formatDiagnostic(d: Diagnostic): string {
+  return `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
+}
+
 /** Project a requirement diagnostic into a payload row. */
 function toDiagnosticRow(d: Diagnostic, source: "gate" | "lint"): AdvisoryDiagnosticRow {
   return {
@@ -1491,6 +1659,7 @@ function buildVerifyPayload(input: {
   requirements: AdvisorySection<AdvisoryDiagnosticRow>;
   requirementCounts: RequirementCounts | undefined;
   antiPatterns: AdvisorySection<AdvisoryFindingRow>;
+  overlays: AdvisorySection<AdvisoryDiagnosticRow>;
 }): Record<string, unknown> {
   const ran = input.gates.filter((g) => g.ran);
   const failed = ran.filter((g) => !g.ok);
@@ -1505,6 +1674,9 @@ function buildVerifyPayload(input: {
   if (input.requirements.total > 0) {
     parts.push(`${input.requirements.total} requirement diagnostic(s)`);
   }
+  if (input.overlays.status === "ran" && input.overlays.total > 0) {
+    parts.push(`${input.overlays.total} overlay authoring finding(s)`);
+  }
 
   const help: string[] = [];
   if (failed.length > 0) {
@@ -1517,7 +1689,17 @@ function buildVerifyPayload(input: {
       `${input.antiPatterns.total} authored site(s) hand-roll what MetaObjects can model — see antiPatterns.rows[] and run \`meta types <construct>\``,
     );
   }
-  if (failed.length === 0 && input.antiPatterns.total === 0 && input.requirements.total === 0) {
+  if (input.overlays.total > 0) {
+    help.push(
+      `${input.overlays.total} unflagged cross-file redeclaration(s) — see overlays.rows[]; add overlay: true so a renamed or removed target fails loudly instead of silently becoming a new object`,
+    );
+  }
+  if (
+    failed.length === 0 &&
+    input.antiPatterns.total === 0 &&
+    input.requirements.total === 0 &&
+    input.overlays.total === 0
+  ) {
     help.push("no drift and nothing advisory to answer — nothing to do");
   }
 
@@ -1528,6 +1710,7 @@ function buildVerifyPayload(input: {
     help,
     antiPatterns: input.antiPatterns,
     requirements: input.requirements,
+    overlays: input.overlays,
     ...(input.requirementCounts !== undefined ? { requirementCounts: input.requirementCounts } : {}),
     // The honest boundary. Everything named here is REACHABLE — it is printed as
     // text on stderr — but it is not in this document, and a reader must not have