@ctxr/skill-llm-wiki 1.0.1

package/scripts/lib/decision-log.mjs

@@ -0,0 +1,343 @@
+// decision-log.mjs — append-only audit trail for tiered-AI decisions.
+//
+// Every non-trivial similarity / operator decision records:
+//
+//   { op_id, operator, sources[], tier_used, similarity,
+//     confidence_band, decision, reason }
+//
+// Stored at `<wiki>/.llmwiki/decisions.yaml`. Same hand-rolled
+// deterministic YAML emitter/parser pattern as history.mjs — no
+// external dep. Atomic append via temp-file + rename.
+//
+// Claude-at-session-time reads this log when a user asks "why was
+// this merged?" so the audit trail has to survive across operations
+// unchanged. The log is intentionally NOT reset on rollback — if an
+// op's decisions are a matter of historical record, they remain
+// queryable even after the op is reset.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export function decisionLogPath(wikiRoot) {
+  return join(wikiRoot, ".llmwiki", "decisions.yaml");
+}
+
+const REQUIRED_FIELDS = [
+  "op_id",
+  "operator",
+  "sources",
+  "tier_used",
+  "similarity",
+  "decision",
+];
+
+function validate(entry) {
+  if (!entry || typeof entry !== "object") {
+    throw new Error("decision-log: entry must be an object");
+  }
+  for (const f of REQUIRED_FIELDS) {
+    if (!(f in entry)) {
+      throw new Error(`decision-log: entry missing required field "${f}"`);
+    }
+  }
+  if (!Array.isArray(entry.sources)) {
+    throw new Error("decision-log: sources must be an array of strings");
+  }
+  // `Number.isFinite` rejects NaN, Infinity, and non-numbers. That's
+  // exactly what we want: the audit log has no place for an
+  // Infinity similarity score (the emitter would serialise it as
+  // the string "Infinity" and the parser would read it back as a
+  // string, silently corrupting the type).
+  if (!Number.isFinite(entry.similarity)) {
+    throw new Error(
+      "decision-log: similarity must be a finite number (got " +
+        `${entry.similarity})`,
+    );
+  }
+  if (typeof entry.tier_used !== "number" || !Number.isInteger(entry.tier_used)) {
+    throw new Error("decision-log: tier_used must be an integer");
+  }
+}
+
+// Quote any string that could be misread as YAML (same rules as
+// history.mjs). We intentionally keep the scalar shape identical
+// to the op-log's so a future consolidation is mechanical.
+function needsQuoting(value) {
+  if (value === "") return true;
+  if (/[:#{}\[\],&*!|>'"`\n\r\t]/.test(value)) return true;
+  if (/^[- ?]/.test(value)) return true;
+  if (/^-?\d+$/.test(value)) return true;
+  if (value === "true" || value === "false" || value === "null") return true;
+  return false;
+}
+
+function escapeQuoted(value) {
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i);
+    if (c < 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d) {
+      throw new Error(
+        `decision-log: control character U+${c.toString(16).padStart(4, "0")} is not round-trip-safe`,
+      );
+    }
+  }
+  let out = '"';
+  for (const ch of value) {
+    switch (ch) {
+      case "\\": out += "\\\\"; break;
+      case '"': out += '\\"'; break;
+      case "\n": out += "\\n"; break;
+      case "\r": out += "\\r"; break;
+      case "\t": out += "\\t"; break;
+      default: out += ch;
+    }
+  }
+  return out + '"';
+}
+
+function emitScalar(value) {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  if (typeof value === "string") {
+    if (needsQuoting(value)) return escapeQuoted(value);
+    return value;
+  }
+  throw new Error(
+    `decision-log: unsupported scalar type ${typeof value}`,
+  );
+}
+
+function emitEntry(entry) {
+  const lines = [];
+  lines.push("- op_id: " + emitScalar(entry.op_id));
+  lines.push("  operator: " + emitScalar(entry.operator));
+  lines.push("  sources:");
+  for (const s of entry.sources) {
+    lines.push("    - " + emitScalar(s));
+  }
+  lines.push("  tier_used: " + emitScalar(entry.tier_used));
+  lines.push("  similarity: " + emitScalar(entry.similarity));
+  lines.push(
+    "  confidence_band: " + emitScalar(entry.confidence_band ?? null),
+  );
+  lines.push("  decision: " + emitScalar(entry.decision));
+  lines.push("  reason: " + emitScalar(entry.reason ?? null));
+  return lines.join("\n");
+}
+
+// Append an entry atomically.
+export function appendDecision(wikiRoot, entry) {
+  validate(entry);
+  const path = decisionLogPath(wikiRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const block = emitEntry(entry) + "\n";
+  let payload;
+  if (!existsSync(path)) {
+    payload =
+      "# skill-llm-wiki tiered-AI decision log (append-only)\n" +
+      "version: 1\n" +
+      "entries:\n" +
+      block;
+  } else {
+    const existing = readFileSync(path, "utf8");
+    const prefix = existing.endsWith("\n") ? existing : existing + "\n";
+    payload = prefix + block;
+  }
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, payload, "utf8");
+  renameSync(tmp, path);
+}
+
+// Convenience helper for cluster-NEST outcomes. The convergence
+// loop calls this for every math-only proposal (with its
+// Tier 2 gate decision) and for every Tier-2-proposed cluster
+// (with decision="tier2-approved" or "rejected-by-metric"). The
+// entry lands in the same entries[] list as pairwise decisions
+// so the audit trail for one op is queryable as a single stream.
+//
+// Schema translation:
+//
+//   op_id, operator="NEST"                — as-is
+//   sources                               — leaf ids in the cluster
+//   tier_used                             — 2 (every NEST decision
+//                                           touches Tier 2 either
+//                                           via propose_structure
+//                                           or nest_decision)
+//   similarity                            — average_affinity
+//   confidence_band                       — one of:
+//                                           "tier2-proposed",
+//                                           "math-gated",
+//                                           "empty-partition",
+//                                           "rejected-by-metric",
+//                                           "rejected-by-gate"
+//   decision                              — one of:
+//                                           "applied",
+//                                           "rejected-by-metric",
+//                                           "rejected-by-gate",
+//                                           "rejected-stale",
+//                                           "slug-renamed",
+//                                           "pending-tier2"
+//   reason                                — free text
+//
+// Coercion: average_affinity may be undefined for Tier-2-proposed
+// clusters; we coerce to 0 so the finite-number validator does
+// not reject the entry.
+export function appendNestDecision(wikiRoot, entry) {
+  const similarity =
+    Number.isFinite(entry.similarity)
+      ? entry.similarity
+      : (Number.isFinite(entry.average_affinity) ? entry.average_affinity : 0);
+  appendDecision(wikiRoot, {
+    op_id: entry.op_id,
+    operator: "NEST",
+    sources: Array.isArray(entry.sources) ? entry.sources : [],
+    tier_used: 2,
+    similarity,
+    confidence_band: entry.confidence_band ?? null,
+    decision: entry.decision,
+    reason: entry.reason ?? null,
+  });
+}
+
+// Append the per-iteration metric trajectory for an op. Writes
+// one entry per trajectory point with operator="METRIC_TRAJECTORY"
+// so readers can recover the full cost curve for each op by
+// filtering the entries[] list. `trajectory` is the
+// metric_trajectory array produced by runConvergence: an array of
+// `{ iteration, cost, event }` records. Writes even a single-
+// point baseline trajectory so the log carries evidence that the
+// convergence loop ran (rather than being silently skipped).
+export function appendMetricTrajectory(wikiRoot, opId, trajectory) {
+  if (!Array.isArray(trajectory)) return;
+  for (const point of trajectory) {
+    const cost = Number.isFinite(point.cost) ? point.cost : 0;
+    const iteration = Number.isInteger(point.iteration) ? point.iteration : 0;
+    appendDecision(wikiRoot, {
+      op_id: opId,
+      operator: "METRIC_TRAJECTORY",
+      sources: [`iter-${iteration}`],
+      tier_used: 0,
+      similarity: cost,
+      confidence_band: point.event ?? "unknown",
+      decision: "measured",
+      reason: point.reason ?? null,
+    });
+  }
+}
+
+// Lightweight reader — we parse only what we need for tests and the
+// `skill-llm-wiki history` subcommand. Errors out loudly on any line
+// the parser doesn't recognise.
+export function readDecisions(wikiRoot) {
+  const path = decisionLogPath(wikiRoot);
+  if (!existsSync(path)) return [];
+  const raw = readFileSync(path, "utf8");
+  // Strip comments and blank lines; reject unknown headers.
+  const lines = raw
+    .split(/\r?\n/)
+    .filter((l) => l.length > 0 && !/^\s*#/.test(l));
+  const out = [];
+  let i = 0;
+  // Header: version + entries:
+  if (i < lines.length && lines[i].startsWith("version:")) i++;
+  if (i < lines.length && lines[i].trim() === "entries:") i++;
+  let current = null;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.startsWith("- op_id:")) {
+      if (current) out.push(current);
+      current = { op_id: parseValue(line.slice("- op_id:".length).trim()), sources: [] };
+      i++;
+      continue;
+    }
+    if (!current) {
+      throw new Error(`decision-log parser: stray line at ${i + 1}: ${line}`);
+    }
+    const listItem = /^    - (.*)$/.exec(line);
+    if (listItem) {
+      current.sources.push(parseValue(listItem[1]));
+      i++;
+      continue;
+    }
+    const kv = /^  (\w+):\s*(.*)$/.exec(line);
+    if (!kv) {
+      throw new Error(
+        `decision-log parser: unrecognised line at ${i + 1}: ${line}`,
+      );
+    }
+    const [, key, rest] = kv;
+    if (key === "sources") {
+      // `sources:` alone introduces the list items; items start with `    - `.
+      current.sources = [];
+      i++;
+      continue;
+    }
+    current[key] = parseValue(rest);
+    i++;
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+function unescapeQuoted(body) {
+  let out = "";
+  for (let i = 0; i < body.length; i++) {
+    if (body[i] === "\\" && i + 1 < body.length) {
+      const next = body[i + 1];
+      switch (next) {
+        case "\\": out += "\\"; break;
+        case '"': out += '"'; break;
+        case "n": out += "\n"; break;
+        case "r": out += "\r"; break;
+        case "t": out += "\t"; break;
+        default: out += next;
+      }
+      i++;
+    } else {
+      out += body[i];
+    }
+  }
+  return out;
+}
+
+// Scientific-notation friendly number regex. Matches `0.5`, `1e-10`,
+// `-3.14`, `42`, `-5`. Does NOT match `Infinity`, `NaN`, or
+// hexadecimal — those are either forbidden by the validator or
+// expressible as unambiguous strings.
+const NUMBER_RE = /^-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?$/;
+
+function parseValue(raw) {
+  if (raw === "null" || raw === "") return null;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+$/.test(raw)) {
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n)) {
+      throw new Error(
+        `decision-log parser: integer ${raw} is not a safe integer`,
+      );
+    }
+    return n;
+  }
+  if (NUMBER_RE.test(raw)) {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+      throw new Error(
+        `decision-log parser: non-finite numeric value ${raw}`,
+      );
+    }
+    return n;
+  }
+  if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+    return unescapeQuoted(raw.slice(1, -1));
+  }
+  if (raw.startsWith('"') !== raw.endsWith('"')) {
+    throw new Error(`decision-log parser: unbalanced quote in: ${raw}`);
+  }
+  return raw;
+}

