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

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

@@ -1,588 +1,151 @@
 ---
 name: fabric-import
-description: Use this skill for cold-start enrichment of `.fabric/knowledge/` from existing project artifacts — mines `git log` and `docs/*.md` for candidate observations, proposes pending entries via `fab_extract_knowledge`, then deduplicates against canonical entries via `fab_review action: search` (rejecting obvious duplicates, modifying-to-merge marginal duplicates). Triggered by user prompts like "import knowledge from git history" / "bootstrap fabric for this repo" or by an explicit fabric-import skill mention. Default layer: team (project artifacts are team-shared). The 3-phase pipeline is resumable via `.fabric/.import-state.json`.
+description: 冷启动从 git log + docs/*.md 回灌 .fabric/knowledge/pending (NOT code/data import). Triggers 导入历史/bootstrap fabric/mine changelog/挖掘 commit.
 allowed-tools: Read, Glob, Grep, Bash, mcp__fabric__fab_extract_knowledge, mcp__fabric__fab_review
 ---
 
-> **Surface**: This is a Skill (AI-driven, LLM judgment over git log + docs for cold-start enrichment). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md) for the CLI / Skill / MCP boundary.
+> **Surface**: Skill (LLM judgment over git + docs). See [`docs/surfaces.md`](https://github.com/fenglimg/fabric/blob/main/docs/surfaces.md).
 
 ## Purpose
 
-`fabric-import` is a one-time (per project) cold-start skill that lifts existing project artifacts — git commit history and Markdown documentation — into the knowledge layer as pending entries. It is the bridge between a brand-new Fabric installation (which only has the 4–7 baseline entries produced by `fabric init`'s deterministic scan) and a useful corpus that reflects accumulated team thinking. Run it once when adopting Fabric on an existing repo, or after a major refactor that invalidates large chunks of canonical knowledge. Default layer is `team`: project artifacts in git/docs are team-shared by definition; the user can later layer-flip individual entries to `personal` via `fabric-review` modify.
+One-time per-project cold-start: lift git commits + `docs/*.md` into `.fabric/knowledge/pending/` as `team`-layer entries. Bridges `fabric install`'s 4-7 baseline → accumulated corpus. Run once on adoption or after major refactor.
 
 ## Precondition
 
-This skill is invoked when one of the following holds:
+Invoke only when ANY: user explicit ("import knowledge" / "bootstrap fabric" / "mine changelog"); user named skill; SessionStart hook fired `shouldRecommendImport()`.
 
-- The user typed an explicit import request (e.g. "import knowledge from git history", "bootstrap fabric for this repo", "mine the changelog into pending", "fabric import")
-- The user explicitly mentioned this skill by name (`fabric-import`)
-- A `fabric import` CLI command was run (rc.4 wires this if shipped; otherwise treat as user prompt)
+Else stop: `没有触发 import 信号；如需手动 import 请显式调用 fabric-import` / `No import signal detected; to manually import, explicitly invoke fabric-import` (per `fabric_language`).
 
-If none of the above hold, stop the skill immediately and tell the user `没有触发 import 信号；如需手动 import 请显式调用 fabric-import`.
+SKIP when: `.fabric/` missing (→ `fabric install`); canonical > `import_skip_canonical_threshold` (default 50); state file `phase=complete` + `last_checkpoint_at <24h`.
 
-### Phase 0 — Sentinel Contract (rc.7 T1)
+Required: `.fabric/` exists, `agents.meta.json` present, MCP `fab_extract_knowledge` + `fab_review` registered, working tree reasonably clean.
 
-**Sentinel file**: `.fabric/.import-requested` (empty content; presence-as-data).
+## Phase 0 — Init
 
-This file is the cross-surface signal between `fabric init` (run in the
-user's terminal) and the AI client session that picks up the import
-recommendation. When `fabric init` ends with the clack confirm prompt
-"下次开 AI 时让我从 git log 抽更多知识吗?" and the user answers Y, the
-CLI writes this empty sentinel file. Two hooks read it:
+Read/init `.fabric/.import-state.json`. Scan stale `.tmp-import-*`. State-corruption recovery → `Read .../ref/state-recovery.md`.
 
-- `templates/hooks/knowledge-hint-broad.cjs` (SessionStart) — appends an
-  import-recommendation banner to the broad-injection stderr regardless of
-  the rc.7 T8 `revision_hash` gate.
-- `templates/hooks/fabric-hint.cjs` (Stop) — bypasses the Signal C cooldown
-  and emits the `signal:'import'` recommendation even when the underseed
-  threshold or 24h cooldown would otherwise silence it.
+> 旧 `.fabric/.import-requested` sentinel 机制已下线 (rc.8+);推荐由 SessionStart hook 的 underseed 自检触发(`shouldRecommendImport()`)。本 skill 不再读写 sentinel。
 
-**Phase 0 action for this skill**: read the sentinel state at the start of
-this skill invocation (informational only — proceed regardless of presence).
-The sentinel is **cleared in Step 3.4** (Phase 3 Completion) so subsequent
-sessions stop receiving the unconditional recommendation. If the skill
-fails or the user aborts before Step 3.4, the sentinel remains and the next
-session will see the recommendation again — this is intentional, the
-import is incomplete.
+## Phase 0.5 — Config Load
 
-This skill SHOULD be skipped (warn the user, do not proceed) when:
+Read `.fabric/fabric-config.json` for tunables (defaults if absent):
 
-- `.fabric/` does not exist — direct the user to run `fabric init` first; `fabric-import` is NOT a substitute for the deterministic init-scan
-- `.fabric/knowledge/` already holds **>50 canonical entries** across all types — the project is mature; use `fabric-archive` (per-session capture) and `fabric-review` (lifecycle review) instead; bulk import would just create dup churn
-- `.fabric/.import-state.json` exists with `phase: "complete"` and `last_checkpoint_at` is **<24h ago** — the user just ran import; surface the prior result rather than re-running
+| Field | Default |
+|---|---|
+| `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 |
 
-Required preconditions before any MCP call:
+First-run vs re-run by state file (ENOENT or `phase != complete && proposed == 0` → first-run window).
 
-- `.fabric/` directory exists in the project root
-- `.fabric/agents.meta.json` is present (init produced it; the id allocator reads it on later approve)
-- `.fabric/events.jsonl` exists (tolerate ENOENT — empty ledger is normal first-run)
-- `mcp__fabric__fab_extract_knowledge` AND `mcp__fabric__fab_review` MCP tools are registered and reachable
-- Working tree is reasonably clean (large uncommitted churn pollutes git-log mining; warn but allow)
+### Store routing (v2.1 multi-store)
 
-## 3-Phase Pipeline (P1 reference / P2 mine / P3 dedup)
+Import requires an **explicit target store** (E7) — mined entries are NOT auto-routed. Resolve candidates via `fabric scope-explain team` (writable stores in the read-set); if more than one writable store exists, `AskUserQuestion` for the target store alias before persisting (header/question translate, the alias options stay English routing keys). Single writable store → use it. Persist through `fab_extract_knowledge` with the chosen store; echo the target alias. Never write to a store the project did not declare (read-set bound).
 
-The pipeline runs strictly in order. Each phase reads the prior phase's outputs and updates `.fabric/.import-state.json` after every successful sub-step (not just at phase end). The skill is `Infer-not-Ask` for which phase to run (always all three when starting fresh, or resumes from the checkpoint phase).
+## UX i18n Policy
 
-### Phase 1 — Init-Scan Reference (NO RE-IMPLEMENTATION)
+Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`). Emit prose per variant. Protected tokens NEVER translate (`fab_extract_knowledge`, `fab_review`, `.fabric/.import-state.json`, all enum strings, `MUST`/`NEVER`). Full 5-class taxonomy → `Read .../ref/i18n-policy.md`.
 
-> Verbatim boundary: `fabric init` (rc.1, deterministic CLI) already produces the baseline scan. Phase 1 of this skill **REFERENCES** that output. It does NOT redo the scan.
+## 3-Phase Pipeline
 
-The deterministic init-scan has already populated `.fabric/knowledge/team/` with 4–7 baseline entries derived from:
+Strict P1→P2→P3 order. State write after every sub-step. Infer-not-Ask.
 
-- `package.json` (tech stack, scripts, key dependencies)
-- `README.md` first paragraph (project elevator pitch)
-- Build configuration (`tsconfig.json`, `pyproject.toml`, `Cargo.toml`, etc.)
-- Code style (`.editorconfig`, lint config)
-- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`, etc.) when present
-- The first sentence of any top-level `LICENSE` (rare baseline signal)
+### Phase 1 — Init-Scan Reference (NO RE-IMPLEMENT)
 
-Phase 1 actions performed by THIS skill:
+`fabric install` produced baseline. Phase 1 REFERENCES, does NOT redo.
 
-1. Read `.fabric/agents.meta.json` to confirm baseline counters exist (each type's `next_id` should be `>1` if init-scan landed entries; `=1` means init produced zero entries of that type — informational, not an error).
-2. Glob `.fabric/knowledge/team/**/*.md` to enumerate baseline entry titles. Capture the list — Phase 2 uses these titles as a **negative filter** (signals already covered by init-scan should be skipped, not re-proposed).
-3. If `.fabric/agents.meta.json` is missing OR `.fabric/knowledge/team/` is empty: STOP. Tell the user `请先运行 fabric init 完成基线扫描，再调用 fabric-import` and exit.
-4. Update `.fabric/.import-state.json`: `phase = "P1-done"`, `p1_baseline_titles = [<list>]`, `last_checkpoint_at = <ISO8601 now>`.
+1. Read `agents.meta.json` → confirm baseline counters.
+2. Glob `.fabric/knowledge/team/**/*.md` → titles for P2 negative filter.
+3. If meta missing OR team/ empty: STOP. Tell user `请先运行 fabric install 完成基线扫描` / `Please run fabric install first` and exit.
+4. State: `phase=P1-done`, `p1_baseline_titles=[...]`, `last_checkpoint_at=<ISO>`.
 
-**Phase 1 produces no MCP calls.** It only reads the on-disk init-scan output.
+No MCP calls.
 
-### Phase 2 — LLM-Driven Git + Doc Mining
+### Phase 2 — LLM-Driven Mining
 
-For each candidate signal mined from git or docs, the skill classifies into one of the 5 types (`decisions / pitfalls / guidelines / models / processes`), drafts a slug per the 5-rule naming guideline (see fabric-archive for the canonical rules), and proposes a pending entry via `fab_extract_knowledge`. Default layer for every Phase 2 proposal: `team`.
+Classify each candidate into 5 types (decisions/pitfalls/guidelines/models/processes), draft slug, propose via `fab_extract_knowledge`. Layer: `team`.
 
-#### Mandatory Scope Rule — Always Broad + Empty Paths (Q-1 Resolution)
+#### Mandatory Scope Rule — broad + empty paths (NON-NEGOTIABLE)
 
-**EVERY `fab_extract_knowledge` call issued from this skill MUST set:**
+Every call MUST `relevance_scope="broad"` AND `relevance_paths=[]`. No exceptions. Why: import is LLM-driven (not session-driven); LLM-inferred narrow lies about applicability. Post-rc.37 A1 the server returns every selectable entry regardless of scope, so false-narrow no longer hides knowledge — but it still poisons doctor lint accounting + downstream consumers that read `relevance_paths` literally. Narrowing deferred to `fab_review.modify` post-import when the user has the real applicability surface. Full rationale + prohibitions + doctor lint #23 → `Read .../ref/phase-2-mining.md`.
 
-- `relevance_scope = "broad"`
-- `relevance_paths = []`
+#### Step 2.1 — Git Mining
 
-This is non-negotiable and applies to BOTH Step 2.1 (git mining) AND Step 2.2 (docs mining). No exceptions, no per-candidate override, no Agent judgment.
+`git log --since="<window> months ago" --pretty=format:"%H%n%s%n%b%n---ENDCOMMIT---" -n <cap>`. Conventional prefix → type signal (feat→decision/model, fix→pitfall, refactor→decision, docs→guideline; chore/test/ci skip). Extract observation → Skip Tree → `fab_extract_knowledge` (broad+[]). Cap: `import_max_pending_per_run`.
 
-**Rationale — why fabric-import cannot bind paths from git history:**
+#### Step 2.1.5 — Proposed Reason
 
-1. `fabric-import` is LLM-driven (mines git log + docs), not session-driven (no live `edit_paths` signal).
-2. `git diff --stat` lists files touched by a commit, but those files are the commit's **effect surface**, not the **applicability surface** of the underlying observation. A pitfall surfaced by a fix in `packages/server/src/retry.ts` may apply to every retry call-site in the repo, not just that one file.
-3. LLM-inferred `relevance_paths` from historical commit metadata produces false-narrow bindings — entries get filtered out for paths they actually govern. False-narrow is worse than broad because it silently hides knowledge during plan-context filtering.
-4. Doc-mined observations are usually architectural / cross-cutting (a `docs/architecture.md` "Why a monolith?" decision applies to the whole codebase, not just to `docs/`).
+Infer one of: `decision-confirmation` | `new-dependency-or-pattern` | `wrong-turn-revert` | `diagnostic-then-fix` | `explicit-user-mark` | `dismissal-with-reason`. Fallback: `new-dependency-or-pattern`. 11-row table → ref.
 
-**Strict prohibitions — DO NOT attempt any of the following:**
-
-- DO NOT derive `relevance_paths` from `git log --name-only` / `git show --stat` / `git diff` file lists.
-- DO NOT derive `relevance_paths` from the path of a mined Markdown file (e.g. do NOT bind a `docs/architecture.md` observation to `["docs/**"]`).
-- DO NOT extract path-shaped tokens from commit subjects / bodies / doc text and lift them into `relevance_paths`.
-- DO NOT classify a candidate as `relevance_scope = "narrow"` under ANY heuristic.
-- DO NOT copy the public-prefix-generalization logic from fabric-archive Phase 1.5 — that logic is valid only when bound to a real-time `edit_paths` signal from an active session, which fabric-import lacks.
-
-**Cross-reference — fabric-import vs fabric-archive scope handling:**
-
-| Skill            | Scope decision     | Why                                                                   |
-|------------------|--------------------|-----------------------------------------------------------------------|
-| `fabric-archive` | narrow OR broad, case-by-case per Phase 1.5 rules | Has live `edit_paths` from the active session — the actual applicability surface. |
-| `fabric-import`  | ALWAYS broad + `[]` (this skill) | LLM-only, no live session signal; git-history paths are effect-surface, not applicability-surface. |
-
-`fabric-archive`'s Phase 1.5 scope decision (narrow-vs-broad rules + public-prefix generalization + glob blacklist) is INTENTIONALLY MORE PERMISSIVE than fabric-import because archive has the data to bind safely. fabric-import is the STRICTER case.
-
-**Post-import narrowing path — deferred to user, via `fab_review.modify`:**
-
-After import completes, the user reviews each kept pending entry via `fabric-review`. When the user judges that an imported entry is actually narrow-scoped, they (or the reviewing Agent on their explicit instruction) issue:
+#### Step 2.2 — Docs Mining
 
-```ts
-mcp__fabric__fab_review({
-  action: "modify",
-  pending_path: "<the imported pending or its post-approval canonical path>",
-  changes: {
-    relevance_scope: "narrow",
-    relevance_paths: ["packages/server/src/retry/**", "packages/server/src/lib/retry.ts"]
-  }
-})
-```
+`find docs/ -maxdepth 3 -name '*.md'` + root `*.md`. Skip README / CHANGELOG / LICENSE / CODE_OF_CONDUCT / CONTRIBUTING / <300B files. Same call shape. Shared cap.
 
-This is the ONLY legal path for an imported entry to acquire `relevance_paths`. The narrowing decision is the user's, informed by the actual `relevance_paths` candidates they propose — not the skill's, inferred from git metadata.
+#### Skip Decision Tree
 
-**Lint backstop:** doctor lint #23 (`narrow_no_paths`) warns on any `relevance_scope=narrow` entry with empty `relevance_paths`. If this skill ever deviates from the broad+[] rule and writes narrow without paths, lint #23 catches the mistake post-hoc.
+Skip if: cosmetic-only / metadata-only / in baseline / not classifiable / slug not derivable to 2-5 kebab words.
 
-#### Step 2.1 — Git Log Mining
+#### Dry-Run
 
-Bash command (executed via the `Bash` tool):
+Explicit token `--dry-run` in invocation → skip MCP, render bilingual preview table (every Scope row `broad+[]`). State NOT written. P3 skipped. v2.0.0-rc.37 NEW-10 dropped legacy substring fallback on bare `dry-run` / `预览` (false-positive on incidental mentions).
 
-```bash
-git log --since="2 months ago" --pretty=format:"%H%n%s%n%b%n---ENDCOMMIT---" -n 200
-```
+Full MCP call shape, Step 2.1.5 table, dry-run templates, T5 idempotency → `Read .../ref/phase-2-mining.md`.
 
-Tolerate empty output (shallow clone or new repo). Cap the working set at the **most recent 200 commits** regardless of date range to bound LLM context.
+### Phase 3 — LLM-Driven Dedup
 
-For each commit:
+For each P2 pending: check vs canonical. Semantic compare is LLM's job — `fab_review` does NOT compare meaning.
 
-1. Inspect the conventional-commit prefix in the subject line. Strong signals:
-   - `feat(...)` with a non-empty body → likely **decision** or **model** (a new capability landed; the body usually explains why)
-   - `fix(...)` with body length >100 chars → likely **pitfall** (a bug worth diagnosing was non-trivial)
-   - `refactor(...)` with body → likely **decision** (architectural choice was made)
-   - `docs(...)` → usually a **guideline** if the body announces a convention; skip if it's just typo/reformat
-   - `chore(...)`, `test(...)`, `ci(...)` → almost always skip (mechanical; no reusable insight)
-2. Read the commit body. Extract the LLM-judged "core observation" — what would a future engineer want to know about this commit beyond the diff? Aim for 1–2 sentences in zh-CN (project knowledge_language; mirror fabric-archive M3 style).
-3. Apply the **Skip Decision Tree** below. If the commit is skip-worthy, record it in `p2_processed_commits[]` with `skipped: true` and move on.
-4. For non-skipped commits, classify type / propose slug / draft summary. Then call `fab_extract_knowledge` with the **mandatory broad + [] scope** (see "Mandatory Scope Rule" above):
+1. **3.1** — `fab_review action="search"` filter by `type`, top 5.
+2. **3.2** — Classify each pair: `duplicate` (reject pending) | `subsumption` (reject pending) | `subsumption-with-novelty` (modify canonical + reject pending) | `contradiction` (leave + flag) | `genuinely-new` (keep).
+3. **3.3** — Issue `fab_review` reject / modify.
+4. **3.4** — `phase=complete` + `final_summary` + roll-up.
 
-```ts
-mcp__fabric__fab_extract_knowledge({
-  source_sessions: ["fabric-import-<ISO8601-date>"],   // T5: array form; stable per import run
-  recent_paths: ["<files touched by this commit, capped at 20>"],   // provenance only, NOT a path-binding signal
-  user_messages_summary: "<zh-CN 1-2 sentence summary of the commit's core observation; cite the commit sha as 'src=<sha7>'>",
-  type: "decisions" | "pitfalls" | "guidelines" | "models" | "processes",
-  slug: "<kebab-case 2-5 words derived from commit subject + body>",
-  relevance_scope: "broad",                                          // MANDATORY — never "narrow" from fabric-import
-  relevance_paths: [],                                               // MANDATORY — never derived from git history
-  // v2.0.0-rc.7 T6: fabric-import defaults to `new-dependency-or-pattern`
-  // because git-log mining surfaces newly-introduced abstractions/conventions.
-  // session_context cites the commit / doc origin so future-self reviewers
-  // know this is an LLM-mined entry rather than a live-session capture.
-  proposed_reason: "new-dependency-or-pattern",
-  session_context: "Imported from git log analysis. Origin: commit <sha7> (<subject 30 chars>). No live session — see commit body for full context."
-})
-```
+Full call shapes + 5-way classification → `Read .../ref/phase-3-dedup.md`.
 
-Note: `recent_paths` continues to carry the touched-file list for **provenance display** (so the user can audit which commit produced which entry). It is NOT lifted into `relevance_paths` — those two fields serve different purposes and the prohibition on path inference from git history applies.
+## Checkpoint Logic
 
-5. On success the server returns `{pending_path, idempotency_key}`. Append to `.fabric/.import-state.json`:
-   - `p2_processed_commits[].push({sha: <full sha>, skipped: false, pending_path, type, slug})`
-   - `last_checkpoint_at = <ISO8601 now>`
-   Update is atomic (write to temp file then rename) so a crash between commits never corrupts the state file.
-6. **Hard cap**: at most **10 new pending entries** per Phase 2 run. When the cap is reached, mark `p2_cap_reached = true` and stop git-log iteration (the user can re-invoke for more — idempotent resume picks up from the next unprocessed commit).
+State file `.fabric/.import-state.json` is single resumability source. Atomic write: Step A `Write .tmp` → Step B `Bash mv` (POSIX `rename(2)`). `Write` alone NOT atomic.
 
-#### Step 2.2 — Docs Mining
+Resume contract: re-invoke MUST NOT dup-propose / re-dedup. By `phase`: `P1-done`→2.1, `P2-done`→3.1, `complete <24h`→skip, `≥24h`→confirm.
 
-Bash command (executed via the `Bash` tool):
+Full rationale + 4KB POSIX constraint + state schema + 6-step Resume → `Read .../ref/checkpoint-state.md`.
 
-```bash
-find docs/ -maxdepth 3 -name '*.md' -type f 2>/dev/null
-ls -1 *.md 2>/dev/null   # root-level architectural docs
-```
+## Default Knobs
 
-For each Markdown file:
+Layer `team` / scope `broad` / paths `[]` are contract-locked (no override). Max pending = config / dry-run via keyword / re-run <24h blocked. Full table → ref.
 
-1. **Skip filter**:
-   - `README.md` → skip (its first paragraph already lives in init-scan; its body is too generic for fine-grained classification)
-   - `CHANGELOG.md` → skip (rendered from commit log; mining commits already covers it)
-   - `LICENSE.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md` → skip (boilerplate)
-   - Files <300 bytes → skip (too thin to extract meaningful observations)
-2. Read the file. Identify candidate observations: section headings that read like decisions ("we chose X over Y"), guidelines ("always do X"), pitfalls ("don't do Y because..."), or process steps ("the deploy procedure is..."). Architecture diagrams in fenced code blocks are strong **model** signals.
-3. For each observation, classify type / propose slug / draft summary. Call `fab_extract_knowledge` with the same shape as Step 2.1 (including the **mandatory `relevance_scope: "broad"` + `relevance_paths: []`**), replacing `recent_paths` with `[<this doc path>]` and citing `src=<doc-relative-path>` in the summary. The mined doc's own path goes into `recent_paths` for provenance display ONLY — it is NOT lifted into `relevance_paths`.
-4. Append to `.fabric/.import-state.json`:
-   - `p2_processed_docs[].push({path: <doc path>, observations_proposed: <count>, pending_paths: [...]})`
-5. **Hard cap shared with Step 2.1**: total new pending entries across git + docs is capped at 10 per Phase 2 run.
+## Hard Rules
 
-#### Skip Decision Tree (when to NOT propose)
+### DISPLAY (per entry)
 
-```
-A candidate signal surfaces (commit body or doc section).
-  ├─ Is it cosmetic only? ("fix typo", whitespace, formatting)
-  │    └─ YES → skip
-  ├─ Is the body just metadata? (Co-Authored-By, Signed-off-by, no prose)
-  │    └─ YES → skip
-  ├─ Is the same observation already covered by an init-scan baseline title (Phase 1 list)?
-  │    └─ YES → skip (don't re-propose what init already captured)
-  ├─ Does the observation fit one of {decisions, pitfalls, guidelines, models, processes}?
-  │    └─ NO  → skip (not classifiable = not yet ripe)
-  ├─ Is the slug derivable as 2-5 kebab-case words?
-  │    └─ NO  → skip (signal too vague for stable identifier)
-  └─ Else → propose via fab_extract_knowledge
-```
+`[type=...]` `[layer=team]` `[scope=broad]` `slug=...` `src=<sha7-or-path>` + `pending_path`. zh-CN body + EN headings. Roll-up: proposed / kept / rejected_dup / merged / contradictions_flagged. Final `phase` on exit. Never hide source / show `idempotency_key` / auto-classify `personal`.
 
-After Step 2.2 completes (or hits the cap), update `.fabric/.import-state.json`: `phase = "P2-done"`, `last_checkpoint_at = <ISO8601 now>`.
+### WRITE
 
-#### Dry-Run Mode
+NEVER write entry via `Edit`/`Write`/`Bash` — only `fab_extract_knowledge` (P2) + `fab_review` (P3).
 
-When the user invocation includes `dry-run` / `预览` / `--dry-run` keywords, Phase 2 runs WITHOUT calling `fab_extract_knowledge`. Instead it prints a table:
+NEVER batch P2 candidates / skip P1 ref / call `fab_review.approve` / `git mv` directly / infer layer-flip / non-atomic state / exceed cap / `relevance_scope="narrow"` / non-empty `relevance_paths` / copy fabric-archive Phase 1.5 logic.
 
-```md
-# Import Dry Run — would propose N pending entries (all relevance_scope=broad, relevance_paths=[])
+Narrowing post-import = `fab_review.modify` (out-of-band).
 
-| # | Source                | Type      | Slug                          | Scope | Summary (zh-CN)                                            |
-|---|-----------------------|-----------|-------------------------------|-------|------------------------------------------------------------|
-| 1 | git c0a351d           | decisions | layer-flip-id-mutation        | broad+[] | layer 切换是唯一合法的 stable_id 变更途径，绑定原子事务。 |
-| 2 | docs/architecture.md  | decisions | monolith-over-microservices   | broad+[] | 决定保留单体架构，三人团队不值微服务运维成本。            |
-| 3 | git 50367b5           | pitfalls  | thundering-herd-no-backoff    | broad+[] | 重试无指数回退导致雪崩；必须 jittered exponential backoff。|
-```
-
-Every dry-run row MUST show `broad+[]` in the Scope column (it is a constant for fabric-import). A row showing anything else is a skill bug — refuse to proceed and surface the violation. Dry-run output is informational only. The state file is NOT written to in dry-run mode (so a real run later starts clean). Phase 3 is also skipped in dry-run.
-
-### Phase 3 — LLM-Driven Dedup vs Canonical
-
-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.**
-
-#### 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({
-  action: "search",
-  query: "<title or summary keywords from the pending entry>",
-  filters: { type: "<same type as pending>" }
-})
-```
-
-The server returns ranked `items[]` of CANONICAL entries (not pending) of the same type. Cap the comparison set at the top 5 results.
-
-#### Step 3.2 — Semantic Compare
-
-For each `(pending, canonical)` pair the LLM judges:
-
-- **Duplicate** — same essential claim. Heuristics: title keyword overlap >60%, summary asserts the same outcome with no novel evidence. 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.
-- **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
-
-For each `reject`-classified pending:
-
-```ts
-mcp__fabric__fab_review({
-  action: "reject",
-  pending_paths: ["<the new pending path>"],
-  reason: "duplicate of <stable_id of canonical>"   // OR "subsumed by <stable_id>"
-})
-```
-
-For each `subsumption-with-novelty` case (modify canonical, then reject pending):
-
-```ts
-// Step A: merge new evidence into canonical
-mcp__fabric__fab_review({
-  action: "modify",
-  pending_path: "<canonical's pending_path-style relative path>",
-  changes: { summary: "<merged summary; original + new evidence cite>" }
-})
-
-// Step B: reject the now-superseded pending
-mcp__fabric__fab_review({
-  action: "reject",
-  pending_paths: ["<the new pending path>"],
-  reason: "merged into <stable_id of modified canonical>"
-})
-```
-
-Append to `.fabric/.import-state.json` after EACH successful MCP call:
-
-- `p3_dedup_completed[].push({pending_path: <new pending>, action: "reject" | "modify-then-reject" | "kept", canonical_ref: "<stable_id>" | null})`
-- `last_checkpoint_at = <ISO8601 now>`
-
-#### Step 3.4 — Phase 3 Completion
-
-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 below).
-- **rc.7 T1 sentinel clear**: if `.fabric/.import-requested` exists (the
-  cross-surface signal from `fabric init`'s Y-confirm hand-off — see Phase 0
-  contract below), delete it now via `Bash: rm -f .fabric/.import-requested`.
-  Failure to remove is non-fatal: log a warning but do not error out — the
-  user can manually delete the sentinel if needed. The sentinel's lifecycle
-  ends here so the SessionStart and Stop hooks stop unconditionally
-  recommending fabric-import.
-
-The user MAY manually delete `.fabric/.import-state.json` to reset, or the skill MAY offer a one-line "reset state and re-run from scratch?" prompt the next time it is invoked with `phase="complete"` already present.
-
-## Checkpoint Logic — `.fabric/.import-state.json`
-
-The state file lives at `.fabric/.import-state.json` and is the single source of resumability for fabric-import. It is written via `atomicWriteJson` (write-temp-then-rename) so a crash between phases / between sub-steps never corrupts it.
-
-### Schema (all fields)
-
-```json
-{
-  "phase": "P1-done | P2-done | complete",
-  "started_at": "<ISO8601 first invocation>",
-  "last_checkpoint_at": "<ISO8601 most recent successful sub-step>",
-  "p1_baseline_titles": ["<title1>", "<title2>"],
-  "p2_processed_commits": [
-    { "sha": "<full sha>", "skipped": true,
-      "skip_reason": "cosmetic | metadata-only | already-in-baseline | unclassifiable | overlong-slug" },
-    { "sha": "<full sha>", "skipped": false,
-      "pending_path": "knowledge/pending/<type>/<slug>.md",
-      "type": "<one of 5>", "slug": "<kebab-case-slug>" }
-  ],
-  "p2_processed_docs": [
-    { "path": "docs/<file>.md", "observations_proposed": 2,
-      "pending_paths": ["<path1>", "<path2>"] }
-  ],
-  "p2_cap_reached": false,
-  "p3_dedup_completed": [
-    { "pending_path": "<new pending path>",
-      "action": "reject | modify-then-reject | kept",
-      "canonical_ref": "<stable_id or null>" }
-  ],
-  "errors": [
-    { "step": "P2.git", "ref": "<commit sha or doc path>", "error": "<message>" }
-  ],
-  "final_summary": {
-    "proposed": 0, "kept": 0, "rejected_dup": 0, "merged": 0, "contradictions_flagged": 0
-  }
-}
-```
-
-### Resume Logic (Idempotent Re-Invocation)
-
-On every skill invocation, BEFORE Phase 1 starts:
-
-1. Read `.fabric/.import-state.json`. ENOENT → fresh run, initialize state with `phase: "P1-done"` after Phase 1 completes (state file is created at end of Phase 1, not at start).
-2. If `phase === "complete"` AND `last_checkpoint_at < 24h ago` → SKIP this invocation (precondition warning above) unless user explicitly typed `re-run import` or `reset import`.
-3. If `phase === "complete"` AND `last_checkpoint_at ≥ 24h ago` → ask the user (free-text prompt, NOT AskUserQuestion since this is rare): "上次 import 已完成 (<N> 天前)。重新运行将基于当前 canonical 重做 P2/P3。继续？(y/n)"; if `n`, exit.
-4. If `phase === "P1-done"` → skip Phase 1; resume from Phase 2 Step 2.1; iterate git log skipping any sha already in `p2_processed_commits[]`.
-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), atomically write the updated state file. 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.
-
-## Default Behavior & Knobs
-
-| Knob                                | Default     | Override                                                       |
-|-------------------------------------|-------------|----------------------------------------------------------------|
-| Layer for new entries               | `team`      | User explicit instruction ("import these as personal")         |
-| `relevance_scope` for new entries   | `broad`     | NONE — contract-locked; narrowing deferred to `fab_review.modify` post-import |
-| `relevance_paths` for new entries   | `[]`        | NONE — contract-locked; populating deferred to `fab_review.modify` post-import |
-| Max new pending entries per P2 run  | `10`        | User explicit ("import up to 25"); skill caps at 50 hard       |
-| Git log window                      | `2 months`  | User explicit ("import the full year")                         |
-| Docs scan depth                     | `3`         | User explicit ("scan docs/ recursively")                       |
-| Dry-run mode                        | OFF         | User keyword `dry-run` / `预览` / `--dry-run`                  |
-| Re-run within 24h of complete       | BLOCKED     | User keyword `re-run import` / `reset import`                  |
-
-## Hard Rules — DISPLAY / WRITE Split
-
-### DISPLAY Rules
-
-- MUST present every proposed pending entry with explicit `[type=...]`, `[layer=team]`, `[scope=broad]`, `slug=...`, AND `src=<commit-sha7 or doc-path>` so the user can audit the provenance and the (constant) scope.
-- MUST display zh-CN body for proposed summaries (M3 style consistent with fabric-archive / fabric-review).
-- MUST display EN section headings.
-- MUST surface the resolved `pending_path` returned by `fab_extract_knowledge` in the per-entry display block.
-- MUST display the final roll-up with proposed / kept / rejected_dup / merged / contradictions_flagged counts.
-- MUST display the `.fabric/.import-state.json` `phase` value when the skill exits (so the user knows whether re-invocation is required).
-- NEVER hide the source signal; provenance is the only audit trail for bulk-imported entries.
-- NEVER classify a Phase 2 candidate as `personal` automatically — default `team` is contract-locked; only flip layer at the user's explicit instruction (and even then, do it post-import via fabric-review).
-- NEVER show raw `idempotency_key` to the user (internal server-side concern).
-
-### WRITE Rules
-
-- NEVER write a knowledge entry directly via `Edit` / `Write` / `Bash`; the only legal write paths are `mcp__fabric__fab_extract_knowledge` (Phase 2) and `mcp__fabric__fab_review` (Phase 3).
-- NEVER batch multiple Phase 2 candidates into a single `fab_extract_knowledge` call; one call per candidate.
-- NEVER skip the Phase 1 reference step — even if init-scan landed zero entries, the skill MUST verify `.fabric/agents.meta.json` is present.
-- NEVER call `fab_review action="approve"` from this skill — promotion of pending → canonical is `fabric-review`'s concern, not import's. Imported entries land in `pending/` and wait for normal review flow.
-- NEVER call `git mv` directly — layer flips during Phase 3 dedup go through `fab_review action="modify"` with `changes.layer`, which is a server-side transaction.
-- NEVER infer a layer-flip target without explicit user instruction — fabric-import defaults `team`; if the user later wants `personal` for an entry, that's a `fabric-review` modify call, not an import-time decision.
-- NEVER overwrite `.fabric/.import-state.json` non-atomically — use `atomicWriteJson` (write-temp-then-rename).
-- NEVER exceed the 10-entry-per-run hard cap without explicit user override.
-- NEVER pass `relevance_scope = "narrow"` to `fab_extract_knowledge` — every call from this skill MUST use `relevance_scope: "broad"`. No heuristic, no Agent judgment, no per-candidate override (see "Mandatory Scope Rule" in Phase 2).
-- NEVER populate `relevance_paths` with a non-empty array on import — every call from this skill MUST pass `relevance_paths: []`. Do not derive paths from `git log --name-only`, `git show --stat`, commit subjects/bodies, or the path of a mined Markdown file.
-- NEVER copy fabric-archive's Phase 1.5 scope-decision logic (narrow-vs-broad rules, public-prefix generalization, glob blacklist) into this skill — that logic requires a live `edit_paths` signal from an active session, which fabric-import does not have.
-- Narrowing of imported entries happens out-of-band through `fab_review action="modify"` (issued by user via `fabric-review`), NOT inside this skill.
-- MUST preserve protected tokens exactly: `stable_id`, `pending_path`, `layer`, `team`, `personal`, `knowledge_proposed`, `fab_extract_knowledge`, `fab_review`, `MUST`, `NEVER`, `phase`, `.import-state.json`, `relevance_scope`, `relevance_paths`, `broad`, `narrow`.
+Protected tokens (verbatim, no translate): `stable_id`, `pending_path`, `layer`, `team`, `personal`, `knowledge_proposed`, `fab_extract_knowledge`, `fab_review`, `MUST`, `NEVER`, `phase`, `.import-state.json`, `relevance_scope`, `relevance_paths`, `broad`, `narrow`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`.
 
 ## Output Contract
 
-After Phase 3 completes (or on any phase exit due to cap / error / interrupt), the skill MUST produce a roll-up:
-
-```md
-# Import Summary — phase=<P1-done | P2-done | complete>
-
-## Phase 2 — Mining
-- Commits scanned: <N>     (skipped: <S> — cosmetic/metadata/baseline-overlap)
-- Docs scanned:    <D>     (skipped: <DS> — README/CHANGELOG/boilerplate)
-- Pending proposed: <P>     (cap_reached: <true|false>)
-- Scope: all <P> proposed entries use relevance_scope=broad, relevance_paths=[] (fabric-import contract).
-
-## Phase 3 — Dedup
-- Kept (genuinely new):       <K>
-- Rejected (duplicate):       <RD>
-- Modified-then-rejected:     <MR>     (canonical entries enriched: <list of stable_ids>)
-- Contradictions flagged:     <C>     (require manual fabric-review)
-
-## State
-- .fabric/.import-state.json phase: <phase>
-- last_checkpoint_at: <ISO8601>
-- Re-invoke to continue if phase != complete.
-
-## Next Steps
-- Run `fabric-review` to approve the <K> kept pending entries.
-- Resolve <C> contradictions manually if any.
-- If any kept entry is actually narrow-scoped, narrow it via `fab_review action="modify"` with `changes.relevance_scope="narrow"` + `changes.relevance_paths=[...]` (this skill cannot narrow — see Mandatory Scope Rule in Phase 2).
-```
-
-Also surface a one-line `git status` of `.fabric/knowledge/` so the user sees the new pending files appear (and any canonical files modified by dedup-merge).
+Roll-up sections (per `fabric_language`): `Phase 2 — Mining` | `Phase 3 — Dedup` | `State` | `Next Steps`. Plus one-line `git status .fabric/knowledge/`. Bilingual templates → `Read .../ref/output-contract.md`.
 
 ## Worked Examples
 
-### 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: "new-dependency-or-pattern",            // T6: import default
-  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_session: "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.
+4 end-to-end (A feat→pitfall + WRONG counter-ex; B docs→decision; C P3 dup→reject; D out-of-band narrow) → `Read .../ref/worked-examples.md`.
 
 ## Failure Recovery
 
-- **Phase 2 mid-run failure** (e.g. `fab_extract_knowledge` errors on commit 5 of 10): state already records commits 1–4; rerun resumes at commit 5 by skipping any sha in `p2_processed_commits[]`. Error appended to `errors[]`.
-- **Phase 3 mid-run failure** (e.g. `fab_review action="search"` MCP timeout on dedup pair 3 of 7): state records pairs 1–2 in `p3_dedup_completed[]`; rerun resumes at pair 3.
-- **Cumulative `errors[].length > 5`**: skill halts; asks free-text "继续 (y) / 中止并保留 state (n)".
-- **State file corruption**: skill renames it to `.fabric/.import-state.json.corrupt-<ISO8601>` and starts fresh from Phase 1.
-- **MCP tool unreachable**: skill halts before any work; surfaces "MCP 工具未注册；请检查 fabric server 是否运行" and exits without writing state.
+- P2 mid-fail: state has `p2_processed_commits[]`; rerun skips them.
+- P3 mid-fail: state has `p3_dedup_completed[]`; rerun resumes.
+- `errors.length > 5`: halt + ask `继续 (y) / 中止并保留 state (n)` / `Continue (y) / Abort and keep state (n)`.
+- State corruption: P0 detects → rename `.json.corrupt-<ISO>` → restart P1.
+- MCP unreachable: halt + `MCP 工具未注册；请检查 fabric server 是否运行` / `MCP tool not registered; please check that the fabric server is running` → exit without state write.
 
-The skill is `Check-not-Ask` for recovery: it inspects state and resumes deterministically; it does NOT ask the user where to resume from.
+Resume policy: inspect existing state and continue from the last completed phase — do not prompt the user mid-flow.