@ctxr/skill-llm-wiki 1.0.1

package/scripts/lib/quality-metric.mjs

@@ -0,0 +1,269 @@
+// quality-metric.mjs — routing_cost metric for convergence.
+//
+// Definition: given a wiki tree and a fixed query distribution
+// (query-fixture.mjs), simulate the routing procedure from
+// SKILL.md for each query. Starting at the root index.md, read its
+// frontmatter's entries[] records, compute which ones are
+// "matched" by the query, follow matched subcategory indices one
+// level deeper, and sum the file bytes of every file the routing
+// pass read (root index + matched subcategory indices + matched
+// leaves).
+//
+// Routing-substrate note. The old (literal) router matched on
+// aggregated `activation_defaults` lifted into entries[] at the
+// parent level. That substrate is gone. Parent `entries[]` now
+// carry only `id` / `file` / `type` / `focus` / `tags`, plus the
+// parent index itself has an authored `focus` / `shared_covers` /
+// `tags` block. The simulator matches entries using those
+// parent-side fields only — it does NOT peek into leaves to make
+// a descent decision.
+//
+// This is the critical property that makes nested wikis cheaper
+// than flat wikis in the simulator: if the parent's description
+// of a subcategory ("focus", shared covers, tags) doesn't match
+// the query, the subcategory's whole subtree is skipped, and
+// every leaf inside it stays unread. In the old literal-routing
+// substrate the subcategory's `activation_defaults` was the gate;
+// now it's the subcategory's authored `focus` and shared_covers.
+//
+// Per-leaf `activation` blocks on the leaves themselves are
+// ignored by the simulator. They still round-trip through
+// frontmatter and may inform Claude's judgment once a leaf is
+// already open, but for the purposes of the routing-cost metric
+// they're hidden behind the parent gate.
+//
+// The metric is:
+//
+//   routing_cost = SUM over queries of bytes_read(query) / total_leaf_bytes
+//
+// where total_leaf_bytes is the total bytes of every .md file
+// under the wiki (excluding .llmwiki / .work / index.md). Lower is
+// better. A perfectly-shaped wiki where each query activates only
+// the matching subcategory will score much lower than a flat wiki
+// where every leaf is a peer at the root and every root lookup
+// has to consider them all.
+//
+// This metric intentionally favours NESTED shapes over FLAT
+// shapes for the same leaves — a flat wiki's root index.md is
+// larger (lists all entries), and routing at the root level has
+// to read every activated leaf directly (no subcategory index
+// between). A nested wiki's root index.md is smaller (lists
+// subcategories) and routing skips past non-matching
+// subcategories without visiting their leaves. That's the
+// behaviour we want to incentivise.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "./frontmatter.mjs";
+import { REPRESENTATIVE_QUERIES } from "./query-fixture.mjs";
+
+// Compute the total bytes of every .md file under wikiRoot,
+// excluding dot-directories. Used as the denominator in the cost
+// ratio so the metric is in a comparable [0, N] range.
+export function totalLeafBytes(wikiRoot) {
+  let total = 0;
+  const stack = [wikiRoot];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!e.isFile() || !e.name.endsWith(".md")) continue;
+      try {
+        total += statSync(full).size;
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return total;
+}
+
+// Does an entry match for a query? Uses only parent-side fields
+// that travel in the parent index's `entries[]` record: `tags`
+// (authored, optional) and `focus` (always present, even if it's
+// just a placeholder). No peeking into leaves or aggregated
+// defaults — those substrates are gone.
+//
+// For subcategory entries we additionally consider the
+// subcategory's own `tags` and `shared_covers` authored in its
+// index.md, because those are the subcategory's "I am relevant
+// for queries about X" description. We read that from the
+// subcat's index.md on demand; the root index no longer carries
+// an aggregated copy.
+function entryMatches(entry, query) {
+  if (!entry) return false;
+  const qKeywords = new Set(
+    (query.activation_keywords || []).map((k) => k.toLowerCase()),
+  );
+  const qTags = new Set((query.tags || []).map((t) => t.toLowerCase()));
+  const entryTags = Array.isArray(entry.tags) ? entry.tags : [];
+  for (const t of entryTags) {
+    if (qTags.has(String(t).toLowerCase())) return true;
+  }
+  const focus = typeof entry.focus === "string" ? entry.focus.toLowerCase() : "";
+  for (const kw of qKeywords) {
+    if (focus.includes(kw)) return true;
+  }
+  return false;
+}
+
+// Does a subcategory's own authored frontmatter match for a
+// query? We read the subcat's index.md (which the router will
+// read anyway once it descends) and check its `tags`, `focus`,
+// and `shared_covers` against the query. Returns true if any
+// field matches.
+function subcatOwnMatches(parsed, query) {
+  if (!parsed || !parsed.data) return false;
+  const qKeywords = new Set(
+    (query.activation_keywords || []).map((k) => k.toLowerCase()),
+  );
+  const qTags = new Set((query.tags || []).map((t) => t.toLowerCase()));
+  const data = parsed.data;
+  const ownTags = Array.isArray(data.tags) ? data.tags : [];
+  for (const t of ownTags) {
+    if (qTags.has(String(t).toLowerCase())) return true;
+  }
+  const focus = typeof data.focus === "string" ? data.focus.toLowerCase() : "";
+  for (const kw of qKeywords) {
+    if (focus.includes(kw)) return true;
+  }
+  const covers = Array.isArray(data.shared_covers) ? data.shared_covers : [];
+  for (const c of covers) {
+    const lc = String(c).toLowerCase();
+    for (const kw of qKeywords) {
+      if (lc.includes(kw)) return true;
+    }
+  }
+  return false;
+}
+
+// Simulate routing for one query starting at `dirPath`'s index.md.
+// Returns the set of absolute file paths the router would read.
+// Bounded recursion: depth cap of 10 prevents pathological cycles.
+//
+// The walk is strictly parent-gated: a subcategory is only
+// descended into when either the parent-side entries[] record
+// matches (via `entryMatches`) OR the subcat's own authored
+// frontmatter matches (via `subcatOwnMatches` reading the
+// subcat's index.md). Leaves inside a non-matching subcat are
+// never touched. This matches the semantic routing procedure in
+// SKILL.md: Claude descends based on the parent's description of
+// the child, not on deep-probe of the child's descendants.
+function simulateQueryRouting(wikiRoot, query, dirPath = wikiRoot, depth = 0, visited = new Set()) {
+  if (depth > 10) return visited;
+  const indexPath = join(dirPath, "index.md");
+  if (!existsSync(indexPath)) return visited;
+  if (visited.has(indexPath)) return visited;
+  visited.add(indexPath);
+  let parsed;
+  try {
+    const raw = readFileSync(indexPath, "utf8");
+    parsed = parseFrontmatter(raw, indexPath);
+  } catch {
+    return visited;
+  }
+  const entries = Array.isArray(parsed.data.entries) ? parsed.data.entries : [];
+  for (const entry of entries) {
+    const file = entry.file;
+    if (!file || typeof file !== "string") continue;
+    const full = join(dirPath, file);
+    if (visited.has(full)) continue;
+    if (entry.type === "index") {
+      // First try the parent-side record (cheap, no extra I/O).
+      let shouldDescend = entryMatches(entry, query);
+      const subDir = full.endsWith("index.md") ? full.slice(0, -"index.md".length - 1) : full;
+      if (!shouldDescend) {
+        // Fallback: peek at the subcat's own authored
+        // `focus`/`tags`/`shared_covers` (parsing the index once).
+        // This matches "Claude opens the child index to read its
+        // own focus before deciding to descend" and is still a
+        // parent-gate, not a deep-probe of leaves.
+        const subIndexPath = join(subDir, "index.md");
+        if (existsSync(subIndexPath)) {
+          try {
+            const subRaw = readFileSync(subIndexPath, "utf8");
+            const subParsed = parseFrontmatter(subRaw, subIndexPath);
+            if (subcatOwnMatches(subParsed, query)) shouldDescend = true;
+          } catch {
+            /* ignore — don't descend */
+          }
+        }
+      }
+      if (!shouldDescend) continue;
+      simulateQueryRouting(wikiRoot, query, subDir, depth + 1, visited);
+    } else {
+      if (!entryMatches(entry, query)) continue;
+      visited.add(full);
+    }
+  }
+  return visited;
+}
+
+// Sum bytes of every file in a set (missing files count zero).
+function sumBytes(files) {
+  let total = 0;
+  for (const f of files) {
+    try {
+      total += statSync(f).size;
+    } catch {
+      /* ignore */
+    }
+  }
+  return total;
+}
+
+// Compute the routing_cost metric for a wiki. Returns an object:
+//
+//   { cost, per_query, total_leaf_bytes, queries_matched }
+//
+// `cost` is the primary scalar used by convergence (lower = better).
+// `per_query` is a per-query breakdown for debugging / logs.
+export function computeRoutingCost(wikiRoot, options = {}) {
+  const { queries = REPRESENTATIVE_QUERIES } = options;
+  const total = totalLeafBytes(wikiRoot);
+  if (total === 0) {
+    return { cost: 0, per_query: [], total_leaf_bytes: 0, queries_matched: 0 };
+  }
+  let costSum = 0;
+  const per = [];
+  let matched = 0;
+  for (const q of queries) {
+    const files = simulateQueryRouting(wikiRoot, q);
+    const bytes = sumBytes(files);
+    if (files.size > 0) matched++;
+    const ratio = bytes / total;
+    costSum += ratio;
+    per.push({
+      query: q.id,
+      files: files.size,
+      bytes,
+      ratio,
+    });
+  }
+  return {
+    cost: costSum,
+    per_query: per,
+    total_leaf_bytes: total,
+    queries_matched: matched,
+  };
+}
+
+// Pretty-print a metric result for commit messages / logs.
+export function formatRoutingCost(metric) {
+  return (
+    `routing_cost=${metric.cost.toFixed(4)} ` +
+    `(${metric.queries_matched}/${metric.per_query.length} queries matched, ` +
+    `total_leaf_bytes=${metric.total_leaf_bytes})`
+  );
+}

