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

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

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

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

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

package/templates/hooks/lib/theme.cjs

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

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: fabric-archive
-description: 归档对话洞察到 active write store 的 pending knowledge (NOT code review). Triggers 以后/always/never/下次/记一下;wrong-turn-revert;decision-confirm;dismissal-reason;/fabric-archive.
-allowed-tools: Read, Glob, Grep, Bash, mcp__fabric__fab_extract_knowledge
+description: 归档对话洞察(default)+ 冷启动从 git log/docs 回灌(source mode)到 active write store 的 pending knowledge (NOT code review). Triggers 归档/记一下/always·never/wrong-turn-revert;source mode bootstrap fabric/import 历史/mine commit.
+allowed-tools: Read, Glob, Grep, Bash, mcp__fabric__fab_archive_scan, mcp__fabric__fab_propose, mcp__fabric__fab_pending, mcp__fabric__fab_review
 ---
 
 > **Surface**: Skill (LLM judgment over session digests). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md).
@@ -29,10 +29,27 @@ rc.37 NEW-9 collapsed the flow to **3 macro-phases**; the legacy fine-grained ph
 
 - **GATHER** = Phase 0 (range) → 0.5 (config) → 1 (ledger scan via `fab_archive_scan`) → [1.5 onboard] → 2 (candidates).
 - **REVIEW** = Phase 2.5 (viability gate) → 3 (classify / layer / slug + batch review) → 3.5 (relevance scope + relevance_paths) → 3.7 (semantic scope / audience axis). The single user review round lives here.
-- **PERSIST** = Phase 4 (`fab_extract_knowledge`, one call per candidate) → 4.5 (archive-attempt ledger).
+- **PERSIST** = Phase 4 (`fab_propose`, one call per candidate) → 4.5 (archive-attempt ledger).
 
 Sub-step chain: `0 → 0.5 → 1 → [1.5] → 2 → 2.5 → 3 → 3.5 → 3.7 → 4 → 4.5`. Each below is a navigator stub — full procedure, decision tables, and worked examples live in `ref/`.
 
+## Source Mode — cold-start bootstrap (W3-C: 吸收原 fabric-import)
+
+**Default mode** GATHERs candidates from the cross-session digest ledger (Phase 1, `fab_archive_scan`). **Source mode** swaps ONLY the GATHER source: it mines `git log` + `docs/*.md` for one-time per-project cold-start — the REVIEW (classify / layer / scope / semantic_scope) and PERSIST (`fab_propose`) pipeline below is **shared, byte-for-byte the same contract**. No new write path: mined entries land as `team`-layer pending via the same `fab_propose`, then dedupe vs canonical via `fab_review`.
+
+**Enter source mode when** the user explicitly asks to bootstrap / import history / mine commits, OR the SessionStart hook fired `shouldRecommendImport()`. Else stay in default mode. **SKIP** when `.fabric/` missing (→ `fabric install`), canonical count > `import_skip_canonical_threshold` (default 50), or checkpoint `phase=complete` + `last_checkpoint_at <24h`.
+
+Source-mode pipeline (replaces GATHER; REVIEW+PERSIST unchanged):
+
+1. **Init / checkpoint** — read/init `.fabric/.import-state.json` (single resumability source; atomic `Write .tmp` → `Bash mv`). Corruption → `Read ref/source-state-recovery.md`. Full state schema + 6-step resume → `Read ref/source-checkpoint.md`.
+2. **Init-scan reference (NO re-implement)** — `fabric onboard-coverage --json` + `fab_pending action="search"` to learn existing canonical titles for the negative filter. `fabric install` already produced the baseline; source mode references it, never redoes it.
+3. **Mine (git + docs)** — `git log --since="<window> months ago"` (conventional prefix → type signal) + `docs/*.md`; classify into the 5 types; `fab_propose` per candidate. **Source-mode scope lock (NON-NEGOTIABLE): every mined entry `relevance_scope="broad"` + `relevance_paths=[]`** — LLM-inferred narrow lies about applicability; narrowing is deferred to `fab_review.modify` post-import. Cap `import_max_pending_per_run` (default 10). Full mining procedure, conventional-prefix table, `--dry-run` template → `Read ref/source-mining.md`.
+4. **Dedupe vs canonical** — for each pending, `fab_pending action="search"` (top 5 by type), classify duplicate / subsumption / subsumption-with-novelty / contradiction / genuinely-new, then `fab_review` reject / modify. `fab_pending` does NOT compare meaning — semantic compare is the LLM's job. Full 5-way classification → `Read ref/source-dedup.md`.
+
+Source-mode config knobs (read from `.fabric/fabric-config.json`, defaults if absent): `import_window_first_run_months` (60), `import_window_rerun_months` (2), `import_max_pending_per_run` (10), `import_max_commits_scan` (500), `import_skip_canonical_threshold` (50).
+
+Source-mode output roll-up + worked examples → `Read ref/source-output-contract.md` / `ref/source-worked-examples.md`. Source mode requires an **explicit target store** (E7) — never auto-route mined entries; resolve writable candidates via `fabric info scope team` and `AskUserQuestion` for the alias when more than one exists.
+
 ### Phase 0 — Range Resolution
 
 Parse user's prompt for time-window (`今日` / `last week`), topic keyword (`rc.20`), or literal `session_id` reference; emit `session_id[]` OR `"all"` sentinel that constrains Phase 1 collection. LLM-as-parser contract — no parser code.
