@fenglimg/fabric-cli 2.0.0-rc.27 → 2.0.0-rc.28

package/templates/skills/fabric-archive/ref/e5-cron-recap.md

@@ -0,0 +1,58 @@
+# E5 Scheduled Daily Recap — full reference
+
+> **Loaded on demand.** Only relevant when invocation context = `cron` / `/loop` (E5 entry). SKILL.md's Phase -0.5 already gates this — if the user just typed `/fabric-archive`, none of the below applies.
+
+## E5 周期触发 (Scheduled Daily Recap)
+
+## Overview
+
+`今日复盘` = E5 entry point. Default scope = today. Falls back to historical scan if today yields no candidates (silent-skip per Phase 2.5).
+
+E5 是 5 入口模型中唯一由 OS 调度器或 Claude Code `/loop` 周期触发的入口形态。fab 端**零代码**——不提供 `fab schedule` 子命令,亦不内嵌 daemon。用户基于自己的执行环境二选一接入: `/loop`(Claude Code 原生,推荐) 或 OS cron(跨平台 fallback)。
+
+### /loop sample (primary path for Claude Code)
+
+```
+/loop /fabric-archive 今日复盘 --cron "0 23 * * *"
+```
+
+每晚 23:00 在当前 Claude Code session 中触发 fabric-archive skill,scope = today。`/loop` 复用现有 Claude session 鉴权,无需独立 token。
+
+### OS cron sample (cross-platform alternative)
+
+```
+# crontab -e
+0 23 * * * cd /path/to/project && claude code -p "/fabric-archive 今日复盘" 2>&1 >> /var/log/fabric-daily-recap.log
+```
+
+适用于:
+- 非 Claude Code 环境(纯 server / CI 节点)
+- 希望脱离 /loop session 生命周期独立运行的场景
+- 已有 cron / launchd 调度基础设施的团队
+
+macOS 用户可改用 `launchd` plist;Linux 用户直接 `crontab -e`。命令需自行确保 `claude code` CLI 已安装且鉴权可用。
+
+### E5 prompt parse contract
+
+当用户或 cron 以 `今日复盘` / `daily recap` 字面短语触发 fabric-archive 时,skill 应按以下契约处理:
+
+- **Phase -0.5 Range Resolution**: 识别 `今日复盘` / `daily recap` 为 magic phrase, 直接设置 `time_window = today` (00:00 local timezone → current ts), 无需 AskUserQuestion 兜底。
+- **Phase 0.4 Onboard Coverage**: 跳过 (entry_point = E5_cron, 非 E2_explicit, 不弹 onboard 弹问)。
+- **Phase 2.5 Persist Archive Attempt**: 始终写入 `session_archive_attempted` event。当今日无 archive 信号触发 viability gate FAIL 时,走 silent-skip 路径(outcome = `skipped_no_signal`),skill 静默退出,cron 日志为空。
+
+### Trade-off table (/loop vs OS cron)
+
+| 维度 | /loop | OS cron |
+|---|---|---|
+| 鉴权 | 复用 Claude session | 独立 token / login |
+| 跨平台 | Claude Code 全平台一致 | macOS launchd / Linux cron 不同 |
+| Token 成本 | 累积 (长 session) | 每 tick fresh, 无累积 |
+| 调试 | Claude UI 可见 | 日志文件 |
+
+### Failure modes
+
+- **/loop session crash**: 归档暂停,用户需重启 `/loop`。无自动恢复机制——`/loop` 与 Claude Code session 生命周期绑定。
+- **OS cron**: 自带恢复(下一个 tick 重新启动),但需独立 `claude code` CLI 安装与鉴权;鉴权 token 过期时 cron job 会静默失败,需人工 `claude login` 重置。
+
+### NOT in scope
+

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

