@fenglimg/fabric-cli 2.2.0-rc.4 → 2.2.0-rc.8

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

@@ -0,0 +1,117 @@
+/**
+ * v2.2 dual-sink (Goal A / D4): nudge_mode + observe.* resolver for hook scripts.
+ *
+ * This lib answers ONE question for the human-facing sink: given the configured
+ * nudge_mode preset, the per-event observe.* overrides, and the event's
+ * structural gate (PreToolUse hit / Stop value), should this lifecycle event
+ * emit a human-facing `systemMessage`, and at what verbosity?
+ *
+ * CORE INVARIANT (D5 / KT-DEC-0007): this resolver governs ONLY the human sink.
+ * It has NO say over the AI sink (`hookSpecificOutput.additionalContext`). The
+ * model receives the same knowledge regardless of how quiet the human channel
+ * is — flow ⊥ observation. There is deliberately no `emitAi()` here; callers
+ * always compute and emit the AI payload unconditionally, then ask this resolver
+ * whether to additionally surface a human breadcrumb. The dedicated invariant
+ * test asserts that no nudge_mode / observe combination changes the AI branch.
+ *
+ * Resolution order for `resolveHumanSink(projectRoot, event, gate)`:
+ *   1. observe.<event> === false      → suppress (explicit per-event mute wins)
+ *   2. structural gate fails           → suppress (PreToolUse miss / Stop low-value:
+ *      nothing meaningful to show the human, mode-independent per C5/D2/D6)
+ *   3. observe.<event> === true        → emit (explicit per-event opt-in)
+ *   4. nudge_mode === "silent"         → suppress (global human-channel mute)
+ *   5. otherwise                       → emit at the preset's verbosity
+ *
+ * `verbosity` (minimal | normal | verbose) is forwarded to the renderer so it
+ * can scale the human breadcrumb's detail; it never affects the AI payload.
+ *
+ * Never-throw contract: any read/parse failure degrades to the "normal" preset
+ * with the structural gate respected — a malfunctioning config must not silence
+ * the human channel by surprise (it falls back to the historical visible
+ * behavior), nor block the hook.
+ */
+
+const { readConfig } = require("./config-cache.cjs");
+
+const NUDGE_MODES = ["silent", "minimal", "normal", "verbose"];
+const DEFAULT_NUDGE_MODE = "normal";
+// The three observe.* event keys, mirroring observeConfigSchema in
+// packages/shared/src/schemas/fabric-config.ts. Hooks pass the matching key.
+const OBSERVE_EVENTS = ["session_start", "pre_tool_use", "stop"];
+
+/**
+ * Resolve the configured nudge_mode preset. Unknown / absent → "normal".
+ */
+function readNudgeMode(projectRoot) {
+  try {
+    const v = readConfig(projectRoot).nudge_mode;
+    return typeof v === "string" && NUDGE_MODES.includes(v) ? v : DEFAULT_NUDGE_MODE;
+  } catch {
+    return DEFAULT_NUDGE_MODE;
+  }
+}
+
+/**
+ * Resolve the per-event observe.* override for one event. Returns a strict
+ * boolean when explicitly set, otherwise undefined (preset decides). Tolerant of
+ * a malformed observe value (non-object → undefined).
+ */
+function readObserveOverride(projectRoot, event) {
+  try {
+    const observe = readConfig(projectRoot).observe;
+    if (!observe || typeof observe !== "object") return undefined;
+    const v = observe[event];
+    return typeof v === "boolean" ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Decide whether `event` should emit a human-facing systemMessage, and at what
+ * verbosity. `gate` carries the event's structural signal:
+ *   - { hit: boolean }       for pre_tool_use (false = narrow miss → suppress)
+ *   - { highValue: boolean } for stop         (false = no high-value archive
+ *                                              candidate → suppress, D6 value-gate)
+ *   - {}                     for session_start (no structural gate)
+ * Omitting a gate field means "gate passes" (e.g. session_start never gates).
+ *
+ * Returns { emitHuman: boolean, verbosity: "minimal"|"normal"|"verbose", mode }.
+ */
+function resolveHumanSink(projectRoot, event, gate) {
+  const mode = readNudgeMode(projectRoot);
+  const verbosity = mode === "silent" ? "minimal" : mode;
+  const override = OBSERVE_EVENTS.includes(event)
+    ? readObserveOverride(projectRoot, event)
+    : undefined;
+
+  // 1. explicit per-event mute wins over everything (even a hit).
+  if (override === false) return { emitHuman: false, verbosity, mode };
+
+  // 2. structural gate (mode-independent, C5/D2/D6): nothing to show → mute.
+  const g = gate || {};
+  if (event === "pre_tool_use" && g.hit === false) {
+    return { emitHuman: false, verbosity, mode };
+  }
+  if (event === "stop" && g.highValue === false) {
+    return { emitHuman: false, verbosity, mode };
+  }
+
+  // 3. explicit per-event opt-in (gate already passed above).
+  if (override === true) return { emitHuman: true, verbosity, mode };
+
+  // 4. global human-channel mute.
+  if (mode === "silent") return { emitHuman: false, verbosity, mode };
+
+  // 5. preset default — emit at the preset's verbosity.
+  return { emitHuman: true, verbosity, mode };
+}
+
+module.exports = {
+  readNudgeMode,
+  readObserveOverride,
+  resolveHumanSink,
+  NUDGE_MODES,
+  DEFAULT_NUDGE_MODE,
+  OBSERVE_EVENTS,
+};

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

@@ -24,6 +24,7 @@
 // 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 fsp = require("node:fs/promises");
 const { dirname, join } = require("node:path");
 
 const CACHE_DIR_REL = join(".fabric", ".cache");
@@ -52,6 +53,22 @@ function atomicWrite(path, data) {
   }
 }
 
+async function atomicWriteAsync(path, data) {
+  await fsp.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await fsp.writeFile(tmp, data);
+    await fsp.rename(tmp, path);
+  } catch (err) {
+    try {
+      await fsp.rm(tmp, { force: true });
+    } catch {
+      // best-effort temp cleanup
+    }
+    throw err;
+  }
+}
+
 function readJsonState(projectRoot, fileName, validate) {
   const path = cachePath(projectRoot, fileName);
   if (!fs.existsSync(path)) return null;
@@ -64,6 +81,17 @@ function readJsonState(projectRoot, fileName, validate) {
   }
 }
 
