@fenglimg/fabric-cli 2.0.1 → 2.2.0-rc.1

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// v2.1.0-rc.1 P4 — hook-side resolved-bindings snapshot reader (F4/S63/S65).
+//
+// 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
+// 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 { join } = require("node:path");
+const { homedir } = require("node:os");
+
+// `~/.fabric` (FABRIC_HOME override mirrors the CLI's resolveGlobalRoot).
+function resolveGlobalRoot() {
+  return join(process.env.FABRIC_HOME || homedir(), ".fabric");
+}
+
+function bindingsSnapshotPath(projectId, globalRoot) {
+  return join(
+    globalRoot || resolveGlobalRoot(),
+    "state",
+    "bindings",
+    projectId + "_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) {
+    return null;
+  }
+  const path = bindingsSnapshotPath(projectId, globalRoot);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      parsed.read_set &&
+      Array.isArray(parsed.read_set.stores)
+    ) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    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
+// the CLI already computed, with the write-target flagged (F4 store labels).
+function formatStoreLabels(snapshot) {
+  if (!snapshot || !snapshot.read_set || !Array.isArray(snapshot.read_set.stores)) {
+    return "";
+  }
+  const writeAlias = snapshot.write_target && snapshot.write_target.alias;
+  const parts = snapshot.read_set.stores.map((store) => {
+    const tag = store.alias === writeAlias ? " (write)" : store.writable ? "" : " (ro)";
+    return store.alias + tag;
+  });
+  if (parts.length === 0) {
+    return "";
+  }
+  return "[fabric] read-set stores: " + parts.join(", ");
+}
+
+module.exports = {
+  resolveGlobalRoot,
+  bindingsSnapshotPath,
+  readBindingsSnapshot,
+  formatStoreLabels,
+};

package/templates/hooks/lib/cite-contract-reminder.cjs

@@ -3,15 +3,16 @@
 // Reads `.fabric/agents.meta.json` to build a stable_id → knowledge_type lookup
 // map, then scans summarised assistant turns (cite_ids + cite_tags +
 // cite_commitments parallel arrays produced by lib/cite-line-parser.cjs) for
-// turns that cited a decision-class or pitfall-class id with [recalled] tag
-// but no operator commitment and no skip:<reason>.
+// turns that cited a decision-class or pitfall-class id with [applied] tag
+// but no operator commitment and no skip:<reason>. (v2.1.0-rc.1 ADJ-P4-1:
+// legacy [recalled] is remapped to [applied] by the parser upstream.)
 //
 // Emits one reminder line per offending id (deduplicated across the turn
 // summary). Non-blocking — caller writes the lines to stderr; failure to
 // load the meta file or absence of offenders means zero output.
 //
 // Reminder template (rc.24 lock B2 / L1 enforcement layer):
-//   ⚠ KB: <id> cited as [recalled] but missing contract; add → edit:<glob>
+//   ⚠ KB: <id> cited as [applied] but missing contract; add → edit:<glob>
 //     or → skip:<reason> next turn
 //
 // Type filter rationale: only `decision` and `pitfall` types are contract-
@@ -34,7 +35,7 @@ const { join } = require("node:path");
 const FABRIC_DIR = ".fabric";
 const AGENTS_META_FILE = "agents.meta.json";
 
-// Knowledge types that require contract commitments on [recalled] cites.
+// Knowledge types that require contract commitments on [applied] cites.
 // Matches the singular form persisted by `withDerivedAgentsMetaNodeDefaults`
 // in packages/shared/src/schemas/agents-meta.ts. We accept both singular
 // and plural defensively so a future schema change to plurals doesn't
