@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.10

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

@@ -66,7 +66,6 @@
 const { spawnSync } = require("node:child_process");
 const { createHash, randomUUID } = require("node:crypto");
 const {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -76,15 +75,34 @@ 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");
+// KT-GLD-0006: the rc.35 opaque-summary substitution (resolveOpaqueSummaries) is
+// retired — the write-time mechanical floor in extractKnowledge prevents
+// degenerate summaries at the source, so the narrow hook no longer band-aids them.
 // v2.0.0-rc.37 NEW-17: shared sidecar I/O for the plan-context-hint result
 // cache (skips a redundant CLI cold-start spawn when the same path-set is
 // re-edited within a session and the knowledge graph hasn't changed).
-const { readJsonState, writeJsonState } = require("./lib/state-store.cjs");
+const { readJsonStateAsync, writeJsonStateAsync } = require("./lib/state-store.cjs");
+// W1-01 (ISS-011): the PreToolUse hook is the highest-frequency, most
+// concurrency-exposed write surface in Fabric. Multi-window edits spawn
+// concurrent hook processes that all append to the SAME non-session-scoped
+// ledger/counter files; a bare appendFileSync can interleave a partial write
+// and corrupt a line. Route every shared-file append through the advisory-lock
+// primitive (drop-on-contention, best-effort — matches injection-log).
+const { appendLockedLine } = require("./lib/injection-log.cjs");
+// lifecycle-refactor W1-T2: client discriminator for the hook_surface_emitted
+// event (schema requires the `client` enum). Mirrors the broad hook's import.
+// v2.2 dual-sink (Goal A): + emitDualSink (PreToolUse two-channel emit).
+const { detectClient, emitDualSink } = require("./lib/client-adapter.cjs");
+// v2.2 dual-sink (Goal A / D4 + C5): human-output gate. On a narrow HIT the human
+// systemMessage is gated by nudge_mode (a miss is already a silent early-return
+// above); the AI additionalContext is emitted regardless (flow ⊥ observation).
+// Optional require so an old install degrades to "always emit human".
+let nudgePolicy = null;
+try {
+  nudgePolicy = require("./lib/nudge-policy.cjs");
+} catch {
+  // Lib missing (old install) — human sink always emits (legacy behavior).
+}
 // v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
 // resolved-bindings snapshot. Store-aware hint surfaces the write-target store
 // for the edited file WITHOUT re-resolving or walking store trees. Best-effort.
@@ -233,8 +251,8 @@ function readPayload(rawStdin) {
   } catch (e) {
     // v2.0.0-rc.29 REVIEW (codex LOW-1): apply BUG-L1's malformed-input
     // diagnostic uniformly across hook scripts. fabric-hint.cjs got the stderr
-    // trace in TASK-008; without this matching write here, a broken Codex /
-    // Cursor host payload silently kills the narrow hint with no operator
+    // trace in TASK-008; without this matching write here, a broken Codex
+    // host payload silently kills the narrow hint with no operator
     // signal at all. Best-effort: a failed stderr write must not throw upward
     // (hook contract — never crash the host's edit pipeline).
     try {
@@ -248,32 +266,27 @@ function readPayload(rawStdin) {
 }
 
 /**
- * Extract the tool name from a hook payload. Clients differ in casing /
- * field placement; we probe the conventional shapes:
+ * Extract the tool name from a hook payload. Both supported clients use the
+ * same shape:
  *   - Claude Code:  { tool_name, tool_input: { ... } }
  *   - Codex CLI:    { tool_name, tool_input: { ... } } (mirrors Claude)
- *   - Cursor:       { tool, input: { ... } } (legacy variant)
  * Returns null when no recognizable shape is present.
  */
 function extractToolName(payload) {
   if (!payload || typeof payload !== "object") return null;
   if (typeof payload.tool_name === "string") return payload.tool_name;
-  if (typeof payload.tool === "string") return payload.tool;
   return null;
 }
 
 /**
- * Extract the tool_input object from a hook payload, accepting both the
- * `tool_input` (Claude/Codex) and `input` (Cursor) conventions.
+ * Extract the tool_input object from a hook payload (the `tool_input`
+ * convention shared by Claude Code and Codex CLI).
  */
 function extractToolInput(payload) {
   if (!payload || typeof payload !== "object") return null;
   if (payload.tool_input && typeof payload.tool_input === "object") {
     return payload.tool_input;
   }
-  if (payload.input && typeof payload.input === "object") {
-    return payload.input;
-  }
   return null;
 }
 
@@ -283,8 +296,8 @@ function extractToolInput(payload) {
  *   - bulk variant:      { file_paths: ["src/foo.ts", "src/bar.ts"] }
  *   - MultiEdit:         { file_path: "...", edits: [{file_path?, ...}, ...] }
  *     (Claude Code's MultiEdit currently issues per-edit operations against
- *     a single `file_path`; older drafts and Cursor's variant carried
- *     per-edit `file_path`. We accept both to be defensive.)
+ *     a single `file_path`; older drafts carried per-edit `file_path`. We
+ *     accept both to be defensive.)
  *
  * Returns a deduped array of strings — empty when no path is recognizable.
  * Order: first occurrence wins (stable across re-renders of the same payload).
@@ -427,7 +440,7 @@ function appendEditIntentToLedger(projectRoot, now, paths, toolName, sessionId)
         window_ms: 0,
       }))
       .join("\n") + "\n";
