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

package/templates/hooks/configs/cursor-hooks.json

@@ -1,30 +0,0 @@
-{
-  "version": 1,
-  "hooks": {
-    "stop": [
-      { "command": ".cursor/hooks/fabric-hint.cjs" }
-    ],
-    "sessionStart": [
-      { "command": ".cursor/hooks/knowledge-hint-broad.cjs" }
-    ],
-    "preToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "command": ".cursor/hooks/knowledge-hint-narrow.cjs"
-      },
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "command": ".cursor/hooks/cite-policy-evict.cjs"
-      }
-    ],
-    "postToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "command": ".cursor/hooks/post-tooluse-mutation.cjs"
-      }
-    ],
-    "sessionEnd": [
-      { "command": ".cursor/hooks/session-end-marker.cjs" }
-    ]
-  }
-}

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

@@ -1,179 +0,0 @@
-// 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 [applied] tag
-// but no operator commitment and no skip:<reason>. (v2.1.0-rc.1 ADJ-P4-1:
-// legacy [recalled] is remapped to [applied] by the parser upstream.)
-//
-// 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 [applied] 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 [applied] 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 "applied" (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}
- *
- * v2.1.0-rc.1 (ADJ-P4-1, full remap): the gate is the rc.37 NEW-1 `applied`
- * tag. Legacy [recalled] cites are remapped to [applied] by the parser before
- * they reach here, so gating on "applied" covers both old and new authoring.
- *
- * 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 [applied],
- * 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 [applied] tag must appear in the turn's tag set
-    // (v2.1.0-rc.1 ADJ-P4-1: legacy [recalled] is remapped to [applied]).
-    if (!citeTags.includes("applied")) 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 [applied] but missing contract; add \`→ edit:<glob>\` or \`→ skip:<reason>\` next turn`,
-    );
-  }
-  return reminders;
-}
-
-module.exports = {
-  readKnowledgeTypeMap,
-  formatContractMissingReminders,
-  CONTRACT_REQUIRED_TYPES,
-};

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

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