@@ -98,13 +99,17 @@ function readKnowledgeTypeMap(projectRoot) {
  * don't, returning the reminder lines to emit.
  *
  * Filter (all must hold for a given index i within a turn):
- *   1. cite_tags includes "recalled" (turn-level — applies to the cited id)
+ *   1. cite_tags includes "applied" (turn-level — applies to the cited id)
  *   2. cite_commitments[i].operators is empty AND cite_commitments[i].skip_reason is null
  *   3. idTypeMap.get(cite_ids[i]) is in {decision, pitfall}
  *
+ * v2.1.0-rc.1 (ADJ-P4-1, full remap): the gate is the rc.37 NEW-1 `applied`
+ * tag. Legacy [recalled] cites are remapped to [applied] by the parser before
+ * they reach here, so gating on "applied" covers both old and new authoring.
+ *
  * Tag-level filter clarification: rc.20 cite_tags is parallel to ALL parsed
  * lines (including sentinels), but for the contract-missing reminder we use
- * the turn-level semantic — if the assistant tagged the cite as [recalled],
+ * the turn-level semantic — if the assistant tagged the cite as [applied],
  * the operator-or-skip contract applies. Per TASK-04 invariant, cite_ids and
  * cite_commitments are parallel index-aligned arrays (length-N each).
  *
@@ -131,8 +136,9 @@ function formatContractMissingReminders({ assistant_turns, idTypeMap }) {
     const citeTags = Array.isArray(turn.cite_tags) ? turn.cite_tags : [];
     const commitments = Array.isArray(turn.cite_commitments) ? turn.cite_commitments : [];
 
-    // Turn-level: the [recalled] tag must appear in the turn's tag set.
-    if (!citeTags.includes("recalled")) continue;
+    // Turn-level: the [applied] tag must appear in the turn's tag set
+    // (v2.1.0-rc.1 ADJ-P4-1: legacy [recalled] is remapped to [applied]).
+    if (!citeTags.includes("applied")) continue;
 
     // Iterate by cite_ids.length — sentinel entries don't have ids so they
     // contribute zero iterations even if cite_tags carries "none".
@@ -160,7 +166,7 @@ function formatContractMissingReminders({ assistant_turns, idTypeMap }) {
   const reminders = [];
   for (const id of offenders) {
     reminders.push(
-      `⚠ KB: ${id} cited as [recalled] but missing contract; add \`→ edit:<glob>\` or \`→ skip:<reason>\` next turn`,
+      `⚠ KB: ${id} cited as [applied] but missing contract; add \`→ edit:<glob>\` or \`→ skip:<reason>\` next turn`,
     );
   }
   return reminders;

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

@@ -18,7 +18,10 @@
 //     auto-ships to cc/codex/cursor with no install pipeline change.
 //
 // Vocabulary contract (mirrored 1:1 with the TS source):
-//   - cite_tags enum: planned | recalled | chained-from | dismissed | none
+//   - 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.
 //   - operator kinds: edit | not_edit | require | forbid
 //     (source token `!edit:` → schema kind `not_edit`)
 //   - skip:<reason> captures everything after the first colon, so
@@ -29,31 +32,44 @@
 const ID_RE = /^K[TP]-[A-Z]+-\d+$/;
 const SENTINEL_RE = /^KB:\s*none\b\s*(?:\[[^\]]*\])?\s*$/i;
 // v2.0.0-rc.27 TASK-003 (audit §2.18): multi-id citations supported via
-// comma-separated ID group. Mirrors packages/shared/src/cite-line-parser.ts.
-const FULL_RE =
-  /^KB:\s+(K[TP]-[A-Z]+-\d+(?:\s*,\s*K[TP]-[A-Z]+-\d+)*)(?:\s+\(([^)]*)\))?(?:\s+\[([^\]]+)\])?(?:\s+→\s*(.+))?\s*$/;
+// comma-separated ID group. v2.1.0-rc.1 P4 (F3/S62): each id may carry an
+// optional `<store>:` prefix. Mirrors packages/shared/src/cite-line-parser.ts.
+const QUALIFIED_ID = "(?:[^\\s,:]+:)?K[TP]-[A-Z]+-\\d+";
+const FULL_RE = new RegExp(
+  "^KB:\\s+(" +
+    QUALIFIED_ID +
+    "(?:\\s*,\\s*" +
+    QUALIFIED_ID +
+    ")*)(?:\\s+\\(([^)]*)\\))?(?:\\s+\\[([^\\]]+)\\])?(?:\\s+→\\s*(.+))?\\s*$",
+);
 const CHAINED_FROM_ID_RE = /chained-from\s+(K[TP]-[A-Z]+-\d+)/i;
 
