@cleocode/core 2026.10.27 → 2026.11.1-canary.3

package/dist/docs/doctor.js

@@ -2,7 +2,8 @@
  * `cleo docs doctor` — store health diagnostics + safe repairs — T13447.
  *
  * Audits the CleoDocs store (`cleo.db` `attachments`/`docs_wikilinks` tables
- * plus the on-disk legacy surfaces) for eight known drift classes and, when
+ * plus the on-disk legacy surfaces and the `docs_publications` ledger) for nine
+ * known drift classes and, when
  * invoked with `apply: true`, performs the repairs that are safe to run
  * in-place:
  *
@@ -63,6 +64,25 @@
  *                             doc whose remaining positions are
  *                             unrecoverable stays listed at `info` level —
  *                             visibility only, no invented repair (T13843).
+ *   - `publication-ledger-drift` — `docs_publications` rows whose mirror is not
+ *                             in sync (T14117): the file is gone (`deleted`;
+ *                             outside the project root this is a dead
+ *                             worktree) or differs from the store head
+ *                             (`modified`). Repair (`prune-publication`) deletes
+ *                             a `deleted` row only when the mirror is provably
+ *                             gone and its blob is still held by an attachments
+ *                             row or by a live ledger row. The ledger syncs
+ *                             across devices, so an absolute path or one outside
+ *                             both this root and this device's worktrees root is
+ *                             `report-only`, and a relative path still tracked by
+ *                             HEAD or the default branch (another branch checked
+ *                             out) is kept. A path in a removed worktree of this
+ *                             device is gone. Each pruned row is appended in
+ *                             full to {@link DOCS_DOCTOR_LEDGER_PRUNE_AUDIT_FILE}
+ *                             first, so it can be re-inserted. `modified` rows
+ *                             and unprotected `deleted` rows get a plan-only
+ *                             entry (republish, or ingest the edit) — the
+ *                             doctor never picks which side of a drift wins.
  *
  * SAFETY: `apply: true` (or `repair: true`) REFUSES to run without a backup receipt
  * ({@link DocsDoctorOptions.backupReceiptPath}) whose mtime is at most
