@fenglimg/fabric-cli 2.0.0 → 2.1.0-rc.2

package/templates/skills/fabric-import/ref/worked-examples.md

@@ -0,0 +1,127 @@
+# Worked Examples (ref)
+
+> **Loaded on demand.** SKILL.md hot path points here for concrete end-to-end traces. These 4 examples illustrate Phase 2 mining (git + docs), Phase 3 dedup classification, and the out-of-band narrowing path that is NOT performed by this skill.
+
+## Example A — Phase 2 git mining: feat commit → pitfall entry
+
+Source signal: `git log` surfaces commit `50367b5` with subject `feat(server): add custom retry logic` and body explaining that initial implementation retried without exponential backoff, causing a thundering-herd outage during a brief upstream hiccup; the fix was jittered exponential backoff with a 30s ceiling.
+
+LLM analysis: this is a **pitfall** (a non-obvious trap that wasted time and is repeatable across services). The body itself documents the trap. Slug candidates: `retry-without-backoff-thundering-herd` (5 words, 38 chars — passes 5 rules).
+
+Skill output (note `relevance_scope: "broad"` + `relevance_paths: []` — mandatory for fabric-import):
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["fabric-import-2026-05-10"],
+  recent_paths: ["packages/server/src/lib/retry.ts"],     // provenance only
+  user_messages_summary: "重试无指数退避会在短暂上游故障下放大成雪崩。修正：jittered exponential backoff，30 秒上限。src=50367b5",
+  type: "pitfalls",
+  slug: "retry-without-backoff-thundering-herd",
+  relevance_scope: "broad",                                // MANDATORY
+  relevance_paths: [],                                     // MANDATORY — do NOT infer ["packages/server/src/lib/retry.ts"]
+  proposed_reason: "diagnostic-then-fix",                  // Step 2.1.5: body describes long diagnostic chain (no-backoff → thundering-herd outage → root cause) → root-cause fix; this overrides the `feat(` prefix per the "body content wins over prefix" ambiguity rule.
+  session_context: "Imported from git log analysis. Origin: commit 50367b5 (feat(server): add custom retry logic). No live session — see commit body for full context."
+})
+```
+
+Counter-example — DO NOT do this:
+
+```ts
+// WRONG — this skill must never produce narrow + paths from git metadata.
+// The retry pitfall applies to every retry site, not just the file touched by 50367b5.
+mcp__fabric__fab_extract_knowledge({
+  // ...
+  relevance_scope: "narrow",                                // VIOLATION
+  relevance_paths: ["packages/server/src/lib/retry.ts"]     // VIOLATION
+})
+```
+
+If the user later judges this pitfall to be narrow-scoped, they (via `fabric-review`) issue `fab_review action="modify"` with `changes.relevance_scope` + `changes.relevance_paths` — that is the legal narrowing path.
+
+State file delta:
+```json
+{ "p2_processed_commits": [
+    { "sha": "50367b5...", "skipped": false,
+      "pending_path": "knowledge/pending/pitfalls/retry-without-backoff-thundering-herd.md",
+      "type": "pitfalls", "slug": "retry-without-backoff-thundering-herd" }
+  ]
+}
+```
+
+## Example B — Phase 2 doc mining: architecture.md → decision entry
+
+Source signal: `docs/architecture.md` contains a section heading "## Why a monolith?" with body explaining the team chose monolith over microservices because the 3-engineer team couldn't justify the operational cost of multi-service deploys, and the dominant performance constraint (DB throughput) doesn't benefit from horizontal split.
+
+LLM analysis: this is a **decision** (≥2 alternatives weighed — monolith vs microservices — with explicit rationale). Slug candidates: `monolith-over-microservices-small-team` (5 words, 38 chars — passes 5 rules).
+
+Skill output (broad+[] mandatory; the doc's own path stays in `recent_paths` for provenance, NOT in `relevance_paths`):
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["fabric-import-2026-05-10"],
+  recent_paths: ["docs/architecture.md"],                  // provenance only
+  user_messages_summary: "选择单体架构而非微服务：3 人团队无法承担多服务运维成本，且主要性能瓶颈在 DB 吞吐而非应用层水平扩展。src=docs/architecture.md",
+  type: "decisions",
+  slug: "monolith-over-microservices-small-team",
+  relevance_scope: "broad",                                // MANDATORY
+  relevance_paths: []                                      // MANDATORY — a monolith-vs-microservices decision applies repo-wide, not only to docs/
+})
+```
+
+## Example C — Phase 3 dedup finds duplicate, rejects
+
+After Example A's pending entry (`retry-without-backoff-thundering-herd`) is proposed, Phase 3 runs:
+
+```ts
+mcp__fabric__fab_review({
+  action: "search",
+  query: "retry backoff thundering herd",
+  filters: { type: "pitfalls" }
+})
+```
+
+Server returns 1 canonical match: `KT-P-0007--retry-no-jitter-amplification.md` with summary "重试缺少 jitter 在并发场景放大原始故障峰值". LLM judgment: the existing canonical asserts the same essential claim (retry without jitter amplifies failures) — this is a **duplicate**, not subsumption-with-novelty (the new pending offers no new evidence beyond restating the trap).
+
+Skill output:
+
+```ts
+mcp__fabric__fab_review({
+  action: "reject",
+  pending_paths: ["knowledge/pending/pitfalls/retry-without-backoff-thundering-herd.md"],
+  reason: "duplicate of KT-P-0007"
+})
+```
+
+State file delta:
+```json
+{ "p3_dedup_completed": [
+    { "pending_path": "knowledge/pending/pitfalls/retry-without-backoff-thundering-herd.md",
+      "action": "reject", "canonical_ref": "KT-P-0007" }
+  ]
+}
+```
+
+Final roll-up to user reflects: 1 proposed, 0 kept, 1 rejected_dup, 0 merged, 0 contradictions.
+
+## Example D — Post-import narrowing (out-of-band, NOT this skill)
+
+This example documents the legal narrowing path; it is NOT performed by `fabric-import` itself. After Example B's `monolith-over-microservices-small-team` decision is imported (with `relevance_scope=broad`, `relevance_paths=[]`) and later approved into canonical via `fabric-review`, the user decides the decision is actually narrow to the server package's deploy tooling.
+
+The user issues (via `fabric-review`, NOT via this skill):
+
+```ts
+mcp__fabric__fab_review({
+  action: "modify",
+  pending_path: "knowledge/team/decisions/monolith-over-microservices-small-team.md",
+  changes: {
+    relevance_scope: "narrow",
+    relevance_paths: ["packages/server/**", "scripts/deploy/**"]
+  }
+})
+```
+
+Key invariants of this flow:
+
+- The narrowing decision originates from the **user**, informed by the actual paths they propose — not from `fabric-import` inferring paths from git metadata.
+- The modify call goes through `fab_review`, not `fab_extract_knowledge`, because the entry already exists (post-import or post-approval).
+- If the user later flips the entry's layer from `team` to `personal`, server-side auto-degrades scope back to `broad` and clears `relevance_paths` (see rc.5 C3 acceptance criterion; personal knowledge crosses projects so paths don't generalize). This is the only legal way for `relevance_paths` to be re-cleared.

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

