@fenglimg/fabric-cli 2.2.0-rc.4 → 2.2.0-rc.9

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

@@ -12,28 +12,20 @@
  * narrow-injection sibling (E2, knowledge-hint-narrow.cjs) handles
  * per-Edit/Write hints with a session-hints cache.
  *
- * Output contract (stderr only):
+ * Output contract (W2 / KT-DEC-0027/0028/0029 — the SessionStart spine):
  *
- *   When narrow count <= 30 (full per-type listing mode):
- *     [fabric] Session start — N broad-scoped knowledge entries available:
- *       [decision] (proven)
- *         - <id> · <summary>
- *       [pitfall] (verified)
- *         - <id> · <summary>
- *       ...
- *     revision_hash: <hash>
- *     Load full content: `fab_recall(paths)`, or `fab_plan_context` -> `fab_get_knowledge_sections` to trim first.
+ *   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
+ *       [decision] team:KT-DEC-0001 — <must_read_if>
+ *       … N more folded (broad index > backstop 50; run fabric-audit)
+ *     Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md
  *
- *   When narrow count > 30 (grouped-truncation mode, per type):
- *     [fabric] Session start — N broad-scoped knowledge entries available (truncated):
- *       [decision] proven (3):
- *         - <id> · <summary>
- *         - ...
- *       [decision] verified (12): <id1>, <id2>, ...
- *       [decision] draft: 7 entries
- *       ...
- *     revision_hash: <hash>
- *     Load full content: `fab_recall(paths)`, or `fab_plan_context` -> `fab_get_knowledge_sections` to trim first.
+ *   Human sink (systemMessage) — broad-only census breadcrumb; SessionStart is
+ *   SILENT about narrow-scoped knowledge (no on-demand counts, no
+ *   dropped-other-project line).
  *
  *   When 0 entries / CLI unavailable / CLI error / parse failure:
  *     (no output — silent exit 0)
@@ -61,7 +53,6 @@ const { appendLockedLine } = require("./lib/injection-log.cjs");
 // (TASK-002). Variant is resolved ONCE per main() invocation via
 // readFabricLanguage(cwd) and threaded into renderBanner — no fs in render path.
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
-const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 // v2.0.0-rc.37 NEW-19: shared fabric-config reader + sidecar I/O. Replaces the
 // five per-key readFileSync+parse config readers (one parse per fire now) and
 // the bespoke last-emit sidecar helpers. The L78 "refactor into lib/ if a
