@fenglimg/fabric-cli 2.2.0-rc.9 → 2.3.0-rc.1

package/templates/hooks/knowledge-hint-broad.cjs

@@ -16,11 +16,11 @@
  *
  *   AI sink (additionalContext) — the dynamically generated "MEMORY.md":
  *     [fabric:SessionStart] <store>
- *     ALWAYS-ACTIVE RULES (no recall needed):    # guideline/model — INDEX line only
- *       [guideline] team:KT-GLD-0001 · <summary> # KT-DEC-0036: no eager body
- *     REFERENCE (read on demand / fab_recall):   # decision/pitfall/process — title + hook
+ *     ALWAYS-ACTIVE RULES (unconditional · act on the line): # guideline/model, BROAD only
+ *       [guideline] team:KT-GLD-0001 · <summary> # INDEX line; body on demand (KT-DEC-0036)
+ *     REFERENCE (situational · Read when must_read_if fires): # decision/pitfall/process, BROAD
  *       [decision] team:KT-DEC-0001 — <must_read_if>
- *       … N more folded (broad index > backstop 50; run fabric-audit)
+ *       … N more folded (broad index > backstop 50; prune via fabric-audit)
  *     Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md
  *
  *   Human sink (systemMessage) — broad-only census breadcrumb; SessionStart is
@@ -42,11 +42,21 @@ const { spawnSync } = require("node:child_process");
 const { existsSync, readdirSync, readFileSync } = require("node:fs");
 const { join } = require("node:path");
 
+// W3-B F-005 (C-003 HUD-shared layer): the SessionStart AI sink reskin consumes
+// the parity-trivial shared structural primitives — sectionBar (title row) +
+// scopeBadge ([team]/[project]/[personal]) — from the .cjs theme mirror. This is
+// the ONLY shared-theme dependency the hook may take: lib/theme.cjs is byte-locked
+// to packages/shared/src/theme.ts by theme-parity.test.ts (G-THEME). The hook MUST
+// NEVER reach for the CLI-only ESM/TS structure layer (the tree / grid primitives
+// under packages/cli/src/tui) — it is unrequireable from a .cjs runtime; the HUD
+// deliberately uses plain two-space indent instead of the complex tree() primitive.
+const { sectionBar, scopeBadge } = require("./lib/theme.cjs");
+
 // W1-01 (ISS-012): the SessionStart broad hook appends a hook_surface_emitted
-// event to the shared events.jsonl. Under multi-window concurrency a bare
-// appendFileSync can interleave a partial write; route through the advisory-lock
-// primitive (drop-on-contention, best-effort — matches injection-log).
-const { appendLockedLine } = require("./lib/injection-log.cjs");
+// event to the shared events.jsonl. ux-w2-9: route through the single guarded
+// event-writer (envelope stamp + event_type guard + advisory-lock append) so
+// the row always satisfies the event-ledger schema the doctor reads.
+const { appendEvent } = require("./lib/event-writer.cjs");
 
 // rc.16 TASK-003: shared banner-i18n lib (resolves fabric_language config and
 // renders localized banner text). Mirror of the wiring in fabric-hint.cjs
