@fenglimg/fabric-server 2.0.0-rc.30 → 2.0.0-rc.34

package/dist/{chunk-4DLGRSYE.js → chunk-Z23PAA5L.js}

@@ -1691,6 +1691,27 @@ function readSelectionTokenTtlMs(projectRoot) {
     return void 0;
   }
 }
+function readOrphanDemoteThresholdDays(projectRoot) {
+  try {
+    const cfg = readFabricConfig(projectRoot);
+    const out = {};
+    const validate = (v) => {
+      if (typeof v !== "number" || !Number.isFinite(v) || v < 1 || v > 3650 || !Number.isInteger(v)) {
+        return void 0;
+      }
+      return v;
+    };
+    const s = validate(cfg.orphan_demote_stable_days);
+    if (s !== void 0) out.stable = s;
+    const e = validate(cfg.orphan_demote_endorsed_days);
+    if (e !== void 0) out.endorsed = e;
+    const d = validate(cfg.orphan_demote_draft_days);
+    if (d !== void 0) out.draft = d;
+    return out;
+  } catch {
+    return {};
+  }
+}
 
 // src/services/doctor.ts
 import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText4 } from "@fenglimg/fabric-shared/node/atomic-write";
@@ -1804,6 +1825,10 @@ async function runDoctorReport(target) {
   ]);
   const mcpConfigInWrongFile = inspectMcpConfigInWrongFile(projectRoot);
   const skillRefMirror = inspectSkillRefMirror(projectRoot);
+  const skillTokenBudget = inspectSkillTokenBudget(projectRoot);
+  const skillDescription = inspectSkillDescription(projectRoot);
+  const citeGoodhart = await inspectCiteGoodhart(projectRoot);
+  const draftBacklog = inspectDraftBacklog(projectRoot);
   const metaManuallyDiverged = await inspectMetaManuallyDiverged(projectRoot);
   const knowledgeDirUnindexed = inspectKnowledgeDirUnindexed(projectRoot, meta);
   const knowledgeDirMissing = inspectKnowledgeDirMissing(projectRoot);
