@fenglimg/fabric-cli 2.2.0-rc.9 → 2.3.0-rc.1

package/dist/audit-PURSJJFH.js

@@ -0,0 +1,734 @@
+#!/usr/bin/env node
+import {
+  resolveDevMode
+} from "./chunk-WA3DYGSY.js";
+import {
+  paint,
+  symbol
+} from "./chunk-SL77FXX7.js";
+import {
+  getDoctorTranslator,
+  getProjectTranslator
+} from "./chunk-HORSMSZL.js";
+
+// src/commands/audit.ts
+import { defineCommand as defineCommand2 } from "citty";
+import {
+  enrichDescriptions,
+  explainWhyNotSurfaced,
+  inspectRetiredReferences,
+  runDoctorArchiveHistory,
+  runDoctorCiteCoverage,
+  runDoctorConflictLint,
+  runDoctorHistoryAll
+} from "@fenglimg/fabric-server";
+
+// src/commands/metrics.ts
+import { resolve } from "path";
+import { defineCommand } from "citty";
+import { readMetrics } from "@fenglimg/fabric-server";
+function parseSinceArg(raw, t2) {
+  if (raw === void 0 || raw.length === 0) return 0;
+  const match = /^(\d+)([smhd]?)$/u.exec(raw);
+  if (match === null) {
+    throw new Error(t2("cli.metrics.invalid-since", { raw }));
+  }
+  const n = Number.parseInt(match[1], 10);
+  const unit = match[2] ?? "s";
+  const multipliers = { s: 1e3, m: 6e4, h: 36e5, d: 864e5 };
+  return n * (multipliers[unit] ?? 1e3);
+}
+function aggregate(rows, sinceMs, now) {
+  const cutoff = sinceMs > 0 ? now.getTime() - sinceMs : 0;
+  const filtered = rows.filter((r) => {
+    if (cutoff === 0) return true;
+    const ts = Date.parse(r.timestamp);
+    return Number.isFinite(ts) && ts >= cutoff;
+  });
+  const totals = {};
+  const perEntryConsumed = {};
+  for (const row of filtered) {
+    for (const [name, count] of Object.entries(row.counters)) {
+      if (name.startsWith("knowledge_consumed:")) {
+        const id = name.slice("knowledge_consumed:".length);
+        perEntryConsumed[id] = (perEntryConsumed[id] ?? 0) + count;
+        totals["knowledge_consumed"] = (totals["knowledge_consumed"] ?? 0) + count;
+        continue;
+      }
+      totals[name] = (totals[name] ?? 0) + count;
+    }
+  }
+  return {
+    // Stable token (NOT localized) so the --json contract is locale-independent;
+    // renderText localizes "all-time" at presentation time only.
+    windowDescription: sinceMs > 0 ? formatDuration(sinceMs) : "all-time",
+    rowCount: filtered.length,
+    totals,
+    perEntryConsumed,
+    rangeStart: filtered[0]?.timestamp ?? null,
+    rangeEnd: filtered[filtered.length - 1]?.timestamp ?? null
+  };
+}
+function formatDuration(ms) {
+  if (ms >= 864e5) return `${Math.round(ms / 864e5)}d`;
+  if (ms >= 36e5) return `${Math.round(ms / 36e5)}h`;
+  if (ms >= 6e4) return `${Math.round(ms / 6e4)}m`;
+  return `${Math.round(ms / 1e3)}s`;
+}
+function renderText(agg, t2) {
+  const lines = [];
+  const windowDisplay = agg.windowDescription === "all-time" ? t2("cli.metrics.window-all-time") : agg.windowDescription;
+  lines.push(t2("cli.metrics.window", { window: windowDisplay }));
+  if (agg.rangeStart && agg.rangeEnd) {
+    lines.push(
+      t2("cli.metrics.rows-range", {
+        count: String(agg.rowCount),
+        start: agg.rangeStart,
+        end: agg.rangeEnd
+      })
+    );
+  } else {
+    lines.push(t2("cli.metrics.rows", { count: String(agg.rowCount) }));
+  }
+  lines.push("");
+  if (Object.keys(agg.totals).length === 0) {
+    lines.push(t2("cli.metrics.no-activity"));
+    return lines.join("\n");
+  }
+  lines.push("  counter                              total");
+  lines.push("  ------------------------------------ ----------");
+  const sorted = Object.entries(agg.totals).sort((a, b) => b[1] - a[1]);
+  for (const [name, count] of sorted) {
+    lines.push(`  ${name.padEnd(36)} ${String(count).padStart(10)}`);
+  }
+  const perEntrySorted = Object.entries(agg.perEntryConsumed).sort((a, b) => b[1] - a[1]).slice(0, 10);
+  if (perEntrySorted.length > 0) {
+    lines.push("");
+    lines.push("  Top per-entry consumed (knowledge_consumed:<id>)");
+    lines.push("  ------------------------------------ ----------");
+    for (const [id, count] of perEntrySorted) {
+      lines.push(`  ${id.padEnd(36)} ${String(count).padStart(10)}`);
+    }
+  }
+  return lines.join("\n");
+}
+var metricsCommand = defineCommand({
+  meta: {
+    name: "metrics",
+    description: "Print a text dashboard of Fabric counter activity from .fabric/metrics.jsonl",
+    hidden: true
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Emit machine-readable JSON instead of the text table.",
+      default: false
+    },
+    target: {
+      type: "string",
+      description: "Project root (defaults to the current working directory)."
+    },
+    since: {
+      type: "string",
+      description: "Limit to rows within a recent window. Examples: 24h, 7d, 30m, 90s. Omit for all-time."
+    }
+  },
+  async run({ args }) {
+    const projectRoot = resolve(args.target ?? process.cwd());
+    const t2 = getProjectTranslator(projectRoot);
+    const sinceMs = parseSinceArg(args.since, t2);
+    const rows = await readMetrics(projectRoot);
+    const aggregated = aggregate(rows, sinceMs, /* @__PURE__ */ new Date());
+    if (args.json === true) {
+      process.stdout.write(`${JSON.stringify(aggregated)}
+`);
+    } else {
+      process.stdout.write(`${renderText(aggregated, t2)}
+`);
+    }
+  }
+});
+var metrics_default = metricsCommand;
+
+// src/commands/audit.ts
+function writeStdout(message) {
+  process.stdout.write(`${message}
+`);
+}
+function writeStderr(message) {
+  process.stderr.write(`${message}
+`);
+}
+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}`);
+}
+var CITE_COVERAGE_CLIENT_FILTERS = /* @__PURE__ */ new Set([
+  "cc",
+  "codex",
+  "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 recallRate = report.metrics.recall_coverage_rate;
+  const recallStr = recallRate === null || recallRate === void 0 ? dt("doctor.cite.metric.recallCoverageNA") : `${(recallRate * 100).toFixed(1)}% (${report.metrics.recall_backed_edits ?? 0}/${report.metrics.edits_touched})`;
+  lines.push(`  ${dt("doctor.cite.metric.recallCoverage")}: ${recallStr}`);
+  const uncorrelatable = report.metrics.uncorrelatable_edits ?? 0;
+  if (uncorrelatable > 0) {
+    lines.push(`  ${dt("doctor.cite.metric.uncorrelatableEdits")}: ${uncorrelatable}`);
+  }
+  if (report.metrics.exposed_and_mutated !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.exposedAndMutated")}: ${report.metrics.exposed_and_mutated.count}`
+    );
+  }
+  if (report.metrics.mutations_observed !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.mutationsObserved")}: ${report.metrics.mutations_observed.count}`
+    );
+  }
+  if (report.metrics.mutation_pool !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.mutationPool")}: ${report.metrics.mutation_pool.attributed} / ${report.metrics.mutation_pool.unattributed_workspace_dirty} (attributed / unattributed_workspace_dirty)`
+    );
+  }
+  if (report.metrics.sessions_closed !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.sessionsClosed")}: ${report.metrics.sessions_closed.count}`
+    );
+  }
+  if (report.metrics.by_store !== void 0) {
+    const storeKeys = Object.keys(report.metrics.by_store).sort();
+    if (storeKeys.length > 0) {
+      lines.push(`  ${dt("doctor.cite.metric.byStore")}:`);
+      for (const store of storeKeys) {
+        lines.push(`    ${store}: ${report.metrics.by_store[store].qualifying_cites}`);
+      }
+    }
+  }
+  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 renderConflictLintReport(report, deepRequested, dt) {
+  const lines = [];
+  lines.push(dt("doctor.conflict.header"));
+  lines.push("");
+  if (report.candidate_count === 0) {
+    lines.push(`  ${symbol.ok} ${dt("doctor.conflict.none")}`);
+    writeStdout(lines.join("\n"));
+    return;
+  }
+  lines.push(
+    `  ${dt("doctor.conflict.summary", {
+      candidates: String(report.candidate_count),
+      conflicts: String(report.conflict_count),
+      threshold: report.threshold.toFixed(2)
+    })}`
+  );
+  if (deepRequested && !report.deep) {
+    lines.push(`  ${symbol.warn} ${dt("doctor.conflict.deep_no_judge")}`);
+  }
+  lines.push("");
+  for (const pair of report.pairs) {
+    const sym = pair.verdict === "conflict" ? symbol.error : symbol.warn;
+    const verdictLabel = dt(`doctor.conflict.verdict.${pair.verdict}`);
+    const pct = `${(pair.similarity * 100).toFixed(0)}%`;
+    let line = `  ${sym} [${pair.a} \u2194 ${pair.b}] (${pair.knowledge_type}/${pair.layer}) ${pct} \u2014 ${verdictLabel}`;
+    if (pair.rationale !== void 0 && pair.rationale.length > 0) {
+      line += `: ${pair.rationale}`;
+    }
+    lines.push(line);
+  }
+  writeStdout(lines.join("\n"));
+}
+function renderEnrichDescriptionsReport(report, dt) {
+  const header = `${symbol.ok} ${paint.ai("fabric audit 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 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())}`;
+}
+function renderRetiredReport(inspection) {
+  if (inspection.status === "skipped") {
+    writeStdout(`${symbol.warn} retired-reference scan skipped \u2014 no agent-consumed surfaces found.`);
+    return;
+  }
+  if (inspection.hits.length === 0) {
+    writeStdout(
+      `${symbol.ok} no retired references \u2014 scanned ${inspection.scannedFiles} agent surface(s).`
+    );
+    return;
+  }
+  writeStdout(
+    `${symbol.error} ${inspection.hits.length} retired reference(s) across ${inspection.scannedFiles} scanned file(s):`
+  );
+  for (const hit of inspection.hits) {
+    const fix = hit.replacement === null ? "(removed)" : `\u2192 ${hit.replacement}`;
+    writeStdout(`  ${hit.path}:${hit.line}  ${hit.token}  ${fix}`);
+  }
+}
+function renderWhyNotSurfaced(r) {
+  const id = r.localId;
+  switch (r.verdict) {
+    case "not_found":
+      writeStdout(
+        `${symbol.error} '${id}' not found in any mounted store. Check the id (try \`fabric store list\`).`
+      );
+      return;
+    case "store_unbound":
+      writeStdout(
+        `${symbol.error} '${id}' lives in store '${r.storeAlias}', which is NOT bound to this project.`
+      );
+      writeStdout(`  \u2192 bind it: fabric store bind ${r.storeAlias}`);
+      return;
+    case "project_mismatch":
+      writeStdout(
+        `${symbol.error} '${id}' is scoped to '${r.semanticScope}', but this repo is bound to 'project:${r.activeProject}'.`
+      );
+      writeStdout(`  \u2192 it surfaces only in repos bound to '${r.semanticScope}' (semantic_scope axis).`);
+      return;
+    case "narrow_timing":
+      writeStdout(
+        `${symbol.warn} '${id}' is relevance_scope=narrow \u2014 it surfaces via the PreToolUse hint when you EDIT a matching file, not at SessionStart.`
+      );
+      writeStdout(`  \u2192 broad entries are the always-on spine; narrow ones are edit-time only (timing axis).`);
+      return;
+    case "should_surface":
+      writeStdout(
+        `${symbol.ok} '${id}' should be surfacing \u2014 store '${r.storeAlias}' bound, scope matches, relevance_scope=broad.`
+      );
+      writeStdout(`  \u2192 if it isn't, the SessionStart snapshot may be stale: start a fresh session or re-run \`fabric install\`.`);
+      return;
+  }
+}
+var whyNotSurfacedCommand = defineCommand2({
+  meta: {
+    name: "why-not-surfaced",
+    description: "Diagnose why a knowledge entry isn't surfacing (store / scope / timing)"
+  },
+  args: {
+    id: { type: "positional", required: true, description: "Knowledge id (e.g. KT-DEC-0001 or team:KT-DEC-0001)" },
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const result = await explainWhyNotSurfaced(resolution.target, String(args.id));
+    if (args.json === true) {
+      writeStdout(JSON.stringify(result, null, 2));
+    } else {
+      renderWhyNotSurfaced(result);
+    }
+    if (result.verdict === "not_found") {
+      process.exitCode = 1;
+    }
+  }
+});
+var citeCommand = defineCommand2({
+  meta: { name: "cite", description: "Cite-policy adherence report (read-only)" },
+  args: {
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    since: { type: "string", description: "Window (e.g. 7d, 24h, 30m)", default: "7d" },
+    client: { type: "string", description: "Client filter", default: "all", valueHint: "cc|codex|all" },
+    layer: { type: "string", description: "KB layer filter", default: "all", valueHint: "team|personal|all" }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const dt = getDoctorTranslator(resolution.target);
+    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 report = await runDoctorCiteCoverage(resolution.target, {
+      since: sinceMs,
+      client: clientFilter,
+      layer: layerFilter
+    });
+    renderCiteCoverageReport(report, args.json === true, dt);
+  }
+});
+var conflictsCommand = defineCommand2({
+  meta: { name: "conflicts", description: "Knowledge-conflict lint (read-only)" },
+  args: {
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    deep: { type: "boolean", description: "Reserve the LLM-judge pass (no judge wired yet)", default: false }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const dt = getDoctorTranslator(resolution.target);
+    const report = await runDoctorConflictLint(resolution.target, { deep: args.deep === true });
+    if (args.json === true) {
+      writeStdout(JSON.stringify(report, null, 2));
+    } else {
+      renderConflictLintReport(report, args.deep === true, dt);
+    }
+  }
+});
+var historyCommand = defineCommand2({
+  meta: { name: "history", description: "Maintenance history rollup (archive | fix | all)" },
+  args: {
+    mode: { type: "positional", required: false, description: "archive | fix | all", valueHint: "archive|fix|all" },
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    since: { type: "string", description: "Window (e.g. 7d, 24h, 30m)", default: "7d" }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const dt = getDoctorTranslator(resolution.target);
+    const mode = typeof args.mode === "string" && args.mode.length > 0 ? args.mode : "all";
+    if (mode !== "archive" && mode !== "fix" && mode !== "all") {
+      writeStderr(dt("cli.doctor.errors.invalid-history-mode", { input: mode }));
+      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 (mode === "archive") {
+      const report2 = await runDoctorArchiveHistory(resolution.target, { since: sinceMs });
+      if (args.json === true) {
+        writeStdout(JSON.stringify(report2, null, 2));
+      } else {
+        renderArchiveHistoryReport(report2, sinceInput, dt);
+      }
+      return;
+    }
+    const report = await runDoctorHistoryAll(resolution.target, { since: sinceMs });
+    if (args.json === true) {
+      writeStdout(JSON.stringify(report, null, 2));
+    } else {
+      renderHistoryAllReport(report, sinceInput, mode, dt);
+    }
+  }
+});
+var descriptionsCommand = defineCommand2({
+  meta: { name: "descriptions", description: "Back-fill description-grade frontmatter fields" },
+  args: {
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    auto: { type: "boolean", description: "Write stub values (default: read-only list)", default: false },
+    "dry-run": { type: "boolean", description: "Preview --auto changes without writing", default: false }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const dt = getDoctorTranslator(resolution.target);
+    const report = await enrichDescriptions(resolution.target, {
+      auto: args.auto === true,
+      dryRun: args["dry-run"] === true
+    });
+    if (args.json === true) {
+      writeStdout(JSON.stringify(report, null, 2));
+    } else {
+      renderEnrichDescriptionsReport(report, dt);
+    }
+  }
+});
+var retiredCommand = defineCommand2({
+  meta: { name: "retired", description: "Scan agent surfaces for retired tool/field references" },
+  args: {
+    target: { type: "string", description: "Override project root (defaults to cwd)" },
+    json: { type: "boolean", description: "Output as JSON", default: false }
+  },
+  async run({ args }) {
+    const resolution = resolveDevMode(args.target, process.cwd());
+    const inspection = await inspectRetiredReferences(resolution.target);
+    if (args.json === true) {
+      writeStdout(JSON.stringify(inspection, null, 2));
+    } else {
+      renderRetiredReport(inspection);
+    }
+    if (inspection.status === "warn") {
+      process.exitCode = 1;
+    }
+  }
+});
+var auditCommand = defineCommand2({
+  meta: {
+    name: "audit",
+    description: "Knowledge & telemetry audits (cite / conflicts / history / descriptions / metrics / retired)"
+  },
+  subCommands: {
+    cite: citeCommand,
+    conflicts: conflictsCommand,
+    history: historyCommand,
+    descriptions: descriptionsCommand,
+    metrics: metrics_default,
+    retired: retiredCommand,
+    "why-not-surfaced": whyNotSurfacedCommand
+  }
+});
+var audit_default = auditCommand;
+export {
+  auditCommand,
+  citeCommand,
+  conflictsCommand,
+  audit_default as default,
+  descriptionsCommand,
+  historyCommand,
+  parseSinceDuration,
+  retiredCommand
+};