@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.1

package/templates/hooks/lib/state-store.cjs

@@ -21,7 +21,9 @@
  * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
  */
 
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+// Namespace import (not destructured) so the atomic write goes through a single
+// mutable fs reference — also what the atomicity tests spy on (ISS-016).
+const fs = require("node:fs");
 const { dirname, join } = require("node:path");
 
 const CACHE_DIR_REL = join(".fabric", ".cache");
@@ -30,11 +32,31 @@ function cachePath(projectRoot, fileName) {
   return join(projectRoot, CACHE_DIR_REL, fileName);
 }
 
+// ISS-016: write to a unique temp file then rename over the target. rename is
+// atomic on POSIX, so a reader sees either the old or the new file in full —
+// never a truncated/garbled write from a crash or concurrent writer. The temp
+// suffix (pid + clock) keeps concurrent windows from colliding on the temp.
+function atomicWrite(path, data) {
+  fs.mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, path);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // best-effort temp cleanup
+    }
+    throw err;
+  }
+}
+
 function readJsonState(projectRoot, fileName, validate) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(fs.readFileSync(path, "utf8"));
     if (typeof validate === "function" && !validate(parsed)) return null;
     return parsed;
   } catch {
@@ -43,10 +65,8 @@ function readJsonState(projectRoot, fileName, validate) {
 }
 
 function writeJsonState(projectRoot, fileName, value) {
-  const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(value));
+    atomicWrite(cachePath(projectRoot, fileName), JSON.stringify(value));
     return true;
   } catch {
     return false;
@@ -55,19 +75,17 @@ function writeJsonState(projectRoot, fileName, value) {
 
 function readTextState(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    return readFileSync(path, "utf8").trim();
+    return fs.readFileSync(path, "utf8").trim();
   } catch {
     return null;
   }
 }
 
 function writeTextState(projectRoot, fileName, text) {
-  const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, String(text));
+    atomicWrite(cachePath(projectRoot, fileName), String(text));
     return true;
   } catch {
     return false;
@@ -80,5 +98,6 @@ module.exports = {
   writeJsonState,
   readTextState,
   writeTextState,
+  atomicWrite,
   CACHE_DIR_REL,
 };

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

@@ -0,0 +1,53 @@
+---
+name: fabric-audit
+description: 知识库语义淘汰门面 — 审计 KB 健康并以 deprecate-over-delete + rescue-before-delete 收口陈旧/孤儿/被取代条目。引擎是 `fabric doctor`；本 skill 按用户意图挑动作并守「不硬删、先抢救」红线。Triggers 审计知识库/清理陈旧知识/知识库体检/deprecate 条目/prune stale knowledge/知识库瘦身/淘汰旧决策.
+---
+
+# fabric-audit — 知识库语义淘汰
+
+知识库 *维护期* 的对话入口:体检 KB,把陈旧 / 孤儿 / 被取代的条目按 **语义淘汰** 收口 —— 而不是一删了之。CLI (`fabric doctor`) 是引擎(跑 lint、算 health、给 orphan/stale 信号);本 skill 按用户意图挑动作,并守两条红线:**deprecate-over-delete** 与 **rescue-before-delete**。
+
+写新条目用 `fabric-archive`;批量审 pending 用 `fabric-review`;本 skill 专管 *已归档条目的退役*。
+
+## When to use
+
+- 「审计 / 体检知识库」「知识库健康度怎样?」
+- 「清理陈旧知识」「这些旧决策还要吗?」「知识库瘦身」
+- 发布 / 大重构前想把过时知识收口。
+- doctor 报了 orphan / stale / 低 health,想逐条处置。
+
+## When NOT to use
+
+- 写 / 提议新知识条目 → `fabric-archive`。
+- 批量审 `.fabric/knowledge/pending/` 的 draft → `fabric-review`。
+- store 运维 / 同步 → `fabric-store` / `fabric-sync`。
+
+## 两条红线
+
+1. **deprecate-over-delete**:陈旧 ≠ 该删。一条「当时为什么这么决策」的 decision/pitfall 即使方案已换,其 **rationale 仍是知识**。退役 = 降 maturity / 标记 deprecated(保留正文 + 记录被什么取代),而非 `rm`。删除只用于「从未成立 / 纯噪声 / 重复」的条目。
+2. **rescue-before-delete**:任何 *打算删* 的条目,删前必做抢救检查 —— 它是否携带别处没有的独特 rationale / 反例 / 边界?有则先 **merge 进取代它的条目**(或在新条目加 `related` 边指回),再删空壳。抢救检查没做过,不许删。
+
+## 意图 → 动作映射
+
+| 意图 | 动作 |
+|---|---|
+| 体检 / 健康度 | `fabric doctor`(读 lint + health rollup);零阻断,只报告 |
+| 找孤儿 / 陈旧条目 | `fabric doctor`(消费 orphan / stale / orphan-demote 信号) |
+| 退役一条陈旧条目 | **不删** → 降 maturity(proven→verified→draft)或在 frontmatter 标 deprecated + 记 superseded-by;经 `fabric-review` 落盘 |
+| 删一条「从未成立 / 重复」条目 | 先跑 rescue 检查(独特 rationale?有则 merge/加 related);确认空壳后才删 |
+| 被取代但有价值 | rescue:把独特 rationale merge 进取代条目,新条目加 `related` 边指回,再退役旧条目 |
+
+## 流程(逐条处置)
+
+1. `fabric doctor` 取 KB health + orphan/stale 候选清单(引擎给信号,本 skill 不自算)。
+2. 对每个候选判 **三态**:still-valid(留) / superseded(退役,走 deprecate) / never-valid(删,走 rescue 检查)。
+3. superseded → deprecate:降 maturity 或标 deprecated + `superseded-by`,保留正文 rationale。
+4. never-valid → rescue-before-delete:独特知识?有则 merge + `related`,无则删空壳。
+5. 处置经 `fabric-review` skill 落盘(本 skill 给决策,review 做写入),保持单一写路径。
+
+## Constraints
+
+- 本 skill **只读 + 给处置建议**;实际写入(降级 / 标记 / 删)经 `fabric-review` 的写路径,不自行改 `.fabric/knowledge/`。
+- NEVER 绕过 rescue 检查直接删;删前 MUST 先跑抢救检查。删是最后手段,默认是 deprecate。
+- `agents.meta.json` 派生态严禁手改;退役动作改的是 `.fabric/knowledge/<type>/` 下 markdown 的 frontmatter(maturity / deprecated / superseded-by),再 `fabric doctor --fix` reconcile。
+- health / orphan / stale 一律取自 `fabric doctor` 的 JSON 输出,不在 skill 内重算(单一真源)。

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

@@ -0,0 +1,48 @@
+---
+name: fabric-connect
+description: 知识图谱关联门面 — 发现 KB 条目间隐藏关联并回写 H2 `related` 图边。读 fab_recall/fab_plan_context 看候选, 按语义/共路径/共引提议 related 边, 经 fabric-review 写路径落盘。Triggers 连接知识/找关联条目/建知识图谱/link related entries/补 related 边/知识库连通性.
+---
+
+# fabric-connect — 知识图谱关联
+
+把孤立的 KB 条目连成图:发现彼此**隐藏关联**(同一决策的正反面、pitfall↔规避它的 guideline、被取代↔取代),回写到 frontmatter 的 `related: [<stable_id>...]` 图边(v2.2 H2)。下游 `fab_recall include_related:true` 据此一跳拉回连通知识。
+
+`related` 是**有向引用**(A.related=[B] 表示「读 A 时也该看 B」),按需补反向边(B.related=[A])。
+
+## When to use
+
+- 「把这些知识连起来」「找出相关条目」「补 related 边」
+- 「知识库连通性怎样?」「有哪些孤岛条目?」
+- 新增一批条目后想建立彼此引用。
+
+## When NOT to use
+
+- 写新条目 → `fabric-archive`。
+- 审 pending / 退役陈旧 → `fabric-review` / `fabric-audit`。
+- 检索时临时拉关联 → 直接 `fab_recall include_related:true`(无需建边)。
+
+## 关联类型(提议 related 边的判据)
+
+| 类型 | 例 |
+|---|---|
+| 互补 | decision「用 JWT」 ↔ pitfall「JWT 过期未刷新踩坑」 |
+| 规避 | pitfall「sprite 黑边」 ↔ guideline「premultiplyAlpha 正确设置」 |
+| 取代 | 旧 decision ↔ 取代它的新 decision(配合 deprecated/superseded-by) |
+| 同域 | 同一子系统 / 共 relevance_paths 的条目 |
+| 引用链 | A 的 rationale 依赖 B 的结论 |
+
+## 流程
+
+1. `fab_recall(paths=[...])` 或 `fab_plan_context` 拿候选 + 现有 `related`(读 description.related 看已连状态)。
+2. 对候选两两/成簇判隐藏关联(用上表判据);只提议**高置信**边,不为「话题相邻」乱连(噪声边稀释图价值)。
+3. 每条提议 = `(源 id, 目标 id, 类型, 一句理由)`;按需提议反向边。
+4. 落盘经 `fabric-review` 写路径:在源条目 frontmatter 的 `related` inline 数组追加目标 stable_id;`fabric doctor --fix` reconcile 进 agents.meta。
+5. 回报新增/反向边数 + 连通性变化(孤岛减少)。
+
+## Constraints
+
+- 本 skill **只提议 + 经 review 写路径落盘**;不自行改 `.fabric/knowledge/`,不手改 `agents.meta.json`(派生态)。
+- `related` MUST 只填**真实存在的 stable_id**(先 `fab_recall` 验证目标在库);NEVER 编造 / 指向 pending。
+- **稀疏优于稠密**:宁缺毋滥。只连高置信关联;低置信「相邻」不连(图的信噪比比覆盖率重要)。
+- 反向边按需补,不强制双向(有向语义:A 该带出 B ≠ B 该带出 A)。
+- 写 `related` 复用 H2 字段(`fabric-review` 的 modify 路径);schema 已支持,无需迁移。

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

@@ -44,6 +44,8 @@ Missing or unreadable → defaults silently.
 
 Review iterates **per-store** — the read-set may span multiple stores (`fabric scope-explain team` → resolved `readSet.stores`). Pending/backlog is reported per-store (NOT aggregated into one undifferentiated pile); each candidate's provenance store is surfaced in cites as `KB: <store-alias>:<id>`. Promotion (draft → verified/proven) is a normal edit + git commit **inside that store's own repo** — no cross-store move. A `dismissed`/`modify` that flips layer between team and personal still goes through `AskUserQuestion`. Never read `~/.fabric` store trees directly; go through the MCP recall path / `scope-explain`.
 
+`Read ref/cite-contract.md` (v2.2 SK5) for the authoritative cite-contract reference — operator syntax, skip/dismissed reason dictionaries, type routing, audit semantics, backward-compat, and the adjudication ladder (AI-self → multi-LLM cold-eval → non-blocking queue) — sunk out of the bootstrap so cite/governance depth lives here, not in `.fabric/AGENTS.md`.
+
 ### UX i18n Policy
 
 Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`); emit user-facing prose in resolved variant. Protected tokens (`fab_review`, `fab_extract_knowledge`, `relevance_scope`, layer/scope enums, `stable_id`, the verbatim `强 team` / `强 personal` / `默认 team` block) NEVER translated. `AskUserQuestion` policy: `header` + `question` translate; `options[]` stay English (routing keys).

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 输出获取。