@@ -79,12 +99,13 @@
  * @see wikilinks.ts — derived edge table + rebuild (T11826)
  */
 import { createHash } from 'node:crypto';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { isAbsolute, join, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { getCleoWorktreesRoot } from '@cleocode/paths';
 import { eq } from 'drizzle-orm';
+import { gitDefaultBranchRefs, gitRefHasPath, gitToplevel } from '../git/work-tree.js';
 import { resolveCleoDir } from '../paths.js';
 import { createAttachmentStore } from '../store/attachment-store.js';
 import { backfillBlobStoreBytes, blobContentExists, resolveLegacyByteSource, } from '../store/blob-keep.js';
@@ -94,6 +115,8 @@ import { docsAttachments } from '../store/tasks-schema.js';
 import { applyConduitHistoryBackfill, planConduitHistoryBackfill, } from './conduit-history-backfill.js';
 import { deriveDocLinks, isScannableTextMime, linksJsonOrNull, } from './derive-links.js';
 import { DOCS_VERSIONING_AUDIT_FILE } from './docs-update.js';
+import { assertCheckoutOfProject } from './modernize/guard.js';
+import { deleteDocsPublication, readDocsPublications } from './publications-store.js';
 import { deriveWikilinkEdges, rebuildDocsWikilinks } from './wikilinks.js';
 /**
  * Maximum age of the backup receipt accepted before an `apply` run.
@@ -117,6 +140,33 @@ export const DOCS_DOCTOR_DEFAULT_OLDER_THAN_DAYS = 30;
  * @task T13447
  */
 export const DOCS_DOCTOR_MAX_DETAIL_ITEMS = 50;
+/**
+ * Project-relative audit log the ledger prune appends each deleted
+ * `docs_publications` row to (one JSON line per row, written before the
+ * delete), so a pruned row can be restored with `upsertDocsPublication`.
+ *
+ * @task T14117
+ */
+export const DOCS_DOCTOR_LEDGER_PRUNE_AUDIT_FILE = '.cleo/audit/docs-publications-prune.jsonl';
+/**
+ * The diagnostic classes that carry a repair, accepted by
+ * {@link DocsDoctorOptions.only} to scope a run to some of them (T14174).
+ *
+ * @task T14174
+ */
+export const DOCS_DOCTOR_REPAIR_CLASSES = [
+    'dangling-pointers',
+    'doc-version-skew',
+    'empty-provenance',
+    'wikilinks-drift',
+    'legacy-blob-coverage',
+    'conduit-history-gaps',
+    'publication-ledger-drift',
+];
+/** Whether a diagnostic kind carries a repair (T14174). @internal */
+function isRepairClass(kind) {
+    return DOCS_DOCTOR_REPAIR_CLASSES.includes(kind);
+}
 /**
  * Parse a row's `attachment_json` defensively. Malformed JSON yields null —
  * such rows are skipped by kind-scoped checks rather than failing the run.
@@ -326,6 +376,157 @@ async function fetchRowContent(row, payload, projectRoot) {
         return null;
     }
 }
+/**
+ * Decide whether a missing mirror is provably gone, not merely absent from
+ * this device or this checkout (T14117 review). `docs_publications` syncs
+ * across devices, so a prune here deletes the row everywhere:
+ *
+ * - an absolute path, or one outside both this project root and this
+ *   device's CLEO worktrees root, belongs to another device or checkout and
+ *   is never proven gone;
+ * - a path inside this device's worktrees root whose worktree directory no
+ *   longer exists is gone;
+ * - otherwise the path must be absent from `HEAD` and from the default
+ *   branch (local and `origin/`) of the checkout that holds it, so a file
+ *   missing only because another branch is checked out is kept. When git
+ *   cannot answer, the row is not proven gone.
+ *
+ * @internal
+ */
+function provePublicationGone(projectRoot, publishedPath, absPath) {
+    if (isAbsolute(publishedPath)) {
+        return {
+            gone: false,
+            reason: 'its path is absolute (published from another device or checkout)',
+        };
+    }
+    const relToRoot = relative(projectRoot, absPath);
+    const insideRoot = !relToRoot.startsWith('..') && !isAbsolute(relToRoot);
+    // `base` is the existing directory the path sits under; git paths are taken
+    // relative to it through its realpath, since gitToplevel() canonicalises
+    // (macOS /var → /private/var would otherwise yield a bogus `../..` path).
+    let base = projectRoot;
+    if (!insideRoot) {
+        const worktreesRoot = getCleoWorktreesRoot();
+        const relToWorktrees = relative(worktreesRoot, absPath);
+        if (relToWorktrees.startsWith('..') || isAbsolute(relToWorktrees)) {
+            return {
+                gone: false,
+                reason: "it is outside this project root and this device's worktrees root (another device's path)",
+            };
+        }
+        const [projectHash, worktreeName] = relToWorktrees.split(sep);
+        if (projectHash === undefined || worktreeName === undefined) {
+            return { gone: false, reason: 'it does not name a worktree' };
+        }
+        const worktreeDir = join(worktreesRoot, projectHash, worktreeName);
+        if (!existsSync(worktreeDir)) {
+            return { gone: true, reason: `its worktree ${worktreeDir} no longer exists` };
+        }
+        base = worktreeDir;
+    }
+    const toplevel = gitToplevel(base);
+    if (toplevel === null)
+        return { gone: false, reason: 'git cannot read the checkout that holds it' };
+    const relPath = join(relative(toplevel, realpathSync(base)), relative(base, absPath))
+        .split(sep)
+        .join('/');
+    const defaults = gitDefaultBranchRefs(toplevel);
+    for (const ref of ['HEAD', ...defaults]) {
+        const has = gitRefHasPath(toplevel, ref, relPath);
+        if (has === true)
+            return { gone: false, reason: `${ref} still tracks it` };
+        if (has === null && ref === 'HEAD')
+            return { gone: false, reason: 'git cannot read HEAD' };
+    }
+    return {
+        gone: true,
+        reason: `absent from ${['HEAD', ...defaults].join(', ')}`,
+    };
+}
+/**
+ * Classify every non-in-sync `docs_publications` row and plan its repair
+ * (T14117). Reuses {@link statusDocs} for the drift classification so the
+ * doctor and `cleo docs status` can never disagree.
+ *
+ * A `deleted` row is prunable only when its blob stays protected without it:
+ * some attachments row holds the sha, or another ledger row naming the same
+ * sha is not itself `deleted`.
+ *
+ * @internal
+ */
+async function scanPublicationLedger(projectRoot, rows, checkoutRoot) {
+    const ledger = await readDocsPublications(projectRoot);
+    if (ledger.length === 0)
+        return [];
+    const { statusDocs } = await import('./docs-ops.js');
+    const status = await statusDocs({ projectRoot, checkoutRoot });
+    const key = (r) => `${r.ownerId}\u0000${r.blobName}\u0000${r.publishedPath}`;
+    const recordByKey = new Map(ledger.map((r) => [key(r), r]));
+    const attachmentShas = new Set(rows.map((r) => r.sha256));
+    const liveLedgerShas = new Map();
+    for (const item of status.items) {
+        if (item.drift === 'deleted')
+            continue;
+        const record = recordByKey.get(key(item));
+        if (record)
+            liveLedgerShas.set(record.lastBlobSha, (liveLedgerShas.get(record.lastBlobSha) ?? 0) + 1);
+    }
+    const findings = [];
+    for (const item of status.items) {
+        if (item.drift !== 'deleted' && item.drift !== 'modified')
+            continue;
+        const record = recordByKey.get(key(item));
+        if (!record)
+            continue;
+        const absPath = isAbsolute(record.publishedPath)
+            ? record.publishedPath
+            : resolve(checkoutRoot, record.publishedPath);
+        const rel = relative(checkoutRoot, absPath);
+        const outsideRoot = rel.startsWith('..') || isAbsolute(rel);
+        if (item.drift === 'modified') {
+            const storeMoved = item.fileSha === record.lastBlobSha;
+            findings.push({
+                record,
+                drift: 'modified',
+                outsideRoot,
+                action: storeMoved ? 'republish' : 'reconcile-edit',
+                prunable: false,
+                detail: storeMoved
+                    ? `mirror ${record.publishedPath} holds the last published blob; the store head moved on — run \`cleo docs publish\``
+                    : `mirror ${record.publishedPath} was edited outside the store — ingest it with \`cleo docs update\` or republish to overwrite`,
+            });
+            continue;
+        }
+        const shas = new Set([record.lastBlobSha, item.blobSha]);
+        const protectedElsewhere = [...shas].every((sha) => attachmentShas.has(sha) || (liveLedgerShas.get(sha) ?? 0) > 0);
+        const proof = provePublicationGone(checkoutRoot, record.publishedPath, absPath);
+        const blob = record.lastBlobSha.slice(0, 12);
+        let action;
+        let detail;
+        if (proof.gone === false) {
+            action = 'report-only';
+            detail = `mirror ${record.publishedPath} is missing here but ${proof.reason} — not pruned (the ledger syncs across devices)`;
+        }
+        else if (!protectedElsewhere) {
+            action = 'republish-or-prune';
+            detail = `mirror ${record.publishedPath} is gone (${proof.reason}) and this row is the only reference to blob ${blob}… — republish it, or archive the doc before pruning`;
+        }
+        else {
+            action = 'prune-publication';
+            detail = `mirror ${record.publishedPath} is gone (${proof.reason}); blob ${blob}… stays referenced elsewhere → delete the ledger row`;
+        }
+        findings.push({
+            record,
+            drift: 'deleted',
+            outsideRoot,
+            action,
+            prunable: action === 'prune-publication',
+            detail,
+        });
+    }
+    return findings;
+}
 /**
  * Scan the store and compute diagnostics + repair inputs in one pass.
  *
@@ -335,7 +536,7 @@ async function fetchRowContent(row, payload, projectRoot) {
  *
  * @internal
  */
-async function scanStore(projectRoot, db, olderThanDays) {
+async function scanStore(projectRoot, db, olderThanDays, checkoutRoot) {
     const rows = await db.select().from(docsAttachments).all();
     const payloadById = new Map();
     for (const row of rows)
@@ -540,6 +741,15 @@ async function scanStore(projectRoot, db, olderThanDays) {
     // planner reads the audit file, the registry and (hash-verified) bytes,
     // and writes nothing.
     const conduitBackfill = await planConduitHistoryBackfill(projectRoot);
+    const ledger = await scanPublicationLedger(projectRoot, rows, checkoutRoot);
+    const ledgerItems = ledger.slice(0, DOCS_DOCTOR_MAX_DETAIL_ITEMS).map((f) => ({
+        ownerId: f.record.ownerId,
+        blobName: f.record.blobName,
+        publishedPath: f.record.publishedPath,
+        drift: f.drift,
+        outsideRoot: f.outsideRoot,
+        proposed: f.action,
+    }));
     // Actionable = anything a doctor run should surface: rows to backfill,
     // unrecoverable gaps (real, unhealed drift — reported even when the doc
     // is otherwise complete), or a refused conflict (review-2253). Severity:
@@ -616,6 +826,13 @@ async function scanStore(projectRoot, db, olderThanDays) {
             items: conduitItems,
             truncated: conduitActionable.length > conduitItems.length,
         },
+        {
+            kind: 'publication-ledger-drift',
+            severity: ledger.length > 0 ? 'warn' : 'info',
+            count: ledger.length,
+            items: ledgerItems,
+            truncated: ledger.length > ledgerItems.length,
+        },
     ];
     return {
         diagnostics,
@@ -626,6 +843,7 @@ async function scanStore(projectRoot, db, olderThanDays) {
         missingEdges,
         needsWikilinksRebuild: missingEdges.length > 0 || backfillChangesLinks,
         conduitBackfill,
+        ledger,
     };
 }
 /**
@@ -668,18 +886,63 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
             },
         };
     }
+    // T14174 — scope to some repair classes.
+    let only = null;
+    if (opts.only !== undefined) {
+        const valid = new Set(DOCS_DOCTOR_REPAIR_CLASSES);
+        const unknown = opts.only.filter((c) => !valid.has(c));
+        if (unknown.length > 0 || opts.only.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    // @sync-invariant none:input-shape an argument refusal before any repair write; nothing was written
+                    code: 'E_DOCS_DOCTOR_UNKNOWN_CLASS',
+                    message: `docs doctor: --only ${unknown.length > 0 ? `names unknown class(es) ${unknown.join(', ')}` : 'names no class'}; ` +
+                        `valid classes: ${DOCS_DOCTOR_REPAIR_CLASSES.join(', ')}`,
+                },
+            };
+        }
+        if (repair) {
+            return {
+                ok: false,
+                error: {
+                    // @sync-invariant none:input-shape a flag-combination refusal before any repair write; nothing was written
+                    code: 'E_DOCS_DOCTOR_FLAG_CONFLICT',
+                    message: 'docs doctor: --only and --repair cannot be combined — --repair is already scoped to ' +
+                        'the legacy-blob backfill; use `--apply --only legacy-blob-coverage` instead.',
+                },
+            };
+        }
+        only = [...new Set(opts.only)].filter((c) => valid.has(c));
+    }
+    const inScope = (kind) => only === null || only.includes(kind);
+    const rebuildWikilinks = inScope('wikilinks-drift') || inScope('empty-provenance');
     if (mutate) {
         const refusal = checkBackupReceipt(opts.backupReceiptPath);
         if (refusal)
             return { ok: false, error: refusal };
     }
     const db = await getDb(projectRoot);
-    const pre = await scanStore(projectRoot, db, olderThanDays);
+    const checkoutRoot = opts.checkoutRoot ?? projectRoot;
+    try {
+        assertCheckoutOfProject(projectRoot, checkoutRoot);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                // @sync-invariant none:input-shape a checkout of another repository is refused before any read or repair write
+                code: 'E_DOCS_DOCTOR_FOREIGN_CHECKOUT',
+                message: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+    const pre = await scanStore(projectRoot, db, olderThanDays, checkoutRoot);
     const repairs = [];
     // T13653: in repair mode ONLY the blob backfill runs — apply mode plans it
     // alongside the other repairs.
     if (!repair) {
-        for (const { row, path } of pre.dangling.archivable) {
+        for (const { row, path } of inScope('dangling-pointers') ? pre.dangling.archivable : []) {
             repairs.push({
                 kind: 'dangling-pointers',
                 action: 'archive-dangling',
@@ -689,7 +952,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                 detail: `marked-dangling: local-file target missing (${path}) → lifecycle_status = 'archived'`,
             });
         }
-        for (const { row, path } of pre.dangling.clearable) {
+        for (const { row, path } of inScope('dangling-pointers') ? pre.dangling.clearable : []) {
             repairs.push({
                 kind: 'dangling-pointers',
                 action: 'clear-stale-path',
@@ -700,7 +963,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                     `(sha256 ${row.sha256.slice(0, 12)}…)`,
             });
         }
-        for (const { row, expected } of pre.skewed) {
+        for (const { row, expected } of inScope('doc-version-skew') ? pre.skewed : []) {
             repairs.push({
                 kind: 'doc-version-skew',
                 action: 'set-doc-version',
@@ -710,7 +973,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                 detail: `audit-note: docVersion ${row.docVersion} → ${expected} (audit log revisions + 1)`,
             });
         }
-        for (const { row, derived } of pre.backfillable) {
+        for (const { row, derived } of inScope('empty-provenance') ? pre.backfillable : []) {
             const derivedCount = derived.topics.length + derived.relatedTasks.length;
             repairs.push({
                 kind: 'empty-provenance',
@@ -723,7 +986,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                     : 'no derivable topics or task mentions — columns stay NULL',
             });
         }
-        if (pre.needsWikilinksRebuild) {
+        if (pre.needsWikilinksRebuild && rebuildWikilinks) {
             repairs.push({
                 kind: 'wikilinks-drift',
                 action: 'rebuild-wikilinks',
@@ -737,7 +1000,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
         // dry-run/apply mode; executed only under --apply (the --repair mode
         // stays the T13653 blob-backfill-only fast path). A complete doc with
         // unrecoverable gaps still gets an entry so the gap stays explained.
-        for (const plan of pre.conduitBackfill) {
+        for (const plan of inScope('conduit-history-gaps') ? pre.conduitBackfill : []) {
             if (plan.complete && plan.gaps.length === 0)
                 continue;
             if (plan.conflict) {
@@ -775,8 +1038,19 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                         `(chain ${plan.expectedVersions}, present ${plan.presentVersions}${gapNote}${auditNote})`,
             });
         }
+        // T14117 — publication-ledger drift: prune protected deleted rows; every
+        // other finding is a plan-only proposal.
+        for (const finding of inScope('publication-ledger-drift') ? pre.ledger : []) {
+            repairs.push({
+                kind: 'publication-ledger-drift',
+                action: finding.action,
+                applied: apply && finding.prunable,
+                detail: finding.detail,
+            });
+        }
     }
-    for (const candidate of pre.blobBackfillable) {
+    const blobBackfillable = inScope('legacy-blob-coverage') ? pre.blobBackfillable : [];
+    for (const candidate of blobBackfillable) {
         repairs.push({
             kind: 'legacy-blob-coverage',
             action: 'backfill-blob-bytes',
@@ -798,7 +1072,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
             .map((r, i) => ({ r, i }))
             .filter(({ r }) => r.kind === 'legacy-blob-coverage' && r.action === 'backfill-blob-bytes')
             .map(({ i }) => i);
-        for (const [n, candidate] of pre.blobBackfillable.entries()) {
+        for (const [n, candidate] of blobBackfillable.entries()) {
             if (candidate.sourcePath === null)
                 continue;
             const outcome = await backfillBlobStoreBytes(cleoDir, candidate.sha256, candidate.sourcePath);
@@ -822,7 +1096,7 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
             // backfill above so the bytes the new rows address are mirrored first;
             // annotate each repair entry with its executed outcome (zip by slug).
             const conduitBySlug = new Map();
-            for (const plan of pre.conduitBackfill) {
+            for (const plan of inScope('conduit-history-gaps') ? pre.conduitBackfill : []) {
                 if (plan.toBackfill.length === 0 || plan.conflict)
                     continue;
                 const result = await applyConduitHistoryBackfill(projectRoot, plan);
@@ -839,14 +1113,14 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                     detail: `${repair.detail} → executed: ${outcome.inserted} row(s) inserted, ${outcome.gaps} gap(s)`,
                 };
             }
-            for (const { row, expected } of pre.skewed) {
+            for (const { row, expected } of inScope('doc-version-skew') ? pre.skewed : []) {
                 await db
                     .update(docsAttachments)
                     .set({ docVersion: expected })
                     .where(eq(docsAttachments.id, row.id))
                     .run();
             }
-            for (const { row, derived } of pre.backfillable) {
+            for (const { row, derived } of inScope('empty-provenance') ? pre.backfillable : []) {
                 if (derived.topics.length + derived.relatedTasks.length === 0)
                     continue;
                 await db
@@ -858,14 +1132,14 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                     .where(eq(docsAttachments.id, row.id))
                     .run();
             }
-            for (const { row } of pre.dangling.archivable) {
+            for (const { row } of inScope('dangling-pointers') ? pre.dangling.archivable : []) {
                 await db
                     .update(docsAttachments)
                     .set({ lifecycleStatus: 'archived' })
                     .where(eq(docsAttachments.id, row.id))
                     .run();
             }
-            for (const { row, payload } of pre.dangling.clearable) {
+            for (const { row, payload } of inScope('dangling-pointers') ? pre.dangling.clearable : []) {
                 const cleaned = { ...payload };
                 delete cleaned['path'];
                 await db
@@ -874,32 +1148,57 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
                     .where(eq(docsAttachments.id, row.id))
                     .run();
             }
-            if (pre.needsWikilinksRebuild) {
+            if (pre.needsWikilinksRebuild && rebuildWikilinks) {
                 await rebuildDocsWikilinks({ projectRoot });
             }
+            const prunable = inScope('publication-ledger-drift')
+                ? pre.ledger.filter((f) => f.prunable)
+                : [];
+            if (prunable.length > 0) {
+                const auditPath = join(projectRoot, DOCS_DOCTOR_LEDGER_PRUNE_AUDIT_FILE);
+                mkdirSync(dirname(auditPath), { recursive: true });
+                const prunedAt = new Date().toISOString();
+                for (const finding of prunable) {
+                    // Audit first: the full row is recoverable even if the delete is interrupted.
+                    appendFileSync(auditPath, `${JSON.stringify({ op: 'docs.doctor.prune-publication', prunedAt, drift: finding.drift, outsideRoot: finding.outsideRoot, backupReceiptPath: opts.backupReceiptPath ?? null, record: finding.record })}\n`, 'utf-8');
+                    await deleteDocsPublication(projectRoot, finding.record);
+                }
+            }
         }
     }
     // T13560: on a mutating run, re-scan so the envelope's diagnostics (and the
     // summary computed from them) describe POST-repair state, consistent with
     // a follow-up dry run. Dry runs keep the pre-repair scan.
-    const post = mutate ? await scanStore(projectRoot, db, olderThanDays) : pre;
+    const post = mutate ? await scanStore(projectRoot, db, olderThanDays, checkoutRoot) : pre;
     const findings = post.diagnostics.reduce((sum, d) => sum + d.count, 0);
     // T13727 — surface the conduit backfill counts in the one-line summary so
     // operators see backfilled/skipped/gap per run without reading the report.
     const conduitActionable = pre.conduitBackfill.filter((p) => !p.complete || p.gaps.length > 0 || p.conflict);
     const conduitGapTotal = conduitActionable.reduce((s, p) => s + p.gaps.length, 0);
     const conduitConflictTotal = conduitActionable.filter((p) => p.conflict).length;
-    const conduitBackfillNote = repair || conduitActionable.length === 0
+    const conduitBackfillNote = repair || !inScope('conduit-history-gaps') || conduitActionable.length === 0
         ? ''
         : apply
             ? `; conduit history: ${conduitActionable.reduce((s, p) => s + p.toBackfill.length, 0)} version(s) backfilled across ${conduitActionable.length} doc(s) (${conduitGapTotal} gap(s) unrecoverable, ${conduitConflictTotal} conflict(s))`
             : `; conduit history: ${conduitActionable.length} doc(s) need attention (${conduitActionable.reduce((s, p) => s + p.toBackfill.length, 0)} version(s) to backfill, ${conduitGapTotal} gap(s) unrecoverable, ${conduitConflictTotal} conflict(s))`;
+    const repairCounts = {};
+    for (const r of repairs) {
+        const kind = r.kind;
+        if (!isRepairClass(kind))
+            continue;
+        const entry = repairCounts[kind] ?? { planned: 0, applied: 0 };
+        entry.planned += 1;
+        if (r.applied)
+            entry.applied += 1;
+        repairCounts[kind] = entry;
+    }
+    const scopeNote = only === null ? '' : ` (only: ${only.join(', ')})`;
     const summary = repair
         ? `docs doctor repaired ${repairs.filter((r) => r.applied).length} blob backfill(s); ` +
             `${post.diagnostics.find((d) => d.kind === 'legacy-blob-coverage')?.count ?? 0} sha(s) still missing post-repair`
         : apply
-            ? `docs doctor applied ${repairs.filter((r) => r.applied).length} repair(s); ${findings} finding(s) remain post-repair${conduitBackfillNote}`
-            : `docs doctor found ${findings} finding(s); ${repairs.length} repair(s) planned (dry-run — pass --apply to execute)${conduitBackfillNote}`;
+            ? `docs doctor applied ${repairs.filter((r) => r.applied).length} repair(s)${scopeNote}; ${findings} finding(s) remain post-repair${conduitBackfillNote}`
+            : `docs doctor found ${findings} finding(s); ${repairs.length} repair(s) planned${scopeNote} (dry-run — pass --apply to execute)${conduitBackfillNote}`;
     return {
         ok: true,
         report: {
@@ -908,6 +1207,8 @@ export async function runDocsDoctor(projectRoot, opts = {}) {
             backupReceiptPath: mutate ? (opts.backupReceiptPath ?? null) : null,
             diagnostics: post.diagnostics,
             repairs,
+            repairCounts,
+            only,
             summary,
         },
     };