@fenglimg/fabric-cli 2.0.0-rc.22 → 2.0.0-rc.25

package/templates/hooks/fabric-hint.cjs

@@ -22,6 +22,39 @@ try {
 // install integration tests, not silently swallow).
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
 
+// v2.0.0-rc.24 TASK-04: shared cite-line parser (CJS twin of
+// packages/shared/src/cite-line-parser.ts, byte-shipped via installHookLibs).
+// Provides `parseCiteLine(raw)` → { cite_ids, cite_tags, cite_commitments }.
+// Hook runtime has no node_modules access; the twin is hand-synced and
+// behavior-parity-tested against the TS source.
+let citeLineParser = null;
+try {
+  citeLineParser = require("./lib/cite-line-parser.cjs");
+} catch {
+  // Helper module missing — degrade silently. parseKbLine falls back to a
+  // legacy in-file regex when the lib is unavailable (e.g. mid-upgrade where
+  // hook script lands before lib is copied). New cite_commitments output is
+  // empty in degraded mode.
+  citeLineParser = null;
+}
+
+// v2.0.0-rc.24 TASK-05: L1 enforcement layer — soft Stop hook reminder for
+// [recalled] cites of decision/pitfall types that arrived without operator
+// contract or skip:<reason>. Reads .fabric/agents.meta.json (via
+// lib/cite-contract-reminder.cjs#readKnowledgeTypeMap) to type-route cite
+// ids per B6 lock; emits one
+//   ⚠ KB: <id> cited as [recalled] but missing contract; add → edit:<glob>
+//     or → skip:<reason> next turn
+// line to stderr per offending id. Non-blocking, never throws.
+let citeContractReminder = null;
+try {
+  citeContractReminder = require("./lib/cite-contract-reminder.cjs");
+} catch {
+  // Helper module missing — soft reminder simply doesn't fire. Audit-side
+  // doctor (TASK-08) still catches contract violations at the next run.
+  citeContractReminder = null;
+}
+
 // CONSTANTS — duplicated from packages/server/src/services/_shared.ts.
 // DRY violation accepted: this hook script runs in user repos WITHOUT
 // node_modules access, so it cannot import from @fenglimg/fabric-server.
@@ -1005,93 +1038,45 @@ function tryReadStdinJson() {
 }
 
 /**
- * v2.0.0-rc.20 TASK-03: parse the raw text that follows the `KB:` prefix on
- * the first non-empty line of an assistant turn. Returns parsed cite ids and
- * the per-id tag enum vocabulary (planned/recalled/chained-from/dismissed/
- * none). Never throws; best-effort tolerant parser.
+ * v2.0.0-rc.20 TASK-03 → v2.0.0-rc.24 TASK-04: legacy shim signature for
+ * parsing the raw text that follows the `KB:` prefix on the first non-empty
+ * line of an assistant turn. As of rc.24 the implementation delegates to the
+ * shared `parseCiteLine` (inline-shipped via lib/cite-line-parser.cjs) to
+ * eliminate per-client regex drift.
  *
- * Vocabulary contract (mirrored in
- * packages/shared/src/schemas/event-ledger.ts → assistantTurnObservedEventSchema):
- *   - "none"                                → ids=[], tags=["none"]
- *   - "KP-001"                              → ids=["KP-001"], tags=[]
- *   - "KP-001, KT-DEC-0009 (review)"        → ids=["KP-001","KT-DEC-0009"], tags=["review"]
- *   - "KP-001 [recalled][chained-from KP-002]" →
- *       ids=["KP-001"], tags=["recalled","chained-from"]
- *   - "dismissed:<reason>"                  → ids=[], tags=["dismissed"]
- *       (kb_line_raw preserves the full "dismissed:<reason>" verbatim;
- *        the parsed `cite_tags` only carries the enum value "dismissed".)
+ * Contract (rc.24 strict mode — superset of rc.20):
+ *   - Sentinel `none` (incl. `[no-relevant]` / `[not-applicable]` tail)
+ *     → cite_ids=[], cite_tags=["none"], cite_commitments=[]
+ *   - `KT-DEC-0001 [planned]` → cite_ids=["KT-DEC-0001"], cite_tags=["planned"],
+ *     cite_commitments=[{operators:[], skip_reason:null}]
+ *   - `KT-DEC-0001 [recalled] → edit:foo.ts` → cite_commitments=[{operators:
+ *     [{kind:"edit", target:"foo.ts"}], skip_reason:null}]
+ *   - `KT-DEC-0001 [recalled] → skip:sequencing` → cite_commitments=[{operators:
+ *     [], skip_reason:"sequencing"}]
+ *   - Id form is now strict `K[TP]-[A-Z]+-\d+` (rc.20 lax form `KP-001`
+ *     without letter-prefix is rejected — see TASK-03 schema).
  *
- * Tags are filtered to the Zod enum set
- * { planned, recalled, chained-from, dismissed, none } before being returned —
- * arbitrary parenthetical/bracket text outside the enum is dropped (silently)
- * so the emitted event always round-trips through the schema.
+ * Argument is the post-`KB:` substring (matches the rc.20 call site). Returns
+ * { cite_ids, cite_tags, cite_commitments }; cite_commitments was added in
+ * rc.24 and is always present (empty array when no cite-line found).
+ *
+ * Never throws.
  */
 function parseKbLine(raw) {
-  const result = { cite_ids: [], cite_tags: [] };
-  if (typeof raw !== "string") return result;
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) return result;
-
-  // dismissed:<reason> → tag="dismissed", no ids.
-  if (/^dismissed:/i.test(trimmed)) {
-    result.cite_tags.push("dismissed");
-    return result;
+  // Compose the full `KB: <raw>` line because the shared parser anchors on
+  // the `KB:` prefix. Handles the legacy `none` / `<sentinel>` inputs naturally
+  // because parseCiteLine's SENTINEL_RE matches the composed line.
+  if (typeof raw !== "string") {
+    return { cite_ids: [], cite_tags: [], cite_commitments: [] };
   }
-  // bare "none" → tag="none".
-  if (/^none$/i.test(trimmed)) {
-    result.cite_tags.push("none");
-    return result;
+  const composed = `KB: ${raw}`;
+  if (citeLineParser && typeof citeLineParser.parseCiteLine === "function") {
+    return citeLineParser.parseCiteLine(composed);
   }
-
-  // Allowed tag enum (matches assistantTurnObservedEventSchema.cite_tags z.enum).
-  const ALLOWED_TAGS = new Set(["planned", "recalled", "chained-from", "dismissed", "none"]);
-  const tagSet = new Set();
-
-  // Extract bracketed tags: `[recalled]`, `[chained-from KP-002]`, etc.
-  // We keep only the leading enum token (split on whitespace) so trailing
-  // ref-ids inside the bracket are discarded — they're not part of the tag
-  // vocabulary.
-  const bracketRegex = /\[([^\]]+)\]/g;
-  let bracketMatch;
-  let stripped = trimmed;
-  while ((bracketMatch = bracketRegex.exec(trimmed)) !== null) {
-    const inner = bracketMatch[1].trim();
-    if (inner.length === 0) continue;
-    const head = inner.split(/\s+/)[0].toLowerCase();
-    if (ALLOWED_TAGS.has(head)) tagSet.add(head);
-  }
-  stripped = stripped.replace(bracketRegex, " ");
-
-  // Extract parenthetical tags: `(review)`, `(planned)`, etc. Only enum
-  // members are retained.
-  const parenRegex = /\(([^)]+)\)/g;
-  let parenMatch;
-  while ((parenMatch = parenRegex.exec(trimmed)) !== null) {
-    const inner = parenMatch[1].trim().toLowerCase();
-    if (inner.length === 0) continue;
-    if (ALLOWED_TAGS.has(inner)) tagSet.add(inner);
-  }
-  stripped = stripped.replace(parenRegex, " ");
-
-  // Remaining content: comma-separated ids, possibly with stray whitespace.
-  // We split on comma, trim, and keep tokens that look like ref-ids
-  // (uppercase letter prefix). This filters out leftover english words and
-  // is permissive enough to allow custom id schemes (KP-, KT-, KD-, etc.).
-  const parts = stripped.split(",");
-  for (const partRaw of parts) {
-    const part = partRaw.trim();
-    if (part.length === 0) continue;
-    // Take the leading token (whitespace-bounded) so "KT-DEC-0009 garbage"
-    // still yields "KT-DEC-0009".
-    const token = part.split(/\s+/)[0];
-    if (/^[A-Z][A-Z0-9-]+$/.test(token)) {
-      result.cite_ids.push(token);
-    }
-  }
-
-  // Materialise tagSet → array (preserves insertion order via Set semantics).
-  for (const t of tagSet) result.cite_tags.push(t);
-  return result;
+  // Degraded fallback: lib missing (e.g. partial install). Emit empty result
+  // so downstream consumers see the cite-line as unobservable rather than
+  // mis-parsed. The Stop-hook contract is best-effort, never blocking.
+  return { cite_ids: [], cite_tags: [], cite_commitments: [] };
 }
 
 /**
@@ -1186,6 +1171,13 @@ function extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload) {
           kb_line_raw: turn.kb_line_raw,
           cite_ids: Array.isArray(turn.cite_ids) ? turn.cite_ids : [],
           cite_tags: Array.isArray(turn.cite_tags) ? turn.cite_tags : [],
+          // rc.24 TASK-04: cite_commitments parallel array (assistantTurn
+          // ObservedEventSchema gained this slot in rc.24 TASK-01). Empty
+          // array for legacy turns or when the parser lib is unavailable —
+          // the schema defaults `.default([])` so omitting it would also be
+          // valid, but emitting an explicit `[]` keeps the on-disk shape
+          // uniform across rc.24+ events.
+          cite_commitments: Array.isArray(turn.cite_commitments) ? turn.cite_commitments : [],
           turn_id: `${sessionId}-${turn.envelope_index}`,
           envelope_index: turn.envelope_index,
           timestamp: new Date().toISOString(),
@@ -1280,6 +1272,11 @@ function summarizeTranscript(transcriptPath) {
       let kbLineRaw = null;
       let citeIds = [];
       let citeTags = [];
+      // rc.24 TASK-04: parallel `cite_commitments` array, populated by the
+      // shared cite-line parser. One entry per non-sentinel cite (index-aligned
+      // with cite_ids). Sentinel `KB: none` contributes a `cite_tags=["none"]`
+      // entry but no commitment — matches the parseCiteLine index contract.
+      let citeCommitments = [];
       if (typeof firstText === "string" && firstText.length > 0) {
         // First non-empty line.
         const linesOfText = firstText.split(/\r?\n/);
@@ -1291,19 +1288,23 @@ function summarizeTranscript(transcriptPath) {
           }
         }
         if (firstNonEmpty.length > 0) {
-          // KB: none (case-insensitive on the literal `none`).
-          const noneMatch = firstNonEmpty.match(/^KB:\s*none\s*$/i);
-          const kbMatch = firstNonEmpty.match(/^KB:\s+(.+)$/);
-          if (noneMatch) {
+          // rc.24 TASK-04: route the FULL `KB: ...` line to the shared parser.
+          // parseCiteLine handles sentinels (`KB: none [<reason>]`) AND full
+          // cite form including contract tail (`KB: KT-DEC-0001 [recalled] →
+          // edit:foo.ts`) uniformly. The sentinel's `[<reason>]` tail stays in
+          // `kb_line_raw` for doctor's downstream histogram parse; cite_tags
+          // still emits the bare `none` token (schema enum-bound).
+          if (/^KB:\s*/i.test(firstNonEmpty)) {
             kbLineRaw = firstNonEmpty;
-            const parsed = parseKbLine("none");
-            citeIds = parsed.cite_ids;
-            citeTags = parsed.cite_tags;
-          } else if (kbMatch) {
-            kbLineRaw = firstNonEmpty;
-            const parsed = parseKbLine(kbMatch[1]);
-            citeIds = parsed.cite_ids;
-            citeTags = parsed.cite_tags;
+            if (citeLineParser && typeof citeLineParser.parseCiteLine === "function") {
+              const parsed = citeLineParser.parseCiteLine(firstNonEmpty);
+              citeIds = parsed.cite_ids;
+              citeTags = parsed.cite_tags;
+              citeCommitments = parsed.cite_commitments;
+            }
+            // Degraded mode (lib missing) → keep kbLineRaw but emit empty
+            // arrays; doctor downstream treats this as "turn observed, parse
+            // unavailable" without crashing.
           }
         }
       }
