@fenglimg/fabric-cli 2.2.0-rc.9 → 2.3.0-rc.1

package/templates/hooks/knowledge-pretooluse.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// ux-w2-6: the SINGLE PreToolUse hook. Previously the Edit|Write|MultiEdit
+// matcher carried TWO commands — knowledge-hint-narrow.cjs (narrow KB hint) and
+// cite-policy-evict.cjs (recall-before-edit nudge) — so a single edit produced
+// TWO additionalContext envelopes (双弹). This orchestrator runs both in ONE
+// process and merges their output into ONE envelope.
+//
+// narrow.cjs and cite-policy-evict.cjs stay as standalone modules (their full
+// contract test-suites are unchanged); this entry imports them as libs, reads
+// stdin ONCE (stdin is single-read), hands the parsed payload to each via the
+// `env.payload` test seam, captures each one's stdout, and folds the two
+// envelopes into a single `{ systemMessage?, hookSpecificOutput.additionalContext? }`.
+// Each sub-hook stays best-effort/silent-on-failure, so a throw in one never
+// blocks the edit or suppresses the other (KT-DEC-0007).
+
+const narrow = require("./knowledge-hint-narrow.cjs");
+const cite = require("./cite-policy-evict.cjs");
+
+function readStdinPayload() {
+  try {
+    const raw = require("node:fs").readFileSync(0, "utf8");
+    if (!raw || raw.trim().length === 0) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// Parse a captured stdout chunk as a Claude Code hook envelope. Returns null for
+// empty / non-JSON output (e.g. a stderr-only codex breadcrumb leaves stdout
+// empty). Tolerant: a malformed line is ignored, never thrown.
+function parseEnvelope(text) {
+  const trimmed = typeof text === "string" ? text.trim() : "";
+  if (trimmed.length === 0) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// Fold narrow + cite envelopes into one. additionalContext (AI sink) is
+// concatenated (narrow hint first, then the cite nudge); systemMessage (human
+// sink) likewise. Either side may be absent.
+function mergeEnvelopes(narrowText, citeText) {
+  const a = parseEnvelope(narrowText);
+  const b = parseEnvelope(citeText);
+  if (a === null && b === null) return null;
+
+  const aiParts = [];
+  const humanParts = [];
+  let eventName = "PreToolUse";
+  for (const env of [a, b]) {
+    if (env === null) continue;
+    const hso = env.hookSpecificOutput;
+    if (hso && typeof hso.additionalContext === "string" && hso.additionalContext.length > 0) {
+      aiParts.push(hso.additionalContext);
+      if (typeof hso.hookEventName === "string") eventName = hso.hookEventName;
+    }
+    if (typeof env.systemMessage === "string" && env.systemMessage.length > 0) {
+      humanParts.push(env.systemMessage);
+    }
+  }
+
+  const merged = {};
+  if (humanParts.length > 0) merged.systemMessage = humanParts.join("\n");
+  if (aiParts.length > 0) {
+    merged.hookSpecificOutput = {
+      hookEventName: eventName,
+      additionalContext: aiParts.join("\n"),
+    };
+  }
+  return Object.keys(merged).length > 0 ? `${JSON.stringify(merged)}\n` : null;
+}
+
+async function main(env, stdio) {
+  try {
+    const out = (stdio && stdio.stdout) || process.stdout;
+    const err = (stdio && stdio.stderr) || process.stderr;
+    // Read stdin ONCE and share the parsed payload with both sub-hooks (stdin is
+    // a single-read stream — the prior two-command wiring read it twice).
+    const payload = env && env.payload !== undefined ? env.payload : readStdinPayload();
+    const sub = { ...(env || {}), payload };
+
+    const narrowChunks = [];
+    const citeChunks = [];
+    const capture = (sink) => ({ write: (c) => sink.push(String(c)) });
+
+    try {
+      await narrow.main(sub, { stdout: capture(narrowChunks), stderr: err });
+    } catch {
+      // narrow best-effort — never block the edit
+    }
+    try {
+      await cite.main(sub, { stdout: capture(citeChunks), stderr: err });
+    } catch {
+      // cite best-effort — never block the edit
+    }
+
+    const merged = mergeEnvelopes(narrowChunks.join(""), citeChunks.join(""));
+    if (merged !== null) out.write(merged);
+  } catch {
+    // Silent — the PreToolUse hook MUST NEVER block the edit on its own failure.
+  }
+}
+
+module.exports = { main, mergeEnvelopes, parseEnvelope };
+
+if (require.main === module) {
+  main();
+}

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

@@ -28,15 +28,16 @@
  *
  *   - STRINGS — exported for test introspection only (read-only by convention).
  *
- * Banner keys (11 total):
+ * Banner keys:
  *   Signal A (archive):     archiveLine1, archiveActivity, archiveCta
+ *   Archive backlog:        backlogLine1, backlogCta
  *   Signal B (review):      reviewLine1, reviewCta
  *   Signal C (import):      importLine1, importCta
  *   Signal D (maintenance): maintenanceLine1Never, maintenanceLine1Aged, maintenanceLine2
  *   Broad hook:             broadImportBanner
  *
  * Protected tokens — NEVER translated, kept verbatim across all 4 variants:
- *   - Slash commands: /fabric-archive, /fabric-review, /fabric-import
+ *   - Slash commands: /fabric-archive, /fabric-review, /fabric-archive
  *   - CLI commands:   `fabric doctor --lint`
  *   - Numeric / template substrings the existing tests assert on:
  *       "${hoursElapsed.toFixed(1)}h" (e.g. "25.0h"), "阈值 ${N}h",
@@ -165,6 +166,23 @@ const STRINGS = {
     "zh-CN-hybrid": () => "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?",
   },
 
+  // ---- Archive backlog (cross-session safety net, crack 2) ------------------
+  // Replaces the old global-24h archive timer: counts DEAD sessions (session
+  // ended / idle) carrying unarchived high-value work. Substring "${count}" is
+  // addressable for tests. params: { count: number }
+  backlogLine1: {
+    "zh-CN": (p) => `📋 Fabric: ${p.count} 个已结束的会话有未归档的高价值改动。`,
+    en: (p) => `📋 Fabric: ${p.count} ended session(s) carry unarchived high-value work.`,
+    "zh-CN-hybrid": (p) => `📋 Fabric: ${p.count} 个已结束的会话有未归档的高价值改动。`,
+  },
+
+  // params: {} — protected token /fabric-archive verbatim across all variants.
+  backlogCta: {
+    "zh-CN": () => "   是否调 /fabric-archive 跨会话补归档这些遗漏?",
+    en: () => "   Run /fabric-archive to sweep these missed sessions across the backlog?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-archive 跨会话补归档这些遗漏?",
+  },
+
   // ---- Signal B: review -----------------------------------------------------
   // Source (zh-CN): fabric-hint.cjs:651  `📋 Fabric: 已积累 ${stats.count} 条待审核知识${ageSuffix}。`
   // params: { count, ageSuffix } — ageSuffix is " / 最早一条 N.N 天前" or "" (zh-CN only)
@@ -204,12 +222,13 @@ const STRINGS = {
       `📋 Fabric: 知识库节点数 ${p.nodeCount}/${p.threshold}，距 init_scan_completed ${p.hoursSinceInit}h。`,
   },
 
-  // Source (zh-CN): fabric-hint.cjs:698  `   是否调 /fabric-import 从 git 历史与现有文档回灌知识?`
-  // params: {} — protected token /fabric-import verbatim across all variants.
+  // W3-C: fabric-import folded into fabric-archive `source` mode — the underseed
+  // cold-start nudge now points at /fabric-archive (its source mode). Protected
+  // token /fabric-archive verbatim across all variants.
   importCta: {
-    "zh-CN": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
-    en: () => "   Run /fabric-import to backfill knowledge from git history and existing docs?",
-    "zh-CN-hybrid": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    "zh-CN": () => "   是否调 /fabric-archive 的 source mode 从 git 历史与现有文档回灌知识?",
+    en: () => "   Run /fabric-archive source mode to backfill knowledge from git history and existing docs?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-archive 的 source mode 从 git 历史与现有文档回灌知识?",
   },
 
   // ---- Signal D: maintenance -----------------------------------------------
@@ -271,15 +290,15 @@ const STRINGS = {
 
   // ---- Broad hook: import recommendation ------------------------------------
   // Source (zh-CN): knowledge-hint-broad.cjs:262
-  //   "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?"
+  //   "  📋 Fabric: 知识库稀疏，是否调 /fabric-archive 从 git 历史与现有文档回灌知识?"
   // Note: leading two spaces are intentional (existing banner indent).
-  // params: {} — protected token /fabric-import verbatim.
+  // params: {} — protected token /fabric-archive verbatim.
   broadImportBanner: {
-    "zh-CN": () => "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    "zh-CN": () => "  📋 Fabric: 知识库稀疏，是否调 /fabric-archive 从 git 历史与现有文档回灌知识?",
     en: () =>
-      "  📋 Fabric: knowledge base is sparse — run /fabric-import to backfill from git history and existing docs?",
+      "  📋 Fabric: knowledge base is sparse — run /fabric-archive to backfill from git history and existing docs?",
     "zh-CN-hybrid": () =>
-      "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+      "  📋 Fabric: 知识库稀疏，是否调 /fabric-archive 从 git 历史与现有文档回灌知识?",
   },
 
   // ---- Broad hook: meta auto-refresh breadcrumb (rc.22 Scope D T-D4) -------

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

@@ -153,7 +153,7 @@ function liveKnowledgeStats(snapshot) {
   // 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
+  // mis-firing the "knowledge sparse → /fabric-archive" 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

package/templates/hooks/lib/event-writer.cjs

@@ -0,0 +1,79 @@
+// ux-w2-9: the SINGLE guarded events.jsonl write path for .cjs hooks.
+//
+// Before this, every hook (knowledge-hint-broad / fabric-hint / post-tooluse-
+// mutation) hand-stamped the event envelope (kind/id/ts/schema_version) and
+// called appendLockedLine directly. A forgotten field or a non-string event_type
+// produced a row the doctor's event-ledger Zod read (event_ledger_schema_compat)
+// would reject. This module centralizes the stamp + guard so every cjs-written
+// row satisfies the same envelope contract the TS appendEventLedgerEvent enforces
+// via Zod — without pulling Zod into the no-build .cjs runtime.
+//
+// Contract (mirrors eventLedgerEventSchema's envelope):
+//   - event_type MUST be a non-empty string (the discriminator). Missing/blank →
+//     the event is REJECTED (returns false), never written.
+//   - kind / schema_version are FORCED to the ledger constants.
+//   - id / ts are stamped only when absent (caller may pre-stamp for determinism).
+//   - Never throws — hooks must never block; a write failure returns false.
+
+const { join } = require("node:path");
+const { appendLockedLine } = require("./injection-log.cjs");
+
+const EVENT_KIND = "fabric-event";
+const SCHEMA_VERSION = 1;
+
+function safeUuid() {
+  try {
+    // eslint-disable-next-line global-require
+    return require("node:crypto").randomUUID();
+  } catch {
+    // crypto unavailable (exotic runtime) → time+rand fallback, still unique enough.
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  }
+}
+
+// Stamp the canonical envelope onto a caller event, or return null when the event
+// fails the guard (not an object / missing event_type). Pure (no I/O).
+function stampEvent(event) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) return null;
+  if (typeof event.event_type !== "string" || event.event_type.length === 0) return null;
+  return {
+    ...event,
+    kind: EVENT_KIND,
+    schema_version: SCHEMA_VERSION,
+    id: typeof event.id === "string" && event.id.length > 0 ? event.id : `event:${safeUuid()}`,
+    ts: typeof event.ts === "number" ? event.ts : Date.now(),
+  };
+}
+
+// Append ONE guarded event line to <fabricDir>/events.jsonl. Returns true on a
+// successful write, false if the event failed the guard or the append errored.
+function appendEvent(fabricDir, event) {
+  const stamped = stampEvent(event);
+  if (stamped === null) return false;
+  try {
+    appendLockedLine(join(fabricDir, "events.jsonl"), JSON.stringify(stamped) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Append MANY guarded events in a SINGLE locked write (preserves the batched
+// append the post-tooluse hook relied on). Invalid events are dropped; returns
+// the count actually written. A zero-valid batch performs no write.
+function appendEvents(fabricDir, events) {
+  if (!Array.isArray(events)) return 0;
+  const stamped = events.map(stampEvent).filter((e) => e !== null);
+  if (stamped.length === 0) return 0;
+  try {
+    appendLockedLine(
+      join(fabricDir, "events.jsonl"),
+      stamped.map((e) => JSON.stringify(e)).join("\n") + "\n",
+    );
+    return stamped.length;
+  } catch {
+    return 0;
+  }
+}
+
+module.exports = { appendEvent, appendEvents, stampEvent };

package/templates/hooks/lib/nudge-policy.cjs

@@ -103,6 +103,17 @@ function resolveHumanSink(projectRoot, event, gate) {
   // 4. global human-channel mute.
   if (mode === "silent") return { emitHuman: false, verbosity, mode };
 
+  // 4b. v2.2 C1 (W5): the `stop` human nudge (archive cadence) defaults to QUIET.
+  // The edit-count / session signal already lives in the events.jsonl ledger as
+  // queryable telemetry (KT-DEC-0030), so the Stop hook should NOT carry a
+  // real-time human-observation UI that interrupts execution flow — find the
+  // specific session after the fact instead (user directive 2026-06-22). It stays
+  // OBSERVE-only by default; opt back in explicitly via observe.stop=true (handled
+  // at step 3) or the verbose preset. SessionStart / pre_tool_use are unaffected.
+  if (event === "stop" && mode !== "verbose") {
+    return { emitHuman: false, verbosity, mode };
+  }
+
   // 5. preset default — emit at the preset's verbosity.
   return { emitHuman: true, verbosity, mode };
 }

package/templates/hooks/lib/theme.cjs

@@ -0,0 +1,62 @@
+// ux-w2-5: the .cjs mirror of packages/shared/src/theme.ts — the hook-side half
+// of Fabric's single terminal theme. Byte-locked to the TS source by
+// theme-parity.test.ts (G-THEME): the PALETTE / ANSI tables and the paint/symbol
+// render primitives MUST produce byte-identical output here and in the CLI, so a
+// SessionStart hint and `fabric install` paint the same colours. No deps (no Ink,
+// no picocolors) — pure ANSI, matching the Ink-exit direction (W3-A).
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+};
+
+const PALETTE = {
+  success: "\x1b[38;2;46;204;113m", // emerald
+  warn: "\x1b[38;2;241;196;15m", // amber
+  error: "\x1b[38;2;231;76;60m", // alizarin
+  drift: "\x1b[38;2;155;89;182m", // amethyst
+  ai: "\x1b[38;2;52;152;219m", // peter-river blue
+  human: "\x1b[38;2;26;188;156m", // turquoise
+  accent: "\x1b[38;2;155;89;182m", // amethyst
+  muted: ANSI.dim,
+};
+
+function isColorEnabled(env, isTTY) {
+  const e = env || process.env;
+  if (e.NO_COLOR) return false;
+  const force = e.FORCE_COLOR;
+  if (force !== undefined) return force !== "0" && force.toLowerCase() !== "false";
+  return Boolean(isTTY === undefined ? process.stdout.isTTY : isTTY);
+}
+
+function paint(token, text, colorOn) {
+  const on = colorOn === undefined ? isColorEnabled() : colorOn;
+  if (!on) return text;
+  return `${PALETTE[token]}${text}${ANSI.reset}`;
+}
+
+const SYMBOL_ASCII = { ok: "[ok]", warn: "[warn]", error: "[error]" };
+const SYMBOL_GLYPH = { ok: "[ok] ✓", warn: "[warn] !", error: "[error] x" };
+const SYMBOL_TOKEN = { ok: "success", warn: "warn", error: "error" };
+
+function symbol(kind, colorOn) {
+  const on = colorOn === undefined ? isColorEnabled() : colorOn;
+  return on ? paint(SYMBOL_TOKEN[kind], SYMBOL_GLYPH[kind], true) : SYMBOL_ASCII[kind];
+}
+
+// W3-B structural primitives — HUD-shared layer (C-003), byte-mirror of the TS
+// source (packages/shared/src/theme.ts), pinned by theme-parity.test.ts.
+function sectionBar(title, colorOn) {
+  const on = colorOn === undefined ? isColorEnabled() : colorOn;
+  return on ? `${ANSI.bold}${PALETTE.accent}▌ ${title}${ANSI.reset}` : `# ${title}`;
+}
+
+const SCOPE_BADGE_TOKEN = { team: "drift", project: "ai", personal: "human" };
+function scopeBadge(scope, colorOn) {
+  const on = colorOn === undefined ? isColorEnabled() : colorOn;
+  const text = `[${scope}]`;
+  return on ? paint(SCOPE_BADGE_TOKEN[scope], text, true) : text;
+}
+
+module.exports = { ANSI, PALETTE, isColorEnabled, paint, symbol, SYMBOL_ASCII, sectionBar, scopeBadge };

package/templates/hooks/post-tooluse-mutation.cjs

@@ -41,9 +41,10 @@ const { isAbsolute, join, relative } = require("node:path");
 
 // W1-01 (ISS-011) parity: route every shared-ledger append through the
 // advisory-lock primitive so concurrent PostToolUse fires (multi-window /
-// parallel edits) never interleave a partial line. Best-effort, drop-on-
-// contention — same primitive the narrow/broad hooks use.
-const { appendLockedLine } = require("./lib/injection-log.cjs");
+// parallel edits) never interleave a partial line. ux-w2-9: route batched event
+// writes through the single guarded event-writer (envelope stamp + event_type
+// guard + advisory-lock append) so every row satisfies the event-ledger schema.
+const { appendEvents } = require("./lib/event-writer.cjs");
 
 const FABRIC_DIR_REL = ".fabric";
 const EVENTS_LEDGER_FILE = "events.jsonl";
@@ -223,23 +224,17 @@ function appendFileMutated(projectRoot, now, paths, toolCallId, toolName, sessio
       typeof sessionId === "string" && sessionId.length > 0 ? sessionId : null;
     const validToolName =
       typeof toolName === "string" && toolName.length > 0 ? toolName : null;
-    const lines =
-      pathList
-        .map((p) =>
-          JSON.stringify({
-            kind: "fabric-event",
-            id: `event:${randomUUID()}`,
-            ts: tsMs,
-            schema_version: 1,
-            ...(validSessionId ? { session_id: validSessionId } : {}),
-            event_type: "file_mutated",
-            path: p,
-            tool_call_id: callId,
-            ...(validToolName ? { tool_name: validToolName } : {}),
-          }),
-        )
-        .join("\n") + "\n";
-    appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), lines);
+    appendEvents(
+      fabricDir,
+      pathList.map((p) => ({
+        ts: tsMs,
+        ...(validSessionId ? { session_id: validSessionId } : {}),
+        event_type: "file_mutated",
+        path: p,
+        tool_call_id: callId,
+        ...(validToolName ? { tool_name: validToolName } : {}),
+      })),
+    );
   } catch {
     // Silent — marker failure must never block the tool pipeline.
   }
@@ -290,25 +285,19 @@ function appendKnowledgeBodyRead(projectRoot, now, paths, toolCallId, toolName,
       typeof sessionId === "string" && sessionId.length > 0 ? sessionId : null;
     const validToolName =
       typeof toolName === "string" && toolName.length > 0 ? toolName : null;
-    const lines =
-      reads
-        .map((r) =>
-          JSON.stringify({
-            kind: "fabric-event",
-            id: `event:${randomUUID()}`,
-            ts: tsMs,
-            schema_version: 1,
-            ...(validSessionId ? { session_id: validSessionId } : {}),
-            event_type: "knowledge_body_read",
-            stable_id: r.stable_id,
-            ...(r.store ? { store: r.store } : {}),
-            path: r.path,
-            tool_call_id: callId,
-            ...(validToolName ? { tool_name: validToolName } : {}),
-          }),
-        )
-        .join("\n") + "\n";
-    appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), lines);
+    appendEvents(
+      fabricDir,
+      reads.map((r) => ({
+        ts: tsMs,
+        ...(validSessionId ? { session_id: validSessionId } : {}),
+        event_type: "knowledge_body_read",
+        stable_id: r.stable_id,
+        ...(r.store ? { store: r.store } : {}),
+        path: r.path,
+        tool_call_id: callId,
+        ...(validToolName ? { tool_name: validToolName } : {}),
+      })),
+    );
   } catch {
     // Silent — marker failure must never block the tool pipeline.
   }

package/templates/skills/fabric-archive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: fabric-archive
-description: 归档对话洞察到 active write store 的 pending knowledge (NOT code review). Triggers 以后/always/never/下次/记一下;wrong-turn-revert;decision-confirm;dismissal-reason;/fabric-archive.
-allowed-tools: Read, Glob, Grep, Bash, mcp__fabric__fab_extract_knowledge
+description: 归档对话洞察(default)+ 冷启动从 git log/docs 回灌(source mode)到 active write store 的 pending knowledge (NOT code review). Triggers 归档/记一下/always·never/wrong-turn-revert;source mode bootstrap fabric/import 历史/mine commit.
+allowed-tools: Read, Glob, Grep, Bash, mcp__fabric__fab_archive_scan, mcp__fabric__fab_propose, mcp__fabric__fab_pending, mcp__fabric__fab_review
 ---
 
 > **Surface**: Skill (LLM judgment over session digests). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md).
@@ -29,10 +29,27 @@ rc.37 NEW-9 collapsed the flow to **3 macro-phases**; the legacy fine-grained ph
 
 - **GATHER** = Phase 0 (range) → 0.5 (config) → 1 (ledger scan via `fab_archive_scan`) → [1.5 onboard] → 2 (candidates).
 - **REVIEW** = Phase 2.5 (viability gate) → 3 (classify / layer / slug + batch review) → 3.5 (relevance scope + relevance_paths) → 3.7 (semantic scope / audience axis). The single user review round lives here.
-- **PERSIST** = Phase 4 (`fab_extract_knowledge`, one call per candidate) → 4.5 (archive-attempt ledger).
+- **PERSIST** = Phase 4 (`fab_propose`, one call per candidate) → 4.5 (archive-attempt ledger).
 
 Sub-step chain: `0 → 0.5 → 1 → [1.5] → 2 → 2.5 → 3 → 3.5 → 3.7 → 4 → 4.5`. Each below is a navigator stub — full procedure, decision tables, and worked examples live in `ref/`.
 
+## Source Mode — cold-start bootstrap (W3-C: 吸收原 fabric-import)
+
+**Default mode** GATHERs candidates from the cross-session digest ledger (Phase 1, `fab_archive_scan`). **Source mode** swaps ONLY the GATHER source: it mines `git log` + `docs/*.md` for one-time per-project cold-start — the REVIEW (classify / layer / scope / semantic_scope) and PERSIST (`fab_propose`) pipeline below is **shared, byte-for-byte the same contract**. No new write path: mined entries land as `team`-layer pending via the same `fab_propose`, then dedupe vs canonical via `fab_review`.
+
+**Enter source mode when** the user explicitly asks to bootstrap / import history / mine commits, OR the SessionStart hook fired `shouldRecommendImport()`. Else stay in default mode. **SKIP** when `.fabric/` missing (→ `fabric install`), canonical count > `import_skip_canonical_threshold` (default 50), or checkpoint `phase=complete` + `last_checkpoint_at <24h`.
+
+Source-mode pipeline (replaces GATHER; REVIEW+PERSIST unchanged):
+
+1. **Init / checkpoint** — read/init `.fabric/.import-state.json` (single resumability source; atomic `Write .tmp` → `Bash mv`). Corruption → `Read ref/source-state-recovery.md`. Full state schema + 6-step resume → `Read ref/source-checkpoint.md`.
+2. **Init-scan reference (NO re-implement)** — `fabric onboard-coverage --json` + `fab_pending action="search"` to learn existing canonical titles for the negative filter. `fabric install` already produced the baseline; source mode references it, never redoes it.
+3. **Mine (git + docs)** — `git log --since="<window> months ago"` (conventional prefix → type signal) + `docs/*.md`; classify into the 5 types; `fab_propose` per candidate. **Source-mode scope lock (NON-NEGOTIABLE): every mined entry `relevance_scope="broad"` + `relevance_paths=[]`** — LLM-inferred narrow lies about applicability; narrowing is deferred to `fab_review.modify` post-import. Cap `import_max_pending_per_run` (default 10). Full mining procedure, conventional-prefix table, `--dry-run` template → `Read ref/source-mining.md`.
+4. **Dedupe vs canonical** — for each pending, `fab_pending action="search"` (top 5 by type), classify duplicate / subsumption / subsumption-with-novelty / contradiction / genuinely-new, then `fab_review` reject / modify. `fab_pending` does NOT compare meaning — semantic compare is the LLM's job. Full 5-way classification → `Read ref/source-dedup.md`.
+
+Source-mode config knobs (read from `.fabric/fabric-config.json`, defaults if absent): `import_window_first_run_months` (60), `import_window_rerun_months` (2), `import_max_pending_per_run` (10), `import_max_commits_scan` (500), `import_skip_canonical_threshold` (50).
+
+Source-mode output roll-up + worked examples → `Read ref/source-output-contract.md` / `ref/source-worked-examples.md`. Source mode requires an **explicit target store** (E7) — never auto-route mined entries; resolve writable candidates via `fabric info scope team` and `AskUserQuestion` for the alias when more than one exists.
+
 ### Phase 0 — Range Resolution
 
 Parse user's prompt for time-window (`今日` / `last week`), topic keyword (`rc.20`), or literal `session_id` reference; emit `session_id[]` OR `"all"` sentinel that constrains Phase 1 collection. LLM-as-parser contract — no parser code.
@@ -45,7 +62,7 @@ Read `.fabric/fabric-config.json`; resolve `archive_max_candidates_per_batch` (d
 
 ### Phase 0.6 — Store routing (v2.1 multi-store)
 
-Archives land in the **active write store** for the entry's scope — NEVER pick a store yourself. Run `fabric scope-explain team` (or the relevant scope) to get the resolved `writeTarget`; that is where `fab_extract_knowledge` persists. Single-store → the lone store (back-compat). After persisting, **echo the target store alias** (`归档到 store '<alias>'`). Personal-scope entries route to the personal store (never the shared team store, R5#3). Do NOT read `~/.fabric` store trees directly — go through `scope-explain` / the MCP write path.
+Archives land in the **active write store** for the entry's scope — NEVER pick a store yourself. Run `fabric info scope team` (or the relevant scope) to get the resolved `writeTarget`; that is where `fab_propose` persists. Single-store → the lone store (back-compat). After persisting, **echo the target store alias** (`归档到 store '<alias>'`). Personal-scope entries route to the personal store (never the shared team store, R5#3). Do NOT read `~/.fabric` store trees directly — go through `fabric info scope` / the MCP write path.
 
 ### UX i18n Policy
 
@@ -65,6 +82,18 @@ The deterministic ledger scan now runs **server-side** — call `fab_archive_sca
 
 Then (LLM side, Boundary B): for each returned `session_id`, load `.fabric/.cache/session-digests/<session_id>.md`, concatenate into a `### Cross-session digest` block, and populate `source_sessions[]` + `session_context` for Phase 4. Cap at `archive_digest_max_sessions`. Missing digest files degrade silently.
 
+**Coverage transparency (crack 3 — cheap recall backstop).** BEFORE collecting candidates, surface the scan's watermark + drops to the user so a human can act as the recall detector and manually override (`--range <session_id>` to force a dropped session back in). This is the affordable substitute for the (deferred) periodic cold-eval miss-rate audit — show, don't hide, what the deterministic filter skipped:
+
+```
+📋 归档覆盖到 <covered_through_ts 转人类可读时间>。
+   纳入会话: <session_ids.length> 个。
+   跳过 <dropped.length> 个: <每个 {session_id 短码} (reason)>
+     reason 含义: user_dismissed=用户曾拒绝 / cooldown=12h 防抖内 / no_new_signal=自上次归档无新高价值活
+   若某个被跳过的会话其实有该归档的内容,显式 `fabric-archive --range <session_id>` 强制纳入。
+```
+
+Render `dropped` only when non-empty; render the watermark line always. en variant mirrors the same fields. Keep it ONE compact block — this is a backstop affordance, not a report.
+
 `Read ref/phase-1-cross-session.md` for the filter state machine + digest-stitch + graceful-degradation notes. The hand-rolled `tail -n 200` scan is retired — `fab_archive_scan` is the source of truth.
 
 Graceful degradation: missing digest cache → single-session fallback. Missing `session_archive_attempted` events (pre-rc.25) → legacy "scan everything since anchor" behaviour.
@@ -83,7 +112,7 @@ Gather raw evidence: tail `.fabric/events.jsonl` since last `knowledge_proposed`
 
 Coarse viability check. **PASS**: user_explicit_invoke OR ≥1 archive signal hit. rc.37 NEW-4 folds the legacy 8 signals into **3 categories**: (1) **User-driven knowledge expression** (normative language `always`/`never`/`以后`/`记一下`/`永远不要`, OR decision-with-rationale, OR dismissal-with-reason); (2) **Reflective discovery** (wrong-turn-and-revert, OR long diagnostic loop, OR a named reusable pattern); (3) **Concrete artifact change** (new dependency diff, OR a formalized multi-step procedure).
 
-Pre-PASS HARD gate (rc.37 NEW-4): per candidate, run `fab_review action="search"` against the mounted read-set; duplicate canonical → drop the candidate (anti-signal #4). Silently writing a near-duplicate is the highest-noise failure mode.
+Pre-PASS HARD gate (rc.37 NEW-4): per candidate, run `fab_pending action="search"` against the mounted read-set; duplicate canonical → drop the candidate (anti-signal #4). Silently writing a near-duplicate is the highest-noise failure mode.
 
 **FAIL → branch**: E1/E3/E5 silent-skip (`outcome='skipped_no_signal'`); E2/E4 render gate-FAIL (`outcome='viability_failed'`) and MUST include the force-archive escape hatch (zh-CN: `如需强制归档，请显式调用 fabric-archive` / en: `To force-archive, explicitly invoke fabric-archive`).
 
@@ -93,6 +122,8 @@ Pre-PASS HARD gate (rc.37 NEW-4): per candidate, run `fab_review action="search"
 
 For each candidate, propose **type** ∈ {model, decision, guideline, pitfall, process}, **layer** ∈ {team, personal} via the verbatim heuristic below, **slug** (kebab-case 2-5 words, 20-40 chars, unique within type+layer bucket), **summary** (1-2 sentences).
 
+> **Self-sufficiency standard — guideline / model summaries (KT-GLD-0001/0006).** These two types land in the SessionStart **ALWAYS-ACTIVE** sink as a single INDEX line with NO body injected — so the summary IS the operative rule the agent acts on. Author it as a self-contained imperative that states the thesis (the *what* + the operative *so-what*), e.g. `改源码前先读 bootstrap+compiler config;scripts 为 init 主执行边界`. A topic label that only points at the body (`Code style guidelines`, `Scope model`) is NOT acceptable here — the reader can't act on it without a fetch, breaking the always-active contract. decision/pitfall/process summaries are exempt (they surface as `must_read_if` triggers, deliberately pointers). Do NOT self-judge sufficiency in this phase (curse-of-knowledge rubber-stamps — KT-GLD-0006); authoring to the standard is the write-time floor, the zero-context cold-eval at review time is the real gate.
+
 #### Layer Classification Heuristic (verbatim, contract-locked)
 
 > - **强 team**: 引用本项目代码、团队共识用语（"we decided"）、fabric-import 路径产物、业务领域、绑定本项目代码的 pitfall
@@ -123,7 +154,7 @@ Sets the entry's **audience** `semantic_scope` (orthogonal to `layer`=store and
 
 ### Phase 4 — Persist via MCP
 
-For each user-confirmed candidate, call `fab_extract_knowledge` ONCE (NEVER batch). Required: `source_sessions[]`, `recent_paths[]` (cap 20), `user_messages_summary`, `type` (plural form: decisions/pitfalls/guidelines/models/processes), `slug`, `layer`, `relevance_scope`, `relevance_paths[]`, `proposed_reason` (enum), `session_context` (3-5 line narrative). One OPTIONAL audience field: `semantic_scope` — pass `team` ONLY when Phase 3.7 classified a team candidate as team-wide (cross-project); OMIT otherwise so the engine auto-derives `project:<active_project>` (or `team` when the repo has no `active_project`). Four OPTIONAL rc.23 triage fields (`intent_clues`, `tech_stack`, `impact`, `must_read_if`) — populate when clean, **omit rather than guess**.
+For each user-confirmed candidate, call `fab_propose` ONCE (NEVER batch). Required: `source_sessions[]`, `recent_paths[]` (cap 20), `user_messages_summary`, `type` (plural form: decisions/pitfalls/guidelines/models/processes), `slug`, `layer`, `relevance_scope`, `relevance_paths[]`, `proposed_reason` (enum), `session_context` (3-5 line narrative). One OPTIONAL audience field: `semantic_scope` — pass `team` ONLY when Phase 3.7 classified a team candidate as team-wide (cross-project); OMIT otherwise so the engine auto-derives `project:<active_project>` (or `team` when the repo has no `active_project`). Four OPTIONAL rc.23 triage fields (`intent_clues`, `tech_stack`, `impact`, `must_read_if`) — populate when clean, **omit rather than guess**.
 
 Server returns `{ pending_path, idempotency_key }`. Display `pending_path` for the user. `idempotency_key = sha256({source_session, type, slug})` — repeated calls SAFE (server merges evidence).
 
@@ -149,25 +180,25 @@ MANDATORY closing step on EVERY invocation (Phase 4 success path + every early-e
 - WHEN `active_project` is set AND `layer=team`, MUST present `[semantic_scope=...]` (`team` for team-wide, or `project:<active_project>` for this-project-only) plus a one-line `Audience reasoning:` citing this-project-only vs team-wide (Phase 3.7).
 - MUST classify against the canonical singular nouns: model / decision / guideline / pitfall / process. NEVER invent new types.
 - MUST cap the batch at `archive_max_candidates_per_batch` candidates (config-resolved, default 8); drop weaker ones over the cap.
-- MUST display the resolved `pending_path` returned by `fab_extract_knowledge` so the user can verify.
+- MUST display the resolved `pending_path` returned by `fab_propose` so the user can verify.
 - MUST treat user inline edits to type/layer/slug/relevance_scope/relevance_paths/semantic_scope as authoritative replacements before Phase 2.
 - MUST skip rather than guess when an observation does not fit any of the 5 types.
 
 ### WRITE Rules
 
-- NEVER write a knowledge entry directly to the filesystem; the only legal write path is `mcp__fabric__fab_extract_knowledge`.
-- NEVER infer or glob a project-local pending directory — persist through `fab_extract_knowledge` and use the returned store-resolved `pending_path`; promotion to canonical knowledge is fab_review concern, NOT this skill.
+- NEVER write a knowledge entry directly to the filesystem; the only legal write path is `mcp__fabric__fab_propose`.
+- NEVER infer or glob a project-local pending directory — persist through `fab_propose` and use the returned store-resolved `pending_path`; promotion to canonical knowledge is fab_review concern, NOT this skill.
 - NEVER include an `id` field anywhere — pending entries have no id (late-bind on approve).
 - NEVER classify a candidate as `personal` when a 强 team signal applies. Default to team on ambiguity.
 - NEVER emit a non-empty `relevance_paths` when `relevance_scope=broad` — broad MUST always carry `relevance_paths=[]`.
 - NEVER emit a non-empty `relevance_paths` when `layer=personal` — personal forces `relevance_scope=broad` + `relevance_paths=[]`.
 - v2.0.0-rc.37 NEW-7 widened Phase 3.5: `edit_paths` ∪ `user_mentioned_paths` drives `relevance_paths`; `read_paths` flows separately to `evidence_paths` (structured frontmatter, not body markdown). NEVER lift body regex / symbol extraction into `relevance_paths` — those remain reserved for v2.1+.
-- NEVER batch multiple candidates into a single fab_extract_knowledge call; one call per candidate.
+- NEVER batch multiple candidates into a single fab_propose call; one call per candidate.
 - NEVER paraphrase the verbatim layer heuristic block above — the Chinese text is contract-locked.
-- MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `fab_extract_knowledge`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `semantic_scope`, `active_project`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`, `related`, `KT→KP`.
+- MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `fab_propose`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `semantic_scope`, `active_project`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`, `related`, `KT→KP`.
 
 ## Worked Examples / E5 Cron / Dry-run (ref-only)
 
-- **Worked examples** (3 end-to-end fab_extract_knowledge calls: decision/team, pitfall/team, guideline/personal): `Read ref/worked-examples.md`
+- **Worked examples** (3 end-to-end fab_propose calls: decision/team, pitfall/team, guideline/personal): `Read ref/worked-examples.md`
 - **E5 Scheduled Daily Recap** (only when entry_point=E5_cron — OS cron, `/loop`, or scheduled trigger): `Read ref/e5-cron-recap.md`
 - **Dry-run Scope** (authoritative catalogue of all writes suspended by `--dry-run`): `Read ref/dry-run-scope.md`

package/templates/skills/fabric-archive/ref/dry-run-scope.md

@@ -4,7 +4,7 @@
 
 | Write operation | Normal mode | Dry-run mode |
 |---|---|---|
-| `fab_extract_knowledge` MCP call (Phase 4) | One call per confirmed candidate, writes to the active write store and returns `pending_path` | SKIPPED. Phase 4 renders "would write N pending entries" preview table instead. |
+| `fab_propose` MCP call (Phase 4) | One call per confirmed candidate, writes to the active write store and returns `pending_path` | SKIPPED. Phase 4 renders "would write N pending entries" preview table instead. |
 | `session_archive_attempted` event (Phase 4.5) | Appended to `.fabric/events.jsonl` for every session in scope | SKIPPED entirely. No ledger entry. |
 | `fab_review reject` (Phase 3 user-dismissed branch) | Invoked when user types `撤销` / `reject` after self-archive proposal | SKIPPED. The dismissal is rendered to console but no MCP write occurs. |
 | `fabric onboard-coverage` slot writes (Phase 1.5 fill-all / dismiss-all) | Each `Bash("fabric config dismiss-slot <slot>")` invocation runs | SKIPPED. Slot decisions are shown as "would dismiss/propose" preview. |

package/templates/skills/fabric-archive/ref/i18n-policy.md

@@ -43,7 +43,7 @@ Rendering rule:
 - `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_recall`), CLI command names (e.g. `fabric install`), file paths, technical concepts (`Skill`, `SessionStart`, `hook`, `MCP`, `revision_hash`, `pending`, `proven`, `verified`, `draft`).
 - `fabric_language === "match-existing"` or any other value → emit the en variant; pure monolingual.
 
-Protected tokens (`fab_extract_knowledge`, `relevance_scope`,
+Protected tokens (`fab_propose`, `relevance_scope`,
 `relevance_paths`, `narrow`, `broad`, `source_sessions`, `proposed_reason`,
 `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`,
 `pending_path`, `layer`, `team`, `personal`,