@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.3

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

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * 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).
+ *
+ * Design (lifecycle-concept-final.md §1 FROZEN invariants + §5 row7):
+ *   - LOW compute: extract paths + tool_call_id, append; the hook never reads
+ *     or aggregates the ledger, never runs `git diff`. ALL mutation_pool /
+ *     attribution work is doctor-side (offline, §5 row7).
+ *   - hook = nudge/marker, never a gate (KT-DEC-0007): every error path ends
+ *     in a silent exit 0; we never throw upward.
+ *   - Front-stage O(1) per path: advisory-locked append, no traversal.
+ *   - Per-event session_id: threaded from the REAL payload when present
+ *     (omitted when the client omits it — the marker is still useful for the
+ *     tool_call_id pairing even without a session).
+ *   - Hooks never require() the server package — only co-located lib/*.cjs.
+ *
+ * Each emitted line matches `fileMutatedEventSchema`
+ * (packages/shared/src/schemas/event-ledger.ts):
+ *   { kind:"fabric-event", id, ts, schema_version:1, session_id?,
+ *     event_type:"file_mutated", path, tool_call_id, tool_name? }
+ *
+ * Stdout/stderr are intentionally empty — PostToolUse is observation-only and
+ * never blocks the host's tool pipeline.
+ */
+
+const { randomUUID } = require("node:crypto");
+const { existsSync } = require("node:fs");
+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");
+
+const FABRIC_DIR_REL = ".fabric";
+const EVENTS_LEDGER_FILE = "events.jsonl";
+
+// Tool names that trigger the mutation marker. PostToolUse fires on many tool
+// names across clients; we only react to the file-edit tools (matches the
+// PreToolUse narrow hint's EDIT_TOOL_NAMES so Pre/Post pair on the same set).
+const EDIT_TOOL_NAMES = new Set(["Edit", "Write", "MultiEdit"]);
+
+/**
+ * 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.
+ */
+function readPayload(rawStdin) {
+  if (typeof rawStdin !== "string" || rawStdin.length === 0) return null;
+  try {
+    const parsed = JSON.parse(rawStdin);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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;
+  if (typeof payload.tool_name === "string") return payload.tool_name;
+  if (typeof payload.tool === "string") return payload.tool;
+  return null;
+}
+
+/**
+ * Extract the tool_input object, accepting both the `tool_input`
+ * (Claude/Codex) and `input` (Cursor) conventions.
+ */
+function extractToolInput(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  if (payload.tool_input && typeof payload.tool_input === "object") {
+    return payload.tool_input;
+  }
+  if (payload.input && typeof payload.input === "object") {
+    return payload.input;
+  }
+  return null;
+}
+
+/**
+ * Pull file paths out of a tool_input object. Same three shapes the narrow
+ * hint handles (single file_path / array file_paths / MultiEdit edits[]).
+ * Returns a deduped array of strings — empty when none recognizable.
+ */
+function extractPaths(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") return [];
+  const collected = [];
+
+  if (typeof toolInput.file_path === "string" && toolInput.file_path.length > 0) {
+    collected.push(toolInput.file_path);
+  }
+  if (Array.isArray(toolInput.file_paths)) {
+    for (const p of toolInput.file_paths) {
+      if (typeof p === "string" && p.length > 0) collected.push(p);
+    }
+  }
+  if (Array.isArray(toolInput.edits)) {
+    for (const edit of toolInput.edits) {
+      if (
+        edit &&
+        typeof edit === "object" &&
+        typeof edit.file_path === "string" &&
+        edit.file_path.length > 0
+      ) {
+        collected.push(edit.file_path);
+      }
+    }
+  }
+
+  const seen = new Set();
+  const out = [];
+  for (const p of collected) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Extract the per-call id. Claude Code's PostToolUse payload carries the id of
+ * the originating tool_use block as `tool_use_id`; older drafts / other clients
+ * variously used `tool_call_id` / `call_id` / `id`. We probe in that order.
+ *
+ * Returns null when none is present — the caller then synthesizes a best-effort
+ * fallback key so the marker still lands (per W2-T3: "缺失则用 best-effort
+ * fallback key 但仍 append"). A fallback key cannot pair with the Pre half but
+ * still records the mutation, which is strictly better than dropping it.
+ */
+function extractToolCallId(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const candidates = ["tool_use_id", "tool_call_id", "call_id", "id"];
+  for (const key of candidates) {
+    const v = payload[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return null;
+}
+
+/**
+ * Normalize a path to a project-relative, forward-slash form. Drops paths that
+ * escape the project tree (mirrors appendEditIntentToLedger in the narrow
+ * hook). Returns null for out-of-tree / empty.
+ */
+function normalizePath(projectRoot, p) {
+  if (typeof p !== "string" || p.length === 0) return null;
+  let rel;
+  if (isAbsolute(p)) {
+    rel = relative(projectRoot, p);
+    if (rel.startsWith("..")) return null;
+  } else {
+    if (p.startsWith("..")) return null;
+    rel = p;
+  }
+  const slashed = rel.split(/[\\/]/).join("/");
+  return slashed.length > 0 ? slashed : null;
+}
+
+/**
+ * Append one `file_mutated` marker per edited path to `.fabric/events.jsonl`.
+ * Best-effort:
+ *   - Skips silently when `.fabric/` does not exist (project not init'd).
+ *   - Skips silently when there are no in-tree paths.
+ *   - ANY error (append, JSON throw) is swallowed — never blocks the pipeline.
+ *
+ * One JSON line per path (PIPE_BUF-atomic). The per-path lines share a single
+ * tool_call_id so doctor can group them as one tool call.
+ */
+function appendFileMutated(projectRoot, now, paths, toolCallId, toolName, sessionId) {
+  try {
+    const fabricDir = join(projectRoot, FABRIC_DIR_REL);
+    if (!existsSync(fabricDir)) return;
+    const pathList = Array.isArray(paths)
+      ? paths.map((p) => normalizePath(projectRoot, p)).filter((p) => p !== null)
+      : [];
+    if (pathList.length === 0) return;
+    const tsMs = now instanceof Date ? now.getTime() : Number(now);
+    // Best-effort fallback key when the client omits the tool-call id: the
+    // mutation is still recorded (can't pair with the Pre half, but the path
+    // signal is preserved). Per-fire UUID keeps parallel fires distinct.
+    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 =
+      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);
+  } 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.
+// -----------------------------------------------------------------------------
+
+function main(env) {
+  try {
+    const cwd = (env && env.cwd) || process.cwd();
+    const now = (env && env.now) || new Date();
+    const payload =
+      env && env.payload !== undefined ? env.payload : readPayload(env && env.stdin);
+    if (payload === null || payload === undefined) return;
+
+    const toolName = extractToolName(payload);
+    if (!toolName || !EDIT_TOOL_NAMES.has(toolName)) return;
+
+    const toolInput = extractToolInput(payload);
+    const paths = extractPaths(toolInput);
+    if (paths.length === 0) return;
+
+    const toolCallId = extractToolCallId(payload);
+    const sessionId =
+      payload && typeof payload === "object" && typeof payload.session_id === "string"
+        ? payload.session_id
+        : null;
+
+    appendFileMutated(cwd, now, paths, toolCallId, toolName, sessionId);
+  } catch {
+    // Silent — never block the tool pipeline on hook failure.
+  }
+}
+
+module.exports = {
+  main,
+  readPayload,
+  extractToolName,
+  extractToolInput,
+  extractPaths,
+  extractToolCallId,
+  normalizePath,
+  appendFileMutated,
+  CONSTANTS: {
+    FABRIC_DIR_REL,
+    EVENTS_LEDGER_FILE,
+    EDIT_TOOL_NAMES,
+  },
+};
+
+if (require.main === module) {
+  // Read stdin synchronously (small hook payloads, no concurrency concerns).
+  let stdinRaw = "";
+  try {
+    stdinRaw = require("node:fs").readFileSync(0, "utf8");
+  } catch {
+    // No stdin — proceed with empty payload (E*: no append without paths).
+  }
+  main({ cwd: process.cwd(), now: new Date(), stdin: stdinRaw });
+  process.exit(0);
+}

package/templates/hooks/session-end-marker.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * lifecycle-refactor W2-T2 — SessionEnd marker hook (previously dormant).
+ *
+ * SessionEnd fires once when a client session boots down. This hook is a
+ * PURE MARKER: it appends a single `session_ended` event (session_id + ts,
+ * via the shared envelope) to `.fabric/events.jsonl` and does NOTHING else.
+ *
+ * Design (lifecycle-concept-final.md §1 FROZEN invariants + §5 row2):
+ *   - ZERO compute: the hook never reads/aggregates the ledger. ALL
+ *     surfaced→cited→edited funnel reconciliation is doctor-side (offline).
+ *   - hook = nudge/marker, never a gate (KT-DEC-0007): every error path ends
+ *     in a silent exit 0; we never throw upward.
+ *   - Front-stage O(1): one advisory-locked append, no traversal.
+ *   - Per-event session_id: when the client omits session_id we DEGRADE by
+ *     skipping the append entirely (a marker with no session is useless for
+ *     the per-session funnel doctor reconstructs).
+ *   - Hooks never require() the server package — only the co-located lib/*.cjs.
+ *
+ * The emitted line matches `sessionEndedEventSchema`
+ * (packages/shared/src/schemas/event-ledger.ts):
+ *   { kind:"fabric-event", id, ts, schema_version:1, session_id?, event_type:"session_ended" }
+ *
+ * Stdout/stderr are intentionally empty — SessionEnd is observation-only.
+ */
+
+const { randomUUID } = require("node:crypto");
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+// W1-01 (ISS-011) parity: route the shared-ledger append through the
+// advisory-lock primitive so concurrent SessionEnd fires (multi-window) never
+// interleave a partial line. Drop-on-contention, best-effort — same primitive
+// the narrow/broad hooks use.
+const { appendLockedLine } = require("./lib/injection-log.cjs");
+
+const FABRIC_DIR_REL = ".fabric";
+const EVENTS_LEDGER_FILE = "events.jsonl";
+
+/**
+ * Read stdin (or a test-supplied raw string) as JSON. Returns null on any
+ * parse failure — the hook stays silent rather than crashing session teardown.
+ */
+function readPayload(rawStdin) {
+  if (typeof rawStdin !== "string" || rawStdin.length === 0) return null;
+  try {
+    const parsed = JSON.parse(rawStdin);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the REAL payload session_id (never a synthetic fallback). The
+ * funnel reconciliation in doctor keys on the client's own session id, so a
+ * fabricated id would silently corrupt the per-session join. Returns null when
+ * absent — the caller then skips the append (degraded, per §1).
+ */
+function extractSessionId(payload) {
+  if (
+    payload &&
+    typeof payload === "object" &&
+    typeof payload.session_id === "string" &&
+    payload.session_id.length > 0
+  ) {
+    return payload.session_id;
+  }
+  return null;
+}
+
+/**
+ * Append one `session_ended` marker to `.fabric/events.jsonl`. Best-effort:
+ *   - Skips silently when `.fabric/` does not exist (project not init'd).
+ *   - Skips silently when sessionId is null (degraded — no session to mark).
+ *   - ANY error (append, JSON throw) is swallowed — never blocks teardown.
+ */
+function appendSessionEnded(projectRoot, now, sessionId) {
+  try {
+    if (typeof sessionId !== "string" || sessionId.length === 0) return;
+    const fabricDir = join(projectRoot, FABRIC_DIR_REL);
+    if (!existsSync(fabricDir)) return;
+    const tsMs = now instanceof Date ? now.getTime() : Number(now);
+    const event = {
+      kind: "fabric-event",
+      id: `event:${randomUUID()}`,
+      ts: tsMs,
+      schema_version: 1,
+      session_id: sessionId,
+      event_type: "session_ended",
+    };
+    appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), JSON.stringify(event) + "\n");
+  } catch {
+    // Silent — marker failure must never block session teardown.
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 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.
+// -----------------------------------------------------------------------------
+
+function main(env) {
+  try {
+    const cwd = (env && env.cwd) || process.cwd();
+    const now = (env && env.now) || new Date();
+    const payload =
+      env && env.payload !== undefined ? env.payload : readPayload(env && env.stdin);
+    const sessionId = extractSessionId(payload);
+    appendSessionEnded(cwd, now, sessionId);
+  } catch {
+    // Silent — never block session teardown on hook failure.
+  }
+}
+
+module.exports = {
+  main,
+  readPayload,
+  extractSessionId,
+  appendSessionEnded,
+  CONSTANTS: {
+    FABRIC_DIR_REL,
+    EVENTS_LEDGER_FILE,
+  },
+};
+
+if (require.main === module) {
+  // Read stdin synchronously (small hook payloads, no concurrency concerns).
+  let stdinRaw = "";
+  try {
+    stdinRaw = require("node:fs").readFileSync(0, "utf8");
+  } catch {
+    // No stdin — proceed with empty payload (degrades to a no-op append).
+  }
+  main({ cwd: process.cwd(), now: new Date(), stdin: stdinRaw });
+  process.exit(0);
+}

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

@@ -113,6 +113,12 @@ Assign `relevance_scope` ∈ {narrow, broad} + derive `relevance_paths` BEFORE b
 
 `Read ref/phase-3-5-scope.md` for the 6-step relevance_paths derivation pseudocode (COLLECT → DEDUPE → BLACKLIST → PUBLIC-PREFIX GENERALIZE → SCOPE GATE → ATTACH READ-ONLY EVIDENCE), worked example (5 sample paths → glob + literal output), and narrow↔broad inline-edit re-derivation rules.
 
+### Phase 3.6 — Related-edge Extraction (§7 graph generation)
+
+For each candidate, identify the **`related`** graph edges to other KB entries — the store-qualified `stable_id`s this entry semantically links to (the decision it supersedes, the pitfall it explains, the model it instantiates). You discovered these ids during the session via `fab_recall` / plan-context, so cite the ones you actually saw, NEVER invent stable_ids. Because `fab_extract_knowledge` has no dedicated `related` input, record the candidate edges as one line inside `session_context` (e.g. `related: team:KT-DEC-0007, team:KT-PIT-0011`) so they survive to approve-time frontmatter authoring (`fabric-review` writes the canonical `related: [...]` frontmatter).
+
+**§4 privacy iron law — KT→KP is FORBIDDEN.** A **team** (`KT-*`) entry's `related` MUST NOT point at a **personal** (`KP-*`) id: that would write a personal-knowledge topology pointer into the project's shared physical ledger (`./.fabric/agents.meta.json`). Allowed: `KT→KT`, `KP→KP`, `KP→KT`. Forbidden: `KT→KP` only. When unsure whether a target is personal, OMIT the edge. (The meta-builder also strips any KT→KP edge that slips through, but do not rely on that — author clean edges.)
+
 ### 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). Four OPTIONAL rc.23 triage fields (`intent_clues`, `tech_stack`, `impact`, `must_read_if`) — populate when clean, **omit rather than guess**.
@@ -155,7 +161,7 @@ MANDATORY closing step on EVERY invocation (Phase 4 success path + every early-e
 - 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 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`, `.fabric/knowledge/pending/`, `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`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`.
+- MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `.fabric/knowledge/pending/`, `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`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`, `related`, `KT→KP`.
 
 ## Worked Examples / E5 Cron / Dry-run (ref-only)
 

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-review/SKILL.md

@@ -44,6 +44,8 @@ Missing or unreadable → defaults silently.
 
 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).

package/templates/skills/fabric-review/ref/cite-contract.md

@@ -0,0 +1,56 @@
+# Cite-contract + 裁决阶梯参考 (v2.2 SK5)
+
+> 本文是 cite policy 与裁决(adjudication)的**权威详参**,从 bootstrap (`.fabric/AGENTS.md`) 下沉至此,避免 bootstrap 随治理细节膨胀。bootstrap 只留**可执行 core**(cite 行格式 + 验证义务 + operator 例),完整 enum 词典 / 类型路由 / 稽核 / backward-compat / 裁决阶梯看这里。`fabric doctor --cite-coverage` 的稽核口径以本文为准。
+
+## 1. Cite 行格式 (回顾)
+
+edit / decide / propose plan 之前,**回复首行**:
+
+```
+KB: <id> (<≤8字 用法>) [applied|dismissed:<reason>]
+KB: none [<reason>]
+```
+
+- `[applied]` 前必须先 `fab_recall`(或 `fab_plan_context` → `fab_get_knowledge_sections`)实际抓 KB body —— 防编造 id。验证不通过 = 不能 cite。
+- **store 前缀** (多 store):read-set 含多 store 且同一 local id 跨 store shadow 时,cite 必须 store-qualified:`KB: <store-alias>:<id> ...`(如 `KB: team:KT-DEC-0001 (auth) [applied]`)。单 store / 无歧义时裸 `KB: <id>` 仍 valid。personal-only 条目 cite 进团队产物 = 强 warning(防泄漏 R5#3)。
+
+## 2. Contract 语法 (decisions/pitfalls 类 `[applied]`)
+
+cite 尾段加 contract:`→ <operator> [<operator> ...]`
+
+| operator | 含义 |
+|---|---|
+| `edit:<glob>` | 本 cite 承诺会改的文件范围 |
+| `!edit:<glob>` | 承诺**不**改的范围 |
+| `require:<symbol>` | 实现必须含某 symbol |
+| `forbid:<symbol>` | 实现必须不含某 symbol |
+| `skip:<reason>` | 本条 applied 但某 operator 跳过,附理由 |
+
+例:`KB: K-001 (auth) [applied] → edit:src/auth/**/*.ts !edit:src/legacy/**`
+
+## 3. 枚举词典
+
+- **skip reason**:`sequencing | conditional | semantic | aesthetic | architectural | other:<text>`
+- **dismissed reason**:`scope-mismatch | outdated | not-applicable | other:<text>`
+- **`KB: none` sentinel**:`[no-relevant]`(已调 recall/plan_context 但无可用条目) / `[not-applicable]`(当前动作不在 cite 范围:纯探索 / Bash 只读 / 用户问答)。裸 `KB: none` 仍 valid,归 `[unspecified]`(legacy 兼容)。
+
+## 4. 类型路由
+
+- `models` 类引用 = reference cite,**不需 contract**。
+- `guidelines` / `processes` 类暂不强制 contract,推后 LLM-judge。
+- `decisions` / `pitfalls` 类 `[applied]` **需** contract。
+
+## 5. 稽核 + Backward compat
+
+- 稽核:`fabric doctor --cite-coverage [--since=7d] [--client=cc|codex|all]` 输出覆盖率,含 `KB: none` sentinel 拆分。不阻断工作,只记录。
+- Backward compat:解析器同时接受老 4-state tags(`planned` / `recalled` / `chained-from <id>`),都映射到 `[applied]` 语义;旧 session cite 仍计入 cite-coverage。
+
+## 6. 裁决阶梯 (adjudication ladder)
+
+执行中遇到**需要拍板**的分歧(plan 选型 / review 取舍 / cross-LLM 不一致),按三级阶梯收口,**只有真正属于 human 的决定才阻塞**:
+
+1. **AI 自决** — 已有清晰证据 + 明确推荐时,直接执行,记 rationale。不为有默认值的选择拆 sub-question。
+2. **多-LLM 评审(含 ≥1 零上下文冷评)** — 主观 / 高风险 / 跨 LLM 分歧时,maestro delegate ≥2 LLM(至少一个零上下文,防执行者自我合理化)。一致 PASS 自动闭;一致 BLOCK + fix verbatim 采纳重跑。
+3. **非阻塞队列** — 仍分歧 / 主观 / 不可逆 / 属 frame 级(只有 human 能挑战 frame)→ 升 `needs_adjudication` 非阻塞队列,带两方理由 + AI 倾向裁决,继续推进不卡死。
+
+**Anchor**:critic 只能 frame 内审计;多-LLM 收敛 ≠ 正确,frame 级判断留给 human。cross-LLM 给 suggested fix 时直接 verbatim 采纳(+ trade-off 注释)。

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

@@ -0,0 +1,44 @@
+---
+name: fabric-store
+description: 知识 store 运维门面 — 创建 / 挂载 / 绑定 / 列出 / 切换写目标。CLI `fabric store …` 做事，本 skill 按用户意图选命令。NOT for git-managing 用户自己的产品仓。Triggers 创建 store/挂载 store/绑定知识库/store 列表/切换写库/set up knowledge store.
+---
+
+# fabric-store — 知识 store 运维
+
+每个「知识 store」操作的对话入口。CLI (`fabric store …`) 是引擎；本 skill 按用户意图挑命令。*store* 是 `~/.fabric/stores/<uuid>/` 下的平行 git 仓 —— 与用户的产品仓不同。同步 (pull+push) 见姊妹 skill `fabric-sync`。
+
+## When to use
+
+- 「创建团队 store」「建个人知识 store」
+- 「挂载团队 store」「这个项目要绑团队 store」
+- 「列出挂了哪些 store?」「我的共享决策写到哪个 store?」
+
+## When NOT to use
+
+- git 同步用户自己的产品仓 (那是普通 `git`)。
+- 同步知识 store (pull/push 冲突解决) → 用 `fabric-sync` skill。
+- 写知识条目 → 用 `fabric-archive` / `fabric-review`。
+
+## 意图 → 命令映射
+
+| 意图 | 命令 |
+|---|---|
+| 创建全新本地 store | `fabric store create --alias <a> [--remote <url>]` |
+| 挂载已存在的磁盘 store | `fabric store add --uuid <u> --alias <a> [--remote <url>]` |
+| 本项目声明需要某 store | `fabric store bind <alias-or-uuid>` |
+| 列出挂载的 store | `fabric store list` |
+| 设置非 personal scope 的写目标 | `fabric store switch-write <alias>` |
+| 解释某 alias 如何解析 | `fabric store explain <alias>` |
+| 同步 (pull+push) | 见 `fabric-sync` skill |
+
+## Precondition
+
+已 `fabric install --global` (存在 `~/.fabric` + 全局 store registry)。无全局配置 → 提示先 `fabric install --global`，停止。
+
+## Constraints
+
+- `store remove` 是 *detach ≠ delete*：从 registry 卸载但 MUST 保留磁盘 git 树。
+- `store add` MUST 拒绝磁盘无 store 树的 uuid (无「幽灵挂载」) —— 先 clone (`fabric install --global --url <remote>`) 或 `store create`。
+- 知识条目写在各 store 的 `.fabric/knowledge/` 下；本 skill 只管 store 生命周期,不写条目。
+- Personal-scope 写永远落在隐式 personal store，与 active write store 无关。
+- Hook/skill NEVER 直接解析 store 或执行 store 内文件 (S65 RCE 防线：store 是数据-only)；所有 store 状态 MUST 经 CLI JSON 输出获取。