@@ -1312,6 +1313,7 @@ function summarizeTranscript(transcriptPath) {
         kb_line_raw: kbLineRaw,
         cite_ids: citeIds,
         cite_tags: citeTags,
+        cite_commitments: citeCommitments,
       });
     }
 
@@ -1356,6 +1358,50 @@ function summarizeTranscript(transcriptPath) {
   return out;
 }
 
+/**
+ * v2.0.0-rc.24 TASK-05: emit soft L1 reminder to stderr when assistant turns
+ * cited a decision/pitfall id with [recalled] but no operator contract and no
+ * skip:<reason>. Reads agents.meta.json once per invocation; aggregated per
+ * turn (one line per offending id). Non-blocking — never throws, always
+ * returns the array of emitted reminder strings (for unit tests + callers
+ * that want to observe what was written).
+ *
+ * The reminder writes go to stderr (the hook contract: stdout is structured
+ * banner JSON consumed by the harness; stderr is free-text system message
+ * that surfaces back to the model on the next turn in cc / codex / cursor).
+ */
+function emitCiteContractRemindersBestEffort(cwd, stdinPayload, stderr) {
+  if (citeContractReminder === null) return [];
+  if (stdinPayload === null || typeof stdinPayload !== "object") return [];
+  try {
+    const transcript = summarizeTranscript(stdinPayload.transcript_path);
+    const turns = transcript.assistant_turns;
+    if (!Array.isArray(turns) || turns.length === 0) return [];
+
+    const idTypeMap = citeContractReminder.readKnowledgeTypeMap(cwd);
+    if (!(idTypeMap instanceof Map) || idTypeMap.size === 0) return [];
+
+    const reminders = citeContractReminder.formatContractMissingReminders({
+      assistant_turns: turns,
+      idTypeMap,
+    });
+    if (!Array.isArray(reminders) || reminders.length === 0) return [];
+
+    const sink = stderr || process.stderr;
+    for (const line of reminders) {
+      try {
+        sink.write(line + "\n");
+      } catch {
+        // Sink write failure must not abort emission of remaining reminders.
+      }
+    }
+    return reminders;
+  } catch {
+    // Outer guard — never throw. Hook continues silently.
+    return [];
+  }
+}
+
 /**
  * v2.0.0-rc.7 T5: writeSessionDigestBestEffort — non-blocking digest fan-out.
  * Called from main() before the existing decide() flow. Failure is silently
@@ -1409,6 +1455,16 @@ function main(env, stdio) {
     // the hook's other I/O).
     extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload);
 
+    // v2.0.0-rc.24 TASK-05: L1 soft reminder layer. Surfaces ⚠ KB:<id> lines
+    // to stderr when decision/pitfall cites arrived with [recalled] tag but
+    // empty contract. Non-blocking, never throws; doctor (TASK-08) catches
+    // any contract violation the model ignored.
+    emitCiteContractRemindersBestEffort(
+      cwd,
+      stdinPayload,
+      stdio && stdio.stderr,
+    );
+
     const events = readLedger(cwd);
     let pendingStats;
     try {
@@ -1622,6 +1678,10 @@ module.exports = {
   parseKbLine,
   detectClient,
   extractAndWriteAssistantTurnsBestEffort,
+  // v2.0.0-rc.24 TASK-05: L1 soft reminder helpers (exported for unit testing
+  // of the contract-missing emission contract). The lib module itself is
+  // also exported indirectly via the reminder helper.
+  emitCiteContractRemindersBestEffort,
   CONSTANTS: {
     FABRIC_DIR,
     EVENT_LEDGER_FILE,

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,118 @@
+// 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;
+const FULL_RE =
+  /^KB:\s+(K[TP]-[A-Z]+-\d+)(?:\s+\(([^)]*)\))?(?:\s+\[([^\]]+)\])?(?:\s+→\s*(.+))?\s*$/;
+
+const ALLOWED_TAGS = new Set([
+  "planned",
+  "recalled",
+  "chained-from",
+  "dismissed",
+  "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 { id: null, tag: "none", commitment: null };
+  }
+  const fullMatch = trimmed.match(FULL_RE);
+  if (fullMatch) {
+    const id = fullMatch[1];
+    if (!ID_RE.test(id)) return null;
+    return {
+      id,
+      tag: parseTag(fullMatch[3]),
+      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.
+ */
+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);
+    if (parsed.id !== null) result.cite_ids.push(parsed.id);
+    if (parsed.commitment !== null) {
+      result.cite_commitments.push(parsed.commitment);
+    }
+  }
+  return result;
+}
+
+module.exports = { parseCiteLine };