@@ -1,256 +1,140 @@
 ---
 name: fabric-review
-description: Use this skill to review pending knowledge entries in `.fabric/knowledge/pending/` — list, approve (late-bind id allocation), reject, modify (incl. layer flip), search, defer. Mode is inferred from invocation context (recent user message + events.jsonl tail + pending count) — NEVER asked. Per-item actions (approve / reject / modify / defer) are surfaced via AskUserQuestion because they are genuine human-judgment choices.
+description: 审 .fabric/knowledge pending+canonical (NOT PR review):approve/reject/modify/revisit/defer。Triggers 审批/驳回/复审/重审/approve/reject/review pending.
 allowed-tools: Read, Glob, Grep, Bash, Edit, mcp__fabric__fab_review
 ---
 
-> **Surface**: This is a Skill (AI-driven, per-entry human-judgment routing). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md) for the CLI / Skill / MCP boundary.
+> **Surface**: Skill (AI-driven, per-entry human-judgment routing). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md).
 
 ## Precondition
 
-This skill is invoked when one of the following holds:
+Invoke this skill ONLY when ONE of the following holds:
 
-- The Stop-hook printed a stdout JSON pointer of shape `{"decision":"block","reason":"..."}` carrying a `signal=review` (pending overflow: ≥10 entries or oldest pending age ≥7 days)
-- The user typed an explicit review request (e.g. "review knowledge", "show pending", "approve what's queued", "what's stale", "look at KT-D-7")
-- A task end where the agent itself判定 review backlog has crossed the overflow threshold
+- Stop-hook printed stdout JSON `{"decision":"block","reason":"..."}` carrying `signal=review` (pending overflow: count ≥ `review_hint_pending_count` (default 10) OR oldest age ≥ `review_hint_pending_age_days` (default 7) days)
+- User typed an explicit review request (e.g. "review knowledge", "show pending", "approve what's queued", "what's stale", "look at KT-D-7")
+- Agent判定 review backlog crossed the overflow threshold
 
-If none of the above hold, stop the skill immediately and tell the user `没有触发 review 信号；如需手动 review 请显式调用 fabric-review`.
+If none hold, stop the skill and tell the user:
+
+- zh-CN: `没有触发 review 信号；如需手动 review 请显式调用 fabric-review`
+- en: `No review signal detected; to manually review, explicitly invoke fabric-review`
 
 This skill is `Infer-not-Ask` for mode and `Ask-when-genuine` for per-item actions:
 
 - Mode (pending / topic / health / revisit) is INFERRED from context — NEVER surfaced via AskUserQuestion
 - Per-item action (approve / reject / modify / defer) IS surfaced via AskUserQuestion — the user must judge