package/scripts/lib/query-fixture.mjs

@@ -0,0 +1,71 @@
+// query-fixture.mjs — a fixed, representative query distribution
+// the convergence loop uses to measure routing cost. Stored in the
+// skill (NOT in user wikis) so the metric is corpus-agnostic and
+// the same metric can be used to compare structural alternatives.
+//
+// Each query is a bag of activation keywords + tags the router
+// would see in the real skill. The metric simulates one lookup
+// pass at the wiki root: compute the activated set of entries[],
+// follow the activated subcategory index.md files one level down,
+// and sum the bytes of every file traversed (indices + leaves).
+// Lower total bytes across all queries = better structure.
+//
+// The 10 queries below exercise different operation tags commonly
+// seen in the skill's documentation: rebuild, build, extend,
+// layout-mode reasoning, history/audit, validation, join, and a
+// couple of "general how do I" questions. They deliberately span
+// the tags the guide emits so both a flat-root wiki and a nested
+// wiki will find matches.
+
+export const REPRESENTATIVE_QUERIES = Object.freeze([
+  {
+    id: "q-rebuild-basic",
+    activation_keywords: ["rebuild", "optimize", "structure"],
+    tags: ["rebuild", "operation"],
+  },
+  {
+    id: "q-build-from-source",
+    activation_keywords: ["build", "source", "ingest"],
+    tags: ["build", "operation"],
+  },
+  {
+    id: "q-extend-new-entries",
+    activation_keywords: ["extend", "add", "new", "entries"],
+    tags: ["extend", "operation"],
+  },
+  {
+    id: "q-layout-mode-reasoning",
+    activation_keywords: ["layout", "sibling", "in-place", "hosted", "mode"],
+    tags: ["layout"],
+  },
+  {
+    id: "q-history-audit",
+    activation_keywords: ["history", "log", "commit", "audit", "blame"],
+    tags: ["history", "git"],
+  },
+  {
+    id: "q-validate-fix",
+    activation_keywords: ["validate", "fix", "invariant", "broken"],
+    tags: ["validation", "fix"],
+  },
+  {
+    id: "q-join-wikis",
+    activation_keywords: ["join", "merge", "wikis"],
+    tags: ["join"],
+  },
+  {
+    id: "q-rollback-to",
+    activation_keywords: ["rollback", "restore", "previous"],
+    tags: ["rollback"],
+  },
+  {
+    id: "q-tiered-ai",
+    activation_keywords: ["tiered", "similarity", "embeddings", "claude"],
+    tags: ["tiered", "ai"],
+  },
+  {
+    id: "q-scale-large",
+    activation_keywords: ["scale", "large", "corpus", "ten", "thousand"],
+    tags: ["scale", "performance"],
+  },
+]);

