@fenglimg/fabric-cli 2.0.0-rc.34 → 2.0.0-rc.36

package/templates/hooks/lib/summary-fallback.cjs

@@ -0,0 +1,210 @@
+/**
+ * rc.35 TASK-06 (P0-10.b) — summary-fallback library.
+ *
+ * Resolves opaque hint entries (where `entry.summary === entry.id` so the
+ * AI sees no information beyond the id) by reading the entry's markdown
+ * file at `.fabric/knowledge/<type>/<id>--<slug>.md`, extracting the first
+ * paragraph under `## Summary`, and substituting that text into the entry
+ * before the hook renders it.
+ *
+ * Caching: results are stored in `.fabric/.cache/summary-fallback.json`
+ * keyed by the current `revision_hash` returned by plan-context-hint. The
+ * cache is wiped wholesale when the revision changes (cheap invariant —
+ * any meta rev bump implies entry text MAY have moved). Per-process call
+ * also benefits from in-memory dedup since the same opaque id may appear
+ * across narrow + broad paths.
+ *
+ * Design contract:
+ *   - Never throw. ANY failure (cache read, fs scan, file read) degrades
+ *     to a no-op — the original opaque summary is left untouched. Hooks
+ *     must remain best-effort.
+ *   - Idempotent over identical inputs. Two calls in succession with the
+ *     same revision_hash + entries set produce zero disk reads on the
+ *     second call.
+ *
+ * Public API (module.exports):
+ *   resolveOpaqueSummaries(entries, projectRoot, revisionHash) — returns
+ *     a NEW array of entries with `summary` substituted for opaque cases.
+ *     Original `entry.id` is preserved verbatim.
+ *
+ *   _extractFirstSummaryParagraph(md) — pure helper, exposed for testing.
+ *
+ *   _readCache / _writeCache — exposed for testing.
+ */
+
+const { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const CACHE_DIR_REL = ".fabric/.cache";
+const CACHE_FILE_REL = ".fabric/.cache/summary-fallback.json";
+const KNOWLEDGE_DIR_REL = ".fabric/knowledge";
+const SUMMARY_MAX_LEN = 80;
+const KNOWLEDGE_TYPE_DIRS = ["decisions", "pitfalls", "guidelines", "models", "processes"];
+
+function _isOpaque(entry) {
+  if (!entry || typeof entry.id !== "string" || typeof entry.summary !== "string") {
+    return false;
+  }
+  return entry.summary.trim() === entry.id.trim();
+}
+
+/**
+ * Pure helper: extract the first paragraph under a `## Summary` heading.
+ *
+ *   - `## Summary` is case-insensitive but level-sensitive (only H2).
+ *   - First paragraph = lines until blank line or next heading.
+ *   - Collapses whitespace + trims; returns `""` if no summary section or
+ *     the section is empty.
+ */
+function _extractFirstSummaryParagraph(md) {
+  if (typeof md !== "string" || md.length === 0) return "";
+  const lines = md.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    if (/^##\s+summary\s*$/i.test(lines[i].trim())) {
+      i += 1;
+      break;
+    }
+    i += 1;
+  }
+  if (i >= lines.length) return "";
+  // Skip blank lines after the heading
+  while (i < lines.length && lines[i].trim().length === 0) i += 1;
+  // Collect until the next blank line or next heading
+  const buf = [];
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim().length === 0) break;
+    if (/^#{1,6}\s/.test(line.trim())) break;
+    buf.push(line.trim());
+    i += 1;
+  }
+  const flat = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (flat.length === 0) return "";
+  if (flat.length <= SUMMARY_MAX_LEN) return flat;
+  return `${flat.slice(0, SUMMARY_MAX_LEN - 1)}…`;
+}
+
+function _readCache(projectRoot) {
+  const cachePath = join(projectRoot, CACHE_FILE_REL);
+  if (!existsSync(cachePath)) return null;
+  try {
+    const raw = readFileSync(cachePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.revision === "string" && parsed.summaries && typeof parsed.summaries === "object") {
+      return parsed;
+    }
+  } catch {
+    // ignore — caller treats null as no-cache
+  }
+  return null;
+}
+
+function _writeCache(projectRoot, payload) {
+  try {
+    const cacheDir = join(projectRoot, CACHE_DIR_REL);
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+    const cachePath = join(projectRoot, CACHE_FILE_REL);
+    writeFileSync(cachePath, JSON.stringify(payload), "utf8");
+  } catch {
+    // Best-effort — failing to persist cache is not an error
+  }
+}
+
+/**
+ * Scan `.fabric/knowledge/<type>/` for the canonical `<id>--<slug>.md`
+ * matching `stableId`. Tries the most likely type-dir first based on the
+ * entry's `type` hint, then falls back to scanning all canonical type
+ * directories. Returns the absolute path or null.
+ *
+ * The id→file mapping is unique by construction (stable_id is allocated
+ * once per file), so the first match wins.
+ */
+function _findEntryFile(projectRoot, stableId, typeHint) {
+  const baseDir = join(projectRoot, KNOWLEDGE_DIR_REL);
+  if (!existsSync(baseDir)) return null;
+  const tryOrder = [];
+  if (typeof typeHint === "string" && typeHint.length > 0) {
+    // Accept both singular and plural hints — find the plural form.
+    const lower = typeHint.toLowerCase();
+    const plural = KNOWLEDGE_TYPE_DIRS.find((d) => d === lower || d.startsWith(lower));
+    if (plural) tryOrder.push(plural);
+  }
+  for (const t of KNOWLEDGE_TYPE_DIRS) {
+    if (!tryOrder.includes(t)) tryOrder.push(t);
+  }
+  const prefix = `${stableId}--`;
+  for (const t of tryOrder) {
+    const typeDir = join(baseDir, t);
+    if (!existsSync(typeDir)) continue;
+    let files;
+    try {
+      files = readdirSync(typeDir);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.startsWith(prefix) && f.endsWith(".md")) {
+        return join(typeDir, f);
+      }
+    }
+  }
+  return null;
+}
+
+function _resolveOne(projectRoot, entry) {
+  const filePath = _findEntryFile(projectRoot, entry.id, entry.type);
+  if (filePath === null) return "";
+  let md;
+  try {
+    md = readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+  return _extractFirstSummaryParagraph(md);
+}
+
+/**
+ * Main API. Returns a new array of entries with `summary` swapped for
+ * the extracted fallback wherever the original summary was opaque AND
+ * the fallback extraction yielded a non-empty string. Non-opaque entries
+ * pass through unchanged.
+ */
+function resolveOpaqueSummaries(entries, projectRoot, revisionHash) {
+  if (!Array.isArray(entries) || entries.length === 0) return entries;
+  const cache = _readCache(projectRoot);
+  const cachedSummaries = cache && cache.revision === revisionHash && cache.summaries ? cache.summaries : {};
+  const nextCacheSummaries = { ...cachedSummaries };
+  let cacheChanged = cache === null || cache.revision !== revisionHash;
+  const result = entries.map((entry) => {
+    if (!_isOpaque(entry)) return entry;
+    const id = entry.id;
+    let fallback;
+    if (Object.prototype.hasOwnProperty.call(cachedSummaries, id)) {
+      fallback = cachedSummaries[id];
+    } else {
+      fallback = _resolveOne(projectRoot, entry);
+      nextCacheSummaries[id] = fallback;
+      cacheChanged = true;
+    }
+    if (typeof fallback === "string" && fallback.length > 0) {
+      return { ...entry, summary: fallback };
+    }
+    return entry;
+  });
+  if (cacheChanged) {
+    _writeCache(projectRoot, { revision: revisionHash, summaries: nextCacheSummaries });
+  }
+  return result;
+}
+
+module.exports = {
+  resolveOpaqueSummaries,
+  _extractFirstSummaryParagraph,
+  _readCache,
+  _writeCache,
+  _findEntryFile,
+  _isOpaque,
+  SUMMARY_MAX_LEN,
+  KNOWLEDGE_TYPE_DIRS,
+};

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

@@ -53,7 +53,7 @@ Graceful degradation: missing digest cache → single-session fallback. Missing
 
 ### Phase 1.5 — First-run Onboard (ref-only)
 
-**SKIP this phase entirely unless** entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND `fab onboard-coverage --json` reports `missing.length > 0`. For E1/E3/E5, silently fall through to Phase 0.
+**SKIP this phase entirely unless** entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND `fabric onboard-coverage --json` reports `missing.length > 0`. For E1/E3/E5, silently fall through to Phase 0.
 
 `Read ref/phase-1-5-onboard.md` for the Step 1-4 coverage check → user prompt → tour-and-propose procedure.
 

package/templates/skills/fabric-archive/ref/dry-run-scope.md

@@ -7,7 +7,7 @@
 | `fab_extract_knowledge` MCP call (Phase 4) | One call per confirmed candidate, writes to `.fabric/knowledge/pending/<slug>.md` | SKIPPED. Phase 4 renders "would write N pending entries" preview table instead. |
 | `session_archive_attempted` event (Phase 4.5) | Appended to `.fabric/events.jsonl` for every session in scope | SKIPPED entirely. No ledger entry. |
 | `fab_review reject` (Phase 3 user-dismissed branch) | Invoked when user types `撤销` / `reject` after self-archive proposal | SKIPPED. The dismissal is rendered to console but no MCP write occurs. |
-| `fab onboard-coverage` slot writes (Phase 1.5 fill-all / dismiss-all) | Each `Bash("fab config dismiss-slot <slot>")` invocation runs | SKIPPED. Slot decisions are shown as "would dismiss/propose" preview. |
+| `fabric onboard-coverage` slot writes (Phase 1.5 fill-all / dismiss-all) | Each `Bash("fabric config dismiss-slot <slot>")` invocation runs | SKIPPED. Slot decisions are shown as "would dismiss/propose" preview. |
 | `.fabric/.cache/session-digests/<session_id>.md` reads | Read freely (read-side, safe) | Read freely — same as normal. |
 | Stop-hook / archive-hint stdin/stdout | Read-only inspection of `.fabric/events.jsonl` | Same — no change. |
 

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

@@ -8,7 +8,7 @@
 
 `今日复盘` = E5 entry point. Default scope = today. Falls back to historical scan if today yields no candidates (silent-skip per Phase 4.5).
 
-E5 是 5 入口模型中唯一由 OS 调度器或 Claude Code `/loop` 周期触发的入口形态。fab 端**零代码**——不提供 `fab schedule` 子命令,亦不内嵌 daemon。用户基于自己的执行环境二选一接入: `/loop`(Claude Code 原生,推荐) 或 OS cron(跨平台 fallback)。
+E5 是 5 入口模型中唯一由 OS 调度器或 Claude Code `/loop` 周期触发的入口形态。fabric 端**零代码**——不提供 `fabric schedule` 子命令,亦不内嵌 daemon。用户基于自己的执行环境二选一接入: `/loop`(Claude Code 原生,推荐) 或 OS cron(跨平台 fallback)。
 
 ### /loop sample (primary path for Claude Code)
 

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

@@ -34,7 +34,7 @@ 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 === "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. `fabric 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`,

package/templates/skills/fabric-archive/ref/phase-1-5-onboard.md

@@ -1,6 +1,6 @@
 # Phase 1.5 — 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.
+> **Loaded on demand.** SKILL.md hot path only runs this when entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND `fabric 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 1.5 — First-run Onboard Phase
 
@@ -55,7 +55,7 @@ tone.
 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
+run an explicit `fabric archive` at least once to populate the onboard
 baseline.
 
 ##### Worked example
@@ -82,7 +82,7 @@ $ /fabric-archive
 
 ---
 
-After F8a removed the auto-`fab scan` baseline pipeline, a freshly installed
+After F8a removed the auto-`fabric 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:
@@ -98,10 +98,10 @@ gathering, so coverage state is fresh for the session.
 
 #### Step 1 — Check coverage
 
-Invoke `fab onboard-coverage --json` and parse the JSON payload:
+Invoke `fabric onboard-coverage --json` and parse the JSON payload:
 
 ```bash
-fab onboard-coverage --json
+fabric onboard-coverage --json
 ```
 
 Expected shape:
@@ -147,8 +147,8 @@ 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 3). |
-| `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. |
+| `fill-each`    | Loop slot-by-slot through `missing`. Per slot: ask user `confirm | dismiss | skip` (per-slot AskUserQuestion); `confirm` → run Step 4; `dismiss` → `fabric config dismiss-slot <slot>`; `skip` → leave for next archive run. |
+| `dismiss-all`  | For EACH slot in `missing`, invoke `Bash("fabric 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)
@@ -174,7 +174,7 @@ After Read-ing the slot-specific sources, classify the observation:
 
 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
+next `fabric onboard-coverage` run will see the slot as filled (once approved
 via fab_review).
 
 Example:
@@ -201,9 +201,9 @@ mcp__fabric__fab_extract_knowledge({
 
 - MUST run BEFORE Phase 2 evidence gathering — onboard is a separate flow,
   not interleaved with session-archive candidates.
-- MUST call `fab onboard-coverage --json` before deciding; never assume
+- MUST call `fabric onboard-coverage --json` before deciding; never assume
   coverage state.
-- NEVER fill a slot that is in `opted_out` — `fab onboard-coverage` already
+- NEVER fill a slot that is in `opted_out` — `fabric 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.