-- Layer-flip target (team vs personal) IS surfaced via AskUserQuestion when modify path includes layer change
+- Layer-flip target (team vs personal) IS surfaced via AskUserQuestion when modify includes layer change
+
+Required preconditions before any `fab_review` call: `.fabric/` exists (or `~/.fabric/` for personal layer); `mcp__fabric__fab_review` MCP tool registered; `.fabric/agents.meta.json` present (id allocator reads it on approve); `.fabric/events.jsonl` exists (tolerate ENOENT — empty ledger normal first-run).
+
+### Config Load
+
+Read `.fabric/fabric-config.json`; resolve:
+
+| Config field | Default | Used by |
+|---|---|---|
+| `review_topic_result_cap` | 8 | topic mode top-N cap |
+| `review_stale_pending_days` | 14 | health mode stale threshold (days) |
+| `review_hint_pending_count` | 10 | precondition overflow signal (count) |
+| `review_hint_pending_age_days` | 7 | precondition overflow signal (age) |
+
+Missing or unreadable → defaults silently.
+
+### Store routing (v2.1 multi-store)
+
+Review iterates **per-store** — the read-set may span multiple stores (`fabric scope-explain team` → resolved `readSet.stores`). Pending/backlog is reported per-store (NOT aggregated into one undifferentiated pile); each candidate's provenance store is surfaced in cites as `KB: <store-alias>:<id>`. Promotion (draft → verified/proven) is a normal edit + git commit **inside that store's own repo** — no cross-store move. A `dismissed`/`modify` that flips layer between team and personal still goes through `AskUserQuestion`. Never read `~/.fabric` store trees directly; go through the MCP recall path / `scope-explain`.
+
+### UX i18n Policy
 
-Required preconditions before any fab_review call:
+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).
 
-- `.fabric/` directory exists in the project (or `~/.fabric/` for personal layer)
-- `mcp__fabric__fab_review` MCP tool is registered and reachable
-- `.fabric/agents.meta.json` is present (the id allocator reads it on approve)
-- `.fabric/events.jsonl` exists (tolerate ENOENT — empty ledger is normal first-run)
+`Read ref/i18n-policy.md` for the full 5-class taxonomy + edge cases.
 
 ## Mode Inference (System Infers — NEVER Ask)
 
-> Verbatim from rc.3 locked decisions:
-> "review 永远走 fabric-review skill，**模式从上下文推断**（4 种 mode：pending queue / by topic / health overview / revisit existing）"
+> Locked decision (KT-DEC-0006): "Review mode inferred from context, not solicited via AskUserQuestion."
 > "**AskUserQuestion 仅在真有选择时用**——'何种 mode' 不是真选择（系统能推断），'approve/reject/modify 单条' 是真选择"
 
-The skill MUST infer one of {`pending`, `topic`, `health`, `revisit`} before any user-facing output. NEVER call `AskUserQuestion` to ask the user which mode to use — the system MUST infer.
+The skill MUST infer one of **2 modes** BEFORE any user-facing output (v2.0.0-rc.37 NEW-12 simplified 4 → 2):
 
-### 3-Step Inference Algorithm
+- **`pending`** — triage the write-side backlog (`.fabric/knowledge/pending/`): approve / reject / modify / defer per item. The dominant entry point.
+- **`maintain`** — sustain the EXISTING canonical KB: browse by topic (search), survey staleness/health, or revisit a specific entry. Merges the legacy `topic` + `health` + `revisit` modes — they are all "operate on already-canonical knowledge", distinct from triaging new drafts.
 
-**Step 1 — Recent user message keyword scan.** Read the user's most recent invocation message (or the Stop-hook reason text). Match against keyword sets in this priority order:
+### 2-Step Inference Algorithm
+
+**Step 1 — Recent user message keyword scan:**
 
 | Keywords (zh-CN + en) | Inferred mode |
 |---|---|
 | "approve", "review pending", "promote", "what's queued", "审核 pending", "通过" | `pending` |
-| "search for X about Y", "find entries about <topic>", "关于…的知识", "找一下 <topic>" | `topic` |
-| "what's stale", "demote old", "health check", "过期的", "陈旧的", "整理一下" | `health` |
-| "look at <id>", "revisit KT-…", "show <slug>", "再看下 <id>", "回顾" | `revisit` |
+| "search/find about <topic>", "what's stale", "demote old", "health check", "look at <id>", "revisit KT-…", "关于…的知识", "过期的", "陈旧的", "整理一下", "再看下 <id>", "回顾" | `maintain` |
 
-If exactly one row matches, lock that mode and skip to Step 3.
+A `maintain`-row match → lock `maintain`. A `pending`-row match (or 0/ambiguous) → fall to Step 2.
 
-**Step 2 — events.jsonl tail scan.** If Step 1 yielded zero or multiple matches, read the tail (last 200 lines) of `.fabric/events.jsonl`:
+**Step 2 — Backlog default.** Glob `.fabric/knowledge/pending/**/*.md`:
 
