@thanh01.pmt/domain-kit 0.6.0 → 0.6.1

package/dist/graph/index.cjs

@@ -4,7 +4,56 @@ var fs = require('fs');
 var os = require('os');
 var path = require('path');
 
+// src/utils/llmTransportResult.ts
+function transportResultFrom(provider, model, options) {
+  return {
+    provider,
+    model,
+    framingStripped: !!options?.framingStripped,
+    upstreamError: options?.upstreamError,
+    usage: options?.usage
+  };
+}
+
 // src/utils/llmClient.ts
+async function responseJsonCompat(response) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    const start = text.indexOf("{");
+    if (start < 0) {
+      throw new LlmClientError(`LLM API returned a non-JSON body: ${text.slice(0, 200)}`);
+    }
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i];
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === "{") depth++;
+      if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          return JSON.parse(text.slice(start, i + 1));
+        }
+      }
+    }
+    throw new LlmClientError(`LLM API returned an unterminated JSON body: ${text.slice(0, 200)}`);
+  }
+}
 var LlmClientError = class extends Error {
   constructor(message, status, cause) {
     super(message);
@@ -13,28 +62,22 @@ var LlmClientError = class extends Error {
     this.name = "LlmClientError";
   }
 };
-function resolveProviderChain(config) {
-  const chain = [];
-  const push = (label, baseUrl, apiKey, model) => {
-    if (apiKey && baseUrl && model && !chain.some((c) => c.baseUrl === baseUrl && c.model === model)) {
-      chain.push({ label, baseUrl, apiKey, model });
-    }
-  };
-  if (config?.apiKey) {
-    push("config", config.baseUrl || "https://api.openai.com/v1", config.apiKey, config.model || "gpt-4o-mini");
-  }
-  push("legacy", process.env.LLM_BASE_URL || process.env.OPENAI_BASE_URL || "", process.env.LLM_API_KEY || process.env.OPENAI_API_KEY || "", process.env.LLM_MODEL || process.env.LLM_TIER_FAST || "");
-  push("dashscope", process.env.DASHSCOPE_BASE_URL || process.env.ALIBABA_BASE_URL || "", process.env.DASHSCOPE_API_KEY || process.env.ALIBABA_API_KEY || "", process.env.DASHSCOPE_MODEL || process.env.DEFAULT_AI_MODEL || "");
-  push("nvidia", "https://integrate.api.nvidia.com/v1", process.env.NVIDIA_API_KEY || "", process.env.NVIDIA_MODEL || "nvidia/nemotron-3-ultra-550b-a55b:free");
-  push("openrouter", "https://openrouter.ai/api/v1", process.env.OPENROUTER_API_KEY || "", process.env.OPENROUTER_MODEL || "nvidia/nemotron-3-ultra-550b-a55b:free");
-  if (process.env.OPENROUTER_MODEL) {
-    const or = chain.find((c) => c.label === "openrouter");
-    if (or) {
-      const rest = chain.filter((c) => c !== or);
-      return [or, ...rest];
-    }
-  }
-  return chain;
+function build9routerProvider(model) {
+  const apiKey = process.env.NINEROUTER_API_KEY;
+  if (!apiKey) return null;
+  const baseUrl = (process.env.NINEROUTER_BASE_URL || "https://ai-router.orchable.app/v1").replace(/^["']|["']$/g, "").trim();
+  const label = "9router";
+  const modelName = (model || process.env.NINEROUTER_MODEL || "laguna-s-2.1").trim();
+  return { label, baseUrl, apiKey, model: modelName };
+}
+function resolve9routerChain(configModel) {
+  const primary = build9routerProvider(configModel);
+  if (!primary) return [];
+  const alt = process.env.NINEROUTER_MODEL_ALT && process.env.NINEROUTER_MODEL_ALT.trim();
+  if (!alt) return [primary];
+  const secondary = build9routerProvider(alt);
+  if (!secondary) return [primary];
+  return primary.model === secondary.model ? [primary] : [primary, secondary];
 }
 var MIN_REQUEST_INTERVAL_MS = 2500;
 var requestIntervalMs = Number(process.env.LLM_MIN_REQUEST_INTERVAL_MS || MIN_REQUEST_INTERVAL_MS);
@@ -45,11 +88,11 @@ async function pacedDelay() {
   lastRequestAt = Date.now();
 }
 function createLlmClient(config) {
-  const chain = resolveProviderChain(config);
+  const chain = resolve9routerChain(config?.model);
   const primary = chain[0];
   if (!primary) {
     throw new LlmClientError(
-      "No LLM provider configured. Set NVIDIA_API_KEY (primary) and/or OPENROUTER_API_KEY (fallback), or pass llmConfig."
+      "No 9router provider configured. Set NINEROUTER_API_KEY and NINEROUTER_MODEL (or the NINEROUTER_* env defaults expected by the kit)."
     );
   }
   primary.apiKey;
@@ -131,17 +174,22 @@ function createLlmClient(config) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
               });
               if (!retry.ok) throw err;
-              const retryData = await retry.json();
+              const retryData = await responseJsonCompat(retry);
               const retryContent2 = retryData.choices?.[0]?.message?.content || "";
               if (!retryContent2.trim()) throw err;
               callLog[recIdx] = { ...callLog[recIdx], ok: true };
+              const transport2 = transportResultFrom(provider.label, retryData.model || provider.model, {
+                usage: retryData.usage,
+                framingStripped: true
+              });
               return {
                 content: retryContent2,
                 model: retryData.model || provider.model,
                 provider: provider.label,
                 attempts: attempts.slice(),
                 usage: retryData.usage,
-                finishReason: retryData.choices?.[0]?.finish_reason
+                finishReason: retryData.choices?.[0]?.finish_reason,
+                _transport: transport2
               };
             }
             if (TRANSIENT.has(response.status)) {
@@ -161,21 +209,26 @@ function createLlmClient(config) {
                 })
               });
               if (!retry.ok) throw err;
