@fenglimg/fabric-cli 2.0.0-rc.15 → 2.0.0-rc.21

package/templates/hooks/fabric-hint.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
+const { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
 const { dirname, join } = require("node:path");
 
 // v2.0.0-rc.7 T5: session-digest writer. Best-effort (never blocks Stop hook
@@ -13,6 +13,15 @@ try {
   sessionDigestWriter = null;
 }
 
+// v2.0.0-rc.16 TASK-002 (F2-apply): banner-i18n lib for the 5 Signal
+// banners (A/B/C/D-never/D-aged). Resolved ONCE per main() invocation and
+// threaded into decide() / evaluateMaintenanceSignal() via the existing
+// thresholds object. Lib is required at module load; failure to load is
+// fatal-here-but-silent: the require itself can't throw without the .cjs
+// being missing entirely (a packaging bug we'd want to surface during
+// install integration tests, not silently swallow).
+const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
+
 // CONSTANTS — duplicated from packages/server/src/services/_shared.ts.
 // DRY violation accepted: this hook script runs in user repos WITHOUT
 // node_modules access, so it cannot import from @fenglimg/fabric-server.
@@ -22,6 +31,11 @@ const EVENT_TYPE_PROPOSED = "knowledge_proposed";
 const EVENT_TYPE_INIT_SCAN_COMPLETED = "init_scan_completed";
 // v2.0.0-rc.7 T10: doctor_run event drives Signal D (maintenance hint).
 const EVENT_TYPE_DOCTOR_RUN = "doctor_run";
+// v2.0.0-rc.20 TASK-03: per-turn cite-policy observation event. Emitted by
+// extractAndWriteAssistantTurnsBestEffort() after the Stop hook parses each
+// assistant envelope's first non-empty line for a `KB:` prefix. Schema
+// registered in packages/shared/src/schemas/event-ledger.ts (rc.20 TASK-02).
+const EVENT_TYPE_ASSISTANT_TURN_OBSERVED = "assistant_turn_observed";
 // rc.6 TASK-022 (E5): Signal A is now `24h OR N-edits since last
 // knowledge_proposed`. The edit-count branch reads
 // `.fabric/.cache/edit-counter` (one ISO-8601 line per PreToolUse fire,
@@ -556,6 +570,10 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     typeof cfg.reviewHintPendingAgeDays === "number" && cfg.reviewHintPendingAgeDays > 0
       ? cfg.reviewHintPendingAgeDays
       : DEFAULT_REVIEW_HINT_PENDING_AGE_DAYS;
+  // rc.16 TASK-002: banner variant for the i18n lib. Defaults to 'zh-CN' so
+  // existing test callers (which never pass thresholds.variant) get the rc.15
+  // byte-identical Chinese output. main() always supplies the resolved variant.
+  const variant = typeof cfg.variant === "string" ? cfg.variant : "zh-CN";
 
   // ---- Archive signal (rc.6 TASK-022 — Signal A, 24h-OR-N-edits) -----------
   // Locate the most-recent knowledge_proposed event. If none exists, Signal A
@@ -611,14 +629,17 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
         `累计 ${editStats.editsSinceLastProposed} 次编辑（阈值 ${editStats.threshold}）`,
       );
     }
-    const line1 = `📋 Fabric: 距上次归档 ${parts.join(" / ")}。`;
+    // rc.16 TASK-002: 5-banner i18n via lib/banner-i18n.cjs. Substring
+    // contracts ('25.0h', '阈值 N', 'fabric-archive') preserved by the lib's
+    // zh-CN templates — see lib header for the full contract.
+    const line1 = renderBanner("archiveLine1", variant, { parts: parts.join(" / ") });
     const activity = banner && typeof banner.activityOverview === "string"
       ? banner.activityOverview
       : "";
     const line2 = activity.length > 0
-      ? `   最近活动集中在: ${activity}。`
+      ? renderBanner("archiveActivity", variant, { activity })
       : "";