-- Count `knowledge_proposed` events since the last `knowledge_promoted` event. If `>5` recent proposals → infer `pending` (write side has piled up; review is overdue).
-- Count `knowledge_demoted` or `lint`-class events in the last 24h. If `≥1` → infer `health` (corpus quality signal already firing).
-- If a recent `knowledge_layer_changed` event exists for the entry the user just referenced → infer `revisit`.
+- Count ≥ `review_hint_pending_count` (default 10) OR oldest mtime > `review_hint_pending_age_days` (default 7) → `pending` (overflow, same threshold as Stop-hook).
+- Otherwise → default `pending` (most common review entry point).
 
-**Step 3 — Pending count default.** If Step 1 and Step 2 both produced no signal, glob `.fabric/knowledge/pending/**/*.md`:
+> Back-compat: the legacy 4-mode names (`topic` / `health` / `revisit`) still resolve — they all map to `maintain`. Old session traces / muscle memory keep working.
 
-- If pending count `≥10` OR oldest pending file mtime is `>7 days` ago → infer `pending` (overflow signal — same threshold the Stop-hook uses).
-- Otherwise → default to `pending` (most common review entry point).
+`Read ref/per-mode-flows.md` for inference examples and anti-pattern restatement.
 
-### Inference Examples (Sample User Messages → Expected Mode)
+## Per-Mode Flow
 
-- "review the pending knowledge" → `pending` (Step 1 keyword "review pending")
-- "find anything about deepMerge" → `topic` (Step 1 keyword "find … about")
-- "anything stale in our knowledge base?" → `health` (Step 1 keyword "stale")
-- "look at KT-D-7" → `revisit` (Step 1 keyword "look at <id>")
-- (Stop-hook fired with signal=review, no user typing) → `pending` (Step 3 default, overflow threshold tripped)
+Each mode produces user-facing output, then routes per-item or per-batch decisions through `fab_review` actions. Display body = zh-CN summaries (M3 style); section headings = EN.
 
-### Anti-Pattern (Hard Rule)
+- **`pending`** — list pending entries → run Semantic Check (see `ref/semantic-check.md`) → per-item AskUserQuestion `{approve, reject, modify, defer, skip}` → route per choice. The modify branch chooses between two explicit actions (rc.37 NEW-12):
+  - `fab_review action="modify-content"` — edit scalars (title/summary/maturity/tags/relevance_*); NEVER flips layer.
+  - `fab_review action="modify-layer"` — the dedicated layer-flip path (`changes.layer` required); may reallocate the stable_id + emit an id-redirect.
+  - (Legacy `action="modify"` still works — it routes by whether `changes.layer` is present.) See `ref/modify-flow.md`.
+- **`maintain`** — sub-flow inferred from the same keywords:
+  - *browse-by-topic*: extract keywords → `fab_review action="search"` → render top-N (cap `review_topic_result_cap`) → AskUserQuestion only on an action verb.
+  - *health/staleness*: `fab_review action="list"` + tail events → compute stale → render dashboard → per-stale AskUserQuestion `{defer, demote, skip}`.
+  - *revisit*: user referenced a specific id/slug → `Read` canonical file directly OR `fab_review action="list"` with narrow filters → display body + history → AskUserQuestion only if actionable.
 
-NEVER emit an `AskUserQuestion` whose options include {pending, topic, health, revisit}. The user does not pick the mode. If inference is genuinely ambiguous after all 3 steps, default to `pending` and proceed; the user can always cancel and redirect.
+`Read ref/per-mode-flows.md` for full step-by-step procedures, bilingual rendering blocks (en + zh-CN per-item display, AskUserQuestion templates, health dashboard format), and the rc.7 T6 `proposed_reason` + `## Why proposed` + `## Session context` rendering contract.
 
-## Per-Mode Flow
+## Semantic Check (LLM-Assisted Duplicate / Contradiction Detection)
 
-Each mode produces user-facing output, then routes per-item or per-batch decisions through `fab_review` actions. Display body = zh-CN summaries (M3 style); section headings = EN.
+> Boundary B (locked): "extraction / classification / layer / slug / mode / **semantic dedup** → Skill (LLM); file write / frontmatter / idempotency / counter / layer-flip / atomic promote → MCP (deterministic)"
 
-### Mode: pending — Approve / Reject / Modify Backlog
-
-1. Call `fab_review` with `action: "list"`, no filters (or `filters.layer="both"` if user explicitly mentioned both layers).
-2. Server returns `items[]` (each = `{pending_path, type, layer, maturity, tags?, title?, summary?}`).
-3. Before presenting, perform **Semantic Check** (see below) by issuing one or more `action: "search"` calls scoped by `filters.type` to surface possible duplicates / contradictions among already-canonical entries.
-4. For each pending item, render a per-item block. v2.0.0-rc.7 T6: render
-   `proposed_reason` (frontmatter) + `## Why proposed` line (body, 1-line enum
-   explanation) + first line of `## Session context` so future-self has full
-   context without re-reading the transcript:
+Semantic check is the LLM's job — the MCP tool does NOT compare meaning. Run during `pending` mode (and on demand during `topic`): for each pending entry, `fab_review action="search"` scoped by `filters.type` → LLM judges semantically against returned canonical entries → surface one of three flags as informational:
 