-              const retryData = await retry.json();
+              const retryData = await responseJsonCompat(retry);
               const retryContent = retryData.choices?.[0]?.message?.content || "";
               callLog[recIdx] = { ...callLog[recIdx], ok: true };
+              const transport2 = transportResultFrom(provider.label, retryData.model || provider.model, {
+                usage: retryData.usage,
+                framingStripped: true
+              });
               return {
                 content: retryContent,
                 model: retryData.model || provider.model,
                 provider: provider.label,
                 attempts: attempts.slice(),
                 usage: retryData.usage,
-                finishReason: retryData.choices?.[0]?.finish_reason
+                finishReason: retryData.choices?.[0]?.finish_reason,
+                _transport: transport2
               };
             }
             throw err;
           }
-          const data = await response.json();
+          const data = await responseJsonCompat(response);
           const wrappedError = data.error;
           if (wrappedError) {
             throw new LlmClientError("[" + provider.label + "] upstream error " + (wrappedError.code ?? "") + ": " + (wrappedError.message ?? "unknown"));
@@ -184,13 +237,18 @@ function createLlmClient(config) {
           if (!content.trim()) {
             throw new LlmClientError("[" + provider.label + "] empty completion returned");
           }
+          const transport = transportResultFrom(provider.label, data.model || provider.model, {
+            usage: data.usage,
+            framingStripped: true
+          });
           return {
             content,
             model: data.model || provider.model,
             provider: provider.label,
             attempts: attempts.slice(),
             usage: data.usage,
-            finishReason: data.choices?.[0]?.finish_reason
+            finishReason: data.choices?.[0]?.finish_reason,
+            _transport: transport
           };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -364,7 +422,7 @@ async function extractProjectOverview(options) {
       (kw) => `- ${kw.keyword} (from ${kw.source})`
     );
     if (kwItems.length > 0) {
-      keywordsAnchor = "\nAST Domain Keywords & Patterns (from static analysis \u2014 use as context anchor):\n" + kwItems.join("\n") + "\n";
+      keywordsAnchor = "\nDomain Keywords & Patterns (from regex-based static scan \u2014 use as context anchor):\n" + kwItems.join("\n") + "\n";
     }
   }
   const systemPrompt = "You are a software architect. The app the user will build IS EXACTLY the provided files (not an SDK/lib). Analyze them and return a PROJECT OVERVIEW \u2014 meta only, DO NOT list steps (steps are handled in a later step). NEVER invent files/APIs. NEVER reference internal SDK/lib unless it appears in the given files.\nEND-USER VIEW (M1/Design Thinking): product.purpose must describe the USER PROBLEM (what the user does with the app, which need it solves). NEVER describe repo/artifacts.\nDEVELOPMENT STAGES: Include 4-6 development stages in product.development_stages. Each stage must have: stage (name), need (list of feature needs), learn (concepts learned), product_state (what works), temporary_approach, and validation.\nMISSING GAPS: Identify 0-5 missing_gaps (features/functionality that should exist but don't).\nTECH DEBT: Identify 0-5 tech_debt issues (code quality problems).\nALL text must be in ENGLISH.";
@@ -1380,7 +1438,110 @@ function techSignalHits(text) {
   }
   return hits;
 }