@@ -0,0 +1,80 @@
+# UX i18n Policy — full reference
+
+> **Loaded on demand.** Only consult when rendering bilingual output AND you're unsure which class a string belongs to. SKILL.md gives the operative rule: read `.fabric/fabric-config.json` → `fabric_language`, emit prose in resolved variant, never translate protected tokens. The 5-class taxonomy below disambiguates edge cases.
+
+## UX i18n Policy (5-class bilingualization)
+
+The skill consults `fabric_language` from `.fabric/fabric-config.json`
+(固化于 init 时，via `lib/detect-language.ts:detectExistingLanguage`; default `"en"` when no
+CJK signal is detected in README + docs/; may resolve to `"match-existing"`,
+`"zh-CN"`, `"en"`, or `"zh-CN-hybrid"`). All user-facing text in the
+following 5 categories MUST be rendered in the resolved language:
+
+1. **Roll-up templates** — the `# Archive Review — N candidates` batch
+   review block (one per candidate) AND any final session summary the
+   skill emits after Phase 2 completes. zh-CN ↔ en mirror.
+2. **Errors / Preconditions warnings** — abort + gate-fail messages (e.g.
+   the "没有触发归档信号…" trigger-miss and the "本次会话为常规执行…"
+   viability-gate-FAIL message). zh-CN ↔ en mirror.
+3. **Confirmation prompts** — the per-candidate `Confirm? (Y to accept,
+   edit … inline, N to skip)` line in the batch review template. zh-CN
+   ↔ en mirror.
+4. **Dry-run table headers** — v2.0.0-rc.27 TASK-007 added a dry-run
+   override path (see Phase 2.5 "dry-run") so users can preview the
+   archive proposal without writing pending entries. The dry-run summary
+   header and per-candidate preview labels MUST be bilingualized per
+   this policy. zh-CN ↔ en mirror.
+5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
+   zh-CN ↔ en mirror. fabric-archive itself does not surface
+   AskUserQuestion in the current contract (Phase 1 batch review is a
+   single markdown screen, not a structured question), but if a future
+   version adds one — e.g. to confirm layer flip — this rule applies.
+
+Rendering rule:
+
+- `fabric_language === "zh-CN"` → emit the zh-CN variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "en"` → emit the en variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_get_knowledge_sections`), CLI command names (e.g. `fab 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`,
+`relevance_paths`, `narrow`, `broad`, `source_sessions`, `proposed_reason`,
+`session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`,
+`pending_path`, `layer`, `team`, `personal`,
+`knowledge_scope_degraded`, `MUST`, `NEVER`, `.fabric/knowledge/`, the verbatim
+`强 team` / `强 personal` / `默认 team` heuristic block, etc.) are NEVER
+translated — they appear verbatim in both language variants. The
+bilingualization scope is prose ONLY.
+
+### AskUserQuestion i18n Policy (value vs label)
+
+When a skill (this one or any sibling skill the user is composing with)
+issues an `AskUserQuestion`, the `header` and `question` strings are
+user-facing prose → translated per `fabric_language`. The `options[]`
+array entries (e.g. `["approve", "reject", "modify", "defer", "skip"]` in
+fabric-review, or `["team", "personal"]` for a layer-flip target) are
+**routing keys** consumed by the skill state machine — they MUST remain
+English regardless of `fabric_language`.
+
+```ts
+// EN (fabric_language === "en")
+AskUserQuestion({
+  header: "Layer-flip target",
+  question: "Move '{title}' to which layer? (current: {current_layer})",
+  options: ["team", "personal"]
+})
+
+// zh-CN (fabric_language === "zh-CN")
+AskUserQuestion({
+  header: "Layer 切换目标",
+  question: "将 '{title}' 切换到哪一层？(当前: {current_layer})",
+  options: ["team", "personal"]   // 不翻译 — routing key
+})
+```
+
+Rationale: localizing routing keys would force every routing branch to
+dual-string match (e.g. `if (choice === "team" || choice === "团队")`),
+which doubles the surface area for protected-token regressions and breaks
+the option-list invariants that downstream tooling depends on. Keeping
+`options[]` English-only is contract-locked across all three skills.
+

package/templates/skills/fabric-archive/ref/phase-0-4-onboard.md

