@ctxr/skill-llm-wiki 1.0.2 → 1.1.0

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;