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

package/dist/{chunk-PNRWNUFX.js → chunk-5N3KXIVI.js}

@@ -57,6 +57,7 @@ var SKILL_IMPORT_TEMPLATE_REL = "skills/fabric-import/SKILL.md";
 var HOOK_SCRIPT_TEMPLATE_REL = "hooks/fabric-hint.cjs";
 var HOOK_BROAD_SCRIPT_TEMPLATE_REL = "hooks/knowledge-hint-broad.cjs";
 var HOOK_NARROW_SCRIPT_TEMPLATE_REL = "hooks/knowledge-hint-narrow.cjs";
+var HOOK_CITE_EVICT_SCRIPT_TEMPLATE_REL = "hooks/cite-policy-evict.cjs";
 var HOOK_LIB_TEMPLATE_DIR_REL = "hooks/lib";
 var CLAUDE_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/claude-code.json";
 var CODEX_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/codex-hooks.json";
@@ -90,7 +91,12 @@ var HOOK_SCRIPT_DESTINATIONS = {
     ".claude/hooks/knowledge-hint-narrow.cjs",
     ".codex/hooks/knowledge-hint-narrow.cjs",
     ".cursor/hooks/knowledge-hint-narrow.cjs"
-  ]
+  ],
+  // v2.0.0-rc.34 TASK-06: Claude Code only — UserPromptSubmit cite-policy
+  // long-session evict sidecar. Codex / Cursor don't have an equivalent
+  // event registration; cite-coverage telemetry there relies on the existing
+  // Stop / SessionStart hooks (knowledge-hint-broad rc.33 W2 channel).
+  citePolicyEvict: [".claude/hooks/cite-policy-evict.cjs"]
 };
 var HOOK_LIB_DESTINATIONS = [
   ".claude/hooks/lib",
@@ -141,32 +147,78 @@ function readFabricLanguagePreference(projectRoot) {
     return "match-existing";
   }
 }