@@ -330,7 +340,7 @@ function isImportTouched(projectRoot) {
 
 /**
  * rc.8 underseed self-check: determine whether the SessionStart hook should
- * surface the one-line `/fabric-import` recommendation banner.
+ * surface the one-line `/fabric-archive` recommendation banner.
  *
  * Three-condition truth table (ALL must hold to return true):
  *   1. the workspace is fabric-bound — readWorkspaceBindingId(cwd) !== null
@@ -348,12 +358,22 @@ function isImportTouched(projectRoot) {
  *
  * Best-effort: any unexpected error → return false (do not nag on faults).
  */
-function shouldRecommendImport(projectRoot) {
+function shouldRecommendImport(projectRoot, liveTotal) {
   try {
     if (readWorkspaceBindingId(projectRoot) === null) return false;
 
     const threshold = readUnderseedThreshold(projectRoot);
-    const nodeCount = countCanonicalNodes(projectRoot);
+    // P0 (Goal H3 / KT-PIT-0017 + KT-PIT-0019): prefer the LIVE census total the
+    // HUD displays as the single count source. The census walks the read-set
+    // fresh every fire (never a frozen snapshot projection), so feeding it here
+    // makes the import nudge and the HUD agree by construction — killing the
+    // "HUD shows 61 entries but the nudge claims the KB is sparse" contradiction
+    // the stale-snapshot count produced. Fall back to the snapshot-derived count
+    // only when no live total is supplied (e.g. direct unit-test calls).
+    const nodeCount =
+      typeof liveTotal === "number" && Number.isFinite(liveTotal)
+        ? liveTotal
+        : countCanonicalNodes(projectRoot);
     // #3: undeterminable count (old snapshot predating knowledge_store_dirs) →
     // skip. `null < threshold` coerces to true in JS, so an explicit guard is
     // required — otherwise the stale-snapshot case would still false-fire.
@@ -383,6 +403,12 @@ function shouldRecommendImport(projectRoot) {
 // truncation summary lines) consume it as a single source of truth.
 const TRUNCATION_THRESHOLD = 12;
 
+// Goal H4 action ladder — review rung: surface a single `/fabric-review` line when
+// the LIVE pending backlog exceeds this. Mirrors fabric-hint.cjs's
+// DEFAULT_REVIEW_HINT_PENDING_COUNT (the Stop hook's review threshold) so the two
+// surfaces agree on "how much pending is too much". Strictly `> threshold`.
+const REVIEW_PENDING_THRESHOLD = 10;
+
 // `fabric plan-context-hint` is a thin wrapper over planContext(); on a
 // well-seeded repo it returns in ~100ms. Two-second cap is defensive — any
 // pathological hang must not stall session start.
@@ -425,7 +451,7 @@ const MATURITY_DRAFT = "draft";
 // fabric-hint.cjs Signal C `📋 Fabric:`). rc.16 TASK-003 routed the literal
 // through the banner-i18n lib (key: 'broadImportBanner') — see main() below
 // for the renderBanner call site. Substring contracts preserved across all
-// variants: leading two-space indent, `📋 Fabric:` prefix, `/fabric-import`
+// variants: leading two-space indent, `📋 Fabric:` prefix, `/fabric-archive`
 // verbatim token (asserted by knowledge-hint-broad.test.ts).
 
 // -----------------------------------------------------------------------------
@@ -767,57 +793,126 @@ function toPluralType(type) {
 // count the (possibly sliced) entries by knowledge_type so the human banner still
 // has something to group. Production payloads always carry the unsliced census.
 function deriveCensusFromEntries(entries) {
-  const census = { by_type: {}, by_layer: { team: 0, personal: 0, project: 0 }, dropped_other_project: 0, total: 0 };
+  const census = {
+    by_type: {},
+    by_layer: { team: 0, personal: 0, project: 0 },
+    broad_by_type: {},
+    narrow_total: 0,
+    dropped_other_project: 0,
+    total: 0,
+  };
   if (!Array.isArray(entries)) return census;
   for (const e of entries) {
     const type = e && typeof e.type === "string" ? toPluralType(e.type) : null;
     if (type === null) continue;
+    const isNarrow = e.relevance_scope === "narrow";
     census.by_type[type] = (census.by_type[type] || 0) + 1;
+    if (isNarrow) census.narrow_total += 1;
+    else census.broad_by_type[type] = (census.broad_by_type[type] || 0) + 1;
     census.total += 1;
   }
   return census;
 }
 
-// Render the human-facing grouped census (§3). `lang` is "zh-CN" | other (en).
-// Returns an array of lines (may be empty when the census is empty).
+// Render the human-facing scope-primary status HUD (Goal H2). `lang` is
+// "zh-CN" | other (en). Returns an array of lines (empty when census is empty).
+//
+// Shape (KT-DEC-0029 — SessionStart is scope-primary; broad is the spine that's
+// injected this session, narrow surfaces contextually via the PreToolUse hint):
+//   ▸ [fabric] 共 N 条 · 团队X · 项目Y · 个人Z
+//     broad B · 本会话注入
+//       ├ 常驻规则 G+M  guideline G · model M     (KT-DEC-0027 resident tier)
+//       └ 情境参考 D+P+Pr  decision D · pitfall P · process Pr  (reference tier)
+//     narrow M · 编辑对应文件时浮现                (合计 only, no per-type)
+// Self-consistency invariant: broad (= 常驻 + 参考) + narrow == total.
 function renderHumanCensus(census, opts) {
   const { lang } = opts || {};
   const c = census || {};
-  const byType = c.by_type || {};
   const total = typeof c.total === "number" ? c.total : 0;
   if (total === 0 && (c.dropped_other_project || 0) === 0) return [];
   const zh = lang === "zh-CN";
 
-  const typeCounts = (types) =>
-    types
-      .filter((t) => (byType[t] || 0) > 0)
-      .map((t) => `${TYPE_SINGULAR[t] || t} ${byType[t]}`)
-      .join(" · ");
+  const broadByType = c.broad_by_type || {};
+  const narrowTotal = typeof c.narrow_total === "number" ? c.narrow_total : 0;
+  // Per-tier broad counts. `broad_by_type` keys on the plural enum.
+  const g = broadByType.guidelines || 0;
+  const m = broadByType.models || 0;
+  const d = broadByType.decisions || 0;
+  const p = broadByType.pitfalls || 0;
+  const pr = broadByType.processes || 0;
+  const residentN = g + m; // 常驻规则 (always-active: guideline + model)
+  const referenceN = d + p + pr; // 情境参考 (decision + pitfall + process)
+  const broadN = residentN + referenceN;
 
-  const lines = [];
-  // `total` is the read-set ENTRY COUNT (not bytes) — label it as 条/entries.
-  lines.push(`▸ [fabric] SessionStart (${total} ${zh ? "条" : total === 1 ? "entry" : "entries"})`);
-  // W2-2/W2-3 (KT-DEC-0027/0029): the human breadcrumb shows only the
-  // always-loaded (guideline/model) census. The on-demand (decision/pitfall/
-  // process) count line and the dropped-other-project line are retired — the
-  // decision/pitfall/process REFERENCE lives in the AI sink (title + must_read_if),
-  // and SessionStart stays silent about narrow-scoped knowledge.
-  const alwaysCounts = typeCounts(ALWAYS_TYPES);
-  lines.push(zh ? "  ─ always-loaded(AI 也收到正文)─" : "  ─ always-loaded (AI also gets bodies) ─");
-  lines.push(`   ${alwaysCounts.length > 0 ? alwaysCounts : zh ? "(无)" : "(none)"}`);
   const layer = c.by_layer || {};
   const teamCount = layer.team || 0;
   const personalCount = layer.personal || 0;
   const projectCount = layer.project || 0;
-  if (teamCount > 0 || personalCount > 0 || projectCount > 0) {
-    const segs = [`[team] ${teamCount}`];
-    if (projectCount > 0) segs.push(`[project] ${projectCount}`);
-    segs.push(`[personal] ${personalCount}`);
-    lines.push(`  ${segs.join(" · ")}`);
-  }
+
+  const lines = [];
+  // Header: total entry count + semantic_scope breakdown (KT-MOD-0001 三轴).
+  const scopeSegs = [zh ? `团队 ${teamCount}` : `team ${teamCount}`];
+  if (projectCount > 0) scopeSegs.push(zh ? `项目 ${projectCount}` : `project ${projectCount}`);
+  scopeSegs.push(zh ? `个人 ${personalCount}` : `personal ${personalCount}`);
+  const totalLabel = zh ? `共 ${total} 条` : `${total} ${total === 1 ? "entry" : "entries"}`;
+  lines.push(`▸ [fabric] ${totalLabel} · ${scopeSegs.join(" · ")}`);
+
+  // broad spine — injected this session.
+  lines.push(zh ? `  broad ${broadN} · 本会话注入` : `  broad ${broadN} · injected this session`);
+  const residentDetail = [];
+  if (g > 0) residentDetail.push(`guideline ${g}`);
+  if (m > 0) residentDetail.push(`model ${m}`);
+  const refDetail = [];
+  if (d > 0) refDetail.push(`decision ${d}`);
+  if (p > 0) refDetail.push(`pitfall ${p}`);
+  if (pr > 0) refDetail.push(`process ${pr}`);
+  const dash = zh ? "—" : "—";
+  lines.push(
+    zh
+      ? `    ├ 常驻规则 ${residentN}  ${residentDetail.join(" · ") || dash}`
+      : `    ├ resident ${residentN}  ${residentDetail.join(" · ") || dash}`,
+  );
+  lines.push(
+    zh
+      ? `    └ 情境参考 ${referenceN}  ${refDetail.join(" · ") || dash}`
+      : `    └ reference ${referenceN}  ${refDetail.join(" · ") || dash}`,
+  );
+
+  // narrow remainder — 合计 only (no per-type; it's file-specific, surfaces on edit).
+  lines.push(
+    zh
+      ? `  narrow ${narrowTotal} · 编辑对应文件时浮现`
+      : `  narrow ${narrowTotal} · surfaces when you edit matching files`,
+  );
   return lines;
 }
 
+// Goal H2: the SessionStart store label, scope-primary wording — `写入 X · 只读 Y`
+// (write target receives new knowledge; the rest are read-only sources). Replaces
+// the legacy `read-set stores: a (write), b (ro)` jargon line inline (kept local
+// to this hook so the shared lib formatStoreLabels — used by other hooks — is
+// untouched). Empty string when there is nothing to show.
+function renderScopeStoreLabel(snapshot, lang) {
+  if (!snapshot || !snapshot.read_set || !Array.isArray(snapshot.read_set.stores)) return "";
+  const stores = snapshot.read_set.stores;
+  if (stores.length === 0) return "";
+  const zh = lang === "zh-CN";
+  const writeAlias = snapshot.write_target && snapshot.write_target.alias;
+  const writeStores = [];
+  const readonlyStores = [];
+  for (const s of stores) {
+    const alias = s && typeof s.alias === "string" ? s.alias : null;
+    if (alias === null) continue;
+    if (alias === writeAlias) writeStores.push(alias);
+    else readonlyStores.push(alias);
+  }
+  const segs = [];
+  if (writeStores.length > 0) segs.push((zh ? "写入 " : "write ") + writeStores.join(", "));
+  if (readonlyStores.length > 0) segs.push((zh ? "只读 " : "readonly ") + readonlyStores.join(", "));
+  if (segs.length === 0) return "";
+  return "  " + segs.join(" · ");
+}
+
 // W2 (KT-DEC-0027/0028/0029): render the AI-facing sink — the dynamically
 // generated "MEMORY.md" spine injected into the SessionStart context. Two
 // type-tiered sections over the BROAD knowledge (narrow stays silent — D0029):
@@ -836,6 +931,24 @@ function renderHumanCensus(census, opts) {
 // must_read_if}); `alwaysBodies` is always_bodies[] ({id,type,layer,summary,body}).
 const REFERENCE_TYPES = new Set(["decision", "pitfall", "process"]);
 
+// W3-B F-005: map a knowledge entry's layer to a scopeBadge() scope key
+// (team→'team' · project→'project' · personal→'personal'). Bodies carry an
+// explicit `.layer`; plan-context reference entries do not, so the layer is
+// recovered from the id prefix (`team:KT-…` / `project:…` / `personal:…`), with a
+// `KP-` id always personal. Anything unrecognized falls back to 'team' — the
+// broadest, default tier — so the badge never renders an undefined scope.
+const VALID_SCOPES = new Set(["team", "project", "personal"]);
+function layerToScope(entry) {
+  const e = entry || {};
+  if (typeof e.layer === "string" && VALID_SCOPES.has(e.layer)) return e.layer;
+  const id = typeof e.id === "string" ? e.id : "";
+  const prefix = id.includes(":") ? id.slice(0, id.indexOf(":")) : "";
+  if (VALID_SCOPES.has(prefix)) return prefix;
+  // `KP-*` ids are the personal convention even without a `personal:` prefix.
+  if (/(^|:)KP-/.test(id)) return "personal";
+  return "team";
+}
+
 function renderAiSink(opts) {
   const { entries, alwaysBodies, storeLabel, broadIndexBackstop, summaryMaxLen, lang } =
     opts || {};
@@ -854,34 +967,64 @@ function renderAiSink(opts) {
   let indexCount = 0; // total rendered index lines (always + reference), for the backstop.
 
   const lines = [];
-  lines.push(`[fabric:SessionStart] ${storeLabel || "store"}`);
+  // W3-B F-005 (mockup #3): a single sectionBar title carrying the active /
+  // reference counts, replacing the legacy `[fabric:SessionStart] <store>` +
+  // flat `ALWAYS-ACTIVE RULES (...)` header. The store label is preserved on the
+  // human sink (renderScopeStoreLabel); the AI sink leads with the count title.
+  // sectionBar degrades to `# <title>` when color is off (NO_COLOR / non-TTY),
+  // byte-locked to the TS source by theme-parity.
+  lines.push(
+    sectionBar(
+      zh
+        ? `Fabric Knowledge · ${bodies.length} 常驻 · ${referenceEntries.length} 参考`
+        : `Fabric Knowledge · ${bodies.length} active · ${referenceEntries.length} reference`,
+    ),
+  );
 
-  // ALWAYS-ACTIVE RULES — index-only (title + summary), never the eager body.
-  lines.push(zh ? "ALWAYS-ACTIVE RULES (无需再 recall):" : "ALWAYS-ACTIVE RULES (no recall needed):");
+  // ALWAYS-ACTIVE — plain sub-section label (the `RULES (...)` qualifier is kept
+  // so the contract substring + framing survive the reskin). Index-only (title +
+  // summary), never the eager body.
+  lines.push(
+    zh
+      ? "  ALWAYS-ACTIVE RULES (无条件适用 · 照此行遵循,正文按需取):"
+      : "  ALWAYS-ACTIVE RULES (unconditional · act on the line; body on demand):",
+  );
   if (bodies.length === 0) {
     lines.push(zh ? "  (无 always-active 条目)" : "  (none)");
   } else {
     // KT-DEC-0036: render each always-active entry as a single index line
-    // (title + summary). The body is one cheap on-demand fetch away (see footer),
-    // so injecting it on every SessionStart is a permanent context tax
-    // (KT-GLD-0005) we no longer pay.
+    // (scope badge + title + summary). The body is one cheap on-demand fetch away
+    // (see footer), so injecting it on every SessionStart is a permanent context
+    // tax (KT-GLD-0005) we no longer pay.
     for (const b of bodies) {
+      const badge = scopeBadge(layerToScope(b));
       const label = `[${TYPE_SINGULAR[b.type] || b.type}] ${b.id}`;
-      const summary = typeof b.summary === "string" ? b.summary.trim() : "";
-      lines.push(summary.length > 0 ? `  ${label} · ${summary}` : `  ${label}`);
+      // ux-w1-3: bound the always-active summary by hint_summary_max_len, mirroring
+      // the REFERENCE must_read_if hook below — one long entry must not blow up the
+      // SessionStart sink.
+      const raw = typeof b.summary === "string" ? b.summary.trim() : "";
+      const summary = truncateSummary(raw, summaryMaxLen);
+      lines.push(
+        summary.length > 0 ? `  ${badge} ${label} · ${summary}` : `  ${badge} ${label}`,
+      );
       indexCount += 1;
     }
   }
 
-  // REFERENCE — broad decision/pitfall/process: title + must_read_if hook.
+  // REFERENCE — broad decision/pitfall/process: scope badge + title + must_read_if hook.
   if (referenceEntries.length > 0) {
-    lines.push(zh ? "REFERENCE (按需 Read / fab_recall):" : "REFERENCE (read on demand / fab_recall):");
+    lines.push(
+      zh
+        ? "  REFERENCE (情境触发 · 命中 must_read_if 时 Read / fab_recall):"
+        : "  REFERENCE (situational · Read when must_read_if fires / fab_recall):",
+    );
     let folded = 0;
     for (const e of referenceEntries) {
       if (backstop > 0 && indexCount >= backstop) {
         folded += 1;
         continue;
       }
+      const badge = scopeBadge(layerToScope(e));
       const type = TYPE_SINGULAR[toPluralType(e.type)] || e.type;
       const rawHook =
         typeof e.must_read_if === "string" && e.must_read_if.length > 0
@@ -890,15 +1033,19 @@ function renderAiSink(opts) {
             ? e.summary
             : "";
       const hookText = truncateSummary(rawHook, summaryMaxLen);
-      lines.push(hookText.length > 0 ? `  [${type}] ${e.id} — ${hookText}` : `  [${type}] ${e.id}`);
+      lines.push(
+        hookText.length > 0
+          ? `  ${badge} [${type}] ${e.id} — ${hookText}`
+          : `  ${badge} [${type}] ${e.id}`,
+      );
       indexCount += 1;
     }
     // D0028 backstop: fold the overflow tail into one marker + drift signal.
     if (folded > 0) {
       lines.push(
         zh
-          ? `  … 另 ${folded} 条 broad 条目折叠 (broad index > backstop ${backstop}; 跑 fabric-audit)`
-          : `  … ${folded} more broad entr${folded === 1 ? "y" : "ies"} folded (broad index > backstop ${backstop}; run fabric-audit)`,
+          ? `  … 另 ${folded} 条 broad 条目折叠 (broad index > backstop ${backstop})。先跑 fabric-audit 瘦身;确需全展示再调 .fabric/fabric-config.json#broad_index_backstop (20..500)`
+          : `  … ${folded} more broad entr${folded === 1 ? "y" : "ies"} folded (broad index > backstop ${backstop}). Run fabric-audit to prune first; raise .fabric/fabric-config.json#broad_index_backstop (20..500) only if you truly need them all`,
       );
     }
   }
@@ -909,6 +1056,15 @@ function renderAiSink(opts) {
       ? "取正文: fab_recall(paths), 或 Read <store>/knowledge/<type>/<id>--*.md"
       : "Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md",
   );
+  // H6 scope discipline: this sink carries ONLY broad (always-relevant) knowledge;
+  // narrow (file-specific) entries surface contextually via the PreToolUse hint
+  // when you edit a matching file (KT-DEC-0029). Stops the agent from assuming
+  // SessionStart is the whole KB.
+  lines.push(
+    zh
+      ? "范围: 此处仅 broad(始终相关);narrow(文件专属)在你编辑对应文件时由 PreToolUse 浮现"
+      : "Scope: broad only (always relevant) here; narrow (file-specific) surfaces via the PreToolUse hint when you edit a matching file",
+  );
   return lines.join("\n");
 }
 
@@ -920,7 +1076,7 @@ function renderAiSink(opts) {
 // Block 5 (Option X): build the two SessionStart sinks (human systemMessage +
 // AI additionalContext) from a plan-context-hint payload, WITHOUT emitting or
 // recording telemetry. This is the single shared renderer: main() calls it then
-// emits + logs; `fabric context` calls it then prints (byte-identical injection
+// emits + logs; `fabric inspect` calls it then prints (byte-identical injection
 // by construction — same code, same config/FS reads). Pure-ish: it reads config
 // + snapshot + .md summaries for `cwd` but has no stdout/ledger side effects.
 //
@@ -939,7 +1095,6 @@ function buildSessionStartSinks(cwd, payload, env) {
   // review-time cold-eval audit pass.
   const resolvedPayload = payload;
 
-  const recommendImport = shouldRecommendImport(cwd);
   const summaryMaxLen = readSummaryMaxLen(cwd);
   const fabricLanguageForEmit = readFabricLanguage(cwd);
 
@@ -956,6 +1111,24 @@ function buildSessionStartSinks(cwd, payload, env) {
         ? payload.always_bodies
         : [];
 
+  // H3: the LIVE census total is the single count source for the import gate —
+  // computed AFTER census so the nudge and the HUD agree by construction.
+  const censusTotal = census && typeof census.total === "number" ? census.total : undefined;
+  const recommendImport = shouldRecommendImport(cwd, censusTotal);
+
+  // Read the resolved-bindings snapshot ONCE — reused for the scope store label
+  // (写入/只读) and the H4 review-rung pending count. Best-effort/decorative: any
+  // failure leaves snapshot null and the dependent lines simply don't render.
+  let snapshot = null;
+  if (bindingsSnapshotReader !== null) {
+    try {
+      const bindingId = readWorkspaceBindingId(cwd);
+      if (bindingId) snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    } catch {
+      snapshot = null;
+    }
+  }
+
   const humanGate =
     nudgePolicy !== null
       ? nudgePolicy.resolveHumanSink(cwd, "session_start", {})
@@ -967,33 +1140,46 @@ function buildSessionStartSinks(cwd, payload, env) {
     const detail = renderSummary(resolvedPayload, summaryMaxLen);
     humanLines.push(...detail);
   }
-  if (bindingsSnapshotReader !== null && humanLines.length > 0) {
-    try {
-      const bindingId = readWorkspaceBindingId(cwd);
-      if (bindingId) {
-        const label = bindingsSnapshotReader.formatStoreLabels(
-          bindingsSnapshotReader.readBindingsSnapshot(bindingId),
+  // H2: scope store label — `写入 X · 只读 Y` (replaces the legacy read-set jargon).
+  if (humanLines.length > 0 && snapshot !== null) {
+    const storeLabel = renderScopeStoreLabel(snapshot, fabricLanguageForEmit);
+    if (storeLabel) humanLines.push(storeLabel);
+  }
+
+  // H4 action ladder (KT-DEC-0007: nudge, never a gate). AT MOST ONE line, the
+  // highest-priority rung wins, and steady state is fully silent:
+  //   1. import  — KB is sparse (recommendImport, off the live census total)
+  //   2. review  — pending backlog exceeds REVIEW_PENDING_THRESHOLD (live count)
+  //   3. (silent)
+  if (humanLines.length > 0 && fabricLanguageForEmit !== null) {
+    if (recommendImport) {
+      humanLines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
+    } else if (snapshot !== null && bindingsSnapshotReader !== null) {
+      let pendingCount = 0;
+      try {
+        const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
+        if (live && Number.isFinite(live.pendingCount)) pendingCount = Math.floor(live.pendingCount);
+      } catch {
+        pendingCount = 0;
+      }
+      if (pendingCount > REVIEW_PENDING_THRESHOLD) {
+        humanLines.push(
+          fabricLanguageForEmit === "zh-CN"
+            ? `  📋 Fabric: ${pendingCount} 条 pending 待审,是否调 /fabric-review?`
+            : `  📋 Fabric: ${pendingCount} pending entries — run /fabric-review?`,
         );
-        if (label) humanLines.push(label);
       }
-    } catch {
-      // store labels are decorative provenance — never crash the hook
     }
   }
-  if (recommendImport && humanLines.length > 0 && fabricLanguageForEmit !== null) {
-    humanLines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
-  }
+
+  // H5: the `下一步: …fab_recall…` AI-plumbing line is retired from the human sink
+  // (the AI gets it from its own footer + the MCP server directive). Keep only the
+  // pointer to the byte-identical inspector for this injection.
   if (humanLines.length > 0) {
     humanLines.push(
       fabricLanguageForEmit === "zh-CN"
-        ? "下一步: 改相关文件前调 fab_recall(paths) 拿 KB 条目的描述+读路径;按需 Read 路径取正文。"
-        : "Next: before editing related files, call fab_recall(paths) for the KB entries' descriptions + read paths; Read a path on demand for the body.",
-    );
-    // Block 5 (Option X): point to the byte-identical inspector for this injection.
-    humanLines.push(
-      fabricLanguageForEmit === "zh-CN"
-        ? "看具体注入: fabric context (--explain 看每条来源)"
-        : "Inspect this injection: fabric context (--explain for per-entry provenance)",
+        ? "  看具体注入: fabric inspect (--explain 看每条来源)"
+        : "  Inspect this injection: fabric inspect (--explain for per-entry provenance)",
     );
   }
 
@@ -1058,7 +1244,7 @@ function main(env, stdio) {
     // per-line char cap + broad_index_backstop fold, not by dropping entries.
 
     // Block 5 (Option X): build both sinks via the shared renderer (same code
-    // `fabric context` uses → byte-identical injection). Side-effect-free; the
+    // `fabric inspect` uses → byte-identical injection). Side-effect-free; the
     // emit + telemetry below stay in main().
     const { human, ai, resolvedPayload, hasRenderedContent, reminderToContext } =
       buildSessionStartSinks(cwd, payload, env);
@@ -1141,7 +1327,7 @@ function main(env, stdio) {
           rendered_ids: renderedIds,
           delivery_status: "delivered",
         };
-        appendLockedLine(join(fabricDir, "events.jsonl"), JSON.stringify(surfaceEvent) + "\n");
+        appendEvent(fabricDir, surfaceEvent);
       }
     } catch {
       // best-effort telemetry — never block session start
@@ -1167,6 +1353,10 @@ module.exports = {
   renderFull,
   renderTruncated,
   renderSummary,
+  // W3-B F-005: the reskinned SessionStart AI sink + its layer→scope mapper,
+  // exported for the NO_COLOR snapshot test (hud-reskin.test.ts).
+  renderAiSink,
+  layerToScope,
   truncateSummary,
   // rc.8 underseed self-check helpers (exported for unit testing).
   countCanonicalNodes,

package/templates/hooks/knowledge-hint-narrow.cjs

@@ -19,7 +19,7 @@
  *         [<id>] (<type>/<maturity>) <summary-line>
  *         [<id>] (<type>/<maturity>) <summary-line>
  *         ...
- *       (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)
+ *       (如需重读 broad 决策，跑 fabric plan-context-hint --all)
  *
  *     When narrow.length === 0: complete silence (exit 0, no stderr).
  *
@@ -1215,7 +1215,7 @@ function readSummaryMaxLen(projectRoot) {
  *   [fabric] N narrow-scoped knowledge entries match your edit targets:
  *     [<id>] (<type>/<maturity>) <summary>
  *     ...
- *   (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)
+ *   (如需重读 broad 决策，跑 fabric plan-context-hint --all)
  */
 function renderSummary(payload, maxLen) {
   if (!payload || payload.version !== 2) {
@@ -1242,7 +1242,7 @@ function renderSummary(payload, maxLen) {
   for (const entry of entries) {
     lines.push(formatEntryLine(entry, maxLen));
   }
-  lines.push("  (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)");
+  lines.push("  (如需重读 broad 决策，跑 fabric plan-context-hint --all)");
   return lines;
 }