package/scripts/lib/draft.mjs

@@ -0,0 +1,158 @@
+// Draft frontmatter: deterministic extraction only.
+//
+// This is the script-side of the script-first + AI-fallback pipeline
+// documented in methodology §9.6. It handles the "structured source" case
+// where frontmatter can be derived mechanically from file metadata:
+//   - id from filename
+//   - focus from title or lead paragraph
+//   - covers[] from H2 sections or bulleted items in the lead
+//   - tags[] from filename prefixes or directory hints
+//   - activation from file_glob inferred from the source path
+//
+// When the source file ALREADY carries a frontmatter block (parsed at
+// ingest time via gray-matter and stashed as
+// `candidate.authored_frontmatter`), each AUTHORED_LEAF_FIELD is
+// preferred over the heuristic — the drafter only fills gaps. This is
+// what preserves `activation`, `covers`, `tags`, `focus`, `domains`,
+// `shared_covers`, `aliases`, and friends when a hand-tuned corpus is
+// re-built.
+//
+// Anything that needs semantic understanding (prose-heavy draft, ambiguous
+// classification, cover synthesis from narrative) is left for Claude to
+// handle inside its own execution context when running this skill. The
+// `needs_ai` flag on the returned draft tells the caller which entries
+// need AI review.
+
+// Fields we copy straight from the source frontmatter when the author
+// supplied them. Fields NOT in this list (id / type / depth_role /
+// parents / source) are always re-derived because their authoritative
+// source is the target-tree position, not the original source file.
+const AUTHORED_LEAF_FIELDS = [
+  "focus",
+  "covers",
+  "tags",
+  "domains",
+  "aliases",
+  "activation",
+  "shared_covers",
+  "overlay_targets",
+  "links",
+];
+
+export function draftLeafFrontmatter(candidate, { categoryPath } = {}) {
+  const authored = candidate.authored_frontmatter || {};
+  const hasAuthored = candidate.has_authored_frontmatter === true;
+
+  // Heuristic baseline — used when the author didn't supply a field.
+  const draftedCovers = extractCovers(candidate);
+  const draftedFocus = candidate.title || candidate.id;
+  const draftedTags = inferTags(candidate);
+
+  const data = {
+    id: candidate.id,
+    type: "primary",
+    depth_role: "leaf",
+    // Priority: authored > drafted > default. `pickAuthored` only
+    // returns the authored value when it is non-empty (non-null,
+    // non-undefined, and — for arrays — non-empty).
+    focus: pickAuthored(authored.focus, draftedFocus),
+    covers: pickAuthored(authored.covers, draftedCovers),
+    // `parents` is authoritative from the source when supplied. The
+    // hand-authored convention is a list of index.md paths relative
+    // to the leaf's own directory (`index.md` for the same dir,
+    // `../index.md` for one up). Heuristic fallback builds the same
+    // relative form from the category path.
+    parents: pickAuthored(authored.parents, ["index.md"]),
+    tags: pickAuthored(authored.tags, draftedTags),
+    source: {
+      origin: "file",
+      path: candidate.source_path,
+      hash: candidate.hash,
+    },
+  };
+
+  // Forward the remaining AUTHORED_LEAF_FIELDS verbatim. These have no
+  // heuristic analogue — when the author supplied them, we keep them;
+  // otherwise we omit the field entirely so the output stays compact.
+  if (hasAuthored) {
+    for (const field of AUTHORED_LEAF_FIELDS) {
+      if (field === "focus" || field === "covers" || field === "tags") continue;
+      if (authored[field] !== undefined && authored[field] !== null) {
+        data[field] = authored[field];
+      }
+    }
+  }
+
+  const confidence = scoreConfidence(data, candidate);
+  return { data, confidence, needs_ai: confidence < 0.6 };
+}
+
+function pickAuthored(authoredVal, fallback) {
+  if (authoredVal === undefined || authoredVal === null) return fallback;
+  if (Array.isArray(authoredVal)) {
+    return authoredVal.length > 0 ? authoredVal : fallback;
+  }
+  if (typeof authoredVal === "string") {
+    return authoredVal.trim() !== "" ? authoredVal : fallback;
+  }
+  return authoredVal;
+}
+
+function extractCovers(candidate) {
+  const out = [];
+  // H2 headings become the primary covers candidates.
+  for (const h of candidate.headings) {
+    if (h.level === 2) out.push(h.text);
+    if (out.length >= 10) break;
+  }
+  if (out.length === 0) {
+    // Fall back to splitting the lead on sentence boundaries.
+    const lead = candidate.lead || "";
+    const sentences = lead.split(/(?<=[.!?])\s+/).filter((s) => s.length > 10);
+    for (const s of sentences) {
+      out.push(s.slice(0, 120));
+      if (out.length >= 5) break;
+    }
+  }
+  return out.slice(0, 12);
+}
+
+function inferTags(candidate) {
+  const tags = new Set();
+  // Directory components as tag hints.
+  const parts = candidate.source_path.split(/[\/\\]/);
+  for (const part of parts.slice(0, -1)) {
+    if (part && part !== "." && !/^\d+$/.test(part)) {
+      tags.add(part.toLowerCase().replace(/[^a-z0-9-]+/g, "-"));
+    }
+  }
+  // Extension hint.
+  if (candidate.ext === ".md") tags.add("markdown");
+  return [...tags].slice(0, 8);
+}
+
+function scoreConfidence(draft, candidate) {
+  let score = 0;
+  if (draft.focus && draft.focus !== candidate.id) score += 0.3;
+  if (draft.covers.length >= 3) score += 0.4;
+  else if (draft.covers.length >= 1) score += 0.2;
+  if (candidate.headings.filter((h) => h.level === 2).length >= 2) score += 0.2;
+  if (candidate.size > 200) score += 0.1;
+  return Math.min(1, score);
+}
+
+// Quick classification by directory prefix. Script-first classifier.
+//
+// When the source file lives at the source root (no directory
+// component), the candidate is placed at the TARGET root — not under a
+// synthetic `general/` bucket. This is what keeps a flat authored
+// guide flat in the output: 17 top-level leaves stay at the wiki root
+// instead of being nested under `general/`.
+//
+// Subdirectories in the source are preserved as top-level categories
+// in the target (e.g. `operations/build.md` → `operations/build.md`).
+export function draftCategory(candidate) {
+  const parts = candidate.source_path.split(/[\/\\]/).filter(Boolean);
+  if (parts.length <= 1) return "";
+  return parts[0].toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+}