+var SKILL_TOKEN_ERROR_TOKENS = 1e4;
+var STALE_INSTALL_RATIO = 1.5;
+function estimateSkillTokens(text) {
+  return Math.ceil(text.length / 3);
+}
+function validateSkillCanonicalSize(source, slug) {
+  const tokens = estimateSkillTokens(source);
+  if (tokens > SKILL_TOKEN_ERROR_TOKENS) {
+    throw new Error(
+      `Skill '${slug}' canonical SKILL.md estimates ${tokens} tok (>${SKILL_TOKEN_ERROR_TOKENS} ERROR threshold). Install aborted \u2014 this is a Fabric release bug, not a user-recoverable state. Re-split SKILL.md via progressive disclosure (see fabric-archive/phases/* as canonical example) and rebuild.`
+    );
+  }
+}
+function inspectStaleInstall(target, source) {
+  if (!existsSync2(target)) return null;
+  let existing;
+  try {
+    existing = readFileSync2(target, "utf8");
+  } catch {
+    return null;
+  }
+  const existingTok = estimateSkillTokens(existing);
+  const sourceTok = estimateSkillTokens(source);
+  if (existingTok > sourceTok * STALE_INSTALL_RATIO) {
+    return `stale-replaced (${existingTok} tok \u2192 ${sourceTok} tok canonical)`;
+  }
+  return null;
+}
 async function installFabricArchiveSkill(projectRoot, _options = {}) {
   const source = await readTemplate(SKILL_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-archive");
   const targets = SKILL_DESTINATIONS.fabricArchive.map((rel) => join2(projectRoot, rel));
   const results = [];
   for (const target of targets) {
-    results.push(await copyTextIdempotent("skill", source, target));
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
   }
   results.push(...await installSkillRefFiles(projectRoot, "fabric-archive"));
   return results;
 }
 async function installFabricReviewSkill(projectRoot, _options = {}) {
   const source = await readTemplate(SKILL_REVIEW_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-review");
   const targets = SKILL_DESTINATIONS.fabricReview.map((rel) => join2(projectRoot, rel));
   const results = [];
   for (const target of targets) {
-    results.push(await copyTextIdempotent("skill-review", source, target));
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill-review", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
   }
   results.push(...await installSkillRefFiles(projectRoot, "fabric-review"));
   return results;
 }
 async function installFabricImportSkill(projectRoot, _options = {}) {
   const source = await readTemplate(SKILL_IMPORT_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-import");
   const targets = SKILL_DESTINATIONS.fabricImport.map((rel) => join2(projectRoot, rel));
   const results = [];
   for (const target of targets) {
-    results.push(await copyTextIdempotent("skill-import", source, target));
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill-import", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
   }
   results.push(...await installSkillRefFiles(projectRoot, "fabric-import"));
   return results;
@@ -279,6 +331,22 @@ async function installKnowledgeHintNarrowHook(projectRoot, _options = {}) {
   }
   return results;
 }
+async function installCitePolicyEvictHook(projectRoot, _options = {}) {
+  const source = await readTemplate(HOOK_CITE_EVICT_SCRIPT_TEMPLATE_REL);
+  const targets = HOOK_SCRIPT_DESTINATIONS.citePolicyEvict.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const result = await copyTextIdempotent("hook-cite-evict-script", source, target);
+    if (result.status === "written" && process.platform !== "win32") {
+      try {
+        chmodSync(target, 493);
+      } catch {
+      }
+    }
+    results.push(result);
+  }
+  return results;
+}
 async function installHookLibs(projectRoot, _options = {}) {
   const libTemplateDir = findTemplatePath(HOOK_LIB_TEMPLATE_DIR_REL);
   let libFiles;
@@ -725,6 +793,7 @@ export {
   installArchiveHintHook,
   installKnowledgeHintBroadHook,
   installKnowledgeHintNarrowHook,
+  installCitePolicyEvictHook,
   installHookLibs,
   mergeClaudeCodeHookConfig,
   mergeCodexHookConfig,

package/dist/{doctor-TTDTKOFJ.js → doctor-E26YO67D.js}

@@ -261,8 +261,12 @@ var doctorCommand = defineCommand({
       fixKnowledgeReport = await runDoctorFixKnowledge(resolution.target);
       report = fixKnowledgeReport.report;
     } else if (fix) {
-      fixReport = await runDoctorFix(resolution.target);
-      report = fixReport.report;
+      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);
     }
@@ -277,6 +281,8 @@ var doctorCommand = defineCommand({
         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);
     }

package/dist/index.js

@@ -11,10 +11,10 @@ import { defineCommand, runMain } from "citty";
 
 // src/commands/index.ts
 var allCommands = {
-  install: () => import("./install-OEBNSCS5.js").then((module) => module.default),
-  doctor: () => import("./doctor-TTDTKOFJ.js").then((module) => module.default),
+  install: () => import("./install-XCRX34CX.js").then((module) => module.default),
+  doctor: () => import("./doctor-E26YO67D.js").then((module) => module.default),
   serve: () => import("./serve-43JTEM3U.js").then((module) => module.default),
-  uninstall: () => import("./uninstall-VLLJG7JT.js").then((module) => module.default),
+  uninstall: () => import("./uninstall-Q7V55BXH.js").then((module) => module.default),
   config: () => import("./config-5CH4EJQ2.js").then((module) => module.default),
   "plan-context-hint": () => import("./plan-context-hint-CXTLNVSV.js").then((module) => module.default),
   // v2.0.0-rc.23 TASK-014 (F8c): S5 onboard-slot coverage. Used by the
@@ -26,7 +26,7 @@ var allCommands = {
 var main = defineCommand({
   meta: {
     name: "fabric",
-    version: "2.0.0-rc.30",
+    version: "2.0.0-rc.34",
     description: t("cli.main.description")
   },
   subCommands: allCommands

package/dist/{install-OEBNSCS5.js → install-XCRX34CX.js}

@@ -4,6 +4,7 @@ import {
 } from "./chunk-SRX7WZUG.js";
 import {
   installArchiveHintHook,
+  installCitePolicyEvictHook,
   installFabricArchiveSkill,
   installFabricImportSkill,
   installFabricReviewSkill,
@@ -18,7 +19,7 @@ import {
   writeCodexBootstrapManagedBlock,
   writeCursorBootstrapManagedBlock,
   writeFabricAgentsSnapshot
-} from "./chunk-PNRWNUFX.js";
+} from "./chunk-5N3KXIVI.js";
 import {
   detectClientSupports
 } from "./chunk-MF3OTILQ.js";
@@ -62,6 +63,7 @@ async function installHooks(target, _options = {}) {
   results.push(...await runStep(() => installArchiveHintHook(normalizedTarget)));
   results.push(...await runStep(() => installKnowledgeHintBroadHook(normalizedTarget)));
   results.push(...await runStep(() => installKnowledgeHintNarrowHook(normalizedTarget)));
+  results.push(...await runStep(() => installCitePolicyEvictHook(normalizedTarget)));
   results.push(...await runStep(() => installHookLibs(normalizedTarget)));
   results.push(await runSingleStep("claude-hook-config", () => mergeClaudeCodeHookConfig(normalizedTarget)));
   results.push(await runSingleStep("codex-hook-config", () => mergeCodexHookConfig(normalizedTarget)));
@@ -1348,7 +1350,7 @@ function readProjectName(target) {
   return basename(target);
 }
 function getCliVersion() {
-  return true ? "2.0.0-rc.30" : "unknown";
+  return true ? "2.0.0-rc.34" : "unknown";
 }
 function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));

package/dist/{uninstall-VLLJG7JT.js → uninstall-Q7V55BXH.js}

@@ -7,7 +7,7 @@ import {
   HOOK_SCRIPT_DESTINATIONS,
   SKILL_DESTINATIONS,
   fabricAgentsSnapshotPath
-} from "./chunk-PNRWNUFX.js";
+} from "./chunk-5N3KXIVI.js";
 import {
   detectClientSupports,
   resolveClients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "2.0.0-rc.30",
+  "version": "2.0.0-rc.34",
   "type": "module",
   "bin": {
     "fab": "dist/index.js",
@@ -20,8 +20,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "2.0.0-rc.30",
-    "@fenglimg/fabric-shared": "2.0.0-rc.30"
+    "@fenglimg/fabric-server": "2.0.0-rc.34",
+    "@fenglimg/fabric-shared": "2.0.0-rc.34"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/templates/hooks/cite-policy-evict.cjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * v2.0.0-rc.34 TASK-06 — cite-policy long-session evict sidecar.
+ *
+ * UserPromptSubmit hook (Claude Code only). Drives periodic cite-policy
+ * reminder injection in long sessions where attention decay erodes contract
+ * adherence (rc.32 Batch 1: 3.1% cite coverage baseline).
+ *
+ * Strategy: **turn-count window** (locked decision per rc.34 plan 2026-05-26;
+ * time-based and token-budget strategies pushed to rc.35). The hook maintains
+ * a per-session counter in `.fabric/.cache/cite-evict-state.json`; on each
+ * UserPromptSubmit, increment the counter and — when
+ * `turn_count % cite_evict_interval == 0` AND `cite_evict_interval > 0` —
+ * emit a compact cite-contract reminder via Claude Code's stdout JSON
+ * envelope (hookSpecificOutput.additionalContext, same channel as rc.33 W2
+ * knowledge-hint-broad reminder-to-context).
+ *
+ * Config: `cite_evict_interval` (number, default 0 = OFF, opt-in). Recommend
+ * 10-20 for active sessions; 5 for high-contract-criticality projects.
+ *
+ * State sidecar shape:
+ *   { session_id: string, turn_count: number }
+ *
+ * Session-boundary semantics: when incoming `session_id` (read from stdin
+ * payload) differs from sidecar's `session_id`, the counter resets to 1 (new
+ * session always starts at 1, never 0 — first turn is "turn 1" not "turn 0").
+ *
+ * Failure invariant: any error path (sidecar I/O failure, stdin parse error,
+ * config read failure) MUST end in silent exit 0. The hook never blocks user
+ * prompt submission on its own malfunction.
+ *
+ * Cross-client scope: Claude Code only (relies on hookSpecificOutput contract
+ * + UserPromptSubmit event registration). Codex CLI and Cursor don't have an
+ * equivalent event hook; cite-coverage telemetry there relies on Stop-hook
+ * fabric-hint and SessionStart knowledge-hint-broad (rc.33 W2 channel).
+ */
+
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const FABRIC_DIR_REL = ".fabric";
+const FABRIC_CONFIG_FILE = "fabric-config.json";
+const EVICT_STATE_FILE = join(".fabric", ".cache", "cite-evict-state.json");
+
+// Default OFF (opt-in). Mirrors hint_broad_cooldown_hours and
+// archive_hint_cooldown_hours convention of "feature exists but inert until
+// user enables it." Schema in packages/shared/src/schemas/fabric-config.ts
+// caps at sensible bounds (positive int).
+const DEFAULT_CITE_EVICT_INTERVAL = 0;
+
+/**
+ * Read .fabric/fabric-config.json#cite_evict_interval. Returns the parsed
+ * positive integer OR DEFAULT_CITE_EVICT_INTERVAL on any failure path
+ * (missing file, parse error, non-numeric value, negative). Mirrors the
+ * defensive config-read pattern in knowledge-hint-broad.cjs readBroadCooldownHours.
+ */
+function readEvictInterval(cwd) {
+  const configPath = join(cwd, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_CITE_EVICT_INTERVAL;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.cite_evict_interval;
+    if (typeof v === "number" && Number.isInteger(v) && v >= 0) {
+      return v;
+    }
+  } catch {
+    // ignore — defensive default
+  }
+  return DEFAULT_CITE_EVICT_INTERVAL;
+}
+
+/**
+ * Read prior state sidecar. Returns `null` on first-run or any failure;
+ * callers treat null as "no prior state" (caller will write fresh state
+ * with turn_count=1).
+ */
+function readEvictState(cwd) {
+  const path = join(cwd, EVICT_STATE_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (
+      parsed &&
+      typeof parsed.session_id === "string" &&
+      typeof parsed.turn_count === "number" &&
+      Number.isInteger(parsed.turn_count) &&
+      parsed.turn_count >= 0
+    ) {
+      return parsed;
+    }
+  } catch {
+    // ignore — corrupted sidecar is treated as no prior state
+  }
+  return null;
+}
+
+function writeEvictState(cwd, sessionId, turnCount) {
+  const path = join(cwd, EVICT_STATE_FILE);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ session_id: sessionId, turn_count: turnCount }));
+  } catch {
+    // best-effort — counter loss is acceptable, hook never blocks
+  }
+}
+
+/**
+ * Pure helper for unit-testing. Given current `turnCount` (post-increment)
+ * and `interval`, decide whether to emit the reminder.
+ *
+ * Contract:
+ *   - interval <= 0 → never emit (feature off)
+ *   - turnCount <= 0 → never emit (guard against bogus state)
+ *   - emit iff turnCount % interval === 0
+ *
+ * Examples:
+ *   evaluateCiteEvict(10, 10) → true  (10 % 10 === 0)
+ *   evaluateCiteEvict(20, 10) → true
+ *   evaluateCiteEvict(15, 10) → false
+ *   evaluateCiteEvict(5, 0)   → false (off)
+ *   evaluateCiteEvict(0, 10)  → false (no turns yet)
+ */
+function evaluateCiteEvict(turnCount, interval) {
+  if (typeof interval !== "number" || interval <= 0) return false;
+  if (typeof turnCount !== "number" || turnCount <= 0) return false;
+  return turnCount % interval === 0;
+}
+
+/**
+ * Build the cite-contract reminder body. Compact — under 10 lines. The
+ * fully-specified contract lives in `.fabric/AGENTS.md` Cite policy section;
+ * the reminder is a tactical re-anchor, not the canonical reference.
+ *
+ * Returns a multi-line string ready for hookSpecificOutput.additionalContext.
+ */
+function renderReminder(turnCount, interval) {
+  return [
+    `[fabric cite-evict] long-session reminder (turn ${turnCount}, interval ${interval}):`,
+    "Before edit / decide / propose plan, write KB: <id> (<≤8字 用法>) [planned|recalled|chained-from <id>|dismissed:<reason>] OR KB: none [<reason>].",
+    "Verify [recalled] via fab_plan_context → fab_get_knowledge_sections two-step (no fabricated ids).",
+    "decisions/pitfalls cite MUST end with contract: → <operator> [<operator>...] where operator ∈ {edit:<glob> !edit:<glob> require:<symbol> forbid:<symbol> skip:<reason>}.",
+    "skip reasons: sequencing | conditional | semantic | aesthetic | architectural | other:<text>.",
+    "KB: none sentinels: [no-relevant] (queried but nothing matched) | [not-applicable] (pure exploration / read-only / user Q&A).",
+    "Audit: fab doctor --cite-coverage — this rule does not block work, only records.",
+  ].join("\n");
+}
+
+/**
+ * Detect Claude Code via CLAUDE_PROJECT_DIR env. Same single-bit signal used
+ * by knowledge-hint-broad.cjs rc.33 W4 review-fix (Gemini High-1). Codex /
+ * Cursor don't set this var.
+ */
+function isClaudeCode() {
+  return (
+    typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
+    process.env.CLAUDE_PROJECT_DIR.length > 0
+  );
+}
+
+async function readStdinJson() {
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      try {
+        resolve(JSON.parse(buffer));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on("error", () => resolve(null));
+    // Defensive timeout: if stdin never closes (host bug), give up after 1s.
+    setTimeout(() => resolve(null), 1000).unref();
+  });
+}
+
+async function main(env) {
+  try {
+    const cwd =
+      (env && typeof env.cwd === "string" && env.cwd) ||
+      process.env.CLAUDE_PROJECT_DIR ||
+      process.cwd();
+
+    const interval = readEvictInterval(cwd);
+    if (interval <= 0) {
+      return; // feature off — silent exit
+    }
+
+    // Skip Claude Code-specific stdout envelope on Codex/Cursor. Counter
+    // bookkeeping also skipped — there's no fire path on those clients.
+    if (!isClaudeCode() && !(env && env.forceClaudeCode === true)) {
+      return;
+    }
+
+    // Read stdin payload to learn session_id. Tests inject env.payload to
+    // bypass the stdin read; production reads JSON envelope from stdin.
+    const payload = env && env.payload !== undefined ? env.payload : await readStdinJson();
+    const sessionId =
+      payload && typeof payload.session_id === "string" && payload.session_id.length > 0
+        ? payload.session_id
+        : "anonymous";
+
+    const prior = readEvictState(cwd);
+    const turnCount = prior && prior.session_id === sessionId ? prior.turn_count + 1 : 1;
+    writeEvictState(cwd, sessionId, turnCount);
+
+    if (!evaluateCiteEvict(turnCount, interval)) {
+      return; // not on a window boundary — silent
+    }
+
+    const reminder = renderReminder(turnCount, interval);
+    const out = (env && env.stdio && env.stdio.stdout) || process.stdout;
+    try {
+      const envelope = {
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit",
+          additionalContext: reminder,
+        },
+      };
+      out.write(`${JSON.stringify(envelope)}\n`);
+    } catch {
+      // best-effort
+    }
+  } catch {
+    // Silent — never block user prompt on hook failure.
+  }
+}
+
+module.exports = {
+  main,
+  evaluateCiteEvict,
+  renderReminder,
+  readEvictInterval,
+  readEvictState,
+  writeEvictState,
+};
+
+if (require.main === module) {
+  main();
+}

package/templates/hooks/configs/claude-code.json

@@ -32,6 +32,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cite-policy-evict.cjs"
+          }
+        ]
+      }
     ]
   }
 }