@@ -0,0 +1,218 @@
+# Phase 0.4 — First-run Onboard Phase (ref)
+
+> **Loaded on demand.** SKILL.md hot path only runs this when entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND `fab onboard-coverage --json` reports `missing.length > 0`. For E1/E3/E5 entries OR fully-covered workspaces, this entire phase is skipped — no reason to load.
+
+## Phase 0.4 — First-run Onboard Phase
+
+#### Phase 0.4 Trigger Gate (rc.25 — entry-context aware)
+
+Before running ANY of the onboard coverage steps below, evaluate the
+**entry-context gate**. Onboard slot collection is an interactive,
+one-time project-tone capture flow that REQUIRES live user dialogue.
+Non-user-active entries (hook / AI self-trigger / cron) either interrupt
+the user mid-work or run unattended where dialogue is impossible, so
+they MUST skip Phase 0.4 entirely and fall through to Phase 0.
+
+Read `context.entry_point` — already determined in **Phase -0.5 Range
+Resolution** (see TASK-04 / Phase -0.5 section above). The 5-entry model
+is the canonical taxonomy for this gate.
+
+##### Entry-context detection rules
+
+| Entry | Symbol | Detection rule (LLM-native, evaluated at skill entry) |
+|-------|--------|-------------------------------------------------------|
+| **E1** | `hook_passive` | stdout JSON `{decision:'block', ...}` from `archive-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`; `<X>` is one of the 4 self-trigger signals from AGENTS.md E3 section: `Normative` / `Wrong-turn-and-revert` / `Decision confirmation` / `Explicit dismissal`). |
+| **E4** | `user_range_rollback` | Prompt contains a **range hint** (parsed in Phase -0.5 — 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). |
+
+##### Gate decision
+
+```
+IF context.entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback}:
+    → gate = PROCEED       # user is live, dialogue is possible
+    → continue to Step 1 (Check coverage) below
+ELSE (E1_hook_passive | E3_ai_self_trigger | E5_cron):
+    → gate = SKIP           # no live user, onboard prompting would misfire
+    → emit one-line log: "Phase 0.4 skipped (entry=<E1|E3|E5>, no live user)"
+    → proceed directly to Phase 0
+```
+
+##### Rationale
+
+Onboard slot collection is a one-time project-tone capture flow that
+requires user dialogue. Non-user-active entries (hook / AI / cron)
+interrupt the user mid-work or run unattended where dialogue is
+impossible, so they MUST skip Phase 0.4. The S5 slot semantics
+(`tech-stack-decision`, `architecture-pattern`, ...) are user-validated
+baselines — populating them from a hook fire-and-forget or a cron daily
+recap would defeat the purpose of capturing _user-confirmed_ project
+tone.
+
+##### Tradeoff (documented in CHANGELOG)
+
+A first-time user whose ONLY invocations ever come via hook (never an
+explicit `/fabric-archive`) will not see the onboard prompt; the 5
+onboard slots remain empty. Mitigation: documentation tells users to
+run an explicit `fab archive` at least once to populate the onboard
+baseline.
+
+##### Worked example
+
+```
+$ /loop 24h /fabric-archive 今日复盘
+  → cron context, no live user
+  → Phase -0.5 detects literal "今日复盘" + no-human marker
+  → context.entry_point = E5_cron
+  → Phase 0.4 Trigger Gate evaluates: E5 ∉ {E2, E4} → SKIP
+  → emit log "Phase 0.4 skipped (entry=E5, no live user)"
+  → proceed directly to Phase 0 (collect candidates for daily window)
+```
+
+Contrast with E2:
+
+```
+$ /fabric-archive
+  → user typed explicit invocation
+  → Phase -0.5: context.entry_point = E2_explicit_user_invoke
+  → Phase 0.4 Trigger Gate evaluates: E2 ∈ {E2, E4} → PROCEED
+  → run Step 1 (Check coverage) below
+```
+
+---
+
+After F8a removed the auto-`fab scan` baseline pipeline, a freshly installed
+Fabric workspace ships with an EMPTY `.fabric/knowledge/` tree. Five fixed
+**S5 onboard slots** capture the "project tone" baseline that the AI needs
+for high-quality plan_context retrieval from day one:
+
+- `tech-stack-decision` — primary languages / frameworks / runtime stack
+- `architecture-pattern` — module layout, service boundaries, layering rules
+- `code-style-tone` — naming / formatting / idiom conventions the project enforces
+- `build-system-idiom` — build tool quirks, scripts, deploy pipeline shape
+- `domain-vocabulary` — business / product terminology that names code entities
+
+This phase runs ONCE per archive-skill invocation, BEFORE Phase 0 evidence
+gathering, so coverage state is fresh for the session.
+
+#### Step 1 — Check coverage
+
+Invoke `fab onboard-coverage --json` and parse the JSON payload:
+
+```bash
+fab onboard-coverage --json
+```
+
+Expected shape:
+
+```json
+{
+  "filled":    { "tech-stack-decision": ["KT-DEC-0012"], ... },
+  "missing":   ["architecture-pattern", "code-style-tone"],
+  "opted_out": ["domain-vocabulary"],
+  "total": 5
+}
+```
+
+#### Step 2 — Decide
+
+```
+IF missing.length === 0:
+    → skip Phase 0.4 entirely; proceed to Phase 0.
+ELSE:
+    → ask the user how to handle the missing slots (Step 3).
+```
+
+#### Step 3 — Prompt user
+
+Present a single roll-up listing each missing slot. UX i18n Policy class 5
+applies: the `header` + `question` strings are translated per
+`fabric_language`; the `options[]` routing keys stay English.
+
+```ts
+AskUserQuestion({
+  header: "Onboard coverage",  // zh-CN: "首装基调覆盖"
+  question:
+    "KB is missing the following project-tone slots: " +
+    missing.join(", ") +
+    ". Tour the project and propose pending entries for each?",
+  options: ["fill-all", "fill-each", "dismiss-all", "skip"]
+})
+```
+
+`fab_extract_knowledge` is called with `onboard_slot: <slot>` set so each
+proposed entry counts toward coverage once approved via fab_review.
+
+| User choice    | Action |
+|----------------|--------|
+| `fill-all`     | For EACH slot in `missing`, run Step 4 (Tour-and-propose). All proposals share session_id; one batch review at the end (Phase 1). |
+| `fill-each`    | Loop slot-by-slot through `missing`. Per slot: ask user `confirm | dismiss | skip` (per-slot AskUserQuestion); `confirm` → run Step 4; `dismiss` → `fab config dismiss-slot <slot>`; `skip` → leave for next archive run. |
+| `dismiss-all`  | For EACH slot in `missing`, invoke `Bash("fab config dismiss-slot <slot>")`. Print a one-line confirmation each. Skip to Phase 0. |
+| `skip`         | No-op. Slots remain in `missing` for the next archive run. Skip to Phase 0. |
+
+#### Step 4 — Tour-and-propose (per-slot)
+
+For each slot to fill, the LLM independently sources slot-specific evidence
+from the project (no user prompt — this is a Read-only tour):
+
+| Slot                     | Source files (LLM should Read these) |
+|--------------------------|---------------------------------------|
+| `tech-stack-decision`    | `package.json` (+ lockfile), `pyproject.toml` / `Cargo.toml` / `go.mod`, `tsconfig.json`, root README |
+| `architecture-pattern`   | Top-level dir tree (`ls -F`), 1-2 entry-point files (`src/index.ts`, `main.go`, etc.), framework-config files (`next.config`, `vite.config`, `astro.config`) |
+| `code-style-tone`        | `.editorconfig`, `prettier.config.*`, `eslint.config.*`, `biome.*`, `.prettierrc*`, framework lint config, 2-3 representative source files for naming-pattern inference |
+| `build-system-idiom`     | `package.json` `scripts` block, `Makefile`, `taskfile.yaml`, CI yml (`.github/workflows/*.yml`), Dockerfile if present |
+| `domain-vocabulary`      | README, `docs/*.md`, top-level `src/` directory names (often domain-aligned), public API entry types |
+
+After Read-ing the slot-specific sources, classify the observation:
+
+- `tech-stack-decision` → type=`decisions`, `proposed_reason=decision-confirmation`
+- `architecture-pattern` → type=`models`, `proposed_reason=new-dependency-or-pattern`
+- `code-style-tone` → type=`guidelines`, `proposed_reason=explicit-user-mark` (the project ITSELF is the mark)
+- `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:
+<slot>`. The pending file's frontmatter will carry the slot label, and the
+next `fab onboard-coverage` run will see the slot as filled (once approved
+via fab_review).
+
+Example:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  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.",
+  type: "decisions",
+  slug: "primary-tech-stack",
+  layer: "team",
+  relevance_scope: "broad",        // tech stack applies everywhere
+  relevance_paths: [],
+  proposed_reason: "decision-confirmation",
+  session_context:
+    "Session goal: capture onboard tech-stack baseline.\nTurning point: read package.json + tsconfig.json + pnpm-workspace.yaml; stack confirmed.",
+  onboard_slot: "tech-stack-decision",    // ← claims the slot
+  tech_stack: ["typescript", "nodejs", "pnpm", "vitest"]
+})
+```
+
+#### Onboard phase constraints (DO NOT TRANSLATE)
+
+- MUST run BEFORE Phase 0 evidence gathering — onboard is a separate flow,
+  not interleaved with session-archive candidates.
+- MUST call `fab onboard-coverage --json` before deciding; never assume
+  coverage state.
+- NEVER fill a slot that is in `opted_out` — `fab onboard-coverage` already
+  excludes those from `missing`, but the Skill MUST NOT re-propose them
+  even if the user asks "fill all of them" — the dismiss is intentional.
+- NEVER prompt the user when `missing.length === 0` — silent skip.
+- NEVER set `onboard_slot` on a regular session-archive candidate in
+  Phase 2 — that field is RESERVED for the onboard phase. Mixing the
+  two would let session-archive proposals masquerade as onboard
+  coverage and let any random pending file claim a slot.
+- 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.
+

package/templates/skills/fabric-archive/ref/rc-history.md

@@ -0,0 +1,38 @@
+# rc-history — version landmarks for fabric-archive
+
+> **Loaded on demand.** SKILL.md hot path does NOT need this file. It exists so when you encounter an inline comment like `(rc.25 TASK-01)` and wonder "what changed then?", you can `Read` here without polluting routine archive invocations.
+
+## v2.0.0-rc.7 (T5)
+
+Cross-session digest mechanism introduced. Stop hook writes per-session digest to `.fabric/.cache/session-digests/<session_id>.md`. fabric-archive Phase 0.0 reads these to stitch context across sessions since the last `knowledge_proposed` event.
+
+## v2.0.0-rc.20 (TASK-02 / TASK-03)
+
+`assistant_turn_observed` event + cite-policy observability landed. KB-line parsing surfaces `cite_ids` / `cite_tags`. fabric-archive doesn't directly consume — see fabric-hint for the parser.
+
+## v2.0.0-rc.23 (F8c / a-C2)
+
+- **F8c**: Phase 0.4 first-run onboard phase added. S5 slots (`tech-stack-decision`, `architecture-pattern`, `code-style-tone`, `build-system-idiom`, `domain-vocabulary`) baseline the workspace tone for plan_context retrieval.
+- **a-C2**: knowledge_enriched event for description-grade frontmatter back-fill.
+
+## v2.0.0-rc.24 (TASK-01 / TASK-04)
+
+`cite_contract_policy_activated` marker + per-cite `cite_commitments` parallel array. CJS twin of shared cite-line-parser shipped to hooks.
+
+## v2.0.0-rc.25 (TASK-01 / E4 / Q3.3 / Q3.4)
+
+Major fabric-archive overhaul:
+
+- **TASK-01**: `session_archive_attempted` event — drives Phase 0.0 cross-session digest rescan filter (outcome state machine: proposed / viability_failed / user_dismissed / skipped_no_signal).
+- **TASK-05**: 5-entry model (E1 hook / E2 explicit / E3 AI-self / E4 user-range / E5 cron). Phase -0.5 Range Resolution parses time-window + topic-keyword hints into a `session_id[]` scope filter. Anti-loop constants (12h cooldown, normative-keyword scan) landed here.
+- **Q3.4**: outcome-based rescan suppression — `user_dismissed` permanently skips a session.
+
+## v2.0.0-rc.27 (TASK-007 / TASK-011 / TASK-012)
+
+- **TASK-007**: Phase 2.5 dry-run override path (Codex audit §2.25).
+- **TASK-011** (Codex review fix): cite_commitments index-aligned with cite_ids on multi-id parses (audit §2.18 follow-up).
+- **TASK-012** (Codex review fix): dropped stale "no dry-run mode" prose that conflicted with TASK-007.
+
+## v2.0.0-rc.28 (this release)
+
+SKILL.md split into entry (hot path) + `ref/` (this file + i18n-policy + phase-0-4-onboard + worked-examples + e5-cron-recap). 1343 → ~950 lines for the hot path (~29% reduction). Active flow logic unchanged; reference-only content (almost-never-loaded i18n class taxonomy, Phase 0.4 onboard, end-to-end examples, E5 cron setup) moved out.

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

@@ -0,0 +1,78 @@
+# Worked Examples — full reference
+
+> **Loaded on demand.** SKILL.md gives the operative contract (the 5 types + layer heuristic + slug rules + MCP call shape). These end-to-end examples illustrate the integration — load when you want to see all fields filled out together.
+
+## Worked Examples
+
+## Example 1 — decision (team)
+
+Session: User and agent debated whether the Stop-hook should be one .cjs script or three per-client scripts. Settled on one because stdout JSON shape `{"decision":"block","reason"}` is identical across Claude / Codex.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: ["templates/claude-hooks/", "packages/cli/src/commands/hooks.ts"],
+  user_messages_summary: "User pushed back on three-script proposal; agreed single .cjs because stdout JSON shape is universal across Claude Code and Codex CLI.",
+  type: "decisions",
+  slug: "single-cjs-hook-script",
+  layer: "team",
+  relevance_scope: "narrow",
+  relevance_paths: [
+    "templates/claude-hooks/**/*.cjs",
+    "packages/cli/src/commands/hooks.ts"
+  ],
+  proposed_reason: "decision-confirmation",
+  session_context: "Session goal: ship Stop-hook for v2 release.\nTurning point: user rejected 3-script proposal after seeing identical stdout JSON across Claude / Codex.\nResult: single .cjs path locked in."
+})
+```
+
+Layer = team (引用本项目代码 + fabric-import 路径产物 signals). Scope = narrow (tied to hook templates + hooks command module; single-module evidence in edit_paths).
+
+### Example 2 — pitfall (team)
+
+Session: deepMerge silently replaced the existing `hooks.Stop[]` array in `.claude/settings.json` instead of appending. Cost ~30 min to diagnose.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: ["packages/cli/src/config/json.ts"],
+  user_messages_summary: "deepMerge default behavior REPLACES arrays. hooks.Stop[] needs an array-append-with-dedupe special case keyed on .command string match.",
+  type: "pitfalls",
+  slug: "deepmerge-array-replace-trap",
+  layer: "team",
+  relevance_scope: "broad",
+  relevance_paths: [],
+  proposed_reason: "diagnostic-then-fix",
+  session_context: "Session goal: wire hook installer for v2.\nTurning point: spent ~30 min chasing why prior Stop[] entries vanished — root cause was deepMerge replacing arrays silently.\nResult: array-append-with-dedupe special case added."
+})
+```
+
+Layer = team (绑定本项目代码的 pitfall signal). Scope = broad (deepMerge gotcha is cross-cutting — applies anywhere JSON merge is used, not just `json.ts`).
+
+### Example 3 — guideline (personal)
+
+Session: User mentioned across three projects that they prefer 2-space indent in TypeScript and 4-space in Python.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: [".editorconfig"],
+  user_messages_summary: "Personal indent preference: 2-space TS / 4-space Py. Stable across multiple projects, not project-specific.",
+  type: "guidelines",
+  slug: "indent-style-by-language",
+  layer: "personal",
+  relevance_scope: "broad",
+  relevance_paths: [],
+  proposed_reason: "explicit-user-mark",
+  session_context: "Session goal: align editor config.\nTurning point: user said '一直 prefer 2-space TS / 4-space Py，across projects'.\nResult: personal-layer guideline; not bound to this project."
+})
+```
+
+Layer = personal (跨项目通用 + 工具/编辑器偏好 signals dominate; no 强 team signal applies). Scope = broad with `relevance_paths=[]` (personal layer ALWAYS forces broad — paths don't generalize across projects per Phase 1.5 special case).
+

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

@@ -41,58 +41,9 @@ Required preconditions before any MCP call:
 - `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)
 
-### Phase 0 — Init & .tmp Residue Scan
-
-Before reading `.fabric/.import-state.json`, scan for residue left by a
-prior crashed run. Skill state writes use a 2-step atomic pattern (Write
-`.tmp` then `Bash mv`); a crash between Step A and Step B leaves a
-`.fabric/.import-state.json.tmp` sidecar that the next invocation MUST
-triage.
-
-1. Does `.fabric/.import-state.json.tmp` exist? (`Bash: ls .fabric/.import-state.json.tmp 2>/dev/null`)
-   - **Does not exist** → proceed normally to Phase 0.1 (no residue work).
-   - **Exists** → triage:
-     1. `Read` the `.tmp` file; try `JSON.parse` on the content.
-     2. Compare `mtime` of `.tmp` vs `.fabric/.import-state.json` via `Bash: stat`.
-        - **Parse OK + .tmp mtime newer than main file** → rescue:
-          `Bash: mv .fabric/.import-state.json.tmp .fabric/.import-state.json`
-          (commits the last incomplete write atomically).
-        - **Parse OK + .tmp mtime older than main file** → stale residue
-          from an earlier run that subsequently completed; delete it:
-          `Bash: rm .fabric/.import-state.json.tmp`.
-        - **Parse fails** (syntax error / unterminated structure / truncated
-          mid-write) → half-written, unrecoverable; delete it:
-          `Bash: rm .fabric/.import-state.json.tmp`.
-     3. After triage, proceed to Phase 0.1.
-
-The 5-minute mtime heuristic (treat any `.tmp` older than 5 minutes as
-stale regardless of parse result) is an acceptable conservative simplification:
-no legitimate atomic write window stays open that long; anything older
-than 5 minutes is definitely crash residue. Implementations MAY use either
-the mtime-comparison rule above OR the 5-minute staleness rule.
-
-### Phase 0.1 — State Corruption Recovery
-
-After residue triage, `Read` `.fabric/.import-state.json`. Detect
-corruption if ANY of the following hold:
-
-- `JSON.parse` throws (syntax error / unterminated structure / truncated)
-- Missing required field: `phase` OR `started_at` OR `last_checkpoint_at`
-- `phase` value not in the enum `{P1-done, P2-done, complete}`
-
-On corruption (any condition above):
-
-1. `Bash: mv .fabric/.import-state.json .fabric/.import-state.json.corrupt-<ISO8601>`
-   (preserve the corrupt file for postmortem; do NOT silently overwrite).
-2. Phase 1 restarts from scratch (Phase 1 produces no MCP calls, so re-run
-   is safe — re-globbing `.fabric/knowledge/team/**/*.md` is cheap and
-   idempotent; the `p1_baseline_titles` array is regenerated).
-3. DO NOT attempt automatic partial recovery; corrupt state is a signal
-   that something serious happened (disk-full, kill -9 mid-write, fs
-   error). Discard-and-restart is the only safe path.
-
-ENOENT (state file absent) is NOT corruption — it is the normal
-first-run state. Proceed to Phase 0.5.
+### Phase 0 — Init (state-recovery ref-only)
+
+On invocation: read/initialize `.fabric/.import-state.json` (resumable phase tracker — see Checkpoint Logic section below for schema). Scan workspace for stale `.tmp-import-*` residues (`.fabric/.import-state.json.tmp-*`). For details on the .tmp scan + state corruption recovery (rare — only triggers when a prior import crashed mid-phase), `Read packages/cli/templates/skills/fabric-import/ref/state-recovery.md` (or `.claude/skills/fabric-import/ref/state-recovery.md` post-install).
 
 ### Phase 0.5 — Config Load
 
@@ -112,74 +63,13 @@ Whether the run is "first-run" vs "re-run" is decided by inspecting
 `.fabric/.import-state.json`: ENOENT (or any state with `phase != "complete"`
 and `final_summary.proposed == 0`) → first-run window; otherwise re-run window.
 
-### UX i18n Policy (5-class bilingualization)
-
-The skill consults `fabric_language` from `.fabric/fabric-config.json`
-(固化于 install 时，via `scan.ts:detectExistingLanguage`; default `"en"` when no
-CJK signal is detected in README + docs/; may resolve to `"match-existing"`,
-`"zh-CN"`, `"en"`, or `"zh-CN-hybrid"`). All user-facing text in the
-following 5 categories MUST be rendered in the resolved language:
-
-1. **Roll-up templates** — final summary blocks (`# Import Summary — phase=...`,
-   `## Phase 2 — Mining`, `## Phase 3 — Dedup`, etc.). zh-CN ↔ en mirror.
-2. **Errors / Preconditions warnings** — abort + gate-fail messages (e.g.
-   "请先运行 fabric install 完成基线扫描…" / "Please run fabric install first…").
-   zh-CN ↔ en mirror.
-3. **Confirmation prompts** — re-run-within-24h prompt, reset prompts, etc.
-   zh-CN ↔ en mirror.
-4. **Dry-run table headers** — `# Import Dry Run — would propose N pending
-   entries…` + the `| # | Source | Type | Slug | Scope | Summary |` header row.
-   zh-CN ↔ en mirror.
-5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
-   zh-CN ↔ en mirror. fabric-import itself does not surface AskUserQuestion
-   in the current contract (the rare re-run prompt is free-text), but if a
-   future version adds one, this rule applies.
-
-Rendering rule:
-
-- `fabric_language === "zh-CN"` → emit the zh-CN variant; pure monolingual, no language mixing inside a single user-facing block.
-- `fabric_language === "en"` → emit the en variant; pure monolingual, no language mixing inside a single user-facing block.
-- `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_get_knowledge_sections`), CLI command names (e.g. `fab 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`, `fab_review`, `relevance_scope`,
-`relevance_paths`, `broad`, `narrow`, `source_sessions`, `proposed_reason`,
-`session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`,
-`pending_path`, `layer`, `team`, `personal`,
-`knowledge_scope_degraded`, `MUST`, `NEVER`, `.fabric/knowledge/`, etc.)
-are NEVER translated — they appear verbatim in both language variants.
-The bilingualization scope is prose ONLY.
-
-### AskUserQuestion i18n Policy (value vs label)
-
-When a skill (this one or any sibling skill the user is composing with)
-issues an `AskUserQuestion`, the `header` and `question` strings are
-user-facing prose → translated per `fabric_language`. The `options[]`
-array entries (e.g. `["approve", "reject", "modify", "defer", "skip"]` in
-fabric-review) are **routing keys** consumed by the skill state machine —
-they MUST remain English regardless of `fabric_language`.
+### UX i18n Policy
 