-    const line3 = "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?";
+    const line3 = renderBanner("archiveCta", variant, {});
     const reason = [line1, line2, line3].filter((l) => l.length > 0).join("\n");
     return {
       decision: "block",
@@ -648,8 +669,13 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
       stats.oldestAgeMs !== null
         ? ` / 最早一条 ${(stats.oldestAgeMs / MS_PER_DAY).toFixed(1)} 天前`
         : "";
-    const line1 = `📋 Fabric: 已积累 ${stats.count} 条待审核知识${ageSuffix}。`;
-    const line2 = "   是否调 /fabric-review 审核 pending/ 条目?";
+    // rc.16 TASK-002: i18n via lib. Substrings ('${count} 条', 'fabric-review')
+    // preserved by the lib's zh-CN templates.
+    const line1 = renderBanner("reviewLine1", variant, {
+      count: stats.count,
+      ageSuffix,
+    });
+    const line2 = renderBanner("reviewCta", variant, {});
     const reason = `${line1}\n${line2}`;
     return {
       decision: "block",
@@ -690,12 +716,16 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     (hoursSinceProposed === null || hoursSinceProposed >= UNDERSEED_NO_PROPOSED_HOURS);
 
   if (triggerUnderseed) {
-    // rc.7 T4: 人-first banner reformat for Signal C. Preserves the
-    // `${nodeCount}/${threshold}` substring (e.g. "3/10") that existing
-    // tests assert against; drops Agent-jussive phrasing.
-    const line1 =
-      `📋 Fabric: 知识库节点数 ${underseed.nodeCount}/${underseed.threshold}，距 init_scan_completed ${hoursSinceInit.toFixed(1)}h。`;
-    const line2 = "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?";
+    // rc.16 TASK-002: i18n via lib. Substrings ('${nodeCount}/${threshold}',
+    // 'fabric-import', '${hoursSinceInit}h') preserved by the lib's zh-CN
+    // templates. Note: hoursSinceInit is passed as already-toFixed(1) string
+    // to keep the lib pure (no number formatting in render path).
+    const line1 = renderBanner("importLine1", variant, {
+      nodeCount: underseed.nodeCount,
+      threshold: underseed.threshold,
+      hoursSinceInit: hoursSinceInit.toFixed(1),
+    });
+    const line2 = renderBanner("importCta", variant, {});
     const reason = `${line1}\n${line2}`;
     return {
       decision: "block",
@@ -898,6 +928,10 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
     typeof cfg.maintenanceHintCooldownDays === "number" && cfg.maintenanceHintCooldownDays > 0
       ? cfg.maintenanceHintCooldownDays
       : DEFAULT_MAINTENANCE_HINT_COOLDOWN_DAYS;
+  // rc.16 TASK-002: banner variant for the i18n lib. Defaults to 'zh-CN' so
+  // existing rc.7 T10 test fixtures (which never set thresholds.variant) get
+  // the byte-identical Chinese maintenance banner.
+  const variant = typeof cfg.variant === "string" ? cfg.variant : "zh-CN";
 
   if (canonicalCount < MAINTENANCE_HINT_MIN_CANONICAL) {
     return null;
@@ -922,14 +956,18 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
     if (ageDays < days) return null; // doctor ran recently, no nag.
   }
 
-  // rc.7 T4: keep the existing T10 banner shape (already 人-first with the
-  // 📋 prefix), but split the action-prompt onto its own line for visual
-  // consistency with Signals A/B/C. Substrings ("从未运行 lint 检查",
-  // "已 N 天未跑 lint", "fabric doctor --lint") preserved for the T10 tests.
-  const line2 = "   是否调 `fabric doctor --lint` 看看知识库健康度?";
-  const reason = lastDoctorTs === null
-    ? `📋 Fabric: 从未运行 lint 检查。\n${line2}`
-    : `📋 Fabric: 已 ${days} 天未跑 lint 检查（实际 ${ageDays.toFixed(1)}d）。\n${line2}`;
+  // rc.16 TASK-002: i18n via lib. Substrings ('从未运行 lint 检查',
+  // '已 N 天未跑 lint', 'fabric doctor --lint') preserved by the lib's
+  // zh-CN templates. ageDays passed as already-toFixed(1) string to keep
+  // the lib pure (no number formatting in render path).
+  const line2 = renderBanner("maintenanceLine2", variant, {});
+  const line1 = lastDoctorTs === null
+    ? renderBanner("maintenanceLine1Never", variant, {})
+    : renderBanner("maintenanceLine1Aged", variant, {
+        days,
+        ageDays: ageDays.toFixed(1),
+      });
+  const reason = `${line1}\n${line2}`;
 
   return {
     decision: "block",
@@ -966,6 +1004,204 @@ function tryReadStdinJson() {
   }
 }
 
+/**
+ * v2.0.0-rc.20 TASK-03: parse the raw text that follows the `KB:` prefix on
+ * the first non-empty line of an assistant turn. Returns parsed cite ids and
+ * the per-id tag enum vocabulary (planned/recalled/chained-from/dismissed/
+ * none). Never throws; best-effort tolerant parser.
+ *
+ * Vocabulary contract (mirrored in
+ * packages/shared/src/schemas/event-ledger.ts → assistantTurnObservedEventSchema):
+ *   - "none"                                → ids=[], tags=["none"]
+ *   - "KP-001"                              → ids=["KP-001"], tags=[]
+ *   - "KP-001, KT-DEC-0009 (review)"        → ids=["KP-001","KT-DEC-0009"], tags=["review"]
+ *   - "KP-001 [recalled][chained-from KP-002]" →
+ *       ids=["KP-001"], tags=["recalled","chained-from"]
+ *   - "dismissed:<reason>"                  → ids=[], tags=["dismissed"]
+ *       (kb_line_raw preserves the full "dismissed:<reason>" verbatim;
+ *        the parsed `cite_tags` only carries the enum value "dismissed".)
+ *
+ * Tags are filtered to the Zod enum set
+ * { planned, recalled, chained-from, dismissed, none } before being returned —
+ * arbitrary parenthetical/bracket text outside the enum is dropped (silently)
+ * so the emitted event always round-trips through the schema.
+ */
+function parseKbLine(raw) {
+  const result = { cite_ids: [], cite_tags: [] };
+  if (typeof raw !== "string") return result;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return result;
+
+  // dismissed:<reason> → tag="dismissed", no ids.
+  if (/^dismissed:/i.test(trimmed)) {
+    result.cite_tags.push("dismissed");
+    return result;
+  }
+  // bare "none" → tag="none".
+  if (/^none$/i.test(trimmed)) {
+    result.cite_tags.push("none");
+    return result;
+  }
+
+  // Allowed tag enum (matches assistantTurnObservedEventSchema.cite_tags z.enum).
+  const ALLOWED_TAGS = new Set(["planned", "recalled", "chained-from", "dismissed", "none"]);
+  const tagSet = new Set();
+
+  // Extract bracketed tags: `[recalled]`, `[chained-from KP-002]`, etc.
+  // We keep only the leading enum token (split on whitespace) so trailing
+  // ref-ids inside the bracket are discarded — they're not part of the tag
+  // vocabulary.
+  const bracketRegex = /\[([^\]]+)\]/g;
+  let bracketMatch;
+  let stripped = trimmed;
+  while ((bracketMatch = bracketRegex.exec(trimmed)) !== null) {
+    const inner = bracketMatch[1].trim();
+    if (inner.length === 0) continue;
+    const head = inner.split(/\s+/)[0].toLowerCase();
+    if (ALLOWED_TAGS.has(head)) tagSet.add(head);
+  }
+  stripped = stripped.replace(bracketRegex, " ");
+
+  // Extract parenthetical tags: `(review)`, `(planned)`, etc. Only enum
+  // members are retained.
+  const parenRegex = /\(([^)]+)\)/g;
+  let parenMatch;
+  while ((parenMatch = parenRegex.exec(trimmed)) !== null) {
+    const inner = parenMatch[1].trim().toLowerCase();
+    if (inner.length === 0) continue;
+    if (ALLOWED_TAGS.has(inner)) tagSet.add(inner);
+  }
+  stripped = stripped.replace(parenRegex, " ");
+
+  // Remaining content: comma-separated ids, possibly with stray whitespace.
+  // We split on comma, trim, and keep tokens that look like ref-ids
+  // (uppercase letter prefix). This filters out leftover english words and
+  // is permissive enough to allow custom id schemes (KP-, KT-, KD-, etc.).
+  const parts = stripped.split(",");
+  for (const partRaw of parts) {
+    const part = partRaw.trim();
+    if (part.length === 0) continue;
+    // Take the leading token (whitespace-bounded) so "KT-DEC-0009 garbage"
+    // still yields "KT-DEC-0009".
+    const token = part.split(/\s+/)[0];
+    if (/^[A-Z][A-Z0-9-]+$/.test(token)) {
+      result.cite_ids.push(token);
+    }
+  }
+
+  // Materialise tagSet → array (preserves insertion order via Set semantics).
+  for (const t of tagSet) result.cite_tags.push(t);
+  return result;
+}
+
+/**
+ * v2.0.0-rc.20 TASK-03: detect which client surface invoked the hook so the
+ * emitted assistant_turn_observed event can carry a `client` discriminator
+ * without having to inspect the transcript shape.
+ *
+ * Resolution order (first match wins):
+ *   1. `FABRIC_HINT_CLIENT` env var — explicit override, set by the per-
+ *      client install pipeline when the hook-config schema supports env
+ *      injection.
+ *   2. Path heuristic against `__dirname` — `.claude/` → "cc", `.codex/` →
+ *      "codex". Covers the dominant deployment shape (hook script lives
+ *      under the client's per-repo dir).
+ *
+ * Returns `undefined` when neither signal fires (e.g. Cursor — deferred to
+ * rc.21 — or a custom deployment). The Zod schema marks `client` optional,
+ * so omitting it leaves the event valid.
+ */
+function detectClient() {
+  const envClient = process.env.FABRIC_HINT_CLIENT;
+  if (typeof envClient === "string" && envClient.length > 0) {
+    const normalised = envClient.trim().toLowerCase();
+    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+      return normalised;
+    }
+  }
+  // Path heuristic — __dirname is the directory containing this .cjs file
+  // when invoked normally (require.main === module).
+  try {
+    if (__dirname.includes(".claude/") || __dirname.includes(".claude\\")) return "cc";
+    if (__dirname.includes(".codex/") || __dirname.includes(".codex\\")) return "codex";
+  } catch {
+    // __dirname always defined for cjs modules; fall through defensively.
+  }
+  return undefined;
+}
+
+/**
+ * v2.0.0-rc.20 TASK-03: emit one `assistant_turn_observed` event per
+ * assistant envelope harvested from the transcript. Wrapped in try/catch
+ * (best-effort, never throws — Stop hook MUST stay non-blocking on any
+ * failure here). The event shape mirrors
+ * assistantTurnObservedEventSchema in
+ * packages/shared/src/schemas/event-ledger.ts (registered in rc.20 TASK-02).
+ *
+ * Call site sits immediately AFTER writeSessionDigestBestEffort so both
+ * digest + per-turn events derive from the same transcript snapshot.
+ *
+ * `id` mirrors the server's convention (`event:<uuid>`) using
+ * crypto.randomUUID when available — falls back to a timestamp+counter
+ * tuple on older Node where randomUUID is missing (cjs hook tooling
+ * defensively targets Node 18+, but the fallback keeps it event-shaped).
+ */
+function extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload) {
+  if (stdinPayload === null || typeof stdinPayload !== "object") return;
+  try {
+    const sessionId = stdinPayload.session_id;
+    if (typeof sessionId !== "string" || sessionId.length === 0) return;
+    const transcript = summarizeTranscript(stdinPayload.transcript_path);
+    const turns = transcript.assistant_turns;
+    if (!Array.isArray(turns) || turns.length === 0) return;
+
+    // Resolve event-ledger path. Caller already validated cwd shape.
+    const fabricDir = join(cwd, FABRIC_DIR);
+    if (!existsSync(fabricDir)) {
+      // No .fabric/ → workspace is uninitialised. Silently skip; the digest
+      // writer applies the same guard via its own internal check.
+      return;
+    }
+    const ledgerPath = join(fabricDir, EVENT_LEDGER_FILE);
+    const client = detectClient();
+    let randomUUID;
+    try {
+      ({ randomUUID } = require("node:crypto"));
+    } catch {
+      randomUUID = null;
+    }
+
+    for (const turn of turns) {
+      try {
+        const idSuffix = typeof randomUUID === "function"
+          ? randomUUID()
+          : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        const event = {
+          kind: "fabric-event",
+          id: `event:${idSuffix}`,
+          ts: Date.now(),
+          schema_version: 1,
+          session_id: sessionId,
+          event_type: EVENT_TYPE_ASSISTANT_TURN_OBSERVED,
+          kb_line_raw: turn.kb_line_raw,
+          cite_ids: Array.isArray(turn.cite_ids) ? turn.cite_ids : [],
+          cite_tags: Array.isArray(turn.cite_tags) ? turn.cite_tags : [],
+          turn_id: `${sessionId}-${turn.envelope_index}`,
+          envelope_index: turn.envelope_index,
+          timestamp: new Date().toISOString(),
+        };
+        if (client !== undefined) event.client = client;
+        appendFileSync(ledgerPath, JSON.stringify(event) + "\n", "utf8");
+      } catch {
+        // Per-turn failure must not abort the remaining turns; the Stop hook
+        // contract is "never block on hook failure". Best-effort continues.
+      }
+    }
+  } catch {
+    // Outer guard — never throw. Hook continues silently.
+  }
+}
+
 /**
  * v2.0.0-rc.7 T5: extract user_messages + edit_paths + 1-line title from the
  * transcript JSONL referenced by the hook's stdin payload. Best-effort, never
@@ -974,9 +1210,18 @@ function tryReadStdinJson() {
  * Claude Code's transcript_path points at a JSONL where each line is a
  * message envelope. We sniff for `role: "user"` lines (text content) and
  * for tool-use entries naming Edit / Write / MultiEdit to harvest file_path.
+ *
+ * v2.0.0-rc.20 TASK-03: additionally collects `assistant_turns[]` — one
+ * entry per assistant envelope with the parsed KB-line cite metadata. Field
+ * is additive; existing callers (writeSessionDigestBestEffort) ignore it.
  */
 function summarizeTranscript(transcriptPath) {
-  const out = { user_messages: [], edit_paths: [], title: "" };
+  // rc.20 TASK-03: additive `assistant_turns` array — one entry per assistant
+  // envelope, regardless of whether the first line matched KB:. Downstream
+  // consumers (extractAndWriteAssistantTurnsBestEffort) emit one
+  // assistant_turn_observed event per element; `kb_line_raw=null` when no
+  // KB: line was found.
+  const out = { user_messages: [], edit_paths: [], title: "", assistant_turns: [] };
   if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return out;
   if (!existsSync(transcriptPath)) return out;
   let raw;
@@ -986,6 +1231,7 @@ function summarizeTranscript(transcriptPath) {
     return out;
   }
   const lines = raw.split(/\r?\n/);
+  let envelopeIndex = -1;
   for (const line of lines) {
     const trimmed = line.trim();
     if (trimmed.length === 0) continue;
@@ -996,6 +1242,7 @@ function summarizeTranscript(transcriptPath) {
       continue;
     }
     if (envelope === null || typeof envelope !== "object") continue;
+    envelopeIndex += 1;
 
     // User text message — Claude Code shape: { role: "user", content: [...] }
     // OR nested under `message.role`. Be generous.
@@ -1013,6 +1260,61 @@ function summarizeTranscript(transcriptPath) {
       }
     }
 
+    // rc.20 TASK-03: assistant envelope — capture first non-empty line of the
+    // first text block and parse for `KB:` prefix. We push ONE assistant_turns
+    // entry per assistant envelope (even when no KB: line) so downstream can
+    // distinguish "turn observed, no KB" (kb_line_raw=null) from "no turn".
+    if (role === "assistant") {
+      const content = envelope.content || (envelope.message && envelope.message.content);
+      let firstText = null;
+      if (typeof content === "string") {
+        firstText = content;
+      } else if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+            firstText = block.text;
+            break;
+          }
+        }
+      }
+      let kbLineRaw = null;
+      let citeIds = [];
+      let citeTags = [];
+      if (typeof firstText === "string" && firstText.length > 0) {
+        // First non-empty line.
+        const linesOfText = firstText.split(/\r?\n/);
+        let firstNonEmpty = "";
+        for (const l of linesOfText) {
+          if (l.trim().length > 0) {
+            firstNonEmpty = l.trim();
+            break;
+          }
+        }
+        if (firstNonEmpty.length > 0) {
+          // KB: none (case-insensitive on the literal `none`).
+          const noneMatch = firstNonEmpty.match(/^KB:\s*none\s*$/i);
+          const kbMatch = firstNonEmpty.match(/^KB:\s+(.+)$/);
+          if (noneMatch) {
+            kbLineRaw = firstNonEmpty;
+            const parsed = parseKbLine("none");
+            citeIds = parsed.cite_ids;
+            citeTags = parsed.cite_tags;
+          } else if (kbMatch) {
+            kbLineRaw = firstNonEmpty;
+            const parsed = parseKbLine(kbMatch[1]);
+            citeIds = parsed.cite_ids;
+            citeTags = parsed.cite_tags;
+          }
+        }
+      }
+      out.assistant_turns.push({
+        envelope_index: envelopeIndex,
+        kb_line_raw: kbLineRaw,
+        cite_ids: citeIds,
+        cite_tags: citeTags,
+      });
+    }
+
     // Tool use — look for Edit / Write / MultiEdit and harvest file_path.
     const candidates = [];
     if (envelope.type === "tool_use") candidates.push(envelope);