-const ALLOWED_TAGS = new Set([
-  // v2.0.0-rc.37 NEW-1: new simplified 2-state tag set ([applied] / [dismissed]).
-  // Old 4-state tags (planned / recalled / chained-from) accepted for
-  // backward compat — they continue to parse and count toward cite-coverage
-  // so in-flight workspaces don't lose their existing audit signal.
-  "applied",
-  "dismissed",
-  // Legacy tags (rc ≤36).
-  "planned",
-  "recalled",
-  "chained-from",
-  "none",
-]);
+// Split `<store>:<id>` into qualifier + local id; bare id → null qualifier.
+function splitStorePrefix(token) {
+  const colon = token.lastIndexOf(":");
+  return colon === -1
+    ? { store: null, id: 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",
+};
 
 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.
   const head = rawTag.trim().split(/[\s:]+/)[0].toLowerCase();
-  return ALLOWED_TAGS.has(head) ? head : "none";
+  if (head === "applied" || head === "dismissed" || head === "none") {
+    return head;
+  }
+  return LEGACY_CITE_TAG_REMAP[head] || "none";
 }
 
 function parseContractTail(tail) {
@@ -89,17 +105,21 @@ function parseLine(line) {
   const trimmed = line.trim();
   if (trimmed.length === 0) return null;
   if (SENTINEL_RE.test(trimmed)) {
-    return { ids: [], tag: "none", commitment: null };
+    return { ids: [], stores: [], tag: "none", commitment: null };
   }
   const fullMatch = trimmed.match(FULL_RE);
   if (fullMatch) {
     // v2.0.0-rc.27 TASK-003 (audit §2.18): split + revalidate each id;
-    // capture chained-from tail id when present.
-    const primaryIds = fullMatch[1]
+    // capture chained-from tail id when present. v2.1.0-rc.1 P4 (F3): strip +
+    // surface any `<store>:` prefix into a parallel stores array.
+    const split = fullMatch[1]
       .split(",")
       .map((part) => part.trim())
-      .filter((part) => part.length > 0);
-    if (primaryIds.some((id) => !ID_RE.test(id))) return null;
+      .filter((part) => part.length > 0)
+      .map(splitStorePrefix);
+    if (split.some((entry) => !ID_RE.test(entry.id))) return null;
+    const primaryIds = split.map((entry) => entry.id);
+    const primaryStores = split.map((entry) => entry.store);
 
     const rawTag = fullMatch[3];
     const tag = parseTag(rawTag);
@@ -114,6 +134,7 @@ function parseLine(line) {
 
     return {
       ids: primaryIds.concat(chainedIds),
+      stores: primaryStores.concat(chainedIds.map(() => null)),
       tag,
       commitment: parseContractTail(fullMatch[4]),
     };
@@ -131,14 +152,15 @@ function parseLine(line) {
  * embedded id as an additional cite_id. cite_tags carries one tag per LINE.
  */
 function parseCiteLine(raw) {
-  const result = { cite_ids: [], cite_tags: [], cite_commitments: [] };
+  const result = { cite_ids: [], cite_tags: [], cite_commitments: [], cite_stores: [] };
   if (typeof raw !== "string") return result;
   for (const line of raw.split(/\r?\n/)) {
     const parsed = parseLine(line);
     if (!parsed) continue;
     result.cite_tags.push(parsed.tag);
-    for (const id of parsed.ids) {
-      result.cite_ids.push(id);
+    for (let i = 0; i < parsed.ids.length; i += 1) {
+      result.cite_ids.push(parsed.ids[i]);
+      result.cite_stores.push(parsed.stores[i] == null ? null : parsed.stores[i]);
     }
     if (parsed.commitment !== null) {
       // v2.0.0-rc.27.1 (Codex review fix): cite_commitments MUST be index-

package/templates/hooks/lib/injection-log.cjs

@@ -0,0 +1,91 @@
+// v2.2 HK3-telemetry (W3-T1): injection-side telemetry. `.fabric/metrics.jsonl`
+// (server) records the CONSUMPTION side — which knowledge the agent actually
+// fetched/consumed. But nothing recorded the INJECTION side — which knowledge a
+// hook OFFERED the agent at SessionStart / PreToolUse. Without that denominator
+// the "true hit rate" (consumed ÷ injected) cannot be computed: a high consume
+// count tells you nothing if the hook injected ten times as many entries.
+//
+// This lib appends one row per injection to `.fabric/injections.jsonl`:
+//   { ts, surface: "broad"|"narrow", count, stable_ids: [...], revision_hash }
+//
+// Best-effort + synchronous: hooks are short-lived processes, so a sync append
+// is simpler than threading async, and ANY failure is swallowed — telemetry
+// must never break or delay the hook (failure invariant: silent). Concurrent
+// writers from multiple windows are serialized with an advisory lock (see
+// appendLockedLine below) so a contended write can't corrupt a line.
+
+const { appendFileSync, mkdirSync, openSync, closeSync, statSync, rmSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+
+// Multi-window concurrency guard (ADJ-W3-INJECTION-CONCURRENCY): the same repo
+// is frequently edited from several client sessions at once, so multiple hook
+// processes can append to injections.jsonl simultaneously. A bare appendFileSync
+// can interleave a partial write under contention and corrupt a line. We guard
+// each append with an advisory lock file created atomically via O_EXCL ("wx"):
+//   - acquired  → write the row, then release the lock
+//   - contended → DROP this row. Telemetry is best-effort; a missing row only
+//                 shrinks the denominator slightly, and dropping is what keeps
+//                 the ledger from ever being corrupted by an interleave.
+//   - stale     → a holder that crashed leaves the lock behind; reclaim it once
+//                 past STALE_LOCK_MS so contention can't wedge forever.
+const STALE_LOCK_MS = 5000;
+
+function appendLockedLine(path, line) {
+  const lockPath = `${path}.lock`;
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx"); // atomic create-exclusive = acquire
+  } catch (err) {
+    if (!err || err.code !== "EEXIST") return; // unexpected → drop (best-effort)
+    try {
+      if (Date.now() - statSync(lockPath).mtimeMs <= STALE_LOCK_MS) return; // fresh holder → drop
+      rmSync(lockPath, { force: true }); // stale holder crashed → reclaim
+      fd = openSync(lockPath, "wx");
+    } catch {
+      return; // racing another reclaimer → drop
+    }
+  }
+  try {
+    closeSync(fd);
+    appendFileSync(path, line);
+  } finally {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      /* lock already released */
+    }
+  }
+}
+
+/**
+ * Append one injection record to `<projectRoot>/.fabric/injections.jsonl`.
+ *
+ * @param {string} projectRoot
+ * @param {{ surface: "broad"|"narrow", stableIds?: string[], count?: number, revisionHash?: string|null, ts?: number }} record
+ */
+function logInjection(projectRoot, record) {
+  try {
+    if (!projectRoot || !record || typeof record.surface !== "string") {
+      return;
+    }
+    const stableIds = Array.isArray(record.stableIds) ? record.stableIds.filter((id) => typeof id === "string") : [];
+    const count = typeof record.count === "number" ? record.count : stableIds.length;
+    if (count <= 0) {
+      return; // nothing injected → no row (keeps the denominator honest)
+    }
+    const row = {
+      ts: typeof record.ts === "number" ? record.ts : Date.now(),
+      surface: record.surface,
+      count,
+      stable_ids: stableIds,
+      revision_hash: typeof record.revisionHash === "string" ? record.revisionHash : null,
+    };
+    const path = join(projectRoot, ".fabric", "injections.jsonl");
+    mkdirSync(dirname(path), { recursive: true });
+    appendLockedLine(path, `${JSON.stringify(row)}\n`);
+  } catch {
+    // Telemetry is best-effort — never crash or delay the hook.
+  }
+}
+
+module.exports = { logInjection, appendLockedLine };

package/templates/hooks/lib/state-store.cjs

@@ -21,7 +21,9 @@
  * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
  */
 
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+// Namespace import (not destructured) so the atomic write goes through a single
+// mutable fs reference — also what the atomicity tests spy on (ISS-016).
+const fs = require("node:fs");
 const { dirname, join } = require("node:path");
 
 const CACHE_DIR_REL = join(".fabric", ".cache");
@@ -30,11 +32,31 @@ function cachePath(projectRoot, fileName) {
   return join(projectRoot, CACHE_DIR_REL, fileName);
 }
 
+// ISS-016: write to a unique temp file then rename over the target. rename is
+// atomic on POSIX, so a reader sees either the old or the new file in full —
+// never a truncated/garbled write from a crash or concurrent writer. The temp
+// suffix (pid + clock) keeps concurrent windows from colliding on the temp.
+function atomicWrite(path, data) {
+  fs.mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, path);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // best-effort temp cleanup
+    }
+    throw err;
+  }
+}
+
 function readJsonState(projectRoot, fileName, validate) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(fs.readFileSync(path, "utf8"));
     if (typeof validate === "function" && !validate(parsed)) return null;
     return parsed;
   } catch {
@@ -43,10 +65,8 @@ function readJsonState(projectRoot, fileName, validate) {
 }
 
 function writeJsonState(projectRoot, fileName, value) {
-  const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(value));
+    atomicWrite(cachePath(projectRoot, fileName), JSON.stringify(value));
     return true;
   } catch {
     return false;
@@ -55,19 +75,17 @@ function writeJsonState(projectRoot, fileName, value) {
 
 function readTextState(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    return readFileSync(path, "utf8").trim();
+    return fs.readFileSync(path, "utf8").trim();
   } catch {
     return null;
   }
 }
 
 function writeTextState(projectRoot, fileName, text) {
-  const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, String(text));
+    atomicWrite(cachePath(projectRoot, fileName), String(text));
     return true;
   } catch {
     return false;
@@ -80,5 +98,6 @@ module.exports = {
   writeJsonState,
   readTextState,
   writeTextState,
+  atomicWrite,
   CACHE_DIR_REL,
 };

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

@@ -43,6 +43,10 @@ Parse user's prompt for time-window (`今日` / `last week`), topic keyword (`rc
 
 Read `.fabric/fabric-config.json`; resolve `archive_max_candidates_per_batch` (default 8), `archive_max_recent_paths` (default 20), `archive_digest_max_sessions` (default 10). Missing file → defaults silently.
 
+### 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` (alias + UUID); that is where `fab_extract_knowledge` persists. Single-store / no global config → the lone store (back-compat). After persisting, **echo the target store alias** to the user (`归档到 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.
+
 ### UX i18n Policy
 
 Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`); emit user-facing prose in resolved variant. Protected tokens (MCP tool names, schema fields, the verbatim `强 team` / `强 personal` / `默认 team` heuristic) NEVER translated. `AskUserQuestion` policy: `header` + `question` translate; `options[]` stay English (routing keys).

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

@@ -0,0 +1,53 @@
+---
+name: fabric-audit
+description: 知识库语义淘汰门面 — 审计 KB 健康并以 deprecate-over-delete + rescue-before-delete 收口陈旧/孤儿/被取代条目。引擎是 `fabric doctor`；本 skill 按用户意图挑动作并守「不硬删、先抢救」红线。Triggers 审计知识库/清理陈旧知识/知识库体检/deprecate 条目/prune stale knowledge/知识库瘦身/淘汰旧决策.
+---
+
+# fabric-audit — 知识库语义淘汰
+
+知识库 *维护期* 的对话入口:体检 KB,把陈旧 / 孤儿 / 被取代的条目按 **语义淘汰** 收口 —— 而不是一删了之。CLI (`fabric doctor`) 是引擎(跑 lint、算 health、给 orphan/stale 信号);本 skill 按用户意图挑动作,并守两条红线:**deprecate-over-delete** 与 **rescue-before-delete**。
+
+写新条目用 `fabric-archive`;批量审 pending 用 `fabric-review`;本 skill 专管 *已归档条目的退役*。
+
+## When to use
+
+- 「审计 / 体检知识库」「知识库健康度怎样?」
+- 「清理陈旧知识」「这些旧决策还要吗?」「知识库瘦身」
+- 发布 / 大重构前想把过时知识收口。
+- doctor 报了 orphan / stale / 低 health,想逐条处置。
+
+## When NOT to use
+
+- 写 / 提议新知识条目 → `fabric-archive`。
+- 批量审 `.fabric/knowledge/pending/` 的 draft → `fabric-review`。
+- store 运维 / 同步 → `fabric-store` / `fabric-sync`。
+
+## 两条红线
+
+1. **deprecate-over-delete**:陈旧 ≠ 该删。一条「当时为什么这么决策」的 decision/pitfall 即使方案已换,其 **rationale 仍是知识**。退役 = 降 maturity / 标记 deprecated(保留正文 + 记录被什么取代),而非 `rm`。删除只用于「从未成立 / 纯噪声 / 重复」的条目。
+2. **rescue-before-delete**:任何 *打算删* 的条目,删前必做抢救检查 —— 它是否携带别处没有的独特 rationale / 反例 / 边界?有则先 **merge 进取代它的条目**(或在新条目加 `related` 边指回),再删空壳。抢救检查没做过,不许删。
+
+## 意图 → 动作映射
+
+| 意图 | 动作 |
+|---|---|
+| 体检 / 健康度 | `fabric doctor`(读 lint + health rollup);零阻断,只报告 |
+| 找孤儿 / 陈旧条目 | `fabric doctor`(消费 orphan / stale / orphan-demote 信号) |
+| 退役一条陈旧条目 | **不删** → 降 maturity(proven→verified→draft)或在 frontmatter 标 deprecated + 记 superseded-by;经 `fabric-review` 落盘 |
+| 删一条「从未成立 / 重复」条目 | 先跑 rescue 检查(独特 rationale?有则 merge/加 related);确认空壳后才删 |
+| 被取代但有价值 | rescue:把独特 rationale merge 进取代条目,新条目加 `related` 边指回,再退役旧条目 |
+
+## 流程(逐条处置)
+
+1. `fabric doctor` 取 KB health + orphan/stale 候选清单(引擎给信号,本 skill 不自算)。
+2. 对每个候选判 **三态**:still-valid(留) / superseded(退役,走 deprecate) / never-valid(删,走 rescue 检查)。
+3. superseded → deprecate:降 maturity 或标 deprecated + `superseded-by`,保留正文 rationale。
+4. never-valid → rescue-before-delete:独特知识?有则 merge + `related`,无则删空壳。
+5. 处置经 `fabric-review` skill 落盘(本 skill 给决策,review 做写入),保持单一写路径。
+
+## Constraints
+
+- 本 skill **只读 + 给处置建议**;实际写入(降级 / 标记 / 删)经 `fabric-review` 的写路径,不自行改 `.fabric/knowledge/`。
+- NEVER 绕过 rescue 检查直接删;删前 MUST 先跑抢救检查。删是最后手段,默认是 deprecate。
+- `agents.meta.json` 派生态严禁手改;退役动作改的是 `.fabric/knowledge/<type>/` 下 markdown 的 frontmatter(maturity / deprecated / superseded-by),再 `fabric doctor --fix` reconcile。
+- health / orphan / stale 一律取自 `fabric doctor` 的 JSON 输出,不在 skill 内重算(单一真源)。

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

@@ -0,0 +1,48 @@
+---
+name: fabric-connect
+description: 知识图谱关联门面 — 发现 KB 条目间隐藏关联并回写 H2 `related` 图边。读 fab_recall/fab_plan_context 看候选, 按语义/共路径/共引提议 related 边, 经 fabric-review 写路径落盘。Triggers 连接知识/找关联条目/建知识图谱/link related entries/补 related 边/知识库连通性.
+---
+
+# fabric-connect — 知识图谱关联
+
+把孤立的 KB 条目连成图:发现彼此**隐藏关联**(同一决策的正反面、pitfall↔规避它的 guideline、被取代↔取代),回写到 frontmatter 的 `related: [<stable_id>...]` 图边(v2.2 H2)。下游 `fab_recall include_related:true` 据此一跳拉回连通知识。
+
+`related` 是**有向引用**(A.related=[B] 表示「读 A 时也该看 B」),按需补反向边(B.related=[A])。
+
+## When to use
+
+- 「把这些知识连起来」「找出相关条目」「补 related 边」
+- 「知识库连通性怎样?」「有哪些孤岛条目?」
+- 新增一批条目后想建立彼此引用。
+
+## When NOT to use
+
+- 写新条目 → `fabric-archive`。
+- 审 pending / 退役陈旧 → `fabric-review` / `fabric-audit`。
+- 检索时临时拉关联 → 直接 `fab_recall include_related:true`(无需建边)。
+
+## 关联类型(提议 related 边的判据)
+
+| 类型 | 例 |
+|---|---|
+| 互补 | decision「用 JWT」 ↔ pitfall「JWT 过期未刷新踩坑」 |
+| 规避 | pitfall「sprite 黑边」 ↔ guideline「premultiplyAlpha 正确设置」 |
+| 取代 | 旧 decision ↔ 取代它的新 decision(配合 deprecated/superseded-by) |
+| 同域 | 同一子系统 / 共 relevance_paths 的条目 |
+| 引用链 | A 的 rationale 依赖 B 的结论 |
+
+## 流程
+
+1. `fab_recall(paths=[...])` 或 `fab_plan_context` 拿候选 + 现有 `related`(读 description.related 看已连状态)。
+2. 对候选两两/成簇判隐藏关联(用上表判据);只提议**高置信**边,不为「话题相邻」乱连(噪声边稀释图价值)。
+3. 每条提议 = `(源 id, 目标 id, 类型, 一句理由)`;按需提议反向边。
+4. 落盘经 `fabric-review` 写路径:在源条目 frontmatter 的 `related` inline 数组追加目标 stable_id;`fabric doctor --fix` reconcile 进 agents.meta。
+5. 回报新增/反向边数 + 连通性变化(孤岛减少)。
+
+## Constraints
+
+- 本 skill **只提议 + 经 review 写路径落盘**;不自行改 `.fabric/knowledge/`,不手改 `agents.meta.json`(派生态)。
+- `related` MUST 只填**真实存在的 stable_id**(先 `fab_recall` 验证目标在库);NEVER 编造 / 指向 pending。
+- **稀疏优于稠密**:宁缺毋滥。只连高置信关联;低置信「相邻」不连(图的信噪比比覆盖率重要)。
+- 反向边按需补,不强制双向(有向语义:A 该带出 B ≠ B 该带出 A)。
+- 写 `related` 复用 H2 字段(`fabric-review` 的 modify 路径);schema 已支持,无需迁移。

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

@@ -40,6 +40,10 @@ Read `.fabric/fabric-config.json` for tunables (defaults if absent):
 
 First-run vs re-run by state file (ENOENT or `phase != complete && proposed == 0` → first-run window).
 
+### Store routing (v2.1 multi-store)
+
+Import requires an **explicit target store** (E7) — mined entries are NOT auto-routed. Resolve candidates via `fabric scope-explain team` (writable stores in the read-set); if more than one writable store exists, `AskUserQuestion` for the target store alias before persisting (header/question translate, the alias options stay English routing keys). Single writable store → use it. Persist through `fab_extract_knowledge` with the chosen store; echo the target alias. Never write to a store the project did not declare (read-set bound).
+
 ## UX i18n Policy
 
 Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`). Emit prose per variant. Protected tokens NEVER translate (`fab_extract_knowledge`, `fab_review`, `.fabric/.import-state.json`, all enum strings, `MUST`/`NEVER`). Full 5-class taxonomy → `Read .../ref/i18n-policy.md`.

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

@@ -40,6 +40,12 @@ Read `.fabric/fabric-config.json`; resolve:
 
 Missing or unreadable → defaults silently.
 
+### Store routing (v2.1 multi-store)
+
+Review iterates **per-store** — the read-set may span multiple stores (`fabric scope-explain team` → resolved `readSet.stores`). Pending/backlog is reported per-store (NOT aggregated into one undifferentiated pile); each candidate's provenance store is surfaced in cites as `KB: <store-alias>:<id>`. Promotion (draft → verified/proven) is a normal edit + git commit **inside that store's own repo** — no cross-store move. A `dismissed`/`modify` that flips layer between team and personal still goes through `AskUserQuestion`. Never read `~/.fabric` store trees directly; go through the MCP recall path / `scope-explain`.
+
+`Read ref/cite-contract.md` (v2.2 SK5) for the authoritative cite-contract reference — operator syntax, skip/dismissed reason dictionaries, type routing, audit semantics, backward-compat, and the adjudication ladder (AI-self → multi-LLM cold-eval → non-blocking queue) — sunk out of the bootstrap so cite/governance depth lives here, not in `.fabric/AGENTS.md`.
+
 ### UX i18n Policy
 
 Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`); emit user-facing prose in resolved variant. Protected tokens (`fab_review`, `fab_extract_knowledge`, `relevance_scope`, layer/scope enums, `stable_id`, the verbatim `强 team` / `强 personal` / `默认 team` block) NEVER translated. `AskUserQuestion` policy: `header` + `question` translate; `options[]` stay English (routing keys).