@fenglimg/fabric-cli 2.0.0-rc.33 → 2.0.0-rc.35

package/templates/skills/fabric-review/ref/modify-flow.md

@@ -0,0 +1,95 @@
+# Modify Sub-Flow, Layer-Flip Rules & Narrowing Imported Entries
+
+## Modify Sub-Flow
+
+`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.
+
+## Modify Examples
+
+```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" }
+})
+
+// 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" }
+})
+```
+
+---
+
+## Narrowing Imported Entries
+
+The fabric-import skill creates pending entries with `relevance_scope=broad` + `relevance_paths=[]` as a deliberate contract — it cannot derive paths from git history. **Narrowing imported entries is fabric-review's responsibility.**
+
+### Detection
+
+An entry is "import-origin" when `source_sessions[0]` starts with `fabric-import-` (e.g. `fabric-import-2026-05-10`).
+
+### Pending mode rendering
+
+For each import-origin entry, prepend one warning line to the display block. UX i18n Policy class 1 — roll-up templates; the protected tokens `relevance_scope`, `relevance_paths`, `broad` appear verbatim in BOTH variants:
+
+- en: `⚠ Imported (relevance_scope=broad, relevance_paths=[]) — pick 'modify' + say 'narrow to <paths>' to bind scope.`
+- zh-CN: `⚠ Imported (relevance_scope=broad, relevance_paths=[]) — 选择 'modify' 并指定 'narrow to <paths>' 以收紧作用域。`
+
+This hint is informational. The user MAY ignore it; broad+[] is a valid final state for cross-cutting knowledge.
+
+### Modify follow-up — narrow scope
+
+When the user picks `modify` on an import-origin entry, surface AskUserQuestion with an extended option list. UX i18n Policy class 5 — `header` + `question` translated; `options[]` remain English routing keys:
+
+```ts
+// EN
+AskUserQuestion({
+  header: "Modify imported entry",
+  question: "What aspect of '{title}' to modify?",
+  options: ["narrow scope", "edit summary", "change layer", "change maturity", "skip"]
+})
+
+// zh-CN
+AskUserQuestion({
+  header: "修改 imported 条目",
+  question: "要修改 '{title}' 的哪一项？",
+  options: ["narrow scope", "edit summary", "change layer", "change maturity", "skip"]   // 不翻译
+})
+```
+
+When user picks "narrow scope":
+
+1. Free-text follow-up. UX i18n Policy class 3 — confirmation prompts:
+   - en: `Type relevance_paths (comma-separated globs, e.g. packages/server/src/retry/**, packages/server/src/lib/retry.ts)`
+   - zh-CN: `请输入 relevance_paths (逗号分隔的 glob，例如 packages/server/src/retry/**, packages/server/src/lib/retry.ts)`
+2. Call fab_review action="modify" with:
+   ```ts
+   changes: { relevance_scope: "narrow", relevance_paths: [<parsed paths>] }
+   ```
+3. Display the resolved frontmatter to confirm.
+
+### Special cases
+
+- **Layer=personal entries**: server auto-degrades narrow → broad+[]; surface the `knowledge_scope_degraded` event back to the user.
+- **Non-import-origin entries**: modify can still narrow (just doesn't show this UX nudge — user types it as a normal modify).

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

@@ -0,0 +1,58 @@
+# Output Contract — fabric-review
+
+Bilingual roll-up templates + events.jsonl atomicity constraint referenced from SKILL.md.
+
+## Roll-up Template
+
+After each invocation, the skill MUST produce a brief roll-up to the user. UX i18n Policy class 1 — roll-up templates; render per `fabric_language`. Protected tokens (event-type strings such as `knowledge_promoted` / `knowledge_layer_changed` / `knowledge_rejected` / `knowledge_deferred`, plus `.fabric/events.jsonl`) appear verbatim in BOTH variants:
+
+**en variant** (`fabric_language === "en"`):
+
+```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
+```
+
+**zh-CN variant** (`fabric_language === "zh-CN"`):
+
+```md
+# Review 汇总 — mode={pending|topic|health|revisit}
+- 列出: N 条
+- 已批准: M (新分配 stable_ids: KT-D-12, KT-G-4, KP-P-2)
+- 已驳回: R
+- 已修改: U (含 K 次 layer 切换)
+- 已延后: D
+- 已跳过: S
+
+## 追加事件 (.fabric/events.jsonl 末尾)
+- 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.
+
+## events.jsonl Constraint Note
+
+Event lines appended to `.fabric/events.jsonl` are subject to POSIX single-write atomicity: only writes ≤ 4KB (`PIPE_BUF`) are guaranteed atomic via `Bash: echo "..." >> file`. Lines exceeding 4KB risk interleaved corruption under concurrent skill + server writes to the same ledger.
+
+Skills MUST ensure:
+
+- Each event JSON line is a **single line** (no embedded newlines; escape `\n` in any string value).
+- `session_context` and other free-form text fields **self-truncate** to keep the entire serialized line under 4KB. Suggested per-field caps: `session_context` first 500 chars; `source_sessions` cap at 5 entries; `recent_paths` cap at 20 entries; `user_messages_summary` first 500 chars.
+- If approaching the 4KB ceiling after the per-field caps, drop optional fields (e.g. tags / extra metadata) **before** truncating semantic content (the summary / context that carries the actual observation).
+- The promote / reject / modify / defer events listed above are emitted by the MCP server via `appendEventLedgerEvent` and are already length-bounded server-side; this constraint applies to any event the skill itself appends directly to the ledger (rare, but possible for diagnostic markers).

package/templates/skills/fabric-review/ref/per-mode-flows.md

@@ -0,0 +1,155 @@
+# Per-Mode Flows — fabric-review
+
+Full bilingual rendering blocks + step-by-step procedures for the four modes referenced from SKILL.md.
+
+---
+
+## 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 `ref/semantic-check.md`) 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. UX i18n Policy class 1 — roll-up templates; protected tokens (`pending_path`, `layer`, `team`, `decisions`, `proposed_reason`, `Tags`, etc.) appear verbatim in BOTH variants:
+
+   **en variant** (`fabric_language === "en"`):
+
+   ```md
+   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
+   Title: Single .cjs hook across clients
+   Summary: stdout JSON shape is identical across the three clients; one script suffices.
+   Maturity: draft   Tags: [hook, cli]
+   Proposed reason: decision-confirmation — ≥2 alternatives weighed; rationale stated.
+   Session context: Session goal: ship Stop-hook for v2 release.
+   ⚠ Possible duplicate of KT-D-0007 (LLM subjective dup/subsumption judgement; thresholds intentionally not quantified)
+   ```
+
+   **zh-CN variant** (`fabric_language === "zh-CN"`):
+
+   ```md
+   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
+   标题: 单 .cjs hook 跨客户端
+   摘要: 三客户端 stdout JSON 格式一致，单脚本即可。
+   成熟度: draft   Tags: [hook, cli]
+   Proposed reason: decision-confirmation — ≥2 候选方案经权衡后确认选型。
+   Session context: Session goal: ship Stop-hook for v2 release.
+   ⚠ 可能重复 KT-D-0007 (LLM 主观判断 dup/subsumption；具体阈值不可量化)
+   ```
+
+   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 the legacy fallback (UX i18n Policy class 1):
+
+   - en: `Proposed reason: <legacy entry, no reason recorded>` and `Session context: <not recorded>`
+   - zh-CN: `Proposed reason: <历史条目，未记录 reason>` 与 `Session context: <未记录>`
+
+   …so the reviewer can still proceed.
+
+5. Surface a per-item AskUserQuestion. UX i18n Policy class 5 — `header` + `question` translated; `options[]` array remain English routing keys:
+
+   ```ts
+   // EN
+   AskUserQuestion({
+     header: "Review pending entry",
+     question: "What action for 'Single .cjs hook across clients'?",
+     options: ["approve", "reject", "modify", "defer", "skip"]
+   })
+
+   // zh-CN
+   AskUserQuestion({
+     header: "审核 pending 条目",
+     question: "对 '单 .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 `ref/modify-flow.md`.
+   - `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. See `ref/output-contract.md` for the bilingual rollup template.
+
+---
+
+## 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 `review_topic_result_cap`, config-resolved, default 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 older than `review_stale_pending_days` (config-resolved, default 14) OR maturity=draft entries with no recent evidence-append events.
+4. Render a corpus dashboard. UX i18n Policy class 1 — roll-up templates; render per `fabric_language`:
+
+   **en variant**:
+
+   ```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
+   ```
+
+   **zh-CN variant**:
+
+   ```md
+   ## 健康度总览
+   - Pending: 12 条 (最旧 18 天) — 建议 `defer` 或 `reject`
+   - Drafts: 8 条 (3 条为陈旧候选: KP-G-3, KP-G-5, KT-P-9)
+   - Layer 切换 (30 天): 2
+   - 已驳回 (30 天): 1
+   ```
+
+5. For each stale candidate, surface AskUserQuestion. UX i18n Policy class 5 — `header` + `question` translated; `options[]` remain English routing keys:
+
+   ```ts
+   // EN
+   AskUserQuestion({
+     header: "Stale entry triage",
+     question: "Action for stale entry '{title}'?",
+     options: ["defer", "demote", "skip"]
+   })
+
+   // zh-CN
+   AskUserQuestion({
+     header: "陈旧条目处理",
+     question: "对陈旧条目 '{title}' 执行什么操作？",
+     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).
+
+---
+
+## Mode Inference — Examples & Anti-Pattern (companion to SKILL.md table)
+
+### Inference Examples (Sample User Messages → Expected Mode)
+
+- "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)
+
+### Anti-Pattern (Hard Rule restatement)
+
+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.

package/templates/skills/fabric-review/ref/semantic-check.md

@@ -0,0 +1,26 @@
+# Semantic Check Guidance — fabric-review
+
+LLM-assisted duplicate / contradiction / subsumption detection during `pending` mode (and on demand during `topic` mode).
+
+> 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.
+
+## Procedure
+
+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). 三类判断均为 LLM 主观判断 dup/subsumption；具体阈值不可量化（不使用百分比 / 相似度数值伪精度）：
+   - **Duplicate** — same essential claim. 标题与摘要表达同一核心结论，pending 未提供新证据或新上下文。Flag: `⚠ Possible duplicate of <stable_id>`.
+   - **Contradiction** — opposing claims about the same subject. 例：一个 entry 说 "use X"，pending 说 "avoid X"，且作用域一致。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 `per-mode-flows.md` 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"`).
+
+## What NOT to do
+
+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.