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

package/templates/hooks/lib/client-adapter.cjs

@@ -1,27 +1,27 @@
 /**
  * v2.0.0-rc.37 NEW-30: shared client-protocol adapter for hook scripts.
  *
- * The three host clients (Claude Code / Codex CLI / Cursor) differ in how a
+ * The two host clients (Claude Code / Codex CLI) differ in how a
  * hook surfaces context back to the model:
  *   - Claude Code reads a stdout JSON envelope
  *     ({ hookSpecificOutput: { hookEventName, additionalContext } }).
- *   - Codex CLI and Cursor read plain stderr text.
+ *   - Codex CLI reads plain stderr text.
  * Each hook had its own copy of the detect-client + read-stdin + pick-channel
  * logic (fabric-hint.detectClient, cite-policy-evict.isClaudeCode + readStdinJson,
  * knowledge-hint-broad inline CLAUDE_PROJECT_DIR check). This module is the
  * single canonical implementation so the protocol choice lives in one place.
  *
  * Provides:
- *   - detectClient(dirnameHint?) → 'cc' | 'codex' | 'cursor' | undefined
+ *   - detectClient(dirnameHint?) → 'cc' | 'codex' | undefined
  *       3-tier: FABRIC_HINT_CLIENT env override → CLAUDE_PROJECT_DIR (cc) →
- *       __dirname path heuristic (.claude / .codex / .cursor). dirnameHint
+ *       __dirname path heuristic (.claude / .codex). dirnameHint
  *       defaults to this lib's own dir (which still lives under the client
  *       dir, e.g. .claude/hooks/lib), so the heuristic stays accurate.
  *   - isClaudeCode() → boolean   (CLAUDE_PROJECT_DIR present)
  *   - readStdinJson({ timeoutMs }) → Promise<object | null>
  *       Async stdin JSON reader; null on parse error / closed stdin / timeout.
  *   - emitContext(text, { client, eventName, streams, forceStderr }) → void
- *       Standardised output: Claude Code → stdout JSON envelope; Codex/Cursor
+ *       Standardised output: Claude Code → stdout JSON envelope; Codex
  *       → plain stderr. forceStderr pins stderr even on Claude Code (used for
  *       SessionStart one-shot reminders). Best-effort — never throws.
  *
@@ -40,7 +40,7 @@ function detectClient(dirnameHint) {
   const envClient = process.env.FABRIC_HINT_CLIENT;
   if (typeof envClient === "string" && envClient.length > 0) {
     const normalised = envClient.trim().toLowerCase();
-    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+    if (normalised === "cc" || normalised === "codex") {
       return normalised;
     }
   }
@@ -51,7 +51,6 @@ function detectClient(dirnameHint) {
   try {
     if (dir.includes(".claude/") || dir.includes(".claude\\")) return "cc";
     if (dir.includes(".codex/") || dir.includes(".codex\\")) return "codex";
-    if (dir.includes(".cursor/") || dir.includes(".cursor\\")) return "cursor";
   } catch {
     // fall through
   }
@@ -98,9 +97,69 @@ function emitContext(text, opts) {
   }
 }
 
+// v2.2 dual-sink (Goal A / D7): two-channel emit. Unlike emitContext (which
+// picks ONE channel), emitDualSink surfaces a knowledge breadcrumb to BOTH the
+// human and the AI in one render, split into two fields, with the protocol
+// shaped per client:
+//
+//   cc / codex (symmetric, D7): a single stdout JSON envelope carrying
+//     { systemMessage: <human>,                          // the human sink
+//       hookSpecificOutput: { hookEventName, additionalContext: <ai> } }  // AI sink
+//     camelCase + nested. `systemMessage` is the universal human-facing field
+//     (verified against official hook docs in the mode④ design session); it is
+//     what fixes the "stderr human channel is dead on CC" gap — CC suppresses
+//     hook stderr at exit 0, so the human never saw the old breadcrumb.
+//
+//   unknown client (detection failed, not CC): fall back to a plain stderr
+//     breadcrumb (human preferred, else ai) — no known JSON contract to target.
+//
+// Either field may be null/empty: pass { human, ai } and only the present
+// channels are written (e.g. a PreToolUse miss passes human:null → AI-only;
+// nudge_mode silent passes human:null too). The AI field is ALWAYS the caller's
+// to decide independently — this fn never derives one channel from the other,
+// preserving the flow ⊥ observation invariant (D5).
+//
+// Never-throw contract (KT-DEC-0007): every path degrades silently.
+function emitDualSink(payload, opts) {
+  const { human = null, ai = null } = payload || {};
+  const { client, eventName = "SessionStart", streams = {} } = opts || {};
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const hasHuman = typeof human === "string" && human.length > 0;
+  const hasAi = typeof ai === "string" && ai.length > 0;
+  const resolved = client || detectClient();
+  try {
+    const useEnvelope =
+      resolved === "cc" ||
+      resolved === "codex" ||
+      (resolved === undefined && isClaudeCode());
+    if (useEnvelope) {
+      const envelope = {};
+      if (hasHuman) envelope.systemMessage = human;
+      if (hasAi) {
+        envelope.hookSpecificOutput = {
+          hookEventName: eventName,
+          additionalContext: ai,
+        };
+      }
+      if (Object.keys(envelope).length > 0) {
+        stdout.write(`${JSON.stringify(envelope)}\n`);
+      }
+      return;
+    }
+    // Unknown client: no JSON contract — surface the human breadcrumb (or ai)
+    // on stderr as a last resort so something is visible.
+    const fallback = hasHuman ? human : hasAi ? ai : null;
+    if (fallback !== null) stderr.write(`${fallback}\n`);
+  } catch {
+    // best-effort — never throw
+  }
+}
+
 module.exports = {
   isClaudeCode,
   detectClient,
   readStdinJson,
   emitContext,
+  emitDualSink,
 };

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/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,100 @@
+---
+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
+
+<!-- fabric:router-intent:begin -->
+<!-- 本块由 `fabric install` 从 7 个 leaf skill 的 description Triggers 子句生成。严禁手编;改 leaf description 后重跑 `fabric install`。 -->
+
+| 用户意图(leaf description Triggers) | 下游 skill |
+| --- | --- |
+| 以后/always/never/下次/记一下;wrong-turn-revert;decision-confirm;dismissal-reason;/fabric-archive | `fabric-archive` |
+| 审批/驳回/复审/重审/approve/reject/review pending | `fabric-review` |
+| 导入历史/bootstrap fabric/mine changelog/挖掘 commit | `fabric-import` |
+| 同步知识库/sync stores/fabric-sync/解决 store 冲突/rebase 冲突 | `fabric-sync` |
+| 创建 store/挂载 store/绑定知识库/store 列表/切换写库/set up knowledge store | `fabric-store` |
+| 审计知识库/清理陈旧知识/知识库体检/deprecate 条目/prune stale knowledge/知识库瘦身/淘汰旧决策 | `fabric-audit` |
+| 连接知识/找关联条目/建知识图谱/link related entries/补 related 边/知识库连通性 | `fabric-connect` |
+
+`S_CLASSIFY` 的 `task_type` 枚举:`archive | review | import | sync | store | audit | connect`
+<!-- fabric:router-intent:end -->
+
+## State Machine
+
+### S_CLASSIFY
+
+提取：
+
+```json
+{
+  "task_type": "<Intent Map task_type 枚举之一>",
+  "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>
+```