@cleocode/cleo 2026.10.27 → 2026.11.1-canary.2

package/dist/cli/{docs-AIZLN3ZE.js → docs-56FESINI.js}

@@ -25,14 +25,11 @@ import {
   dispatchFromCli,
   dispatchRaw,
   handleRawError
-} from "./chunk-OIS3BDSL.js";
+} from "./chunk-N3CEB7IU.js";
 import "./chunk-6N6WGLXE.js";
 import {
   resolve
 } from "./chunk-4VASFLUW.js";
-import {
-  loadCanonRegistry
-} from "./chunk-SXXOC6KZ.js";
 import {
   UnknownFlagError,
   assertKnownFlags
@@ -49,11 +46,11 @@ import {
 } from "./chunk-ESI6Q4OS.js";
 import "./chunk-6JSJNYH2.js";
 import "./chunk-D7BAQNV2.js";
-import "./chunk-JRDAITPC.js";
+import "./chunk-HFB4FPLA.js";
 
 // packages/cleo/src/cli/commands/docs.ts
 import { existsSync } from "node:fs";
-import { appendFile, mkdir as mkdir3, readdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir3, readdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname3, isAbsolute, join as join4, resolve as resolve3 } from "node:path";
 import {
   DocKindConfigError,
@@ -67,11 +64,6 @@ import {
   resolveWorktreeRouting
 } from "@cleocode/core/core-paths";
 import { createDocsReadModel } from "@cleocode/core/docs/docs-read-model";
-import {
-  checkSlugSimilarity,
-  DEFAULT_SIMILARITY_MODE,
-  DEFAULT_SIMILARITY_THRESHOLD
-} from "@cleocode/core/docs/similarity-check";
 import { CleoError as CleoError2 } from "@cleocode/core/errors";
 import { pushWarning } from "@cleocode/core/output";
 import { getProjectRoot as getProjectRoot3 } from "@cleocode/core/project-scope";
@@ -291,6 +283,113 @@ var migrateCommand = defineCommand({
   }
 });
 
+// packages/cleo/src/cli/commands/docs/modernize.ts
+var modernizeCommand = defineCommand({
+  meta: {
+    name: "modernize",
+    description: "Turn a messy docs folder into clean, linked CleoDocs (T14113). Dry run by default: per file a kind, a stable slug (no task, session or date tokens) and keep/rename/merge-into/delete with reasons; ambiguous classify and merge calls go to System One (cleo decide) with a rule fallback. --apply stores docs, merges duplicates, records supersession, moves files and writes wikilink edges, with a receipt under .cleo/modernize/; --rollback <runId> reverses a run."
+  },
+  args: {
+    path: {
+      type: "positional",
+      description: "Folder to modernize (required unless --rollback or --plan)",
+      required: false
+    },
+    apply: {
+      type: "boolean",
+      description: "Execute the plan (default: dry run, nothing written)"
+    },
+    plan: {
+      type: "string",
+      description: "Apply this saved plan JSON verbatim (with --apply)"
+    },
+    out: {
+      type: "string",
+      description: "Save the plan JSON to this path for review"
+    },
+    rollback: {
+      type: "string",
+      description: "Roll back the apply run with this id (from the receipt)"
+    },
+    exclude: {
+      type: "string",
+      description: "Extra folder names to skip, comma-separated"
+    },
+    overrides: {
+      type: "string",
+      description: "Reviewer decisions JSON keyed by path; they win over rules and System One"
+    },
+    kind: {
+      type: "string",
+      description: "Use this kind for every file instead of classifying (bulk ingest)"
+    },
+    "allow-dirty": {
+      type: "boolean",
+      description: "Apply even when the root is not a clean git checkout (default: refuse)"
+    },
+    store: {
+      type: "boolean",
+      description: "Modernize the docs already in the store: re-kind, re-slug (old slugs stay as aliases), renumber colliding ADRs"
+    },
+    "store-only": {
+      type: "boolean",
+      description: "Ingest every file into the store (task-owned) and leave the folder untouched"
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "mutate",
+      "docs",
+      "modernize",
+      {
+        ...typeof args.path === "string" ? { path: args.path } : {},
+        apply: args.apply === true,
+        ...typeof args.plan === "string" ? { planFile: args.plan } : {},
+        ...typeof args.out === "string" ? { out: args.out } : {},
+        ...typeof args.rollback === "string" ? { rollback: args.rollback } : {},
+        ...typeof args.exclude === "string" ? { exclude: args.exclude } : {},
+        ...typeof args.overrides === "string" ? { overrides: args.overrides } : {},
+        ...typeof args.kind === "string" ? { kind: args.kind } : {},
+        storeOnly: args["store-only"] === true,
+        allowDirty: args["allow-dirty"] === true,
+        store: args.store === true
+      },
+      { command: "docs modernize" }
+    );
+  }
+});
+
+// packages/cleo/src/cli/commands/docs/rot.ts
+var rotCommand = defineCommand({
+  meta: {
+    name: "rot",
+    description: "Docs-rot report from git alone (T14111): docs whose covers: code changed after them (stale), duplicate docs, and orphaned docs (dead covers globs, unreferenced docs/ files). --changed <base>..<head> also lists the docs a merged change left stale; --strict exits 2 on any finding."
+  },
+  args: {
+    changed: {
+      type: "string",
+      description: "Git range <base>..<head> of a merged change to flag docs for"
+    },
+    strict: {
+      type: "boolean",
+      description: "Exit 2 when the report finds stale, duplicate, orphaned or flagged docs"
+    }
+  },
+  async run({ args }) {
+    const params = typeof args.changed === "string" ? { changed: args.changed } : {};
+    if (args.strict !== true) {
+      await dispatchFromCli("query", "docs", "rot", params, { command: "docs rot" });
+      return;
+    }
+    const response = await dispatchRaw("query", "docs", "rot", params);
+    handleRawError(response, { command: "docs rot", operation: "docs.rot" });
+    const report = response.data;
+    cliOutput(report, { command: "docs rot", message: report.summary });
+    const findings = report.stale.length + report.duplicates.length + report.orphans.length + report.flagged.length;
+    if (findings > 0) process.exit(2);
+  }
+});
+
 // packages/cleo/src/cli/commands/docs/set-alias.ts
 import { ExitCode as ExitCode3 } from "@cleocode/contracts/exit-codes.js";
 import { setDisplayAlias } from "@cleocode/core/docs/display-alias";
@@ -1272,7 +1371,7 @@ async function runGapCheck(_projectRoot, filterId) {
 var addCommand = defineCommand({
   meta: {
     name: "add",
-    description: 'Usage: cleo docs add <OWNER-ID> [<file>] [--content <text> | --url <url>] [--slug <kebab>] [--type <kind>]\n  OWNER-ID is the FIRST positional; the file is the SECOND. Examples:\n    cleo docs add T123 ./docs/rfc.md --slug my-rfc --type spec\n    cleo docs add T123 --content "# Note" --slug my-note\n\nAttach a local file or remote URL to a CLEO entity (task, session, observation). Owner type is inferred from the ID prefix: T### \u2192 task, ses_* \u2192 session, O-* \u2192 observation. Use --slug to set a human-friendly alias (unique per project) (T9636).\n\nPositional arguments:\n  <owner-id>             Owner entity ID (T###, ses_*, O-*) \u2014 required\n  [file]                 Local file path to attach \u2014 optional when --url/--content is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\n  --content <text>       Inline document body \u2014 author without a file (T10965); \'-\' reads stdin\n  --desc <text>          Free-text description of this attachment\n  --labels <csv>         Comma-separated labels (e.g. rfc,spec)\n  --attached-by <name>   Agent identity that created the attachment (default: "human")\n  --slug <kebab>         Human-friendly alias, unique per project (T9636)\n  --title <text>         Human-readable title \u2014 REQUIRED for --type adr when --slug is omitted (T10360)\n  --type <kind>          Taxonomy classification \u2014 run `cleo docs schema` for kinds\n  --allow-similar        Bypass the slug-similarity warn \u2014 every bypass is audited\n                         to .cleo/audit/similar-bypass.jsonl (T10361)\n  --strict               Enforce body-schema (requiredSections) \u2014 fail with\n                         E_DOC_SCHEMA_MISMATCH instead of warning (T10160)\n' + docsOutputFlagHelp + "\n\nValidation behaviors:\n  \u2022 Unknown flags \u2192 E_UNKNOWN_FLAG with did-you-mean suggestions (T10359)\n  \u2022 Slug collision \u2192 E_SLUG_RESERVED + 3 alternative slugs (T10386)\n  \u2022 Near-duplicate slug \u2192 W_SLUG_SIMILAR warning unless --allow-similar (T10361)\n  \u2022 For --type adr without --slug, slug auto-allocates as `adr-NNN-<kebab-title>` via the\n    central allocator (T10360 \u2014 closes T10153). --title is required in this case."
+    description: 'Usage: cleo docs add <OWNER-ID> [<file>] [--content <text> | --url <url>] [--slug <kebab>] [--type <kind>]\n  OWNER-ID is the FIRST positional; the file is the SECOND. Examples:\n    cleo docs add T123 ./docs/rfc.md --slug my-rfc --type spec\n    cleo docs add T123 --content "# Note" --slug my-note\n\nAttach a local file or remote URL to a CLEO entity (task, session, observation). Owner type is inferred from the ID prefix: T### \u2192 task, ses_* \u2192 session, O-* \u2192 observation. Use --slug to set a human-friendly alias (unique per project) (T9636).\n\nPositional arguments:\n  <owner-id>             Owner entity ID (T###, ses_*, O-*) \u2014 required\n  [file]                 Local file path to attach \u2014 optional when --url/--content is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\n  --content <text>       Inline document body \u2014 author without a file (T10965); \'-\' reads stdin\n  --desc <text>          Free-text description of this attachment\n  --labels <csv>         Comma-separated labels (e.g. rfc,spec)\n  --attached-by <name>   Agent identity that created the attachment (default: "human")\n  --slug <kebab>         Human-friendly alias, unique per project (T9636)\n  --title <text>         Human-readable title \u2014 REQUIRED for --type adr when --slug is omitted (T10360)\n  --type <kind>          Taxonomy classification \u2014 run `cleo docs schema` for kinds\n  --new-because <why>    Add a doc that resembles an existing one; the reason is\n                         recorded in .cleo/audit/docs-new-because.jsonl (T14109)\n  --strict               Enforce body-schema (requiredSections) \u2014 fail with\n                         E_DOC_SCHEMA_MISMATCH instead of warning (T10160)\n' + docsOutputFlagHelp + "\n\nValidation behaviors:\n  \u2022 Unknown flags \u2192 E_UNKNOWN_FLAG with did-you-mean suggestions (T10359)\n  \u2022 Slug collision \u2192 E_SLUG_RESERVED + 3 alternative slugs (T10386)\n  \u2022 Likely duplicate (same content, or similar slug, title or text) \u2192 E_DOC_DUPLICATE,\n    naming the existing doc, `cleo docs fetch <slug>` and `cleo docs update <slug>`,\n    unless --new-because <why> (T14109)\n  \u2022 For --type adr without --slug, slug auto-allocates as `adr-NNN-<kebab-title>` via the\n    central allocator (T10360 \u2014 closes T10153). --title is required in this case."
   },
   args: {
     "owner-id": {
@@ -1317,9 +1416,13 @@ var addCommand = defineCommand({
       type: "string",
       description: "Taxonomy classification \u2014 run `cleo docs schema` to enumerate registered kinds (T9637 / T9788 / T11142)"
     },
+    "new-because": {
+      type: "string",
+      description: "Why this doc is new although it resembles an existing one (T14109). A likely duplicate (same content, or a similar slug, title or text) is refused with E_DOC_DUPLICATE and routed to `cleo docs update <slug>` unless this states the reason (15+ characters); the reason is recorded in .cleo/audit/docs-new-because.jsonl."
+    },
     "allow-similar": {
       type: "boolean",
-      description: "Bypass the T10361 slug-similarity check. Use when you really do mean to add a new doc with a near-duplicate slug (e.g. intentional fork). Every bypass is logged to .cleo/audit/similar-bypass.jsonl."
+      description: "Deprecated (T14109): needs --new-because <reason>, which is what lets a likely duplicate through."
     },
     strict: {
       type: "boolean",
@@ -1399,83 +1502,17 @@ var addCommand = defineCommand({
         process.exit(ExitCode6.FILE_ERROR);
       }
     }
-    if (args.slug && args.type) {
-      const projectRoot = await getProjectRoot3();
-      let warnThreshold = DEFAULT_SIMILARITY_THRESHOLD;
-      let mode = DEFAULT_SIMILARITY_MODE;
-      try {
-        const canon = loadCanonRegistry(projectRoot);
-        if (canon?.similarity) {
-          warnThreshold = canon.similarity.warnThreshold;
-          mode = canon.similarity.mode;
-        }
-      } catch {
-      }
-      try {
-        const sim = await checkSlugSimilarity({
-          slug: args.slug,
-          type: args.type,
-          projectRoot,
-          threshold: warnThreshold
-        });
-        if (sim.mostSimilarSlug !== null) {
-          const scoreFixed = sim.score.toFixed(2);
-          const hint = `Similar to '${sim.mostSimilarSlug}' (score ${scoreFixed}) \u2014 did you mean: cleo docs update ${sim.mostSimilarSlug}? Pass --allow-similar to bypass.`;
-          if (mode === "block" && !allowSimilar) {
-            cliError(hint, ExitCode6.VALIDATION_ERROR, {
-              name: "E_SLUG_SIMILARITY",
-              fix: `Use \`cleo docs update ${sim.mostSimilarSlug}\` if updating, or pass --allow-similar to add as a new doc.`,
-              alternatives: [
-                {
-                  action: `update '${sim.mostSimilarSlug}' instead`,
-                  command: `cleo docs update ${sim.mostSimilarSlug}`
-                },
-                {
-                  action: "bypass the similarity check",
-                  command: `cleo docs add ${ownerId} ${fileArg ?? `--url ${url}`} --slug ${args.slug} --type ${args.type} --allow-similar`
-                }
-              ],
-              details: {
-                proposedSlug: args.slug,
-                mostSimilarSlug: sim.mostSimilarSlug,
-                score: sim.score,
-                threshold: warnThreshold,
-                kind: args.type
-              }
-            });
-            process.exit(ExitCode6.VALIDATION_ERROR);
-          }
-          humanInfo(hint);
-          if (allowSimilar) {
-            const auditLine = `${JSON.stringify({
-              ts: (/* @__PURE__ */ new Date()).toISOString(),
-              reason: "allow-similar-bypass",
-              proposedSlug: args.slug,
-              mostSimilarSlug: sim.mostSimilarSlug,
-              score: sim.score,
-              threshold: warnThreshold,
-              kind: args.type,
-              ownerId
-            })}
-`;
-            try {
-              await mkdir3(join4(projectRoot, ".cleo", "audit"), { recursive: true });
-              await appendFile(
-                join4(projectRoot, ".cleo", "audit", "similar-bypass.jsonl"),
-                auditLine,
-                "utf-8"
-              );
-            } catch {
-            }
-          }
-        }
-      } catch (err) {
-        if (process.env["CLEO_DEBUG"]) {
-          humanInfo(
-            `similarity check skipped: ${err instanceof Error ? err.message : String(err)}`
-          );
+    const newBecause = args["new-because"];
+    if (allowSimilar && typeof newBecause !== "string") {
+      cliError(
+        "--allow-similar no longer bypasses the duplicate check on its own; say why this doc is new",
+        6,
+        {
+          name: "E_VALIDATION",
+          fix: 'Pass --new-because "<why this is not the existing doc>" (recorded in .cleo/audit/docs-new-because.jsonl), or update the existing doc with cleo docs update <slug>.'
         }
-      }
+      );
+      process.exit(6);
     }
     await dispatchFromCli(
       "mutate",
@@ -1492,7 +1529,8 @@ var addCommand = defineCommand({
         ...args.slug ? { slug: args.slug } : {},
         ...args.title ? { title: args.title } : {},
         ...args.type ? { type: args.type } : {},
-        ...args.strict === true ? { strict: true } : {}
+        ...args.strict === true ? { strict: true } : {},
+        ...typeof newBecause === "string" ? { newBecause } : {}
       },
       { command: "docs add" }
     );
@@ -2562,7 +2600,7 @@ function parseOlderThanDays(raw) {
 var doctorCommand = defineCommand({
   meta: {
     name: "doctor",
-    description: "Docs store health diagnostics + safe repairs: dangling local-file pointers, docVersion skew vs the audit log, empty topics/related_tasks provenance, docs_wikilinks drift, legacy store surfaces, blob-store coverage, stale drafts. Dry-run by default; --apply executes repairs (a fresh backup is created automatically first); --repair runs only the hash-verified legacy-bytes \u2192 blob-store backfill (T13653)."
+    description: "Docs store health diagnostics + safe repairs: dangling local-file pointers, docVersion skew vs the audit log, empty topics/related_tasks provenance, docs_wikilinks drift, legacy store surfaces, blob-store coverage, stale drafts, publication-ledger drift (rows whose mirror is gone or stale; T14117). Dry-run by default; --apply executes repairs (a fresh backup is created automatically first); --repair runs only the hash-verified legacy-bytes \u2192 blob-store backfill (T13653)."
   },
   args: {
     apply: {
@@ -2875,8 +2913,12 @@ var docsCommand = defineCommand({
     triage: triageCommand,
     // T13363 — docs.stats adoption metrics (read-only)
     stats: statsCommand,
+    // T14111 — docs.rot stale/duplicate/orphaned report (read-only, git only)
+    rot: rotCommand,
     // T13360 — docs.migrate legacy docs import (harness-bracketed, idempotent)
     migrate: migrateCommand,
+    // T14113 — docs.modernize (dry run / apply / rollback)
+    modernize: modernizeCommand,
     // Drift status — agent-facing, kept per cleodocs-rearch-design §6 (T13361 retired gap-check only)
     status: statusCommand,
     // T9645 reingest — retained: the docs-reingest workflow invokes `docs sync --from/--for/--name`
@@ -2897,4 +2939,4 @@ export {
   _llmOutputCommand,
   docsCommand
 };
-//# sourceMappingURL=docs-AIZLN3ZE.js.map
+//# sourceMappingURL=docs-56FESINI.js.map

package/dist/cli/{docs-NF5COLOB.js → docs-HOAUXIRZ.js}

@@ -15,7 +15,7 @@
 })();
 import {
   lazyOperation
-} from "./chunk-JRDAITPC.js";
+} from "./chunk-HFB4FPLA.js";
 import {
   defineTypedHandler,
   lafsError,
@@ -29,7 +29,7 @@ import {
 } from "./chunk-XD25OCUE.js";
 
 // packages/cleo/src/dispatch/domains/docs.ts
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { DocKindRegistry } from "@cleocode/contracts/docs-taxonomy.js";
@@ -75,6 +75,12 @@ var allocateAdrSlug = lazyOperation(
 var allocateAutoSlugForDispatch = lazyOperation(
   async () => (await import("@cleocode/core/docs/numbering")).allocateAutoSlugForDispatch
 );
+var docNameViolation = lazyOperation(
+  async () => (await import("@cleocode/core/docs/doc-name-rule")).docNameViolation
+);
+var describeDocNameViolation = lazyOperation(
+  async () => (await import("@cleocode/core/docs/doc-name-rule")).describeDocNameViolation
+);
 var exportDocument = lazyOperation(
   async () => (await import("@cleocode/core/docs/export-document")).exportDocument
 );
@@ -130,6 +136,12 @@ var triageDocs = lazyOperation(
 var computeDocsStats = lazyOperation(
   async () => (await import("@cleocode/core/docs/stats")).computeDocsStats
 );
+var runDocsModernize = lazyOperation(
+  async () => (await import("@cleocode/core/docs/modernize/index")).runDocsModernize
+);
+var scanDocsRot = lazyOperation(
+  async () => (await import("@cleocode/core/docs/rot")).scanDocsRot
+);
 var runLegacyDocMigration = lazyOperation(
   async () => (await import("@cleocode/core/docs/legacy-doc-migration")).runLegacyDocMigration
 );
@@ -284,12 +296,9 @@ var _docsTypedHandler = defineTypedHandler("docs", {
     const model = createDocsReadModel();
     const backend = await currentAttachmentBackend();
     if (isProjectScope) {
-      const docs = await model.listProjectDocs({
-        kind: typeFilter,
-        limit: Number.isFinite(effectiveLimit) ? effectiveLimit : void 0
-      });
+      const docs = await model.listProjectDocs({ kind: typeFilter });
       const totalCount = docs.length;
-      const projected = docs.map((doc) => ({
+      const allProjected = docs.map((doc) => ({
         id: doc.id,
         // Full content hash — a SHA-256 field in a machine envelope must be the
         // real digest, never a display-truncated form (T11294: the per-doc
@@ -312,12 +321,13 @@ var _docsTypedHandler = defineTypedHandler("docs", {
         ownerId: doc.ownerId,
         ownerType: doc.ownerType
       }));
-      projected.sort(
+      allProjected.sort(
         (a, b) => comparator(
           { sha256: a.sha256, slug: a.slug, createdAt: a.createdAt },
           { sha256: b.sha256, slug: b.slug, createdAt: b.createdAt }
         )
       );
+      const projected = Number.isFinite(effectiveLimit) ? allProjected.slice(0, effectiveLimit) : allProjected;
       const truncated = totalCount > projected.length;
       if (truncated) {
         hintParts.push(
@@ -332,6 +342,12 @@ var _docsTypedHandler = defineTypedHandler("docs", {
           ...typeFilter !== void 0 ? { type: typeFilter } : {},
           count: projected.length,
           ...truncated ? { totalCount } : {},
+          population: {
+            matched: totalCount,
+            returned: projected.length,
+            truncated,
+            limit: Number.isFinite(effectiveLimit) ? effectiveLimit : null
+          },
           limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
           orderBy,
           ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
@@ -381,6 +397,12 @@ var _docsTypedHandler = defineTypedHandler("docs", {
         ...typeFilter !== void 0 ? { type: typeFilter } : {},
         count: slicedOwner.length,
         ...truncatedOwner ? { totalCount: totalCountOwner } : {},
+        population: {
+          matched: totalCountOwner,
+          returned: slicedOwner.length,
+          truncated: truncatedOwner,
+          limit: Number.isFinite(effectiveLimit) ? effectiveLimit : null
+        },
         limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
         orderBy,
         ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
@@ -616,6 +638,28 @@ var _docsTypedHandler = defineTypedHandler("docs", {
       "migrate"
     );
   },
+  // ── docs.modernize (T14113 — messy docs folder → linked CleoDocs) ─────────
+  modernize: async (params) => {
+    let result;
+    try {
+      result = await runDocsModernize(getProjectRoot(), {
+        ...params,
+        exclude: params.exclude?.split(",").map((e) => e.trim()).filter(Boolean)
+      });
+    } catch (err) {
+      const code = err instanceof Error && "code" in err ? String(err.code) : "";
+      if (!code.startsWith("E_MODERNIZE")) throw err;
+      return lafsError(
+        code,
+        // @sync-invariant none:input-shape a stale plan, missing root or unknown receipt is refused; the receipt holds any earlier step
+        err instanceof Error ? err.message : code,
+        "modernize"
+      );
+    }
+    const counts = result.plan?.counts;
+    const summary = result.mode === "rollback" ? `rolled back ${result.receipt?.runId} (${result.receipt?.ops.length ?? 0} steps reversed)` : (result.plan?.mode === "store" ? `${result.plan.storeRows?.length ?? 0} stored docs to re-kind or re-slug` : `${result.plan?.rows.length ?? 0} files: ${counts?.keep ?? 0} keep, ${counts?.rename ?? 0} rename, ${counts?.["merge-into"] ?? 0} merge, ${counts?.delete ?? 0} delete`) + (result.receipt ? `; applied as ${result.receipt.runId} (${result.receipt.ops.length} steps, ${result.receipt.edgeCount} graph edges)` : "; dry run, nothing written");
+    return lafsSuccess({ ...result, summary }, "modernize");
+  },
   // ── docs.add ───────────────────────────────────────────────────────────────
   add: async (params) => {
     const {
@@ -629,7 +673,8 @@ var _docsTypedHandler = defineTypedHandler("docs", {
       slug: rawSlug,
       title: rawTitle,
       type: rawType,
-      strict: strictMode
+      strict: strictMode,
+      newBecause
     } = params;
     if (!ownerId) {
       return lafsError("E_INVALID_INPUT", "ownerId is required", "add");
@@ -841,6 +886,71 @@ var _docsTypedHandler = defineTypedHandler("docs", {
               );
             }
           }
+          if (slug !== void 0) {
+            const nameCheck = await docNameViolation(slug, type);
+            if (nameCheck !== null) {
+              if (adrNumber !== void 0) releaseReservedSlug(slug);
+              return lafsError(
+                "E_DOC_NAME_RULE",
+                // @sync-invariant none:input-shape a slug that breaks the doc naming rule is refused before anything is written
+                await describeDocNameViolation(slug, nameCheck),
+                "add",
+                `cleo docs add ... --slug ${nameCheck.suggestion}`,
+                { suggestion: nameCheck.suggestion, reasons: nameCheck.reasons }
+              );
+            }
+          }
+          {
+            const reason = typeof newBecause === "string" ? newBecause.trim() : void 0;
+            const dup = await import("@cleocode/core/docs/duplicate-check");
+            if (reason !== void 0 && reason.length < dup.NEW_BECAUSE_MIN_LENGTH) {
+              if (adrNumber !== void 0 && slug !== void 0) releaseReservedSlug(slug);
+              return lafsError(
+                "E_INVALID_INPUT",
+                // @sync-invariant none:input-shape a too-short --new-because reason is refused before anything is written
+                `--new-because needs a reason of at least ${dup.NEW_BECAUSE_MIN_LENGTH} characters saying why this is not an existing doc`,
+                "add"
+              );
+            }
+            const bytes = typeof inlineContent === "string" ? Buffer.from(inlineContent, "utf-8") : filePath ? await readFile(resolve(String(filePath))).catch(() => null) : null;
+            const text = bytes?.toString("utf-8");
+            const title = (typeof rawTitle === "string" && rawTitle.trim() ? rawTitle : null) ?? (text ? dup.markdownTitle(text) : null);
+            const match = type === void 0 ? null : dup.findDuplicateDoc(
+              {
+                ...slug !== void 0 ? { slug } : {},
+                ...type !== void 0 ? { kind: type } : {},
+                ...title !== null ? { title } : {},
+                ...text !== void 0 ? { content: text } : {},
+                ...bytes ? { sha256: createHash("sha256").update(bytes).digest("hex") } : {}
+              },
+              await dup.loadDuplicateCandidates(projectRoot, { kind: type }),
+              await dup.readDuplicateThresholds(projectRoot)
+            );
+            if (match && reason === void 0) {
+              if (adrNumber !== void 0 && slug !== void 0) releaseReservedSlug(slug);
+              const { message, fix } = dup.describeDuplicate(match);
+              return lafsError(
+                "E_DOC_DUPLICATE",
+                // @sync-invariant none:input-shape a likely duplicate doc is refused before anything is written
+                message,
+                "add",
+                fix,
+                {
+                  existing: { slug: match.slug, kind: match.kind, title: match.title },
+                  rule: match.rule,
+                  score: match.score
+                }
+              );
+            }
+            if (match && reason !== void 0) {
+              await dup.recordNewBecause(projectRoot, {
+                slug: slug ?? null,
+                kind: type ?? null,
+                resembles: match,
+                reason
+              });
+            }
+          }
           if (slug !== void 0 && adrNumber === void 0) {
             const reservation = await reserveSlugForDispatch(projectRoot, {
               kind: type ?? "",
@@ -1541,7 +1651,8 @@ var QUERY_OPS = /* @__PURE__ */ new Set([
   "audit",
   "doctor",
   "triage",
-  "stats"
+  "stats",
+  "rot"
 ]);
 var MUTATE_OPS = /* @__PURE__ */ new Set([
   "add",
@@ -1555,7 +1666,8 @@ var MUTATE_OPS = /* @__PURE__ */ new Set([
   "sync",
   "import",
   "doctor",
-  "migrate"
+  "migrate",
+  "modernize"
 ]);
 async function dispatchDocsLegacyQuery(operation, params) {
   const projectRoot = getProjectRoot();
@@ -1625,6 +1737,11 @@ async function dispatchDocsLegacyQuery(operation, params) {
       });
     case "stats":
       return computeDocsStats({ projectRoot });
+    case "rot":
+      return scanDocsRot({
+        projectRoot,
+        ...typeof params["changed"] === "string" ? { changed: params["changed"] } : {}
+      });
     default:
       throw new Error(`Unsupported docs query operation: ${operation}`);
   }
@@ -1855,7 +1972,8 @@ var DocsHandler = class {
         "audit",
         "doctor",
         "triage",
-        "stats"
+        "stats",
+        "rot"
       ],
       mutate: [
         "add",
@@ -1869,7 +1987,8 @@ var DocsHandler = class {
         "sync",
         "import",
         "doctor",
-        "migrate"
+        "migrate",
+        "modernize"
       ]
     };
   }
@@ -1877,4 +1996,4 @@ var DocsHandler = class {
 export {
   DocsHandler
 };
-//# sourceMappingURL=docs-NF5COLOB.js.map
+//# sourceMappingURL=docs-HOAUXIRZ.js.map

package/dist/cli/{doctor-4DWCNDOP.js → doctor-4GX4L5UU.js}

@@ -27,10 +27,13 @@ import {
 } from "./chunk-RBI6IBDF.js";
 import {
   doctorToolLocksCommand
-} from "./chunk-TUUKU4H7.js";
+} from "./chunk-5AL6B3J2.js";
 import {
   doctorTwinCollapseCommand
 } from "./chunk-5IFMSDWF.js";
+import {
+  doctorTypeMatrixCommand
+} from "./chunk-RYGY5LG4.js";
 import {
   doctorWorktreeStoresCommand
 } from "./chunk-T2TE45UH.js";
@@ -129,7 +132,7 @@ import {
 import {
   dispatchFromCli,
   dispatchRaw
-} from "./chunk-OIS3BDSL.js";
+} from "./chunk-N3CEB7IU.js";
 import "./chunk-6N6WGLXE.js";
 import "./chunk-4VASFLUW.js";
 import {
@@ -143,7 +146,7 @@ import {
 } from "./chunk-ESI6Q4OS.js";
 import "./chunk-6JSJNYH2.js";
 import "./chunk-D7BAQNV2.js";
-import "./chunk-JRDAITPC.js";
+import "./chunk-HFB4FPLA.js";
 
 // packages/cleo/src/cli/commands/doctor.ts
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -552,6 +555,8 @@ var doctorCommand = defineCommand({
     "ac-bindings": doctorAcBindingsCommand,
     // T12886 — stored task dependency cycles + repair plan (read-only)
     "dep-cycles": doctorDepCyclesCommand,
+    // T14096 — parent/child type-matrix violations: plan, --apply with a receipt, --rollback
+    "type-matrix": doctorTypeMatrixCommand,
     // T12158 — tables nexus resolves by bare name must actually live where it assumes
     "nexus-residency": doctorNexusResidencyCommand,
     // T12113 (gh#1222) — evidence-tool semaphore holders + orphan reaping
@@ -1280,4 +1285,4 @@ Dependency cycles: check skipped (${msg})`);
 export {
   doctorCommand
 };
-//# sourceMappingURL=doctor-4DWCNDOP.js.map
+//# sourceMappingURL=doctor-4GX4L5UU.js.map

package/dist/cli/{doctor-tool-locks-VXKJZKAY.js → doctor-tool-locks-3ZT2LXRY.js}

@@ -15,7 +15,7 @@
 })();
 import {
   doctorToolLocksCommand
-} from "./chunk-TUUKU4H7.js";
+} from "./chunk-5AL6B3J2.js";
 import "./chunk-VIZSF3NL.js";
 import "./chunk-IVN46UST.js";
 import "./chunk-ESI6Q4OS.js";
@@ -23,4 +23,4 @@ import "./chunk-6JSJNYH2.js";
 export {
   doctorToolLocksCommand
 };
-//# sourceMappingURL=doctor-tool-locks-VXKJZKAY.js.map
+//# sourceMappingURL=doctor-tool-locks-3ZT2LXRY.js.map

package/dist/cli/{canon-docs-2GTOLF7Y.js → doctor-type-matrix-DD233VK2.js}

@@ -14,13 +14,13 @@
   };
 })();
 import {
-  CanonDocsDiffError,
-  loadCanonRegistry,
-  runCanonDocsCheck
-} from "./chunk-SXXOC6KZ.js";
+  doctorTypeMatrixCommand
+} from "./chunk-RYGY5LG4.js";
+import "./chunk-VIZSF3NL.js";
+import "./chunk-IVN46UST.js";
+import "./chunk-ESI6Q4OS.js";
+import "./chunk-6JSJNYH2.js";
 export {
-  CanonDocsDiffError,
-  loadCanonRegistry,
-  runCanonDocsCheck
+  doctorTypeMatrixCommand
 };
-//# sourceMappingURL=canon-docs-2GTOLF7Y.js.map
+//# sourceMappingURL=doctor-type-matrix-DD233VK2.js.map