-   ```md
-   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
-   Title: 单 .cjs hook 跨客户端
-   Summary: 三客户端 stdout JSON 格式一致，单脚本即可。
-   Maturity: draft   Tags: [hook, cli]
-   Proposed reason: decision-confirmation — ≥2 候选方案经权衡后确认选型。
-   Session context: Session goal: ship Stop-hook for v2 release.
-   ⚠ Possible duplicate of KT-D-0007 (similarity 0.78 on title + summary)
-   ```
+- `⚠ Possible duplicate of <stable_id> (overlap: high)` — same essential claim
+- `⚠ Contradicts <stable_id> (overlap: high)` — opposing claims, same scope
+- `⚠ Subsumed by <stable_id> (overlap: medium+); consider modify-to-merge` — fully covered
 
-   The Skill MUST read `proposed_reason` from the pending file's frontmatter
-   (parse the YAML block, key `proposed_reason`) and the `## Why proposed`
-   line / first non-blank line of `## Session context` from the body. If
-   either is missing on a pre-rc.7 pending entry, render `Proposed reason:
-   <legacy entry, no reason recorded>` and `Session context: <not recorded>`
-   so the reviewer can still proceed.
-
-5. Surface a per-item AskUserQuestion:
-
-   ```ts
-   AskUserQuestion({
-     header: "Review pending entry",
-     question: "What action for '单 .cjs hook 跨客户端'?",
-     options: ["approve", "reject", "modify", "defer", "skip"]
-   })
-   ```
-
-6. Route the user's choice:
-   - `approve` → accumulate pending_path into a batch; flush via single `fab_review action="approve"` with `pending_paths=[…]` after the loop ends.
-   - `reject` → ask the user for a one-line reason via free-text follow-up; call `fab_review action="reject"` with `pending_paths=[path]` and `reason`.
-   - `modify` → see Modify Sub-Flow below.
-   - `defer` → call `fab_review action="defer"` with `pending_paths=[path]`; optional `until` ISO datetime if the user supplies one ("defer 2 weeks" → compute and set).
-   - `skip` → no MCP call; move to next item.
-7. After the loop, display a roll-up: counts by action, list of newly-allocated `stable_id`s (from approve output), and tail of `.fabric/events.jsonl` showing the appended events.
-
-### Mode: topic — Search & Surface Findings
-
-1. Extract the topic keyword(s) from the user's message (e.g. "find about deepMerge" → query="deepMerge").
-2. Call `fab_review action="search"` with `query` and any obvious filters (if user said "team-only" → `filters.layer="team"`).
-3. Server returns `items[]` ranked by relevance — these are entries already in `.fabric/knowledge/{layer}/{type}/` (NOT pending), unless `filters` says otherwise.
-4. Render top-N (cap at 8) results with title / summary / pending_path.
-5. If the user follow-up indicates intent to act ("approve all", "modify the second one"), pivot into the corresponding pending mode action — the search result already gives the `pending_path` needed for the action.
-6. NEVER surface a per-item AskUserQuestion just for browsing — only when the user signals an action verb.
-
-### Mode: health — Corpus Health & Stale Detection
-
-1. Call `fab_review action="list"` with `filters.maturity="draft"` (or no filter for full corpus inspection).
-2. Tail `.fabric/events.jsonl` for layer_changed / demoted / rejected counts in the trailing 30 days.
-3. Compute stale candidates: pending entries with mtime `>14 days` OR maturity=draft entries with no recent evidence-append events.
-4. Render a corpus dashboard:
-
-   ```md
-   ## Health Overview
-   - Pending: 12 entries (oldest 18d) — recommend `defer` or `reject`
-   - Drafts: 8 (3 are stale candidates: KP-G-3, KP-G-5, KT-P-9)
-   - Layer flips (30d): 2
-   - Rejections (30d): 1
-   ```
-
-5. For each stale candidate, surface AskUserQuestion `{options: ["defer", "demote", "skip"]}`; route `defer` → `fab_review action="defer"`, `demote` → `fab_review action="modify"` with `changes.maturity` lowered (or `reject` if the user wants outright removal of a pending entry).
-
-### Mode: revisit — Specific Entry Deep Dive
-
-1. The user referenced a specific entry (by id `KT-D-7` or by slug `single-cjs-hook`).
-2. Call `fab_review action="list"` with `filters` narrowed by best-guess fields; if the entry is canonical (has stable_id), `Read` the file directly at `.fabric/knowledge/{layer}/{type}/<id>--<slug>.md`.
-3. Display the full body (frontmatter + content). Tail the events.jsonl for any history events tagged with this stable_id.
-4. Surface AskUserQuestion `{options: ["approve", "modify", "reject", "skip"]}` only if the entry is still pending; for canonical entries the only mutation path is `modify` (incl. layer flip).
-
-## Semantic Check Guidance (LLM-Assisted Duplicate / Contradiction Detection)
-
-> Boundary B (locked): "extraction classification / layer inference / slug naming / mode inference / **semantic dedup** → Skill (LLM); pending file write / frontmatter assembly / idempotency check / counter mgmt / layer-flip transaction / atomic promote → MCP (deterministic)"
-
-Semantic check is the LLM's job — the MCP tool does NOT compare meaning. Run this check during `pending` mode (and on demand during `topic` mode):
-
-For each pending entry to be presented:
-
-1. Call `fab_review action="search"` with `query=<title or summary keywords>` and `filters.type=<same type>` to fetch already-canonical entries of the same type.
-2. Compare semantically (LLM judgment, not string match):
-   - **Duplicate** — same essential claim. Heuristics: title keyword overlap >60%, summary asserts the same outcome with no novel context. Flag: `⚠ Possible duplicate of <stable_id>`.
-   - **Contradiction** — opposing claims about the same subject. Heuristics: one entry says "use X" while pending says "avoid X" on identical scope. Flag: `⚠ Contradicts <stable_id>`.
-   - **Subsumption** — pending fully covered by an existing entry plus extras. Flag: `⚠ Subsumed by <stable_id>; consider modify-to-merge`.
-3. Surface the flag in the per-item display block (see pending mode step 4).
-4. The user decides:
-   - Still approve → flag is informational; pending becomes canonical alongside the existing entry.
-   - Modify-to-harmonize → user supplies edits via `modify` action; consider merging language with the existing entry.
-   - Reject as duplicate → reason field MUST cite the existing stable_id (e.g. `reason="duplicate of KT-D-7"`).
-
-DO NOT call `AskUserQuestion` to ask "is this a duplicate?" — the LLM has already judged. The user only chooses among approve / reject / modify, which is a genuine choice.
-
-## Modify Sub-Flow & Layer-Flip Rules
-
-`modify` is the only action that mutates frontmatter or stable_id. It accepts `changes` of shape `{title?, summary?, layer?, maturity?, tags?}`. Server semantics:
-
-- **title / summary / tags / maturity changes** → in-place rewrite; stable_id PRESERVED; emits `knowledge_slug_renamed` only when slug derives from title.
-- **layer change** → the ONLY legal stable_id mutation in the system.
-
-### Layer-Flip Rules (the only legal stable_id mutation)
-
-Triggered when `changes.layer` differs from current entry layer. Server-side transaction:
-
-1. Allocate new id under target layer via `KnowledgeIdAllocator.allocate(new_layer, type)` (e.g. KT-D-7 in `team/decisions/` flips to KP-D-3 in `personal/decisions/`).
-2. `git mv <old-layer>/<type>/<old-id>--<slug>.md <new-layer>/<type>/<new-id>--<slug>.md`.
-3. Append `knowledge_layer_changed` event with `{from_layer, to_layer, prior_stable_id, new_stable_id}`.
-4. Server response includes `prior_stable_id` and `new_stable_id` — surface BOTH to the user in the roll-up.
-
-Skill responsibilities for layer flip:
-
-- BEFORE calling fab_review, surface `AskUserQuestion {options: ["team", "personal"]}` to confirm target layer. The default in the question header should reflect the verbatim layer heuristic (default team unless 强 personal signals dominate). This IS a genuine choice — the user must pick.
-- AFTER server returns, render: `Layer flipped: <prior_stable_id> → <new_stable_id>`. Do NOT silently swallow the id change — downstream agents may have cached the prior id.
+**Quantified overlap band (rc.37 NEW-12).** The LLM still judges meaning (no embedding %), but MUST tag each flag with a 3-level band so the signal is comparable across entries and the user can triage at a glance:
 