-    appendFileSync(join(fabricDir, EVENTS_LEDGER_FILE), lines, "utf8");
+    appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), lines);
   } catch {
     // Silent — events ledger failure must never block the edit.
   }
@@ -471,7 +484,7 @@ function appendEditCounter(projectRoot, now, paths) {
           .filter((p) => typeof p === "string" && p.length > 0)
       : [];
     const line = JSON.stringify({ ts: iso, paths: pathList });
-    appendFileSync(file, `${line}\n`, "utf8");
+    appendLockedLine(file, `${line}\n`);
   } catch {
     // Silent — sidecar failure must never block the edit.
   }
@@ -501,7 +514,7 @@ function appendHintSilenceCounter(projectRoot, now) {
       mkdirSync(dir, { recursive: true });
     }
     const iso = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
-    appendFileSync(file, `${iso}\n`, "utf8");
+    appendLockedLine(file, `${iso}\n`);
   } catch {
     // Silent — sidecar failure must never block the edit.
   }
@@ -514,7 +527,7 @@ function appendHintSilenceCounter(projectRoot, now) {
 /**
  * Resolve the session id used to key the cache file. Priority:
  *   1. payload.session_id (string, non-empty) — preferred; threads through
- *      from the client hook payload (Claude Code / Codex CLI / Cursor).
+ *      from the client hook payload (Claude Code / Codex CLI).
  *   2. process.env.FABRIC_SESSION_ID — environment fallback.
  *   3. SYNTHETIC_SESSION_ID — a process-lifetime UUID, generated lazily so
  *      tests can stub it (see resetSyntheticSessionId).
@@ -856,9 +869,9 @@ function pathSetKey(paths) {
 
 // Returns the cached cliPayload for `paths` iff the cache's meta token matches
 // the current knowledge-graph freshness, else null (caller spawns the CLI).
-function readNarrowResultCache(cwd, sessionId, paths, metaToken) {
+async function readNarrowResultCache(cwd, sessionId, paths, metaToken) {
   if (metaToken === null) return null;
-  const cache = readJsonState(
+  const cache = await readJsonStateAsync(
     cwd,
     narrowResultCacheFileName(sessionId),
     (parsed) => parsed && typeof parsed === "object" && parsed.results && typeof parsed.results === "object",
@@ -871,10 +884,10 @@ function readNarrowResultCache(cwd, sessionId, paths, metaToken) {
 // Persist `cliPayload` under the path-set key. Resets the map when the meta
 // token changed (stale graph) and caps the map size (FIFO-ish: drop oldest
 // insertion-order keys). Best-effort — never throws.
-function writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload) {
+async function writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload) {
   if (metaToken === null) return;
   const fileName = narrowResultCacheFileName(sessionId);
-  const prior = readJsonState(
+  const prior = await readJsonStateAsync(
     cwd,
     fileName,
     (parsed) => parsed && typeof parsed === "object" && parsed.results && typeof parsed.results === "object",
@@ -888,7 +901,7 @@ function writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload) {
       delete results[stale];
     }
   }
-  writeJsonState(cwd, fileName, { meta_token: metaToken, results });
+  await writeJsonStateAsync(cwd, fileName, { meta_token: metaToken, results });
 }
 
 // -----------------------------------------------------------------------------
@@ -1163,7 +1176,15 @@ function formatEntryLine(entry, maxLen) {
   const maturity = entry.maturity || "unknown";
   const summary = truncateSummary(entry.summary, maxLen);
   const tail = summary.length > 0 ? ` ${summary}` : "";
-  return `  [${id}] (${type}/${maturity})${tail}`;
+  // lifecycle-refactor W3-T2 (§7 图谱消费 / §5 hook 沿 related 二阶召回): mark entries
+  // pulled in by a surfaced entry's one-hop `related` graph edge with their source
+  // provenance. Omitted for ordinarily-ranked entries — no fake graph annotation
+  // is ever synthesized (graph-empty honesty).
+  const provenance =
+    typeof entry.related_to === "string" && entry.related_to.length > 0
+      ? ` (related-to-${entry.related_to})`
+      : "";
+  return `  [${id}] (${type}/${maturity})${tail}${provenance}`;
 }
 
 function readSummaryMaxLen(projectRoot) {
@@ -1229,7 +1250,7 @@ function renderSummary(payload, maxLen) {
 // Main — invoked as a CLI (require.main === module) and in-process by tests
 // -----------------------------------------------------------------------------
 
-function main(env, stdio) {
+async function main(env, stdio) {
   try {
     const cwd = (env && env.cwd) || process.cwd();
     const now = (env && env.now) || new Date();
@@ -1331,14 +1352,14 @@ function main(env, stdio) {
       const useResultCache = !(env && env.skipResultCache === true);
       const metaToken = useResultCache ? metaFreshnessToken(cwd) : null;
       const cached = useResultCache
-        ? readNarrowResultCache(cwd, sessionId, paths, metaToken)
+        ? await readNarrowResultCache(cwd, sessionId, paths, metaToken)
         : null;
       if (cached !== null) {
         cliPayload = cached;
       } else {
         cliPayload = invokePlanContextHint(cwd, paths);
         if (useResultCache && cliPayload !== null && cliPayload !== undefined) {
-          writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload);
+          await writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload);
         }
       }
     }
@@ -1469,21 +1490,10 @@ function main(env, stdio) {
     }
 
     const summaryMaxLen = readSummaryMaxLen(cwd);
-    // 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);
+    // KT-GLD-0006: the rc.35 opaque-summary runtime substitution is retired — the
+    // write-time mechanical floor in extractKnowledge prevents degenerate summaries
+    // at the source, so the narrow hook renders the description summary as-is.
+    const lines = renderSummary({ ...cliPayload, entries: dedupDecision.filtered }, summaryMaxLen);
     if (lines.length === 0) return;
 
     // v2.1.0-rc.1 P4 (F4/S63): store-aware hint — append the write-target store
@@ -1505,39 +1515,76 @@ function main(env, stdio) {
       }
     }
 
-    // Stderr: human-facing breadcrumb + legacy contract.
-    for (const line of lines) {
-      err.write(`${line}\n`);
+    // v2.2 dual-sink (Goal A / C5): a narrow HIT emits BOTH channels. The human
+    // systemMessage is gated by nudge_mode (a MISS already returned silently far
+    // above — narrow.length===0 / gate-skip / dedup-filter); the AI
+    // additionalContext is emitted regardless (gated only by reminder_to_context),
+    // preserving flow ⊥ observation (D5). emitDualSink shapes the protocol per
+    // client (CC/Codex camelCase nested; unknown → stderr).
+    const text = lines.join("\n");
+    const humanGate =
+      nudgePolicy !== null
+        ? nudgePolicy.resolveHumanSink(cwd, "pre_tool_use", { hit: true })
+        : { emitHuman: true };
+    const human = humanGate.emitHuman ? text : null;
+    const ai = readReminderToContext(cwd) ? text : null;
+    if (!(env && env.skipStdout === true)) {
+      emitDualSink(
+        { human, ai },
+        { client: detectClient(), eventName: "PreToolUse", streams: { stdout: out, stderr: err } },
+      );
+    } else if (human !== null) {
+      // skipStdout test seam: still surface the human breadcrumb to stderr.
+      err.write(`${text}\n`);
     }
 
-    // v2.0.0-rc.33 W2-6 (P0-7): stdout JSON envelope. When
-    // hint_reminder_to_context is true (default), serialize the same banner
-    // body as Claude Code's PreToolUse hookSpecificOutput shape so the model
-    // receives the reminder IN-CONTEXT (rc.32 baseline cite-coverage 3.1%
-    // root cause: reminders never entered model context). PreToolUse hook
-    // contract: stdout JSON with hookSpecificOutput.additionalContext is
-    // injected into the model's context window; the hook DOES NOT block the
-    // edit (additionalContext is informational, not a permissionDecision).
-    // v2.0.0-rc.33 W4 review-fix (gemini High-1): CC-specific stdout envelope.
-    // See knowledge-hint-broad.cjs companion for rationale — CLAUDE_PROJECT_DIR
-    // is the CC presence signal; Codex CLI / Cursor don't set it.
-    const _isClaudeCode =
-      typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
-      process.env.CLAUDE_PROJECT_DIR.length > 0;
-    if (!(env && env.skipStdout === true) && _isClaudeCode && readReminderToContext(cwd)) {
-      try {
-        const envelope = {
-          hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            additionalContext: lines.join("\n"),
-          },
+    // lifecycle-refactor W1-T2: hook_surface_emitted — record WHICH narrow-scoped
+    // stable_ids this PreToolUse fire surfaced into the edit, so doctor can join
+    // surfaced→edited (this is the join's LEFT half; the edit_intent_checked event
+    // appended above supplies the edited path / RIGHT half, keyed on the same
+    // real payload session_id). Fires only after all gates passed and lines were
+    // rendered (so it tracks genuinely-surfaced hints, never bloat). Best-effort,
+    // never blocks the edit (KT-DEC-0007); the schema's `client` is a required
+    // enum, so skip when the client is undetectable rather than emit an invalid
+    // row. Mirrors the broad SessionStart emit (knowledge-hint-broad.cjs).
+    try {
+      const surfaceClient = detectClient();
+      const fabricDir = join(cwd, FABRIC_DIR_REL);
+      if (surfaceClient !== undefined && existsSync(fabricDir)) {
+        const renderedIds = dedupDecision.filtered
+          .map((e) => (e && typeof e.id === "string" ? e.id : null))
+          .filter((x) => x !== null);
+        const realSessionId =
+          payload &&
+          typeof payload === "object" &&
+          typeof payload.session_id === "string" &&
+          payload.session_id.length > 0
+            ? payload.session_id
+            : null;
+        const surfaceEvent = {
+          kind: "fabric-event",
+          id: `event:${randomUUID()}`,
+          ts: nowMs,
+          schema_version: 1,
+          ...(realSessionId ? { session_id: realSessionId } : {}),
+          event_type: "hook_surface_emitted",
+          hook_name: "knowledge-hint-narrow",
+          client: surfaceClient,
+          target_channel: "stderr",
+          rendered_ids: renderedIds,
+          delivery_status: "delivered",
         };
-        out.write(`${JSON.stringify(envelope)}\n`);
-      } catch {
-        // Best-effort — stderr is the durable contract.
+        appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), JSON.stringify(surfaceEvent) + "\n");
       }
+    } catch {
+      // best-effort telemetry — never block the edit
     }
 
+    // v2.2 dual-sink (Goal A): the legacy rc.33 W2-6 CC-only stdout envelope is
+    // replaced by emitDualSink above (which carries BOTH the human systemMessage
+    // and the AI additionalContext, shaped per client). reminder_to_context still
+    // gates whether the AI sink is populated (see `ai` above).
+
     // v2.0.0-rc.33 W2-5: record successful emit for cooldown gate.
     if (cooldownHours > 0 && !(env && env.skipCooldownWrite === true)) {
       writeNarrowLastEmit(cwd, nowMs);
@@ -1625,6 +1672,5 @@ if (require.main === module) {
   main(
     { cwd: process.cwd(), now: new Date(), stdin: stdinRaw },
     { stderr: process.stderr },
-  );
-  process.exit(0);
+  ).finally(() => process.exit(0));
 }

package/templates/hooks/lib/banner-i18n.cjs

@@ -238,6 +238,37 @@ const STRINGS = {
     "zh-CN-hybrid": () => "   是否调 `fabric doctor --lint` 看看知识库健康度?",
   },
 
+  // ---- Stop hook: session-activity status (human trust anchor) -------------
+  // Observability grill (a): a no-signal Stop currently returns SILENT — the
+  // human only ever hears from Fabric when there is a nudge to act on, never a
+  // "here is what I did" status, which reads as "Fabric does nothing". This line
+  // is the trust anchor: session-scoped counts from events.jsonl (edits +
+  // knowledge pulls by the AI + pending backlog). Cadence is gated by nudge_mode
+  // (silent=never, normal=once/session, verbose=every turn) at the call site.
+  // params: { edits, consumed, pending } — all numbers.
+  statusLine: {
+    "zh-CN": (p) =>
+      `📋 Fabric 本会话 · 改 ${p.edits} 文件 · AI 取用知识 ${p.consumed} 次 · 待审 ${p.pending} 条`,
+    en: (p) =>
+      `📋 Fabric this session · ${p.edits} files edited · ${p.consumed} KB pulls by AI · ${p.pending} pending`,
+    "zh-CN-hybrid": (p) =>
+      `📋 Fabric 本会话 · 改 ${p.edits} 文件 · AI 取用知识 ${p.consumed} 次 · 待审 ${p.pending} 条`,
+  },
+
+  // ---- Stop hook: nudge_mode tier guidance (discoverability) ---------------
+  // Observability grill (Q4): users did not know the human-channel volume knob
+  // (nudge_mode) exists, so they assumed the hooks never surface to humans. This
+  // line names the current tier and the levers. params: { mode } — current
+  // nudge_mode. Protected token: nudge_mode + the config path verbatim.
+  statusTier: {
+    "zh-CN": (p) =>
+      `   音量 ${p.mode}:verbose=每步可见 / silent=静音(.fabric/fabric-config.json nudge_mode)`,
+    en: (p) =>
+      `   volume ${p.mode}: verbose=show every step / silent=mute (.fabric/fabric-config.json nudge_mode)`,
+    "zh-CN-hybrid": (p) =>
+      `   音量 ${p.mode}:verbose=每步可见 / silent=静音(.fabric/fabric-config.json nudge_mode)`,
+  },
+
   // ---- Broad hook: import recommendation ------------------------------------
   // Source (zh-CN): knowledge-hint-broad.cjs:262
   //   "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?"

package/templates/hooks/lib/bindings-snapshot-reader.cjs

@@ -4,37 +4,50 @@
 // Hooks are a REMINDER layer (KT-DEC-0007) and must never block. They are also
 // FORBIDDEN from re-resolving stores or walking `.fabric` store trees directly
 // — a hook reads ONLY the CLI-pre-generated snapshot at
-// `~/.fabric/state/bindings/<project_id>_resolved.json` (written by P3
+// `~/.fabric/state/bindings/<workspace_binding_id>_resolved.json` (written by P3
 // install/sync/bind). This keeps the resolver logic in one place (the CLI) and
 // keeps hooks a thin, store-unaware-by-construction projection. Missing /
 // unreadable / malformed snapshot → null (harmless degrade; the hook proceeds
 // without store labels). Zero-dep CJS so it inline-loads at hook runtime.
 
-const { existsSync, readFileSync } = require("node:fs");
+const { existsSync, readFileSync, readdirSync, statSync } = require("node:fs");
 const { join } = require("node:path");
 const { homedir } = require("node:os");
 
+// Canonical knowledge type dirs (mirror STORE_KNOWLEDGE_TYPE_DIRS in
+// packages/shared/src/schemas/store.ts). Kept inline — this zero-dep reader
+// runs in user repos without node_modules access.
+const KNOWLEDGE_CANONICAL_TYPES = [
+  "decisions",
+  "pitfalls",
+  "guidelines",
+  "models",
+  "processes",
+];
+const KNOWLEDGE_SUBDIR = "knowledge";
+const PENDING_SUBDIR = "pending";
+
 // `~/.fabric` (FABRIC_HOME override mirrors the CLI's resolveGlobalRoot).
 function resolveGlobalRoot() {
   return join(process.env.FABRIC_HOME || homedir(), ".fabric");
 }
 
-function bindingsSnapshotPath(projectId, globalRoot) {
+function bindingsSnapshotPath(bindingId, globalRoot) {
   return join(
     globalRoot || resolveGlobalRoot(),
     "state",
     "bindings",
-    projectId + "_resolved.json",
+    bindingId + "_resolved.json",
   );
 }
 
 // Read + shallow-validate the snapshot. Returns the parsed object, or null when
 // absent / unreadable / not the expected shape. NEVER throws.
-function readBindingsSnapshot(projectId, globalRoot) {
-  if (typeof projectId !== "string" || projectId.length === 0) {
+function readBindingsSnapshot(bindingId, globalRoot) {
+  if (typeof bindingId !== "string" || bindingId.length === 0) {
     return null;
   }
-  const path = bindingsSnapshotPath(projectId, globalRoot);
+  const path = bindingsSnapshotPath(bindingId, globalRoot);
   if (!existsSync(path)) {
     return null;
   }
@@ -54,6 +67,103 @@ function readBindingsSnapshot(projectId, globalRoot) {
   }
 }
 
+// Recursively count *.md files under `dir`, tracking the oldest mtime. Missing
+// / unreadable dirs contribute zero (degrade silently — a hook never throws).
+function countMarkdownFiles(dir) {
+  let count = 0;
+  let oldestMtimeMs = null;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return { count, oldestMtimeMs };
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = countMarkdownFiles(fullPath);
+      count += nested.count;
+      if (
+        nested.oldestMtimeMs !== null &&
+        (oldestMtimeMs === null || nested.oldestMtimeMs < oldestMtimeMs)
+      ) {
+        oldestMtimeMs = nested.oldestMtimeMs;
+      }
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(fullPath).mtimeMs;
+    } catch {
+      continue;
+    }
+    count += 1;
+    if (oldestMtimeMs === null || mtimeMs < oldestMtimeMs) {
+      oldestMtimeMs = mtimeMs;
+    }
+  }
+  return { count, oldestMtimeMs };
+}
+
+// LIVE store-backed knowledge counts for nudges (underseed canonical_count,
+// review-backlog pending_count). The snapshot's cached `knowledge_stats` is a
+// store-global projection frozen at write time, so it goes stale whenever store
+// content changes out-of-band (a `git pull` in the store repo, a sync run from a
+// *different* bound workspace) — that staleness is the root cause of the phantom
+// review-backlog (KT-PIT-0017) and the false "knowledge sparse" underseed nudge.
+//
+// Fix: the snapshot persists the resolved store ROOT dirs (`knowledge_store_dirs`,
+// stable across content sync — they only change when mounts/bindings change,
+// which regenerates the snapshot). Recount the *.md files under those dirs LIVE
+// so the numbers are always fresh regardless of how content changed. Falls back
+// to the cached `knowledge_stats` for snapshots written before this field
+// existed. Returns null only when neither source is available.
+function liveKnowledgeStats(snapshot) {
+  if (!snapshot || typeof snapshot !== "object") {
+    return null;
+  }
+  const dirs = snapshot.knowledge_store_dirs;
+  if (Array.isArray(dirs) && dirs.length > 0) {
+    let pendingCount = 0;
+    let canonicalCount = 0;
+    let oldestPendingMtimeMs = null;
+    for (const storeDir of dirs) {
+      if (typeof storeDir !== "string" || storeDir.length === 0) {
+        continue;
+      }
+      for (const type of KNOWLEDGE_CANONICAL_TYPES) {
+        canonicalCount += countMarkdownFiles(join(storeDir, KNOWLEDGE_SUBDIR, type)).count;
+      }
+      const pending = countMarkdownFiles(join(storeDir, KNOWLEDGE_SUBDIR, PENDING_SUBDIR));
+      pendingCount += pending.count;
+      if (
+        pending.oldestMtimeMs !== null &&
+        (oldestPendingMtimeMs === null || pending.oldestMtimeMs < oldestPendingMtimeMs)
+      ) {
+        oldestPendingMtimeMs = pending.oldestMtimeMs;
+      }
+    }
+    return { pendingCount, canonicalCount, oldestPendingMtimeMs };
+  }
+  // #3 (GH issue): snapshot predates knowledge_store_dirs. The cached
+  // `knowledge_stats` projection is frozen at snapshot-write time and goes stale
+  // out-of-band (store grew via git pull / cross-workspace sync), so trusting it
+  // re-introduced exactly the false-nudge this whole field cures — observed a
+  // store with 61 live canonical entries whose cached count was frozen at 1,
+  // mis-firing the "knowledge sparse → /fabric-import" underseed nudge AND
+  // defeating the fabric-import `canonical > 50 → SKIP` guard. read_set carries
+  // no resolved store root either (alias/uuid only), so a live recount is
+  // impossible without re-resolution (which hooks must not do). Return null
+  // ("undeterminable") so callers SKIP the nudge rather than act on a stale
+  // count — old snapshots self-heal on the next install/sync/store-op (which
+  // regenerates the snapshot WITH knowledge_store_dirs). 宁可不弹也别误弹
+  // (KT-DEC-0007: hook = nudge, never a false-positive gate).
+  return null;
+}
+
 // Render a compact, per-store label line for a SessionStart / Stop hook from a
 // snapshot. Empty string when there is nothing to show (degrade silently). The
 // label is provenance only — it never re-resolves; it just echoes the read-set
@@ -77,5 +187,6 @@ module.exports = {
   resolveGlobalRoot,
   bindingsSnapshotPath,
   readBindingsSnapshot,
+  liveKnowledgeStats,
   formatStoreLabels,
 };

package/templates/hooks/lib/cite-line-parser.cjs

@@ -15,13 +15,12 @@
 //     hand-syncing is cheaper than introducing transpile machinery.
 //   - The existing `installHookLibs` pipeline auto-copies every `.cjs` under
 //     templates/hooks/lib/ to each client's hooks/lib/ dir, so this file
-//     auto-ships to cc/codex/cursor with no install pipeline change.
+//     auto-ships to cc/codex with no install pipeline change.
 //
 // Vocabulary contract (mirrored 1:1 with the TS source):
-//   - cite_tags enum: applied | dismissed | none (rc.37 NEW-1 2-state vocab).
-//     v2.1.0-rc.1 (ADJ-P4-1, full remap): legacy rc≤36 tags (planned / recalled
-//     / chained-from) are REMAPPED to `applied` here — accepted as input but no
-//     longer emitted verbatim, so the TS source and this twin stay in lockstep.
+//   - cite_tags enum: applied | dismissed | none (2-state vocab). Pre-user
+//     clean-slate: unrecognized tags degrade to `none` (no legacy remap), so
+//     the TS source and this twin stay in lockstep.
 //   - operator kinds: edit | not_edit | require | forbid
 //     (source token `!edit:` → schema kind `not_edit`)
 //   - skip:<reason> captures everything after the first colon, so
@@ -52,24 +51,17 @@ function splitStorePrefix(token) {
     : { store: token.slice(0, colon), id: token.slice(colon + 1) };
 }
 
-// v2.1.0-rc.1 (ADJ-P4-1, full remap): legacy rc≤36 tags collapse to `applied`.
-// Mirrors LEGACY_CITE_TAG_REMAP / normalizeCiteTag in the TS source — accepted
-// as input but emitted as the 2-state vocab so cite-coverage never undercounts.
-const LEGACY_CITE_TAG_REMAP = {
-  planned: "applied",
-  recalled: "applied",
-  "chained-from": "applied",
-};
-
+// Mirrors normalizeCiteTag in the TS source: applied/dismissed/none pass
+// through; anything else degrades to `none` (no legacy remap).
 function parseTag(rawTag) {
   if (!rawTag) return "none";
-  // Tags may carry tails like `chained-from KT-DEC-0001` or
-  // `dismissed:scope-mismatch`; head token (whitespace/colon-bounded) wins.
+  // Tags may carry tails like `dismissed:scope-mismatch`; the head token
+  // (whitespace/colon-bounded) wins.
   const head = rawTag.trim().split(/[\s:]+/)[0].toLowerCase();
   if (head === "applied" || head === "dismissed" || head === "none") {
     return head;
   }
-  return LEGACY_CITE_TAG_REMAP[head] || "none";
+  return "none";
 }
 
 function parseContractTail(tail) {
@@ -166,9 +158,9 @@ function parseCiteLine(raw) {
       // v2.0.0-rc.27.1 (Codex review fix): cite_commitments MUST be index-
       // aligned with cite_ids per the schema doc on event-ledger.ts:428.
       // Multi-id citations share ONE parsed contract — propagate it across
-      // every id slot so downstream consumers (`doctor.ts` per-cite walk +
-      // `cite-contract-reminder.cjs`) can look up `commitments[i]` for any
-      // valid `i < cite_ids.length` without falling into an undefined slot.
+      // every id slot so the downstream consumer (`doctor.ts` per-cite
+      // cite-coverage walk) can look up `commitments[i]` for any valid
+      // `i < cite_ids.length` without falling into an undefined slot.
       for (let i = 0; i < parsed.ids.length; i += 1) {
         result.cite_commitments.push(parsed.commitment);
       }