@@ -1099,6 +1401,13 @@ function main(env, stdio) {
         ? env.stdin_payload
         : tryReadStdinJson();
     writeSessionDigestBestEffort(cwd, stdinPayload);
+    // v2.0.0-rc.20 TASK-03: per-turn cite-policy observation events. Same
+    // best-effort contract as the digest writer — never throws, never blocks
+    // the Stop hook on failure. Shares the transcript snapshot read by
+    // writeSessionDigestBestEffort (each call re-reads independently; the
+    // transcript file is small in practice and re-parse cost is dwarfed by
+    // the hook's other I/O).
+    extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload);
 
     const events = readLedger(cwd);
     let pendingStats;
@@ -1147,6 +1456,19 @@ function main(env, stdio) {
     // rc.7 T7: read the externalized thresholds and pass them into decide.
     // Reader failures degrade silently to documented defaults — fabric-hint
     // must never block on config errors (see hook contract above).
+    //
+    // rc.16 TASK-002 (F2-apply): resolve `fabric_language` ONCE per main()
+    // invocation via the banner-i18n lib. The result threads through
+    // `thresholds.variant` into both decide() and evaluateMaintenanceSignal()
+    // so we read the config file at most once, not five times. Lib reader
+    // is never-throw; defensive try/catch is belt-and-suspenders.
+    let variant = "zh-CN";
+    try {
+      variant = readFabricLanguage(cwd);
+    } catch {
+      variant = "zh-CN";
+    }
+
     let thresholds;
     try {
       thresholds = {
@@ -1155,6 +1477,7 @@ function main(env, stdio) {
         reviewHintPendingAgeDays: readReviewHintPendingAgeDays(cwd),
         maintenanceHintDays: readMaintenanceHintDays(cwd),
         maintenanceHintCooldownDays: readMaintenanceHintCooldownDays(cwd),
+        variant,
       };
     } catch {
       thresholds = {
@@ -1163,6 +1486,7 @@ function main(env, stdio) {
         reviewHintPendingAgeDays: DEFAULT_REVIEW_HINT_PENDING_AGE_DAYS,
         maintenanceHintDays: DEFAULT_MAINTENANCE_HINT_DAYS,
         maintenanceHintCooldownDays: DEFAULT_MAINTENANCE_HINT_COOLDOWN_DAYS,
+        variant,
       };
     }
 
@@ -1293,6 +1617,11 @@ module.exports = {
   readMaintenanceHintCooldownDays,
   readShownCache,
   writeShownCache,
+  // v2.0.0-rc.20 TASK-03 / TASK-09: cite-policy parsing + per-turn emission
+  // helpers (exported for unit testing of the parse + emit contract).
+  parseKbLine,
+  detectClient,
+  extractAndWriteAssistantTurnsBestEffort,
   CONSTANTS: {
     FABRIC_DIR,
     EVENT_LEDGER_FILE,

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

@@ -54,6 +54,12 @@ const {
 } = require("node:fs");
 const { join } = require("node:path");
 
+// rc.16 TASK-003: shared banner-i18n lib (resolves fabric_language config and
+// renders localized banner text). Mirror of the wiring in fabric-hint.cjs
+// (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");
+
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
 // SessionStart fire (matching Skill-style progressive disclosure). Prior
@@ -257,10 +263,12 @@ const MATURITY_PROVEN = "proven";
 const MATURITY_VERIFIED = "verified";
 const MATURITY_DRAFT = "draft";
 
-// rc.8 underseed self-check banner text. Single line, mirrors the emoji-prefix
-// style of other Fabric banners (cf. fabric-hint.cjs Signal C `📋 Fabric:`).
-const IMPORT_RECOMMENDATION_BANNER =
-  "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?";
+// rc.8 underseed self-check banner: single line, emoji-prefixed (cf.
+// fabric-hint.cjs Signal C `📋 Fabric:`). rc.16 TASK-003 routed the literal
+// through the banner-i18n lib (key: 'broadImportBanner') — see main() below
+// for the renderBanner call site. Substring contracts preserved across all
+// variants: leading two-space indent, `📋 Fabric:` prefix, `/fabric-import`
+// verbatim token (asserted by knowledge-hint-broad.test.ts).
 
 // -----------------------------------------------------------------------------
 // CLI invocation
@@ -431,16 +439,29 @@ function renderTruncated(narrow) {
  *
  * Returns an array of lines (one stderr write per line keeps the formatter
  * trivial and testable). Returns [] when there is nothing meaningful to say
- * (empty narrow set) so callers know to stay silent.
+ * (empty entries set) so callers know to stay silent.
+ *
+ * Protocol v2 gate (rc.18): payloads must carry `version: 2`. A null/missing
+ * payload returns [] silently; a payload with a mismatched `version` returns []
+ * after writing exactly one stderr breadcrumb so operators grepping a stuck-
+ * banner report can diagnose the version drift without source-diving.
  */
 function renderSummary(payload) {
-  // Local rebind: `payload.narrow` in `--all` mode degenerates to the full
-  // shared index (every broad-scoped entry), so the field name `narrow` is
-  // misleading at this rendering layer. We rename the local variable to
-  // `entries` to avoid name confusion when reading renderSummary in isolation.
-  // The CLI protocol field name (`payload.narrow`) is unchanged — a wire-shape
-  // rename is a deferred independent task.
-  const entries = Array.isArray(payload && payload.narrow) ? payload.narrow : [];
+  if (!payload || payload.version !== 2) {
+    if (payload && payload.version !== undefined) {
+      try {
+        process.stderr.write(
+          `[fabric] hint payload version=${payload.version} unsupported (expected 2), skipping\n`,
+        );
+      } catch {}
+    }
+    return [];
+  }
+  // Protocol v2 (rc.18): the wire field is now `payload.entries`, matching what
+  // this renderer always called it locally. The historical `narrow` name (which
+  // degenerated in --all mode) has been retired without a compat shim per
+  // pre-user clean-slate policy.
+  const entries = Array.isArray(payload.entries) ? payload.entries : [];
   if (entries.length === 0) return [];
 
   const truncated = entries.length > TRUNCATION_THRESHOLD;
@@ -487,7 +508,12 @@ function main(env, stdio) {
     const lines = renderSummary(payload);
 
     if (recommendImport) {
-      lines.push(IMPORT_RECOMMENDATION_BANNER);
+      // rc.16 TASK-003: resolve fabric_language ONCE per invocation (only when
+      // we actually need to emit the banner — keeps the no-banner path free of
+      // the extra config read). 'match-existing' / unknown variant folds to 'en'
+      // inside renderBanner per UX i18n Policy class 1.
+      const variant = readFabricLanguage(cwd);
+      lines.push(renderBanner("broadImportBanner", variant, {}));
     }
 
     if (lines.length === 0) return; // nothing to say — silent exit
@@ -523,7 +549,6 @@ module.exports = {
     MATURITY_DRAFT,
     DEFAULT_UNDERSEED_NODE_THRESHOLD,
     KNOWLEDGE_CANONICAL_TYPES,
-    IMPORT_RECOMMENDATION_BANNER,
   },
 };
 

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

@@ -615,9 +615,17 @@ function formatEntryLine(entry) {
 
 /**
  * Render the narrow-match block to an array of stderr lines. Returns []
- * when there is nothing to render (empty narrow set). Callers stay silent
+ * when there is nothing to render (empty entries set). Callers stay silent
  * on empty output.
  *
+ * Protocol gate (rc.18): only `payload.version === 2` payloads are
+ * rendered. Anything else returns []. When the payload exists but carries
+ * a mismatched (non-undefined) version, a one-line stderr breadcrumb is
+ * emitted as a debug aid — see `_protocol-v2-decisions.md` (Decision 2,
+ * "silent-skip + one-line stderr breadcrumb"). The wire field is
+ * `payload.entries` (renamed from `payload.narrow` in protocol v2,
+ * Decision 1).
+ *
  * Output shape:
  *   [fabric] N narrow-scoped knowledge entries match your edit targets:
  *     [<id>] (<type>/<maturity>) <summary>
@@ -625,13 +633,28 @@ function formatEntryLine(entry) {
  *   (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)
  */
 function renderSummary(payload) {
-  const narrow = Array.isArray(payload && payload.narrow) ? payload.narrow : [];
-  if (narrow.length === 0) return [];
+  if (!payload || payload.version !== 2) {
+    if (payload && payload.version !== undefined) {
+      // breadcrumb only if payload exists but version mismatches (avoid
+      // spam on null). Best-effort write — silent-on-failure honors the
+      // hook's "never block edits" contract.
+      try {
+        process.stderr.write(
+          `[fabric] hint payload version=${payload.version} unsupported (expected 2), skipping\n`,
+        );
+      } catch {
+        // ignore — stderr unavailable, silent-skip still applies
+      }
+    }
+    return [];
+  }
+  const entries = Array.isArray(payload.entries) ? payload.entries : [];
+  if (entries.length === 0) return [];
 
   const lines = [
-    `[fabric] ${narrow.length} narrow-scoped knowledge entries match your edit targets:`,
+    `[fabric] ${entries.length} narrow-scoped knowledge entries match your edit targets:`,
   ];
-  for (const entry of narrow) {
+  for (const entry of entries) {
     lines.push(formatEntryLine(entry));
   }
   lines.push("  (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)");
@@ -699,7 +722,8 @@ function main(env, stdio) {
         : invokePlanContextHint(cwd, paths);
     if (cliPayload === null || cliPayload === undefined) return;
 
-    const narrow = Array.isArray(cliPayload.narrow) ? cliPayload.narrow : [];
+    // Protocol v2 (rc.18 TASK-005): wire field is `entries`, no v1 shim.
+    const narrow = Array.isArray(cliPayload.entries) ? cliPayload.entries : [];
     if (narrow.length === 0) {
       // rc.6 TASK-023 (E6): silence-counter — matched-narrow == 0. The CLI
       // had a chance to match against the extracted paths but came back
@@ -764,7 +788,7 @@ function main(env, stdio) {
       });
     }
 
-    const lines = renderSummary({ ...cliPayload, narrow: gateDecision.narrow });
+    const lines = renderSummary({ ...cliPayload, entries: gateDecision.narrow });
     if (lines.length === 0) return;
     for (const line of lines) {
       err.write(`${line}\n`);