@@ -1830,6 +1855,8 @@ async function runDoctorReport(target) {
   const relevanceFieldsMissing = inspectRelevanceFieldsMissing(projectRoot);
   const skillMdYamlInvalid = inspectSkillMdYamlInvalid(projectRoot);
   const onboardCoverage = inspectOnboardCoverage(projectRoot);
+  const hooksWired = inspectHooksWired(projectRoot);
+  const promoteLedgerInvariant = eventLedger.exists && eventLedger.writable && eventLedger.parseable ? await inspectPromoteLedgerInvariant(projectRoot) : null;
   const checks = [
     createBootstrapAnchorCheck(t, bootstrapAnchor),
     // v2.0.0-rc.19 TASK-004: bootstrap marker migration check sits adjacent to
@@ -1871,6 +1898,10 @@ async function runDoctorReport(target) {
     // contract between .claude/skills/<slug>/ref/ and .codex/skills/<slug>/
     // ref/. warning severity — fab install restores parity.
     createSkillRefMirrorCheck(t, skillRefMirror),
+    createSkillTokenBudgetCheck(t, skillTokenBudget),
+    createSkillDescriptionCheck(t, skillDescription),
+    createCiteGoodhartCheck(t, citeGoodhart),
+    createDraftBacklogCheck(t, draftBacklog),
     createMcpConfigInWrongFileCheck(t, mcpConfigInWrongFile),
     createMetaManuallyDivergedCheck(t, metaManuallyDiverged),
     createKnowledgeDirUnindexedCheck(t, knowledgeDirUnindexed),
@@ -1924,6 +1955,12 @@ async function runDoctorReport(target) {
     // first-run phase. Sits adjacent to Skill markdown YAML — both are
     // Skill-adjacent advisories. --fix never mutates onboard state.
     createOnboardCoverageCheck(t, onboardCoverage),
+    // rc.31 BUG-M3/NEW-4: hooks_wired observability. Adjacent to onboard /
+    // promote-ledger checks — all three are install/runtime-state advisories.
+    createHooksWiredCheck(t, hooksWired),
+    // rc.31 BUG-G2/G5: promote-ledger invariant. Sits adjacent to onboard
+    // coverage — both are observability advisories built off events.jsonl.
+    ...promoteLedgerInvariant === null ? [] : [createPromoteLedgerInvariantCheck(t, promoteLedgerInvariant)],
     createPreexistingRootFilesCheck(t, preexistingRootFiles)
     // v2.0 / rc.2: `createLegacyClientPathCheck` removed. The schema now
     // rejects retired clientPaths keys (windsurf/rooCode/geminiCLI) at Zod
@@ -2032,13 +2069,14 @@ async function runDoctorFix(target) {
   const reconcileCodes = [
     "agents_meta_missing",
     "agents_meta_stale",
+    "agents_meta_invalid",
     "knowledge_test_index_missing",
     "knowledge_test_index_stale",
     "content_ref_missing",
     "knowledge_dir_unindexed",
     "meta_manually_diverged"
   ];
-  if (before.fixable_errors.some((issue) => reconcileCodes.includes(issue.code)) || before.warnings.some((issue) => reconcileCodes.includes(issue.code))) {
+  if (before.fixable_errors.some((issue) => reconcileCodes.includes(issue.code)) || before.warnings.some((issue) => reconcileCodes.includes(issue.code)) || before.manual_errors.some((issue) => reconcileCodes.includes(issue.code))) {
     await reconcileKnowledge(projectRoot, { trigger: "doctor" });
     for (const issue of before.fixable_errors.filter(
       (candidate) => reconcileCodes.includes(candidate.code)
@@ -2050,6 +2088,11 @@ async function runDoctorFix(target) {
     )) {
       fixed.push(issue);
     }
+    for (const issue of before.manual_errors.filter(
+      (candidate) => reconcileCodes.includes(candidate.code)
+    )) {
+      fixed.push(issue);
+    }
     contextCache.invalidate("meta_write", projectRoot);
     await fixCounterDesync(projectRoot);
     contextCache.invalidate("meta_write", projectRoot);
@@ -2735,6 +2778,184 @@ function inspectSkillRefMirror(projectRoot) {
   if (driftedPaths.length === 0) return { status: "ok" };
   return { status: "drift", driftedPaths };
 }
+function inspectSkillTokenBudget(projectRoot) {
+  const skillSlugs = ["fabric-archive", "fabric-review", "fabric-import"];
+  const WARN_TOKENS = 5e3;
+  const ERROR_TOKENS = 1e4;
+  const overSize = [];
+  let highestSeverity = "ok";
+  for (const slug of skillSlugs) {
+    const skillMdPath = join7(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    let body;
+    try {
+      body = readFileSync3(skillMdPath, "utf8");
+    } catch {
+      continue;
+    }
+    const tokens = Math.ceil(body.length / 3);
+    if (tokens > ERROR_TOKENS) {
+      overSize.push({ slug, tokens, severity: "error" });
+      highestSeverity = "error";
+    } else if (tokens > WARN_TOKENS) {
+      overSize.push({ slug, tokens, severity: "warn" });
+      if (highestSeverity !== "error") highestSeverity = "warn";
+    }
+  }
+  return { status: highestSeverity, overSize };
+}
+function inspectSkillDescription(projectRoot) {
+  const skillSlugs = ["fabric-archive", "fabric-review", "fabric-import"];
+  const MAX_DESCRIPTION_TOKENS = 60;
+  const issues = [];
+  const CJK_PATTERN = /[㐀-䶿一-鿿]/;
+  const ASCII_PATTERN = /[a-zA-Z]{2,}/;
+  for (const slug of skillSlugs) {
+    const skillMdPath = join7(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    let body;
+    try {
+      body = readFileSync3(skillMdPath, "utf8");
+    } catch {
+      continue;
+    }
+    const fmMatch = body.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch) {
+      issues.push({ slug, problem: "missing", detail: "no YAML frontmatter" });
+      continue;
+    }
+    const descMatch = fmMatch[1].match(/^description:\s*(.+?)\s*$/m);
+    if (!descMatch || descMatch[1].trim().length === 0) {
+      issues.push({ slug, problem: "missing", detail: "description field empty or absent" });
+      continue;
+    }
+    const description = descMatch[1].replace(/^["'](.+)["']$/, "$1");
+    const tokens = Math.ceil(description.length / 3);
+    if (tokens > MAX_DESCRIPTION_TOKENS) {
+      issues.push({ slug, problem: "too_long", detail: `${tokens} tok (max ${MAX_DESCRIPTION_TOKENS})` });
+    }
+    if (!CJK_PATTERN.test(description)) {
+      issues.push({ slug, problem: "no_cjk", detail: "no Chinese trigger phrase" });
+    }
+    if (!ASCII_PATTERN.test(description)) {
+      issues.push({ slug, problem: "no_ascii", detail: "no English trigger phrase" });
+    }
+  }
+  return { status: issues.length === 0 ? "ok" : "warn", issues };
+}
+async function inspectCiteGoodhart(projectRoot) {
+  const WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+  const RITUAL_REPEAT_THRESHOLD = 5;
+  const DISMISSAL_ABUSE_RATIO = 0.6;
+  const PLACEHOLDER_COUNT_THRESHOLD = 5;
+  const cutoffMs = Date.now() - WINDOW_MS;
+  const fired = [];
+  let events = [];
+  try {
+    const result = await readEventLedger(projectRoot);
+    events = result.events;
+  } catch {
+    return { status: "ok", fired: [] };
+  }
+  const turns = events.filter(
+    (e) => {
+      if (e.event_type !== "assistant_turn_observed") return false;
+      const ts = Date.parse(e.timestamp);
+      return Number.isFinite(ts) && ts >= cutoffMs;
+    }
+  );
+  if (turns.length === 0) {
+    return { status: "ok", fired: [] };
+  }
+  const recalledCount = /* @__PURE__ */ new Map();
+  for (const turn of turns) {
+    for (let i = 0; i < turn.cite_ids.length; i += 1) {
+      if (turn.cite_tags[i] === "recalled") {
+        const key = turn.cite_ids[i];
+        recalledCount.set(key, (recalledCount.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  for (const [id, n] of recalledCount.entries()) {
+    if (n > RITUAL_REPEAT_THRESHOLD) {
+      fired.push({ pattern: "G1", detail: `${id} repeated as [recalled] ${n}x in 7d` });
+      break;
+    }
+  }
+  let recalledTotal = 0;
+  let recalledWithSkip = 0;
+  for (const turn of turns) {
+    for (let i = 0; i < turn.cite_ids.length; i += 1) {
+      if (turn.cite_tags[i] !== "recalled") continue;
+      recalledTotal += 1;
+      const commitment = turn.cite_commitments[i];
+      if (commitment && typeof commitment.skip_reason === "string" && commitment.skip_reason.length > 0) {
+        recalledWithSkip += 1;
+      }
+    }
+  }
+  if (recalledTotal >= 5 && recalledWithSkip / recalledTotal > DISMISSAL_ABUSE_RATIO) {
+    fired.push({
+      pattern: "G2",
+      detail: `${recalledWithSkip}/${recalledTotal} recalled cites used skip:<reason> (> ${Math.round(DISMISSAL_ABUSE_RATIO * 100)}%)`
+    });
+  }
+  let chainedFromMisuse = 0;
+  for (const turn of turns) {
+    for (let i = 0; i < turn.cite_ids.length; i += 1) {
+      if (turn.cite_tags[i] !== "chained-from") continue;
+      const commitment = turn.cite_commitments[i];
+      if (!commitment) {
+        chainedFromMisuse += 1;
+        continue;
+      }
+      const hasOps = Array.isArray(commitment.operators) && commitment.operators.length > 0;
+      const hasSkip = typeof commitment.skip_reason === "string" && commitment.skip_reason.length > 0;
+      if (!hasOps && !hasSkip) chainedFromMisuse += 1;
+    }
+  }
+  if (chainedFromMisuse > RITUAL_REPEAT_THRESHOLD) {
+    fired.push({
+      pattern: "G3",
+      detail: `${chainedFromMisuse} chained-from cites with no commitment (operators=[] + skip_reason=null) in 7d`
+    });
+  }
+  let placeholderCount = 0;
+  for (const turn of turns) {
+    if (turn.cite_tags.length === 0) continue;
+    const allNone = turn.cite_tags.every((t) => t === "none");
+    if (!allNone) continue;
+    const raw = (turn.kb_line_raw ?? "").trim();
+    if (raw === "KB: none" || raw.includes("[unspecified]")) {
+      placeholderCount += 1;
+    }
+  }
+  if (placeholderCount > PLACEHOLDER_COUNT_THRESHOLD) {
+    fired.push({
+      pattern: "G5",
+      detail: `${placeholderCount} placeholder "KB: none" / "[unspecified]" cites in 7d`
+    });
+  }
+  return { status: fired.length === 0 ? "ok" : "warn", fired };
+}
+function inspectDraftBacklog(projectRoot) {
+  const DRAFT_BACKLOG_RATIO = 0.5;
+  const MIN_TOTAL_FOR_RATIO = 10;
+  let draftCount = 0;
+  let totalCount = 0;
+  for (const entry of iterateCanonicalEntries(projectRoot, /* @__PURE__ */ new Map())) {
+    totalCount += 1;
+    if (entry.maturity === "draft") draftCount += 1;
+  }
+  if (totalCount < MIN_TOTAL_FOR_RATIO) {
+    return { status: "ok", draftCount, totalCount, ratio: 0 };
+  }
+  const ratio = draftCount / totalCount;
+  return {
+    status: ratio > DRAFT_BACKLOG_RATIO ? "warn" : "ok",
+    draftCount,
+    totalCount,
+    ratio
+  };
+}
 async function inspectKnowledgeTestIndex(projectRoot) {
   const path2 = join7(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const built = await tryBuildRuleMeta(projectRoot);
@@ -3330,6 +3551,90 @@ function createSkillRefMirrorCheck(t, inspection) {
     t("doctor.check.skill_ref_mirror.remediation")
   );
 }
+function createSkillTokenBudgetCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.skill_token_budget.name"),
+      t("doctor.check.skill_token_budget.ok")
+    );
+  }
+  const list = inspection.overSize.map((s) => `${s.slug}=${s.tokens} tok (${s.severity})`).join(", ");
+  const count = inspection.overSize.length;
+  return issueCheck(
+    t("doctor.check.skill_token_budget.name"),
+    inspection.status,
+    inspection.status === "error" ? "manual_error" : "warning",
+    "skill_token_budget_exceeded",
+    t(`doctor.check.skill_token_budget.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      list
+    }),
+    t("doctor.check.skill_token_budget.remediation")
+  );
+}
+function createDraftBacklogCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.draft_backlog.name"),
+      t("doctor.check.draft_backlog.ok")
+    );
+  }
+  const pct = Math.round(inspection.ratio * 100);
+  return issueCheck(
+    t("doctor.check.draft_backlog.name"),
+    "warn",
+    "warning",
+    "knowledge_draft_backlog",
+    t("doctor.check.draft_backlog.message", {
+      draftCount: String(inspection.draftCount),
+      totalCount: String(inspection.totalCount),
+      pct: String(pct)
+    }),
+    t("doctor.check.draft_backlog.remediation")
+  );
+}
+function createCiteGoodhartCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.cite_goodhart.name"),
+      t("doctor.check.cite_goodhart.ok")
+    );
+  }
+  const list = inspection.fired.map((f) => `${f.pattern}: ${f.detail}`).join("; ");
+  const count = inspection.fired.length;
+  return issueCheck(
+    t("doctor.check.cite_goodhart.name"),
+    "warn",
+    "warning",
+    "cite_goodhart_pattern",
+    t(`doctor.check.cite_goodhart.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      list
+    }),
+    t("doctor.check.cite_goodhart.remediation")
+  );
+}
+function createSkillDescriptionCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.skill_description.name"),
+      t("doctor.check.skill_description.ok")
+    );
+  }
+  const list = inspection.issues.map((i) => `${i.slug}: ${i.problem} (${i.detail})`).join("; ");
+  const count = inspection.issues.length;
+  return issueCheck(
+    t("doctor.check.skill_description.name"),
+    "warn",
+    "warning",
+    "skill_description_quality",
+    t(`doctor.check.skill_description.message.${count === 1 ? "singular" : "plural"}`, {
+      count: String(count),
+      list
+    }),
+    t("doctor.check.skill_description.remediation")
+  );
+}
 function createEventLedgerPartialWriteCheck(t, ledger) {
   if (!ledger.exists || !ledger.writable) {
     return okCheck(
@@ -3358,6 +3663,137 @@ function createEventLedgerPartialWriteCheck(t, ledger) {
 function okCheck(name, message) {
   return { name, status: "ok", message };
 }
+function inspectHooksWired(projectRoot) {
+  const claudeDir = join7(projectRoot, ".claude");
+  if (!existsSync5(claudeDir)) {
+    return { status: "skipped", missingHooks: [] };
+  }
+  const settingsPath = join7(projectRoot, ".claude", "settings.json");
+  if (!existsSync5(settingsPath)) {
+    return { status: "missing-settings", missingHooks: [] };
+  }
+  let raw;
+  try {
+    raw = readFileSync3(settingsPath, "utf8");
+  } catch {
+    return { status: "missing-settings", missingHooks: [] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { status: "missing-settings", missingHooks: [] };
+  }
+  const required = [
+    { event: "Stop", hookFile: "fabric-hint.cjs" },
+    { event: "SessionStart", hookFile: "knowledge-hint-broad.cjs" },
+    { event: "PreToolUse", hookFile: "knowledge-hint-narrow.cjs" }
+  ];
+  const missing = [];
+  const hooksSection = isRecord(parsed) ? parsed.hooks : void 0;
+  for (const { event, hookFile } of required) {
+    if (!isHookWiredForEvent(hooksSection, event, hookFile)) {
+      missing.push(`${event}:${hookFile}`);
+    }
+  }
+  if (missing.length === 0) {
+    return { status: "ok", missingHooks: [] };
+  }
+  return { status: "incomplete", missingHooks: missing };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHookWiredForEvent(hooks, event, hookFile) {
+  if (!isRecord(hooks)) return false;
+  const eventEntries = hooks[event];
+  if (!Array.isArray(eventEntries)) return false;
+  for (const matcherBlock of eventEntries) {
+    if (!isRecord(matcherBlock)) continue;
+    const inner = matcherBlock.hooks;
+    if (!Array.isArray(inner)) continue;
+    for (const hookEntry of inner) {
+      if (!isRecord(hookEntry)) continue;
+      const cmd = hookEntry.command;
+      if (typeof cmd === "string" && cmd.includes(hookFile)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function createHooksWiredCheck(t, inspection) {
+  if (inspection.status === "skipped") {
+    return okCheck(
+      t("doctor.check.hooks_wired.name"),
+      t("doctor.check.hooks_wired.ok.skipped")
+    );
+  }
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.hooks_wired.name"),
+      t("doctor.check.hooks_wired.ok.wired")
+    );
+  }
+  if (inspection.status === "missing-settings") {
+    return issueCheck(
+      t("doctor.check.hooks_wired.name"),
+      "warn",
+      "warning",
+      "hooks_wired_missing_settings",
+      t("doctor.check.hooks_wired.message.missing_settings"),
+      t("doctor.check.hooks_wired.remediation")
+    );
+  }
+  return issueCheck(
+    t("doctor.check.hooks_wired.name"),
+    "warn",
+    "warning",
+    "hooks_wired_incomplete",
+    t("doctor.check.hooks_wired.message.incomplete", {
+      missing: inspection.missingHooks.join(", ")
+    }),
+    t("doctor.check.hooks_wired.remediation")
+  );
+}
+async function inspectPromoteLedgerInvariant(projectRoot) {
+  const [proposed, started, promoted] = await Promise.all([
+    readEventLedger(projectRoot, { event_type: "knowledge_proposed" }),
+    readEventLedger(projectRoot, { event_type: "knowledge_promote_started" }),
+    readEventLedger(projectRoot, { event_type: "knowledge_promoted" })
+  ]);
+  const proposedCount = proposed.events.length;
+  const promoteStartedCount = started.events.length;
+  const promotedCount = promoted.events.length;
+  let violation = null;
+  if (proposedCount < promoteStartedCount) {
+    violation = "proposed-lt-started";
+  } else if (promoteStartedCount < promotedCount) {
+    violation = "started-lt-promoted";
+  }
+  return { proposedCount, promoteStartedCount, promotedCount, violation };
+}
+function createPromoteLedgerInvariantCheck(t, inspection) {
+  const params = {
+    proposed: String(inspection.proposedCount),
+    started: String(inspection.promoteStartedCount),
+    promoted: String(inspection.promotedCount)
+  };
+  if (inspection.violation === null) {
+    return okCheck(
+      t("doctor.check.promote_ledger_invariant.name"),
+      t("doctor.check.promote_ledger_invariant.ok", params)
+    );
+  }
+  return issueCheck(
+    t("doctor.check.promote_ledger_invariant.name"),
+    "warn",
+    "warning",
+    "promote_ledger_invariant_violated",
+    t(`doctor.check.promote_ledger_invariant.message.${inspection.violation}`, params),
+    t("doctor.check.promote_ledger_invariant.remediation")
+  );
+}
 function issueCheck(name, status, kind, code, message, actionHint) {
   return {
     name,
@@ -3804,13 +4240,24 @@ async function buildLastConsumedIndex(projectRoot) {
     return map;
   }
   for (const event of events) {
-    if (event.event_type !== "knowledge_consumed" && event.event_type !== "knowledge_demoted" && event.event_type !== "knowledge_archived") {
-      continue;
-    }
     const ts = event.ts;
     if (typeof ts !== "number" || !Number.isFinite(ts)) {
       continue;
     }
+    if (event.event_type === "knowledge_sections_fetched") {
+      const ids = Array.isArray(event.final_stable_ids) ? event.final_stable_ids : [];
+      for (const stableId2 of ids) {
+        if (typeof stableId2 !== "string" || stableId2.length === 0) continue;
+        const prev2 = map.get(stableId2);
+        if (prev2 === void 0 || ts > prev2) {
+          map.set(stableId2, ts);
+        }
+      }
+      continue;
+    }
+    if (event.event_type !== "knowledge_consumed" && event.event_type !== "knowledge_demoted" && event.event_type !== "knowledge_archived") {
+      continue;
+    }
     const stableId = event.stable_id;
     if (typeof stableId !== "string" || stableId.length === 0) {
       continue;
@@ -3882,8 +4329,16 @@ async function buildLastActiveIndex(projectRoot) {
   }
   return map;
 }
-function maturityThresholdDays(maturity) {
-  return ORPHAN_DEMOTE_THRESHOLD_DAYS[maturity];
+function resolveMaturityThresholds(projectRoot) {
+  const overrides = readOrphanDemoteThresholdDays(projectRoot);
+  return {
+    stable: overrides.stable ?? ORPHAN_DEMOTE_THRESHOLD_DAYS.stable,
+    endorsed: overrides.endorsed ?? ORPHAN_DEMOTE_THRESHOLD_DAYS.endorsed,
+    draft: overrides.draft ?? ORPHAN_DEMOTE_THRESHOLD_DAYS.draft
+  };
+}
+function maturityThresholdDays(maturity, thresholds) {
+  return (thresholds ?? ORPHAN_DEMOTE_THRESHOLD_DAYS)[maturity];
 }
 function nextLowerMaturity(current) {
   if (current === "stable") return "endorsed";
@@ -3969,11 +4424,12 @@ function* iterateCanonicalEntries(projectRoot, lastActiveIndex) {
 }
 async function inspectOrphanDemote(projectRoot, now) {
   const lastConsumedIndex = await buildLastConsumedIndex(projectRoot);
+  const thresholds = resolveMaturityThresholds(projectRoot);
   const candidates = [];
   for (const entry of iterateCanonicalEntries(projectRoot, lastConsumedIndex)) {
     const ageMs = entry.lastReferenceMs > 0 ? now - entry.lastReferenceMs : now;
     const ageDays = Math.floor(ageMs / MS_PER_DAY);
-    const threshold = maturityThresholdDays(entry.maturity);
+    const threshold = maturityThresholdDays(entry.maturity, thresholds);
     if (ageDays <= threshold) {
       continue;
     }
@@ -3986,7 +4442,7 @@ async function inspectOrphanDemote(projectRoot, now) {
     });
   }
   candidates.sort((a, b) => a.path.localeCompare(b.path));
-  return { candidates };
+  return { candidates, thresholds };
 }
 async function inspectStaleArchive(projectRoot, now) {
   const lastActiveIndex = await buildLastActiveIndex(projectRoot);
@@ -4307,9 +4763,9 @@ function createOrphanDemoteCheck(t, inspection) {
     "knowledge_orphan_demote_required",
     t(`doctor.check.orphan_demote.message.${count === 1 ? "singular" : "plural"}`, {
       count: String(count),
-      stableDays: String(ORPHAN_DEMOTE_THRESHOLD_DAYS.stable),
-      endorsedDays: String(ORPHAN_DEMOTE_THRESHOLD_DAYS.endorsed),
-      draftDays: String(ORPHAN_DEMOTE_THRESHOLD_DAYS.draft),
+      stableDays: String(inspection.thresholds.stable),
+      endorsedDays: String(inspection.thresholds.endorsed),
+      draftDays: String(inspection.thresholds.draft),
       detail
     }),
     t("doctor.check.orphan_demote.remediation")

package/dist/{http-ALTGDHLT.js → http-2L2SQN7A.js}

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-4DLGRSYE.js";
+} from "./chunk-Z23PAA5L.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";

package/dist/index.js

@@ -39,7 +39,7 @@ import {
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-4DLGRSYE.js";
+} from "./chunk-Z23PAA5L.js";
 
 // src/index.ts
 import { existsSync as existsSync3 } from "fs";
@@ -333,6 +333,16 @@ function renderFreshEntry(args) {
     `created_at: ${createdAt}`,
     `source_sessions: [${args.sourceSessions.map((s) => JSON.stringify(s)).join(", ")}]`,
     `proposed_reason: ${args.proposedReason}`,
+    // rc.31 BUG-2.9/2.1: persist the caller-supplied summary in frontmatter so
+    // knowledge-meta-builder.extractDescriptionFromFrontmatter picks it up
+    // directly. Without this, the meta-builder fell back to extractRule
+    // Description's h1-or-stable-id-or-placeholder synthesis (line ~944),
+    // which made user-visible description.summary == stable_id for any
+    // pending file whose body started with h2-only sections (`## Summary` is
+    // the canonical pending shape). The frontmatter `summary:` line is the
+    // canonical source-of-truth: `extractDescriptionFromFrontmatter` reads it
+    // before extractRuleDescription's fallback kicks in.
+    `summary: ${quoteRelevancePath(args.summary)}`,
     "tags: []"
   ];
   if (args.relevanceScope !== void 0) {
@@ -615,7 +625,11 @@ async function planContext(projectRoot, input) {
   }
   const stale = metaResult.degraded === true || input.client_hash !== void 0 && input.client_hash !== meta.revision;
   const uniquePaths = dedupePaths(input.paths);
-  const allDescriptions = buildDescriptionIndex(meta);
+  const scoringContext = {
+    nowMs: Date.now(),
+    targetPaths: input.target_paths ?? dedupePaths(input.paths)
+  };
+  const allDescriptions = buildDescriptionIndex(meta, scoringContext);
   const relevanceTargetPaths = input.target_paths ?? uniquePaths;
   const entries = uniquePaths.map((path) => {
     const profile = buildRequirementProfile(path, input);
@@ -719,7 +733,7 @@ function buildRequirementProfile(path, input) {
     detected_entities: input.detected_entities?.[normalizedPath] ?? input.detected_entities?.[path] ?? []
   };
 }
-function buildDescriptionIndex(meta) {
+function buildDescriptionIndex(meta, scoringContext) {
   return Object.entries(meta.nodes).flatMap(([nodeId, node]) => {
     const level = deriveAgentsMetaLayer(node.file);
     const description = node.description ?? descriptionFromLegacyActivation(node.activation?.description);
@@ -744,7 +758,7 @@ function buildDescriptionIndex(meta) {
       relevance_scope: description.relevance_scope,
       relevance_paths: description.relevance_paths
     }];
-  }).sort(compareDescriptionIndexItems);
+  }).sort((left, right) => compareDescriptionIndexItems(left, right, scoringContext));
 }
 function matchesAnyPath(globs, targetPaths) {
   if (globs.length === 0) {
@@ -827,9 +841,68 @@ function dedupeDescriptionIndex(items) {
     return true;
   });
 }
-function compareDescriptionIndexItems(left, right) {
+function compareDescriptionIndexItems(left, right, context) {
+  if (context !== void 0) {
+    const leftScore = scoreDescriptionItem(left, context.nowMs, context.targetPaths);
+    const rightScore = scoreDescriptionItem(right, context.nowMs, context.targetPaths);
+    if (leftScore !== rightScore) {
+      return rightScore - leftScore;
+    }
+  }
   return left.stable_id.localeCompare(right.stable_id);
 }
+var RECENCY_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+var RECENCY_BOOST = 100;
+var LOCALITY_SAME_FILE = 100;
+var LOCALITY_SAME_DIR = 50;
+var LOCALITY_SAME_PACKAGE = 25;
+function scoreDescriptionItem(item, nowMs, targetPaths) {
+  let score = 0;
+  const createdAtRaw = item.description?.created_at;
+  if (typeof createdAtRaw === "string" && createdAtRaw.length > 0) {
+    const createdMs = Date.parse(createdAtRaw);
+    if (Number.isFinite(createdMs) && nowMs - createdMs < RECENCY_WINDOW_MS) {
+      score += RECENCY_BOOST;
+    }
+  }
+  if (targetPaths.length > 0) {
+    const relevancePaths = item.relevance_paths ?? item.description?.relevance_paths ?? [];
+    let best = 0;
+    for (const rp of relevancePaths) {
+      for (const tp of targetPaths) {
+        const tier = localityTier(rp, tp);
+        if (tier > best) best = tier;
+      }
+    }
+    score += best;
+  }
+  return score;
+}
+function localityTier(relevancePath, targetPath) {
+  if (relevancePath === targetPath) return LOCALITY_SAME_FILE;
+  const rpDir = dirnameOfPath(relevancePath);
+  const tpDir = dirnameOfPath(targetPath);
+  if (rpDir.length > 0 && rpDir === tpDir) return LOCALITY_SAME_DIR;
+  const rpPkg = packageRootOfPath(relevancePath);
+  const tpPkg = packageRootOfPath(targetPath);
+  if (rpPkg.length > 0 && rpPkg === tpPkg) return LOCALITY_SAME_PACKAGE;
+  return 0;
+}
+function dirnameOfPath(p) {
+  const idx = p.search(/[*?[]/);
+  if (idx >= 0) {
+    return p.slice(0, idx).replace(/\/$/, "");
+  }
+  const lastSlash = p.lastIndexOf("/");
+  return lastSlash >= 0 ? p.slice(0, lastSlash) : "";
+}
+function packageRootOfPath(p) {
+  const idx = p.search(/[*?[]/);
+  const stem = idx >= 0 ? p.slice(0, idx).replace(/\/$/, "") : p;
+  const segments = stem.split("/").filter(Boolean);
+  if (segments.length < 2) return "";
+  return segments.slice(0, 2).join("/");
+}
 
 // src/tools/plan-context.ts
 function registerPlanContext(server, tracker) {
@@ -1195,6 +1268,11 @@ async function approveOne(projectRoot, pendingPath, allocator) {
     return null;
   }
   const slug = basename(pendingPath).replace(/\.md$/u, "");
+  await emitEventBestEffort2(projectRoot, {
+    event_type: "knowledge_proposed",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    reason: `approve-synth:${slug}`
+  });
   await emitEventBestEffort2(projectRoot, {
     event_type: "knowledge_promote_started",
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2013,7 +2091,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.30"
+    version: "2.0.0-rc.34"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -2121,7 +2199,7 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-ALTGDHLT.js");
+  const { createFabricHttpApp } = await import("./http-2L2SQN7A.js");
   const { port, projectRoot, host = "127.0.0.1", authToken, allowLoopbackNoAuth } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken, allowLoopbackNoAuth });
   return await new Promise((resolveServer, rejectServer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.30",
+  "version": "2.0.0-rc.34",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
     "express": "^5.2.1",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.0.0-rc.30"
+    "@fenglimg/fabric-shared": "2.0.0-rc.34"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",