@fenglimg/fabric-cli 2.0.0 → 2.0.1

package/templates/hooks/lib/banner-i18n.cjs

@@ -0,0 +1,309 @@
+/**
+ * v2.0.0-rc.16 TASK-001 (F2-prep): shared banner-i18n library for hook scripts.
+ *
+ * Provides:
+ *   - readFabricLanguage(projectRoot) → 'zh-CN' | 'en' | 'zh-CN-hybrid' | 'match-existing'
+ *     Synchronously reads `fabric_language` from `.fabric/fabric-config.json`.
+ *     Mirrors the never-throw contract of the existing config readers in
+ *     fabric-hint.cjs (readReviewHintPendingCount, readMaintenanceHintDays, etc.):
+ *     missing file / parse error / missing field → returns 'zh-CN' (the
+ *     documented BACKWARD-COMPAT default — preserves rc.15 hard-coded zh-CN
+ *     hook output when fabric_language was never a configurable key).
+ *
+ *     'match-existing' is ONLY returned when explicitly set in config; per UX
+ *     i18n Policy class 1, renderBanner then folds 'match-existing' (and any
+ *     unknown variant) down to 'en'.
+ *
+ *     RC.16 TASK-002 NOTE: this default was originally 'match-existing' in
+ *     TASK-001 but was tightened to 'zh-CN' here so that the existing rc.7+
+ *     fabric-hint test fixtures (which never set fabric_language and expect
+ *     zh-CN substrings byte-identically) continue passing without modification.
+ *     Pre-user clean-slate policy: no shim, but back-compat for in-tree tests
+ *     is the right line — they encode the rc.15 user-visible contract.
+ *
+ *   - renderBanner(key, variant, params) → string
+ *     Renders one of the 11 banner fragments for the requested variant.
+ *     Variant fallback: STRINGS[key][variant] ?? STRINGS[key]['en'].
+ *     Unknown / 'match-existing' / missing → 'en' table.
+ *
+ *   - STRINGS — exported for test introspection only (read-only by convention).
+ *
+ * Banner keys (11 total):
+ *   Signal A (archive):     archiveLine1, archiveActivity, archiveCta
+ *   Signal B (review):      reviewLine1, reviewCta
+ *   Signal C (import):      importLine1, importCta
+ *   Signal D (maintenance): maintenanceLine1Never, maintenanceLine1Aged, maintenanceLine2
+ *   Broad hook:             broadImportBanner
+ *
+ * Protected tokens — NEVER translated, kept verbatim across all 4 variants:
+ *   - Slash commands: /fabric-archive, /fabric-review, /fabric-import
+ *   - CLI commands:   `fabric doctor --lint`
+ *   - Numeric / template substrings the existing tests assert on:
+ *       "${hoursElapsed.toFixed(1)}h" (e.g. "25.0h"), "阈值 ${N}h",
+ *       "${count} 条", "${nodeCount}/${threshold}", "${days} 天"
+ *   - 📋 Fabric: emoji prefix
+ *
+ * zh-CN-hybrid policy: Chinese narrative prose with English protected tokens
+ * preserved verbatim. In practice this matches zh-CN exactly because the
+ * banners already inline slash commands + CLI commands without translation;
+ * we keep the variant entries explicit anyway for forward-compat (future copy
+ * may diverge, e.g. mixing English connector words).
+ *
+ * match-existing policy: per UX i18n Policy class 1, falls back to 'en' at
+ * render time. The fallback decision is centralized in renderBanner; only an
+ * EXPLICIT `fabric_language: "match-existing"` in config triggers the en
+ * fallback. Unset / missing config defaults to 'zh-CN' (rc.15 back-compat).
+ *
+ * Pattern reference:
+ *   - Never-throw fs read: fabric-hint.cjs `_readConfigNumber`,
+ *     `readReviewHintPendingCount` (lines 720-743)
+ *   - hooks/lib/*.cjs precedent: session-digest-writer.cjs
+ */
+"use strict";
+
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR = ".fabric";
+const CONFIG_FILE = "fabric-config.json";
+
+const VALID_LANGUAGES = ["zh-CN", "en", "zh-CN-hybrid", "match-existing"];
+// rc.16 TASK-002: backward-compat default. rc.15 and earlier hardcoded
+// zh-CN in the hook scripts; preserving zh-CN as the unset-default keeps
+// the rc.7+ fabric-hint test fixtures (which assert Chinese substrings
+// without ever setting fabric_language) green and matches the user-visible
+// contract real workspaces have observed since rc.7.
+const DEFAULT_LANGUAGE = "zh-CN";
+const RENDER_FALLBACK_VARIANT = "en";
+
+/**
+ * Read `fabric_language` from <projectRoot>/.fabric/fabric-config.json.
+ *
+ * Returns one of the four valid language codes. Missing file, malformed JSON,
+ * missing/unknown field value → DEFAULT_LANGUAGE ('zh-CN' — see comment on
+ * the constant for the back-compat rationale). NEVER throws — config-read
+ * failure must not block any hook.
+ */
+function readFabricLanguage(projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    return DEFAULT_LANGUAGE;
+  }
+  const configPath = join(projectRoot, FABRIC_DIR, CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_LANGUAGE;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.fabric_language;
+    if (typeof v === "string" && VALID_LANGUAGES.indexOf(v) !== -1) {
+      return v;
+    }
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_LANGUAGE;
+}
+
+// ---------------------------------------------------------------------------
+// String table
+// ---------------------------------------------------------------------------
+//
+// Each key maps variant -> (params) => string. Templates intentionally use
+// the same parameter names across all four variants so call sites pass one
+// shape. Substring contracts (see file header) are preserved verbatim across
+// translations; only narrative connector words shift.
+// ---------------------------------------------------------------------------
+
+const STRINGS = {
+  // ---- Signal A: archive ----------------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:614  `📋 Fabric: 距上次归档 ${parts}。`
+  // params: { parts } where parts is pre-joined `已过 25.0h（阈值 24h）` etc.
+  //
+  // v2.0.0-rc.27 TASK-005 (audit §2.17): `parts` is now constructed by the
+  // sibling archivePartsHours / archivePartsEdits keys (also per-variant) so
+  // the caller never hardcodes Chinese into the en banner. The substring
+  // contract on "25.0h" / "阈值 N" / "次编辑" is preserved per-variant but
+  // each variant gets a coherent monolingual rendering — pre-rc.27 produced
+  // mixed-language output like `📋 Fabric: 已过 25.0h since last archive.`
+  // (audit §2.17 reproduction).
+  archiveLine1: {
+    "zh-CN": (p) => `📋 Fabric: 距上次归档 ${p.parts}。`,
+    en: (p) => `📋 Fabric: ${p.parts} since last archive.`,
+    "zh-CN-hybrid": (p) => `📋 Fabric: 距上次归档 ${p.parts}。`,
+  },
+
+  // v2.0.0-rc.27 TASK-005 (audit §2.17): per-variant assembly of the
+  // hours-trigger fragment. zh-CN tightens to the original substring
+  // contract (`已过 25.0h（阈值 24h）`); en variant translates the prose
+  // while preserving the numeric tokens; hybrid mirrors zh-CN.
+  // params: { hoursFixed: string (already toFixed(1)), threshold: number }
+  archivePartsHours: {
+    "zh-CN": (p) => `已过 ${p.hoursFixed}h（阈值 ${p.threshold}h）`,
+    en: (p) => `${p.hoursFixed}h elapsed (threshold ${p.threshold}h)`,
+    "zh-CN-hybrid": (p) => `已过 ${p.hoursFixed}h（阈值 ${p.threshold}h）`,
+  },
+
+  // v2.0.0-rc.27 TASK-005 (audit §2.17): edits-trigger fragment.
+  // params: { count: number, threshold: number }
+  archivePartsEdits: {
+    "zh-CN": (p) => `累计 ${p.count} 次编辑（阈值 ${p.threshold}）`,
+    en: (p) => `${p.count} edits since last archive (threshold ${p.threshold})`,
+    "zh-CN-hybrid": (p) => `累计 ${p.count} 次编辑（阈值 ${p.threshold}）`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:619  `   最近活动集中在: ${activity}。`
+  // params: { activity }
+  archiveActivity: {
+    "zh-CN": (p) => `   最近活动集中在: ${p.activity}。`,
+    en: (p) => `   Recent activity centered on: ${p.activity}.`,
+    "zh-CN-hybrid": (p) => `   最近活动集中在: ${p.activity}。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:621  `   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?`
+  // params: {} — protected token /fabric-archive verbatim across all variants.
+  archiveCta: {
+    "zh-CN": () => "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?",
+    en: () => "   Run /fabric-archive to review decisions/pitfalls/reusables worth archiving?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?",
+  },
+
+  // ---- Signal B: review -----------------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:651  `📋 Fabric: 已积累 ${stats.count} 条待审核知识${ageSuffix}。`
+  // params: { count, ageSuffix } — ageSuffix is " / 最早一条 N.N 天前" or "" (zh-CN only)
+  // For en variant we shape the suffix inline to keep substring "${count}" addressable.
+  reviewLine1: {
+    "zh-CN": (p) => `📋 Fabric: 已积累 ${p.count} 条待审核知识${p.ageSuffix || ""}。`,
+    en: (p) => {
+      const suffix =
+        p.ageSuffix && p.ageSuffix.length > 0
+          ? p.ageSuffix
+              .replace(" / 最早一条 ", " / oldest is ")
+              .replace(" 天前", "d old")
+          : "";
+      return `📋 Fabric: ${p.count} pending knowledge entries accumulated${suffix}.`;
+    },
+    "zh-CN-hybrid": (p) => `📋 Fabric: 已积累 ${p.count} 条待审核知识${p.ageSuffix || ""}。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:652  `   是否调 /fabric-review 审核 pending/ 条目?`
+  // params: {} — protected token /fabric-review verbatim across all variants.
+  reviewCta: {
+    "zh-CN": () => "   是否调 /fabric-review 审核 pending/ 条目?",
+    en: () => "   Run /fabric-review to triage pending/ entries?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-review 审核 pending/ 条目?",
+  },
+
+  // ---- Signal C: import (underseed) ----------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:697  `📋 Fabric: 知识库节点数 ${nodeCount}/${threshold}，距 init_scan_completed ${hoursSinceInit.toFixed(1)}h。`
+  // params: { nodeCount, threshold, hoursSinceInit } — caller supplies hoursSinceInit
+  //         already toFixed(1)'d (i.e. as string "24.5") to keep all rendering pure.
+  importLine1: {
+    "zh-CN": (p) =>
+      `📋 Fabric: 知识库节点数 ${p.nodeCount}/${p.threshold}，距 init_scan_completed ${p.hoursSinceInit}h。`,
+    en: (p) =>
+      `📋 Fabric: knowledge node count ${p.nodeCount}/${p.threshold}, ${p.hoursSinceInit}h since init_scan_completed.`,
+    "zh-CN-hybrid": (p) =>
+      `📋 Fabric: 知识库节点数 ${p.nodeCount}/${p.threshold}，距 init_scan_completed ${p.hoursSinceInit}h。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:698  `   是否调 /fabric-import 从 git 历史与现有文档回灌知识?`
+  // params: {} — protected token /fabric-import verbatim across all variants.
+  importCta: {
+    "zh-CN": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    en: () => "   Run /fabric-import to backfill knowledge from git history and existing docs?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+  },
+
+  // ---- Signal D: maintenance -----------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:931  `📋 Fabric: 从未运行 lint 检查。`
+  // params: {} — substring "从未运行 lint 检查" is test-asserted (zh-CN test).
+  maintenanceLine1Never: {
+    "zh-CN": () => "📋 Fabric: 从未运行 lint 检查。",
+    en: () => "📋 Fabric: lint check has never been run.",
+    "zh-CN-hybrid": () => "📋 Fabric: 从未运行 lint 检查。",
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:932  `📋 Fabric: 已 ${days} 天未跑 lint 检查（实际 ${ageDays.toFixed(1)}d）。`
+  // params: { days, ageDays } — ageDays caller-supplied as already-toFixed(1) string.
+  // Substring "已 N 天未跑 lint" is test-asserted (zh-CN test).
+  maintenanceLine1Aged: {
+    "zh-CN": (p) => `📋 Fabric: 已 ${p.days} 天未跑 lint 检查（实际 ${p.ageDays}d）。`,
+    en: (p) => `📋 Fabric: ${p.days} days since the last lint check (actual ${p.ageDays}d).`,
+    "zh-CN-hybrid": (p) => `📋 Fabric: 已 ${p.days} 天未跑 lint 检查（实际 ${p.ageDays}d）。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:929  `   是否调 \`fabric doctor --lint\` 看看知识库健康度?`
+  // params: {} — protected token `fabric doctor --lint` (with backticks) verbatim.
+  maintenanceLine2: {
+    "zh-CN": () => "   是否调 `fabric doctor --lint` 看看知识库健康度?",
+    en: () => "   Run `fabric doctor --lint` to check knowledge-base health?",
+    "zh-CN-hybrid": () => "   是否调 `fabric doctor --lint` 看看知识库健康度?",
+  },
+
+  // ---- Broad hook: import recommendation ------------------------------------
+  // Source (zh-CN): knowledge-hint-broad.cjs:262
+  //   "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?"
+  // Note: leading two spaces are intentional (existing banner indent).
+  // params: {} — protected token /fabric-import verbatim.
+  broadImportBanner: {
+    "zh-CN": () => "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    en: () =>
+      "  📋 Fabric: knowledge base is sparse — run /fabric-import to backfill from git history and existing docs?",
+    "zh-CN-hybrid": () =>
+      "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+  },
+
+  // ---- Broad hook: meta auto-refresh breadcrumb (rc.22 Scope D T-D4) -------
+  // Surfaced ONLY when planContext() detected meta drift and rebuilt the meta
+  // in-place (server emits `auto_healed: true` in plan-context-hint payload).
+  // Single informational line — operators need a breadcrumb when meta auto-
+  // heals so a "why did revision change?" question has a paper trail.
+  //
+  // Two render shapes:
+  //   - metaAutoRefreshedBanner: full transition with prev → cur 8-char hash
+  //     prefixes. Used when both previous_revision_hash + revision_hash present.
+  //   - metaAutoRefreshedBannerGeneric: defensive fallback when the server
+  //     emitted `auto_healed: true` but did not include previous_revision_hash
+  //     (T10 noted this edge case). No hash transition shown.
+  //
+  // Note: 🔄 emoji prefix is intentional (matches the project's general "no
+  // emoji" rule's exception for explicit user request — see TASK-011 description).
+  // params: { prev, cur } — both already 8-char hex strings, caller-supplied.
+  metaAutoRefreshedBanner: {
+    "zh-CN": (p) => `  🔄 Fabric: 元数据已自动刷新(sha ${p.prev} → ${p.cur})`,
+    en: (p) => `  🔄 Fabric: meta auto-refreshed (sha ${p.prev} → ${p.cur})`,
+    "zh-CN-hybrid": (p) => `  🔄 Fabric: 元数据已自动刷新(sha ${p.prev} → ${p.cur})`,
+  },
+
+  // Generic variant — no hash transition. Used when auto_healed:true but
+  // previous_revision_hash is missing from the payload.
+  metaAutoRefreshedBannerGeneric: {
+    "zh-CN": () => "  🔄 Fabric: 元数据已自动刷新",
+    en: () => "  🔄 Fabric: meta auto-refreshed",
+    "zh-CN-hybrid": () => "  🔄 Fabric: 元数据已自动刷新",
+  },
+};
+
+/**
+ * Render a banner fragment for the requested variant.
+ *
+ * Variant resolution:
+ *   1. If STRINGS[key][variant] exists → use it.
+ *   2. Else fall back to STRINGS[key][RENDER_FALLBACK_VARIANT] ('en').
+ *   3. If key itself is unknown → returns "" (defensive; never throws).
+ *
+ * 'match-existing' is intentionally NOT in the STRINGS table so it folds
+ * down to the 'en' fallback per UX i18n Policy class 1.
+ */
+function renderBanner(key, variant, params) {
+  const entry = STRINGS[key];
+  if (!entry) return "";
+  const tmpl = entry[variant] || entry[RENDER_FALLBACK_VARIANT];
+  if (typeof tmpl !== "function") return "";
+  try {
+    return tmpl(params || {});
+  } catch {
+    // Defensive: a missing param shouldn't crash the hook.
+    return "";
+  }
+}
+
+module.exports = { readFabricLanguage, renderBanner, STRINGS };

package/templates/hooks/lib/cite-contract-reminder.cjs

@@ -0,0 +1,173 @@
+// v2.0.0-rc.24 TASK-05: L1 Stop hook soft reminder for missing cite contract.
+//
+// Reads `.fabric/agents.meta.json` to build a stable_id → knowledge_type lookup
+// map, then scans summarised assistant turns (cite_ids + cite_tags +
+// cite_commitments parallel arrays produced by lib/cite-line-parser.cjs) for
+// turns that cited a decision-class or pitfall-class id with [recalled] tag
+// but no operator commitment and no skip:<reason>.
+//
+// Emits one reminder line per offending id (deduplicated across the turn
+// summary). Non-blocking — caller writes the lines to stderr; failure to
+// load the meta file or absence of offenders means zero output.
+//
+// Reminder template (rc.24 lock B2 / L1 enforcement layer):
+//   ⚠ KB: <id> cited as [recalled] but missing contract; add → edit:<glob>
+//     or → skip:<reason> next turn
+//
+// Type filter rationale: only `decision` and `pitfall` types are contract-
+// required per rc.24 design lock B6 (idTypeMap routing). `model`,
+// `guideline`, `process` use reference-cite or LLM-judge (deferred to rc.25+)
+// and are intentionally skipped here to avoid false-positive nudges.
+//
+// agents.meta.json schema note: `description.knowledge_type` values are
+// SINGULAR (`decision`, `pitfall`, `model`, `guideline`, `process`) per
+// packages/shared/src/schemas/agents-meta.ts. The reminder filter normalises
+// any plural input defensively but the canonical contract is singular.
+//
+// Reading happens once per hook invocation (caller passes the projectRoot;
+// the lib does the fs read internally). The map is small (<200 entries in
+// typical corpora) so caching beyond the per-invocation scope is unnecessary.
+
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR = ".fabric";
+const AGENTS_META_FILE = "agents.meta.json";
+
+// Knowledge types that require contract commitments on [recalled] cites.
+// Matches the singular form persisted by `withDerivedAgentsMetaNodeDefaults`
+// in packages/shared/src/schemas/agents-meta.ts. We accept both singular
+// and plural defensively so a future schema change to plurals doesn't
+// silently break the filter.
+const CONTRACT_REQUIRED_TYPES = new Set([
+  "decision",
+  "decisions",
+  "pitfall",
+  "pitfalls",
+]);
+
+/**
+ * Build a Map<stable_id, knowledge_type> from <projectRoot>/.fabric/agents.meta.json.
+ *
+ * Never throws — missing file, malformed JSON, missing nodes key, etc. all
+ * yield an empty Map. The caller's downstream filter then becomes a no-op
+ * (no id resolves → no reminders).
+ *
+ * @param {string} projectRoot - workspace root
+ * @returns {Map<string, string>} stable_id → knowledge_type (singular)
+ */
+function readKnowledgeTypeMap(projectRoot) {
+  const out = new Map();
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) return out;
+
+  const metaPath = join(projectRoot, FABRIC_DIR, AGENTS_META_FILE);
+  if (!existsSync(metaPath)) return out;
+
+  let raw;
+  try {
+    raw = readFileSync(metaPath, "utf8");
+  } catch {
+    return out;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return out;
+  }
+
+  if (parsed === null || typeof parsed !== "object") return out;
+  const nodes = parsed.nodes;
+  if (nodes === null || typeof nodes !== "object") return out;
+
+  for (const [id, node] of Object.entries(nodes)) {
+    if (node === null || typeof node !== "object") continue;
+    const description = node.description;
+    if (description === null || typeof description !== "object") continue;
+    const kt = description.knowledge_type;
+    if (typeof kt !== "string" || kt.length === 0) continue;
+    out.set(id, kt);
+  }
+
+  return out;
+}
+
+/**
+ * Scan parsed assistant turns for cites that should have a contract but
+ * don't, returning the reminder lines to emit.
+ *
+ * Filter (all must hold for a given index i within a turn):
+ *   1. cite_tags includes "recalled" (turn-level — applies to the cited id)
+ *   2. cite_commitments[i].operators is empty AND cite_commitments[i].skip_reason is null
+ *   3. idTypeMap.get(cite_ids[i]) is in {decision, pitfall}
+ *
+ * Tag-level filter clarification: rc.20 cite_tags is parallel to ALL parsed
+ * lines (including sentinels), but for the contract-missing reminder we use
+ * the turn-level semantic — if the assistant tagged the cite as [recalled],
+ * the operator-or-skip contract applies. Per TASK-04 invariant, cite_ids and
+ * cite_commitments are parallel index-aligned arrays (length-N each).
+ *
+ * Sentinel turns (cite_ids=[], cite_tags=["none"]) contribute no offenders
+ * because the cite_ids loop has zero iterations.
+ *
+ * Offenders are deduplicated by id across the entire turn array; multiple
+ * turns citing the same id yield ONE reminder line.
+ *
+ * @param {Object} args
+ * @param {Array<{cite_ids: string[], cite_tags: string[], cite_commitments: Array<{operators: Array<unknown>, skip_reason: string|null}>}>} args.assistant_turns
+ * @param {Map<string, string>} args.idTypeMap
+ * @returns {string[]} reminder lines (empty when no offenders)
+ */
+function formatContractMissingReminders({ assistant_turns, idTypeMap }) {
+  if (!Array.isArray(assistant_turns) || assistant_turns.length === 0) return [];
+  if (!(idTypeMap instanceof Map) || idTypeMap.size === 0) return [];
+
+  const offenders = new Set();
+
+  for (const turn of assistant_turns) {
+    if (turn === null || typeof turn !== "object") continue;
+    const citeIds = Array.isArray(turn.cite_ids) ? turn.cite_ids : [];
+    const citeTags = Array.isArray(turn.cite_tags) ? turn.cite_tags : [];
+    const commitments = Array.isArray(turn.cite_commitments) ? turn.cite_commitments : [];
+
+    // Turn-level: the [recalled] tag must appear in the turn's tag set.
+    if (!citeTags.includes("recalled")) continue;
+
+    // Iterate by cite_ids.length — sentinel entries don't have ids so they
+    // contribute zero iterations even if cite_tags carries "none".
+    for (let i = 0; i < citeIds.length; i += 1) {
+      const id = citeIds[i];
+      if (typeof id !== "string" || id.length === 0) continue;
+
+      const type = idTypeMap.get(id);
+      if (!CONTRACT_REQUIRED_TYPES.has(type)) continue;
+
+      const commitment = commitments[i];
+      if (commitment === null || typeof commitment !== "object") continue;
+      const operators = Array.isArray(commitment.operators) ? commitment.operators : [];
+      const skipReason = commitment.skip_reason;
+      const hasContract = operators.length > 0 || (typeof skipReason === "string" && skipReason.length > 0);
+      if (hasContract) continue;
+
+      offenders.add(id);
+    }
+  }
+
+  if (offenders.size === 0) return [];
+
+  // Stable order: insertion order is the order ids first appeared across turns.
+  const reminders = [];
+  for (const id of offenders) {
+    reminders.push(
+      `⚠ KB: ${id} cited as [recalled] but missing contract; add \`→ edit:<glob>\` or \`→ skip:<reason>\` next turn`,
+    );
+  }
+  return reminders;
+}
+
+module.exports = {
+  readKnowledgeTypeMap,
+  formatContractMissingReminders,
+  CONTRACT_REQUIRED_TYPES,
+};

package/templates/hooks/lib/cite-line-parser.cjs

@@ -0,0 +1,158 @@
+// v2.0.0-rc.24 TASK-04: CJS twin of packages/shared/src/cite-line-parser.ts.
+//
+// Hook runtime has NO node_modules access, so the shared TS module cannot be
+// imported. This file is a hand-authored CJS mirror; behavioral parity is
+// asserted by packages/cli/__tests__/cite-line-parser-parity.test.ts which
+// runs both implementations against the same corpus and asserts identical
+// output. Any drift between this file and ../../shared/src/cite-line-parser.ts
+// MUST be reflected in BOTH files plus the parity-test corpus, otherwise the
+// parity test fails and blocks the commit.
+//
+// Why a hand-authored twin (not transpile-at-install or string-template inject)?
+//   - tsup/esbuild are CLI build-time deps, NOT install-time deps; bundling
+//     them into the install pipeline grows the user-facing footprint.
+//   - The parser is small (≤150 LOC), pure (zero deps), and rarely changes —
+//     hand-syncing is cheaper than introducing transpile machinery.
+//   - The existing `installHookLibs` pipeline auto-copies every `.cjs` under
+//     templates/hooks/lib/ to each client's hooks/lib/ dir, so this file
+//     auto-ships to cc/codex/cursor with no install pipeline change.
+//
+// Vocabulary contract (mirrored 1:1 with the TS source):
+//   - cite_tags enum: planned | recalled | chained-from | dismissed | none
+//   - operator kinds: edit | not_edit | require | forbid
+//     (source token `!edit:` → schema kind `not_edit`)
+//   - skip:<reason> captures everything after the first colon, so
+//     `skip:other:non-codifiable` yields skip_reason="other:non-codifiable".
+//   - Index contract: cite_commitments[i] ↔ cite_ids[i]. Sentinel `KB: none`
+//     contributes a "none" cite_tag only — no id, no commitment.
+
+const ID_RE = /^K[TP]-[A-Z]+-\d+$/;
+const SENTINEL_RE = /^KB:\s*none\b\s*(?:\[[^\]]*\])?\s*$/i;
+// v2.0.0-rc.27 TASK-003 (audit §2.18): multi-id citations supported via
+// comma-separated ID group. Mirrors packages/shared/src/cite-line-parser.ts.
+const FULL_RE =
+  /^KB:\s+(K[TP]-[A-Z]+-\d+(?:\s*,\s*K[TP]-[A-Z]+-\d+)*)(?:\s+\(([^)]*)\))?(?:\s+\[([^\]]+)\])?(?:\s+→\s*(.+))?\s*$/;
+const CHAINED_FROM_ID_RE = /chained-from\s+(K[TP]-[A-Z]+-\d+)/i;
+
+const ALLOWED_TAGS = new Set([
+  // v2.0.0-rc.37 NEW-1: new simplified 2-state tag set ([applied] / [dismissed]).
+  // Old 4-state tags (planned / recalled / chained-from) accepted for
+  // backward compat — they continue to parse and count toward cite-coverage
+  // so in-flight workspaces don't lose their existing audit signal.
+  "applied",
+  "dismissed",
+  // Legacy tags (rc ≤36).
+  "planned",
+  "recalled",
+  "chained-from",
+  "none",
+]);
+
+function parseTag(rawTag) {
+  if (!rawTag) return "none";
+  // Tags may carry tails like `chained-from KT-DEC-0001` or
+  // `dismissed:scope-mismatch`; head token (whitespace/colon-bounded) wins.
+  const head = rawTag.trim().split(/[\s:]+/)[0].toLowerCase();
+  return ALLOWED_TAGS.has(head) ? head : "none";
+}
+
+function parseContractTail(tail) {
+  const result = { operators: [], skip_reason: null };
+  if (!tail) return result;
+  const tokens = tail.trim().split(/\s+/).filter((t) => t.length > 0);
+  for (const token of tokens) {
+    // skip:<reason> — reason may itself contain a colon (skip:other:<text>).
+    const skipMatch = token.match(/^skip:(.+)$/i);
+    if (skipMatch) {
+      if (result.skip_reason === null) result.skip_reason = skipMatch[1];
+      continue;
+    }
+    // !edit:<target> → schema kind "not_edit".
+    const notEditMatch = token.match(/^!edit:(.+)$/i);
+    if (notEditMatch) {
+      result.operators.push({ kind: "not_edit", target: notEditMatch[1] });
+      continue;
+    }
+    const opMatch = token.match(/^(edit|require|forbid):(.+)$/i);
+    if (opMatch) {
+      result.operators.push({
+        kind: opMatch[1].toLowerCase(),
+        target: opMatch[2],
+      });
+    }
+    // Unknown token → forward-compat drop.
+  }
+  return result;
+}
+
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return null;
+  if (SENTINEL_RE.test(trimmed)) {
+    return { ids: [], tag: "none", commitment: null };
+  }
+  const fullMatch = trimmed.match(FULL_RE);
+  if (fullMatch) {
+    // v2.0.0-rc.27 TASK-003 (audit §2.18): split + revalidate each id;
+    // capture chained-from tail id when present.
+    const primaryIds = fullMatch[1]
+      .split(",")
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+    if (primaryIds.some((id) => !ID_RE.test(id))) return null;
+
+    const rawTag = fullMatch[3];
+    const tag = parseTag(rawTag);
+
+    const chainedIds = [];
+    if (rawTag) {
+      const chained = CHAINED_FROM_ID_RE.exec(rawTag);
+      if (chained && ID_RE.test(chained[1])) {
+        chainedIds.push(chained[1]);
+      }
+    }
+
+    return {
+      ids: primaryIds.concat(chainedIds),
+      tag,
+      commitment: parseContractTail(fullMatch[4]),
+    };
+  }
+  return null;
+}
+
+/**
+ * Parse one or more newline-separated `KB:` cite lines into structured arrays
+ * matching the assistant_turn_observed event-ledger fields. Tolerates
+ * whitespace, CR/LF, blank lines, interleaved prose. Never throws.
+ *
+ * v2.0.0-rc.27 TASK-003 (audit §2.18): supports multi-id citations
+ * (`KB: KT-DEC-0001, KT-PIT-0005 ...`) and surfaces `chained-from <id>`'s
+ * embedded id as an additional cite_id. cite_tags carries one tag per LINE.
+ */
+function parseCiteLine(raw) {
+  const result = { cite_ids: [], cite_tags: [], cite_commitments: [] };
+  if (typeof raw !== "string") return result;
+  for (const line of raw.split(/\r?\n/)) {
+    const parsed = parseLine(line);
+    if (!parsed) continue;
+    result.cite_tags.push(parsed.tag);
+    for (const id of parsed.ids) {
+      result.cite_ids.push(id);
+    }
+    if (parsed.commitment !== null) {
+      // v2.0.0-rc.27.1 (Codex review fix): cite_commitments MUST be index-
+      // aligned with cite_ids per the schema doc on event-ledger.ts:428.
+      // Multi-id citations share ONE parsed contract — propagate it across
+      // every id slot so downstream consumers (`doctor.ts` per-cite walk +
+      // `cite-contract-reminder.cjs`) can look up `commitments[i]` for any
+      // valid `i < cite_ids.length` without falling into an undefined slot.
+      for (let i = 0; i < parsed.ids.length; i += 1) {
+        result.cite_commitments.push(parsed.commitment);
+      }
+    }
+  }
+  return result;
+}
+
+module.exports = { parseCiteLine };