@fenglimg/fabric-cli 2.0.0-rc.33 → 2.0.0-rc.35

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: fabric 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.
     }
 

package/templates/hooks/knowledge-hint-broad.cjs

@@ -61,6 +61,7 @@ const { dirname, join } = require("node:path");
 // (TASK-002). Variant is resolved ONCE per main() invocation via
 // readFabricLanguage(cwd) and threaded into renderBanner — no fs in render path.
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
+const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
@@ -415,12 +416,11 @@ const MATURITY_DRAFT = "draft";
  * Spawn `fabric plan-context-hint --all` and return parsed JSON. Returns
  * null on any failure (ENOENT, non-zero exit, malformed JSON). Never throws.
  *
- * spawn strategy: try `fabric` first (user-PATH install) then `fab` (the
- * alternate bin name shipped by @fenglimg/fabric-cli). If neither is on PATH,
- * return null — the hook stays silent rather than nagging about install state.
+ * If `fabric` is not on PATH, return null — the hook stays silent rather
+ * than nagging about install state.
  */
 function invokePlanContextHint(cwd) {
-  const candidates = ["fabric", "fab"];
+  const candidates = ["fabric"];
   // rc.31 NEW-6: capture the last meaningful failure so we can surface it on
   // stderr before fail-open. Without this, hook silently swallows backend
   // crashes (e.g. agents_meta_invalid → plan-context-hint exits with stderr
@@ -439,7 +439,7 @@ function invokePlanContextHint(cwd) {
       continue; // spawn throw (extremely rare) — try next candidate
     }
     // ENOENT surfaces as error on the result object. Skip silently for ENOENT
-    // (bin not installed is expected for `fabric` when only `fab` is shipped).
+    // (bin not installed is the only legitimate reason to bail).
     if (res.error) {
       if (res.error.code !== "ENOENT") {
         lastFailure = { bin, reason: String(res.error.message || res.error.code || res.error) };
@@ -708,6 +708,14 @@ function main(env, stdio) {
       const lastEmitMs = readBroadLastEmit(cwd);
       if (
         typeof lastEmitMs === "number" &&
+        // rc.34 TASK-01 + review-fix (Gemini P1): when lastEmit is in the
+        // FUTURE relative to now (backward clock skew — NTP sync /
+        // suspend-wake / TZ change), the gate fires immediately. Otherwise
+        // standard cooldown check. Math.max(0, …) was a no-op (silent for
+        // cooldown + |skew| under both formulations); this guard actually
+        // heals the skew on the next invocation by treating future-stamped
+        // sidecar as "expired."
+        nowMs >= lastEmitMs &&
         nowMs - lastEmitMs < cooldownHours * MS_PER_HOUR
       ) {
         return; // still in cooldown — silent
@@ -730,6 +738,26 @@ function main(env, stdio) {
         ? { ...payload, entries: payload.entries.slice(0, topK) }
         : payload;
 
+    // rc.35 TASK-06 (P0-10.b): summary-fallback substitution. Entries whose
+    // description.summary equals stable_id render as "<id> · <id>" and the
+    // AI skips fetching them; the fallback reads `## Summary` from the
+    // entry's .md file and swaps in the first paragraph. Best-effort —
+    // failure leaves the original opaque summary untouched.
+    let resolvedPayload = slicedPayload;
+    try {
+      if (slicedPayload && Array.isArray(slicedPayload.entries)) {
+        const resolvedEntries = resolveOpaqueSummaries(
+          slicedPayload.entries,
+          cwd,
+          typeof slicedPayload.revision_hash === "string" ? slicedPayload.revision_hash : "",
+        );
+        resolvedPayload = { ...slicedPayload, entries: resolvedEntries };
+      }
+    } catch {
+      // resolveOpaqueSummaries swallows its own errors; this catch is belt
+      // + suspenders for any unexpected exception from the lib layer.
+    }
+
     // rc.8 underseed self-check: decide whether to surface the one-line
     // `/fabric-import` recommendation banner alongside the broad summary.
     const recommendImport = shouldRecommendImport(cwd);
@@ -741,7 +769,7 @@ function main(env, stdio) {
     // for the agent's working memory. rc.33 W2-5 reintroduces an opt-in
     // hours-based cooldown via fabric-config (see gate above).
     const summaryMaxLen = readSummaryMaxLen(cwd);
-    const lines = renderSummary(slicedPayload, summaryMaxLen);
+    const lines = renderSummary(resolvedPayload, summaryMaxLen);
 
     if (recommendImport) {
       // rc.16 TASK-003: resolve fabric_language ONCE per invocation (only when

package/templates/hooks/knowledge-hint-narrow.cjs

@@ -75,6 +75,12 @@ const {
 } = require("node:fs");
 const { dirname, join } = require("node:path");
 
+// rc.35 TASK-06 (P0-10.b): summary-fallback. Substitutes opaque entries
+// (where description.summary === stable_id) with a snippet read from the
+// entry's .md `## Summary` section. Caches results in
+// `.fabric/.cache/summary-fallback.json` keyed by revision_hash.
+const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
+
 // -----------------------------------------------------------------------------
 // CONSTANTS
 // -----------------------------------------------------------------------------
@@ -95,6 +101,14 @@ const DEFAULT_SUMMARY_MAX_LEN = 80;
 const EDIT_COUNTER_DIR_REL = join(".fabric", ".cache");
 const EDIT_COUNTER_FILE = "edit-counter";
 
+// rc.35 TASK-07 (P0-2): events.jsonl path. PreToolUse Edit fires append a
+// `edit_intent_checked` event (ledger_source: 'hook') so doctor cite-
+// coverage's editsTouched metric sees actual edit signals. Without this
+// signal the entire cite-policy contract validation is structurally inert
+// (rc.30 audit P0-2: 18582 turns / 240 edits / 0 events).
+const EVENTS_LEDGER_DIR_REL = ".fabric";
+const EVENTS_LEDGER_FILE = "events.jsonl";
+
 // rc.6 TASK-023 (E6): hint-silence-counter sidecar — companion to the
 // edit-counter above. Where edit-counter records every PreToolUse fire
 // (numerator-agnostic), the silence-counter records only those fires that
@@ -317,6 +331,72 @@ function extractPaths(toolInput) {
  *     array. The fire-count signal is preserved; the activity overview
  *     just contributes nothing from those lines.
  */
+/**
+ * rc.35 TASK-07 (P0-2): append one `edit_intent_checked` event per touched
+ * path to `.fabric/events.jsonl`. Carries `ledger_source: 'hook'` so doctor
+ * cite-coverage can distinguish hook-originated edit signals from
+ * AI/human-originated `appendLedgerEntry` calls.
+ *
+ * Best-effort:
+ *   - Skips silently when `.fabric/` does not exist (project not init'd).
+ *   - Skips silently when paths is empty (counter signal is preserved by
+ *     the sibling appendEditCounter call; cite-coverage only cares about
+ *     non-empty path events).
+ *   - ANY error (mkdir, append, JSON throw) is swallowed — the hook must
+ *     remain non-blocking per the rc.6 contract.
+ *
+ * Atomicity:
+ *   - One JSON line per path. Append on small writes (< PIPE_BUF, ~4KB on
+ *     POSIX) is atomic at the OS level, so concurrent PreToolUse fires
+ *     from parallel sessions interleave cleanly without partial writes.
+ */
+function appendEditIntentToLedger(projectRoot, now, paths, toolName) {
+  try {
+    const fabricDir = join(projectRoot, EVENTS_LEDGER_DIR_REL);
+    // No .fabric/ → project not initialised. Bail before any write.
+    if (!existsSync(fabricDir)) return;
+    const { isAbsolute: pathIsAbsolute, relative: pathRelative } = require("node:path");
+    const pathList = Array.isArray(paths)
+      ? paths
+          .filter((p) => typeof p === "string" && p.length > 0)
+          .map((p) => {
+            if (pathIsAbsolute(p)) {
+              const rel = pathRelative(projectRoot, p);
+              return rel.startsWith("..") ? null : rel;
+            }
+            // Already-relative paths: drop ones that escape the project tree.
+            return p.startsWith("..") ? null : p;
+          })
+          .filter((p) => typeof p === "string" && p.length > 0)
+          // Use forward slashes for cross-platform consistency on disk.
+          .map((p) => p.split(/[\\/]/).join("/"))
+      : [];
+    if (pathList.length === 0) return;
+    const tsMs = now instanceof Date ? now.getTime() : Number(now);
+    const ledgerEntryId = `hook:${randomUUID()}`;
+    const intent = typeof toolName === "string" && toolName.length > 0 ? toolName : "edit";
+    const lines = pathList
+      .map((p) => JSON.stringify({
+        kind: "fabric-event",
+        id: `event:${randomUUID()}`,
+        ts: tsMs,
+        schema_version: 1,
+        event_type: "edit_intent_checked",
+        path: p,
+        compliant: true,
+        intent,
+        ledger_entry_id: ledgerEntryId,
+        ledger_source: "hook",
+        matched_rule_context_ts: null,
+        window_ms: 0,
+      }))
+      .join("\n") + "\n";
+    appendFileSync(join(fabricDir, EVENTS_LEDGER_FILE), lines, "utf8");
+  } catch {
+    // Silent — events ledger failure must never block the edit.
+  }
+}
+
 function appendEditCounter(projectRoot, now, paths) {
   try {
     const dir = join(projectRoot, EDIT_COUNTER_DIR_REL);
@@ -1079,6 +1159,11 @@ function main(env, stdio) {
     }
     if (!(env && env.skipCounter === true)) {
       appendEditCounter(cwd, now, paths);
+      // rc.35 TASK-07 (P0-2): mirror the edit-counter sidecar into the
+      // events.jsonl ledger so doctor cite-coverage's editsTouched metric
+      // sees actual edit signals. Best-effort — failure is swallowed inside
+      // appendEditIntentToLedger and does not block the hook.
+      appendEditIntentToLedger(cwd, now, paths, toolName);
     }
 
     // E2 path is conditional on a recognized tool + extractable paths.
@@ -1237,7 +1322,21 @@ function main(env, stdio) {
     }
 
     const summaryMaxLen = readSummaryMaxLen(cwd);
-    const lines = renderSummary({ ...cliPayload, entries: dedupDecision.filtered }, summaryMaxLen);
+    // rc.35 TASK-06 (P0-10.b): substitute opaque summaries before render.
+    // Same lib used by the broad hook — opaque entries seen from both call
+    // sites share a single .fabric/.cache/summary-fallback.json file.
+    // Best-effort — any failure leaves the original opaque summary intact.
+    let resolvedEntries = dedupDecision.filtered;
+    try {
+      resolvedEntries = resolveOpaqueSummaries(
+        dedupDecision.filtered,
+        cwd,
+        currentRevisionHash,
+      );
+    } catch {
+      // resolveOpaqueSummaries swallows its own errors; defensive catch.
+    }
+    const lines = renderSummary({ ...cliPayload, entries: resolvedEntries }, summaryMaxLen);
     if (lines.length === 0) return;
 
     // Stderr: human-facing breadcrumb + legacy contract.
@@ -1294,6 +1393,10 @@ module.exports = {
   renderSummary,
   truncateSummary,
   formatEntryLine,
+  // rc.35 TASK-07 (P0-2): cite-infrastructure wire-up. Exported so the
+  // integration test can drive the writer directly without standing up the
+  // entire PreToolUse main() flow.
+  appendEditIntentToLedger,
   // rc.6 TASK-021 (E3) — session-hints cache exports for tests / future
   // consumers (TASK-023 silence-counter telemetry will reuse the same
   // session-id resolution + cache shape).
@@ -1323,6 +1426,8 @@ module.exports = {
     EDIT_COUNTER_FILE,
     HINT_SILENCE_COUNTER_DIR_REL,
     HINT_SILENCE_COUNTER_FILE,
+    EVENTS_LEDGER_DIR_REL,
+    EVENTS_LEDGER_FILE,
     EDIT_TOOL_NAMES,
     SESSION_HINTS_DIR_REL,
     SESSION_HINTS_FILE_PREFIX,