-```ts
-// EN (fabric_language === "en")
-AskUserQuestion({
-  header: "Review pending entry",
-  question: "What action for '{title}'?",
-  options: ["approve", "reject", "modify", "defer", "skip"]
-})
+Read `.fabric/fabric-config.json` → `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`). Emit user-facing prose in the resolved variant. Protected tokens (`fab_extract_knowledge`, `fab_review`, `.fabric/.import-state.json`, schema/scope/layer enum values) are NEVER translated.
 
-// zh-CN (fabric_language === "zh-CN")
-AskUserQuestion({
-  header: "审核 pending 条目",
-  question: "对 '{title}' 执行什么操作？",
-  options: ["approve", "reject", "modify", "defer", "skip"]   // 不翻译 — routing key
-})
-```
+`AskUserQuestion` policy: `header` + `question` translate; `options[]` are routing keys — stay English regardless of locale.
 
-Rationale: localizing routing keys would force every routing branch to
-dual-string match (e.g. `if (choice === "approve" || choice === "通过")`),
-which doubles the surface area for protected-token regressions and breaks
-the option-list invariants that downstream tooling depends on. Keeping
-`options[]` English-only is contract-locked across all three skills.
+**For the full 5-class taxonomy + edge cases:** `Read packages/cli/templates/skills/fabric-import/ref/i18n-policy.md` (or `.claude/skills/fabric-import/ref/i18n-policy.md` post-install).
 
 ## 3-Phase Pipeline (P1 reference / P2 mine / P3 dedup)