@ctxr/skill-llm-wiki 1.0.1 → 1.1.0

package/scripts/lib/templates.mjs

@@ -0,0 +1,78 @@
+// templates.mjs — discovery + metadata for the shipped layout
+// templates under <SKILL_ROOT>/templates/*.llmwiki.layout.yaml.
+//
+// Feature 1 (this module) exposes the list and paths. Feature 2
+// (init) uses them to seed a consumer's topic wiki with one command.
+// Consumers can also copy templates by hand via `skill-llm-wiki
+// where --json` + templates_dir.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SKILL_ROOT } from "./where.mjs";
+
+const TEMPLATES_DIR = join(SKILL_ROOT, "templates");
+const TEMPLATE_SUFFIX = ".llmwiki.layout.yaml";
+
+// Metadata layer ON TOP of the template files. Keeps the per-template
+// YAML focused on the layout contract itself while the "what kind of
+// topic am I?" mapping lives in code. A template whose name isn't
+// listed here is still usable, just not recommended via the CLI's
+// `--kind` short-hand.
+const TEMPLATE_META = {
+  reports: { kind: "dated", description: "Generated reports filed by day." },
+  sessions: { kind: "dated", description: "Daily session logs filed by day." },
+  regressions: { kind: "dated", description: "Regression notes filed by month." },
+  plans: { kind: "dated", description: "Plans filed by day, with subject subfolders for families." },
+  runbooks: { kind: "subject", description: "Runbooks grouped by subject." },
+  adrs: { kind: "subject", description: "Architecture decision records, numbered by subject." },
+};
+
+export function templatesDir() {
+  return TEMPLATES_DIR;
+}
+
+// Return a map of template name (e.g. "reports") -> { path, kind,
+// description }. Only templates that actually exist on disk are
+// returned — package.json `files` ships the templates/ dir, but a
+// broken install or an older skill version may lack a given file.
+export function listTemplates() {
+  if (!existsSync(TEMPLATES_DIR)) return {};
+  const out = {};
+  for (const entry of readdirSync(TEMPLATES_DIR)) {
+    if (!entry.endsWith(TEMPLATE_SUFFIX)) continue;
+    const name = entry.slice(0, -TEMPLATE_SUFFIX.length);
+    const abs = join(TEMPLATES_DIR, entry);
+    try {
+      if (!statSync(abs).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const meta = TEMPLATE_META[name] ?? {
+      kind: "unknown",
+      description: "",
+    };
+    out[name] = { path: abs, kind: meta.kind, description: meta.description };
+  }
+  return out;
+}
+
+export function getTemplate(name) {
+  const all = listTemplates();
+  return all[name] ?? null;
+}
+
+export function readTemplate(name) {
+  const t = getTemplate(name);
+  if (!t) return null;
+  return readFileSync(t.path, "utf8");
+}
+
+// Returns the canonical default template name for a given --kind.
+// Consumers who don't want to name a specific template can pass
+// --kind and get a sensible default (dated -> reports, subject ->
+// runbooks).
+export function defaultTemplateForKind(kind) {
+  if (kind === "dated") return "reports";
+  if (kind === "subject") return "runbooks";
+  return null;
+}

package/scripts/lib/tiered.mjs

@@ -10,7 +10,7 @@
 // circuits the whole ladder.
 //
 // Three quality modes, selected via --quality-mode or the
-// LLM_WIKI_QUALITY_MODE env var:
+// LLM_WIKI_QUALITY_MODE env var (see resolveQualityMode):
 //
 //   tiered-fast (default):
 //     Tier 0 → Tier 1 → Tier 2, the full ladder. Mid-band Tier 0
@@ -21,9 +21,16 @@
 //     obvious decisions) but anything in the Tier 0 mid-band goes
 //     straight to Tier 2, skipping Tier 1.
 //
-//   tier0-only:
-//     Tier 0 decisions only. Mid-band becomes an explicit
-//     "undecidable" marker that the caller must resolve manually.
+//   deterministic:
+//     Tier 0 + Tier 1 ladder, but the ladder terminates at Tier 1:
+//     mid-band Tier 0 escalates to Tier 1 (as in tiered-fast), but
+//     mid-band Tier 1 is resolved by a deterministic threshold
+//     (`TIER1_DETERMINISTIC_THRESHOLD`) instead of escalating to
+//     Tier 2. No LLM/sub-agent is ever consulted — every decision
+//     is produced from TF-IDF + MiniLM cosine alone, so repeated
+//     runs on the same inputs are byte-reproducible. This is the
+//     mode the clustering pipeline pairs with algorithmic HAC +
+//     auto-slug to produce deterministic wiki builds end-to-end.
 //
 // Tier 2 escalation contract: the skill's CLI runs under Node with
 // no access to Claude Code's `Agent` tool, so it cannot spawn
@@ -64,11 +71,27 @@ import {
 export const QUALITY_MODES = Object.freeze([
   "tiered-fast",
   "claude-first",
-  "tier0-only",
+  "deterministic",
 ]);
 
 export const DEFAULT_QUALITY_MODE = "tiered-fast";
 
+// Deterministic-mode split point for resolving mid-band Tier 1
+// similarities. Derived as the midpoint of the Tier 1 mid-band so
+// future tuning of the decisive-same / decisive-different thresholds
+// propagates here without a separate code-change — no drift between
+// "where the ladder says 'escalate'" and "where deterministic mode
+// says 'same vs different'". Any pair whose Tier 1 cosine sits
+// strictly above this is routed to "same"; anything at-or-below is
+// routed to "different". In this mode there is no mid-band
+// "undecidable" / pending-Tier-2 outcome — Tier 1 always produces a
+// concrete branch without an LLM in the loop. (Note: Tier 0 can still
+// produce an "undecidable" result on insufficient-text inputs — two
+// empty frontmatters — independent of quality mode; that predates
+// deterministic mode and is by design.)
+export const TIER1_DETERMINISTIC_THRESHOLD =
+  (TIER1_DECISIVE_SAME + TIER1_DECISIVE_DIFFERENT) / 2;
+
 export function resolveQualityMode(flags = {}) {
   const fromFlag = flags.quality_mode;
   const fromEnv = process.env.LLM_WIKI_QUALITY_MODE;
@@ -244,18 +267,6 @@ export async function decide(
   }
 
   // Mid-band Tier 0 → escalate. Behaviour depends on quality mode.
-  if (qualityMode === "tier0-only") {
-    const result = {
-      tier: 0,
-      similarity: t0.similarity,
-      decision: "undecidable",
-      confidence_band: t0.confidence_band,
-      reason: "tier0-only quality mode — mid-band left unresolved",
-    };
-    finaliseDecision(result, { a, b, hashA, hashB, wikiRoot, opId, operator, writeLog, writeCache });
-    return result;
-  }
-
   if (qualityMode === "claude-first") {
     // Skip Tier 1 entirely, go straight to Tier 2.
     return await escalateToTier2(
@@ -308,7 +319,20 @@ export async function decide(
     finaliseDecision(result, { a, b, hashA, hashB, wikiRoot, opId, operator, writeLog, writeCache });
     return result;
   }
-  // Mid-band Tier 1 → Tier 2.
+  // Mid-band Tier 1. Branch on quality mode: deterministic resolves
+  // algorithmically, tiered-fast escalates to Tier 2.
+  if (qualityMode === "deterministic") {
+    const decision = sim > TIER1_DETERMINISTIC_THRESHOLD ? "same" : "different";
+    const result = {
+      tier: 1,
+      similarity: sim,
+      decision,
+      confidence_band: "deterministic-mid-band",
+      reason: `deterministic mode: sim ${sim.toFixed(3)} ${decision === "same" ? ">" : "≤"} ${TIER1_DETERMINISTIC_THRESHOLD}`,
+    };
+    finaliseDecision(result, { a, b, hashA, hashB, wikiRoot, opId, operator, writeLog, writeCache });
+    return result;
+  }
   return await escalateToTier2(
     a, b, hashA, hashB, wikiRoot, opId, operator,
     sim, "tier1 mid-band", writeLog, writeCache,

package/scripts/lib/validate.mjs

@@ -133,6 +133,28 @@ export function validateWiki(wikiRoot) {
         }
       }
     }
+
+    // LEAF-AT-WIKI-ROOT — the wiki root must hold only `index.md`
+    // plus subdirectories. Any `.md` file at the wiki root other
+    // than `index.md` itself violates the invariant, regardless of
+    // what its frontmatter `type:` claims. Keying off path rather
+    // than `data.type` catches the edge case of a hand-authored
+    // `foo.md` at root declared as `type: index` — it's still a
+    // loose root file the navigational model forbids. The rule is
+    // navigational: Claude reading `<root>/index.md` and following
+    // its `entries[]` should reach every leaf via a
+    // semantically-named category; loose root files bypass that
+    // mental model and bloat the top-level index.
+    const absDir = dirname(e.absolute);
+    const absName = basename(e.absolute);
+    if (absDir === wikiRoot && absName !== "index.md") {
+      push(
+        "error",
+        "LEAF-AT-WIKI-ROOT",
+        e.absolute,
+        `non-index markdown file at wiki root — must live in a subcategory (run 'fix' to contain)`,
+      );
+    }
   }
 
   return findings;

package/scripts/lib/where.mjs

@@ -0,0 +1,71 @@
+// where.mjs — canonical "where am I installed?" report.
+//
+// Consumers need a reliable way to resolve the skill's install path
+// without hard-coding `~/.claude/skills/...` or duplicating the
+// @ctxr/kit path list. `skill-llm-wiki where` answers:
+//   - where is the skill root?
+//   - where is SKILL.md?
+//   - where is the templates/ directory?
+//   - where is the scripts/testkit/ directory?
+//   - what are the current package and format versions?
+//
+// Safe to invoke before the runtime-dep preflight resolves; uses
+// only node:fs + node:path + node:url. No gray-matter, no transformers.
+
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { FORMAT_VERSION } from "./contract.mjs";
+
+// `where.mjs` lives at <SKILL_ROOT>/scripts/lib/where.mjs. The skill
+// root is two directories up. Exported so other lib / testkit
+// modules that need the skill root import this single source of
+// truth (contract.mjs, templates.mjs, cli-run.mjs).
+export const SKILL_ROOT = dirname(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+);
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(SKILL_ROOT, "package.json"), "utf8"),
+    );
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function pathIfExists(p) {
+  return existsSync(p) ? p : null;
+}
+
+export function getWhere() {
+  return {
+    schema: "skill-llm-wiki/where/v1",
+    skill_root: SKILL_ROOT,
+    skill_md: join(SKILL_ROOT, "SKILL.md"),
+    cli: join(SKILL_ROOT, "scripts", "cli.mjs"),
+    guide_dir: join(SKILL_ROOT, "guide"),
+    templates_dir: pathIfExists(join(SKILL_ROOT, "templates")),
+    testkit_dir: pathIfExists(join(SKILL_ROOT, "scripts", "testkit")),
+    package_version: readPackageVersion(),
+    format_version: FORMAT_VERSION,
+  };
+}
+
+// Human-readable summary. Absolute paths, one per line, aligned so
+// operators can eyeball things without parsing JSON.
+export function renderWhereText(info) {
+  const lines = [
+    `skill_root:       ${info.skill_root}`,
+    `skill_md:         ${info.skill_md}`,
+    `cli:              ${info.cli}`,
+    `guide_dir:        ${info.guide_dir}`,
+    `templates_dir:    ${info.templates_dir ?? "<not shipped>"}`,
+    `testkit_dir:      ${info.testkit_dir ?? "<not shipped>"}`,
+    `package_version:  ${info.package_version}`,
+    `format_version:   ${info.format_version}`,
+  ];
+  return lines.join("\n") + "\n";
+}

package/scripts/testkit/assert-frontmatter.mjs

@@ -0,0 +1,171 @@
+// assert-frontmatter.mjs — testkit helper: read a leaf, parse its
+// frontmatter block, assert expected fields match.
+//
+// Deliberately lightweight: does not import gray-matter. The
+// opening `---` fence, body, and closing `---` fence pattern the
+// skill emits is stable enough that a ~10-line parser is the right
+// shape for a testkit. Tolerates both LF and CRLF line endings so
+// consumer tests running on Windows runners don't see spurious
+// parse failures.
+//
+// Zero runtime deps; pure Node built-ins.
+
+import { readFileSync } from "node:fs";
+
+// Both fences match CRLF and LF: git on Windows checks repos out
+// with native line endings by default. Capture group on FM_START is
+// the length of the consumed fence so the caller can slice past it.
+const FM_START = /^---(\r?\n)/;
+const FM_END = /\r?\n---(\r?\n|$)/;
+
+// Parse a leaf's frontmatter block into a flat key: string-ish
+// object. Only the shallow YAML shape the skill emits is
+// supported. For full YAML-as-data consumers should use gray-matter
+// in their own test code; this helper is for sanity checks.
+export function readLeafFrontmatter(absLeafPath) {
+  const raw = readFileSync(absLeafPath, "utf8");
+  const startMatch = FM_START.exec(raw);
+  if (!startMatch) {
+    throw new Error(
+      `readLeafFrontmatter: ${absLeafPath} has no frontmatter block`,
+    );
+  }
+  const afterFirst = raw.slice(startMatch[0].length);
+  const endMatch = FM_END.exec(afterFirst);
+  if (!endMatch) {
+    throw new Error(
+      `readLeafFrontmatter: ${absLeafPath} has an unterminated frontmatter block`,
+    );
+  }
+  const block = afterFirst.slice(0, endMatch.index);
+  const data = {};
+  // A "pending key" is a top-level key with an empty RHS whose
+  // type isn't yet decided. The first indented continuation line
+  // picks: `- x` → list, `subkey: v` → map. Once decided, further
+  // continuations at the same indent extend the same container.
+  let pendingKey = null;
+  let pendingIndent = -1;
+  let pendingKind = null; // null | "list" | "map"
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    const trimmed = line.trimStart();
+
+    // Continuation: line is indented past the open key.
+    if (pendingKey !== null && indent > pendingIndent) {
+      const listMatch = /^-\s*(.*)$/.exec(trimmed);
+      if (listMatch && (pendingKind === null || pendingKind === "list")) {
+        if (pendingKind === null) {
+          data[pendingKey] = [];
+          pendingKind = "list";
+        }
+        data[pendingKey].push(unquote(listMatch[1].trim()));
+        continue;
+      }
+      const nestedKv = /^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i.exec(trimmed);
+      if (nestedKv && (pendingKind === null || pendingKind === "map")) {
+        if (pendingKind === null) {
+          data[pendingKey] = {};
+          pendingKind = "map";
+        }
+        data[pendingKey][nestedKv[1]] = unquote(nestedKv[2].trim());
+        continue;
+      }
+      // Fall through: unknown continuation shape, ignore.
+      continue;
+    }
+
+    // New top-level key ends any open container.
+    const kv = /^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i.exec(line);
+    if (!kv) continue;
+    pendingKey = null;
+    pendingIndent = -1;
+    pendingKind = null;
+    const key = kv[1];
+    const val = kv[2].trim();
+    if (val === "") {
+      // Empty RHS: open a pending key; the first continuation
+      // picks list vs map. Default to an empty object until
+      // decided — consumers that assert a key exists without
+      // inspecting its type still pass.
+      data[key] = {};
+      pendingKey = key;
+      pendingIndent = indent;
+      pendingKind = null;
+    } else if (val === "[]") {
+      data[key] = [];
+    } else if (val.startsWith("[") && val.endsWith("]")) {
+      data[key] = val
+        .slice(1, -1)
+        .split(",")
+        .map((s) => unquote(s.trim()))
+        .filter(Boolean);
+    } else {
+      data[key] = unquote(val);
+    }
+  }
+  return data;
+}
+
+function unquote(s) {
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// Compare actual frontmatter to an expected subset. Only fields
+// named in `expected` are checked; extra fields in the leaf are
+// allowed. Arrays compare element-wise as strings; objects compare
+// each expected key shallowly (string-equality) so consumers can
+// write `{ source: { origin: "file", path: "foo.md" } }` against
+// the skill's canonical frontmatter shape.
+//
+// Throws an Error when any mismatch is found. Returns the parsed
+// frontmatter object on success.
+export function assertFrontmatterShape(absLeafPath, expected) {
+  const data = readLeafFrontmatter(absLeafPath);
+  const mismatches = [];
+  for (const [key, want] of Object.entries(expected ?? {})) {
+    const got = data[key];
+    if (Array.isArray(want)) {
+      if (!Array.isArray(got)) {
+        mismatches.push(`${key}: expected array, got ${JSON.stringify(got)}`);
+        continue;
+      }
+      if (got.length !== want.length || got.some((v, i) => String(v) !== String(want[i]))) {
+        mismatches.push(
+          `${key}: expected [${want.join(", ")}], got [${got.join(", ")}]`,
+        );
+      }
+      continue;
+    }
+    if (want !== null && typeof want === "object") {
+      if (got === null || typeof got !== "object" || Array.isArray(got)) {
+        mismatches.push(`${key}: expected object, got ${JSON.stringify(got)}`);
+        continue;
+      }
+      for (const [subKey, subWant] of Object.entries(want)) {
+        if (String(got[subKey]) !== String(subWant)) {
+          mismatches.push(
+            `${key}.${subKey}: expected ${JSON.stringify(subWant)}, got ${JSON.stringify(got[subKey])}`,
+          );
+        }
+      }
+      continue;
+    }
+    if (String(got) !== String(want)) {
+      mismatches.push(`${key}: expected ${JSON.stringify(want)}, got ${JSON.stringify(got)}`);
+    }
+  }
+  if (mismatches.length > 0) {
+    throw new Error(
+      `assertFrontmatterShape failed for ${absLeafPath}:\n  - ` +
+        mismatches.join("\n  - "),
+    );
+  }
+  return data;
+}

package/scripts/testkit/cli-run.mjs

@@ -0,0 +1,95 @@
+// cli-run.mjs — testkit helper: spawn the skill CLI as a child
+// process, capture stdout/stderr/exitCode, optionally parse the
+// --json envelope. Consumers use this in their test suites to drive
+// the skill without re-implementing the spawn ceremony.
+//
+// Zero runtime deps; pure Node built-ins.
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { SKILL_ROOT } from "../lib/where.mjs";
+import { hasJsonFlag } from "../lib/json-envelope.mjs";
+
+export const CLI_PATH = join(SKILL_ROOT, "scripts", "cli.mjs");
+
+// Run the skill CLI with `args`. Returns an object of:
+//   { status, stdout, stderr, envelope, error }
+//
+// `envelope` is only populated when `args` includes `--json` or
+// `--json-errors` AND the stdout parses as JSON. On parse failure it
+// is `null` and the caller can inspect `stdout` directly.
+//
+// `error` is populated when the child process could not be spawned
+// at all (ENOENT, EACCES, EPERM). When it is set, `status` will be
+// `null` (spawnSync's convention) and the `error` field carries the
+// Node errno. Consumers writing cross-platform tests need to see
+// this to distinguish "CLI ran and exited with status X" from "CLI
+// never ran".
+//
+// Note on environment: when `env` is supplied, the testkit forwards
+// the parent process environment too (object-spread with the
+// override). This is intentional for local test convenience; CI
+// harnesses writing untrusted fixtures should scrub `process.env`
+// before calling.
+export function runCli(args, { cwd, env } = {}) {
+  const resolvedArgs = Array.isArray(args) ? args : [];
+  const r = spawnSync(process.execPath, [CLI_PATH, ...resolvedArgs], {
+    encoding: "utf8",
+    cwd: cwd ?? process.cwd(),
+    env: env ? { ...process.env, ...env } : process.env,
+  });
+  const wantJson = hasJsonFlag(resolvedArgs);
+  let envelope = null;
+  if (wantJson && r.stdout) {
+    // Two output shapes exist. Envelope subcommands (validate, init,
+    // heal) emit a single-line JSON object. contract/where emit
+    // pretty-printed JSON spanning multiple lines. Try parsing the
+    // full stdout first; if that fails, fall back to the last
+    // JSON-like line (handles envelope output that may be preceded
+    // by progress lines).
+    const full = r.stdout.trim();
+    try {
+      envelope = JSON.parse(full);
+    } catch {
+      const lines = full.split("\n");
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith("{")) continue;
+        try {
+          envelope = JSON.parse(line);
+          break;
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  return {
+    status: r.status,
+    stdout: r.stdout,
+    stderr: r.stderr,
+    envelope,
+    error: r.error ?? null,
+  };
+}
+
+// Convenience: assert a clean run, throw on non-zero exit with the
+// stderr attached so the consumer's test output is useful. When the
+// child failed to spawn at all (ENOENT/EACCES), surface that
+// explicitly rather than saying "exited null".
+export function runCliOk(args, opts) {
+  const r = runCli(args, opts);
+  const argString = Array.isArray(args) ? args.join(" ") : "";
+  if (r.error) {
+    throw new Error(
+      `runCliOk: failed to spawn skill-llm-wiki ${argString}: ` +
+        `${r.error.code ?? "unknown"} — ${r.error.message}`,
+    );
+  }
+  if (r.status !== 0) {
+    throw new Error(
+      `runCliOk: skill-llm-wiki ${argString} exited ${r.status}:\n${r.stderr}`,
+    );
+  }
+  return r;
+}