@@ -74,7 +65,18 @@ const {
 const { readTextState, writeTextState } = require("./lib/state-store.cjs");
 // v2.0.0-rc.37 NEW-30: shared client detection (replaces the inline
 // CLAUDE_PROJECT_DIR single-bit check below).
-const { isClaudeCode, detectClient } = require("./lib/client-adapter.cjs");
+// v2.2 dual-sink (Goal A): + emitDualSink (two-channel SessionStart emit).
+const { isClaudeCode, detectClient, emitDualSink } = require("./lib/client-adapter.cjs");
+// v2.2 dual-sink (Goal A / D4): human-output gate (nudge_mode + observe.*). Only
+// governs the human systemMessage — the AI additionalContext is emitted
+// regardless (flow ⊥ observation). Optional require so an old install lacking the
+// lib degrades to "always emit human" (the pre-dual-sink default).
+let nudgePolicy = null;
+try {
+  nudgePolicy = require("./lib/nudge-policy.cjs");
+} catch {
+  // Lib missing (old install) — human sink always emits (legacy behavior).
+}
 // v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
 // resolved-bindings snapshot. The hook NEVER re-resolves stores or walks store
 // trees — it only echoes the read-set the CLI already computed. Best-effort.
@@ -94,19 +96,62 @@ try {
   // Lib missing (old install) — injection telemetry degrades to silent absence.
 }
 
-// Read the project's own `project_id` from `.fabric/fabric-config.json` (the
-// snapshot key). Reading the PROJECT config is not a store-tree read — it is how
-// the hook learns which snapshot to fetch. Returns null on any failure.
-function readProjectId(cwd) {
+// Read the workspace binding id from `.fabric/fabric-config.json` (the snapshot
+// key). Defaults to project_id when workspace_binding_id is absent.
+function readWorkspaceBindingId(cwd) {
   try {
     const raw = readFileSync(join(cwd, ".fabric", "fabric-config.json"), "utf8");
     const parsed = JSON.parse(raw);
+    if (typeof parsed.workspace_binding_id === "string") return parsed.workspace_binding_id;
     return typeof parsed.project_id === "string" ? parsed.project_id : null;
   } catch {
     return null;
   }
 }
 
+function readSnapshotCanonicalCount(projectRoot) {
+  // No reader / not bound → degrade to an empty corpus (0), the documented
+  // store-only behavior (KT-DEC-0007). Only the "snapshot EXISTS but predates
+  // knowledge_store_dirs" case below is undeterminable → null (skip).
+  if (bindingsSnapshotReader === null) {
+    return 0;
+  }
+  const bindingId = readWorkspaceBindingId(projectRoot);
+  if (bindingId === null) {
+    return 0;
+  }
+  try {
+    const snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    // No snapshot file at all → treat as an empty corpus (KT-DEC-0007),
+    // preserving the fresh-project underseed nudge.
+    if (!snapshot) {
+      return 0;
+    }
+    // LIVE recount off the snapshot's resolved store dirs. The cached
+    // knowledge_stats.canonical_count is frozen at snapshot-write time and goes
+    // stale when store content syncs in out-of-band (e.g. the store grew from 1
+    // → 57 nodes via a `git pull`/cross-workspace sync that never regenerated
+    // THIS workspace's snapshot), which mis-fired the "knowledge sparse"
+    // underseed nudge (KT-PIT-0017, same stale-projection root cause).
+    const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
+    // #3: a snapshot that predates knowledge_store_dirs makes liveKnowledgeStats
+    // return null — the count is undeterminable and the cached projection is
+    // unreliable. Return null (not 0) so countCanonicalNodes / shouldRecommendImport
+    // SKIP the nudge instead of false-firing on stale data; the snapshot
+    // self-heals on the next install/sync. A genuine live 0 (dirs present, no
+    // *.md) still returns 0 and fires correctly.
+    if (live === null) {
+      return null;
+    }
+    return Number.isFinite(live.canonicalCount) ? Math.floor(live.canonicalCount) : 0;
+  } catch {
+    // Read/parse fault → degrade to empty (0), preserving prior behavior. The
+    // only undeterminable→skip path is the explicit live===null above.
+    return 0;
+  }
+}
+
+
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
 // SessionStart fire (matching Skill-style progressive disclosure). Prior
@@ -124,7 +169,6 @@ const FABRIC_DIR_REL = ".fabric";
 // cannot `require` each other. If a third hook ever needs the same logic,
 // refactor into packages/cli/templates/hooks/lib/. Keep these values in sync
 // with packages/cli/templates/hooks/fabric-hint.cjs.
-const AGENTS_META_FILE = "agents.meta.json";
 const IMPORT_STATE_FILE = ".import-state.json";
 const KNOWLEDGE_CANONICAL_TYPES = [
   "decisions",
@@ -135,11 +179,12 @@ const KNOWLEDGE_CANONICAL_TYPES = [
 ];
 const DEFAULT_UNDERSEED_NODE_THRESHOLD = 10;
 
-// v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound on broad-scoped entries surfaced
-// per SessionStart fire. Keeps the banner inside ~1 screenful so the agent
-// actually reads the top-priority entries instead of triaging a wall of text.
-// Overridable via fabric-config.json#hint_broad_top_k (range 1..50).
-const DEFAULT_HINT_BROAD_TOP_K = 8;
+// W2-1 (KT-DEC-0028): the broad index is shown in FULL (no top-K hard cap). The
+// only scale guard is a backstop: when the rendered broad index exceeds this
+// many lines, the overflow tail folds into one marker that doubles as a drift
+// signal (the W4 doctor `broad-index-drift` lint is the authoritative detector).
+// Overridable via fabric-config.json#broad_index_backstop (W4 schema range 20..500).
+const DEFAULT_HINT_BROAD_INDEX_BACKSTOP = 50;
 
 // v2.0.0-rc.33 W2-5 (P1-8): cooldown (in hours) between broad-hint re-emits.
 // Default 0 preserves rc.32 behavior — every SessionStart re-fires the banner.
@@ -169,37 +214,15 @@ const DEFAULT_HINT_REMINDER_TO_CONTEXT = true;
 // -----------------------------------------------------------------------------
 
 /**
- * Count canonical knowledge entries across the five canonical type subdirs
- * (decisions / pitfalls / guidelines / models / processes). Pending entries
- * are NOT counted — they are proposals, not seeded knowledge.
- *
- * Returns the integer count. ENOENT / unreadable subdir → silently treated as
- * zero (preserves never-block-on-failure invariant). Filters on `.md` suffix
- * only; the more-precise canonical filename pattern check is owned by
- * doctor.ts (the hook is a coarse signal, not a lint).
+ * Count canonical knowledge entries from the CLI-generated resolved-bindings
+ * snapshot. Store-only: hooks never walk project-local knowledge or store
+ * trees — a missing snapshot degrades to zero (KT-DEC-0007).
  */
 function countCanonicalNodes(projectRoot) {
-  const knowledgeRoot = join(projectRoot, FABRIC_DIR_REL, "knowledge");
-  if (!existsSync(knowledgeRoot)) {
-    return 0;
-  }
-  let count = 0;
-  for (const type of KNOWLEDGE_CANONICAL_TYPES) {
-    const typeDir = join(knowledgeRoot, type);
-    if (!existsSync(typeDir)) continue;
-    let entries;
-    try {
-      entries = readdirSync(typeDir);
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (entry.endsWith(".md")) {
-        count += 1;
-      }
-    }
-  }
-  return count;
+  // #3: null = undeterminable (old snapshot lacking store dirs, or no binding
+  // context). Propagate it — shouldRecommendImport SKIPS on null rather than
+  // treating it as zero and false-firing the underseed nudge on a stale corpus.
+  return readSnapshotCanonicalCount(projectRoot);
 }
 
 /**
@@ -216,14 +239,15 @@ function readUnderseedThreshold(projectRoot) {
 }
 
 /**
- * v2.0.0-rc.33 W2-1: resolve hint_broad_top_k from fabric-config.json. Slices
- * the broad entry list to TopK before group/truncation render. Validates the
- * schema's 1..50 range inline so a malformed config silently falls back.
+ * W2-1 (KT-DEC-0028): resolve broad_index_backstop from fabric-config.json. Caps
+ * the rendered broad index line count; the overflow tail folds into a drift
+ * marker. Validates the W4 schema's 20..500 range inline so a malformed config
+ * silently falls back to the default.
  */
-function readBroadTopK(projectRoot) {
-  return readConfigNumber(projectRoot, "hint_broad_top_k", DEFAULT_HINT_BROAD_TOP_K, {
-    min: 1,
-    max: 50,
+function readBroadIndexBackstop(projectRoot) {
+  return readConfigNumber(projectRoot, "broad_index_backstop", DEFAULT_HINT_BROAD_INDEX_BACKSTOP, {
+    min: 20,
+    max: 500,
     floor: true,
   });
 }
@@ -309,9 +333,11 @@ function isImportTouched(projectRoot) {
  * surface the one-line `/fabric-import` recommendation banner.
  *
  * Three-condition truth table (ALL must hold to return true):
- *   1. `.fabric/agents.meta.json` exists
- *      (workspace has been `fabric init`-ed; otherwise the recommendation
- *       is meaningless — `fabric-import` requires init's baseline scan).
+ *   1. the workspace is fabric-bound — readWorkspaceBindingId(cwd) !== null
+ *      (a resolved binding id in fabric-config.json; otherwise the
+ *       recommendation is meaningless — `fabric-import` requires a bound
+ *       workspace. Store-only: replaces the legacy derived-index-file
+ *       existence probe.)
  *   2. countCanonicalNodes(cwd) < readUnderseedThreshold(cwd)
  *      (knowledge graph is sparse — import would meaningfully enrich it).
  *   3. isImportTouched(cwd) === 'absent'
@@ -324,11 +350,14 @@ function isImportTouched(projectRoot) {
  */
 function shouldRecommendImport(projectRoot) {
   try {
-    const metaPath = join(projectRoot, FABRIC_DIR_REL, AGENTS_META_FILE);
-    if (!existsSync(metaPath)) return false;
+    if (readWorkspaceBindingId(projectRoot) === null) return false;
 
     const threshold = readUnderseedThreshold(projectRoot);
     const nodeCount = 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.
+    if (nodeCount === null) return false;
     if (nodeCount >= threshold) return false;
 
     if (isImportTouched(projectRoot) !== "absent") return false;
@@ -365,65 +394,6 @@ const CLI_TIMEOUT_MS = 2000;
 // `hint_summary_max_len` in fabric-config overrides this default (range 40..240).
 const DEFAULT_SUMMARY_MAX_LEN = 80;
 
-// v2.2 HK2-degrade (W2-T2): char budget for the rendered broad-menu BODY. The
-// hook already degrades by COUNT (hint_broad_top_k slice + TRUNCATION_THRESHOLD
-// grouped mode), but nothing bounded the total rendered SIZE — a corpus with
-// many types or long (near-maxLen) summaries could still emit a wall of text
-// that displaces the agent's working memory. Borrowing the maestro
-// context-budget idea, this is the final rung of the degradation ladder: once
-// the body exceeds the budget, the tail collapses to a single "N more omitted"
-// marker. Default 2000 chars ≈ one screenful. Overridable via
-// fabric-config.json#hint_broad_budget_chars (range 200..20000); 0 disables.
-const DEFAULT_HINT_BROAD_BUDGET_CHARS = 2000;
-
-// v2.2 C5-budget (W2-T3): bind the injection char budget to the layered retrieval
-// budget profile. Mirrors the injectionChars column of shared/retrieval-budget.ts
-// PROFILES (kept in sync — the hook cannot require the TS resolver). The explicit
-// `hint_broad_budget_chars` knob still wins; the profile only supplies the
-// default. `balanced` (and an absent/unknown profile) keeps the historical 2000.
-const RETRIEVAL_BUDGET_INJECTION_CHARS = {
-  conservative: 1000,
-  balanced: 2000,
-  generous: 4000,
-};
-
-function readBroadBudgetChars(projectRoot) {
-  const profile = readConfigString(projectRoot, "retrieval_budget_profile", "balanced");
-  const profileDefault =
-    RETRIEVAL_BUDGET_INJECTION_CHARS[profile] ?? DEFAULT_HINT_BROAD_BUDGET_CHARS;
-  return readConfigNumber(projectRoot, "hint_broad_budget_chars", profileDefault, {
-    min: 0,
-    max: 20000,
-    floor: true,
-  });
-}
-
-// v2.2 HK2-degrade (W2-T2): cap the rendered body to `budgetChars`, collapsing
-// the overflow tail into one marker line. Structural lines (banner, revision_hash,
-// footer) are appended by renderSummary AFTER this pass, so they always survive —
-// only entry/group body lines are subject to the budget. `budgetChars` of 0 or
-// undefined is a no-op (preserves the pre-HK2 unbounded behavior and all
-// existing snapshot tests).
-function capBodyToBudget(body, budgetChars) {
-  if (!budgetChars || budgetChars <= 0) return body;
-  const kept = [];
-  let total = 0;
-  for (let i = 0; i < body.length; i += 1) {
-    const line = body[i];
-    // +1 for the newline each line costs once joined.
-    if (kept.length > 0 && total + line.length + 1 > budgetChars) {
-      const remaining = body.length - i;
-      kept.push(
-        `  … ${remaining} more entr${remaining === 1 ? "y" : "ies"} omitted (injection budget ${budgetChars} chars; raise hint_broad_budget_chars or narrow scope)`,
-      );
-      return kept;
-    }
-    kept.push(line);
-    total += line.length + 1;
-  }
-  return kept;
-}
-
 function readSummaryMaxLen(projectRoot) {
   return readConfigNumber(projectRoot, "hint_summary_max_len", DEFAULT_SUMMARY_MAX_LEN, {
     min: 40,
@@ -673,7 +643,7 @@ function renderTruncated(narrow, maxLen) {
  * after writing exactly one stderr breadcrumb so operators grepping a stuck-
  * banner report can diagnose the version drift without source-diving.
  */
-function renderSummary(payload, maxLen, budgetChars) {
+function renderSummary(payload, maxLen) {
   if (!payload || payload.version !== 2) {
     if (payload && payload.version !== undefined) {
       try {
@@ -696,9 +666,9 @@ function renderSummary(payload, maxLen, budgetChars) {
     ? `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available (truncated):`
     : `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available:`;
 
-  const renderedBody = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
-  // v2.2 HK2-degrade (W2-T2): final budget rung — cap the body's rendered size.
-  const body = capBodyToBudget(renderedBody, budgetChars);
+  // KT-DEC-0028 completeness: the rendered census is bounded by the per-line
+  // maxLen + TRUNCATION_THRESHOLD grouped mode, not by a body char budget.
+  const body = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
 
   const lines = [banner, ...body];
   const revHash = typeof payload.revision_hash === "string" ? payload.revision_hash : null;
@@ -745,26 +715,307 @@ function renderSummary(payload, maxLen, budgetChars) {
     }
   }
 
-  // v2.2 MC3-fix-guidance (W1-T5): unify the footer with the canonical recall
-  // flow. The prior text ("Use `fab_get_knowledge_sections` to fetch full
-  // content.") told the agent to call a tool that REQUIRES a selection_token it
-  // does not yet have — directly contradicting the bilingual next-step nudge
-  // (and AGENTS.md) which leads with `fab_recall`. Footer now states the same
-  // two-path model: single-step `fab_recall`, or `fab_plan_context` →
-  // `fab_get_knowledge_sections` when the bodies must be trimmed first. Keeps
-  // the `fab_get_knowledge_sections` token (downstream substring contracts) but
-  // sequences it correctly behind the token-issuing `fab_plan_context`.
+  // W2-4 (KT-DEC-0026): single lean retrieval flow. The two-step
+  // fab_plan_context → fab_get_knowledge_sections footer is retired — fab_recall
+  // returns descriptions + read paths, and bodies load via a native Read.
   lines.push(
-    "  Load full content: `fab_recall(paths)` (one step), or `fab_plan_context` → `fab_get_knowledge_sections` to trim first.",
+    "  Load full content: `fab_recall(paths)`, or Read `<store>/knowledge/<type>/<id>--*.md` directly.",
   );
   return lines;
 }
 
+// -----------------------------------------------------------------------------
+// v2.2 dual-sink (Goal A): two-sink SessionStart rendering.
+//
+// HUMAN sink (systemMessage): a grouped census (§3 / D8) — always-loaded vs
+// on-demand split + [team]/[personal] + ✗ dropped-other-project. Count-summary
+// form (not a per-entry wall of text); the verbose nudge_mode appends the legacy
+// per-entry renderSummary listing on top.
+//
+// AI sink (additionalContext): the always-active (guideline/model) BODIES (§3 /
+// D9), bounded by the injection char budget with overflow degrading to summary +
+// a recall pointer, followed by on-demand category counts. Replaces the legacy
+// top_k=8 id-list that used to be the AI payload.
+// -----------------------------------------------------------------------------
+
+// Singular display label for a plural knowledge_type.
+const TYPE_SINGULAR = {
+  decisions: "decision",
+  pitfalls: "pitfall",
+  guidelines: "guideline",
+  models: "model",
+  processes: "process",
+};
+
+const ALWAYS_TYPES = ["guidelines", "models"];
+
+// Normalize a knowledge_type to its canonical PLURAL form. Frontmatter / entries
+// may carry the singular ("decision") while the census keys on the plural enum
+// ("decisions"); fold both so counting + display stay consistent.
+const TYPE_TO_PLURAL = {
+  decision: "decisions",
+  pitfall: "pitfalls",
+  guideline: "guidelines",
+  model: "models",
+  process: "processes",
+};
+function toPluralType(type) {
+  return TYPE_TO_PLURAL[type] || type;
+}
+
+// Fallback census when payload.census is absent (old CLI / unit-test payloads):
+// 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 };
+  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;
+    census.by_type[type] = (census.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).
+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 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(" · ")}`);
+  }
+  return lines;
+}
+
+// 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):
+//
+//   ALWAYS-ACTIVE RULES (guideline/model): INDEX LINE only (title + summary) —
+//     never the eager body (KT-DEC-0036). The body is one cheap on-demand fetch
+//     away, so injecting it on every SessionStart is a permanent context tax
+//     (KT-GLD-0005) we no longer pay; each entry stays individually visible.
+//   REFERENCE (decision/pitfall/process): TITLE + must_read_if hook only
+//     (situational; the agent Reads the body on demand) — never the body.
+//
+// `broadIndexBackstop` (D0028) caps the total rendered index lines; the overflow
+// tail folds into one marker that doubles as the drift signal (fabric-audit /
+// the W4 doctor lint is the authoritative detector). `entries` is the broad
+// plan-context-hint entry list ({id,type,maturity,summary,relevance_scope,
+// must_read_if}); `alwaysBodies` is always_bodies[] ({id,type,layer,summary,body}).
+const REFERENCE_TYPES = new Set(["decision", "pitfall", "process"]);
+
+function renderAiSink(opts) {
+  const { entries, alwaysBodies, storeLabel, broadIndexBackstop, summaryMaxLen, lang } =
+    opts || {};
+  const zh = lang === "zh-CN";
+  const bodies = Array.isArray(alwaysBodies) ? alwaysBodies : [];
+  // REFERENCE = broad decision/pitfall/process. narrow entries stay silent (D0029).
+  const referenceEntries = (Array.isArray(entries) ? entries : []).filter((e) => {
+    if (!e || e.relevance_scope === "narrow") return false;
+    return REFERENCE_TYPES.has(TYPE_SINGULAR[toPluralType(e.type)] || e.type);
+  });
+  // Nothing to inject → empty so main() stays silent on an empty knowledge base.
+  if (bodies.length === 0 && referenceEntries.length === 0) return "";
+
+  const backstop =
+    typeof broadIndexBackstop === "number" && broadIndexBackstop > 0 ? broadIndexBackstop : 0;
+  let indexCount = 0; // total rendered index lines (always + reference), for the backstop.
+
+  const lines = [];
+  lines.push(`[fabric:SessionStart] ${storeLabel || "store"}`);
+
+  // ALWAYS-ACTIVE RULES — index-only (title + summary), never the eager body.
+  lines.push(zh ? "ALWAYS-ACTIVE RULES (无需再 recall):" : "ALWAYS-ACTIVE RULES (no recall needed):");
+  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.
+    for (const b of bodies) {
+      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}`);
+      indexCount += 1;
+    }
+  }
+
+  // REFERENCE — broad decision/pitfall/process: title + must_read_if hook.
+  if (referenceEntries.length > 0) {
+    lines.push(zh ? "REFERENCE (按需 Read / fab_recall):" : "REFERENCE (read on demand / fab_recall):");
+    let folded = 0;
+    for (const e of referenceEntries) {
+      if (backstop > 0 && indexCount >= backstop) {
+        folded += 1;
+        continue;
+      }
+      const type = TYPE_SINGULAR[toPluralType(e.type)] || e.type;
+      const rawHook =
+        typeof e.must_read_if === "string" && e.must_read_if.length > 0
+          ? e.must_read_if
+          : typeof e.summary === "string"
+            ? e.summary
+            : "";
+      const hookText = truncateSummary(rawHook, summaryMaxLen);
+      lines.push(hookText.length > 0 ? `  [${type}] ${e.id} — ${hookText}` : `  [${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)`,
+      );
+    }
+  }
+
+  // W2-4 footer: single lean retrieval flow — no two-step.
+  lines.push(
+    zh
+      ? "取正文: fab_recall(paths), 或 Read <store>/knowledge/<type>/<id>--*.md"
+      : "Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md",
+  );
+  return lines.join("\n");
+}
+
 // -----------------------------------------------------------------------------
 // Main entry — invoked both as a CLI (require.main === module) and in-process
 // by tests. Wraps the entire flow in try/catch: ANY error → silent exit 0.
 // -----------------------------------------------------------------------------
 
+// 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
+// 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.
+//
+// Returns:
+//   human               — gated final human text (null when gated off / empty)
+//   ai                  — gated final AI text (null when reminder-to-context off / empty)
+//   resolvedPayload     — the plan-context payload, passed through unchanged (for telemetry / --explain)
+//   hasRenderedContent  — true when ANY sink rendered content (main's silent-exit gate)
+//   reminderToContext   — readReminderToContext(cwd) (telemetry target-channel)
+function buildSessionStartSinks(cwd, payload, env) {
+  // KT-GLD-0006: the rc.35 opaque-summary runtime substitution
+  // (resolveOpaqueSummaries) is retired. The write-time mechanical floor in
+  // extractKnowledge (summary !== stable_id/slug + length floor) prevents
+  // degenerate summaries at the source, so SessionStart no longer band-aids them
+  // at render time; surviving legacy opaque summaries are fixed by the
+  // review-time cold-eval audit pass.
+  const resolvedPayload = payload;
+
+  const recommendImport = shouldRecommendImport(cwd);
+  const summaryMaxLen = readSummaryMaxLen(cwd);
+  const fabricLanguageForEmit = readFabricLanguage(cwd);
+
+  const census =
+    env && env.census !== undefined
+      ? env.census
+      : payload && payload.census
+        ? payload.census
+        : deriveCensusFromEntries(resolvedPayload && resolvedPayload.entries);
+  const alwaysBodies =
+    env && env.alwaysBodies !== undefined
+      ? env.alwaysBodies
+      : payload && Array.isArray(payload.always_bodies)
+        ? payload.always_bodies
+        : [];
+
+  const humanGate =
+    nudgePolicy !== null
+      ? nudgePolicy.resolveHumanSink(cwd, "session_start", {})
+      : { emitHuman: true, verbosity: "normal" };
+
+  // ---- HUMAN sink: §3 grouped census (+ verbose per-entry detail). ----
+  const humanLines = renderHumanCensus(census, { lang: fabricLanguageForEmit });
+  if (humanLines.length > 0 && humanGate.verbosity === "verbose") {
+    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),
+        );
+        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, {}));
+  }
+  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)",
+    );
+  }
+
+  // ---- AI sink: spine — always-active INDEX lines (no eager body, KT-DEC-0036)
+  // + reference, bounded by the broad_index_backstop fold. ----
+  const broadIndexBackstop = readBroadIndexBackstop(cwd);
+  const aiText = renderAiSink({
+    entries: resolvedPayload && Array.isArray(resolvedPayload.entries) ? resolvedPayload.entries : [],
+    alwaysBodies,
+    broadIndexBackstop,
+    summaryMaxLen,
+    lang: fabricLanguageForEmit,
+  });
+
+  const hasRenderedContent = humanLines.length > 0 || (typeof aiText === "string" && aiText.length > 0);
+  const human = humanGate.emitHuman && humanLines.length > 0 ? humanLines.join("\n") : null;
+  const reminderToContext = readReminderToContext(cwd);
+  const ai = reminderToContext && aiText && aiText.length > 0 ? aiText : null;
+
+  return { human, ai, resolvedPayload, hasRenderedContent, reminderToContext };
+}
+
 function main(env, stdio) {
   try {
     const cwd = (env && env.cwd) || process.cwd();
@@ -802,96 +1053,31 @@ function main(env, stdio) {
       env && env.payload !== undefined ? env.payload : invokePlanContextHint(cwd);
     if (payload === null || payload === undefined) return; // silent
 
-    // v2.0.0-rc.33 W2-1 (P0-9): apply TopK slice BEFORE renderSummary so the
-    // grouped/truncation rendering operates on the bounded set. Slicing here
-    // (not inside renderSummary) keeps the formatter pure — it never has to
-    // know about the cap.
-    const topK = readBroadTopK(cwd);
-    const slicedPayload =
-      payload && Array.isArray(payload.entries) && payload.entries.length > topK
-        ? { ...payload, entries: payload.entries.slice(0, topK) }
-        : payload;
-
-    // rc.35 TASK-06 (P0-10.b): summary-fallback substitution. Entries whose
-    // description.summary equals stable_id render as "<id> · <id>" and the
-    // AI skips fetching them; the fallback reads `## Summary` from the
-    // entry's .md file and swaps in the first paragraph. Best-effort —
-    // failure leaves the original opaque summary untouched.
-    let resolvedPayload = slicedPayload;
-    try {
-      if (slicedPayload && Array.isArray(slicedPayload.entries)) {
-        const resolvedEntries = resolveOpaqueSummaries(
-          slicedPayload.entries,
-          cwd,
-          typeof slicedPayload.revision_hash === "string" ? slicedPayload.revision_hash : "",
-        );
-        resolvedPayload = { ...slicedPayload, entries: resolvedEntries };
-      }
-    } catch {
-      // resolveOpaqueSummaries swallows its own errors; this catch is belt
-      // + suspenders for any unexpected exception from the lib layer.
-    }
-
-    // rc.8 underseed self-check: decide whether to surface the one-line
-    // `/fabric-import` recommendation banner alongside the broad summary.
-    const recommendImport = shouldRecommendImport(cwd);
-
-    // rc.12: broad-summary body is unconditionally rendered on every
-    // SessionStart fire (Skill-style progressive disclosure). The prior
-    // revision_hash cooldown gate (rc.7 T8 — rc.11) was removed because
-    // compact/clear-triggered SessionStart re-fires must re-inject the menu
-    // for the agent's working memory. rc.33 W2-5 reintroduces an opt-in
-    // hours-based cooldown via fabric-config (see gate above).
-    const summaryMaxLen = readSummaryMaxLen(cwd);
-    // v2.2 HK2-degrade (W2-T2): thread the injection char-budget into the renderer.
-    const broadBudgetChars = readBroadBudgetChars(cwd);
-    const lines = renderSummary(resolvedPayload, summaryMaxLen, broadBudgetChars);
-
-    // v2.0.0-rc.37 NEW-23: resolve fabric_language ONCE per emit path —
-    // shared between the (existing) broadImportBanner branch and the new
-    // 'next step' nudge tail added below. 'match-existing' / unknown variants
-    // fold to 'en' inside renderBanner per UX i18n Policy class 1.
-    const fabricLanguageForEmit = lines.length > 0 || recommendImport ? readFabricLanguage(cwd) : null;
-    if (recommendImport && fabricLanguageForEmit !== null) {
-      lines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
-    }
-
-    if (lines.length === 0) return; // nothing to say — silent exit
-
-    // v2.1.0-rc.1 P4 (F4/S63): append a per-store read-set label from the
-    // CLI-pre-generated bindings snapshot so the session opens aware of which
-    // stores it reads and where writes land. Best-effort, never blocks: a
-    // missing snapshot / single-store setup just omits the line.
-    if (bindingsSnapshotReader !== null) {
-      try {
-        const projectId = readProjectId(cwd);
-        if (projectId) {
-          const label = bindingsSnapshotReader.formatStoreLabels(
-            bindingsSnapshotReader.readBindingsSnapshot(projectId),
-          );
-          if (label) lines.push(label);
-        }
-      } catch {
-        // store labels are decorative provenance — never crash the hook
-      }
-    }
-
-    // v2.0.0-rc.37 NEW-23: SessionStart 索引末尾"下一步"引导。Tail line that
-    // tells the AI what to do with the broad index it just received. Without
-    // this, the model often parses the index and moves on without ever calling
-    // fab_recall / fab_plan_context. One-line nudge, bilingual.
-    // v2.2 W1-REVIEW codex LOW-6: `description_index` was renamed to `candidates`
-    // in rc.38 UX-1; the nudge now uses the current field name so the guidance
-    // matches the actual MCP response shape.
-    const nextStepNudge =
-      fabricLanguageForEmit === "zh-CN"
-        ? "下一步: 调 fab_recall(paths) 拿 KB 相关条目;或调 fab_plan_context 先看候选描述(candidates)。"
-        : "Next: call fab_recall(paths) to fetch related KB entries, or fab_plan_context to preview the candidate descriptions first.";
-    lines.push(nextStepNudge);
-
-    // Stderr: always emit (human-facing breadcrumb + legacy contract).
-    for (const line of lines) {
-      err.write(`${line}\n`);
+    // W2-1 (KT-DEC-0028): broad 全显示 — the legacy hint_broad_top_k hard cap is
+    // retired. SessionStart must SEE every broad entry; scale is bounded by the
+    // 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
+    // emit + telemetry below stay in main().
+    const { human, ai, resolvedPayload, hasRenderedContent, reminderToContext } =
+      buildSessionStartSinks(cwd, payload, env);
+
+    // Nothing to say at all → silent exit (preserves the empty-payload contract).
+    if (!hasRenderedContent) return;
+
+    // v2.2 dual-sink (Goal A / D7): emit both channels in one render. The human
+    // systemMessage is gated by nudge_mode (emitHuman); the AI additionalContext
+    // is emitted regardless. emitDualSink shapes the protocol per client (CC/Codex
+    // camelCase nested envelope; unknown → stderr).
+    if (!(env && env.skipStdout === true)) {
+      emitDualSink(
+        { human, ai },
+        { client: detectClient(), eventName: "SessionStart", streams: { stdout: out, stderr: err } },
+      );
+    } else if (human !== null) {
+      // skipStdout test seam: still surface the human breadcrumb to stderr.
+      err.write(`${human}\n`);
     }
 
     // v2.2 HK3-telemetry (W3-T1): record the injection side. We just OFFERED the
@@ -914,37 +1100,10 @@ function main(env, stdio) {
       });
     }
 
-    // v2.0.0-rc.33 W2-6 (P0-7): stdout JSON envelope. When
-    // hint_reminder_to_context is true (default), serialize the same banner
-    // body as Claude Code's SessionStart hookSpecificOutput shape so the model
-    // receives the reminder IN-CONTEXT (rc.32 baseline cite-coverage 3.1%
-    // root cause: reminders never entered model context). Stderr stays the
-    // host-facing channel.
-    //
-    // Failure to write JSON envelope must NOT crash the hook — stderr already
-    // delivered, the stdout layer is best-effort.
-    // v2.0.0-rc.33 W4 review-fix (gemini High-1): the stdout JSON envelope
-    // is Claude Code-specific (hookSpecificOutput.additionalContext contract).
-    // Codex CLI / Cursor don't parse it — leaking it to their stdout risks
-    // either polluting the terminal or crashing the host's hook-parsing
-    // pipeline. CLAUDE_PROJECT_DIR is set by CC when invoking hooks (see
-    // packages/cli/templates/hooks/configs/claude-code.json sigil paths);
-    // its presence is the single-bit "this is Claude Code" signal (now via
-    // the shared client-adapter, rc.37 NEW-30).
-    const reminderToContext = readReminderToContext(cwd) && isClaudeCode();
-    if (reminderToContext && !(env && env.skipStdout === true)) {
-      try {
-        const envelope = {
-          hookSpecificOutput: {
-            hookEventName: "SessionStart",
-            additionalContext: lines.join("\n"),
-          },
-        };
-        out.write(`${JSON.stringify(envelope)}\n`);
-      } catch {
-        // Best-effort — stderr is the durable contract
-      }
-    }
+    // v2.2 dual-sink (Goal A): the legacy rc.33 W2-6 stdout JSON envelope is
+    // replaced by emitDualSink above (which carries BOTH the human systemMessage
+    // and the AI additionalContext, shaped per client). hint_reminder_to_context
+    // still gates whether the AI sink is populated (see `ai` above).
 
     // v2.1 NEW-N-3 (ADJ-NEWN-3): hook_surface_emitted instrumentation. One
     // best-effort ledger row recording WHICH broad-scoped ids were surfaced
@@ -953,7 +1112,7 @@ function main(env, stdio) {
     // per session boot so this never bloats the ledger. Never blocks the hook
     // (KT-DEC-0007): any failure (no .fabric/, undetected client, write error)
     // degrades to silent skip. Client is omitted-by-skip when undetectable
-    // because the schema's `client` enum admits only cc/codex/cursor.
+    // because the schema's `client` enum admits only cc/codex.
     try {
       const surfaceClient = detectClient();
       const fabricDir = join(cwd, FABRIC_DIR_REL);
@@ -1002,6 +1161,7 @@ function main(env, stdio) {
 
 module.exports = {
   main,
+  buildSessionStartSinks,
   invokePlanContextHint,
   groupEntries,
   renderFull,
@@ -1013,8 +1173,8 @@ module.exports = {
   readUnderseedThreshold,
   isImportTouched,
   shouldRecommendImport,
-  // v2.0.0-rc.33 W2-1 / W2-5 / W2-6 helpers.
-  readBroadTopK,
+  // W2-1 (KT-DEC-0028) + rc.33 W2-5 / W2-6 helpers.
+  readBroadIndexBackstop,
   readBroadCooldownHours,
   readReminderToContext,
   readBroadLastEmit,
@@ -1031,7 +1191,7 @@ module.exports = {
     MATURITY_DRAFT,
     DEFAULT_UNDERSEED_NODE_THRESHOLD,
     KNOWLEDGE_CANONICAL_TYPES,
-    DEFAULT_HINT_BROAD_TOP_K,
+    DEFAULT_HINT_BROAD_INDEX_BACKSTOP,
     DEFAULT_HINT_BROAD_COOLDOWN_HOURS,
     DEFAULT_HINT_REMINDER_TO_CONTEXT,
     HINT_BROAD_LAST_EMIT_FILE_NAME,