@metaobjectsdev/cli 0.24.5 → 1.0.0-rc.1

package/dist/src/commands/verify.js

@@ -9,6 +9,8 @@
 import { join, resolve as resolvePath } from "node:path";
 import { parseVerifyArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
+import { emitStructured } from "../lib/format.js";
+import { antiPatternRows, ranSection, skippedSection, warnCapped, } from "../lib/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";
@@ -16,11 +18,12 @@ 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 { computeCodegenDrift } from "../lib/codegen-drift.js";
+import { computeDocsDrift } from "../lib/docs-drift.js";
 import { checkRequirements, summariseRequirements, scanRequirements, } from "../lib/requirement-check.js";
 import { lintRequirements } from "../lib/requirement-lint.js";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import { buildWranglerExecuteArgs, defaultWranglerRunner, isWranglerLocalD1StatePath, } from "../lib/wrangler.js";
-import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
+import { buildProjectionViews, resolveDocsConfig } from "@metaobjectsdev/codegen-ts";
 import { buildKyselyFromUrl, inferDialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
 import { computeDrift, computeDriftFromActual, collectUnmanagedNames, excludeFromSnapshot, scopedDiffInputs, scopeExpectedSchema, buildExpectedSchemaWithProvenance, applyPending, openReplayEngine, verifyReplay, introspect, diff, readSnapshot, snapshotPath, introspectD1, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
@@ -60,14 +63,33 @@ function attrAsStringArray(attr) {
 }
 export async function verifyCommand(args, cwd, 
 /** Injectable wrangler runner (D1 path only) — tests pass a mock; production uses the default. */
-wranglerRunner) {
+wranglerRunner, 
+/**
+ * Output format, threaded from the global `--format` flag (4th position, matching
+ * `migrateCommand`). It used to be passed to `gen` and `migrate` ONLY, so
+ * `meta verify --format json` was accepted, validated, exited 0 — and printed
+ * human text. An adopter who guessed the right flag lost silently.
+ */
+fmt = "text") {
     const activeWranglerRunner = wranglerRunner ?? defaultWranglerRunner;
+    // In a structured format stdout carries exactly ONE document, so every narration
+    // line moves to stderr (`say` below) instead of being printed into the payload or
+    // dropped. Same split `meta migrate` makes for its out-of-scope note.
+    const structured = fmt !== "text";
+    const say = (msg) => { if (structured)
+        log.warn(msg);
+    else
+        log.info(msg); };
     let flags;
     try {
         flags = parseVerifyArgs(args);
     }
     catch (err) {
-        log.error(err.message);
+        const msg = err.message;
+        log.error(msg);
+        // A structured caller gets a structured refusal. Exiting 2 with an EMPTY stdout
+        // is the same silence this command is being fixed for, one level up.
+        emitStructured({ error: msg, hint: "run `meta verify --help` for the accepted flags" }, fmt);
         return 2;
     }
     // ADR-0021 D2 — explicit verify subverbs. Each flag selects one drift mode;
@@ -79,9 +101,11 @@ wranglerRunner) {
     // The schema gate is selected by the presence of --db, or --dialect d1 (#225 —
     // D1 has no URL connection); that check lives inside runSchemaVerify.
     const runCodegen = flags.codegen;
+    const runDocs = flags.docs;
     if (!flags.anyExplicit) {
-        log.info("meta verify — running --templates (default). Explicit subverbs: " +
+        say("meta verify — running --templates (default). Explicit subverbs: " +
             "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift), " +
+            "--docs (docs drift), " +
             "--replay/--replay-snapshot (the committed migration chain replays from empty).");
     }
     // Where the metadata lives is `resolveCollection`'s decision, not a hardcoded
@@ -98,7 +122,9 @@ wranglerRunner) {
         collection = await resolveCollection(cwd);
     }
     catch (err) {
-        log.error(err.message);
+        const msg = err.message;
+        log.error(msg);
+        emitStructured({ error: msg, hint: "declare metadata `sources` in .metaobjects/config.json, or run `meta init`" }, fmt);
         return 2;
     }
     // The project root is whichever directory `resolveCollection` decided the
@@ -163,15 +189,40 @@ wranglerRunner) {
     catch (err) {
         const msg = err.message;
         log.error(`failed to load metadata: ${msg}`);
-        // Strict-load rejection (ADR-0023): give the author the three exits — register
-        // the attr on a provider, stash it in the `attr.properties` bag, or pass --lax.
+        // Strict-load rejection (ADR-0023). Two different failures reach here and they need
+        // different advice:
+        //
+        //   a TYPO'd or genuinely undeclared attr — the three exits below are right;
+        //   a RETIRED attr — the loader already knows the exits and attaches them as
+        //   ADR-0009 `suggestions[]`, so we print those and say nothing of our own.
+        //
+        // The distinction is not cosmetic. The middle generic exit — the `attr.properties`
+        // bag — is EXEMPT from the strict-attr check by subtype, so it loads. Offer it for a
+        // retired attribute and the author gets a green `meta verify` over a value that now
+        // reaches nothing: a correct, loud failure converted into a quiet, wrong pass. That is
+        // strictly worse than the error it replaced.
         const code = err.code;
-        if (code === ERR_UNKNOWN_ATTR || msg.includes("Unknown attribute")) {
-            log.error("meta verify is strict (ADR-0023): every authored @attr must be declared. " +
-                "Fix: register the attr on a metadata provider, OR move arbitrary " +
-                "author-supplied properties into an `attr.properties` bag, OR re-run " +
-                "with `meta verify --lax` to keep the legacy open-attr load.");
+        const suggestions = err.suggestions;
+        const strictHint = "meta verify is strict (ADR-0023): every authored @attr must be declared. " +
+            "Fix: register the attr on a metadata provider, OR move arbitrary " +
+            "author-supplied properties into an `attr.properties` bag, OR re-run " +
+            "with `meta verify --lax` to keep the legacy open-attr load.";
+        const isStrictAttr = code === ERR_UNKNOWN_ATTR || msg.includes("Unknown attribute");
+        if (suggestions !== undefined && suggestions.length > 0) {
+            for (const s of suggestions)
+                log.error(`  ${s}`);
+        }
+        else if (isStrictAttr) {
+            log.error(strictHint);
         }
+        // The same refusal, machine-readable. No gate ran, so there is no verdict to
+        // report — only why there is none.
+        emitStructured({
+            error: `failed to load metadata: ${msg}`,
+            hint: suggestions !== undefined && suggestions.length > 0
+                ? suggestions.join(" ")
+                : isStrictAttr ? strictHint : "fix the metadata error above and re-run",
+        }, fmt);
         return 1;
     }
     // The schema gate governs exactly the objects `meta migrate` governs — ONE
@@ -181,12 +232,29 @@ wranglerRunner) {
     const schemaScope = collection.inMigrateScope;
     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
+    // 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.
+    let requirementSection = skippedSection("the requirement pass did not run");
+    let antiPatternSection = skippedSection("the advisory anti-pattern pass 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
+    // ledger instead of no ledger.
+    let requirementCounts;
+    // Whether the schema gate is selected. `runSchemaVerify` makes this decision
+    // internally (it is selected by --db or --dialect d1, not by a subverb flag);
+    // naming it here lets the structured payload report "ran" from the SAME
+    // expression rather than a second guess at it.
+    const ranSchemaGate = (flags.db !== undefined || flags.dialect === "d1") && !flags.skipSchema;
     // Exit-code composition: the overall result is the MAX across every selected
     // subverb so ANY kind of drift fails CI. Each gate only runs when its mode is
     // selected; an unselected gate contributes 0.
     const templateExit = runTemplates ? runTemplateVerify() : 0;
     const schemaExit = await runSchemaVerify();
     const codegenExit = runCodegen ? await runCodegenVerify() : 0;
+    const docsExit = runDocs ? await runDocsVerify() : 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.
@@ -200,9 +268,29 @@ wranglerRunner) {
     // 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`).
-    if (!flags.noAntipatterns && process.env.META_NO_ANTIPATTERNS !== "1")
-        runAntiPatternAdvisory();
-    return Math.max(templateExit, schemaExit, codegenExit, requirementExit, replayExit);
+    runAntiPatternAdvisory();
+    const exitCode = Math.max(templateExit, schemaExit, codegenExit, docsExit, requirementExit, replayExit);
+    if (structured) {
+        emitStructured(buildVerifyPayload({
+            gates: [
+                { gate: "templates", ran: runTemplates, ok: templateExit === 0 },
+                // The schema gate decides internally whether it is selected (--db, or
+                // --dialect d1), so "ran" is read off the same signals rather than
+                // restated: a payload that claims a gate ran when it did not is the
+                // failure mode this whole change exists to remove.
+                { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
+                { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
+                { gate: "docs", ran: runDocs, ok: docsExit === 0 },
+                { gate: "requirements", ran: true, ok: requirementExit === 0 },
+                { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
+            ],
+            exitCode,
+            requirements: requirementSection,
+            requirementCounts,
+            antiPatterns: antiPatternSection,
+        }), fmt);
+    }
+    return exitCode;
     // -- replay (#313) ---------------------------------------------------------
     /**
      * Replay the committed migration chain into an EMPTY throwaway database and assert
@@ -278,12 +366,12 @@ wranglerRunner) {
             // empty replay is still compared against a snapshot that may record dozens of
             // tables, rather than reporting success having compared nothing.
             if (applied.pending.length === 0) {
-                log.info(`meta verify --replay: no committed migrations — nothing to replay`);
+                say(`meta verify --replay: no committed migrations — nothing to replay`);
                 if (!flags.replaySnapshot)
                     return 0;
             }
             else {
-                log.info(`meta verify --replay — the committed chain applies to an empty ${dialect} database ` +
+                say(`meta verify --replay — the committed chain applies to an empty ${dialect} database ` +
                     `(${applied.applied.length} migration(s)).`);
             }
             if (!flags.replaySnapshot)
@@ -318,11 +406,11 @@ wranglerRunner) {
             snapshot = await readSnapshot(snapshotPath(dir, dialect));
         }
         catch {
-            log.info(`meta verify --replay-snapshot: the committed snapshot could not be read — nothing to compare`);
+            say(`meta verify --replay-snapshot: the committed snapshot could not be read — nothing to compare`);
             return 0;
         }
         if (snapshot === null) {
-            log.info(`meta verify --replay-snapshot: no committed snapshot — nothing to compare`);
+            say(`meta verify --replay-snapshot: no committed snapshot — nothing to compare`);
             return 0;
         }
         // A scoped project carries the OTHER owner's tables into its snapshot on purpose
@@ -354,7 +442,7 @@ wranglerRunner) {
             ...(governed !== undefined ? { governed } : {}),
         });
         if (result.ok) {
-            log.info(`meta verify --replay-snapshot — the replayed chain reproduces the committed snapshot.`);
+            say(`meta verify --replay-snapshot — the replayed chain reproduces the committed snapshot.`);
             return 0;
         }
         log.error(`meta verify --replay-snapshot: the replayed chain does not reproduce the committed snapshot. ` +
@@ -396,31 +484,45 @@ wranglerRunner) {
             // all, which is why nothing had ever flagged the templates living in them. No
             // check can see a tree it was never pointed at, so the honest fix is to publish
             // what the count was taken over and let a wrong number be noticeable.
-            log.info(`meta verify — requirements: ${s.total} entries (${s.functional} functional, ` +
+            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).`);
             if (s.undecided > 0) {
-                log.info(`meta verify — requirements: ${s.undecided} recorded gap(s) with no @disposition. ` +
+                say(`meta verify — requirements: ${s.undecided} recorded gap(s) with no @disposition. ` +
                     `These are known problems nobody has ruled on — set 'accepted' or 'deferred' to close the question.`);
             }
+            // The same counts, machine-readable. `metadataFiles` travels with them for the
+            // reason the text line carries it: the claimed/total ratio is only ever taken
+            // over what actually loaded, so a reader needs the denominator's provenance to
+            // notice a spine that covers half an estate.
+            requirementCounts = {
+                total: s.total,
+                functional: s.functional,
+                architectural: s.architectural,
+                byStatus: order
+                    .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,
+                metadataFiles: collection.files.length,
+            };
         }
         const errors = diags.filter((d) => d.severity === "error");
         const warns = diags.filter((d) => d.severity === "warn");
-        const CAP = 20;
-        const fmt = (d) => `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
-        /** Print a capped run of warnings. Capped per SECTION, never across them: a
-         *  ledger of a few hundred entries can produce hundreds of prose findings, and a
-         *  shared cap would let the advisory lint push every gate warning off the end. */
-        const warnCapped = (ds) => {
-            for (const d of ds.slice(0, CAP))
-                log.warn(fmt(d));
-            if (ds.length > CAP)
-                log.warn(`  …and ${ds.length - CAP} more.`);
-        };
+        // 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) => `  ${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(fmt(d));
-        warnCapped(warns);
+            log.error(fmtDiag(d));
+        warnCapped(warns.map(fmtDiag), 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
         // says the ledger DISAGREES WITH THE MODEL; the lint says it agrees but
@@ -446,8 +548,15 @@ wranglerRunner) {
         if (lint.length > 0) {
             log.warn(`meta verify — requirements: ${lint.length} authoring warning(s) ` +
                 `(advisory — does not fail the build):`);
-            warnCapped(lint);
+            warnCapped(lint.map(fmtDiag), flags.limit, { structured });
         }
+        // Everything this pass found, uncapped, for the structured payload — gate
+        // diagnostics and lint findings in one list, each row saying which it is, so a
+        // reader can tell what can fail a build from what never can.
+        requirementSection = ranSection([
+            ...diags.map((d) => toDiagnosticRow(d, "gate")),
+            ...lint.map((d) => toDiagnosticRow(d, "lint")),
+        ]);
         if (errors.length > 0) {
             log.error(`meta verify — requirements: ${errors.length} error(s).`);
             return 1;
@@ -455,30 +564,41 @@ wranglerRunner) {
         return 0;
     }
     // -- 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() {
+        if (flags.noAntipatterns) {
+            antiPatternSection = skippedSection("suppressed by --no-antipatterns");
+            return;
+        }
+        if (process.env.META_NO_ANTIPATTERNS === "1") {
+            antiPatternSection = skippedSection("suppressed by META_NO_ANTIPATTERNS=1");
+            return;
+        }
         let findings;
         try {
-            findings = scanSourceForAntiPatterns(projectRoot);
+            const ignore = forgeConfig?.verify?.antiPatternIgnore;
+            findings = scanSourceForAntiPatterns(projectRoot, ignore !== undefined ? { ignore } : undefined);
         }
-        catch {
-            return; // never let an advisory scan break verify
+        catch (err) {
+            // Never let an advisory scan break verify — and never report it as clean.
+            antiPatternSection = skippedSection(`the scan failed: ${err.message}`);
+            return;
         }
+        antiPatternSection = ranSection(antiPatternRows(findings));
         if (findings.length === 0)
             return;
-        const CAP = 10;
         log.warn(`meta verify — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
             `(advisory — does not fail the build):`);
-        for (const f of findings.slice(0, CAP))
-            log.warn(`  ${f.message}`);
-        if (findings.length > CAP)
-            log.warn(`  …and ${findings.length - CAP} more.`);
+        warnCapped(findings.map((f) => `  ${f.message}`), flags.limit, { structured });
     }
     // -- template (prompt / output) drift --------------------------------------
     function runTemplateVerify() {
         // ADR-0039: effective children — resolve rather than rely on root being unextended.
         const templates = root.children().filter((c) => c.type === TYPE_TEMPLATE);
         if (templates.length === 0) {
-            log.info("meta verify — no template.* nodes found; nothing to check.");
+            say("meta verify — no template.* nodes found; nothing to check.");
             return 0;
         }
         let errorCount = 0;
@@ -491,9 +611,19 @@ wranglerRunner) {
         // "11 drift error(s) across 29 template(s)" while failing and "22 template(s)
         // clean" once fixed: seven templates apparently vanishing on the way to green,
         // and a failure line claiming a denominator of work that had not been done.
-        // `checkedTemplates` is now the single unit — templates at least one body of
-        // which was verified. (An @kind=email template has up to three bodies and still
-        // counts once; the line says "template(s)", so it counts templates.)
+        // `checkedTemplates` is the single unit — templates this check ENGAGED with: one
+        // whose body verified, or one that produced an error. (An @kind=email template has
+        // up to three bodies and still counts once; the line says "template(s)", so it counts
+        // templates.)
+        //
+        // "Engaged with" rather than "verified" because an error is not always reached
+        // THROUGH a verified body: an unresolvable @payloadRef, or a body ref that resolves
+        // to nothing, errors and verifies nothing. Counting only verified bodies made the
+        // failure line divide by the population that SUCCEEDED, so a run where every template
+        // failed to resolve its body read "22 drift error(s) across 0 template(s)" — an
+        // errors-with-no-population line that says nothing was checked while naming 22
+        // failures. Found running this gate against a real adopter estate. The clean line is
+        // unaffected: on a passing run no template errors, so engaged == verified.
         let checkedTemplates = 0;
         for (const tmpl of templates) {
             // ADR-0039: effective attrs — @payloadRef may be inherited via an abstract template.
@@ -510,6 +640,7 @@ wranglerRunner) {
                 log.error(`[${tmpl.name}] (${tmpl.subType}) ${ERR_PARTIAL_UNRESOLVED}: ` +
                     `@payloadRef "${payloadRef}" did not resolve to a loaded object.value`);
                 errorCount++;
+                checkedTemplates++;
                 continue;
             }
             // Collect every renderable mustache ref for this template + whether the
@@ -561,12 +692,14 @@ wranglerRunner) {
             const requiredSlots = promptRules ? attrAsStringArray(tmpl.attr(TEMPLATE_ATTR_REQUIRED_SLOTS)) : [];
             const requiredTags = promptRules ? attrAsStringArray(tmpl.attr(TEMPLATE_ATTR_REQUIRED_TAGS)) : [];
             let anyBodyChecked = false;
+            let anyErrorHere = false;
             for (const { label, ref } of refs) {
                 // Render-engine drift check: mustache variables ↔ payload field names.
                 const text = provider.resolve(ref);
                 if (text === undefined) {
                     log.error(`[${tmpl.name}] (${label}) ${ERR_PARTIAL_UNRESOLVED}: ref "${ref}" did not resolve under ${promptsDir}`);
                     errorCount++;
+                    anyErrorHere = true;
                     continue;
                 }
                 const drift = verify(text, fieldTree, { provider, requiredSlots, requiredTags });
@@ -579,17 +712,18 @@ wranglerRunner) {
                     else {
                         log.error(`[${tmpl.name}] (${label}) ${e.code}: ${e.path}`);
                         errorCount++;
+                        anyErrorHere = true;
                     }
                 }
             }
-            if (anyBodyChecked)
+            if (anyBodyChecked || anyErrorHere)
                 checkedTemplates++;
         }
         if (errorCount > 0) {
             log.error(`meta verify — ${errorCount} drift error(s) across ${checkedTemplates} template(s).`);
             return 1;
         }
-        log.info(`meta verify — ${checkedTemplates} template(s) clean${warnCount > 0 ? ` (${warnCount} warning(s))` : ""}.`);
+        say(`meta verify — ${checkedTemplates} template(s) clean${warnCount > 0 ? ` (${warnCount} warning(s))` : ""}.`);
         return 0;
     }
     // -- schema drift (live DB) ------------------------------------------------
@@ -852,17 +986,17 @@ wranglerRunner) {
         // annotate them as external (declared) rather than let them vanish silently.
         const externalDeclared = collectUnmanagedNames(root);
         if (externalDeclared.length > 0) {
-            log.info(`meta verify — ${externalDeclared.length} object(s) external (declared @unmanaged, managed elsewhere): ${externalDeclared.join(", ")}`);
+            say(`meta verify — ${externalDeclared.length} object(s) external (declared @unmanaged, managed elsewhere): ${externalDeclared.join(", ")}`);
         }
         // 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) {
-            log.info(outOfScopeNote("verify", driftResult.outOfScope));
+            say(outOfScopeNote("verify", driftResult.outOfScope));
         }
         const changes = driftResult.changes;
         if (changes.length === 0 && ledgerDrift.length === 0) {
-            log.info(`meta verify — schema in sync with ${displayUrl}.`);
+            say(`meta verify — schema in sync with ${displayUrl}.`);
             return 0;
         }
         // The header is conditional: #292's snapshot findings arrive through `ledgerDrift`
@@ -914,6 +1048,11 @@ wranglerRunner) {
             }
             catch (err) {
                 log.error(`verify --codegen: failed to load this package's metadata: ${err.message}`);
+                // The second door onto the same strict load. It carried no remedy at all, which
+                // meant a retirement diagnosed here told the author what broke and nothing about
+                // how to fix it — the half-true rule this file's sibling comment warns about.
+                for (const s of err.suggestions ?? [])
+                    log.error(`  ${s}`);
                 return 2;
             }
         }
@@ -930,7 +1069,7 @@ wranglerRunner) {
             return 2;
         }
         if (result.clean) {
-            log.info("meta verify — generated output is in sync with the metadata (no codegen drift).");
+            say("meta verify — generated output is in sync with the metadata (no codegen drift).");
             return 0;
         }
         log.error(`meta verify — codegen drift (${result.driftedFiles.length} file(s) differ from a fresh regen):`);
@@ -939,6 +1078,57 @@ wranglerRunner) {
         log.error("Run 'meta gen' to regenerate, then commit the result.");
         return 1;
     }
+    // -- docs drift -------------------------------------------------------------
+    // Gated on --docs. Runs `meta docs` into a temp dir and diffs the committed docs
+    // tree. See lib/docs-drift.ts for the two deliberate differences from --codegen
+    // (a byte difference IS drift here, and a committed file a regen would not emit is
+    // never reported — `docs.outDir` is full of files MetaObjects did not write).
+    //
+    // It needs a config for the same reason `--codegen` does: `docs.outDir` says which
+    // tree to compare against, and the `agent` surface will not even materialise
+    // without one.
+    async function runDocsVerify() {
+        if (forgeConfig === undefined) {
+            log.error("verify --docs: no metaobjects.config.ts found (or it is invalid) — " +
+                "cannot locate the committed docs tree to diff against. " +
+                "Run 'meta init' to scaffold one, or run without --docs.");
+            return 2;
+        }
+        // Resolved through the SAME resolver `meta docs` uses, so a project that moved its
+        // docs elsewhere is checked where its docs actually are. `outputLayout` is the
+        // documented fallback for `docs.layout`.
+        const docsCfg = resolveDocsConfig(forgeConfig.docs, {}, forgeConfig.outputLayout ?? "flat");
+        let result;
+        try {
+            result = await computeDocsDrift({
+                projectRoot: genConfigDir,
+                docsDir: resolvePath(genConfigDir, docsCfg.outDir),
+                cwd: genConfigDir,
+            });
+        }
+        catch (err) {
+            log.error(`verify --docs: regeneration failed: ${err.message}`);
+            return 1;
+        }
+        if (result.error !== undefined) {
+            log.error(result.error);
+            return 2;
+        }
+        if (result.clean) {
+            // The denominator is what was actually COMPARED, so the passing line and the
+            // failing line below count the same set. A gate whose two halves divide by
+            // different numbers is how `verify --templates` came to report seven templates
+            // vanishing between a red run and a green one.
+            say(`meta verify — ${result.checked} docs page(s) match a fresh 'meta docs' (no docs drift).`);
+            return 0;
+        }
+        log.error(`meta verify — docs drift (${result.driftedFiles.length} of ${result.checked} page(s) ` +
+            `differ from a fresh 'meta docs'):`);
+        for (const line of result.lines)
+            log.error(`  ${line}`);
+        log.error("Run 'meta docs' to regenerate, then commit the result.");
+        return 1;
+    }
 }
 /**
  * Migration-history ledger reconciliation hook (Unit 3 — not yet built).
@@ -982,4 +1172,69 @@ function summarizeDrift(changes) {
         return `${p.glyph} ${p.noun} ${describeChange(c)}`;
     });
 }
+/** Project a requirement diagnostic into a payload row. */
+function toDiagnosticRow(d, source) {
+    return {
+        code: d.code,
+        // "" rather than omitted: a tabular encoder (TOON) needs every row to carry the
+        // same keys, and an absent column would silently shift the rest.
+        path: d.path ?? "",
+        severity: d.severity,
+        source,
+        message: d.message,
+    };
+}
+/**
+ * What `--format json|toon` puts on stdout.
+ *
+ * The rule this shape is built to keep: **anything not represented here is
+ * STATED, not silently dropped.** A half-payload that looks complete is the very
+ * defect being fixed — an agent read a run carrying 233 advisory findings as "all
+ * green across the board", because the findings were on stderr as text and the
+ * payload mentioned none of them.
+ *
+ * So: every gate's verdict, every advisory finding (uncapped), and an explicit
+ * `notRepresented` list naming what stays on stderr as text.
+ */
+function buildVerifyPayload(input) {
+    const ran = input.gates.filter((g) => g.ran);
+    const failed = ran.filter((g) => !g.ok);
+    const parts = [
+        failed.length === 0
+            ? `${ran.length} gate(s) ran, all clean`
+            : `${failed.length} of ${ran.length} gate(s) failed (${failed.map((g) => g.gate).join(", ")})`,
+    ];
+    if (input.antiPatterns.status === "ran" && input.antiPatterns.total > 0) {
+        parts.push(`${input.antiPatterns.total} advisory anti-pattern finding(s)`);
+    }
+    if (input.requirements.total > 0) {
+        parts.push(`${input.requirements.total} requirement diagnostic(s)`);
+    }
+    const help = [];
+    if (failed.length > 0) {
+        help.push(`the failing gate's drift DETAIL is printed as text on stderr — this payload carries the verdict only`);
+    }
+    if (input.antiPatterns.total > 0) {
+        help.push(`${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) {
+        help.push("no drift and nothing advisory to answer — nothing to do");
+    }
+    return {
+        verify: input.gates,
+        exitCode: input.exitCode,
+        summary: parts.join("; "),
+        help,
+        antiPatterns: input.antiPatterns,
+        requirements: input.requirements,
+        ...(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
+        // to discover that by its absence.
+        notRepresented: [
+            "per-gate drift detail (which template variable drifted, which schema change, which generated file differs, which migration failed to replay) — printed as text on stderr; this payload carries each gate's pass/fail verdict",
+            "the loader's own warnings and the agent-context/manifest advisories — printed as text on stderr",
+        ],
+    };
+}
 //# sourceMappingURL=verify.js.map