-function auditDepthLayers(concepts) {
+var COMPLETABLE_VERBS = [
+  "build",
+  "create",
+  "implement",
+  "write",
+  "configure",
+  "add",
+  "use",
+  "apply",
+  "display",
+  "store",
+  "load",
+  "save",
+  "handle",
+  "parse",
+  "validate",
+  "test",
+  "register",
+  "compute",
+  "generate",
+  "print",
+  "format",
+  "convert",
+  "extend",
+  "define",
+  "execute",
+  "run",
+  "read",
+  "fetch",
+  "wrap",
+  "log",
+  "call",
+  "raise",
+  "install",
+  "import",
+  "export",
+  "declare",
+  "embed",
+  "model",
+  "represent",
+  "override",
+  "customize",
+  "enforce",
+  "mock",
+  "assert",
+  "query",
+  "index",
+  "cache",
+  "stream",
+  "split",
+  "join",
+  "strip",
+  "encode",
+  "decode",
+  "traverse",
+  "measure",
+  "evaluate",
+  "benchmark",
+  "diagnose",
+  "demonstrate",
+  "verify",
+  "organize",
+  "structure",
+  "choose",
+  "select",
+  "compare",
+  "distinguish",
+  "attach",
+  "annotate",
+  "expose",
+  "accept",
+  "manage",
+  "group",
+  "sort",
+  "filter",
+  "map",
+  "reduce",
+  "catch",
+  "throw",
+  "migrate",
+  "inspect",
+  "trace",
+  "parameterize",
+  "construct",
+  "design",
+  "capture",
+  // Completable implementation verbs present in production SIO output but
+  // missing from the original registry (2026-10-07 smoke test, swift kg):
+  "update",
+  "inject",
+  "compose",
+  "pass",
+  "modify",
+  "connect",
+  "remove",
+  "transform",
+  "trigger",
+  "refresh",
+  "persist",
+  "observe",
+  "arrange",
+  "derive"
+];
+function auditDepthLayers(concepts, transport) {
   return concepts.map((c) => {
     const ulo = (c.ulo ?? "").trim();
     const cio = (c.cio ?? "").trim();
@@ -1401,7 +1562,7 @@ function auditDepthLayers(concepts) {
     });
     const conceptKeywords = (c.keywords ?? []).map((k) => k.toLowerCase()).filter(Boolean);
     const sioOffConceptItems = conceptKeywords.length > 0 ? sioItems.filter((s) => !boundToConcept(s)) : [];
-    const COMPLETABLE = /\b(build|create|implement|write|configure|add|use|apply|display|store|load|save|handle|parse|validate|test|register|compute|generate|print|format|convert|extend|define|execute|run|read|fetch|wrap|log|call|raise|install|import|export|declare|embed|model|represent|override|customize|enforce|mock|assert|query|index|cache|stream|split|join|strip|encode|decode|traverse|measure|evaluate|benchmark|diagnose|demonstrate|verify|organize|structure|choose|select|compare|distinguish|attach|annotate|expose|accept|manage|group|sort|filter|map|reduce|catch|throw|migrate|inspect|trace|parameterize|construct|design|capture)\b/i;
+    const COMPLETABLE = new RegExp("\\b(?:" + COMPLETABLE_VERBS.join("|") + ")\\b", "i");
     const sioNotCompletable = sioItems.filter((s) => !COMPLETABLE.test(s) && !/`[^`]+`/.test(s));
     const density = (text) => {
       if (!text) return 0;
@@ -1441,7 +1602,8 @@ function auditDepthLayers(concepts) {
       clauseOk,
       codesOk,
       codeIssues,
-      passed
+      passed,
+      transport
     };
   });
 }
@@ -1451,14 +1613,14 @@ function excerpt(text, max) {
   const t = (text || "").trim();
   return t.length > max ? t.slice(0, max) + "..." : t;
 }
-async function chatJson(client, system, user) {
+async function chatJson(client, system, user, transport) {
   const r = await client.chat(
     [{ role: "system", content: system }, { role: "user", content: user }],
     { temperature: 0.1, maxTokens: parseInt(process.env.KG_MAX_TOKENS || "65536", 10) }
   );
   return parseJsonFromLlm(r.content);
 }
-var LO_BATCH_SIZE = 6;
+var LO_BATCH_SIZE = 10;
 function chunkConcepts(items, size) {
   const out = [];
   for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
@@ -1497,7 +1659,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
   for (const batch of chunkConcepts(concepts, LO_BATCH_SIZE)) {
     const batchList = batch.map((c) => "- " + c.id + " (" + c.name + ")" + (c.description ? ": " + excerpt(c.description, 160) : "")).join("\n");
     const batchUser = "Concepts:\n" + batchList + '\n\nReturn JSON:\n{"ulos":[{"concept_id":"C1","ulo":"..."}]}';
-    const uloRes = await chatJson(client, uloSystem, batchUser);
+    const uloRes = await chatJson(client, uloSystem, batchUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const u of uloRes.ulos ?? []) {
       if (u.concept_id && u.ulo) uloByConcept[u.concept_id] = standardStatement(u.ulo);
     }
@@ -1536,7 +1698,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
     new Set(batch.map((c) => c.id));
     const batchUloContext = batch.map((c) => "- " + c.id + " (" + c.name + "): " + (uloByConcept[c.id] || "(missing)")).join("\n");
     const batchCioUser = "Approved ULOs:\n" + batchUloContext + '\n\nReturn JSON:\n{"cios":[{"concept_id":"C1","cio":"..."}]}';
-    const cioRes = await chatJson(client, cioSystem, batchCioUser);
+    const cioRes = await chatJson(client, cioSystem, batchCioUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const x of cioRes.cios ?? []) {
       if (x.concept_id && x.cio) cioByConcept[x.concept_id] = standardStatement(x.cio);
     }
@@ -1561,15 +1723,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
     "   context where it is used. Application/Analysis/Creation skills are assessed",
     "   INDIRECTLY through completing these tasks \u2014 there is no fixed Bloom ceiling.",
     "   MACHINE CHECK: every item MUST contain at least one ACTION VERB from this whitelist",
-    "   (build, create, implement, write, configure, add, use, apply, display, store, load,",
-    "   save, handle, parse, validate, test, register, compute, generate, print, format,",
-    "   convert, extend, define, execute, run, read, fetch, wrap, log, call, raise, install,",
-    "   import, export, declare, embed, model, represent, override, customize, enforce, mock,",
-    "   assert, query, index, cache, stream, split, join, strip, encode, decode, traverse,",
-    "   measure, evaluate, benchmark, diagnose, demonstrate, verify, organize, structure,",
-    "   choose, select, compare, distinguish, attach, annotate, expose, accept, manage, group,",
-    "   sort, filter, map, reduce, catch, throw, migrate, inspect, trace, parameterize,",
-    "   construct, design, capture) \u2014 OR wrap the concrete construct in backticks.",
+    "   (" + COMPLETABLE_VERBS.join(", ") + ") \u2014 OR wrap the concrete construct in backticks.",
     "   Items with abstract verbs (understand, learn, know, grasp, appreciate, explore) and",
     "   no backtick construct FAIL the audit. Prefer starting the task phrase with the verb.",
     "3. 2-3 items per concept, each referencing a DIFFERENT concrete construct.",
@@ -1597,7 +1751,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
       "Return JSON:",
       '{"sios":[{"concept_id":"C1","sio":["...","..."]}]}'
     ].join("\n");
-    const sioRes = await chatJson(client, sioSystem, batchSioUser);
+    const sioRes = await chatJson(client, sioSystem, batchSioUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const x of sioRes.sios ?? []) {
       if (x.concept_id && Array.isArray(x.sio)) sioByConcept[x.concept_id] = x.sio.map((item) => standardStatement(String(item)));
     }
@@ -1650,7 +1804,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
         "- CIO: HOW mechanism, technology-agnostic, more concrete than ULO, Marr 2-Language neutral.",
         "- SIO: keyword-bound completable implementation tasks naming real constructs of " + techStack + ".",
         "- BINDING RULE: every SIO item must contain at least one of the concept's listed keywords VERBATIM (copy the exact keyword text into the sentence).",
-        "- COMPLETABILITY RULE: every SIO item must contain an actionable verb (build, create, implement, write, configure, parse, validate, handle, store, load, run, read, fetch, display, generate, format, convert, test, debug, trace, measure, design, structure, select, filter, sort, map, reduce, catch, throw, migrate, deploy, query, index, cache, stream, inspect) or wrap a concrete construct in backticks \u2014 abstract verbs (understand, learn, know, grasp, explore, appreciate) always fail.",
+        "- COMPLETABILITY RULE: every SIO item must contain an actionable verb (" + ["build", "create", "update", "inject", "compose", "pass", "modify", "use"].join(", ") + " ...full registry in the SIO authoring step) or wrap a concrete construct in backticks \u2014 abstract verbs (understand, learn, know, grasp, explore, appreciate) always fail.",
         "",
         JSON_ONLY
       ].join("\n");
@@ -1698,7 +1852,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
       "Depth-layer contract audit failed after repair for: " + detail + " \u2014 regenerate or fix the prompt contract (fail-closed, no silent fallback)"
     );
   }
-  return { uloByConcept, cioByConcept, sioByConcept, audits, warnings };
+  return { uloByConcept, cioByConcept, sioByConcept, audits, warnings, lastTransport: audits[0]?.transport };
 }
 function cell(v) {
   return (v || "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -1841,7 +1995,7 @@ async function standardizeConcepts(opts) {
     "     Adopt the tree's terminology. Only propose new when the tree genuinely has NO concept teaching that knowledge (broader AND narrower both fail).",
     '  2. "proposed_new" - no tree concept covers it at the same granularity. Propose an UPPER_SNAKE_CASE code (descriptive, stable, max 5 words) and a one-sentence definition.',
     "     If between 1 and 3 tree concepts are CLOSE but not exact, list their codes in possible_tree_matches for human review.",
-    `For a "standardized" decision ALSO return "adopted_keywords": the subset of that tree concept's keywords (from the shortlist) that make sense for the course TECH STACK. Drop keywords that name tooling from other ecosystems (e.g. JS test runners for a Python course) \u2014 keep conceptual keywords even when spelled generically. Maximum 8, ordered most-relevant first.`,
+    `For a "standardized" decision ALSO return "adopted_keywords": copy VERBATIM from that tree concept's keyword list in the shortlist (exact tokens, do not re-spell, singularize or translate). Pick the subset that makes sense for the course TECH STACK; if none fit, return an EMPTY array \u2014 never invent a keyword. Maximum 8, ordered most-relevant first.`,
     "Rules:",
     "- Judge by MEANING (definition + keywords), not by string similarity.",
     '- COVERAGE RULE: a "standardized" match must cover ALL primary dimensions of the input concept \u2014 every distinct aspect named in its title or description. A tree concept covering only ONE of several aspects (e.g. "interpreting error messages" for a concept about error handling AND user experience) is a PARTIAL match: decide "proposed_new" and list that tree code in possible_tree_matches.',
@@ -1881,10 +2035,25 @@ async function standardizeConcepts(opts) {
       const tc = catalog.concepts.find((x) => x.code === d.tree_code);
       if (!tc) throw new Error("Concept " + c.id + " standardized to unknown tree code " + d.tree_code + " \u2014 fail-closed");
       const treeKw = new Set(tc.keywords.map((k) => k.toLowerCase()));
-      const adopted = (d.adopted_keywords || []).map((k) => String(k)).filter((k) => {
-        if (treeKw.has(k.toLowerCase())) return true;
-        throw new Error("Concept " + c.id + ' adopted keyword "' + k + '" not in tree concept ' + tc.code + " \u2014 fail-closed");
-      });
+      const rawAdopted = (d.adopted_keywords || []).map((k) => String(k)).filter(Boolean);
+      let adopted;
+      if (tc.keywords.length === 0) {
+        adopted = rawAdopted.filter((k) => (c.keywords ?? []).some((ck) => ck.toLowerCase() === k.toLowerCase()));
+        if (adopted.length === 0) adopted = (c.keywords ?? []).slice(0, 8);
+        warnings.push("Concept " + c.id + ": tree concept " + tc.code + " has no keyword registry \u2014 adopted " + adopted.length + " keyword(s) from the analysis concept");
+      } else {
+        const norm = (k) => k.toLowerCase().replace(/ies$/, "y").replace(/s$/, "");
+        const treeKwNorm = new Set([...treeKw].map(norm));
+        const dropped = [];
+        adopted = rawAdopted.filter((k) => {
+          if (treeKw.has(k.toLowerCase()) || treeKwNorm.has(norm(k))) return true;
+          dropped.push(k);
+          return false;
+        });
+        if (dropped.length > 0) {
+          warnings.push("Concept " + c.id + ": dropped " + dropped.length + " adopted keyword(s) not in tree concept " + tc.code + " registry: " + dropped.join(", "));
+        }
+      }
       if (tc.keywords.length > 0 && adopted.length === 0) {
         throw new Error("Concept " + c.id + " standardized to " + tc.code + " without adopted_keywords \u2014 fail-closed");
       }
@@ -1979,7 +2148,7 @@ async function generateKnowledgeGraph(options) {
     log("STEP_1", `Parsed syllabus: ${parsedSyllabus.units.length} units, ${parsedSyllabus.allTopics.length} topics`);
   }
   const client = createLlmClient(llmConfig);
-  const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "16000", 10);
+  const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "32000", 10);
   let truncatedSyllabus = "";
   if (syllabusText) {
     if (syllabusText.length > maxSyllabusChars) {
@@ -2169,23 +2338,32 @@ Return JSON:
       }
     }
     const idByTreeCode = new Map(concepts.filter((c) => c.tree_code).map((c) => [c.tree_code, c.id]));
+    const unmappedTreePrereqs = /* @__PURE__ */ new Set();
     for (const c of concepts) {
       for (const tp of c.tree_prerequisites || []) {
         const target = idByTreeCode.get(tp);
         if (target && target !== c.id && !(c.prerequisites || []).includes(target)) {
           c.prerequisites = [...c.prerequisites || [], target];
           warnings.push("Prereq seeded from tree: " + c.id + " <- " + tp + " (" + target + ")");
+        } else if (!target) {
+          unmappedTreePrereqs.add(tp);
         }
       }
     }
+    if (unmappedTreePrereqs.size > 0) {
+      const shown = [...unmappedTreePrereqs].slice(0, 10).join(", ");
+      warnings.push("Tree prereqs outside THIS analysis (no edge seeded, " + unmappedTreePrereqs.size + " codes): " + shown + (unmappedTreePrereqs.size > 10 ? ", ..." : ""));
+    }
     log("STEP_2_5", "Standardized: " + std.decisions.filter((d) => d.decision === "standardized").length + ", proposed new: " + std.decisions.filter((d) => d.decision === "proposed_new").length);
+  } else {
+    warnings.push("No knowledgeTreePath provided \u2014 concepts are NOT standardized against the knowledge tree (all proposed_new)");
   }
   log("STEP_3", "Checking for prerequisite cycles...");
   const cycles = detectPrerequisiteCycles(concepts);
   if (cycles.length > 0) {
     log("STEP_3", `Found ${cycles.length} cycle(s) in prerequisite chain \u2014 breaking cycles`);
     for (const cycle of cycles) {
-      warnings.push(`Cycle detected: ${cycle.join(" \u2192 ")} \u2014 breaking at weakest edge`);
+      warnings.push(`Cycle detected: ${cycle.join(" \u2192 ")} \u2014 removing the closing back-edge (last DFS edge; pedagogically arbitrary)`);
     }
     const { fixed, removed } = breakPrerequisiteCycles(concepts, cycles);
     for (let i = 0; i < concepts.length; i++) {