package/templates/hooks/fabric-hint.cjs

@@ -1018,9 +1018,13 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
   }
 
   // Cooldown gate — short-circuit when we just nagged.
+  // rc.34 TASK-01 + review-fix (Gemini P1): future-stamped lastEmit (backward
+  // clock skew) bypasses cooldown — treats sidecar as "expired" so the gate
+  // heals on the next invocation instead of waiting (cooldown + |skew|).
   if (
     typeof lastEmitMs === "number" &&
     Number.isFinite(lastEmitMs) &&
+    nowMs >= lastEmitMs &&
     nowMs - lastEmitMs < cooldownDays * MS_PER_DAY
   ) {
     return null;
@@ -1733,7 +1737,13 @@ function main(env, stdio) {
     const cooldownMs = readCooldownHours(cwd) * MS_PER_HOUR;
     const cache = readShownCache(cwd);
     const lastShown = cache[result.signal];
-    if (typeof lastShown === "number" && nowMs - lastShown < cooldownMs) {
+    // rc.34 TASK-01 + review-fix (Gemini P1): future-stamped lastShown
+    // (backward clock skew) bypasses cooldown — sidecar treated as expired.
+    if (
+      typeof lastShown === "number" &&
+      nowMs >= lastShown &&
+      nowMs - lastShown < cooldownMs
+    ) {
       return; // Still in cooldown — silent.
     }