-### Modify Examples
+- `high` — ≥ ~80% of the candidate's essential claim is restated; near-certain dup/contradiction. Recommend reject-as-duplicate or modify-to-merge.
+- `medium` — substantial conceptual overlap but the new entry adds a distinct facet (different path scope, added caveat). Recommend modify-to-harmonize.
+- `low` — adjacent topic, not a real overlap. Do NOT raise a flag at `low` — it is below the surfacing threshold (suppresses noise).
 
-```ts
-// Maturity bump only (no id change)
-mcp__fabric__fab_review({
-  action: "modify",
-  pending_path: "knowledge/team/decisions/KT-D-0007--single-cjs-hook.md",
-  changes: { maturity: "verified" }
-})
+Only `medium`+ flags are surfaced. User decides: still-approve (flag informational), modify-to-harmonize, or reject-as-duplicate (reason MUST cite existing stable_id).
 
-// Layer flip team → personal (id WILL change)
-mcp__fabric__fab_review({
-  action: "modify",
-  pending_path: "knowledge/team/guidelines/KT-G-0003--indent-style.md",
-  changes: { layer: "personal" }
-})
-```
+DO NOT AskUserQuestion "is this a duplicate?" — LLM already judged. User only chooses approve/reject/modify.
 
-## AskUserQuestion Policy
+`Read ref/semantic-check.md` for full procedure + 三类判断的细化定义.
 
