@fenglimg/fabric-cli 2.0.0 → 2.0.1

package/dist/doctor-EJDSEJSS.js

@@ -0,0 +1,810 @@
+#!/usr/bin/env node
+import {
+  paint,
+  symbol
+} from "./chunk-WWNXR34K.js";
+import {
+  resolveDevMode
+} from "./chunk-COI5VDFU.js";
+import {
+  getDoctorTranslator,
+  t
+} from "./chunk-PWLW3B57.js";
+
+// src/commands/doctor.ts
+import { confirm, isCancel } from "@clack/prompts";
+import { defineCommand } from "citty";
+import {
+  appendEventLedgerEvent,
+  enrichDescriptions,
+  runDoctorApplyLint as runDoctorFixKnowledge,
+  runDoctorArchiveHistory,
+  runDoctorCiteCoverage,
+  runDoctorFix,
+  runDoctorHistoryAll,
+  runDoctorReport
+} from "@fenglimg/fabric-server";
+var FIX_KNOWLEDGE_CODE_LABELS = {
+  knowledge_orphan_demote_required: "demote (maturity)",
+  knowledge_stale_archive_required: "archive (git mv)",
+  knowledge_pending_auto_archive: "archive (git mv, pending)",
+  knowledge_index_drift: "counter bump (agents.meta)",
+  knowledge_session_hints_stale: "cache delete"
+};
+var PLAN_PREVIEW_LIMIT = 12;
+var doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: t("cli.doctor.description")
+  },
+  args: {
+    target: {
+      type: "string",
+      description: t("cli.doctor.args.target.description")
+    },
+    fix: {
+      type: "boolean",
+      description: t("cli.doctor.args.fix.description"),
+      default: false
+    },
+    "fix-knowledge": {
+      type: "boolean",
+      description: t("cli.doctor.args.fix-knowledge.description"),
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: t("cli.doctor.args.json.description"),
+      default: false
+    },
+    strict: {
+      type: "boolean",
+      description: t("cli.doctor.args.strict.description"),
+      default: false
+    },
+    // rc.7 T11: skip the safety confirm before mutations. Required for any
+    // non-tty invocation that wants to run --fix-knowledge without setting
+    // FABRIC_NONINTERACTIVE=1 in the environment.
+    yes: {
+      type: "boolean",
+      description: t("cli.doctor.args.yes.description"),
+      default: false
+    },
+    // rc.35 TASK-12 (P0-11): expose maintainer-audience actionHints. By
+    // default the renderer folds remediation strings that target Fabric
+    // contributors (edit `packages/cli/templates/...`, interpret G1-G5
+    // cite-goodhart codes, etc.) since npm end users have no actionable
+    // lever for them. --verbose shows them.
+    verbose: {
+      type: "boolean",
+      description: t("cli.doctor.args.verbose.description"),
+      default: false
+    },
+    // rc.20 TASK-05: cite policy adherence report (read-only). Skips standard
+    // inspections entirely — different output surface. Mutually exclusive
+    // with --fix / --fix-knowledge (enforced in run()).
+    "cite-coverage": {
+      type: "boolean",
+      description: t("cli.doctor.args.cite-coverage.description"),
+      default: false
+    },
+    since: {
+      type: "string",
+      description: t("cli.doctor.args.since.description"),
+      default: "7d"
+    },
+    client: {
+      type: "string",
+      description: t("cli.doctor.args.client.description"),
+      default: "all",
+      valueHint: "cc|codex|cursor|all"
+    },
+    // v2.0.0-rc.24 TASK-10: --layer filter for the cite contract audit. Pairs
+    // with --cite-coverage. Validated against {'team','personal','all'} at
+    // command entry; rejects 'both' (rc.20 plan-context vocabulary) explicitly.
+    layer: {
+      type: "string",
+      description: t("cli.doctor.args.layer.description"),
+      default: "all",
+      valueHint: "team|personal|all"
+    },
+    // rc.23 TASK-007 (a-C2): description-grade back-fill flag set. Read-side
+    // by default; `--auto` flips the writer arm on. Mutually exclusive with
+    // --fix / --fix-knowledge / --cite-coverage (different mutation surfaces).
+    "enrich-descriptions": {
+      type: "boolean",
+      description: t("cli.doctor.args.enrich-descriptions.description"),
+      default: false
+    },
+    auto: {
+      type: "boolean",
+      description: t("cli.doctor.args.auto.description"),
+      default: false
+    },
+    "dry-run": {
+      type: "boolean",
+      description: t("cli.doctor.args.dry-run.description"),
+      default: false
+    },
+    // v2.0.0-rc.25 TASK-10: --archive-history flag (parallel to rc.20
+    // --cite-coverage). Read-only; reads session_archive_attempted events
+    // and renders a per-session table. Pairs with the shared `--since` flag.
+    "archive-history": {
+      type: "boolean",
+      description: t("cli.doctor.args.archive-history.description"),
+      default: false
+    },
+    // rc.37 NEW-33: unified history view across archive / fix / all surfaces.
+    // Mode = `archive | fix | all` (the `archive` mode delegates to the
+    // existing runDoctorArchiveHistory; `fix` aggregates doctor_run events;
+    // `all` rolls up both into a per-day count table). Read-only; mutex
+    // with the mutation arms.
+    history: {
+      type: "string",
+      description: t("cli.doctor.args.history.description"),
+      valueHint: "archive|fix|all"
+    }
+  },
+  async run({ args }) {
+    const workspaceRoot = process.cwd();
+    const resolution = resolveDevMode(args.target, workspaceRoot);
+    const dt = getDoctorTranslator(resolution.target);
+    const fixKnowledge = args["fix-knowledge"] === true;
+    const fix = args.fix === true;
+    const citeCoverage = args["cite-coverage"] === true;
+    const enrichDesc = args["enrich-descriptions"] === true;
+    const archiveHistory = args["archive-history"] === true;
+    if (args.since !== void 0) {
+      try {
+        parseSinceDuration(args.since);
+      } catch {
+        writeStderr(dt("cli.doctor.errors.invalid-since", { input: args.since }));
+        process.exitCode = 1;
+        return;
+      }
+    }
+    const historyMode = args.history;
+    if (typeof historyMode === "string" && historyMode.length > 0) {
+      if (fix || fixKnowledge || citeCoverage || enrichDesc || archiveHistory) {
+        writeStderr(dt("cli.doctor.errors.history-mutex"));
+        process.exitCode = 1;
+        return;
+      }
+      if (historyMode !== "archive" && historyMode !== "fix" && historyMode !== "all") {
+        writeStderr(dt("cli.doctor.errors.invalid-history-mode", { input: historyMode }));
+        process.exitCode = 1;
+        return;
+      }
+      const sinceInput = args.since ?? "7d";
+      let sinceMs;
+      try {
+        sinceMs = parseSinceDuration(sinceInput);
+      } catch {
+        writeStderr(dt("cli.doctor.errors.invalid-since", { input: sinceInput }));
+        process.exitCode = 1;
+        return;
+      }
+      if (historyMode === "archive") {
+        const report3 = await runDoctorArchiveHistory(resolution.target, { since: sinceMs });
+        if (args.json === true) {
+          writeStdout(JSON.stringify(report3, null, 2));
+        } else {
+          renderArchiveHistoryReport(report3, sinceInput, dt);
+        }
+        return;
+      }
+      const report2 = await runDoctorHistoryAll(resolution.target, { since: sinceMs });
+      if (args.json === true) {
+        writeStdout(JSON.stringify(report2, null, 2));
+      } else {
+        renderHistoryAllReport(report2, sinceInput, historyMode, dt);
+      }
+      return;
+    }
+    if (archiveHistory) {
+      if (fix || fixKnowledge || citeCoverage || enrichDesc) {
+        writeStderr(dt("cli.doctor.errors.archive-history-mutex"));
+        process.exitCode = 1;
+        return;
+      }
+      const sinceInput = args.since ?? "7d";
+      let sinceMs;
+      try {
+        sinceMs = parseSinceDuration(sinceInput);
+      } catch {
+        writeStderr(dt("cli.doctor.errors.invalid-since", { input: sinceInput }));
+        process.exitCode = 1;
+        return;
+      }
+      const report2 = await runDoctorArchiveHistory(resolution.target, {
+        since: sinceMs
+      });
+      if (args.json === true) {
+        writeStdout(JSON.stringify(report2, null, 2));
+      } else {
+        renderArchiveHistoryReport(report2, sinceInput, dt);
+      }
+      return;
+    }
+    if (enrichDesc) {
+      if (fix || fixKnowledge || citeCoverage) {
+        writeStderr(dt("cli.doctor.errors.enrich-descriptions-mutex"));
+        process.exitCode = 1;
+        return;
+      }
+      const autoFlag = args.auto === true;
+      const dryRun = args["dry-run"] === true;
+      const report2 = await enrichDescriptions(resolution.target, {
+        auto: autoFlag,
+        dryRun
+      });
+      if (args.json === true) {
+        writeStdout(JSON.stringify(report2, null, 2));
+      } else {
+        renderEnrichDescriptionsReport(report2, dt);
+      }
+      return;
+    }
+    if (citeCoverage) {
+      if (fix || fixKnowledge) {
+        writeStderr(dt("cli.doctor.errors.cite-coverage-mutex"));
+        process.exitCode = 1;
+        return;
+      }
+      let sinceMs;
+      try {
+        sinceMs = parseSinceDuration(args.since ?? "7d");
+      } catch {
+        writeStderr(dt("cli.doctor.errors.invalid-since", { input: args.since ?? "7d" }));
+        process.exitCode = 1;
+        return;
+      }
+      const clientFilter = args.client ?? "all";
+      if (!isValidClientFilter(clientFilter)) {
+        writeStderr(dt("cli.doctor.errors.invalid-client", { input: clientFilter }));
+        process.exitCode = 1;
+        return;
+      }
+      const layerFilter = args.layer ?? "all";
+      if (!isValidLayerFilter(layerFilter)) {
+        writeStderr(dt("cli.doctor.errors.invalid-layer", { input: layerFilter }));
+        process.exitCode = 1;
+        return;
+      }
+      const report2 = await runDoctorCiteCoverage(resolution.target, {
+        since: sinceMs,
+        client: clientFilter,
+        layer: layerFilter
+      });
+      renderCiteCoverageReport(report2, args.json === true, dt);
+      return;
+    }
+    if (fixKnowledge && fix) {
+      writeStderr(dt("cli.doctor.errors.fix-knowledge-fix-mutually-exclusive"));
+      process.exitCode = 1;
+      return;
+    }
+    let fixKnowledgeReport = null;
+    let fixReport = null;
+    let report;
+    if (fixKnowledge) {
+      const preReport = await runDoctorReport(resolution.target);
+      const plan = computeFixKnowledgePlan(preReport);
+      const yesFlag = args.yes === true;
+      const envBypass = process.env.FABRIC_NONINTERACTIVE === "1";
+      if (plan.totalCount === 0) {
+      } else {
+        renderFixKnowledgePlan(plan);
+        const decision = await resolveFixKnowledgeConsent({
+          yesFlag,
+          envBypass,
+          plan
+        });
+        if (decision === "abort") {
+          process.exitCode = 1;
+          return;
+        }
+      }
+      fixKnowledgeReport = await runDoctorFixKnowledge(resolution.target);
+      report = fixKnowledgeReport.report;
+    } else if (fix) {
+      if (args["dry-run"] === true) {
+        report = await runDoctorReport(resolution.target);
+      } else {
+        fixReport = await runDoctorFix(resolution.target);
+        report = fixReport.report;
+      }
+    } else {
+      report = await runDoctorReport(resolution.target);
+    }
+    if (args.json === true) {
+      writeStdout(JSON.stringify(fixKnowledgeReport ?? fixReport ?? report, null, 2));
+    } else {
+      if (fixKnowledgeReport !== null) {
+        writeStdout(fixKnowledgeReport.message);
+        if (fixKnowledgeReport.aborted && fixKnowledgeReport.abort_reason !== void 0) {
+          writeStderr(fixKnowledgeReport.abort_reason);
+        }
+        renderFixKnowledgeMutations(fixKnowledgeReport, dt);
+      } else if (fixReport !== null) {
+        writeStdout(fixReport.message);
+      } else if (fix && args["dry-run"] === true) {
+        writeStdout(dt("cli.doctor.fix-dry-run-banner"));
+      }
+      renderHumanReport(report, dt, args.verbose === true);
+    }
+    await emitDoctorRunEventBestEffort(resolution.target, {
+      mode: fixKnowledge ? "fix-knowledge" : "lint",
+      issues: report.fixable_errors.length + report.manual_errors.length + report.warnings.length,
+      mutations: fixKnowledgeReport !== null ? fixKnowledgeReport.mutations.filter((m) => m.applied).length : void 0
+    });
+    if (fixKnowledgeReport !== null) {
+      if (fixKnowledgeReport.aborted) {
+        process.exitCode = 1;
+        return;
+      }
+      if (fixKnowledgeReport.mutations.some((m) => !m.applied)) {
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (report.status === "error" || args.strict === true && (report.status === "warn" || report.warnings.length > 0)) {
+      process.exitCode = 1;
+    }
+  }
+});
+var doctor_default = doctorCommand;
+function renderHumanReport(report, dt, verbose) {
+  writeStdout(`${renderStatus(report.status)} ${paint.ai("fabric doctor")} ${paint.human(report.summary.target)}`);
+  renderTldrHeader(report);
+  for (const check of report.checks) {
+    writeStdout(`${renderStatus(check.status)} ${check.name}: ${check.message}`);
+  }
+  const opts = { verbose, dt };
+  writeIssueSection(dt("doctor.section.fixable"), report.fixable_errors, opts);
+  writeIssueSection(dt("doctor.section.manual"), report.manual_errors, opts);
+  writeIssueSection(dt("doctor.section.warnings"), report.warnings, opts);
+  renderPayloadLimits(report, dt);
+}
+function renderPayloadLimits(report, dt) {
+  const limits = report.summary.payload_limits;
+  if (limits === void 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(dt("doctor.section.payload-limits"));
+  writeStdout(
+    `- ${dt("doctor.payload-limits.line", {
+      warnKb: String(Math.round(limits.warn_bytes / 1024)),
+      hardKb: String(Math.round(limits.hard_bytes / 1024)),
+      source: limits.source
+    })}`
+  );
+}
+function renderFixKnowledgeMutations(fixKnowledgeReport, dt) {
+  if (fixKnowledgeReport.mutations.length === 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(dt("doctor.section.fix-knowledge-mutations"));
+  for (const mutation of fixKnowledgeReport.mutations) {
+    const marker = mutation.applied ? symbol.ok : symbol.error;
+    const errSuffix = mutation.applied || mutation.error === void 0 ? "" : ` (${mutation.error})`;
+    writeStdout(`${marker} ${mutation.kind}: ${mutation.path} [${mutation.detail}]${errSuffix}`);
+  }
+}
+function writeIssueSection(title, issues, options) {
+  if (issues.length === 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(title);
+  for (const issue of issues) {
+    writeStdout(`- ${issue.code}: ${issue.message}`);
+    if (issue.actionHint !== void 0 && issue.actionHint.length > 0) {
+      if (issue.audience === "maintainer" && !options.verbose) {
+        writeStdout(`  \u2192 ${options.dt("doctor.maintainer-hint-folded")}`);
+      } else {
+        writeStdout(`  \u2192 ${issue.actionHint}`);
+      }
+    }
+  }
+}
+function renderTldrHeader(report) {
+  const ranked = [];
+  for (const issue of report.fixable_errors) {
+    ranked.push({ severity: "fixable", code: issue.code, message: issue.message });
+  }
+  for (const issue of report.manual_errors) {
+    ranked.push({ severity: "manual", code: issue.code, message: issue.message });
+  }
+  for (const issue of report.warnings) {
+    ranked.push({ severity: "warn", code: issue.code, message: issue.message });
+  }
+  if (ranked.length === 0) {
+    writeStdout(`${symbol.ok} TL;DR: all 48 checks green \u2014 nothing to fix.`);
+    return;
+  }
+  const top3 = ranked.slice(0, 3);
+  writeStdout(
+    `TL;DR (top ${top3.length} of ${ranked.length}, severity order: fixable\u2192manual\u2192warn):`
+  );
+  for (const item of top3) {
+    const marker = item.severity === "fixable" ? symbol.error : item.severity === "manual" ? symbol.error : symbol.warn;
+    const truncated = item.message.length > 140 ? `${item.message.slice(0, 137)}...` : item.message;
+    writeStdout(`  ${marker} ${item.code}: ${truncated}`);
+  }
+}
+function renderStatus(status) {
+  if (status === "ok") {
+    return symbol.ok;
+  }
+  if (status === "warn") {
+    return symbol.warn;
+  }
+  return symbol.error;
+}
+function writeStdout(message) {
+  process.stdout.write(`${message}
+`);
+}
+async function emitDoctorRunEventBestEffort(projectRoot, payload) {
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "doctor_run",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      mode: payload.mode,
+      issues: payload.issues,
+      ...payload.mutations !== void 0 ? { mutations: payload.mutations } : {}
+    });
+  } catch {
+  }
+}
+function writeStderr(message) {
+  process.stderr.write(`${message}
+`);
+}
+function computeFixKnowledgePlan(report) {
+  const buckets = {};
+  const sources = [
+    ...report.fixable_errors,
+    ...report.warnings
+  ];
+  for (const issue of sources) {
+    if (FIX_KNOWLEDGE_CODE_LABELS[issue.code] === void 0) continue;
+    if (!Array.isArray(buckets[issue.code])) {
+      buckets[issue.code] = [];
+    }
+    buckets[issue.code].push(issue);
+  }
+  const codes = Object.keys(buckets).sort(
+    (a, b) => FIX_KNOWLEDGE_CODE_LABELS[a].localeCompare(FIX_KNOWLEDGE_CODE_LABELS[b])
+  );
+  const perCodeLines = [];
+  let totalCount = 0;
+  for (const code of codes) {
+    const items = buckets[code];
+    totalCount += items.length;
+    perCodeLines.push(`  - ${FIX_KNOWLEDGE_CODE_LABELS[code]}: ${items.length}`);
+  }
+  const previewLines = [];
+  const flattened = codes.flatMap((c) => buckets[c]);
+  for (const item of flattened.slice(0, PLAN_PREVIEW_LIMIT)) {
+    const where = item.path !== void 0 && item.path.length > 0 ? `${item.path}` : "(no path)";
+    previewLines.push(`    \u2022 ${where} \u2014 ${item.message}`);
+  }
+  if (flattened.length > PLAN_PREVIEW_LIMIT) {
+    previewLines.push(`    \u2022 ... and ${flattened.length - PLAN_PREVIEW_LIMIT} more`);
+  }
+  return { totalCount, perCodeLines, previewLines };
+}
+function renderFixKnowledgePlan(plan) {
+  writeStdout("");
+  writeStdout(`${paint.warn("fix-knowledge mutation plan")} (${plan.totalCount} total)`);
+  for (const line of plan.perCodeLines) {
+    writeStdout(line);
+  }
+  if (plan.previewLines.length > 0) {
+    writeStdout("");
+    writeStdout("  preview:");
+    for (const line of plan.previewLines) {
+      writeStdout(line);
+    }
+  }
+}
+async function resolveFixKnowledgeConsent(options) {
+  if (options.yesFlag || options.envBypass) {
+    return "proceed";
+  }
+  if (process.stdin.isTTY !== true) {
+    writeStderr(
+      "doctor --fix-knowledge: stdin is not a TTY and neither --yes nor FABRIC_NONINTERACTIVE=1 is set. Refusing to mutate."
+    );
+    return "abort";
+  }
+  const message = `About to apply ${options.plan.totalCount} mutation(s) to knowledge entries (frontmatter writes + git mv + cache deletes). Proceed?`;
+  const answer = await confirm({
+    message,
+    initialValue: false
+  });
+  if (isCancel(answer) || answer !== true) {
+    writeStderr("doctor --fix-knowledge: aborted by user.");
+    return "abort";
+  }
+  return "proceed";
+}
+var CITE_COVERAGE_CLIENT_FILTERS = /* @__PURE__ */ new Set([
+  "cc",
+  "codex",
+  "cursor",
+  "all"
+]);
+function isValidClientFilter(input) {
+  return CITE_COVERAGE_CLIENT_FILTERS.has(input);
+}
+var CITE_COVERAGE_LAYER_FILTERS = /* @__PURE__ */ new Set([
+  "team",
+  "personal",
+  "all"
+]);
+function isValidLayerFilter(input) {
+  return CITE_COVERAGE_LAYER_FILTERS.has(input);
+}
+function renderCiteCoverageReport(report, jsonMode, dt) {
+  if (jsonMode) {
+    writeStdout(JSON.stringify(report, null, 2));
+    return;
+  }
+  if (report.status === "skipped") {
+    writeStdout(dt("doctor.cite.status.skipped"));
+    return;
+  }
+  const lines = [];
+  lines.push(dt("doctor.section.cite-coverage"));
+  lines.push(
+    dt("doctor.cite.header", {
+      since: new Date(report.since_ts).toISOString(),
+      marker: new Date(report.marker_ts).toISOString()
+    })
+  );
+  if (report.marker_emitted_now) {
+    lines.push(dt("doctor.cite.warning.justActivated"));
+  }
+  lines.push("");
+  lines.push(`  ${dt("doctor.cite.metric.editsTouched")}: ${report.metrics.edits_touched}`);
+  lines.push(`  ${dt("doctor.cite.metric.qualifyingCites")}: ${report.metrics.qualifying_cites}`);
+  lines.push(`  ${dt("doctor.cite.metric.recalledUnverified")}: ${report.metrics.recalled_unverified}`);
+  lines.push(`  ${dt("doctor.cite.metric.expectedButMissed")}: ${report.metrics.expected_but_missed}`);
+  lines.push(`  ${dt("doctor.cite.metric.totalTurns")}: ${report.metrics.total_turns}`);
+  const complianceRate = report.metrics.cite_compliance_rate;
+  const complianceStr = complianceRate === null || complianceRate === void 0 ? dt("doctor.cite.metric.complianceNA") : `${(complianceRate * 100).toFixed(1)}% (${report.metrics.compliant_cites ?? 0}/${(report.metrics.compliant_cites ?? 0) + (report.metrics.noncompliant_cites ?? 0)})`;
+  lines.push(`  ${dt("doctor.cite.metric.complianceRate")}: ${complianceStr}`);
+  const uncorrelatable = report.metrics.uncorrelatable_edits ?? 0;
+  if (uncorrelatable > 0) {
+    lines.push(`  ${dt("doctor.cite.metric.uncorrelatableEdits")}: ${uncorrelatable}`);
+  }
+  if (report.per_client !== void 0 && Object.keys(report.per_client).length > 1) {
+    lines.push("");
+    lines.push(`### ${dt("doctor.cite.section.perClient")}`);
+    for (const [client, metrics] of Object.entries(report.per_client)) {
+      const summary = Object.entries(metrics).map(([k, v]) => `${k}=${v}`).join(" / ");
+      lines.push(`  ${client}: ${summary}`);
+    }
+  }
+  if (report.dismissed_reason_histogram !== void 0 && Object.keys(report.dismissed_reason_histogram).length > 0) {
+    lines.push("");
+    lines.push(`### ${dt("doctor.cite.section.dismissedReasons")}`);
+    for (const [reason, count] of Object.entries(report.dismissed_reason_histogram)) {
+      const label = dt(`doctor.cite.dismissed.${reason}`);
+      lines.push(`  ${label}: ${count}`);
+    }
+  }
+  if (report.none_reason_histogram !== void 0 && Object.keys(report.none_reason_histogram).length > 0) {
+    lines.push("");
+    lines.push(`### ${dt("doctor.cite.section.noneReasons")}`);
+    for (const [reason, count] of Object.entries(report.none_reason_histogram)) {
+      const label = dt(`doctor.cite.none.${reason}`);
+      lines.push(`  ${label}: ${count}`);
+    }
+  }
+  appendContractSection(lines, report, dt);
+  writeStdout(lines.join("\n"));
+}
+function appendContractSection(lines, report, dt) {
+  const status = report.contract_metrics_status;
+  if (status === void 0) {
+    return;
+  }
+  const metrics = report.contract_metrics;
+  const perLayerType = report.per_layer_type;
+  const allCountsZero = metrics === void 0 || metrics.decisions_cited === 0 && metrics.pitfalls_cited === 0 && metrics.contract_with === 0 && metrics.contract_missing === 0 && metrics.hard_violated === 0 && metrics.cite_id_unresolved === 0 && Object.keys(metrics.skip_count).length === 0;
+  if (status === "awaiting_marker" && allCountsZero) {
+    return;
+  }
+  lines.push("");
+  lines.push(`### ${dt("cite-coverage.contract.header")}`);
+  if (status === "skipped:bootstrap_drift") {
+    lines.push(`  ${dt("cite-coverage.contract.status.skipped_bootstrap_drift")}`);
+    return;
+  }
+  const statusKey = status === "ok" ? "cite-coverage.contract.status.ok" : "cite-coverage.contract.status.awaiting_marker";
+  lines.push(`  status: ${dt(statusKey)}`);
+  if (typeof report.contract_marker_ts === "number" && report.contract_marker_ts > 0) {
+    lines.push(`  since: ${new Date(report.contract_marker_ts).toISOString()}`);
+  }
+  if (report.layer_filter !== void 0) {
+    lines.push(`  layer filter: ${report.layer_filter}`);
+  }
+  if (metrics !== void 0) {
+    lines.push(`  ${dt("cite-coverage.contract.decisions_cited")}: ${metrics.decisions_cited}`);
+    lines.push(`  ${dt("cite-coverage.contract.pitfalls_cited")}: ${metrics.pitfalls_cited}`);
+    lines.push(`  ${dt("cite-coverage.contract.with")}: ${metrics.contract_with}`);
+    lines.push(`  ${dt("cite-coverage.contract.missing")}: ${metrics.contract_missing}`);
+    if (metrics.hard_violated > 0) {
+      const layerSuffix = report.layer_filter === "personal" ? dt("cite-coverage.layer.personal_fyi") : dt("cite-coverage.layer.team_review");
+      lines.push(
+        `  ${dt("cite-coverage.contract.hard_violated")} ${layerSuffix}: ${metrics.hard_violated}`
+      );
+    }
+  }
+  if (perLayerType !== void 0) {
+    const teamKeys = Object.keys(perLayerType.team).filter(
+      (k) => perLayerType.team[k] > 0
+    );
+    const personalKeys = Object.keys(perLayerType.personal).filter(
+      (k) => perLayerType.personal[k] > 0
+    );
+    if (teamKeys.length > 0 || personalKeys.length > 0) {
+      lines.push("");
+      lines.push(`#### ${dt("cite-coverage.layer.team")} \xD7 ${dt("cite-coverage.layer.personal")}`);
+      for (const key of teamKeys) {
+        const label = dt(`cite-coverage.contract.type.${key}`);
+        lines.push(`  ${dt("cite-coverage.layer.team")} \u2014 ${label}: ${perLayerType.team[key]}`);
+      }
+      for (const key of personalKeys) {
+        const label = dt(`cite-coverage.contract.type.${key}`);
+        lines.push(
+          `  ${dt("cite-coverage.layer.personal")} \u2014 ${label}: ${perLayerType.personal[key]}`
+        );
+      }
+    }
+  }
+  if (metrics !== void 0 && Object.keys(metrics.skip_count).length > 0) {
+    lines.push("");
+    lines.push(`#### ${dt("cite-coverage.contract.skip_count")}`);
+    for (const [reason, count] of Object.entries(metrics.skip_count)) {
+      const label = dt(`cite-coverage.skip.${reason}`);
+      lines.push(`  ${label}: ${count}`);
+    }
+  }
+  if (metrics !== void 0 && metrics.cite_id_unresolved > 0) {
+    lines.push("");
+    lines.push(
+      `${symbol.warn} ${dt("cite-coverage.contract.cite_id_unresolved")}: ${metrics.cite_id_unresolved}`
+    );
+  }
+}
+function renderEnrichDescriptionsReport(report, dt) {
+  const header = `${symbol.ok} ${paint.ai("fabric doctor --enrich-descriptions")} mode=${report.mode}${report.dryRun ? " (dry-run)" : ""} scanned=${report.scanned} modified=${report.modified} skipped=${report.skipped}`;
+  writeStdout(header);
+  if (report.candidates.length === 0) {
+    writeStdout(dt("doctor.enrich.allComplete"));
+    return;
+  }
+  writeStdout("");
+  for (const candidate of report.candidates) {
+    if (candidate.error !== void 0) {
+      writeStdout(`${symbol.error} ${candidate.path} \u2014 ${candidate.error}`);
+      continue;
+    }
+    const missing = candidate.missing.join(", ");
+    if (candidate.modified) {
+      const added = candidate.added_fields.join(", ");
+      writeStdout(
+        `${symbol.ok} ${candidate.path} \u2014 missing: ${missing} \u2192 added: ${added}`
+      );
+    } else {
+      writeStdout(`${symbol.warn} ${candidate.path} \u2014 missing: ${missing}`);
+    }
+  }
+}
+function parseSinceDuration(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`invalid --since value: ${input}`);
+  }
+  const durationMatch = /^(\d+)([dhm])$/.exec(trimmed);
+  if (durationMatch !== null) {
+    const value = Number.parseInt(durationMatch[1], 10);
+    const unit = durationMatch[2];
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(`invalid --since value: ${input}`);
+    }
+    const unitMs = unit === "d" ? 864e5 : unit === "h" ? 36e5 : 6e4;
+    return Date.now() - value * unitMs;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const value = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`invalid --since value: ${input}`);
+    }
+    return value;
+  }
+  throw new Error(`invalid --since value: ${input}`);
+}
+function renderArchiveHistoryReport(report, sinceLabel, dt) {
+  if (report.entries.length === 0) {
+    writeStdout(dt("doctor.archive-history.empty", { sinceLabel }));
+    return;
+  }
+  const lines = [];
+  lines.push(
+    dt("doctor.archive-history.header", {
+      sinceLabel,
+      count: String(report.total),
+      plural: report.total === 1 ? "" : "s"
+    })
+  );
+  lines.push("");
+  lines.push(
+    `| ${dt("doctor.archive-history.table.session")} | ${dt(
+      "doctor.archive-history.table.lastAttempt"
+    )} | ${dt("doctor.archive-history.table.outcome")} | ${dt(
+      "doctor.archive-history.table.candidates"
+    )} | ${dt("doctor.archive-history.table.coveredGap")} |`
+  );
+  lines.push("| ------- | ---------------- | -------- | ---------- | ----------- |");
+  for (const entry of report.entries) {
+    const lastAttempt = formatTimestampForTable(entry.last_attempted_at);
+    lines.push(
+      `| ${entry.session_id_short} | ${lastAttempt} | ${entry.outcome} | ${entry.candidates_proposed} | ${entry.age_since_covered_hours}h |`
+    );
+  }
+  writeStdout(lines.join("\n"));
+}
+function renderHistoryAllReport(report, sinceLabel, mode, dt) {
+  if (report.rows.length === 0) {
+    writeStdout(dt("doctor.history.empty", { sinceLabel, mode }));
+    return;
+  }
+  const lines = [];
+  lines.push(
+    dt("doctor.history.header", {
+      sinceLabel,
+      mode,
+      days: String(report.rows.length)
+    })
+  );
+  lines.push("");
+  if (mode === "fix") {
+    lines.push("| date       | lint | fix | issues | mutations |");
+    lines.push("| ---------- | ---- | --- | ------ | --------- |");
+    for (const row of report.rows) {
+      lines.push(
+        `| ${row.date} | ${row.doctor_runs_lint} | ${row.doctor_runs_fix} | ${row.doctor_total_issues} | ${row.doctor_total_mutations} |`
+      );
+    }
+  } else {
+    lines.push("| date       | lint | fix | issues | mutations | archive | proposed |");
+    lines.push("| ---------- | ---- | --- | ------ | --------- | ------- | -------- |");
+    for (const row of report.rows) {
+      lines.push(
+        `| ${row.date} | ${row.doctor_runs_lint} | ${row.doctor_runs_fix} | ${row.doctor_total_issues} | ${row.doctor_total_mutations} | ${row.archive_attempts} | ${row.archive_proposed} |`
+      );
+    }
+  }
+  writeStdout(lines.join("\n"));
+}
+function formatTimestampForTable(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  const pad = (n) => n < 10 ? `0${n}` : `${n}`;
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(
+    d.getUTCHours()
+  )}:${pad(d.getUTCMinutes())}`;
+}
+export {
+  doctor_default as default,
+  doctorCommand,
+  parseSinceDuration
+};