package/scripts/lib/rollback.mjs

@@ -0,0 +1,95 @@
+// rollback.mjs — resolve a rollback reference to a concrete git ref,
+// verify it exists, then perform `git reset --hard` + `git clean -fd`.
+//
+// Tag namespace split (see snapshot.mjs): pre-op anchors live under
+// `refs/tags/pre-op/<id>` and final tags live under `refs/tags/op/<id>`.
+// The two namespaces exist so git's ref hierarchy doesn't collide.
+//
+// Accepted ref forms:
+//   genesis             → op/genesis          (always present after gitInit)
+//   <op-id>             → op/<op-id>          (state right after the op)
+//   pre-<op-id>         → pre-op/<op-id>      (state just before the op)
+//   HEAD, HEAD~N, etc.  → passed through verbatim to git rev-parse
+//   pre-op/...          → passed through verbatim
+//   op/...              → passed through verbatim
+
+import { gitClean, gitRefExists, gitResetHard, gitRevParse } from "./git.mjs";
+
+// Op-id / bare-ref grammar. Refs that don't look like this are
+// rejected outright so they cannot slip through to git as unintended
+// command-line flags or path-like expressions.
+const BARE_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const HEAD_REF_RE = /^HEAD(~\d+|\^\d*)?$/;
+
+export function resolveRollbackRef(raw) {
+  if (!raw || typeof raw !== "string") {
+    throw new Error("rollback reference must be a non-empty string");
+  }
+  if (raw.startsWith("-")) {
+    throw new Error(`rollback reference must not start with '-': ${raw}`);
+  }
+  if (raw === "genesis") return "op/genesis";
+  if (HEAD_REF_RE.test(raw)) return raw;
+  // Namespace-prefixed tags: accept but validate the body.
+  if (raw.startsWith("pre-op/")) {
+    const rest = raw.slice("pre-op/".length);
+    if (!BARE_REF_RE.test(rest)) {
+      throw new Error(`rollback: invalid pre-op ref body: ${raw}`);
+    }
+    return raw;
+  }
+  if (raw.startsWith("op/")) {
+    const rest = raw.slice("op/".length);
+    if (!BARE_REF_RE.test(rest)) {
+      throw new Error(`rollback: invalid op ref body: ${raw}`);
+    }
+    return raw;
+  }
+  if (raw.startsWith("pre-")) {
+    const rest = raw.slice("pre-".length);
+    if (!BARE_REF_RE.test(rest)) {
+      throw new Error(`rollback: invalid pre-<op-id> ref body: ${raw}`);
+    }
+    return `pre-op/${rest}`;
+  }
+  // Bare op-id: interpret as "state right after the op finished".
+  if (!BARE_REF_RE.test(raw)) {
+    throw new Error(`rollback: invalid op-id: ${raw}`);
+  }
+  return `op/${raw}`;
+}
+
+/**
+ * Rollback the wiki's working tree to a prior commit, destructively.
+ *
+ * ⚠ IRREVERSIBLE by itself: this function runs `git reset --hard` and
+ * `git clean -fd`, which discards any unsaved working-tree edits and
+ * removes untracked files not protected by `.gitignore` / `info/exclude`.
+ * Callers should either (a) take a fresh `preOpSnapshot` immediately
+ * before invoking this as a belt-and-braces rollback anchor, or (b)
+ * prompt the user with the current HEAD SHA so they can recover via
+ * `git reflog` on the private repo if they typed the wrong ref.
+ *
+ * `git clean -fd` omits `-x` intentionally: scratch dirs protected by
+ * the internal `.llmwiki/git/info/exclude` (namely `.work/` and
+ * `.shape/history/*\/work/`) are preserved through a rollback.
+ *
+ * @param {string} wikiRoot  Absolute path to the wiki root
+ * @param {string} rawRef    One of: "genesis", "<op-id>", "pre-<op-id>",
+ *                           "HEAD", "HEAD~N", or any git ref the private
+ *                           repo understands.
+ * @returns {{ ref: string, sha: string | null }}
+ * @throws if the resolved ref does not exist in the private repo
+ */
+export function rollbackOperation(wikiRoot, rawRef) {
+  const ref = resolveRollbackRef(rawRef);
+  if (!gitRefExists(wikiRoot, ref)) {
+    throw new Error(
+      `rollback: ref "${ref}" not found in the wiki's private git repo`,
+    );
+  }
+  const sha = gitRevParse(wikiRoot, ref);
+  gitResetHard(wikiRoot, ref);
+  gitClean(wikiRoot);
+  return { ref, sha };
+}