-### DO ask (genuine choices that require human judgment)
+## Narrowing Imported Entries & Modify Sub-Flow
 
-- Per-pending-item action: `["approve", "reject", "modify", "defer", "skip"]`
-- Per-stale-item action (health mode): `["defer", "demote", "skip"]`
-- Layer-flip target when modify path includes layer change: `["team", "personal"]`
-- Reject reason follow-up (free-text, may use AskUserQuestion's free-form variant if available, otherwise plain prompt)
+`modify` is the only action that mutates frontmatter or stable_id. Two paths:
 
-### DO NOT ask (system must infer or operate deterministically)
+- **Title/summary/tags/maturity** → in-place rewrite; stable_id PRESERVED.
+- **Layer change** → ONLY legal stable_id mutation. BEFORE call, AskUserQuestion `{team, personal}` to confirm target (this IS genuine choice). AFTER server returns, surface BOTH `prior_stable_id` and `new_stable_id` in roll-up — downstream agents may cache the prior id.
 
-- Mode picking (pending / topic / health / revisit) — INFERRED per the 3-step algorithm
-- Whether to invoke this skill at all — Stop-hook signal or explicit user request decides
-- Whether an entry is a duplicate — LLM semantic check answers
-- Frontmatter parsing — deterministic, never asked
-- Allocate next id — deterministic via KnowledgeIdAllocator, never asked
+**Import-origin entries** (`source_sessions[0]` starts with `fabric-import-`) ship with `relevance_scope=broad + relevance_paths=[]` by design; narrowing is fabric-review's responsibility. Render `⚠ Imported (relevance_scope=broad, relevance_paths=[]) — pick 'modify' + say 'narrow to <paths>'` as informational hint. On `modify` of import-origin: extended option list `{narrow scope, edit summary, change layer, change maturity, skip}`; "narrow scope" → free-text follow-up → `changes: { relevance_scope: "narrow", relevance_paths: [<parsed>] }`. Personal layer auto-degrades narrow → broad+[] (server-side), emitting `knowledge_scope_degraded`.
 
-### Per-Item Question Phrasing Template
+`Read ref/modify-flow.md` for layer-flip server transaction (4-step), modify call shape examples (maturity bump / layer flip), and full narrowing flow with bilingual AskUserQuestion templates.
 
-```ts
-AskUserQuestion({
-  header: "Review pending entry",
-  question: "What action for '{title}'?  ({pending_path})",
-  options: ["approve", "reject", "modify", "defer", "skip"]
-})
-```
+## AskUserQuestion Policy
 
-For layer-flip target:
+**DO ask** (genuine choices): per-pending action `{approve, reject, modify, defer, skip}` · per-stale action `{defer, demote, skip}` · layer-flip target `{team, personal}` · reject reason follow-up (free-text).
 
-```ts
-AskUserQuestion({
-  header: "Layer-flip target",
-  question: "Move '{title}' to which layer?  (current: {current_layer})",
-  options: ["team", "personal"]
-})
-```
+**DO NOT ask**: mode picking (inferred) · whether to invoke skill (Stop-hook/explicit decides) · whether duplicate (LLM judges) · frontmatter parsing (deterministic) · next id allocation (deterministic via KnowledgeIdAllocator).
+
+`Read ref/askuserquestion-policy.md` for full DO/DO NOT lists + bilingual per-item question phrasing templates (pending action / layer-flip target).
 
 ## Decision Tree — Is This Entry Approvable?
 
@@ -289,94 +173,16 @@ Pending entry presented for review
 - NEVER batch heterogeneous decisions into a single MCP call. Approve and reject MAY be batched within their own action; modify MUST be one call per entry.
 - NEVER invoke `fab_review action="approve"` without at least one `pending_paths` entry.
 - NEVER infer a layer-flip target — the user MUST choose via AskUserQuestion.
-- MUST preserve protected tokens exactly: `stable_id`, `pending_path`, `layer`, `team`, `personal`, `knowledge_promoted`, `knowledge_layer_changed`, `knowledge_proposed`, `fab_review`, `MUST`, `NEVER`.
-
-## Output Contract
-
-After each invocation, the skill MUST produce a brief roll-up to the user:
-
-```md
-# Review Summary — mode={pending|topic|health|revisit}
-- Listed: N entries
-- Approved: M (new stable_ids: KT-D-12, KT-G-4, KP-P-2)
-- Rejected: R
-- Modified: U (incl. K layer flips)
-- Deferred: D
-- Skipped: S
-
-## Events appended (.fabric/events.jsonl tail)
-- knowledge_promote_started ×M
-- knowledge_promoted ×M
-- knowledge_layer_changed ×K
-- knowledge_rejected ×R
-- knowledge_deferred ×D
-```
-
-Also surface a one-line `git status` of `.fabric/knowledge/` so the user sees the file moves caused by approve / layer-flip.
-
-## Worked Examples
-
-### Example A — pending mode with semantic check flagging a duplicate (user chooses reject)
-
-User: "review the pending knowledge".
-
-Inferred mode: `pending` (Step 1 keyword "review … pending").
-
-Skill flow:
-
-1. `fab_review action="list"` → returns 3 pending items.
-2. Semantic check on item 2 (`pending/decisions/single-cjs-hook.md`) — `fab_review action="search"` with `query="single cjs hook"` filter `type=decisions` returns canonical `KT-D-0007--single-cjs-hook-across-clients.md` (similarity high).
-3. Display block:
-
-   ```md
-   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
-   Title: 单 .cjs hook 跨客户端
-   Summary: 三客户端 stdout JSON 格式一致，单脚本即可。
-   ⚠ Possible duplicate of KT-D-0007 (similarity 0.84 on title + summary)
-   ```
-
-4. AskUserQuestion fires; user picks `reject`.
-5. Free-text follow-up: user types `duplicate of KT-D-7`.
-6. `fab_review action="reject"` with `pending_paths=["knowledge/pending/decisions/single-cjs-hook.md"]` and `reason="duplicate of KT-D-7"`.
-7. Roll-up reports: 1 rejected, 0 approved, events appended.
-
-### Example B — revisit mode with layer flip (KT → KP)
-
-User: "look at KT-G-3, that's actually personal not team".
-
-Inferred mode: `revisit` (Step 1 keyword "look at <id>").
-
-Skill flow:
-
-1. Read `.fabric/knowledge/team/guidelines/KT-G-0003--indent-style.md`. Display body to user.
-2. AskUserQuestion `{options: ["approve", "modify", "reject", "skip"]}` — user picks `modify`.
-3. Skill detects user-stated intent "actually personal not team" — surface AskUserQuestion `{options: ["team", "personal"]}` with current layer=team noted; user confirms `personal`.
-4. Call:
-
-   ```ts
-   mcp__fabric__fab_review({
-     action: "modify",
-     pending_path: "knowledge/team/guidelines/KT-G-0003--indent-style.md",
-     changes: { layer: "personal" }
-   })
-   ```
+- MUST preserve protected tokens exactly: `stable_id`, `pending_path`, `layer`, `team`, `personal`, `knowledge_promoted`, `knowledge_layer_changed`, `knowledge_proposed`, `knowledge_scope_degraded`, `fab_review`, `MUST`, `NEVER`, `relevance_scope`, `relevance_paths`, `narrow`, `broad`, `proposed_reason`, `session_context`.
 
-5. Server returns `{prior_stable_id: "KT-G-0003", new_stable_id: "KP-G-0001"}`.
-6. Roll-up: `Layer flipped: KT-G-0003 → KP-G-0001`. `git status` shows the rename across layer roots.
+## Output Contract & events.jsonl Constraint (ref-only)
 
-### Example C — health mode finding stale entries (defer 2, demote 1)
+After each invocation, produce a bilingual `# Review Summary` (en) / `# Review 汇总` (zh-CN) roll-up: listed/approved/rejected/modified/deferred/skipped counts + new stable_ids + tail of `.fabric/events.jsonl` events (`knowledge_promote_started`, `knowledge_promoted`, `knowledge_layer_changed`, `knowledge_rejected`, `knowledge_deferred`). Also surface `git status` of `.fabric/knowledge/` so file moves are visible.
 
-User: "anything stale in our knowledge base?"
+events.jsonl appends MUST stay single-line + ≤4KB (POSIX `PIPE_BUF` atomicity).
 
-Inferred mode: `health` (Step 1 keyword "stale").
+`Read ref/output-contract.md` for full bilingual rollup templates + per-field self-truncate caps (`session_context` 500 chars; `source_sessions` 5 entries; `recent_paths` 20 entries; `user_messages_summary` 500 chars).
 
-Skill flow:
+## Worked Examples (ref-only)
 
-1. `fab_review action="list"` (no filter) + tail events.jsonl for trailing-30d demoted/layer_changed counts.
-2. Compute stale candidates: 3 pending entries with mtime >14d (KP-G-5 candidate-pending, KT-P-9 candidate-pending, KP-G-3 canonical draft with no evidence-append in 21d).
-3. Render dashboard then loop per stale item.
-4. Per-item AskUserQuestion fires:
-   - KP-G-5 → user picks `defer` (until="2026-06-01") → `fab_review action="defer"` with `until` set.
-   - KT-P-9 → user picks `defer` (no until) → `fab_review action="defer"` with no `until`.
-   - KP-G-3 → user picks `demote` → `fab_review action="modify"` with `changes.maturity="draft"` (already draft; equivalently demote means reject if pending — skill chooses correct action by inspecting current state).
-5. Roll-up: 2 deferred, 1 modified, events appended (`knowledge_deferred ×2`, `knowledge_promote_started/promoted` not relevant; `knowledge_layer_changed` not relevant).
+Four worked examples (pending-mode dedupe / revisit layer-flip / health mode / narrowing imported entries) live in `ref/worked-examples.md`. Load when you want to see how Mode + AskUserQuestion + MCP-call shape composes on real candidate sets.