@@ -45,7 +62,7 @@ Read `.fabric/fabric-config.json`; resolve `archive_max_candidates_per_batch` (d
 
 ### Phase 0.6 — Store routing (v2.1 multi-store)
 
-Archives land in the **active write store** for the entry's scope — NEVER pick a store yourself. Run `fabric scope-explain team` (or the relevant scope) to get the resolved `writeTarget`; that is where `fab_extract_knowledge` persists. Single-store → the lone store (back-compat). After persisting, **echo the target store alias** (`归档到 store '<alias>'`). Personal-scope entries route to the personal store (never the shared team store, R5#3). Do NOT read `~/.fabric` store trees directly — go through `scope-explain` / the MCP write path.
+Archives land in the **active write store** for the entry's scope — NEVER pick a store yourself. Run `fabric info scope team` (or the relevant scope) to get the resolved `writeTarget`; that is where `fab_propose` persists. Single-store → the lone store (back-compat). After persisting, **echo the target store alias** (`归档到 store '<alias>'`). Personal-scope entries route to the personal store (never the shared team store, R5#3). Do NOT read `~/.fabric` store trees directly — go through `fabric info scope` / the MCP write path.
 
 ### UX i18n Policy
 
@@ -95,7 +112,7 @@ Gather raw evidence: tail `.fabric/events.jsonl` since last `knowledge_proposed`
 
 Coarse viability check. **PASS**: user_explicit_invoke OR ≥1 archive signal hit. rc.37 NEW-4 folds the legacy 8 signals into **3 categories**: (1) **User-driven knowledge expression** (normative language `always`/`never`/`以后`/`记一下`/`永远不要`, OR decision-with-rationale, OR dismissal-with-reason); (2) **Reflective discovery** (wrong-turn-and-revert, OR long diagnostic loop, OR a named reusable pattern); (3) **Concrete artifact change** (new dependency diff, OR a formalized multi-step procedure).
 
-Pre-PASS HARD gate (rc.37 NEW-4): per candidate, run `fab_review action="search"` against the mounted read-set; duplicate canonical → drop the candidate (anti-signal #4). Silently writing a near-duplicate is the highest-noise failure mode.
+Pre-PASS HARD gate (rc.37 NEW-4): per candidate, run `fab_pending action="search"` against the mounted read-set; duplicate canonical → drop the candidate (anti-signal #4). Silently writing a near-duplicate is the highest-noise failure mode.
 
 **FAIL → branch**: E1/E3/E5 silent-skip (`outcome='skipped_no_signal'`); E2/E4 render gate-FAIL (`outcome='viability_failed'`) and MUST include the force-archive escape hatch (zh-CN: `如需强制归档，请显式调用 fabric-archive` / en: `To force-archive, explicitly invoke fabric-archive`).
 
@@ -137,7 +154,7 @@ Sets the entry's **audience** `semantic_scope` (orthogonal to `layer`=store and
 
 ### Phase 4 — Persist via MCP
 
-For each user-confirmed candidate, call `fab_extract_knowledge` ONCE (NEVER batch). Required: `source_sessions[]`, `recent_paths[]` (cap 20), `user_messages_summary`, `type` (plural form: decisions/pitfalls/guidelines/models/processes), `slug`, `layer`, `relevance_scope`, `relevance_paths[]`, `proposed_reason` (enum), `session_context` (3-5 line narrative). One OPTIONAL audience field: `semantic_scope` — pass `team` ONLY when Phase 3.7 classified a team candidate as team-wide (cross-project); OMIT otherwise so the engine auto-derives `project:<active_project>` (or `team` when the repo has no `active_project`). Four OPTIONAL rc.23 triage fields (`intent_clues`, `tech_stack`, `impact`, `must_read_if`) — populate when clean, **omit rather than guess**.
+For each user-confirmed candidate, call `fab_propose` ONCE (NEVER batch). Required: `source_sessions[]`, `recent_paths[]` (cap 20), `user_messages_summary`, `type` (plural form: decisions/pitfalls/guidelines/models/processes), `slug`, `layer`, `relevance_scope`, `relevance_paths[]`, `proposed_reason` (enum), `session_context` (3-5 line narrative). One OPTIONAL audience field: `semantic_scope` — pass `team` ONLY when Phase 3.7 classified a team candidate as team-wide (cross-project); OMIT otherwise so the engine auto-derives `project:<active_project>` (or `team` when the repo has no `active_project`). Four OPTIONAL rc.23 triage fields (`intent_clues`, `tech_stack`, `impact`, `must_read_if`) — populate when clean, **omit rather than guess**.
 
 Server returns `{ pending_path, idempotency_key }`. Display `pending_path` for the user. `idempotency_key = sha256({source_session, type, slug})` — repeated calls SAFE (server merges evidence).
 
@@ -163,25 +180,25 @@ MANDATORY closing step on EVERY invocation (Phase 4 success path + every early-e
 - WHEN `active_project` is set AND `layer=team`, MUST present `[semantic_scope=...]` (`team` for team-wide, or `project:<active_project>` for this-project-only) plus a one-line `Audience reasoning:` citing this-project-only vs team-wide (Phase 3.7).
 - MUST classify against the canonical singular nouns: model / decision / guideline / pitfall / process. NEVER invent new types.
 - MUST cap the batch at `archive_max_candidates_per_batch` candidates (config-resolved, default 8); drop weaker ones over the cap.
-- MUST display the resolved `pending_path` returned by `fab_extract_knowledge` so the user can verify.
+- MUST display the resolved `pending_path` returned by `fab_propose` so the user can verify.
 - MUST treat user inline edits to type/layer/slug/relevance_scope/relevance_paths/semantic_scope as authoritative replacements before Phase 2.
 - MUST skip rather than guess when an observation does not fit any of the 5 types.
 
 ### WRITE Rules
 
-- NEVER write a knowledge entry directly to the filesystem; the only legal write path is `mcp__fabric__fab_extract_knowledge`.
-- NEVER infer or glob a project-local pending directory — persist through `fab_extract_knowledge` and use the returned store-resolved `pending_path`; promotion to canonical knowledge is fab_review concern, NOT this skill.
+- NEVER write a knowledge entry directly to the filesystem; the only legal write path is `mcp__fabric__fab_propose`.
+- NEVER infer or glob a project-local pending directory — persist through `fab_propose` and use the returned store-resolved `pending_path`; promotion to canonical knowledge is fab_review concern, NOT this skill.
 - NEVER include an `id` field anywhere — pending entries have no id (late-bind on approve).
 - NEVER classify a candidate as `personal` when a 强 team signal applies. Default to team on ambiguity.
 - NEVER emit a non-empty `relevance_paths` when `relevance_scope=broad` — broad MUST always carry `relevance_paths=[]`.
 - NEVER emit a non-empty `relevance_paths` when `layer=personal` — personal forces `relevance_scope=broad` + `relevance_paths=[]`.
 - v2.0.0-rc.37 NEW-7 widened Phase 3.5: `edit_paths` ∪ `user_mentioned_paths` drives `relevance_paths`; `read_paths` flows separately to `evidence_paths` (structured frontmatter, not body markdown). NEVER lift body regex / symbol extraction into `relevance_paths` — those remain reserved for v2.1+.
-- NEVER batch multiple candidates into a single fab_extract_knowledge call; one call per candidate.
+- NEVER batch multiple candidates into a single fab_propose call; one call per candidate.
 - NEVER paraphrase the verbatim layer heuristic block above — the Chinese text is contract-locked.
-- MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `fab_extract_knowledge`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `semantic_scope`, `active_project`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`, `related`, `KT→KP`.
+- MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `fab_propose`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `semantic_scope`, `active_project`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`, `related`, `KT→KP`.
 
 ## Worked Examples / E5 Cron / Dry-run (ref-only)
 
-- **Worked examples** (3 end-to-end fab_extract_knowledge calls: decision/team, pitfall/team, guideline/personal): `Read ref/worked-examples.md`
+- **Worked examples** (3 end-to-end fab_propose calls: decision/team, pitfall/team, guideline/personal): `Read ref/worked-examples.md`
 - **E5 Scheduled Daily Recap** (only when entry_point=E5_cron — OS cron, `/loop`, or scheduled trigger): `Read ref/e5-cron-recap.md`
 - **Dry-run Scope** (authoritative catalogue of all writes suspended by `--dry-run`): `Read ref/dry-run-scope.md`

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

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

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

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

package/templates/skills/fabric-archive/ref/phase-1-5-onboard.md

@@ -23,7 +23,7 @@ is the canonical taxonomy for this gate.
 |-------|--------|-------------------------------------------------------|
 | **E1** | `hook_passive` | stdout JSON `{decision:'block', ...}` from `fabric-hint.cjs` detected at skill entry (the Stop-hook reminder path). |
 | **E2** | `explicit_user_invoke` | User prompt is a direct invocation: `fabric archive` / `/fabric-archive` / `archive what we just did` / `归档一下` / similar imperative. |
-| **E3** | `ai_self_trigger` | AI internal marker `self-archive policy triggered by signal: <X>` present (substring match on the verbatim prefix `self-archive policy triggered by signal` per AGENTS.md self-archive policy section; `<X>` is the signal name. v2.0.0-rc.37 NEW-2 simplified the AGENTS.md taxonomy to 2 categories: `User-driven normative` / `Wrong-turn-and-revert`. Back-compat: legacy 4-state names (`Normative` / `Decision confirmation` / `Explicit dismissal`) still route correctly because the substring gate only matches the verbatim prefix and treats any text after `signal:` as the signal label.) |
+| **E3** | `ai_self_trigger` | DEFAULT else-branch: the AI invoked `fabric-archive` itself, following the AGENTS.md self-archive policy (a clear archival signal — `User-driven normative` or `Wrong-turn-and-revert` — surfaced this turn), AND none of the affirmative non-AI entry signals are present (no E1 hook `{decision:'block'}` block, no E2/E4 explicit user invocation, no E5 cron literal). v2.2 C1 W3b retired the AI-printed routing marker — E3 is now the deterministic else-branch, so routing no longer depends on the AI emitting an exact magic string (every other entry has its own non-AI affirmative detector; E3 is what remains). The signal category does not need to be conveyed to the skill — Phase 2.5's viability gate re-derives it independently. |
 | **E4** | `user_range_rollback` | Prompt contains a **range hint** (parsed in Phase 0 — e.g. `今日` / `上周` / `rc.20`) AND the user is invoking. Sub-mode of E2. |
 | **E5** | `cron` | Prompt contains literal `今日复盘` / `daily recap` / `daily-archive` AND no human is present (running under `/loop`, OS cron, or scheduled trigger). |
 
@@ -141,7 +141,7 @@ AskUserQuestion({
 })
 ```
 
-`fab_extract_knowledge` is called with `onboard_slot: <slot>` set so each
+`fab_propose` is called with `onboard_slot: <slot>` set so each
 proposed entry counts toward coverage once approved via fab_review.
 
 | User choice    | Action |
@@ -172,7 +172,7 @@ After Read-ing the slot-specific sources, classify the observation:
 - `build-system-idiom` → type=`processes`, `proposed_reason=new-dependency-or-pattern`
 - `domain-vocabulary` → type=`models`, `proposed_reason=new-dependency-or-pattern`
 
-Call `fab_extract_knowledge` with the inferred fields PLUS `onboard_slot:
+Call `fab_propose` with the inferred fields PLUS `onboard_slot:
 <slot>`. The pending file's frontmatter will carry the slot label, and the
 next `fabric onboard-coverage` run will see the slot as filled (once approved
 via fab_review).
@@ -180,7 +180,7 @@ via fab_review).
 Example:
 
 ```ts
-mcp__fabric__fab_extract_knowledge({
+mcp__fabric__fab_propose({
   source_sessions: ["<current-session-id>"],
   recent_paths: ["package.json", "tsconfig.json"],
   user_messages_summary: "Project uses TypeScript + pnpm workspace + Vitest. Node 20 LTS target. ESM-only.",
@@ -214,4 +214,4 @@ mcp__fabric__fab_extract_knowledge({
 - MUST emit `onboard_slot: <slot>` verbatim — the slot name is one of
   the locked S5 strings (tech-stack-decision / architecture-pattern /
   code-style-tone / build-system-idiom / domain-vocabulary). The
-  fab_extract_knowledge schema enum will reject anything else.
+  fab_propose schema enum will reject anything else.

package/templates/skills/fabric-archive/ref/phase-1-cross-session.md

@@ -35,7 +35,7 @@ Before Step 5 builds the cross-session context, drop sessions that the outcome l
 - **(e) Never attempted (no `session_archive_attempted` event found for this `session_id`) → keep.** First-time scan; nothing to filter against.
 - **(f) Cross-session pending dedupe** (operates on candidate observations, not on `session_id` filter): gather all `knowledge_proposed_ids` from `session_archive_attempted` events with `outcome === "proposed"` across ALL sessions in the recent window (NOT just the current candidate session). This builds a global set of idempotency keys already proposed by prior archive runs but not yet reviewed by the user (the active write store may still contain matching pending entries). When classifying new observations in Phase 3, drop any candidate whose computed `idempotency_key` matches an id already in this set — it was already proposed by an earlier archive run, the user just hasn't reviewed it yet, so re-proposing would duplicate pending entries and inflate `candidates_proposed` counts. Per Phase 4.5 dedupe consumer of `knowledge_proposed_ids`.
 
-The resulting filtered `session_id[]` proceeds into Step 5's digest concatenation. Sessions filtered out in this step do NOT contribute to `### Cross-session digest`, are NOT included in `source_sessions` on any fab_extract_knowledge call, and are NOT referenced in `session_context` bodies.
+The resulting filtered `session_id[]` proceeds into Step 5's digest concatenation. Sessions filtered out in this step do NOT contribute to `### Cross-session digest`, are NOT included in `source_sessions` on any fab_propose call, and are NOT referenced in `session_context` bodies.
 
 ### Constants (rc.25 — verbatim)
 
@@ -54,7 +54,7 @@ The resulting filtered `session_id[]` proceeds into Step 5's digest concatenatio
 Concatenate the loaded digests into a single `### Cross-session digest` block to carry into Phase 2.5 + Phase 1. Use this block to:
 
 - Detect session-spanning patterns (e.g. a discussion that started in session A and continued in session B).
-- Populate the `source_sessions` array on every fab_extract_knowledge call — the array form (T5) replaces the legacy `source_session` string.
+- Populate the `source_sessions` array on every fab_propose call — the array form (T5) replaces the legacy `source_session` string.
 - Inform the `session_context` blob written to each pending entry's body (3-5 lines summarizing goal + key turning point, per T6).
 
 ## Graceful degradation

package/templates/skills/fabric-archive/ref/phase-2-5-viability.md

@@ -36,7 +36,7 @@ These force the gate to FAIL **unless** an archive signal also fires (i.e. anti-
 1. **Typo-only edits** — the entire session is whitespace / spelling / formatting changes. No semantic content to archive.
 2. **Pure refactor** — rename / move / extract with no behavior change AND no naming convention being established.
 3. **Narrow rename request** — user asked to rename one symbol / file with no rationale. Zero generalization potential.
-4. **Duplicate of existing canonical** — v2.0.0-rc.37 NEW-4: this check is now **mandatory** (was "do a quick Glob before deciding"). Pre-PASS MUST step: for each candidate, call `fab_review action="search"` scoped by type/slug keywords so the MCP read path searches mounted stores. If duplicate found → drop candidate. Silently writing a near-duplicate is the highest-noise failure mode.
+4. **Duplicate of existing canonical** — v2.0.0-rc.37 NEW-4: this check is now **mandatory** (was "do a quick Glob before deciding"). Pre-PASS MUST step: for each candidate, call `fab_pending action="search"` scoped by type/slug keywords so the MCP read path searches mounted stores. If duplicate found → drop candidate. Silently writing a near-duplicate is the highest-noise failure mode.
 
 ## Gate-FAIL user messages (E2 / E4 only)
 

package/templates/skills/fabric-archive/ref/phase-3-5-scope.md

@@ -62,7 +62,7 @@ Step 5: SCOPE GATE
 
 Step 6: ATTACH evidence_paths to FRONTMATTER (rc.37 NEW-7 upgrade)
   Pass evidence_candidate_paths (from Step 2, post-blacklist Step 3) to
-  fab_extract_knowledge as the `evidence_paths` input field. Server writes
+  fab_propose as the `evidence_paths` input field. Server writes
   them to frontmatter `evidence_paths: [...]` (NOT to body `## Evidence`).
   This makes evidence consumable by plan-context retrieval as structured
   data instead of forcing markdown re-parsing every recall. The legacy

package/templates/skills/fabric-archive/ref/phase-3-6-related-edges.md

@@ -2,7 +2,7 @@
 
 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).
+Because `fab_propose` 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
 

package/templates/skills/fabric-archive/ref/phase-3-classify.md

@@ -5,7 +5,7 @@
 ## Five Knowledge Types (verbose)
 
 - **model** — A reusable mental abstraction or domain object schema. Worth-archive signal: the user names something ("the X pattern", "the Y phase"). Skip-it signal: ad-hoc terminology used once. Positive: "Wave-1/Wave-2 task DAG decomposition for parallel-safe planning". Negative: "the thing we did just now" (too thin, no reusable abstraction).
-- **decision** — A choice between alternatives with rationale. Worth-archive signal: ≥2 options were weighed AND a rationale was given. Skip-it signal: the choice was forced by external constraint with no real alternative. Positive: "Single .cjs hook script over three per-client scripts — rationale: identical stdout JSON shape across Claude/Codex". Negative: "Used the existing fab_extract_knowledge schema" (no alternative was considered).
+- **decision** — A choice between alternatives with rationale. Worth-archive signal: ≥2 options were weighed AND a rationale was given. Skip-it signal: the choice was forced by external constraint with no real alternative. Positive: "Single .cjs hook script over three per-client scripts — rationale: identical stdout JSON shape across Claude/Codex". Negative: "Used the existing fab_propose schema" (no alternative was considered).
 - **guideline** — A normative rule for future similar situations. Worth-archive signal: the user said "always" / "never" / "from now on". Skip-it signal: a one-off preference that won't generalize. Positive: "Slug naming: kebab-case, 2-5 words, 20-40 chars, semantic core only". Negative: "Use 4-space indent in this one file" (too narrow).
 - **pitfall** — A trap that wasted time and is non-obvious. Worth-archive signal: a bug took >15 min to diagnose AND is repeatable. Skip-it signal: a typo or one-time API quirk. Positive: "deepMerge replaces arrays — hooks.Stop[] needs special-case append-with-dedupe". Negative: "Forgot a comma in JSON" (too obvious).
 - **process** — A multi-step procedure with a stable shape. Worth-archive signal: the steps were executed in a specific order AND the order matters. Skip-it signal: a one-shot script with no reusable structure. Positive: "fab_review approve = counter++ → frontmatter inject → git mv → meta rebuild → event append (5 atomic steps)". Negative: "Ran the tests, then committed" (trivial, no reusable shape).

package/templates/skills/fabric-archive/ref/phase-4-5-emit.md

@@ -25,7 +25,7 @@ For EACH `session_id` in the run's scope (multi-session E4 runs emit MULTIPLE ev
 
 | Skill terminal state                                                 | outcome              | candidates_proposed | knowledge_proposed_ids                          |
 |----------------------------------------------------------------------|----------------------|---------------------|-------------------------------------------------|
-| Phase 4 wrote ≥ 1 pending entry                                      | `proposed`           | N (count written)   | `[idempotency_key_1, idempotency_key_2, ...]` (from each fab_extract_knowledge response) |
+| Phase 4 wrote ≥ 1 pending entry                                      | `proposed`           | N (count written)   | `[idempotency_key_1, idempotency_key_2, ...]` (from each fab_propose response) |
 | Phase 2.5 viability_failed AND entry_point ∈ {E2_explicit, E4_user_range} AND user saw + accepted the gate-FAIL message | `viability_failed`   | 0                   | `[]`                                            |
 | Phase 3 batch review — user dismissed ALL presented candidates       | `user_dismissed`     | 0                   | `[]`                                            |
 | Phase 1 filter dropped every session in scope OR Phase 2.5 silent-skip path (E1_hook / E3_ai_self_trigger / E5_cron) | `skipped_no_signal`  | 0                   | `[]`                                            |

package/templates/skills/fabric-archive/ref/phase-4-mcp-persist.md

@@ -5,15 +5,16 @@
 ## Full MCP tool call shape
 
 ```ts
-mcp__fabric__fab_extract_knowledge({
+mcp__fabric__fab_propose({
   source_sessions: ["<session id1>", "<session id2>", ...],  // T5: array form (Phase 1)
   recent_paths: ["<path1>", "<path2>", ...],   // capped at archive_max_recent_paths (config-resolved, default 20)
   user_messages_summary: "<compact prose ≤500 chars>",
   type: "decisions" | "pitfalls" | "guidelines" | "models" | "processes",
   slug: "<kebab-case-2-to-5-words>",
-  layer: "team" | "personal",
-  relevance_scope: "narrow" | "broad",         // from Phase 3.5
-  relevance_paths: ["<glob1>", "<literal2>", ...],  // narrow ⇒ derived; broad ⇒ []
+  // v2.2 C1 (W1): author-facing scope is TWO fields only — `audience` + `paths`.
+  // The engine derives layer / visibility_store / store / relevance_scope.
+  audience: "team" | "personal" | "project:<id>" | "org:<...>",  // WHO it's for (open coordinate); omit → engine default (project:<active> | team)
+  paths: ["<glob1>", "<literal2>", ...],  // relevance anchors; non-empty ⇒ narrow, empty/omit ⇒ broad (relevance_scope is derived from this — no separate flag)
   // v2.0.0-rc.7 T6: required fields for future-self reviewability.
   proposed_reason:
     "explicit-user-mark"      // user said "always / never / 下次注意" etc.
@@ -78,7 +79,7 @@ The server returns `{ pending_path, idempotency_key }`. Display `pending_path` t
 
 ## Idempotency Notes (T5 array-form, rc.7+)
 
-The MCP tool derives `idempotency_key = sha256({source_session, type, slug})`. Calling `fab_extract_knowledge` twice with the same `(source_session, type, slug)` triple is SAFE: the server appends new evidence to the existing pending file rather than overwriting or producing duplicates. The skill MAY be re-invoked on the same session without producing junk.
+The MCP tool derives `idempotency_key = sha256({source_session, type, slug})`. Calling `fab_propose` twice with the same `(source_session, type, slug)` triple is SAFE: the server appends new evidence to the existing pending file rather than overwriting or producing duplicates. The skill MAY be re-invoked on the same session without producing junk.
 
 If the skill needs to record a genuinely separate observation in the same session+type, the slug MUST differ.
 

package/templates/skills/{fabric-import/ref/checkpoint-state.md → fabric-archive/ref/source-checkpoint.md}

@@ -2,7 +2,7 @@
 
 > **Loaded on demand.** SKILL.md hot path retains a 2-line mention of the 2-step atomic write pattern + a pointer to this file. This file holds the full Atomic State Write rationale, events.jsonl 4KB constraint, complete schema, and resume-logic state machine.
 
-The state file lives at `.fabric/.import-state.json` and is the single source of resumability for fabric-import. It is written via the explicit 2-step atomic pattern documented below so a crash between phases / between sub-steps never corrupts it.
+The state file lives at `.fabric/.import-state.json` and is the single source of resumability for archive source mode. It is written via the explicit 2-step atomic pattern documented below so a crash between phases / between sub-steps never corrupts it.
 
 ## Atomic State Write (2-step pattern)
 
@@ -15,7 +15,7 @@ This 2-step pattern is mandatory for every state file update. `mv` is atomic on
 
 Crash safety expectations:
 
-- Crash between Step A and Step B → leaves `.fabric/.import-state.json.tmp`. Phase 0 residue scan (see `ref/state-recovery.md`) triages it on next invocation.
+- Crash between Step A and Step B → leaves `.fabric/.import-state.json.tmp`. Phase 0 residue scan (see `ref/source-state-recovery.md`) triages it on next invocation.
 - Crash during Step B (between the `rename` syscall start and return) → POSIX `rename` is atomic; either the prior `.import-state.json` is intact, or the new one is in place. No torn state.
 - Crash before Step A → no state mutation occurred; prior state file is unchanged.
 
@@ -82,4 +82,4 @@ On every skill invocation, BEFORE Phase 1 starts:
 5. If `phase === "P2-done"` → skip Phase 1 + Phase 2; resume from Phase 3 Step 3.1; iterate Phase 2 outputs skipping any pending_path already in `p3_dedup_completed[]`.
 6. After every successful sub-step (one commit processed, one doc processed, one dedup pair resolved), write the updated state file via the 2-step `.tmp` + `mv` pattern. Failures append to `errors[]` and proceed (or halt with prompt if cumulative errors `>5`).
 
-The contract: re-invoking fabric-import after ANY interruption (Ctrl-C, crash, network blip on MCP) MUST NOT propose duplicates of already-proposed entries and MUST NOT redo already-completed dedup decisions.
+The contract: re-invoking archive source mode after ANY interruption (Ctrl-C, crash, network blip on MCP) MUST NOT propose duplicates of already-proposed entries and MUST NOT redo already-completed dedup decisions.

package/templates/skills/{fabric-import/ref/phase-3-dedup.md → fabric-archive/ref/source-dedup.md}

@@ -2,14 +2,14 @@
 
 > **Loaded on demand.** SKILL.md hot path retains the Phase 3 purpose statement + 4-step outline + completion sentinel. This file holds the full Step 3.1/3.2/3.3/3.4 MCP call shapes, semantic compare 5-way classification, and the underseed sentinel rationale.
 
-For each pending entry created in Phase 2 (read from `p2_processed_commits[].pending_path` and `p2_processed_docs[].pending_paths`), check if it duplicates / contradicts / is subsumed by an existing canonical entry. **Semantic comparison is the LLM's job — `fab_review` does not compare meaning.**
+For each pending entry created in Phase 2 (read from `p2_processed_commits[].pending_path` and `p2_processed_docs[].pending_paths`), check if it duplicates / contradicts / is subsumed by an existing canonical entry. **Semantic comparison is the LLM's job — `fab_pending` does not compare meaning.**
 
 ## Step 3.1 — Search Canonical of Same Type
 
 For each just-proposed pending entry (read its frontmatter via the `Read` tool to get type + slug + title):
 
 ```ts
-mcp__fabric__fab_review({
+mcp__fabric__fab_pending({
   action: "search",
   query: "<title or summary keywords from the pending entry>",
   filters: { type: "<same type as pending>" }
@@ -25,7 +25,7 @@ For each `(pending, canonical)` pair the LLM judges:
 - **Duplicate** — same essential claim. LLM 主观判断：标题与摘要表达同一核心结论，新 pending 未提供新证据。具体阈值不可量化。Action: **reject** the new pending.
 - **Subsumption** (pending narrower) — canonical fully covers the pending plus more. Action: **reject** the new pending (canonical already serves).
 - **Subsumption-with-novelty** (pending adds evidence) — canonical covers the claim but the new pending brings new evidence (commit sha, file paths). Action: **modify** the canonical to merge in the new evidence; **reject** the new pending citing the modified canonical.
-- **Contradiction** — opposing claims about the same scope. Action: leave pending; flag for user via roll-up. The user must decide via `fabric-review` later — `fabric-import` does NOT auto-resolve contradictions.
+- **Contradiction** — opposing claims about the same scope. Action: leave pending; flag for user via roll-up. The user must decide via `fabric-review` later — `archive source mode` does NOT auto-resolve contradictions.
 - **Genuinely new** — no canonical match. Action: leave pending in place (will surface in next `fabric-review` run for normal approval flow).
 
 ## Step 3.3 — Issue Dedup MCP Calls
@@ -68,7 +68,7 @@ Append to `.fabric/.import-state.json` after EACH successful MCP call:
 After all Phase 2 outputs are dedup-reviewed:
 
 - Update `.fabric/.import-state.json`: `phase = "complete"`, `last_checkpoint_at = <ISO8601 now>`, `final_summary = {proposed: N, kept: K, rejected_dup: R, merged: M, contradictions_flagged: C}`.
-- Render the final roll-up to the user (see Output Contract — see `ref/output-contract.md`).
+- Render the final roll-up to the user (see Output Contract — see `ref/source-output-contract.md`).
 
 > Setting `phase = "complete"` in `.fabric/.import-state.json` is enough to silence the SessionStart underseed self-check banner (`shouldRecommendImport()` returns false for any non-`absent` state). 无需额外清理 sentinel 文件 — 该机制已在 rc.8 下线。