package/scripts/lib/shape-check.mjs

@@ -0,0 +1,172 @@
+// Shape-check: detect which rewrite operators from section 3.5 of the
+// methodology would currently apply. Non-mutating. Writes findings to
+// `<wiki>/.shape/suggestions.md` and, if they cross a threshold, sets
+// `rebuild_needed: true` on the root index.md.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, statSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { parseFrontmatter, renderFrontmatter } from "./frontmatter.mjs";
+import { listChildren, readIndex } from "./indices.mjs";
+
+const DEFAULT_THRESHOLD = 5;
+const MERGE_SIMILARITY = 0.7;
+
+export function runShapeCheck(wikiRoot, options = {}) {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  const suggestions = [];
+  const dirs = [];
+  collectDirs(wikiRoot, dirs);
+
+  for (const dir of dirs) {
+    const { leaves, subdirs } = listChildren(dir);
+
+    // LIFT: exactly one non-index entry in a non-root folder
+    if (dir !== wikiRoot && leaves.length === 1 && subdirs.length === 0) {
+      suggestions.push({
+        operator: "LIFT",
+        target: dir,
+        reason: `folder contains exactly one entry (${leaves[0].data.id}); lift it to parent`,
+      });
+    }
+
+    // MERGE: sibling pairs with high covers overlap
+    for (let i = 0; i < leaves.length; i++) {
+      for (let j = i + 1; j < leaves.length; j++) {
+        const a = leaves[i].data;
+        const b = leaves[j].data;
+        if (a.type !== b.type) continue;
+        const aCov = new Set(a.covers ?? []);
+        const bCov = new Set(b.covers ?? []);
+        if (aCov.size === 0 || bCov.size === 0) continue;
+        let intersect = 0;
+        for (const c of aCov) if (bCov.has(c)) intersect++;
+        const union = aCov.size + bCov.size - intersect;
+        if (union === 0) continue;
+        const overlap = intersect / union;
+        if (overlap >= MERGE_SIMILARITY) {
+          suggestions.push({
+            operator: "MERGE",
+            target: [leaves[i].path, leaves[j].path],
+            reason: `siblings "${a.id}" and "${b.id}" have ${Math.round(overlap * 100)}% covers overlap`,
+          });
+        }
+      }
+    }
+
+    // DESCEND: index body with authored zone above budget
+    const indexPath = join(dir, "index.md");
+    if (existsSync(indexPath)) {
+      const raw = readFileSync(indexPath, "utf8");
+      const { body } = parseFrontmatter(raw, indexPath);
+      const authored = extractAuthoredZone(body);
+      if (authored.length > 2048) {
+        suggestions.push({
+          operator: "DESCEND",
+          target: indexPath,
+          reason: `index authored zone is ${authored.length} bytes; push content to a leaf`,
+        });
+      }
+      if (authored && (/^\s*```/m.test(authored) || /^\s*- \[ \]/m.test(authored))) {
+        suggestions.push({
+          operator: "DESCEND",
+          target: indexPath,
+          reason: "index body contains leaf-style content (code fence or checklist)",
+        });
+      }
+    }
+
+    // DECOMPOSE & NEST candidates are frontmatter-heuristic-heavy; we report
+    // simpler signals here and leave semantic clustering to AI review during
+    // Rebuild.
+    for (const leaf of leaves) {
+      const covers = leaf.data.covers ?? [];
+      if (covers.length > 12) {
+        suggestions.push({
+          operator: "DECOMPOSE",
+          target: leaf.path,
+          reason: `leaf has ${covers.length} covers[] items; consider splitting by concern`,
+        });
+      }
+      if (leaf.data.nests_into && Array.isArray(leaf.data.nests_into) && leaf.data.nests_into.length > 0) {
+        suggestions.push({
+          operator: "NEST",
+          target: leaf.path,
+          reason: `leaf declares nests_into: ${leaf.data.nests_into.join(", ")}`,
+        });
+      }
+    }
+  }
+
+  // Write suggestions file and root flag.
+  writeSuggestions(wikiRoot, suggestions);
+  if (suggestions.length >= threshold) {
+    setRootRebuildFlag(wikiRoot, suggestions, true);
+  } else if (suggestions.length === 0) {
+    setRootRebuildFlag(wikiRoot, [], false);
+  }
+  return suggestions;
+}
+
+function collectDirs(dirPath, acc) {
+  if (!existsSync(dirPath)) return;
+  acc.push(dirPath);
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      if (!e.isDirectory()) continue;
+      const sub = join(dirPath, e.name);
+      if (existsSync(join(sub, "index.md"))) collectDirs(sub, acc);
+    }
+  } catch {
+    /* skip */
+  }
+}
+
+function extractAuthoredZone(body) {
+  const start = body.indexOf("<!-- BEGIN AUTHORED ORIENTATION -->");
+  const end = body.indexOf("<!-- END AUTHORED ORIENTATION -->");
+  if (start === -1 || end === -1) return "";
+  return body.slice(start + "<!-- BEGIN AUTHORED ORIENTATION -->".length, end).trim();
+}
+
+function writeSuggestions(wikiRoot, suggestions) {
+  const dir = join(wikiRoot, ".shape");
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, "suggestions.md");
+  const now = new Date().toISOString();
+  const lines = [];
+  lines.push("# Shape Suggestions");
+  lines.push("");
+  lines.push(`_Last shape-check: ${now}_`);
+  lines.push("");
+  if (suggestions.length === 0) {
+    lines.push("_No pending operator candidates._");
+    lines.push("");
+  } else {
+    lines.push(`**${suggestions.length} pending candidate(s):**`);
+    lines.push("");
+    for (const s of suggestions) {
+      const targetStr = Array.isArray(s.target) ? s.target.map((t) => relative(wikiRoot, t)).join(", ") : relative(wikiRoot, s.target);
+      lines.push(`- **${s.operator}** — \`${targetStr}\``);
+      lines.push(`  - ${s.reason}`);
+    }
+    lines.push("");
+  }
+  writeFileSync(p, lines.join("\n"), "utf8");
+}
+
+function setRootRebuildFlag(wikiRoot, suggestions, needed) {
+  const p = join(wikiRoot, "index.md");
+  if (!existsSync(p)) return;
+  const raw = readFileSync(p, "utf8");
+  const { data, body } = parseFrontmatter(raw, p);
+  data.rebuild_needed = needed;
+  data.rebuild_reasons = suggestions.slice(0, 10).map((s) => `${s.operator}: ${s.reason}`);
+  if (!data.rebuild_command) {
+    data.rebuild_command = "skill-llm-wiki rebuild <wiki> --plan";
+  }
+  const tmp = p + ".tmp";
+  writeFileSync(tmp, renderFrontmatter(data, body), "utf8");
+  renameSync(tmp, p);
+}