+async function readJsonStateAsync(projectRoot, fileName, validate) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    const parsed = JSON.parse(await fsp.readFile(path, "utf8"));
+    if (typeof validate === "function" && !validate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
 function writeJsonState(projectRoot, fileName, value) {
   try {
     atomicWrite(cachePath(projectRoot, fileName), JSON.stringify(value));
@@ -73,6 +101,15 @@ function writeJsonState(projectRoot, fileName, value) {
   }
 }
 
+async function writeJsonStateAsync(projectRoot, fileName, value) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function readTextState(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
   if (!fs.existsSync(path)) return null;
@@ -83,6 +120,15 @@ function readTextState(projectRoot, fileName) {
   }
 }
 
+async function readTextStateAsync(projectRoot, fileName) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    return (await fsp.readFile(path, "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+
 function writeTextState(projectRoot, fileName, text) {
   try {
     atomicWrite(cachePath(projectRoot, fileName), String(text));
@@ -92,12 +138,26 @@ function writeTextState(projectRoot, fileName, text) {
   }
 }
 
+async function writeTextStateAsync(projectRoot, fileName, text) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   cachePath,
   readJsonState,
+  readJsonStateAsync,
   writeJsonState,
+  writeJsonStateAsync,
   readTextState,
+  readTextStateAsync,
   writeTextState,
+  writeTextStateAsync,
   atomicWrite,
+  atomicWriteAsync,
   CACHE_DIR_REL,
 };

package/templates/hooks/lib/summary-fallback.cjs

@@ -2,8 +2,8 @@
  * rc.35 TASK-06 (P0-10.b) — summary-fallback library.
  *
  * Resolves opaque hint entries (where `entry.summary === entry.id` so the
- * AI sees no information beyond the id) by reading the entry's markdown
- * file at `.fabric/knowledge/<type>/<id>--<slug>.md`, extracting the first
+ * AI sees no information beyond the id) by reading the entry's markdown file
+ * from mounted store `knowledge/<type>/<id>--<slug>.md`, extracting the first
  * paragraph under `## Summary`, and substituting that text into the entry
  * before the hook renders it.
  *
@@ -33,11 +33,13 @@
  */
 
 const { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } = require("node:fs");
+const { homedir } = require("node:os");
 const { join } = require("node:path");
 
 const CACHE_DIR_REL = ".fabric/.cache";
 const CACHE_FILE_REL = ".fabric/.cache/summary-fallback.json";
-const KNOWLEDGE_DIR_REL = ".fabric/knowledge";
+const GLOBAL_CONFIG_FILE = "fabric-global.json";
+const PROJECT_CONFIG_REL = ".fabric/fabric-config.json";
 const SUMMARY_MAX_LEN = 80;
 const KNOWLEDGE_TYPE_DIRS = ["decisions", "pitfalls", "guidelines", "models", "processes"];
 
@@ -112,7 +114,60 @@ function _writeCache(projectRoot, payload) {
 }
 
 /**
- * Scan `.fabric/knowledge/<type>/` for the canonical `<id>--<slug>.md`
+ * Return mounted store directories in the project's read-set
+ * (`required_stores` plus implicit personal). This hook helper is deliberately
+ * tiny and best-effort: malformed config degrades to an empty read-set rather
+ * than throwing during a shell hook.
+ */
+function _readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function _globalRoot() {
+  return join(process.env.FABRIC_HOME || homedir(), ".fabric");
+}
+
+function _storeDir(globalRoot, store) {
+  return join(globalRoot, "stores", store.mount_name || store.store_uuid);
+}
+
+function _readSetStoreDirs(projectRoot) {
+  const globalRoot = _globalRoot();
+  const global = _readJson(join(globalRoot, GLOBAL_CONFIG_FILE));
+  if (!global || !Array.isArray(global.stores)) return [];
+  const project = _readJson(join(projectRoot, PROJECT_CONFIG_REL)) || {};
+  const required = Array.isArray(project.required_stores) ? project.required_stores : [];
+  const stores = [];
+
+  for (const req of required) {
+    if (!req || typeof req.id !== "string") continue;
+    const matched = global.stores.find(
+      (store) => store && !store.personal && (store.alias === req.id || store.store_uuid === req.id),
+    );
+    if (matched) stores.push(matched);
+  }
+
+  const personal = global.stores.find((store) => store && store.personal);
+  if (personal) stores.push(personal);
+
+  return stores.map((store) => ({
+    alias: typeof store.alias === "string" ? store.alias : "",
+    dir: _storeDir(globalRoot, store),
+  }));
+}
+
+function _splitQualifiedId(id) {
+  const idx = typeof id === "string" ? id.indexOf(":") : -1;
+  if (idx <= 0) return { alias: "", stableId: id };
+  return { alias: id.slice(0, idx), stableId: id.slice(idx + 1) };
+}
+
+/**
+ * Scan mounted store `knowledge/<type>/` for the canonical `<id>--<slug>.md`
  * matching `stableId`. Tries the most likely type-dir first based on the
  * entry's `type` hint, then falls back to scanning all canonical type
  * directories. Returns the absolute path or null.
@@ -121,8 +176,11 @@ function _writeCache(projectRoot, payload) {
  * once per file), so the first match wins.
  */
 function _findEntryFile(projectRoot, stableId, typeHint) {
-  const baseDir = join(projectRoot, KNOWLEDGE_DIR_REL);
-  if (!existsSync(baseDir)) return null;
+  const parsedId = _splitQualifiedId(stableId);
+  const storeDirs = _readSetStoreDirs(projectRoot).filter(
+    (store) => parsedId.alias.length === 0 || store.alias === parsedId.alias,
+  );
+  if (storeDirs.length === 0) return null;
   const tryOrder = [];
   if (typeof typeHint === "string" && typeHint.length > 0) {
     // Accept both singular and plural hints — find the plural form.
@@ -133,19 +191,23 @@ function _findEntryFile(projectRoot, stableId, typeHint) {
   for (const t of KNOWLEDGE_TYPE_DIRS) {
     if (!tryOrder.includes(t)) tryOrder.push(t);
   }
-  const prefix = `${stableId}--`;
-  for (const t of tryOrder) {
-    const typeDir = join(baseDir, t);
-    if (!existsSync(typeDir)) continue;
-    let files;
-    try {
-      files = readdirSync(typeDir);
-    } catch {
-      continue;
-    }
-    for (const f of files) {
-      if (f.startsWith(prefix) && f.endsWith(".md")) {
-        return join(typeDir, f);
+  const prefix = `${parsedId.stableId}--`;
+  for (const store of storeDirs) {
+    const baseDir = join(store.dir, "knowledge");
+    if (!existsSync(baseDir)) continue;
+    for (const t of tryOrder) {
+      const typeDir = join(baseDir, t);
+      if (!existsSync(typeDir)) continue;
+      let files;
+      try {
+        files = readdirSync(typeDir);
+      } catch {
+        continue;
+      }
+      for (const f of files) {
+        if (f.startsWith(prefix) && f.endsWith(".md")) {
+          return join(typeDir, f);
+        }
       }
     }
   }
@@ -204,6 +266,7 @@ module.exports = {
   _readCache,
   _writeCache,
   _findEntryFile,
+  _readSetStoreDirs,
   _isOpaque,
   SUMMARY_MAX_LEN,
   KNOWLEDGE_TYPE_DIRS,

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

@@ -3,12 +3,16 @@
  * lifecycle-refactor W2-T3 — PostToolUse mutation marker hook (previously
  * dormant). Closes the mutation env opened by the PreToolUse narrow hint.
  *
- * PostToolUse fires AFTER an Edit/Write/MultiEdit tool call completes. This
- * hook appends one `file_mutated` event per edited path to
- * `.fabric/events.jsonl`, carrying the `tool_call_id` so doctor can pair the
- * Pre (intent) and Post (mutation) halves of a single tool call — the per-call
- * key also guards against parallel-fire races (two concurrent edits never
- * collapse to one ledger key).
+ * PostToolUse fires AFTER a tool call completes. This hook serves two markers,
+ * both appended to `.fabric/events.jsonl` and both observation-only:
+ *   - Edit/Write/MultiEdit → one `file_mutated` event per edited path, carrying
+ *     the `tool_call_id` so doctor can pair the Pre (intent) and Post (mutation)
+ *     halves of a single call (the per-call key also guards parallel-fire races).
+ *   - Read → one `knowledge_body_read` event per Fabric knowledge file opened
+ *     (KT-DEC-0030). After retrieval collapsed to one lean tool (KT-DEC-0026),
+ *     fab_recall returns descriptions + paths only; the agent reads a body via a
+ *     NATIVE Read, and this marker is the observable trace doctor uses for the
+ *     planned → body_read → cite[applied] funnel.
  *
  * Design (lifecycle-concept-final.md §1 FROZEN invariants + §5 row7):
  *   - LOW compute: extract paths + tool_call_id, append; the hook never reads
@@ -49,6 +53,24 @@ const EVENTS_LEDGER_FILE = "events.jsonl";
 // PreToolUse narrow hint's EDIT_TOOL_NAMES so Pre/Post pair on the same set).
 const EDIT_TOOL_NAMES = new Set(["Edit", "Write", "MultiEdit"]);
 
+// KT-DEC-0030: tool names that read a file body. After retrieval collapsed to
+// one lean tool (KT-DEC-0026), the agent consumes a knowledge body via a NATIVE
+// Read of the store file — so a Read landing on a `<store>/knowledge/<type>/
+// <ID>--*.md` path is the observable "body opened" signal. Only `Read` is in
+// scope (Edit/Write already covered by the mutation marker above).
+const READ_TOOL_NAMES = new Set(["Read"]);
+
+// Matches a Fabric knowledge file path and captures the stable_id from the
+// basename. The id grammar mirrors KT-DEC-0004 (`K[PT]-(DEC|MOD|GLD|PIT|PRO)-NNNN`).
+// The path MUST sit under a `/knowledge/<type>/` segment so arbitrary Reads that
+// merely happen to embed an id-shaped token never false-fire.
+const KNOWLEDGE_BODY_PATH_RE =
+  /[\\/]knowledge[\\/][^\\/]+[\\/](K[PT]-(?:DEC|MOD|GLD|PIT|PRO)-\d{3,})--[^\\/]*\.md$/;
+
+// Captures the store alias from a multistore path (`.../stores/<alias>/...`).
+// Absent for legacy dual-root layouts → store stays undefined (still a valid event).
+const STORE_ALIAS_RE = /[\\/]stores[\\/]([^\\/]+)[\\/]/;
+
 /**
  * Read stdin (or a test-supplied raw string) as JSON. Returns null on any
  * parse failure — the hook stays silent rather than crashing the tool pipeline.
@@ -69,7 +91,6 @@ function readPayload(rawStdin) {
 /**
  * Extract the tool name. Mirrors the narrow hint's probe:
  *   - Claude Code / Codex: { tool_name, ... }
- *   - Cursor (legacy):      { tool, ... }
  */
 function extractToolName(payload) {
   if (!payload || typeof payload !== "object") return null;
@@ -79,8 +100,8 @@ function extractToolName(payload) {
 }
 
 /**
- * Extract the tool_input object, accepting both the `tool_input`
- * (Claude/Codex) and `input` (Cursor) conventions.
+ * Extract the tool_input object from the `tool_input`
+ * (Claude/Codex) convention.
  */
 function extractToolInput(payload) {
   if (!payload || typeof payload !== "object") return null;
@@ -224,6 +245,75 @@ function appendFileMutated(projectRoot, now, paths, toolCallId, toolName, sessio
   }
 }
 
+/**
+ * KT-DEC-0030: parse a Read path into a knowledge-body-read descriptor. Returns
+ * `{ stable_id, store, path }` when the path is a Fabric knowledge file, else
+ * null. `store` is omitted when no `stores/<alias>/` segment is present (legacy
+ * dual-root layout). `path` is forward-slash-normalized but NOT made
+ * project-relative — knowledge bodies live under ~/.fabric, outside the project
+ * tree, so the home-anchored path is the meaningful identifier.
+ */
+function extractKnowledgeBodyRead(filePath) {
+  if (typeof filePath !== "string" || filePath.length === 0) return null;
+  const idMatch = KNOWLEDGE_BODY_PATH_RE.exec(filePath);
+  if (idMatch === null) return null;
+  const storeMatch = STORE_ALIAS_RE.exec(filePath);
+  const slashed = filePath.split(/[\\/]/).join("/");
+  return {
+    stable_id: idMatch[1],
+    store: storeMatch !== null ? storeMatch[1] : null,
+    path: slashed,
+  };
+}
+
+/**
+ * Append one `knowledge_body_read` marker per Fabric knowledge file read.
+ * Best-effort, identical guarantees to appendFileMutated (silent on any error,
+ * skips when `.fabric/` absent). Non-knowledge reads produce zero events — the
+ * common case (the agent reads source files far more than knowledge bodies),
+ * so the hook stays a near-noop on the hot Read path.
+ */
+function appendKnowledgeBodyRead(projectRoot, now, paths, toolCallId, toolName, sessionId) {
+  try {
+    const fabricDir = join(projectRoot, FABRIC_DIR_REL);
+    if (!existsSync(fabricDir)) return;
+    const reads = Array.isArray(paths)
+      ? paths.map((p) => extractKnowledgeBodyRead(p)).filter((r) => r !== null)
+      : [];
+    if (reads.length === 0) return;
+    const tsMs = now instanceof Date ? now.getTime() : Number(now);
+    const callId =
+      typeof toolCallId === "string" && toolCallId.length > 0
+        ? toolCallId
+        : `fallback:${randomUUID()}`;
+    const validSessionId =
+      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);
+  } catch {
+    // Silent — marker failure must never block the tool pipeline.
+  }
+}
+
 // -----------------------------------------------------------------------------
 // Main — invoked as a CLI (require.main === module) and in-process by tests.
 // Wraps the entire flow in try/catch: ANY error → silent exit 0.
@@ -238,7 +328,9 @@ function main(env) {
     if (payload === null || payload === undefined) return;
 
     const toolName = extractToolName(payload);
-    if (!toolName || !EDIT_TOOL_NAMES.has(toolName)) return;
+    const isEdit = toolName && EDIT_TOOL_NAMES.has(toolName);
+    const isRead = toolName && READ_TOOL_NAMES.has(toolName);
+    if (!isEdit && !isRead) return;
 
     const toolInput = extractToolInput(payload);
     const paths = extractPaths(toolInput);
@@ -250,7 +342,13 @@ function main(env) {
         ? payload.session_id
         : null;
 
-    appendFileMutated(cwd, now, paths, toolCallId, toolName, sessionId);
+    if (isEdit) {
+      appendFileMutated(cwd, now, paths, toolCallId, toolName, sessionId);
+    } else {
+      // KT-DEC-0030: observe native Reads of store knowledge bodies. Non-
+      // knowledge Reads filter out inside appendKnowledgeBodyRead (zero events).
+      appendKnowledgeBodyRead(cwd, now, paths, toolCallId, toolName, sessionId);
+    }
   } catch {
     // Silent — never block the tool pipeline on hook failure.
   }
@@ -265,10 +363,13 @@ module.exports = {
   extractToolCallId,
   normalizePath,
   appendFileMutated,
+  extractKnowledgeBodyRead,
+  appendKnowledgeBodyRead,
   CONSTANTS: {
     FABRIC_DIR_REL,
     EVENTS_LEDGER_FILE,
     EDIT_TOOL_NAMES,
+    READ_TOOL_NAMES,
   },
 };
 

package/templates/skills/fabric/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: fabric
+description: Fabric 入口层路由 — 参考 maestro 的顺序协调方式，把用户意图分派到 fabric-archive/review/import/store/sync/audit/connect。Triggers fabric/知识库/归档/审批/store/同步/关联/审计.
+---
+
+# fabric — Fabric Skill Router
+
+这是 Fabric 相关 skills 的入口层。它只负责理解用户意图、选择正确的下游 skill、按顺序直接调用；不直接读写 `~/.fabric` store，不自行解析 store 树，也不替代底层 `fabric-*` skills 的安全门。
+
+## Routing Contract
+
+1. 先判断用户要做的是哪类 Fabric 工作。
+2. 只调用一个最合适的下游 skill；只有用户明确要求一组维护动作时，才按顺序调用多个。
+3. 每一步完成后读取结果，再决定是否继续下一步。不要并发委派，也不要用 CSV/wave worker。
+4. 如果目标涉及写入、审批、退役或关联，必须走对应下游 skill 的既有写路径；本入口 skill 不直接修改 `knowledge/`。
+5. Store 状态只通过 `fabric info`、`fabric store ...`、`fabric sync`、MCP 工具或下游 skill 获取。MUST NOT 直接遍历或执行 `~/.fabric/stores/` 内容；store 是 data-only。
+
+## Intent Map
+
+| 用户意图 | 下游 skill |
+| --- | --- |
+| 记录/归档/以后记住/always/never/下次注意 | `fabric-archive` |
+| 审批 pending、批量 approve/reject/modify/revisit/defer | `fabric-review` |
+| 从 git log、docs 或历史材料冷启动导入知识 | `fabric-import` |
+| 创建、挂载、绑定、列出、切换 write store | `fabric-store` |
+| 多 store pull --rebase + push、同步冲突处理 | `fabric-sync` |
+| 知识库体检、淘汰陈旧条目、deprecate、rescue-before-delete | `fabric-audit` |
+| 发现 KB 条目关联、补 `related` 边、知识图谱连通性 | `fabric-connect` |
+
+## State Machine
+
+### S_CLASSIFY
+
+提取：
+
+```json
+{
+  "task_type": "archive|review|import|store|sync|audit|connect",
+  "scope": "project|store|entry|paths|null",
+  "write_intent": true,
+  "confidence": "high|medium|low"
+}
+```
+
+低置信度时问 1 个短问题；不要一次性列长菜单。若用户只是说“fabric 帮我处理一下”，默认先运行 `fabric-audit` 做只读体检，再根据输出建议下一步。
+
+### S_EXECUTE
+
+按 `Intent Map` 直接调用下游 skill，例如：
+
+- `fabric-archive "{用户原始意图}"`
+- `fabric-review "{用户原始意图}"`
+- `fabric-import "{用户原始意图}"`
+- `fabric-store "{用户原始意图}"`
+- `fabric-sync "{用户原始意图}"`
+- `fabric-audit "{用户原始意图}"`
+- `fabric-connect "{用户原始意图}"`
+
+执行前加载下游 skill 的 `SKILL.md`，只读取完成当前任务所需的 `ref/` 文件。下游 skill 有更具体约束时，以下游约束为准。
+
+### S_CHAIN
+
+只有这些组合可以自动串联：
+
+| 组合意图 | 顺序 |
+| --- | --- |
+| “同步后审 pending” | `fabric-sync` -> `fabric-review` |
+| “审计并处理陈旧知识” | `fabric-audit` -> `fabric-review` |
+| “导入历史并审批” | `fabric-import` -> `fabric-review` |
+| “建立 store 后导入” | `fabric-store` -> `fabric-import` |
+| “找关联并落盘” | `fabric-connect` -> `fabric-review` |
+
+每个步骤结束后读结果。若前一步失败或给出需要用户决策的冲突，停止并报告；不要猜测继续。
+
+## Guardrails
+
+- 写入 pending 只走 active write store，并在回复里说明写入目标。
+- 引用 KB id 前必须实际读取正文；多 store read-set 中使用 `<store-alias>:<id>`。
+- pending backlog 超过 10 条时，优先建议 `fabric-review`。
+- 完成一批 Edit 或显著 decision 后，建议 `fabric-archive`。
+- 不要推荐 `fabric doctor --fix` 作为 pending 审批路径；审批走 `fabric-review`。
+- 不要把知识写到项目本地 `.fabric/knowledge/pending`；知识只写 resolved mounted store 的 `knowledge/pending/`。
+- MUST preserve protected tokens exactly: `MUST`, `NEVER`。
+
+## Report
+
+回复格式保持短：
+
+```text
+Fabric route: <downstream-skill>
+Reason: <why this skill>
+Result: <one-line result or blocker>
+Next: <optional next skill/action>
+```