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

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

@@ -0,0 +1,56 @@
+# Cite-contract + 裁决阶梯参考 (v2.2 SK5)
+
+> 本文是 cite policy 与裁决(adjudication)的**权威详参**,从 bootstrap (`.fabric/AGENTS.md`) 下沉至此,避免 bootstrap 随治理细节膨胀。bootstrap 只留**可执行 core**(cite 行格式 + 验证义务 + operator 例),完整 enum 词典 / 类型路由 / 稽核 / backward-compat / 裁决阶梯看这里。`fabric doctor --cite-coverage` 的稽核口径以本文为准。
+
+## 1. Cite 行格式 (回顾)
+
+edit / decide / propose plan 之前,**回复首行**:
+
+```
+KB: <id> (<≤8字 用法>) [applied|dismissed:<reason>]
+KB: none [<reason>]
+```
+
+- `[applied]` 前必须先 `fab_recall`(或 `fab_plan_context` → `fab_get_knowledge_sections`)实际抓 KB body —— 防编造 id。验证不通过 = 不能 cite。
+- **store 前缀** (多 store):read-set 含多 store 且同一 local id 跨 store shadow 时,cite 必须 store-qualified:`KB: <store-alias>:<id> ...`(如 `KB: team:KT-DEC-0001 (auth) [applied]`)。单 store / 无歧义时裸 `KB: <id>` 仍 valid。personal-only 条目 cite 进团队产物 = 强 warning(防泄漏 R5#3)。
+
+## 2. Contract 语法 (decisions/pitfalls 类 `[applied]`)
+
+cite 尾段加 contract:`→ <operator> [<operator> ...]`
+
+| operator | 含义 |
+|---|---|
+| `edit:<glob>` | 本 cite 承诺会改的文件范围 |
+| `!edit:<glob>` | 承诺**不**改的范围 |
+| `require:<symbol>` | 实现必须含某 symbol |
+| `forbid:<symbol>` | 实现必须不含某 symbol |
+| `skip:<reason>` | 本条 applied 但某 operator 跳过,附理由 |
+
+例:`KB: K-001 (auth) [applied] → edit:src/auth/**/*.ts !edit:src/legacy/**`
+
+## 3. 枚举词典
+
+- **skip reason**:`sequencing | conditional | semantic | aesthetic | architectural | other:<text>`
+- **dismissed reason**:`scope-mismatch | outdated | not-applicable | other:<text>`
+- **`KB: none` sentinel**:`[no-relevant]`(已调 recall/plan_context 但无可用条目) / `[not-applicable]`(当前动作不在 cite 范围:纯探索 / Bash 只读 / 用户问答)。裸 `KB: none` 仍 valid,归 `[unspecified]`(legacy 兼容)。
+
+## 4. 类型路由
+
+- `models` 类引用 = reference cite,**不需 contract**。
+- `guidelines` / `processes` 类暂不强制 contract,推后 LLM-judge。
+- `decisions` / `pitfalls` 类 `[applied]` **需** contract。
+
+## 5. 稽核 + Backward compat
+
+- 稽核:`fabric doctor --cite-coverage [--since=7d] [--client=cc|codex|all]` 输出覆盖率,含 `KB: none` sentinel 拆分。不阻断工作,只记录。
+- Backward compat:解析器同时接受老 4-state tags(`planned` / `recalled` / `chained-from <id>`),都映射到 `[applied]` 语义;旧 session cite 仍计入 cite-coverage。
+
+## 6. 裁决阶梯 (adjudication ladder)
+
+执行中遇到**需要拍板**的分歧(plan 选型 / review 取舍 / cross-LLM 不一致),按三级阶梯收口,**只有真正属于 human 的决定才阻塞**:
+
+1. **AI 自决** — 已有清晰证据 + 明确推荐时,直接执行,记 rationale。不为有默认值的选择拆 sub-question。
+2. **多-LLM 评审(含 ≥1 零上下文冷评)** — 主观 / 高风险 / 跨 LLM 分歧时,maestro delegate ≥2 LLM(至少一个零上下文,防执行者自我合理化)。一致 PASS 自动闭;一致 BLOCK + fix verbatim 采纳重跑。
+3. **非阻塞队列** — 仍分歧 / 主观 / 不可逆 / 属 frame 级(只有 human 能挑战 frame)→ 升 `needs_adjudication` 非阻塞队列,带两方理由 + AI 倾向裁决,继续推进不卡死。
+
+**Anchor**:critic 只能 frame 内审计;多-LLM 收敛 ≠ 正确,frame 级判断留给 human。cross-LLM 给 suggested fix 时直接 verbatim 采纳(+ trade-off 注释)。

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

@@ -0,0 +1,44 @@
+---
+name: fabric-store
+description: 知识 store 运维门面 — 创建 / 挂载 / 绑定 / 列出 / 切换写目标。CLI `fabric store …` 做事，本 skill 按用户意图选命令。NOT for git-managing 用户自己的产品仓。Triggers 创建 store/挂载 store/绑定知识库/store 列表/切换写库/set up knowledge store.
+---
+
+# fabric-store — 知识 store 运维
+
+每个「知识 store」操作的对话入口。CLI (`fabric store …`) 是引擎；本 skill 按用户意图挑命令。*store* 是 `~/.fabric/stores/<uuid>/` 下的平行 git 仓 —— 与用户的产品仓不同。同步 (pull+push) 见姊妹 skill `fabric-sync`。
+
+## When to use
+
+- 「创建团队 store」「建个人知识 store」
+- 「挂载团队 store」「这个项目要绑团队 store」
+- 「列出挂了哪些 store?」「我的共享决策写到哪个 store?」
+
+## When NOT to use
+
+- git 同步用户自己的产品仓 (那是普通 `git`)。
+- 同步知识 store (pull/push 冲突解决) → 用 `fabric-sync` skill。
+- 写知识条目 → 用 `fabric-archive` / `fabric-review`。
+
+## 意图 → 命令映射
+
+| 意图 | 命令 |
+|---|---|
+| 创建全新本地 store | `fabric store create --alias <a> [--remote <url>]` |
+| 挂载已存在的磁盘 store | `fabric store add --uuid <u> --alias <a> [--remote <url>]` |
+| 本项目声明需要某 store | `fabric store bind <alias-or-uuid>` |
+| 列出挂载的 store | `fabric store list` |
+| 设置非 personal scope 的写目标 | `fabric store switch-write <alias>` |
+| 解释某 alias 如何解析 | `fabric store explain <alias>` |
+| 同步 (pull+push) | 见 `fabric-sync` skill |
+
+## Precondition
+
+已 `fabric install --global` (存在 `~/.fabric` + 全局 store registry)。无全局配置 → 提示先 `fabric install --global`，停止。
+
+## Constraints
+
+- `store remove` 是 *detach ≠ delete*：从 registry 卸载但 MUST 保留磁盘 git 树。
+- `store add` MUST 拒绝磁盘无 store 树的 uuid (无「幽灵挂载」) —— 先 clone (`fabric install --global --url <remote>`) 或 `store create`。
+- 知识条目写在各 store 的 `.fabric/knowledge/` 下；本 skill 只管 store 生命周期,不写条目。
+- Personal-scope 写永远落在隐式 personal store，与 active write store 无关。
+- Hook/skill NEVER 直接解析 store 或执行 store 内文件 (S65 RCE 防线：store 是数据-only)；所有 store 状态 MUST 经 CLI JSON 输出获取。

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

@@ -0,0 +1,46 @@
+---
+name: fabric-sync
+description: 多 store git 同步辅助 — 遍历挂载的知识 store, pull --rebase + push, AI 辅助解冲突。Triggers 同步知识库/sync stores/fabric-sync/解决 store 冲突/rebase 冲突.
+---
+
+# fabric-sync
+
+跨多个挂载知识 store 的 git 同步辅助 (v2.1, S46)。CLI `fabric sync` 是事务/状态机引擎；本 skill 是它的 AI 辅助外层：遍历 store、解释每个 store 的同步结果、在 rebase 冲突时辅助用户决断 continue/abort。
+
+## Precondition
+
+- 已 `fabric install --global` (存在 `~/.fabric` + 全局 store registry)。无全局配置 → 提示先装，停止。
+- 本 skill 不直接读 `~/.fabric` store 树；所有 store 状态经 `fabric sync` / `fabric store list` / `fabric scope-explain` 的 JSON 输出获取 (hook/skill 不自解析 store)。
+
+## Phase 0 — Enumerate stores
+
+`fabric store list` 拿到挂载的 store (alias / uuid / remote)。仅 remote-backed store 参与同步；local-only store 跳过 (无可推/拉)，但提示「local-only — 加 remote 备份」(R5#5)。
+
+## Phase 1 — Run sync
+
+执行 `fabric sync`。逐 store 渲染结果 (NOT 聚合成一坨)：
+- `synced` — 干净 rebase + push 完成。
+- `offline` — 网络不可达；本地已提交，push 已 defer (S17 offline-first)，下次 online 重试。**不报错**。
+- `conflict` — rebase 冲突，sync 暂停并持久化 session。进入 Phase 2。
+
+## Phase 2 — AI-assisted conflict resolution (仅冲突时)
+
+冲突 store 的工作区停在 rebase 中途。辅助用户：
+1. 展示冲突文件 (store 知识树 `.fabric/knowledge/<type>/*.md` 中的 `<<<<<<<`/`=======`/`>>>>>>>` 段)。
+2. 对每个冲突，MUST 解释两侧 (ours = 本地草稿/晋升, theirs = 远端协作者) 并给出**合并建议**（知识条目通常可并存或取更成熟 maturity）。NEVER 擅自丢弃任一侧未经用户确认。
+3. 用户解决后 → `fabric sync --continue` (git rebase --continue + 恢复遍历剩余 store)。
+4. 用户选择放弃该 store → `fabric sync --abort` (git rebase --abort，该 store 留未同步，继续遍历其余)。
+
+## Phase 3 — Settle
+
+所有 store settled (无 pending/conflict) 后：CLI 自动清 session 并重生 `~/.fabric/state/bindings/<id>_resolved.json` 快照 (P3→P4 链)。汇报：已同步 store 数、deferred (offline) store 数、aborted store 数。
+
+## UX i18n Policy
+
+按 `.fabric/fabric-config.json` 的 `fabric_language` 渲染用户可见文案。Protected tokens (`fabric sync`, `--continue`, `--abort`, `git rebase`, store alias, enum) NEVER translate。
+
+## Constraints
+
+- Hook/skill **绝不**直接解析 store 或执行 store 内任何文件 (S65 RCE 防线：store 是数据-only)。
+- 冲突合并建议是辅助，最终由用户拍板；不静默丢弃知识。
+- promotion/CR 经普通 git commit，不跨 store 搬运条目。